V3

Standardize inbound contributions under the @imqueue dual-license model (GPL-3.0 + commercial): CONTRIBUTING.md, CONTRIBUTION-TERMS.md (v1.0), and .github/PULL_REQUEST_TEMPLATE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Require contributors to sign the @imqueue Contribution Terms on each PR. Signatures stored per-repo (signatures/version1/cla.json) via GITHUB_TOKEN; no external app or PAT required.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

enrich logging

single pub sub lock fix

Calls the shared workflow in imqueue/.github. Notes come from a CHANGELOG.md
section when present, otherwise GitHub's PR-derived notes, always followed by a
standard About + links block so the release page is a self-contained, indexable
description of the package even when the generated change list is empty.

Triggered by the existing `npm version` + `git push --follow-tags` flow, so the
release habit does not change. workflow_dispatch backfills an existing tag and
defaults to a dry run.

Calls the shared check in imqueue/.github. Generated release notes are built from PR
titles and bodies, so a blank template or a title like "V3" silently becomes the
changelog for a release. `edited` is in the trigger list so fixing the description
clears the failure without pushing a commit.

This reports status but does not block merging until it is added as a required status
check in branch protection.

Generated API reference for this package is about to be published on
imqueue.org. 23 symbols carried no doc comment at all; all 114 model nodes are
documented now.

The worst of it was not missing documentation but ORPHANED documentation. The
65-line class doc block — "Implements LISTEN/NOTIFY client for PostgreSQL
connections... the end-user is going to work with this class directly", with
import and usage examples — was attached to nothing: MAX_PAYLOAD_LENGTH's own doc
block sat between it and `export class PgPubSub`, and TypeScript attaches the
NEAREST preceding comment. So the flagship class of the package had no summary at
all, on the site and in the package's own docs. Moving the const above the block
reattaches all 1,649 characters of it.

74 `@return {Type}` tags removed, and that is a content fix, not tidying.
`@return` is NOT a TSDoc tag, so api-extractor does not treat it as a block tag
and its content spills into the PRECEDING one: every method's last `@param`
description was ending with the return type. PgPubSub.listen documented its
channel parameter as "channel name to listen  {Promise<void>}". They are deleted
rather than renamed to `@returns` — none of the 74 carried any description, so
converting them would have rendered 74 empty Returns sections. TypeScript already
declares the return type.

12 `~~~` code fences switched to backticks. `~~~` is not a TSDoc fence, so the
examples were parsed as prose and every `@imqueue/...` in them read as a tag.
`@access` (12), `@event` (10), `@type`, `@constructor` and `@mergeModuleWith` are
all undefined TSDoc tags, removed — `@event end` only duplicated a summary that
already named the event in backticks.

The 20 typed event overloads had `@param event -` / `@param listener -` with no
text, which renders as an empty parameter table on 20 pages. Each now says what
its event means.

What reading the code turned up, now written down:

- ACQUIRE_INTERVAL is the failover bound, and it is asymmetric. A clean release
  deletes the lock row and fires a NOTIFY, so takeover is near-immediate; an
  unclean exit notifies nobody and the channel stays unhandled until the next
  retry. Anything published in that window is lost, because LISTEN/NOTIFY has no
  backlog. So the default is a 30s worst-case gap.
- PgClient.appName is load-bearing, not cosmetic: the lock's liveness check looks
  the holder up in pg_stat_activity BY that name, so two processes sharing one
  cannot be told apart and a blank one defeats the check.
- EXECUTION_LOCK de-duplicates by CONTENT, so two legitimately identical
  notifications collapse into one within UNIQUE_LOCK_TTL.
- singleListener is what makes scaling out safe at all: without it every replica
  receives and handles every notification.
- NoLock's onAcquire/onRelease are deliberate no-ops, which an empty method body
  otherwise reads as an oversight.

One `{@link PgPubSub.destroy}` needed the explicit `(PgPubSub:class)` selector:
PgPubSub is declared as both a class and an interface (declaration merging for the
typed event overloads), so a bare reference is ambiguous and rendered as a broken
link.

Comments only, no behaviour change. tsc, lint and format:check all pass; the
extractor now reports 0 errors and 0 tsdoc warnings for this package.

… package doc

The previous release reattached this class doc block, which had been orphaned.
Only 15 of its 65 lines were actually rendering: a `@see PgPubSubOptions` sat in
the MIDDLE of the block, and a TSDoc block tag ends the summary — so everything
after it belonged to the @see block, which api-documenter then dropped entirely.
Verified absent from the generated page: "Connecting and listening", "Handle
messages", "Destroying" and the close/connect paragraph, with no See Also section
to hold them either.

Restructured into the shape core/index.ts already uses: summary, then @remarks,
then @example blocks, with @see last where it cannot swallow anything. The
extracted comment goes from 1,649 to 2,335 characters, all of it reachable.

Fixed two errors in the examples while moving them, which matter more than usual
because agents copy these verbatim through the MCP server:

- `['ChannelOne','ChannelTwo'].map(channel => channel.listen())` called listen()
  on a string. It is `pubSub.listen(channel)`. The bug appeared twice.
- the 'message' handler had a stray semicolon inside the arrow body, making the
  snippet invalid TypeScript.

Also documented WHY subscriptions belong inside the 'connect' handler rather than
after awaiting connect(): only the handler re-runs on automatic reconnect, so
subscriptions made once afterwards are silently not restored. And spelled out what
close()/connect() is actually for — releasing the channel locks so another copy
takes over while this process is busy — versus destroy(), which cannot be undone.

Adds @packageDocumentation to the entry point. Without it the package ROOT page,
/api/pg-pubsub/latest/, had no description of its own and fell back to
"pg-pubsub package — @imqueue/pg-pubsub 3.0.3 API reference". That page is one of
the URLs actually submitted to the sitemap, so it was the most valuable one still
missing prose. It carries the at-most-once trade-off explicitly: NOTIFY has no
backlog, so anything published while no process holds the lock is gone, and the
8000-byte payload cap.

Comments only, no behaviour change. tsc, lint and format:check pass; 0 errors and
0 tsdoc warnings.

The interface description read "configure PgBubSub objects behavior". It is
the summary api-extractor lifts onto the generated reference page, so the
typo was published on /api/pg-pubsub/latest/pg-pubsub.pgpubsuboptions/ and in
the site's API search index.