@githolon/dsl 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -19,6 +19,8 @@
     "./manifest": "./src/manifest.ts",
     "./compose": "./src/compose.ts",
     "./usd": "./src/usd.ts",
+    "./usd-layers": "./src/usd_layers.ts",
+    "./usd-state": "./src/usd_state.ts",
     "./engine-entry": "./src/engine_entry.ts",
     "./build-package": "./src/build_package.ts",
     "./compile-engine": "./src/compile_engine.ts",

package/src/codegen_proof.ts

@@ -0,0 +1,430 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * GENERATED PROOF CODEGEN — `build/<name>.proof.mts`, the runnable e2e SYNTHESIZED
+ * FROM THE LAW ITSELF (the field-test-6 ask: reshaping the domain meant rewriting
+ * test/e2e.mts by hand; now the proof reshapes itself on every compile).
+ *
+ * `generateTsProof(modules, opts)` reads the domain's ACTUAL directives / queries /
+ * counts (the same composed modules every other emitter sees) and emits a
+ * domain-shaped live proof:
+ *
+ *   throwaway workspace → deploy `build/<name>.deploy.json` → connect via the
+ *   GENERATED typed client → fetch-TRAPPED offline dispatch of the first `.creates`
+ *   directive (payload synthesized from its zod schema) → first declared query +
+ *   first count answered LOCALLY → sync (edge admission) → the CLOUD answers →
+ *   two-client AddWins concurrency (when the law has the shape for it) →
+ *   convergence → ALL GREEN.
+ *
+ * Payload SYNTHESIS rules ({@link synthesizePayload}): string → `"sample-<field>"`,
+ * enum → its first option, number → 1, boolean → true, array of string →
+ * `["sample-a"]`, literal → its value, `.optional()`/`.default()` → omitted,
+ * required `…At` strings → omitted (the generated client auto-stamps ISO now() at
+ * dispatch — the same {@link autoStampFields} convention codegen_ts types by).
+ * NO FALLBACK: a shape the synthesizer can't sample throws, naming the field and
+ * the remedy — the compile then SKIPS the proof (the law still ships) and says why.
+ *
+ * Deterministic codegen: the emitted bytes are a pure function of the modules +
+ * package name + domain hash — no timestamps, no randomness (the proof picks its
+ * throwaway workspace name at RUN time, not at generation time).
+ */
+import type { z } from "zod";
+
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
+import type { Directive } from "./directive.js";
+import type { DomainModule } from "./codegen_dart.js";
+import type { QueryDecl } from "./query.js";
+import { finishCount } from "./count.js";
+import {
+  autoStampFields,
+  tsClientFactoryName,
+  tsHashConstName,
+  zodArrayElement,
+  zodDef,
+  zodEnumValues,
+  zodKind,
+  zodObjectShape,
+} from "./codegen_ts.js";
+
+const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
+const lcFirst = (s: string) => (s.length ? s[0]!.toLowerCase() + s.slice(1) : s);
+
+// ── payload synthesis (the sample-value sibling of codegen_ts's type walker) ──────
+
+export interface SynthesizedPayload {
+  /** The literal the proof dispatches. Auto-stamped `…At` fields are OMITTED here. */
+  readonly value: Record<string, unknown>;
+  /** Required `…At` string fields deliberately omitted — the generated client stamps ISO now() at dispatch. */
+  readonly autoStamped: readonly string[];
+}
+
+/** One sample value for one zod shape. NO FALLBACK: an unhandled shape throws, naming its remedy. */
+function sampleOfZod(zt: z.ZodTypeAny, field: string, where: string): unknown {
+  switch (zodKind(zt)) {
+    case "string":
+      return `sample-${field}`;
+    case "number":
+      return 1;
+    case "boolean":
+      return true;
+    case "enum":
+      return zodEnumValues(zt)[0];
+    case "literal": {
+      const def = zodDef(zt);
+      return def.value !== undefined ? def.value : def.values?.[0];
+    }
+    case "array": {
+      const el = zodArrayElement(zt);
+      return zodKind(el) === "string" ? ["sample-a"] : [sampleOfZod(el, field, where)];
+    }
+    case "object": {
+      const out: Record<string, unknown> = {};
+      for (const [name, raw] of Object.entries(zodObjectShape(zt))) {
+        const k = zodKind(raw as z.ZodTypeAny);
+        if (k === "optional" || k === "default") continue; // optional → omit
+        out[name] = sampleOfZod(raw as z.ZodTypeAny, name, where);
+      }
+      return out;
+    }
+    case "record":
+      return {};
+    case "nullable":
+    case "optional":
+    case "default":
+      return sampleOfZod(zodDef(zt).innerType!, field, where);
+    case "union": {
+      const first = zodDef(zt).options?.[0];
+      if (first !== undefined) return sampleOfZod(first, field, where);
+      throw new Error(`codegen-proof: empty union at field '${field}' of ${where}`);
+    }
+    default:
+      throw new Error(
+        `codegen-proof: cannot synthesize a sample for zod shape '${zodKind(zt)}' (field '${field}' of ${where}) — reshape the payload to a sampleable type, or prove that directive by hand in test/e2e.mts`,
+      );
+  }
+}
+
+/**
+ * Synthesize a dispatchable sample payload from a directive's zod object schema:
+ * optional/defaulted fields omitted, required `…At` strings omitted (auto-stamped
+ * by the generated client), everything else sampled by {@link sampleOfZod}.
+ */
+export function synthesizePayload(schema: z.ZodTypeAny, where: string): SynthesizedPayload {
+  if (zodKind(schema) !== "object") {
+    throw new Error(`codegen-proof: ${where} payload is not a zod object — the proof can only synthesize object payloads`);
+  }
+  const autoStamped = autoStampFields(schema);
+  const stamped = new Set(autoStamped);
+  const value: Record<string, unknown> = {};
+  for (const [name, raw] of Object.entries(zodObjectShape(schema))) {
+    const f = raw as z.ZodTypeAny;
+    const k = zodKind(f);
+    if (k === "optional" || k === "default") continue; // optional → omit
+    if (stamped.has(name)) continue; // `…At` → omit; the client stamps it
+    value[name] = sampleOfZod(f, name, where);
+  }
+  return { value, autoStamped };
+}
+
+// ── shape discovery (which legs THIS law can prove) ───────────────────────────────
+
+interface ConcurrencyLeg {
+  readonly directive: Directive<unknown>;
+  /** The payload field that carries the target instance id (first required string `…Id`). */
+  readonly idField: string;
+  /** The AddWins set field the directive adds to (payload array field name === aggregate set field name). */
+  readonly setField: string;
+}
+
+/**
+ * The AddWins two-writer leg needs the law to have the shape for it: a `.mutates`
+ * directive on the created aggregate whose payload carries (a) a required string
+ * `…Id` field (the instance) and (b) an array-of-string field named exactly like
+ * one of the aggregate's AddWins set fields (the `addToSet` signature). Absent
+ * that shape, the proof prints a skip note instead of inventing law.
+ */
+function findConcurrencyLeg(
+  directives: readonly Directive<unknown>[],
+  agg: AggregateHandle,
+): ConcurrencyLeg | undefined {
+  const addWinsSets = Object.entries(agg.fields)
+    .filter(([, f]) => (f as Field).kind === "set" && ((f as Field).driver as { kind?: string }).kind === "AddWins")
+    .map(([name]) => name);
+  if (addWinsSets.length === 0) return undefined;
+  for (const d of directives) {
+    if (d.marker !== "mutates" || d.aggregateId !== agg.id) continue;
+    let shape: Record<string, z.ZodTypeAny>;
+    try {
+      shape = zodObjectShape(d.payloadSchema as z.ZodTypeAny);
+    } catch {
+      continue;
+    }
+    const idField = Object.entries(shape).find(
+      ([name, f]) => name.length > 2 && name.endsWith("Id") && zodKind(f) === "string",
+    )?.[0];
+    if (idField === undefined) continue;
+    const setField = addWinsSets.find((s) => {
+      const f = shape[s];
+      return f !== undefined && zodKind(f) === "array" && zodKind(zodArrayElement(f)) === "string";
+    });
+    if (setField !== undefined) return { directive: d, idField, setField };
+  }
+  return undefined;
+}
+
+// ── the generator ─────────────────────────────────────────────────────────────────
+
+export interface TsProofOptions {
+  /** The package name (`nomos.package.mjs` `name`) — names the artifacts the proof loads. */
+  readonly packageName: string;
+  /** sha256 of the built `.package.usda` — checked against the deploy response. */
+  readonly domainHash: string;
+}
+
+export function generateTsProof(modules: readonly DomainModule[], opts: TsProofOptions): string {
+  // The proof drives the FIRST domain that has a creating write — without one
+  // there is nothing to author, so there is nothing to prove.
+  const mod = modules.find((m) =>
+    (m.directives as Directive<unknown>[]).some((d) => d?.marker === "creates" && typeof d.payloadSchema === "object"),
+  );
+  if (mod === undefined) {
+    throw new Error(
+      `no .creates directive in any domain — a generated proof needs one creating write; add a directive(...).creates(...) (test/e2e.mts remains the hand-authored lane)`,
+    );
+  }
+  const domain = mod.domain ?? mod.name;
+  const factory = tsClientFactoryName(domain);
+  const hashConst = tsHashConstName(opts.packageName);
+
+  const createDir = (mod.directives as Directive<unknown>[]).find((d) => d?.marker === "creates")!;
+  const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === createDir.aggregateId);
+  if (agg === undefined) {
+    throw new Error(
+      `directive '${createDir.id}' creates '${createDir.aggregateId}' but no such aggregate is composed — export the aggregate from a listed module`,
+    );
+  }
+  const synth = synthesizePayload(createDir.payloadSchema as z.ZodTypeAny, `${domain}/${createDir.id}`);
+
+  // The first declared query that can READ BACK the create: returns the created
+  // aggregate and every key field has a synthesized payload value to probe with.
+  const query = ((mod.queries ?? []) as QueryDecl[]).find(
+    (q) => q.returns === agg.id && q.key.length > 0 && q.key.every((k) => !k.includes(".") && synth.value[k] !== undefined),
+  );
+
+  // The first declared count the create moves: counts the created aggregate,
+  // unpredicated (a .where can't be evaluated at codegen time), and — when
+  // grouped — grouped by a field the synthesized payload carries.
+  const count = (mod.counts ?? [])
+    .map((raw) => finishCount(raw))
+    .find(
+      (c) =>
+        c.of === agg.id &&
+        (c as { where?: unknown }).where == null &&
+        (c.by == null || synth.value[c.by] !== undefined),
+    );
+
+  const concurrency = findConcurrencyLeg(mod.directives as Directive<unknown>[], agg);
+
+  // Workspace-name slug: any package name → a safe, recognizable ws prefix.
+  const slug =
+    opts.packageName
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 24) || "domain";
+
+  const payloadLit = JSON.stringify(synth.value);
+  const queryParams = query ? JSON.stringify(Object.fromEntries(query.key.map((k) => [k, synth.value[k]]))) : "";
+  const listAccessor = `list${agg.id}s`;
+
+  let step = 0;
+  const n = () => ++step;
+  const out: string[] = [];
+
+  out.push(
+    `// AUTO-GENERATED by nomos-compile — the RUNNABLE PROOF for package "${opts.packageName}",`,
+    `// synthesized from the domain's OWN directives/queries/counts. Reshape the law,`,
+    `// recompile, and this proof reshapes itself — no test rewriting. Run it:`,
+    `//`,
+    `//   npx githolon proof        (or: npx tsx build/${opts.packageName}.proof.mts)`,
+    `//`,
+    `// The flow mirrors the scaffold's test/e2e.mts (docs/ in a scaffolded app explains`,
+    `// every call — start at docs/01-mental-model.md). Regenerated on every compile; do not edit.`,
+    `import { readFileSync } from "node:fs";`,
+    `import { connect } from "@githolon/client";`,
+    `import { ${factory}, ${hashConst} } from "./${opts.packageName}.client.ts";`,
+    ``,
+    `const CLOUD = (process.env.NOMOS_CLOUD || "https://nomos.captainapp.co.uk").replace(/\\/+$/, "");`,
+    `const WS = process.env.NOMOS_WS || ${JSON.stringify(slug + "-proof-")} + Math.random().toString(36).slice(2, 8);`,
+    ``,
+    `// IDENTITY NOTE: this proof uses the bare x-nomos-principal lane so it is`,
+    `// SELF-CONTAINED (a throwaway workspace, no stored credentials). Real apps use`,
+    `// \`githolon login --agent\` (a VERIFIED identity) + \`githolon ws create/deploy\`.`,
+    `const fail: (m: string) => never = (m) => { console.error("✗ " + m); process.exit(1); };`,
+    `const ok = (m: string) => console.log("✓ " + m);`,
+    ``,
+    `const deploy = JSON.parse(readFileSync(new URL(${JSON.stringify(`./${opts.packageName}.deploy.json`)}, import.meta.url), "utf8"));`,
+    ``,
+    `// ${n()}. a throwaway workspace (the ONE-TIME secret comes back on create)`,
+    `let r = await fetch(\`\${CLOUD}/v1/workspaces/\${WS}\`, { method: "POST", headers: { "x-nomos-principal": "githolon-proof" } });`,
+    `let d = await r.json();`,
+    `if (!d.ok) fail(\`create workspace: \${JSON.stringify(d)}\`);`,
+    `const SECRET: string = d.workspaceSecret;`,
+    `if (!SECRET?.startsWith("nws_v1_")) fail(\`no workspaceSecret returned: \${JSON.stringify(d)}\`);`,
+    `ok(\`workspace \${WS} created — secret \${SECRET.slice(0, 10)}…\`);`,
+    ``,
+    `// ${n()}. deploy YOUR compiled law (build/${opts.packageName}.deploy.json) WITH the secret`,
+    `r = await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/domains\`, { method: "POST", headers: { "content-type": "application/json", authorization: \`Bearer \${SECRET}\` }, body: JSON.stringify(deploy) });`,
+    `d = await r.json();`,
+    `if (!d.ok || d.installation?.[0]?.data?.["status.phase"] !== "Active") fail(\`deploy: \${JSON.stringify(d)}\`);`,
+    `if (d.domainHash !== ${hashConst}) fail(\`deploy hash \${d.domainHash} != the generated client's \${${hashConst}}\`);`,
+    `ok(\`law deployed Active — \${${hashConst}.slice(0, 12)}… (the content hash baked into your typed client)\`);`,
+    ``,
+    `// ${n()}. connect + bind the GENERATED typed client`,
+    `const holon = await connect({ cloud: CLOUD, workspace: WS, clientId: "proof-1" });`,
+    `const app = ${factory}(holon);`,
+    `ok(\`web client connected — ${factory} bound (replica \${holon.replica.slice(0, 6)}…)\`);`,
+    ``,
+    `// ${n()}. OFFLINE write — the proof is ENFORCED, not narrated: while we author and`,
+    `//    read LOCALLY, fetch THROWS. The payload below was SYNTHESIZED from the zod`,
+    `//    schema of \`${domain}/${createDir.id}\`${synth.autoStamped.length ? ` (${synth.autoStamped.map((s) => `\`${s}\``).join("/")} omitted — the client auto-stamps ISO now())` : ``}.`,
+    `const realFetch = globalThis.fetch;`,
+    `globalThis.fetch = (() => { throw new Error("OFFLINE PROOF VIOLATED: local authoring touched the network"); }) as typeof fetch;`,
+    ``,
+    `await app.${createDir.id}(${payloadLit});`,
+    `ok("dispatch ${domain}/${createDir.id} — offline write under the pulled law (payload synthesized from YOUR schema)");`,
+    ``,
+  );
+
+  if (query) {
+    out.push(
+      `// ${n()}. the first declared query routes LOCALLY (params from the synthesized payload)`,
+      `const rows = await app.${lcFirst(camel(query.id))}(${queryParams});`,
+      `if (rows.length !== 1) fail(\`local declared query ${query.id}: \${JSON.stringify(rows)}\`);`,
+      `const createdId = rows[0]!.id;`,
+      `ok(\`declared query ${query.id} answers locally — ${agg.id} \${createdId}\`);`,
+      ``,
+    );
+  } else {
+    out.push(
+      `// ${n()}. no declared query reads this create back (declare a query(...) keyed on a`,
+      `//    payload field to see one proved here) — the type-index probe captures the id.`,
+      `const rows = await app.${listAccessor}();`,
+      `if (rows.length !== 1) fail(\`local ${listAccessor}: \${JSON.stringify(rows)}\`);`,
+      `const createdId = rows[0]!.id;`,
+      `console.log("– declared-query leg SKIPPED — no query(...) returns ${agg.id} keyed on a synthesized payload field");`,
+      `ok(\`local read answers — ${agg.id} \${createdId}\`);`,
+      ``,
+    );
+  }
+
+  if (count) {
+    const accessor = lcFirst(camel(count.id));
+    const callArg = count.by != null ? JSON.stringify(String(synth.value[count.by])) : "";
+    out.push(
+      `// ${n()}. the first declared count — the maintained O(1) tally, locally`,
+      `const localCount = await app.${accessor}(${callArg});`,
+      `if (localCount !== 1) fail(\`local declared count ${count.id}: \${localCount}\`);`,
+      `ok("declared count ${count.id}${count.by != null ? `(${callArg.replace(/"/g, "'")})` : `()`} = 1 locally");`,
+      ``,
+    );
+  }
+
+  out.push(
+    `globalThis.fetch = realFetch;`,
+    `ok("offline proof ENFORCED — fetch was trapped: local write/read touched no network");`,
+    ``,
+    `// ${n()}. sync: push the session branch; edge admission re-verifies and merges to main`,
+    `const s = await holon.sync();`,
+    `if (!s.admission?.ok) fail(\`sync/admit: \${JSON.stringify(s)}\`);`,
+    `const admitted = (s.admission.sessions || []).flatMap((x: { admitted?: unknown[] }) => x.admitted || []);`,
+    `if (admitted.length < 1) fail(\`edge admitted \${admitted.length} intent(s): \${JSON.stringify(s.admission)}\`);`,
+    `ok(\`synced — edge admission merged \${admitted.length} intent(s) to main\`);`,
+    ``,
+  );
+
+  if (query) {
+    out.push(
+      `// ${n()}. the CLOUD answers the SAME declared query (read-manifest overlay, edge projection)`,
+      `d = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/query?queryId=${query.id}&params=\${encodeURIComponent(${JSON.stringify(queryParams)})}\`)).json();`,
+      `if (!(d.ok && d.rows.length === 1 && d.rows[0].id === createdId)) fail(\`cloud declared query: \${JSON.stringify(d)}\`);`,
+      `ok("cloud declared query ${query.id} returns the admitted row — full loop closed");`,
+      ``,
+    );
+  } else {
+    out.push(
+      `// ${n()}. the CLOUD answers the by-id read (edge projection of the admitted write)`,
+      `d = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/aggregates/\${encodeURIComponent(createdId)}\`)).json();`,
+      `if (!(d.rows?.length === 1 && d.rows[0].id === createdId)) fail(\`cloud by-id read: \${JSON.stringify(d)}\`);`,
+      `ok("cloud read returns the admitted row — full loop closed");`,
+      ``,
+    );
+  }
+
+  if (count) {
+    out.push(
+      `// ${n()}. the EDGE maintains the same count (same wasm, same law)`,
+      `d = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/counts/${count.id}${count.by != null ? `?group=\${encodeURIComponent(${JSON.stringify(String(synth.value[count.by]))})}` : ``}\`)).json();`,
+      `if (!(d.ok && d.count === 1)) fail(\`cloud count ${count.id}: \${JSON.stringify(d)}\`);`,
+      `ok("cloud count ${count.id} = 1 — the O(1) maintained read, at the edge too");`,
+      ``,
+    );
+  }
+
+  if (concurrency) {
+    const { directive: cd, idField, setField } = concurrency;
+    const cSynth = synthesizePayload(cd.payloadSchema as z.ZodTypeAny, `${domain}/${cd.id}`);
+    const concPayload = (writer: string): string => {
+      const entries = Object.entries({ ...cSynth.value, [idField]: 0, [setField]: 0 }).map(([k]) => {
+        if (k === idField) return `${JSON.stringify(k)}: createdId`;
+        if (k === setField) return `${JSON.stringify(k)}: ${JSON.stringify([`proof-${writer}`])}`;
+        return `${JSON.stringify(k)}: ${JSON.stringify(cSynth.value[k])}`;
+      });
+      return `{ ${entries.join(", ")} }`;
+    };
+    out.push(
+      `// ${n()}. CONCURRENCY — two writers, two clientIds, BLIND to each other: each adds to`,
+      `//    the AddWins set \`${agg.id}.${setField}\` via \`${domain}/${cd.id}\` offline; admission`,
+      `//    merges both and the union keeps every add.`,
+      `const writerA = await connect({ cloud: CLOUD, workspace: WS, clientId: "proof-a" });`,
+      `const writerB = await connect({ cloud: CLOUD, workspace: WS, clientId: "proof-b" });`,
+      `await ${factory}(writerA).${cd.id}(${concPayload("a")});`,
+      `await ${factory}(writerB).${cd.id}(${concPayload("b")});`,
+      `await writerA.sync();`,
+      `await writerB.sync();`,
+      `d = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/aggregates/\${encodeURIComponent(createdId)}\`)).json();`,
+      `const merged: string[] = d.rows?.[0]?.data?.[${JSON.stringify(setField)}] ?? [];`,
+      `if (!(merged.includes("proof-a") && merged.includes("proof-b"))) fail(\`AddWins union lost an add: \${JSON.stringify(merged)}\`);`,
+      `ok(\`two blind writers' concurrent adds BOTH survive the merge — ${setField} [\${[...merged].sort().join(", ")}]\`);`,
+      ``,
+    );
+  } else {
+    out.push(
+      `// ${n()}. concurrency leg: this law has no addToSet-capable .mutates directive on an`,
+      `//    AddWins set field, so there is nothing honest to race.`,
+      `console.log("– concurrency leg SKIPPED — add a .mutates directive carrying an array field named like an AddWins set (the addToSet shape) to see two blind writers merge");`,
+      ``,
+    );
+  }
+
+  out.push(
+    `// ${n()}. CONVERGENCE: the original instance adopts canonical main in place — no reconnect`,
+    `await holon.pull();`,
+    `const head = await holon.head();`,
+    `const refsAdv = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/git/info/refs?service=git-upload-pack\`)).text();`,
+    `const remoteMain = (refsAdv.match(/([0-9a-f]{40}) refs\\/heads\\/main/) || [])[1];`,
+    `if (head !== remoteMain) fail(\`not converged in place: local \${head?.slice(0, 10)} vs main \${remoteMain?.slice(0, 10)}\`);`,
+    `ok("converged in place — local head == canonical main");`,
+    ``,
+    `console.log(\`\\nALL GREEN — generated proof for "${opts.packageName}": deploy → offline write → local reads → admission → cloud reads${concurrency ? ` → AddWins merge` : ``} → convergence (\${WS})\`);`,
+    ``,
+  );
+
+  return out.join("\n");
+}

package/src/codegen_ts.ts

@@ -63,6 +63,8 @@ export const tsClientFactoryName = (domain: string): string => `${lcFirst(camel(
 export const tsHashConstName = (packageName: string): string => `${upperSnake(packageName)}_DOMAIN_HASH`;
 
 // ── zod → TS (the same `_def ?? def` convention as codegen_dart's walker) ─────────
+// The walkers are exported: codegen_proof.ts synthesizes SAMPLE payloads from the
+// same zod shapes this file derives TYPES from — one introspection, two emitters.
 
 type ZodInternalDef = {
   type?: string | z.ZodTypeAny;
@@ -76,17 +78,17 @@ type ZodInternalDef = {
   valueType?: z.ZodTypeAny;
 };
 
-function zodDef(zt: z.ZodTypeAny): ZodInternalDef {
+export function zodDef(zt: z.ZodTypeAny): ZodInternalDef {
   const raw = zt as unknown as { _def?: ZodInternalDef; def?: ZodInternalDef };
   return raw._def ?? raw.def ?? {};
 }
 
-function zodKind(zt: z.ZodTypeAny): string {
+export function zodKind(zt: z.ZodTypeAny): string {
   const t = zodDef(zt).type;
   return typeof t === "string" ? t : "unknown";
 }
 
-function zodEnumValues(zt: z.ZodTypeAny): string[] {
+export function zodEnumValues(zt: z.ZodTypeAny): string[] {
   const raw = zt as unknown as { options?: readonly unknown[] };
   if (raw.options !== undefined) return raw.options.map(String);
   const entries = zodDef(zt).entries;
@@ -94,7 +96,7 @@ function zodEnumValues(zt: z.ZodTypeAny): string[] {
   throw new Error("codegen-ts: ZodEnum has no values");
 }
 
-function zodObjectShape(zt: z.ZodTypeAny): Record<string, z.ZodTypeAny> {
+export function zodObjectShape(zt: z.ZodTypeAny): Record<string, z.ZodTypeAny> {
   const shape = zodDef(zt).shape;
   if (typeof shape === "function") return shape();
   if (shape !== undefined) return shape;
@@ -103,7 +105,7 @@ function zodObjectShape(zt: z.ZodTypeAny): Record<string, z.ZodTypeAny> {
   throw new Error("codegen-ts: ZodObject has no shape");
 }
 
-function zodArrayElement(zt: z.ZodTypeAny): z.ZodTypeAny {
+export function zodArrayElement(zt: z.ZodTypeAny): z.ZodTypeAny {
   const def = zodDef(zt);
   if (def.element !== undefined) return def.element;
   if (typeof def.type !== "string" && def.type !== undefined) return def.type;
@@ -175,7 +177,7 @@ function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
  * Passing the field explicitly always wins (scheduling-shaped fields like
  * `expiresAt` should be passed explicitly — "now" is only the DEFAULT).
  */
-function autoStampFields(schema: z.ZodTypeAny): string[] {
+export function autoStampFields(schema: z.ZodTypeAny): string[] {
   if (zodKind(schema) !== "object") return [];
   const out: string[] = [];
   for (const [name, f] of Object.entries(zodObjectShape(schema))) {