@@ -0,0 +1,18 @@
+---
+'@objectstack/spec': minor
+---
+
+`api-surface-declarations/<entry>.txt` — every export of every published entry point now ships a readable pin of the `.d.ts` declaration text the packed build actually emits for it, and the 27-entry `api-surface-signatures.json` hash it subsumes is retired (#16045).
+
+`Clause-②: yes (widening)`
+
+Until now this package pinned its public surface on one axis. `api-surface/<entry>.json` records each export as `name (kind)` — 5336 rows across 17 entry points, re-derived on the landing tree — and a signature change, a renamed interface field and a dropped union member move **none** of them. The only shape pin was `api-surface-signatures.json`: 27 rows, 0.5% of the surface, and reference-level even there, because it hashed `checker.typeToString()`, which prints `z.input<typeof ActionSchema>` without expanding it. A breaking shape change to a ratified public type could pass every witness green.
+
+- **Text, ⛔ not a hash, deliberately.** A digest answers "did the bytes move" with one opaque bit whose known failure at scale is that a red one gets *accepted* rather than investigated. Each shard holds one block per declaration — `// ── Name (kind) ──` followed by the declaration verbatim — so a diff names the export and shows the change, and the existing review discipline is what guards it.
+- **The input is the packed `.d.ts` reached through the `exports` map**, i.e. the declarations a consumer installs, never `src/`. Two of the manifest's 19 `exports` entries are asset subpaths with no declaration (`./openapi.json`, `./package.json`), which is why this artifact and `api-surface/` both hold 17 shards.
+- **What it costs, measured on the landing tree**: 12,661,943 bytes (12.08 MiB) of text across 17 shards, 237,706 lines, 1.02 MiB gzipped against this package's ~17.6 MiB compressed `dist`. The skew is extreme — the median declaration is 81 bytes and the 20 largest hold ~65% of the bytes, because a Zod schema's packed declaration is its fully expanded structural type. That expansion is exactly what makes an inner field rename visible; it also means four declarations exceed 20,000 lines each.
+- **Leading TSDoc is excluded**, so a re-worded `.describe()` does not churn this artifact — documentation drift stays `check:docs`'s axis.
+- **The retirement is a strict superset, proven before it landed**: all 27 factory names resolve to a declaration block in `api-surface-declarations/root.txt`, 0 missing. For those 27 declarations text and hash discriminate the same amount (both print a type reference); what is *gained* is the 5309 other declarations, including the schemas those factories point at, whose expanded blocks are where an inner-key narrowing shows up. Nothing published read the retired file: it was not in this package's `files[]`.
+- **Sharded per entry point from day one**, for the reason `api-surface/` is: the merge queue rebuilds server-side where no custom merge driver runs, so two PRs sharing one generated file evict the second.
+
+Regenerate with `pnpm --filter @objectstack/spec build && pnpm --filter @objectstack/spec gen:api-surface-declarations`; `check:api-surface-declarations` names that command when it fails. It reads the built dist, so a missing or stale one is a hard refusal in both modes rather than a green run over nothing.
@@ -144,10 +144,10 @@ packages/spec/authorable-surface.base.json                   merge=os-regen
 packages/spec/authorable-defaults/**                         merge=os-regen
 packages/spec/json-schema.manifest/**                        merge=os-regen
 packages/spec/api-surface/**                                 merge=os-regen
+packages/spec/api-surface-declarations/**                     merge=os-regen
 packages/spec/src/meta-spelling/meta-url-data.generated.ts   merge=os-regen
 packages/spec/export-origins/**                              merge=os-regen
 packages/spec/declaration-map/**                             merge=os-regen
-packages/spec/api-surface-signatures.json                    merge=os-regen
 docs/protocol-upgrade-guide.md                               merge=os-regen
 docs/audits/2026-07-unknown-key-strictness-ledger.counts.md  merge=os-regen
 content/docs/references/**                                   merge=os-regen
 
@@ -5187,11 +5187,16 @@ jobs:
 
       # The authorable KEY surface — what a metadata author may write, which for
       # this platform is the third-party API. `api-surface/` records exported
-      # names and `api-surface-signatures.json` hashes factory types as TypeScript
-      # PRINTS them (a reference, never structurally expanded), so neither sees a
-      # key added to or removed from a schema. #3883 removed three authorable keys
-      # with every witness green; #3733 did it by accident. ADR-0059 §5 deferred
-      # this gate until a narrowing actually slipped both — it has.
+      # names only, so it does not see a key added to or removed from a schema;
+      # the shape sibling that used to sit beside it (`api-surface-signatures.json`,
+      # retired at #16045) hashed factory types as TypeScript PRINTS them — a
+      # reference, never structurally expanded — so it did not see one either.
+      # #3883 removed three authorable keys with every witness green; #3733 did it
+      # by accident. ADR-0059 §5 deferred this gate until a narrowing actually
+      # slipped both — it has. `check:api-surface-declarations` (consumer-gates
+      # lane) now records the declaration TEXT of every export, which DOES move on
+      # such a key; this gate stays the authority on the AUTHORABLE key set, which
+      # is a different question from the declared TypeScript shape.
       #
       # ⚠ ORDER: this step must stay ABOVE the `check:docs` step below. Its
       # `--check` run of scripts/build-schemas.ts writes the gitignored
@@ -6113,6 +6118,29 @@ jobs:
       - name: Check @objectstack/spec public API surface
         run: pnpm --filter @objectstack/spec run check:api-surface
 
+      # [#16045] The SHAPE half of the same surface, and the step the card above
+      # exists for: `api-surface/` pins 5336 `name (kind)` rows and a signature
+      # change, a renamed interface field and a dropped union member move NONE of
+      # them, so 99.5% of the pinned surface could not go red on a breaking shape
+      # change to a ratified public type. The declaration-text snapshot records
+      # what the packed `.d.ts` actually declares for every export, per entry
+      # point. Ruled at #16045 (director batch #60, maintainer 「同意」): text and
+      # ⛔ NOT a hash, because a red hash gets accepted rather than investigated
+      # and a readable diff is what makes contract review a guard.
+      #
+      # WHY THIS LANE. It resolves each entry point through the `exports` map to
+      # the BUILT `.d.ts` — the declarations a consumer installs — so it is
+      # build-dependent and sits after the two build steps above with its family
+      # (`check:api-surface`, `check:published-readme-exports`). A missing or
+      # stale dist is a HARD REFUSAL in both of the script's modes, never a skip:
+      # a build-dependent gate that silently reads nothing reports "not measured"
+      # as if it were "measured and clean" (#4690).
+      #
+      # It adds no required context: a step in an existing lane, so no open PR
+      # waits on a check whose name no head has ever reported (#9325).
+      - name: Check @objectstack/spec declaration text (the shape half)
+        run: pnpm --filter @objectstack/spec run check:api-surface-declarations
+
       # [#11350] Consumer-shaped declaration-emit pin against the BUILT root
       # entry (an un-annotated `export default defineStack(...)` must compile
       # with `declaration: true` — the TS2883 class). The pin is environment-
 
@@ -41,7 +41,12 @@ arithmetic composes on a merge and the judgement does not).
 
 - **`spec-changes.json`** — keyed by version, so two PRs append under different majors.
   Never a conflict surface worth splitting.
-- **`api-surface-signatures.json`** — 1.3KB, one line per `defineX` factory.
+- **`api-surface-signatures.json`** — RETIRED at #16045, and the one row here whose reason
+  did not survive its own artifact. It was 1.3KB, one line per `defineX` factory, so it was
+  never worth splitting. Its replacement is the opposite shape: `api-surface-declarations/`
+  holds the declaration TEXT of every export (12 MiB across 17 shards on the tree that
+  landed it), so it is sharded per entry point from the day it arrived, for the same
+  merge-queue reason `api-surface/` is.
 - **`authorable-surface.base.json`** — the #5235 deletion-gate anchor. Nothing but an
   explicit `gen:authorable-surface-base` writes it (#5358), so it was never on the churn
   path that made the other three the queue's serialization point. It also carries **one**
 
@@ -240,6 +240,7 @@
     "src/**/*.zod.ts",
     "CHANGELOG.md",
     "api-surface",
+    "api-surface-declarations",
     "spec-changes.json"
   ],
   "scripts": {
 
@@ -9,7 +9,7 @@
  * #2023 class) — and no in-repo consumer catches it, because they all co-evolve
  * with the spec in the same commit. See ADR-0059.
  *
- * Two committed artifacts, both checked in CI:
+ * One committed artifact, checked in CI:
  *   - api-surface/<entry>.json    — one `name (kind)` row per DECLARED KIND of
  *                                    every export of ONE public entry point
  *                                    (breadth: did an export disappear?). A
@@ -22,29 +22,35 @@
  *                                    because the queue rebuilds server-side with
  *                                    no custom merge driver. The root entry `.`
  *                                    lands in `root.json`.
- *   - api-surface-signatures.json — a stable hash of each `defineX` factory's
- *                                    resolved signature. Scoped to the factories to
- *                                    stay low-noise; full per-export signatures
- *                                    would churn on every internal type tweak.
- *                                    Deliberately NOT sharded: 1.3KB, one line
- *                                    per factory, never a conflict surface.
  *
- * SCOPE — read before trusting these as a narrowing gate. Both artifacts describe
- * the TYPESCRIPT surface. The hash is of `checker.typeToString()`, which prints a
- * type REFERENCE (`z.input<typeof ActionSchema>`) and does not expand it, so
- * adding or removing a key inside a schema does not move it: #3883 narrowed
- * `defineAction`'s input by three keys and this snapshot did not change. The
- * authorable KEY surface — which for a metadata-driven platform is the real
- * third-party API — is ratcheted separately by `authorable-surface/`
- * (scripts/build-schemas.ts, #3855). Value-level narrowing (an enum losing a
- * member) is still ungated, per ADR-0059 §5's evidence gate.
+ * SCOPE — read before trusting this as a narrowing gate. It is the BREADTH half
+ * and nothing more: a row records that an export EXISTS under a kind, so a
+ * signature change, a renamed interface field and a dropped union member move no
+ * row here at all. The SHAPE half is `api-surface-declarations/<entry>.txt`
+ * (scripts/build-api-surface-declarations.ts) — the declaration TEXT of every
+ * export, which is where each of those three becomes visible. The authorable KEY
+ * surface — which for a metadata-driven platform is the real third-party API —
+ * is ratcheted separately by `authorable-surface/` (scripts/build-schemas.ts,
+ * #3855). Value-level narrowing (an enum losing a member) is still ungated, per
+ * ADR-0059 §5's evidence gate.
+ *
+ * RETIRED HERE: `api-surface-signatures.json`, a `sha256` of each `defineX`
+ * factory's `checker.typeToString()`. It was the only shape pin on this surface
+ * and it covered 27 of 5336 declared rows. It is not merely narrow, it is
+ * REFERENCE-level — `typeToString` prints `z.input<typeof ActionSchema>` without
+ * expanding it, so #3883 narrowed `defineAction`'s input by three keys and the
+ * hash did not move. The declaration-text artifact records the same 27 factory
+ * declarations (proven covered before the retirement) AND the schemas they point
+ * at, whose own expanded blocks are where such a narrowing shows up. ⛔ Do not
+ * reintroduce a digest here: an opaque bit that goes red gets accepted, which is
+ * the failure mode the text artifact exists to avoid.
  *
  *   pnpm --filter @objectstack/spec gen:api-surface     # regenerate + write
  *   pnpm --filter @objectstack/spec check:api-surface   # CI: fail on any drift
  *
- * A REMOVED export or a CHANGED factory signature is breaking (bump major). An
- * ADDED export still requires regenerating, so every change is deliberate. Reads
- * the built dist — run after `pnpm --filter @objectstack/spec build`.
+ * A REMOVED export is breaking (bump major). An ADDED export still requires
+ * regenerating, so every change is deliberate. Reads the built dist — run after
+ * `pnpm --filter @objectstack/spec build`.
  *
  * That last sentence is a PRECONDITION, and since #7122 it is enforced rather
  * than merely documented: both modes refuse to read a dist that is missing or
@@ -57,8 +63,7 @@
  * tree whose sources were re-checked-out unchanged.
  */
 import ts from 'typescript';
-import { createHash } from 'node:crypto';
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { inspectDistFreshness } from './lib/dist-freshness';
@@ -71,7 +76,6 @@ import {
 
 const PKG_DIR = resolve(fileURLToPath(new URL('.', import.meta.url)), '..');
 const SURFACE_DIR = resolve(PKG_DIR, API_SURFACE_DIR_NAME);
-const SIG_SNAPSHOT = resolve(PKG_DIR, 'api-surface-signatures.json');
 const CHECK = process.argv.includes('--check');
 
 // BEFORE a single `.d.ts` is read (#7122). Order is the whole point: once
@@ -160,52 +164,20 @@ function buildSurface(): Record<string, string[]> {
   return surface;
 }
 
-/** Depth: hash of each `defineX` factory's resolved signature (from root). */
-function buildSignatures(): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const s of moduleExports(entries['.'], '.')) {
-    const name = s.getName();
-    if (!/^define[A-Z]/.test(name)) continue;
-    const resolved = unalias(s);
-    if (!(resolved.getFlags() & ts.SymbolFlags.Function)) continue;
-    const decl = resolved.valueDeclaration ?? resolved.declarations?.[0];
-    if (!decl) continue;
-    const type = checker.getTypeOfSymbolAtLocation(resolved, decl);
-    const str = checker.typeToString(type, decl, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.InTypeAlias);
-    out[name] = 'sha256:' + createHash('sha256').update(str).digest('hex').slice(0, 16);
-  }
-  return Object.fromEntries(Object.keys(out).sort().map((k) => [k, out[k]]));
-}
-
 const surface = buildSurface();
-const signatures = buildSignatures();
 const surfaceTexts = apiSurfaceShardTexts(surface);
-const sigStr = JSON.stringify(signatures, null, 2) + '\n';
 
 if (!CHECK) {
   const { written, removed } = writeShards(SURFACE_DIR, surfaceTexts);
-  writeFileSync(SIG_SNAPSHOT, sigStr);
   const total = Object.values(surface).reduce((n, a) => n + a.length, 0);
-  console.log(
-    `Wrote ${API_SURFACE_DIR_NAME}/ (${Object.keys(surface).length} entries, ${total} exports) ` +
-      `and api-surface-signatures.json (${Object.keys(signatures).length} factories).`,
-  );
+  console.log(`Wrote ${API_SURFACE_DIR_NAME}/ (${Object.keys(surface).length} entries, ${total} exports).`);
   // The locality claim, printed: a PR that changed one entry point's exports
   // rewrites one shard, so two such PRs cannot conflict (#5837).
   if (written.length > 0) console.log(`  touched: ${written.map((n) => `${n}.json`).join(', ')}`);
   if (removed.length > 0) console.log(`  removed: ${removed.map((n) => `${n}.json`).join(', ')}`);
   process.exit(0);
 }
 
-function read(path: string, hint: string): string {
-  try {
-    return readFileSync(path, 'utf8');
-  } catch {
-    console.error(`No snapshot at ${path}. Run \`pnpm --filter @objectstack/spec gen:api-surface\` and commit it (${hint}).`);
-    process.exit(1);
-  }
-}
-
 let breaking = 0;
 let additions = 0;
 
@@ -246,24 +218,14 @@ if (staleShards.length > 0 || orphanShards.length > 0) {
   }
 }
 
-// Depth check (factory signatures).
-const prevSig: Record<string, string> = JSON.parse(read(SIG_SNAPSHOT, 'depth'));
-if (JSON.stringify(prevSig, null, 2) + '\n' !== sigStr) {
-  for (const name of new Set([...Object.keys(prevSig), ...Object.keys(signatures)])) {
-    if (!(name in signatures)) { console.error(`\n  signature removed: ${name}`); breaking++; }
-    else if (!(name in prevSig)) { console.error(`\n  signature added: ${name}`); additions++; }
-    else if (prevSig[name] !== signatures[name]) { console.error(`\n  signature changed: ${name}  (${prevSig[name]} → ${signatures[name]})`); breaking++; }
-  }
-}
-
 if (breaking === 0 && additions === 0) {
-  console.log('@objectstack/spec public API surface + factory signatures unchanged ✓');
+  console.log('@objectstack/spec public API surface unchanged ✓');
   process.exit(0);
 }
 
-console.error(`\n@objectstack/spec public API changed: ${breaking} breaking (removed/narrowed), ${additions} added.`);
+console.error(`\n@objectstack/spec public API changed: ${breaking} breaking (removed), ${additions} added.`);
 if (breaking > 0) {
-  console.error('A REMOVED export or a CHANGED factory signature is a BREAKING change for third parties — bump @objectstack/spec to a new major (or restore it).');
+  console.error('A REMOVED export is a BREAKING change for third parties — bump @objectstack/spec to a new major (or restore it).');
 }
 console.error('If intentional, run `pnpm --filter @objectstack/spec gen:api-surface` and commit the updated snapshots.');
 process.exit(1);