[Vivswan]

Before

// src/sections/shared/snapshot-helpers.ts, one of four walkers reaching into zod's private internals
const def = defOf(schema);          // (schema as unknown as { _zod: { def: ZodDef } })._zod.def
switch (def.type) {
  case "optional": case "nullable": case "default":
    return project(def.innerType as z.ZodType, live);
  // ...
  default:
    if (!LEAF_TYPES.has(def.type)) throw new Error(`BUG: projectOntoSchema(): unhandled schema type ...`);

After

// every reader goes through one adapter over zod's public .def
const node = schemaNode(schema);
switch (node.kind) {
  case "wrapper": return project(node.inner, live);
  // ...
  case "leaf": return live;
}

How

• One adapter, schemaNode(), maps every schema into a closed union (object, array, record, wrapper, union, leaf) from zod's public .def and class checks; the one unhandled-type invariant and the one leaf whitelist live there.
• Four walkers fold onto it: snapshot projection, the replace sweep, canonical ordering, and loosen(), which now writes through public z.clone with a typed def.
• Four test-side walkers and the schema generator read the adapter too, so no private access remains anywhere in the repository.
• Behavior unchanged: the published schema is byte-identical and every existing expectation holds; one BUG message string moved to the adapter's wording.

Proof

• Census: _zod references 6 to 0 across source, scripts, and tests.
• Tests: 2174 green across the engine, sections, slices, and e2e oracle suites; scripts and lint 367; the full e2e run 370 of 370.
• Gates: typecheck, biome, both lint plugins, lint:arch, knip clean; the cross-model review converged.

Technical details

• Step 4 of the zod public-API plan, built on step 1 (refactor(sections): gate every schema rule with zod's when instead of cloning its checks #440, merged) and restacked onto main; step 2 (knob routing by typed options) and step 3 (open() replacing loosen()) follow.
• Line accounting: source +211 -172, tests +134 -182, scripts +4 -8: the adapter and its header replace four walkers and two whitelists.
• Deliberate readings: the adapter looks through prefault, catch, nonoptional, and readonly wrappers too, since an existing list-section test draws through .catch() and the old walkers disagreed on them; open means a catchall is declared and not never, which every old walker tested; the unreachable "int" leaf entry is dropped (z.int().type is "number"), with the slice walk census in the commit body.
• One direct downcast from zod's core supertype to the classic type, because zod's generics type every child as the core supertype; no cast through unknown.
• Recorded, not built: an instanceof check plus BUG in place of that downcast; refusing non-classic toJSONSchema callbacks instead of the generator override's null arm.
• Files: src/sections/shared/{schema-node,snapshot-helpers,schema-helpers}.ts, src/engine/canonical.ts, src/sections/contract/module.ts, .github/scripts/gen-settings-schema.ts, test/{engine/canonical,schema-slices,sections/raw-sibling,sections/loosen}.test.ts, test/e2e/gen-support.ts.

[github-actions]

File size check

0 over a hard cap (fails), 33 warning(s).

File	Size	Tier	Cap
.github/actions/setup/action.yml:7	169 chars	warn	150
.github/scripts/gen-inputs-table.ts:54	11 comment lines	warn	10
.github/scripts/generated.ts:28	191 chars	warn	150
.github/scripts/release-pipeline.ts:7	156 chars	warn	150
.github/scripts/release-pipeline.ts:458	151 chars	warn	150
.github/scripts/release-pipeline.ts:1252	153 chars	warn	150
.github/scripts/release-pipeline.ts:1	35 comment lines (header)	warn	25
.github/scripts/release-pipeline.ts:454	14 comment lines	warn	10
.github/workflows/post-green.yml:29	153 chars	warn	150
.github/workflows/update-release-pr.yml:110	14 comment lines	warn	10
docs/upgrading/v2-to-v3.md	1276 lines	warn	1040
src/engine/layers.ts:75	157 chars	warn	150
src/engine/layers.ts:95	167 chars	warn	150
src/flows/settings-write.ts:137	159 chars	warn	150
src/github/secret-scan.ts:43	11 comment lines	warn	10
src/schema.ts:186	153 chars	warn	150
src/schema.ts:197	176 chars	warn	150
src/sections/contract/errors.ts:14	14 comment lines	warn	10
src/sections/secret_scanning_custom_patterns/compilable-form.ts:382	161 chars	warn	150
src/sections/shared/roles.ts:43	13 comment lines	warn	10
src/sections/shared/schema-helpers.ts:12	153 chars	warn	150
src/types.ts:16	156 chars	warn	150
test/docs/guides.test.ts:451	155 chars	warn	150
test/docs/nightly-workflows.test.ts:206	160 chars	warn	150
test/e2e/constants.ts:9	197 chars	warn	150
test/e2e/generators.ts	2634 lines	warn	2560
test/e2e/generators.ts:1704	166 chars	warn	150
test/e2e/generators.ts:1858	161 chars	warn	150
test/e2e/generators.ts:1667	12 comment lines	warn	10
test/engine/execute.test.ts:617	152 chars	warn	150
test/flows/merge-parity.test.ts:63	164 chars	warn	150
test/scripts/auto-fix-allowlist.test.ts:12	12 comment lines	warn	10
test/sections/refusal-messages.test.ts:61	19 comment lines	warn	10

Split the file, wrap the line, shorten or exempt the comment, or list the path in .file-size-allow.local with a # reason.

5 managed file(s) skipped; repo-platform owns them.

[Copilot]

Copilot review overview

🟢 Approval recommended

The adapter migration is consistent across production, generation, and test paths with no unresolved defects found.

Review effort: Balanced
Findings: None

What changed in this PR

Centralizes Zod schema traversal behind the public schemaNode() adapter while preserving schema generation and runtime behavior.

Changes:

• Adds a closed schema-node representation.
• Migrates projection, canonicalization, loosening, generation, and test walkers.
• Removes private _zod access.

File	Description
.github/​scripts/​gen-settings-schema.ts	Uses the adapter during JSON Schema generation.
src/​engine/​canonical.ts	Migrates canonical traversal.
src/​sections/​contract/​module.ts	Reworks loosen() around public cloning.
src/​sections/​shared/​schema-helpers.ts	Updates adapter-related documentation.
src/​sections/​shared/​schema-node.ts	Adds the centralized schema adapter.
src/​sections/​shared/​snapshot-helpers.ts	Migrates projection and replace-sweep traversal.
test/​e2e/​gen-support.ts	Migrates slice-based generators.
test/​engine/​canonical.test.ts	Migrates canonical schema census helpers.
test/​schema-slices.test.ts	Validates slice composition through the adapter.
test/​sections/​loosen.test.ts	Updates the centralized invariant expectation.
test/​sections/​raw-sibling.test.ts	Migrates raw-sibling schema walkers.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.