ci: public-API snapshot gate — breaking diff requires a major

[rubenhensen]

Track the public API surface as a reviewed snapshot (api-extractor report or a rolled-up .d.ts diff) and gate CI on it: a breaking diff without a major version is red. Evidence this is needed: the fix that shipped as refactor: and silently published nothing — commit-type labels are fallible, the snapshot is not.

Child of the external-compatibility umbrella in encryption4all/postguard; part of encryption4all/postguard#247 (workstream D).

[rubenhensen]

/dobby please pick this up — the monorepo landed (#132), so this is now unblocked. Spec in the issue body: track the public API surface of packages/pg-js as a reviewed snapshot (api-extractor report or a rolled-up .d.ts diff) and gate CI on it, so a breaking diff without a major fails. Context worth knowing: the fleet's other two API gates are in place for comparison — cargo-semver-checks is being built for Rust (encryption4all/postguard#253) and PublicApiAnalyzers landed for .NET (encryption4all/postguard-dotnet#52, which caught a real breaking change shipping as a patch). Releases here are changesets now, so the gate should reason about the pending changeset's bump type where it can. Part of encryption4all/postguard#247 (workstream D).

[dobby-coder]

Picked this up, @rubenhensen — now that #132's monorepo landed, I'm starting on the pg-js public API gate: setting up an api-extractor (or rolled-up .d.ts diff) snapshot for packages/pg-js, wiring it into CI to fail on breaking changes without a major bump, and having it reason about the pending changeset's bump type where possible. I'll open a draft PR and keep it updated as it progresses.

[dobby-coder]

Done — postguard-js#135 is signed off, out of draft, and green on all five CI lanes.

It ships the two-part gate you asked for: a postbuild freshness check on the committed pg-js.api.md snapshot, plus pnpm api:gate, which classifies the report diff against the merge base and fails when the changeset's bump type is too small for what changed. That completes workstream D alongside cargo-semver-checks (Rust) and PublicApiAnalyzers (.NET).

Three review cycles ran along the way — rounds 2/3 closed six classifier holes (worst: a name-collision could read a real break as a false major), and round 4 caught a related gap where type-parameter positions fell back to name matching. Both round-4 findings were one-liners, so I fixed them directly on the branch (17964e6, two new regression tests, 284 green).

One thing left for you: api:gate isn't wired into CI yet since the bot can't push workflow files. The job patch is waiting in a PR comment — apply it and tighten the "pending" note in CLAUDE.md in the same PR.