reader program 1/4 — the option-B acceptance probe: a two-package fixture booted through every entry path with the flattened collections absent

[hotlong]

Part of #14122 · blocks #14512 · first card of the reader program ruled on #14512 (comment 5528589044, maintainer 2026-09-03, decision batch #23).

The ruling: a multi-package artifact carries each definition once under packages[]; the reader half lands first with the artifact staying additive, the emitter half last. And, in the ruling's own words, "the reader half does not land without it" — it being this pin.

Why this card exists before any reader is touched

Option B's failure mode is a reader nobody enumerated. That is not hypothetical here: the enumeration missed sites twice (comments 5523603341 and 5523741937), the second time including a reader in @objectstack/plugin-security, a package nobody had scoped. And the symptom is silent — nothing throws, the collection is simply absent, so a multi-package artifact boots clean while having lost its declarative actions, its engine registration, its seed data or its default permission set.

A pin that goes red when a reader is missed is the only thing that converts that silent loss into a build failure. Every other card in this program is unsafe to land without it, which is why it is 1/4 and why it carries priority:p2 while the rest carry p3.

What to build

A two-package fixture carrying one member of every collection family — objects (with embedded actions), global actions, hooks, functions, jobs, seed data, translations, datasources, datasourceMapping, permissions, positions. One package declares the app; the other contributes.

Boot it through every entry path, twice: once in today's additive shape, and once with an option-B-shaped artifact (the top-level collections removed, packages[] carrying everything). Every subsystem must see its collections in both shapes. The entry paths, from the boundary measurement in 5523741937:

Boundary	file:line
B1 loadArtifactBundle — compiled-artifact load	packages/runtime/src/load-artifact-bundle.ts:76, sole production caller standalone-stack.ts:686
B2 os serve / os dev config-module load	packages/cli/src/commands/serve.ts:2170-2172
B3 os build config-module load	packages/cli/src/commands/compile.ts:211
B4 os migrate — its own second, independent loadConfig	packages/cli/src/utils/schema-migration-plugins.ts:1083
B5 resolve-project-database — its own readFileSync + JSON.parse, a COPY of B1's envelope unwrap	packages/runtime/src/resolve-project-database.ts:193

⚠️ B5 is upstream of every candidate fold — inside createStandaloneStack it runs at :574, 112 lines before loadArtifactBundle at :686, and it is reached independently from os dev (dev.ts:56), os start (start.ts:557) and os db clean (db/clean.ts:46) before any stack exists. A probe that only covers B1 proves nothing about it.

⚠️ The two entry paths share no seam. composeStacks has exactly one call site in this repo and it is user config (examples/app-multi-package/objectstack.config.ts:51); the CLI receives the config already composed at serve.ts:2172, which the artifact never passes through. So the fixture must be driven from both the compiled artifact and from source — covering one is half a pin.

Acceptance

• The pin is green today on the additive shape (it must not require the reader work to pass its baseline).
• The pin is RED today on the option-B shape, and its failure names which subsystem lost which collection. ⛔ A pin that is green on the option-B shape before any reader work has landed is a broken pin, not a passing one — reverse-verify this explicitly and record the red output in the PR.
• As each of cards 2/4, 3/4 and 4/4 lands, the option-B leg goes green one subsystem at a time. The program is done when it is fully green.
• The probe the dev seat already wrote for the enumeration (comment 5523603341: a two-package artifact run through each reader twice, 10 of 12 reader paths non-zero → zero) is the starting point — this card turns that throwaway measurement into a committed pin.

Not in scope

⛔ Do not change any reader. ⛔ Do not change composeStacks or the artifact format. This card adds a fixture and a test only; every production file it touches should be zero.

Blocks: #14512 (the emitter half), and cards 2/4 @objectstack/runtime, 3/4 @objectstack/cli, 4/4 @objectstack/plugin-security.

Related: #14877 exports the artifact envelope's declared top-level key set — if it lands first, the fixture should derive its collection list from that export rather than hand-listing it.

[hotlong]

Claim

Dev seat, session session_01UHvF5hyiZjnCyExFnfQB8m, branch claude/issue-15004-option-b-acceptance-probe (pushed empty as a write-path probe before the first edit).

Worktree: dedicated, off origin/main 33681eaef. Re-read this card's comments before starting — no earlier claim with a different session id exists. The card is unassigned on arrival; per the dispatch contract the assignee field is the PM's to write, so this comment plus the branch is the claim marker.

Read in full first: this card, plus #14512 comments 5523603341 (reader enumeration), 5523741937 (boundary measurement), 5528589044 (maintainer ruling, batch #23) and 5529305298 (the execution comment that filed this card).

Scope as I will hold it: fixture plus test only, zero production files touched, no reader changed, composeStacks and the artifact format untouched. Acceptance is the discriminating pin — green on the additive leg, RED on the option-B leg today, with the red output naming which subsystem lost which collection recorded in the PR body.

---

Generated by Claude Code

[hotlong]

os-dev-report

{
 "issue": 15004,
 "status": "done",
 "branch": "claude/issue-15004-option-b-acceptance-probe",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/15039",
 "premise_still_valid": true,
 "summary": "Built the option-B acceptance pin as three new test files in packages/cli/test — a two-package collection zoo carrying one member of every collection family, an instrument that runs every reader over both shapes, and the pin itself. Zero production files touched; one test-layer tsc config (packages/cli/tsconfig.test.json) gained three paths rules because check:type-source-resolution went red on the pin, and its shrink-only registry may not be widened. Every probe row either calls a reader this repo ships (collectBundleActions / collectBundleHooks / collectBundleFunctionEntries / resolveStandaloneDatabase / createStandaloneStack / appSecurityPluginOptions) or boots a real LiteKernel carrying the real AppPlugin and records what that plugin handed to a subsystem (job schedule, datasource connect, ql.setDatasourceMapping, i18n service, seed-dataset registry) — no row re-implements a read, because such a row would stay red after the reader beside it was fixed. The two shapes are separated by a key set DERIVED from ObjectStackDefinitionSchema intersect AssembledPackageBodySchema rather than hand-listed, so a new collection family joins the probe automatically (#14877 would let it read that set as an export instead). Losses are held in OPTION_B_LOSSES, a shrink-only ledger asserted by set equality: red when a reader is fixed (delete the line), red when one regresses, red when an unenumerated reader arrives, red if the probe measures less. The card arrived unassigned — I did not write the assignee field per the dispatch contract; my claim is comment 5529358729 plus the branch.",
 "tests": "All at e70392ba7 (final commit), gate family derived with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands` against the real 4-path change set and re-derived identical after the tsconfig edit. GREEN LEG: `pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/option-b-reader-acceptance.pin.test.ts` -> `Test Files 1 passed (1) / Tests 6 passed (6)`. RED LEG (reverse verification, the card's acceptance): committed first, then mutated with a trap-restored script using absolute paths — the mutation was CONFIRMED ON DISK before the run (24 ledger lines -> 0, empty-literal occurrences 1, both by grep -c) and the file restored with `git checkout HEAD -- ABSOLUTE_PATH`, proven by an empty `git diff HEAD` and a clean `git status`. With OPTION_B_LOSSES emptied the pin reports 24 subsystems losing their collections across all three scoped packages, while the additive BASELINE, the packages[] anti-vacuity control and three structural tests all pass in that same run (1 failed / 5 passed). Full red output is in the PR body. TYPECHECK: `pnpm --filter @objectstack/cli check:test-typecheck` -> `OK — 3 file(s) / 28 error(s) / 6 pinned signature(s)`, byte for byte the pre-existing test-typecheck-debt.json, so the new paths rules added ZERO diagnostics (the hazard that registry's own notes record from PR #12570). LINT: repo-wide `pnpm lint` (eslint . --no-inline-config) exit 0, no narrowing claimed. GATES: 30 of the 32 derived commands exit 0, including check:type-source-resolution, check:test-source-alias, check:type-check-coverage, check:type-check-debt (218 raw errors, none above its recorded number), check:nul-bytes, check:engine-double-contract, check:published-files, check:cross-package-test-inputs, check:cli-test-child-env and the ten direct-node gates. NOT MEASURED, not reported as passed: scripts/check-test-completeness.mjs exit 3 PREREQUISITE NOT MET (it grades a saved turbo test log only CI produces, and its own text says the family names it with no argument), and pnpm check:dual-build-cjs-loads exit 3 PREREQUISITE NOT MET (reads built output; 12 packages outside this card's build closure have no dist). DECLARED NARROWING: the @objectstack/cli vitest suite was not run whole, only this PR's file — provable rather than hopeful, since the diff only ADDS files and edits a tsc-only config, and vitest does not read tsconfig paths (no vite-tsconfig-paths plugin in packages/cli/vitest.config.ts, untouched here). Every exit code above was captured before any pipe.",
 "mcp_calls": "10 — issue_read get 15004, issue_read get_comments 14512, add_issue_comment (claim), create_pull_request, pull_request_read get 15039, issue_write update (labels), search_issues x2 (positive control first, then the dedup query), issue_write create 15042, add_issue_comment (this report). The card body and the four #14512 comments it rests on were read through the zero-quota public-payload channel where it reaches; the #14512 comment page only preloads 15 of 42 timeline items and offers no zero-quota pagination, so the four comments cost one MCP get_comments call. Container REST is session-gated 403 (`GitHub access is not enabled for this session`, probed repo-scoped at session start), and `gh` is absent — so labels went through MCP with a compare-read-back rather than the additive REST endpoint. Channel switch declared.",
 "open_questions": [
 {
 "question": "The card says the count of production files this PR touches should be zero and to stop rather than widen. It IS zero for production files — but the diff carries one file outside `test/`: packages/cli/tsconfig.test.json gains three `paths` rules. Is that inside the card's intent, or does it want re-homing?",
 "options": [
 "A. Keep it. `check:type-source-resolution` went red because @objectstack/runtime, @objectstack/objectql and @objectstack/plugin-security are newly reached by that tsc program and resolve to dist/index.d.ts. Its registry is shrink-only and the gate's own failure text says `paths` — not a widening — is the fix for a dep exposed through an EXISTING program. The file is the test layer's own program (include test/**/*, noEmit) and tsconfig.build.json does not extend it, so nothing shipped changes. Measured: zero new tsc diagnostics.",
 "B. Move the pin to a package where those three already resolve to source, so no config changes at all. No such package exists: the pin must reach @objectstack/runtime, @objectstack/cli source (lowerCallables) and @objectstack/plugin-security together, and packages/cli is the only one that depends on all three.",
 "C. Drop the rows that need those imports. That removes the runtime and plugin-security halves of the pin, i.e. most of the card."
 ],
 "recommendation": "A. The gate prescribes it by name, the file is test-layer rather than production, the alternative homes do not exist, and the one documented risk of `paths` (billing another package's diagnostics into the consumer's shrink-only ledger, PR #12570) was measured here and is zero. Flagged rather than buried because the card was explicit about the file count."
 },
 {
 "question": "Three enumerated reads are expressions inline inside oclif command bodies and no probe short of running the command reaches them: serve.ts's two `config.objects` auto-registration gates on the FROM-SOURCE path, dev.ts `readArtifactObjects()`, and compile.ts's union authoring-rule run. Should 1/4 have covered them?",
 "options": [
 "A. Leave them to cards 3/4 (#15006) and 4/4, which own those sites and will introduce whatever seam a probe can attach to. The artifact half of the two serve.ts gates IS covered today, through createStandaloneStack's surfaced `objects` — the very key that path exists to drive them with.",
 "B. Cover them now by asserting `config.objects` on the option-B config in the pin.",
 "C. Cover them now by driving the real commands as subprocess e2e tests (the shape build-multi-package-artifact.e2e.test.ts already uses)."
 ],
 "recommendation": "A. B is the re-implementation trap the pin's header forbids — a row shaped like the read it watches stays red after that read is fixed, and a gate that cannot go green gets deleted. C is honest but buys three rows for a per-shape `os build` subprocess in the repo's largest suite, and the sites belong to cards that will create a callable seam anyway. The boundary is named in the test file's header and in the PR so it cannot be mistaken for coverage."
 }
 ],
 "out_of_scope_findings": [
 "filed as #15042: @objectstack/service-cluster's dist/*.d.ts vanished AFTER its own build printed `check-dts-emitted: 3/3 declared declaration file(s) present`, with no rebuild and no rm in between — a later tsc reported TS7016 against runtime.ts, and the quiet direction of the same state is a suite passing green against `any`. Cause NOT established and stated as such; the known tsup array-config race is explicitly guarded against in that package's own config (#13013), and no other package in the tree showed the shape. Dedup search ran with a positive control first."
 ]
}

---

Generated by Claude Code

[zhuangjianguo]

ACCEPT — PR #15039, driven to the queue

Reviewer of record: PM seat, maintainer direct-dispatch channel (maintainer asked this session to assess the open PR set and land what is landable, live chat 2026-09-04). Readings taken against GitHub at 2026-09-04T04:40Z, PR head e70392ba79460773d3e59b0a31446c8510b11263.

Checklist

Item	Reading
PR shape	non-draft, base main, first line Fixes #15004, mergeable_state: clean
Path surface (get_files)	4 files — packages/cli/test/fixtures/option-b-collection-zoo.ts, packages/cli/test/fixtures/option-b-reader-probe.ts, packages/cli/test/option-b-reader-acceptance.pin.test.ts, packages/cli/tsconfig.test.json. No governed path; zero production files
Clause ②	path limb not hit (no packages/spec/src/**); the diff cannot change accept/reject behaviour or widen a public surface — it adds a test and a noEmit tsc config
Checks	38 check runs, all completed, zero failure; Governed Surface Queue Guard green
Changeset	skip-changeset applied and correct — packages/cli's files field ships dist and bin; every path here is under test/ or is a noEmit config

Spot-checks against the diff

• The card's acceptance was that the option-B leg is red today, and the PR carries the reverse-verification: 24 rows red with OPTION_B_LOSSES emptied on origin/main 33681eaef, with the additive BASELINE, the packages[] anti-vacuity control and the shape-derivation test all passing in that same run. That is what makes the red a discrimination rather than a broken fixture — the check I care about most on a ledgered-red pin, and it is supplied.
• The ledger is asserted by set equality, not toBe(0), so a fixed reader goes red naming the line to delete and a new unenumerated reader goes red on arrival. That is the card's actual deliverable.
• The functions row asserts the value (effect), not a count — a correction to the enumeration that a presence-check would have missed, since mergeRuntimeModule re-supplies the callable and normalizeFlowFunctionEntry silently defaults a declared writer to pure.
• The three paths rules in tsconfig.test.json are star-less exact matches; check:test-typecheck reports 3 file(s) / 28 error(s) / 6 pinned signature(s) — byte-identical to the pre-existing test-typecheck-debt.json. Zero new diagnostics, so the paths addition bills nothing to this package's ledger.

Declared and accepted

• The @objectstack/cli suite was not run whole; the narrowing is argued from the diff (three added files plus a tsc-only config, and packages/cli/vitest.config.ts carries no vite-tsconfig-paths, so no existing test's resolution moves). CI runs the suite regardless and is green.
• Two gates NOT MEASURED locally with self-declared unmet prerequisites; both CI-owned.

Verdict: ACCEPT → ready, auto-merge armed, queue owns it from here. Tracking to MERGED. OPTION_B_LOSSES stands at 24 lines for #15005 / #15006 / #15007 to shrink.

---

Generated by Claude Code