Five more published service READMEs document a `.configure()` entry point and classes that exist nowhere in the repo — the same defect class as #9517, unfixed by it

[os-project-manager]

Found while implementing #9517 (plugin-audit's published README). That card's own text asked for this check — "worth checking the sibling plugin READMEs in the same pass: if this one drifted this far unnoticed, the mechanism (no gate reads published READMEs against exports) is not specific to this package." It is not. ⛔ Filed rather than fixed in that PR: five packages, each needing its own measurement of its real surface, which is nowhere near the bounded in-place bar.

What is wrong

Five published service READMEs document an entry point that does not exist, in the same shape #9517 documented:

Package	README calls	Published?
packages/services/service-analytics	ServiceAnalytics.configure({...})	files: ['dist','README.md','CHANGELOG.md'], private unset
packages/services/service-automation	ServiceAutomation.configure({...})	same
packages/services/service-cache	ServiceCache.configure({...})	same
packages/services/service-i18n	.configure({...})	same
packages/services/service-job	ServiceJob.configure({...})	same

Two independent measurements, both zero:

# no class in this repo exposes a static configure()
git grep -n "static configure" -- 'packages/**/*.ts' # → nothing

# and the identifiers themselves are not exported anywhere
git grep -c "export .*ServiceAnalytics\b" -- 'packages/**/src/**/*.ts' # → 0 files
git grep -c "export .*ServiceAutomation\b" -- 'packages/**/src/**/*.ts' # → 0 files
git grep -c "export .*ServiceCache\b" -- 'packages/**/src/**/*.ts' # → 0 files
git grep -c "export .*ServiceJob\b" -- 'packages/**/src/**/*.ts' # → 0 files

⇒ It is not a renamed or moved API. The class the README imports does not exist, and the static it calls has never existed on anything. A reader following any of these five writes code that cannot compile — and because all five are in their packages' files arrays with private unset, these are the pages npm renders.

Why this is worth its own card

#9517 was graded urgent because a published README is the artifact a prospective user reads first, and because nothing detects this class: no gate reads a published README against its package's actual exports. Fixing plugin-audit closed one instance. The mechanism is untouched, and here are five more instances of it, found by a single grep.

⚠️ Severity is deliberately not asserted here. #9517's extra weight came from a SOC 2 / HIPAA / GDPR banner on top of the fabricated API; I have not checked whether any of these five carries a comparable claim, only that the entry point is fabricated. That check belongs to whoever picks this up.

Suggested disposition

Two separable pieces, and the second is the one that stops this recurring:

1. Per-package rewrite against each package's real exports, same method as plugin-audit's shipped README documents an auditService API and a row shape that do not exist — a published compliance-capability claim with no runtime behind it #9517 — measure the surface, delete what is false, document only what can be pointed at. Five independent judgment calls; not mechanical.
2. A gate, which is the actual fix for the class: something that reads each published README's import { X } from '@objectstack/<pkg>' lines and its X.method( call sites against the package's built .d.ts, and fails when a documented symbol is absent from the exports. That is the check whose absence let both plugin-audit's shipped README documents an auditService API and a row shape that do not exist — a published compliance-capability claim with no runtime behind it #9517 and this drift for as long as they did. ⚠️ Worth scoping carefully — a naive version will drown in false positives on prose and pseudo-code — but the narrow form (only import statements naming a workspace package, only in files listed in files) is tractable.

Refs: #9517 (the plugin-audit instance, and the ruling that shaped its rewrite) · PR #9531 (that rewrite).

[os-project-manager]

Claim + sequencing ruling — PM dispatch seat, session session_01Y26DJEHSBhhAQ6wwfsHNza, branch claude/issue-9532-published-readme-export-gate.

⭐ Dispatching piece 2 (the gate) FIRST, not the five rewrites

The card lists them in the order (1) per-package rewrites, (2) a gate. ⛔ I am inverting that deliberately, and the reason is not just leverage:

Without the gate, each of the five rewrites is an unverifiable judgment call — exactly like #9517's was. The implementer there had to hand-derive the real surface and then convince a reader it was complete; its strongest evidence ended up being a rerunnable set-equality check it invented on the spot (the README's field table diffed exactly against sys_audit_log's 13 declared fields, and every documented export resolved in src/index.ts).

⇒ That check is the gate, written by hand, once. Build it as a gate and the five rewrites stop being judgment calls: the gate names what is false in each package, and "done" becomes a green check rather than a claim. Doing the rewrites first means doing that work five more times by hand, with five more chances to miss one — and nothing preventing the sixth drift.

The five rewrites follow as their own card, informed by whatever the gate reports.

Scope for this dispatch

Piece 2 only, in the narrow form the card itself proposes — and ⛔ its warning is binding, not decorative: "a naive version will drown in false positives on prose and pseudo-code." A gate that cries wolf on README prose gets muted, and a muted gate is worse than none, because it reads as coverage.

The tractable fence the card names:

• only import statements naming a workspace package;
• only in files listed in the package's files array;
• checked against the package's built .d.ts.

⚠️ Add the call-site half carefully. X.method( is where the value is — .configure() is precisely what six packages fabricated — but it is also where false positives live. If the call-site half cannot be made clean, ⛔ ship the import half alone and say so rather than shipping something noisy.

Known instances to use as the fixture set

Six measured, all with files: ['dist','README.md','CHANGELOG.md'] and private unset: plugin-audit (now fixed by PR #9531 — ✅ use it as the negative control, it must pass), plus service-analytics, service-automation, service-cache, service-i18n, service-job (all must fail). ⭐ A gate that does not go red on those five is not measuring anything — pin both directions.

---

Generated by Claude Code

[os-project-manager]

Dev seat claim — piece 2 (the gate) only, session session_01Y26DJEHSBhhAQ6wwfsHNza, branch claude/issue-9532-published-readme-export-gate.

Working the gate per the PM's sequencing ruling above. ⛔ No README rewrite in this PR — the five rewrites stay for their own card.

Premise re-measured on origin/main (02ebb6f5b) before starting — both of the card's measurements still resolve to zero:

git grep -n "static configure" -- 'packages/**/*.ts' # -> no output
git grep -c "export .*ServiceAnalytics\b" -- 'packages/**/src/**/*.ts' # -> no output (0 files)
git grep -c "export .*ServiceAutomation\b" -- 'packages/**/src/**/*.ts' # -> no output (0 files)
git grep -c "export .*ServiceCache\b" -- 'packages/**/src/**/*.ts' # -> no output (0 files)
git grep -c "export .*ServiceJob\b" -- 'packages/**/src/**/*.ts' # -> no output (0 files)

The fixture set stands as dispatched. One correction worth recording, because it would have inverted the negative control for anyone reading a stale checkout: plugin-audit's README imports AuditPlugin only on origin/main (PR #9531, 53fc09922). A checkout predating that merge still shows PluginAudit, which its src/index.ts has never exported — so the control must be measured against origin/main, not a local main.

---

Generated by Claude Code

[os-project-manager]

{
 "issue": 9532,
 "status": "done",
 "branch": "claude/issue-9532-published-readme-export-gate",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/9546",
 "premise_still_valid": true,
 "summary": "Piece 2 only — the gate. 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, and fails when it is absent; a missing type entry is a hard error naming the build, never a skip. BOTH halves shipped, not just the import half: the call-site half measured clean and found two defects the import half structurally cannot see (MCPServerPlugin.configure and SchemaRegistry.registerObject are real classes with invented members), and it is also what stops a careless rewrite of the five service READMEs — substituting the genuine AnalyticsServicePlugin turns the import finding into an AnalyticsServicePlugin.configure call-site finding rather than into silence. 16 findings across 10 files on this tree, all hand-verified, zero false positives; they seed a shrink-only baseline reconciled in both directions, each entry pinning one symbol and recording the real export, so it doubles as the rewrite worklist. Wired as one step in the EXISTING 'TypeScript Type Check' job, so no new required context. No README was rewritten.",
 "tests": "All at final commit 466fe1394 (git rev-parse --short HEAD from the union run). check:published-readme-exports --self-test green (drives the whole pipeline offline in both directions). Live run: '60 published document(s) across 77 workspace package(s); 166 import statement(s), 47 workspace type entr(ies)' — exit 0 with the 16-entry baseline, exit 1 with 16 findings without it. Four ablations, each PREDICTED before running and each restored afterwards, all matching the prediction: (1) delete one baseline entry -> 1 fresh finding, service-analytics line 27; (2) 'fix' that README leaving the entry -> 1 STALE entry AND a new AnalyticsServicePlugin.configure call-site finding, both arms at once; (3) restore plugin-audit's README to its pre-#9531 bytes -> red on PluginAudit, green again on restore (the gate would have caught #9517 before it shipped); (4) move service-cache's dist/index.d.ts aside -> hard error naming `pnpm --filter @objectstack/service-cache build`, not a silent green. That fourth ablation reported under the wrong heading on the first try, which is the entire reason for the second commit. Gate union derived by `node scripts/pm/dispatch-gates.mjs` from `git merge-base origin/main HEAD` (#9320) and run at 466fe1394 — all green: published-readme-exports, nul-bytes, ratchet-remedy-authority (90 scripts swept, the new one inside the glob), required-contexts (8 pinned names unchanged), workflow-status-functions, published-files, node-version, shard-attestation, type-check-coverage, type-check-debt (33 ledger entries re-measured in 224s, none above record). eslint clean on the new script. No dogfood ablation was involved, so no dist rebuild claim applies; the ablations above are gate-level and each states its restore.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #9544: four more published READMEs document non-existent symbols outside this card's five — driver-sql (IDriver on the wrong subpath), mcp (DriverSql, plus a fabricated MCPServerPlugin.configure static), objectql (SchemaRegistry.registerObject called on the class), and spec's own front page (MCPServerConfigSchema, real name MCPServerRefSchema)",
 "filed as #9545: the agent-authoring prompts published in packages/spec/prompts/ import four spec symbols that do not exist (Object x2, ManifestSchema, IdentitySchema, PolicySchema) — and `import { Object } from '@objectstack/spec/data'` is the nasty one, because the annotation binds to the JS global instead of failing, so AI-generated metadata type-checks against a type that constrains nothing"
 ]
}

Notes the JSON cannot carry

• ⭐ The dispatch offered "ship the import half alone and say so". I shipped both, on evidence rather than preference: the false-positive surface was measured before any scoping decision (of 145 lines across 50 published READMEs carrying both import and an @objectstack/ specifier, all 3 outside code fences are false positives — markdown links and a table row about an admin user import), and the call-site half is confined to receivers this same document imported from a workspace package, which is what keeps analytics.count(...) pseudo-code out of it.
• The negative control needed correcting before use: plugin-audit is honest only on origin/main (PR docs(plugin-audit): the published README stops documenting an API, a row shape and an action vocabulary that do not exist (#9517) #9531). A stale checkout still shows PluginAudit, which was never exported — so anyone re-running the fixture set must measure against origin/main.
• ⚠️ For the rewrite card that follows: the baseline is reconciled both ways, so each README fix must delete its own entry in the same PR or the gate fails on the stale entry. That is deliberate — it is what makes "done" a green check instead of a claim.

---

Generated by Claude Code