ci(spec): public API-surface snapshot gate to catch silent export drift (#2035)

For a metadata-driven platform the spec package IS the third-party API surface.
A removed/renamed/kind-changed export silently breaks every consumer pinned to a
published release the moment they upgrade (the #2023 class) — and no in-repo
consumer catches it, because they all co-evolve with the spec in the same commit.

`scripts/build-api-surface.ts` enumerates every exported `name (kind)` from the
built `.d.ts` of each public entry point (`.`, `./ui`, `./data`, … 16 entries,
4251 exports), resolving re-export aliases to their real kind. The result is
committed at `packages/spec/api-surface.json`.

  pnpm --filter @objectstack/spec gen:api-surface     # regenerate + write
  pnpm --filter @objectstack/spec check:api-surface   # CI: fail on any drift

Wired into lint.yml's TypeScript Type Check job (after the build step). A
REMOVED export fails as breaking (bump major); an ADDED export still requires
regenerating the snapshot, so every change to the public surface is deliberate,
never silent. Complements the downstream-contract gate: that proves exercised
exports still ACCEPT real third-party metadata (depth); this proves the whole
export set still EXISTS (breadth).

Dev tooling only — the script and snapshot are not in the package `files`, so
nothing ships to consumers. Sort is code-unit (not locale) for cross-platform
determinism; verified the check passes clean and rejects a simulated removal.

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

Author: os-zhuang

.github/workflows/lint.yml

@@ -107,3 +107,12 @@ jobs:
       # export a published-spec third party already uses. See the package README.
       - name: Type check downstream consumer contract
         run: pnpm --filter @objectstack/downstream-contract run typecheck
+
+      # Public API-surface gate (#2035): the spec package IS the third-party API.
+      # A removed/renamed export silently breaks every consumer pinned to a
+      # published release. This diffs the built export surface against the
+      # committed snapshot; intentional changes regenerate it via
+      # `pnpm --filter @objectstack/spec gen:api-surface`. Runs after the build
+      # step above (reads the built dist).
+      - name: Check @objectstack/spec public API surface
+        run: pnpm --filter @objectstack/spec run check:api-surface