fix(spec): registry array survives the field.zod ↔ suggestions.zod ↔ strict-object import cycle under eager schemas

DECLARATIONS moved from a module-level const (TDZ at import time when the
cycle enters through the automation barrel — an ordering #5593's migration
itself introduced) to a hoisted function-owned store, the same property
flowNodeObject() relies on (#4415). Pinned from both sides; the eager
reproduction path is gen:schema (OS_EAGER_SCHEMAS=1).

Recovery commit: the dev agent was killed by a container restart during
its final verification run; verification re-run to completion by the PM —
gen:schema eager pass, targeted cycle tests 36/36, full spec suite
342 files / 8768 tests green.

Author: claude

packages/spec/src/shared/strict-object.test.ts

@@ -1,5 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
+import { execFileSync } from 'node:child_process';
+
 import { z } from 'zod';
 import { describe, expect, it } from 'vitest';
 
@@ -350,3 +352,47 @@ describe('strictObject — the error map is lazy, so cycles cannot break it', ()
     expect(aliasesRead).toBe(1);
   });
 });
+
+// ============================================================================
+// #5593 — this module survives being entered FIRST in its own import cycle.
+//
+// `strictObject` is called at MODULE SCOPE by schemas that sit inside the
+// `field.zod` ↔ `suggestions.zod` ↔ `strict-object` cycle, so under
+// `OS_EAGER_SCHEMAS=1` it can run while this module is still initializing.
+// Everything it touches on the way in must therefore be reachable from the
+// first instruction of module evaluation — which rules out a module-level
+// `const` for the declaration registry, and is why `declarationStore()` is a
+// hoisted `function` declaration.
+//
+// ⚠️ Why this needs its own subprocess rather than an ordinary assertion:
+// `lazySchema` defers construction behind a Proxy, so a normal `vitest run`
+// never evaluates a schema at import time and the hazard is invisible. #5593
+// shipped the regression and the ordinary suite stayed green — what caught it
+// was CI's `check-test-completeness` gate noticing that
+// `automation/flow-region-cycle.test.ts` was counted and never reported,
+// because ITS subprocess died at import with `ReferenceError: Cannot access
+// 'DECLARATIONS' before initialization` and vitest could not even format the
+// stack. Two guards, one hazard: that file states the cycle it protects
+// (#4415), this one states the rule this module has to keep.
+//
+// The entry point is deliberately `data/field.zod.ts` — the module whose
+// own module-scope `strictObject(…)` call is the one that lands here
+// mid-initialization — reached through a module that pulls THIS file first.
+// ============================================================================
+describe('#5593 — eager construction with this module entered first', () => {
+  it('does not throw at import time under OS_EAGER_SCHEMAS=1', () => {
+    const barrel = new URL('../automation/index.ts', import.meta.url).href;
+    const run = (): string =>
+      execFileSync(
+        process.execPath,
+        ['--import', 'tsx', '--input-type=module', '-e',
+          `import ${JSON.stringify(barrel)};
+           console.log('ok');`],
+        { env: { ...process.env, OS_EAGER_SCHEMAS: '1' }, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+      ).trim();
+    expect(
+      run(),
+      'a module-level `const` in strict-object.ts is in its TDZ here — use a hoisted function',
+    ).toBe('ok');
+  }, 60_000);
+});

packages/spec/src/shared/strict-object.ts

@@ -163,7 +163,41 @@ export interface StrictObjectDeclaration {
   readonly shape: z.ZodRawShape;
 }
 
-const DECLARATIONS: StrictObjectDeclaration[] = [];
+/**
+ * The registry array, owned by a HOISTED function declaration.
+ *
+ * ⚠️ **Deliberately not a module-level `const`, and this is load-bearing.**
+ * `strictObject` is called at MODULE SCOPE by schemas that sit inside the
+ * `field.zod` ↔ `suggestions.zod` ↔ this module import cycle, so under
+ * `OS_EAGER_SCHEMAS=1` it can run while this module is still initializing. A
+ * `const` is in its temporal dead zone until its own line executes, so the call
+ * throws `ReferenceError: Cannot access 'DECLARATIONS' before initialization`
+ * at IMPORT time — before a single test body runs. A hoisted `function`
+ * declaration is fully initialized from the first instruction of module
+ * evaluation, which is the same property `automation/flow.zod.ts`'s
+ * `flowNodeObject()` relies on for its own cycle (#4415, and its docblock says
+ * so out loud).
+ *
+ * Measured, not assumed. On `main` the cycle happened to be entered through
+ * `field.zod` first, which resolves this module fully before anything calls
+ * into it. #5593 moved `automation/`'s schemas from `strictUnknownKeyError` to
+ * this helper, and that one edge reordered the entry: the `automation` barrel
+ * now reaches THIS module first, then `suggestions.zod`, then `field.zod`,
+ * whose own module-scope `strictObject(…)` call lands here mid-initialization.
+ *
+ * ⚠️ The failure mode is why this is written down rather than left to the
+ * types. `lazySchema` defers construction behind a Proxy, so an ordinary
+ * `vitest run` never evaluates a schema at import time and stays GREEN; the
+ * eager subprocess dies before any test body runs, and vitest cannot even
+ * format the stack, so the owning file reports *no result at all*. What caught
+ * it was CI's `check-test-completeness` gate noticing that
+ * `automation/flow-region-cycle.test.ts` was counted and never reported. Pinned
+ * from this side too, in `strict-object.test.ts`.
+ */
+function declarationStore(): StrictObjectDeclaration[] {
+  const self = declarationStore as unknown as { list?: StrictObjectDeclaration[] };
+  return (self.list ??= []);
+}
 
 /**
  * Every authoring shape {@link strictObject} has built **so far in this
@@ -187,7 +221,7 @@ const DECLARATIONS: StrictObjectDeclaration[] = [];
  * nothing judges, and that must fail loudly rather than pass quietly.
  */
 export function strictObjectDeclarations(): readonly StrictObjectDeclaration[] {
-  return DECLARATIONS;
+  return declarationStore();
 }
 
 /**
@@ -251,7 +285,7 @@ export function strictObject<T extends z.ZodRawShape>(options: StrictObjectOptio
     }))(issue);
   };
 
-  DECLARATIONS.push({ options, shape });
+  declarationStore().push({ options, shape });
 
   return z.object(shape, { error }).strict();
 }