From 50221c8e8c7cce0d71d71dc4c0b2a1396ed8b6d5 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 11 Sep 2026 14:28:43 +0000 Subject: [PATCH] docs(spec): the control-flow test's comment and describe title state the two-seam division The block comment and the `describe` title both said `validateControlFlow` and the key gate "do not fight" and "meet at exactly one seam". A landed ruling (commit `21aabbc7b`) made both false: `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. Both now follow the canonical `control-flow.zod.ts` docblock (`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 pinned by `flow.test.ts`'s `the seam at MAX_REGION_DEPTH` case, named here so a reader is sent to that pin instead of to a third hand-written restatement. Prose only. No assertion, no test data and no test behaviour moved: with whole-line comments and the one corrected `describe` title normalised away, the file's remaining bytes hash identical to the base commit's, and the suite still reports 45 passing cases. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH --- .../spec/src/automation/control-flow.test.ts | 30 +++++++++++++------ 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/packages/spec/src/automation/control-flow.test.ts b/packages/spec/src/automation/control-flow.test.ts index 5164d5828e..131ed69779 100644 --- a/packages/spec/src/automation/control-flow.test.ts +++ b/packages/spec/src/automation/control-flow.test.ts @@ -471,15 +471,27 @@ describe('TryCatchErrorValueSchema', () => { // the key gate collide with `validateControlFlow`, which has validated these // same regions structurally since ADR-0031? // -// It does not, and the reason is that they answer different questions. The -// schema rejects undeclared KEYS; the analysis rejects malformed STRUCTURE -// (single-entry / single-exit / acyclic), which no key check can decide. They -// meet at exactly one seam — `validateControlFlow` `safeParse`s each region -// slot before analyzing it, so from #4001 that parse is also where an -// undeclared region key surfaces. Nothing was duplicated and nothing was -// removed: the guard's structural prose is untouched, and it simply stopped -// silently repairing its own input before judging it. -describe('[#4001] validateControlFlow and the key gate do not fight', () => { +// The two are no longer disjoint, and since #16134 that is deliberate: the +// schema rejects undeclared KEYS *and* one structural fact — a duplicate node +// id — while the analysis rejects malformed STRUCTURE (single-entry / +// single-exit / acyclic), which no key check can decide. They meet at two +// seams. The canonical statement of that division is the `control-flow.zod.ts` +// docblock as #16835 left it (`c3ce76c210`); this block follows it rather than +// restating the boundary independently. +// +// The cases below pin the **#4001** seam only: `validateControlFlow` +// `safeParse`s each region slot before analyzing it, so that parse is also +// where a region's undeclared key surfaces. That seam duplicated nothing and +// removed nothing — the guard's structural prose is untouched, and it simply +// stopped silently repairing its own input before judging it. +// +// The **#16134** seam is pinned elsewhere: `FlowSchema`'s `superRefine` holds +// ONE node-id space across the top-level `nodes[]` and every region body, +// judged at every depth `collectFlowGraphs` walks, and past +// `MAX_REGION_DEPTH` (32) `analyzeRegion`'s own `duplicate node id` line is +// the only refusal of a within-region duplicate. `flow.test.ts`'s +// `the seam at MAX_REGION_DEPTH` case pins that hand-off. +describe('[#4001] validateControlFlow and the key gate meet at the region-slot seam', () => { const flowWith = (cfg: Record, type = LOOP_NODE_TYPE) => ({ nodes: [{ ...node('c1', type), config: cfg }] } as never);