feat(typecheck): public-method fixture coverage gate

AGENTS.md

@@ -72,8 +72,8 @@ Do not hand-edit `COMMAND_CATALOG`, `OPERATION_MEMBER_PATH_MAP`, `OPERATION_REFE
 - `pnpm test` - unit tests
 - `pnpm dev` - dev server from `examples/`
 - `pnpm check:types` - raw TS compile across all referenced projects (`tsc -b tsconfig.references.json`). Does NOT run the public-interface chain. Legacy alias: `pnpm run type-check`.
-- `pnpm check:public` - **canonical pre-merge command for typed public surfaces.** Validates both `superdoc` (tier discipline + jsdoc ratchet + vite build + postbuild chain + consumer typecheck matrix + deep-type audit + package-shape + snapshots + classification closure) and Document API (contract parity + output staleness + examples + overview). ~5 min. Non-mutating. Combines `check:public:superdoc` + `check:public:docapi`.
-- `pnpm check:public:superdoc` - SuperDoc public package surface only. Wraps nine stages in cheap-to-expensive order: `contract-tiers-test`, `contract-tiers`, `jsdoc-ratchet`, `build`, `consumer-typecheck-matrix`, `deep-type-audit-supported-root`, `package-shape`, `export-snapshots`, `root-classification-closure`. Legacy alias: `pnpm run check:public-contract`.
+- `pnpm check:public` - **canonical pre-merge command for typed public surfaces.** Validates both `superdoc` (tier discipline + jsdoc ratchet + public-method fixture coverage + vite build + postbuild chain + consumer typecheck matrix + deep-type audit + package-shape + snapshots + classification closure) and Document API (contract parity + output staleness + examples + overview). ~5 min. Non-mutating. Combines `check:public:superdoc` + `check:public:docapi`.
+- `pnpm check:public:superdoc` - SuperDoc public package surface only. Wraps ten stages in cheap-to-expensive order: `contract-tiers-test`, `contract-tiers`, `jsdoc-ratchet`, `public-method-coverage`, `build`, `consumer-typecheck-matrix`, `deep-type-audit-supported-root`, `package-shape`, `export-snapshots`, `root-classification-closure`. Legacy alias: `pnpm run check:public-contract`.
 - `pnpm check:public:docapi` - Document API public surface only. Wraps four stages: `contract-parity`, `contract-outputs`, `examples`, `overview-alignment`. Clean-checkout safe: gitignored generated artifacts are built in memory; tracked outputs (reference docs, overview block) are compared byte-for-byte. No mutation. Legacy alias: `pnpm run docapi:check`.
 - `pnpm generate:docapi` - regenerate Document API outputs after editing the contract (alias of `docapi:sync`). Writes gitignored Document API generated artifacts. Run only when you need the artifacts materialized locally (SDK builds, publishing); `check:public:docapi` does not require it.
 - `pnpm generate:all` - regenerate schemas, SDK clients, tool catalogs, reference docs.

packages/superdoc/scripts/README.md

@@ -144,12 +144,14 @@ what an actual consumer would see — not the workspace source.
 | `check-all-public-types-fixture.mjs` | Asserts every type-only root export has an `AssertNotAny<T>` line in `src/all-public-types.ts`. | Derives the expected set from `superdoc-root-classification.json`. |
 | `package-shape-gate.mjs` | External package-shape linters (publint + attw) against the packed tarball. | Catches condition ordering, masquerading exports, missing field declarations. |
 | `check-root-classification-closure.mjs` | Asserts no `supported-root` or `legacy-root` export references an `internal-candidate` symbol in its public declared type. | Closure rule from SD-3212. |
+| `check-public-method-coverage.mjs` | Obligation-based ratchet over public `SuperDoc` methods + getters. For each member the AST computes which obligations are meaningful (`parameters`, `returns`, or `call`); the gate fails when any required obligation is unsatisfied by a fixture under `src/` AND not on the debt snapshot. Catches the `search(text: string)` regression class — call sites do NOT satisfy `parameters`/`returns` on their own. | Snapshot at `public-method-coverage-debt-snapshot.json`; allowlist at `public-method-coverage-allowlist.cjs` (each entry validated: key must match a real member, value must be a non-empty reason). Refresh with `--write`. |
 
-Of these, five run as wrapper stages of `check:public:superdoc`
+Of these, six run as wrapper stages of `check:public:superdoc`
 after the cheap policy gates (`contract-tiers-test`,
-`contract-tiers`, `jsdoc-ratchet`) and `build`:
-`consumer-typecheck-matrix`, `deep-type-audit-supported-root`,
-`package-shape`, `export-snapshots`, `root-classification-closure`.
+`contract-tiers`, `jsdoc-ratchet`, `public-method-coverage`) and
+`build`: `consumer-typecheck-matrix`,
+`deep-type-audit-supported-root`, `package-shape`,
+`export-snapshots`, `root-classification-closure`.
 `consumer-typecheck-matrix` packs `superdoc.tgz` and installs it into
 the consumer fixture. The rest reuse what matrix produced:
 `deep-type-audit-supported-root`, `export-snapshots`, and

scripts/check-public-contract.mjs

@@ -29,7 +29,20 @@
  *                                      land without `// @ts-check` or
  *                                      when the allowlist carries
  *                                      empty/stale entries.
- *   4. build                         - vite build + the postbuild
+ *   4. public-method-coverage        - obligation-based ratchet over
+ *                                      public SuperDoc methods +
+ *                                      getters. For each member the
+ *                                      AST computes which obligations
+ *                                      are meaningful (parameters /
+ *                                      returns / call); each unmet
+ *                                      obligation must be on the debt
+ *                                      snapshot or the gate fails.
+ *                                      Call sites do NOT satisfy
+ *                                      parameters/returns obligations
+ *                                      on their own — that's why
+ *                                      `search(text: string)` shipped
+ *                                      under v1 of this gate.
+ *   5. build                         - vite build + the postbuild
  *                                      validator chain
  *                                      (check-tsconfig-type-surface,
  *                                      ensure-types, audit-bundle,
@@ -40,29 +53,29 @@
  *                                      Skipped when `--skip-build` is
  *                                      passed (CI calls `pnpm run build`
  *                                      separately in its own step).
- *   5. consumer-typecheck-matrix     - packs superdoc + installs the
+ *   6. consumer-typecheck-matrix     - packs superdoc + installs the
  *                                      tarball into
  *                                      tests/consumer-typecheck/
  *                                      node_modules/, then runs every
  *                                      consumer scenario.
- *   6. deep-type-audit-supported-root - strict gate on the supported-
+ *   7. deep-type-audit-supported-root - strict gate on the supported-
  *                                      root public surface; fails on any
  *                                      `any` leak. Reuses the install
- *                                      from stage 5.
- *   7. package-shape                 - publint + attw against the packed
+ *                                      from stage 6.
+ *   8. package-shape                 - publint + attw against the packed
  *                                      manifest. Reuses the tarball
- *                                      from stage 5.
- *   8. export-snapshots              - super-editor / legacy / root
+ *                                      from stage 6.
+ *   9. export-snapshots              - super-editor / legacy / root
  *                                      no-growth export snapshots.
  *                                      Reuses the install.
- *   9. root-classification-closure   - no supported-root or legacy-root
+ *  10. root-classification-closure   - no supported-root or legacy-root
  *                                      export references an internal-
  *                                      candidate type in its public
  *                                      declared shape (SD-3212 A1b).
  *
- * Why stage 5 runs before 6-9: stage 5 packs `superdoc.tgz` and
- * installs the tarball into the consumer fixture once. Stages 6, 8,
- * and 9 reuse the installed fixture; stage 7 reuses the packed tarball
+ * Why stage 6 runs before 7-10: stage 6 packs `superdoc.tgz` and
+ * installs the tarball into the consumer fixture once. Stages 7, 9,
+ * and 10 reuse the installed fixture; stage 8 reuses the packed tarball
  * directly. Without this ordering each downstream stage would `--pack`
  * separately and multiply the work.
  *
@@ -122,6 +135,18 @@ const stages = [
       'fails when new public-reachable JSDoc files land without // @ts-check. ' +
       'Cheap; runs before the slow build so JSDoc drift fails fast.',
   },
+  {
+    name: 'public-method-coverage',
+    cwd: REPO_ROOT,
+    cmd: 'node',
+    args: ['tests/consumer-typecheck/check-public-method-coverage.mjs'],
+    blurb:
+      'Obligation-based ratchet over public SuperDoc methods + getters. ' +
+      'Each member has computed obligations (parameters / returns / call) ' +
+      'that must be satisfied by a typed assertion in a consumer fixture, ' +
+      'or be on the debt snapshot. Call sites do NOT satisfy parameters/' +
+      'returns on their own (this is why search(text: string) shipped).',
+  },
   {
     name: 'build',
     cwd: REPO_ROOT,