docs(spec): the control-flow test's comment and describe title state the two-seam division

[os-bill]

Part of #17384

Prose only, inside one test file. No assertion, no test data and no test behaviour changed.

What was false

packages/spec/src/automation/control-flow.test.ts restated the retired sentences in two places — a block comment and a describe title, the half that reaches a test report and a grep:

• describe('[#4001] validateControlFlow and the key gate do not fight', …)
• the comment above it: "It does not, and the reason is that they answer different questions … They meet at exactly one seam"

Both halves were falsified by the ruling that landed as 21aabbc7be: FlowSchema's superRefine refuses a duplicate node id over one node-id space spanning the top-level nodes[] and every region body, so the schema decides a structural fact too, and the clean key-versus-structure division the comment drew is exactly what that ruling removed.

What it says now

The block and the title follow the canonical control-flow.zod.ts docblock as it was left by c3ce76c210 rather than restating the boundary independently: the two are no longer disjoint, they meet at two seams, and the cases in this block pin the region-slot seam only. The other seam's hand-off at MAX_REGION_DEPTH (32) is named as pinned by flow.test.ts's the seam at MAX_REGION_DEPTH case, so the reader is sent to that pin instead of to a third hand-written restatement. Named artefacts only — a landed commit and a test — no schedule.

New title: describe('[#4001] validateControlFlow and the key gate meet at the region-slot seam', …)

Falsified first, on origin/main at 6465cc0a7c

Prerequisite	Reading, anchored by content
the retirement landed	control-flow.zod.ts docblock carries "The two are no longer disjoint" and "They meet at two seams" (c3ce76c210)
the ledger correction landed	docs/audits/2026-07-unknown-key-strictness-ledger.md row carries the same two sentences (2bafbfdca9)
the restatements survived	both spellings present in control-flow.test.ts, located by content, not by line

Census — probed on the CLAIM, not on one spelling

The standing instruction that surfaced this card, reused. Instrument: whole tree at 6465cc0a7c, read from a clean worktree with no dist/ and no node_modules present (so the census is reproducible), each file whitespace-flattened after stripping a leading block-comment marker per line, occurrences counted with a regex findall (not grep -c, which counts lines).

Scoped to the 22 tracked files that name the claim's subject validateControlFlow:

Probe	Before	After
do/does not fight	1 — only control-flow.test.ts	0
exactly one seam	1 — only control-flow.test.ts	0
answer different questions	1 in control-flow.test.ts	0
two seams (the correct sentence)	7, incl. the zod docblock, the ledger, the generated reference page	+1 in control-flow.test.ts
LIT validateControlFlow	22 files / 15 hits in the target file	15
DARK zzqq-not-a-term	0	0

In-file census: 3 distinct false assertions, not the 2 the card names — the third is "It does not, and the reason is that they answer different questions", which asserts the very disjointness the ruling removed. All three are corrected.

Tree-wide: 1 file carried the claim in hand-written prose, and it is this one. Every other live restatement is already correct (control-flow.zod.ts, the strictness ledger, the generated control-flow.mdx). packages/spec/CHANGELOG.md carries the old wording in the past tense and is RELEASE-OWNED — deliberately untouched.

Broad single-spelling probes were run too and are reported as not claim-specific: disjoint fires 306 times tree-wide and answer different questions 72 times, almost all unrelated. The three other do not fight hits in the tree were read and are about other subjects.

Proof that no assertion moved

A comparator drops every whole-line // comment and normalises the one corrected describe title line, then hashes the rest:

HEAD non-prose sha256: cb3b44848782d5731017ec97fa56e0a9cfce0ce65b48c4dd16164f70909d983f
WORK non-prose sha256: cb3b44848782d5731017ec97fa56e0a9cfce0ce65b48c4dd16164f70909d983f
IDENTICAL
  it( : HEAD=45  WORK=45     expect( : HEAD=104  WORK=104
  .toThrow : HEAD=17  WORK=17   safeParse : HEAD=14  WORK=14   describe( : HEAD=10  WORK=10

Lit control for the comparator: the same run over a scratch copy with one assertion flipped from toBe(false) to toBe(true) reports DIFFERENT and exits 1 — so IDENTICAL is a reading, not an instrument that cannot fail.

Verification

• pnpm --filter '@objectstack/spec^...' build — empty by construction: No projects matched the filters. packages/spec has no workspace dependencies, so leg 1 is reported as an empty run, not as a green.
• pnpm --filter @objectstack/spec build — VERDICT command-exit 0; working tree still shows only the one edited file, so no generated artifact moved.
• pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/automation/control-flow.test.ts — VERDICT command-exit 0, Test Files 1 passed (1), Tests 45 passed (45).
• pnpm --filter @objectstack/spec test — VERDICT command-exit 0, Test Files 473 passed (473), Tests 13432 passed (13432).
• pnpm --filter @objectstack/spec typecheck — VERDICT command-exit 0. Its third leg check:test-typecheck compiles the test layer explicitly, so the edited .test.ts is inside the type-checked program rather than excluded from it.
• Derived gate families, run and green (exit captured before any pipe): check:nul-bytes · check-spec-docblock-symbol-anchors · check-comment-mask-adoption · check-comment-mask-corpus · check-keyed-text-bounds · check:test-source-alias · check:cross-package-test-inputs · check:tier-file-adoption · check-closing-keyword-parity · check-changeset-no-major --base origin/main · check-adr-0087-registration --base origin/main · check:published-files · check:type-check-coverage · spec's check:docs / check:api-surface / check:authorable-surface / check:strictness-ledger.
• NOT MEASURED: pnpm check:type-check-debt exits 3 — PREREQUISITE NOT MET, its --re-measure leg needs the whole packages/* closure built and says in its own words that this is "NOT a pass and NOT a finding". Declared as a narrowing, not read as a green; CI builds that closure.
• pnpm check:nul-bytes, plus a direct control-character sweep of the edited file: no hits.
• Full-farm check:* is CI's. scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derives 76 runnable commands from this one-path change set; the local face above is the affected package plus the families that actually read a test file, a comment or a changeset. Leg 1 of the standard face is empty by construction (no workspace dependencies), and the rest is declared to CI.

Changeset

skip-changeset, applied as a label. The rule used is AGENTS.md → Post-Task Checklist §3: a changeset is owed for anything that publishes, and skip-changeset "is for a diff that publishes nothing from any released package."

Measured rather than assumed, with a positive control:

• npm pack --dry-run --json in packages/spec resolves files[] to 2011 shipped paths. src/automation/control-flow.test.ts is not one of them; zero *.test.ts / *.spec.ts files ship at all.
• Positive control: the sibling src/automation/control-flow.zod.ts is in that list (it matches the src/**/*.zod.ts entry), so the reading is an instrument that fires.
• After a real build, the corrected title text reads 0 occurrences across dist/, json-schema/, api-surface/, liveness/, prompts/, llms.txt; the canonical sentence They meet at two seams — the positive control — reads 3 (dist/automation/index.d.mts, dist/automation/index.d.ts, src/automation/control-flow.zod.ts).

Gate declarations

• Clause-②: no

The commit message carries no card relation of any kind — the relation is declared once, here in the body. Greps over the stored message: Part of, Part-of, Refs, Fixes, Closes, Resolves, Fix, Close, Resolve and bare #NNNNN each 0; lit controls Co-Authored-By and Claude-Session each 1. scripts/check-partof-closing-keyword.mjs was then run two-legged against this branch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH

---

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 88a933088e93067b4df4b20380ab9a1ceed2ed17 → packageMentionDocs.