docs(metadata-protocol): re-point the seed-exemption falsification instruction at its proven lever

[huangyiirene]

Fixes #17938

Clause-②: no

Comment-only repair of a runnable falsification instruction in
packages/metadata-protocol/src/seed-loader-state-machine-exempt.test.ts. One file, +12/-2,
all of it inside the file's leading block comment. No assertion changed, no behaviour changed.

The stale instruction

The comment told a future debugger: "Revert the seedReplay flag in SEED_OPTIONS and both
cases below go red". SEED_OPTIONS is now { context: SEED_WRITE_EXECUTION_CONTEXT }
(seed-loader.ts:2112, imported at :17 from @objectstack/spec/kernel), so there is no
seedReplay inside SEED_OPTIONS left to revert. The procedure is not wrong, it moved — and
the natural next move, "this comment is stale, ignore it", discards a correct falsification
procedure that still works at a different address.

Which lever — measured, not read

packages/spec/src/kernel/execution-context.zod.ts holds two plausible candidates, and the card
did not disambiguate them. Both were ablated, each leg rebuilding @objectstack/spec and proving
on disk that the mutation reached dist/ before its colour was read — this suite has no vitest
alias for that dep, so it resolves it through the export map, i.e. through dist/.

leg	edit	dist proof	the two cases
A — the VALUE	delete seedReplay: true from SEED_WRITE_EXECUTION_CONTEXT (:519)	marker seedReplay: true absent from all 216 built files	2 failed (exit 1)
B — the SCHEMA FIELD	make seedReplay: z.boolean().optional() (:393) required	marker seedReplay: z.boolean().optional() absent from all 216 built files	2 passed (exit 0)

Leg A failures, both cases, as the comment now promises:

FAIL  ... > inserts every mid-lifecycle row on a fresh DB (no initialStates rejection)
AssertionError: expected false to be true       (result.success, line 171)
FAIL  ... > threads seedReplay into every project write (the flag the engine keys off)
AssertionError: expected undefined to be true   (call[2]?.context?.seedReplay, line 201)
Test Files  1 failed (1) · Tests  2 failed (2)

Leg B, same rebuild discipline, same two cases:

Test Files  1 passed (1) · Tests  2 passed (2)

So the schema field is a decoy: it governs what is ACCEPTED, not what the loader SENDS. A
falsification instruction naming it would be worse than the stale one it replaces — a debugger
flips a .optional(), nothing happens, and the vacuous pass reads as a completed falsification.
The new comment therefore names the VALUE, names the rebuild step, and names the schema field as
the decoy it was measured to be.

Both legs restored from HEAD and verified by blob hash plus a whole-tree git status --porcelain, and @objectstack/spec was rebuilt on the restore leg with the marker proven back
in dist/, so nothing of either ablation survives in this tree or in the built artifacts.

Verification

Taken at 8a4d82c833, which is this branch's final head.

• Gate reconciliation — dispatch-gates.mjs --repo objectstack-ai/objectstack --ran:
  51 derived, 48 run, 3 NOT-MEASURED, 0 UNRUN. 47 of the 48 exited 0.
  • The 3 NOT-MEASURED are check:dual-build-cjs-loads, check:lean-entry-closure and
    check:type-check-debt, each exit 3 = PREREQUISITE NOT MET (they read built output of the
    whole repo; a full pnpm build is CI's run, not this card's).
  • The 1 non-zero is check:cross-package-test-inputs (exit 1). It is the known gate defect
    [finding] check:cross-package-test-inputs exits 0 or 1 on the same commit depending on whether a dist/ exists — and lint.yml runs it with no build ahead of it, so CI only ever sees the blind leg #18621 — its verdict follows build state, not this diff: it names
    packages/cli/test/init-created-files-summary.e2e.test.ts descending into
    packages/spec/dist/, and this diff's only path appears nowhere in its output.
• pnpm --filter @objectstack/metadata-protocol typecheck — exit 0. tsc --listFiles confirms
  the edited file is one of the 744 files in that program, so the green covers it.
• pnpm --filter @objectstack/metadata-protocol test — exit 0. 178 files passed / 3 skipped,
  2548 tests passed / 19 skipped.
• pnpm lint (eslint . --no-inline-config) — exit 0, whole repo, 110s. No narrowing was needed,
  so no narrowing is claimed.
• The derivation is stale against origin/main by 3 commits (scripts/pm/check-widening-tells.mjs
  moved in that range). The count above is the reading at this branch's head, stated as such.

Changeset

None — skip-changeset, measured rather than assumed. @objectstack/metadata-protocol's
files[] is ["dist", "README.md", "CHANGELOG.md"]. After building the package, enforceInitialStates
— a symbol unique to the edited test file — has zero hits across all three, while the positive
control SeedLoaderService is present in 5 built files. Nothing that ships moves.

Acceptance notes

Out-of-scope findings from this round, none of them class (a)/(b)/(c), so none filed:

• noted, not filed: seed-loader.ts:866 and :2223 read SeedLoaderService.SEED_OPTIONS as any,
  erasing the ExecutionContext typing the constant carries at its declaration. Nothing is wrong
  at runtime and no declared contract is violated, so this is an observation, not a defect.
  Who would meet it: the next PR that touches the loader's write path. Nothing is queued on it
  today.
• noted, not filed: the retained tail "4 of 5 rows rejected" is not directly witnessed by the leg A
  output, because case 1 fails on result.success before it reaches any row count. It is correct
  by construction of the fixture (1 of the 5 seed rows is born planned, which is the only member
  of initialStates), so it was kept unchanged rather than re-derived. Who would meet it: whoever
  next runs the procedure. It will hold for them.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 17005ccbe6a344b24b9447fcb4e94e8cc11d53ed → packageMentionDocs.