ci: a published README's symbol claims are checked against the package's built exports

[os-project-manager]

Part of #9532 — piece 2 only, the gate. The five per-package README rewrites are the other half of that card and are deliberately untouched here, so the card stays open for them.

Verified at 466fe1394 (the head of this branch; the gate union below was run on that tree).

Premise, re-measured before building

Both of the card's measurements still resolve to zero on origin/main (02ebb6f5b): no static configure anywhere under packages/**/*.ts, and none of ServiceAnalytics / ServiceAutomation / ServiceCache / ServiceJob is exported by any file. The fixture set stands as dispatched.

One correction worth recording: plugin-audit's README only became honest on origin/main (PR #9531). A checkout predating that merge still shows PluginAudit, which src/index.ts has never exported — so the negative control has to be measured against origin/main, not a local main.

What landed

scripts/check-published-readme-exports.mjs resolves every symbol a published markdown document tells a reader to import — through the package's exports map, to the built .d.ts a consumer actually installs — and fails when the symbol is not there.

Two halves:

• import — a name in an import { … } from clause naming a workspace package must be an export of that package's type entry. This catches all six measured instances.
• call site — for a name that did resolve, Name.member( must name a real property of that symbol's type. This is where .configure() lives in the worse version of the defect, where the class itself is real.

Type resolution is the TypeScript compiler's, over one shared program — not a regex over declaration text — so cross-package re-exports resolve the way a consumer's compiler resolves them.

The call-site half is not decorative — it was kept on evidence

The dispatch said to ship the import half alone rather than ship something noisy. Both halves shipped, because both measured clean and the second one found defects the first structurally cannot see:

• packages/mcp/README.md:40 — MCPServerPluginis a real exported class; its .configure() is invented.
• packages/objectql/README.md:66 — SchemaRegistry.registerObject is an instance method called on the class.

It is also what stops a careless rewrite of the five service READMEs. Measured directly: substituting the genuine AnalyticsServicePlugin into service-analytics' README turns the import finding into an AnalyticsServicePlugin.configurecall-site finding — not into silence.

Scope was set by measurement, not taste

The card warned a naive version "will drown in false positives on prose and pseudo-code", and a muted gate is worse than none because it still reads as coverage. Every boundary below was measured on the real tree first:

Decision	The measurement behind it
Fenced code blocks only	Of 145 lines across 50 published READMEs carrying both import and an @objectstack/ specifier, 142 are inside fences. All 3 outside are false positives — two markdown links in packages/core ("import @objectstack/spec") and one table row about an admin user import feature.
Code-language fences only	Import lines appear only under typescript / ts / tsx / diff. bash (51 fences), json (12), sql, sh are excluded; untagged fences are included (zero import lines today, so it is free coverage).
diff fences read the + side only	The one diff fence in the tree is a migration table whose - lines document the old imports. Scanning them would report the deletion the fence exists to announce.
CHANGELOG.md excluded	It is in every package's files, but a changelog documents the past: an entry naming a v1 export that v3 removed is correct text this gate would redden permanently, unfixably. Any other published .md is in scope automatically.
Only workspace targets	react, @objectql/core and friends are not this repo's business.

Result on this tree: 16 findings across 10 files, and zero false positives. Every one was hand-verified against the built .d.ts before it was accepted.

Why the built .d.ts, and why an unbuilt package is an error

The question is "can a consumer write this line?", and a consumer resolves through exports to a .d.ts. Reading src/index.ts would answer a similar-looking question about a file no consumer sees, and would miss a subpath the README imports that exports never declares (which is exactly driver-sql's finding).

That makes it build-dependent, and build-dependent gates fail characteristically: on a fresh checkout dist/ is absent, the scan reads nothing, and green means "not measured" while looking like "measured and clean". So a missing type entry is a hard error with its own heading and remedy, never a skip. The second commit exists only because reverse-verifying that path showed it reporting under the wrong heading with a remedy pointing at the README instead of at pnpm build.

Baseline

All 16 findings are pre-existing on main, so they seed scripts/published-readme-exports.baseline.json:

• shrink-only, reconciled in both directions — an entry whose finding no longer occurs is STALE and fails, so fixing a README forces its entry to be deleted in the same PR;
• one symbol per entry, never a file — a baselined package that invents a second fabricated symbol still goes red;
• each entry records the measured real export, so the baseline is the rewrite worklist rather than a to-do list someone has to re-derive;
• no --fix flag, and adding an entry is not offered as an author remedy — this gate takes the refusal arm of the check:engine-double-contract fires at CI time, not authoring time — four independent PRs tripped it on brand-new test files in one shift, and a pre-warning in the brief did not prevent it #8435 convention;
• plugin-audit is deliberately absent — it is the negative control.

Self-test and reverse verification

--self-test drives the whole pipeline offline in both directions, over the shapes measured above: the three prose false positives, the bash fence, the diff fence's two sides, multi-line clauses, aliases, import type, both exports-map shapes, and end-to-end analysis of a fabricated import, a fabricated static, and an honest README. A text scanner over prose fails by quietly matching nothing, and only a positive control tells that apart from a clean tree.

Four ablations, each predicted before it was run, each restored afterwards:

Ablation	Predicted	Observed
Delete one baseline entry	1 fresh finding	1 fresh finding, service-analytics line 27
"Fix" that README, leave the entry	1 stale entry and a new call-site finding	exactly that — AnalyticsServicePlugin.configure
Restore plugin-audit's README to its pre-#9531 text	red on PluginAudit	red on PluginAudit; green again on restore
Remove one package's dist/index.d.ts	hard error naming the build	hard error naming pnpm --filter @objectstack/service-cache build

The third is the strongest control: on the exact bytes of the README that shipped, this gate would have caught #9517 before it went out.

CI wiring

One step added to the existingTypeScript Type Check job in lint.yml, after its build steps, beside the other dist-reading gate (check:api-surface). No new job, so no new required context — nothing waits on a check name no head has ever reported. Confirmed by check:required-contexts, which still pins the same 8 names across 2 workflows.

Gate union — all green at 466fe1394

Derived from the actual changed paths via node scripts/pm/dispatch-gates.mjs (paths taken from git merge-base origin/main HEAD, per #9320), then run:

check:published-readme-exports OK (self-test + 60 docs, 166 imports, 47 type entries)
check:nul-bytes OK
check:ratchet-remedy-authority OK (90 scripts swept; the new one is inside the glob)
check:required-contexts OK (8 pinned names, unchanged)
check:workflow-status-functions OK
check:published-files OK
check:node-version OK
check:shard-attestation OK
check:type-check-coverage OK
check:type-check-debt OK (33 ledger entries re-measured, 224s, none above record)

eslint is clean on the new script. Prettier is not wired into CI and the existing gate scripts fail bare prettier --check identically, so the file follows its siblings' convention.

Changeset

None — new tooling, nothing published moves. Labelled skip-changeset.

Filed, not fixed

Eleven of the 16 findings sit outside this card's five-package rewrite scope. One of them (service-i18n's cross-package useTranslation claim) falls inside #9532's own rewrite of that README, so it needs no card. The other ten are filed unassigned:

• Four more published READMEs document symbols that do not exist — driver-sql, mcp (×2), objectql, and spec's own front page #9544 — driver-sql, mcp (×2), objectql, and spec's own front page.
• The agent-authoring prompts published in packages/spec/prompts/ import four spec symbols that do not exist — and one of them resolves to the JS global instead of failing #9545 — the agent-authoring prompts in packages/spec/prompts/, where import { Object } from '@objectstack/spec/data' binds to the JS global instead of failing loudly.

---

Generated by Claude Code