@githolon/dsl 0.1.6 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "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",

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

@@ -18,7 +18,9 @@
  *   * a PAYLOAD TYPE per directive — derived from the SAME zod schema the sealed
  *     engine validates (recursive zod→TS: enums become literal unions, `.optional()`
  *     becomes `?`, `.int()` stays `number`), so a payload the type system accepts is
- *     a payload the engine accepts;
+ *     a payload the engine accepts; required string fields named `…At` are
+ *     CALLER-STAMPED TIMESTAMPS — optional in the type, auto-filled with ISO now()
+ *     at dispatch (see {@link autoStampFields});
  *   * a READ-MODEL interface per aggregate — derived from the DSL `Field` kinds the
  *     projection decodes by (set→`T[]`, map→`Record<string, V>` via `mapValueKind`,
  *     `t.jsonObject()`→`Record<string, unknown>`, plain `t.json()`→`unknown`), with
@@ -45,11 +47,24 @@ import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 
 const cap = (s: string) => (s.length ? s[0]!.toUpperCase() + s.slice(1) : s);
-const camel = (s: string) => s.replace(/[_-]+(\w)/g, (_m, c: string) => c.toUpperCase());
+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);
 const upperSnake = (s: string) => s.replace(/[-\s]+/g, "_").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
 
+// ── NAME NORMALIZATION (no naming convention to learn) ────────────────────────────
+// `nomos.package.mjs` names and domain keys may be ANY string — kebab-case,
+// snake_case, space-separated, PascalCase. Artifact FILENAMES keep the raw name
+// verbatim; generated SYMBOLS normalize it:
+
+/** `tool-library` / `tool_library` / `Tool Library` → `toolLibraryClient` — the factory symbol. */
+export const tsClientFactoryName = (domain: string): string => `${lcFirst(camel(domain))}Client`;
+
+/** `tool-library` / `tool_library` / `Tool Library` → `TOOL_LIBRARY_DOMAIN_HASH` — the hash const. */
+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;
@@ -63,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;
@@ -81,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;
@@ -90,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;
@@ -151,6 +166,44 @@ function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
   }
 }
 
+// ── caller-side clock sugar (the `…At` payload convention) ────────────────────────
+
+/**
+ * Top-level REQUIRED string payload fields named `…At` (`signedAt`, `updatedAt`,
+ * `stampedAt`, …) are CALLER-STAMPED TIMESTAMPS by convention: the generated client
+ * fills an omitted one with `new Date().toISOString()` at dispatch. The stamp rides
+ * IN the payload — the plan stays a pure function of `(payload, ports)` and replays
+ * byte-identical on every peer — so the domain dev stops thinking about clocks.
+ * Passing the field explicitly always wins (scheduling-shaped fields like
+ * `expiresAt` should be passed explicitly — "now" is only the DEFAULT).
+ */
+export function autoStampFields(schema: z.ZodTypeAny): string[] {
+  if (zodKind(schema) !== "object") return [];
+  const out: string[] = [];
+  for (const [name, f] of Object.entries(zodObjectShape(schema))) {
+    // required-only: `.optional()`/`.default()` wrappers change the zod kind, so they skip.
+    if (name.length > 2 && name.endsWith("At") && zodKind(f as z.ZodTypeAny) === "string") out.push(name);
+  }
+  return out;
+}
+
+/** The payload type text, with auto-stamped fields surfaced as optional (`?`). */
+function tsTypeOfPayload(schema: z.ZodTypeAny, autoStamped: readonly string[]): string {
+  if (zodKind(schema) !== "object" || autoStamped.length === 0) return tsTypeOfZod(schema, "");
+  const stamped = new Set(autoStamped);
+  const fields = Object.entries(zodObjectShape(schema)).map(([name, raw]) => {
+    let f = raw as z.ZodTypeAny;
+    let optional = stamped.has(name);
+    while (zodKind(f) === "optional" || zodKind(f) === "default") {
+      optional = true;
+      f = zodDef(f).innerType!;
+    }
+    const note = stamped.has(name) ? " // auto-stamped with ISO now() at dispatch when omitted" : "";
+    return `  ${name}${optional ? "?" : ""}: ${tsTypeOfZod(f, "  ")};${note}`;
+  });
+  return fields.length ? `{\n${fields.join("\n")}\n}` : "Record<string, never>";
+}
+
 // ── DSL Field → read-model TS type (the projection's decode surface) ──────────────
 
 function tsTypeOfField(field: Field): string {
@@ -214,7 +267,7 @@ export interface TsClientOptions {
 }
 
 export function generateTsClient(modules: readonly DomainModule[], opts: TsClientOptions): string {
-  const hashConst = `${upperSnake(opts.packageName)}_DOMAIN_HASH`;
+  const hashConst = tsHashConstName(opts.packageName);
   const out: string[] = [];
   out.push(
     `// AUTO-GENERATED by nomos-compile — typed TS client for package "${opts.packageName}".`,
@@ -222,9 +275,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `// exposing the @githolon/client surface (the structural NomosHolon below), e.g.`,
     `//`,
     `//   import { connect } from "@githolon/client";`,
-    `//   import { ${lcFirst(camel(modules[0]?.domain ?? "domain"))}Client } from "./build/${opts.packageName}.client.js";`,
+    `//   import { ${tsClientFactoryName(modules[0]?.domain ?? "domain")} } from "./build/${opts.packageName}.client.js";`,
     `//   const holon = await connect({ cloud, workspace, clientId });`,
-    `//   const app = ${lcFirst(camel(modules[0]?.domain ?? "domain"))}Client(holon);`,
+    `//   const app = ${tsClientFactoryName(modules[0]?.domain ?? "domain")}(holon);`,
     ``,
     `/** sha256 of the deployed \`.package.usda\` — the installed law this client dispatches under. */`,
     `export const ${hashConst} = ${JSON.stringify(opts.domainHash)};`,
@@ -250,6 +303,28 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     ``,
   );
 
+  const anyAutoStamp = modules.some((mod) =>
+    (mod.directives as Directive<unknown>[]).some(
+      (d) =>
+        d &&
+        typeof (d as { payloadSchema?: unknown }).payloadSchema === "object" &&
+        autoStampFields((d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema).length > 0,
+    ),
+  );
+  if (anyAutoStamp) {
+    out.push(
+      `/** Caller-side clock sugar: fill omitted \`…At\` timestamp payload fields with ISO now().`,
+      ` *  The stamp rides IN the payload, so plans stay pure and replay byte-identical. */`,
+      `const stampNow = <T extends object>(payload: T, fields: string[]): T => {`,
+      `  const now = new Date().toISOString();`,
+      `  const out = { ...payload } as Record<string, unknown>;`,
+      `  for (const f of fields) if (out[f] === undefined) out[f] = now;`,
+      `  return out as T;`,
+      `};`,
+      ``,
+    );
+  }
+
   // ── read models: one interface per aggregate wire type (deduped), deriveds/combineds merged ──
   const aggByType = new Map<string, AggregateHandle>();
   const extrasByType = new Map<string, string[]>();
@@ -291,14 +366,17 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       if (usedPayloadNames.has(payloadName)) payloadName = `${cap(camel(domain))}${cap(d.id)}Payload`;
       usedPayloadNames.add(payloadName);
       const schema = (d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema;
+      const stamps = autoStampFields(schema);
       out.push(
-        `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema). */`,
-        `export type ${payloadName} = ${tsTypeOfZod(schema, "")};`,
+        `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema).${stamps.length ? ` Omitted ${stamps.map((s) => `\`${s}\``).join("/")} auto-stamp(s) ISO now() at dispatch.` : ""} */`,
+        `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps)};`,
         ``,
       );
       methods.push(
         `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head. */`,
-        `    ${d.id}: (payload: ${payloadName}) => holon.dispatch(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, payload, { domainHash }),`,
+        stamps.length
+          ? `    ${d.id}: (payload: ${payloadName}) => holon.dispatch(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, stampNow(payload, ${JSON.stringify(stamps)}), { domainHash }),`
+          : `    ${d.id}: (payload: ${payloadName}) => holon.dispatch(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, payload, { domainHash }),`,
       );
     }
 
@@ -350,7 +428,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
 
     out.push(
       `/** Typed client for the \`${domain}\` domain, bound to a connected holon. */`,
-      `export function ${lcFirst(camel(domain))}Client(holon: NomosHolon, domainHash: string = ${hashConst}) {`,
+      `export function ${tsClientFactoryName(domain)}(holon: NomosHolon, domainHash: string = ${hashConst}) {`,
       `  return {`,
       `    domain: ${JSON.stringify(domain)} as const,`,
       `    domainHash,`,

package/src/compile_package_main.ts

@@ -37,6 +37,10 @@
  *     identityHashes}`: the EXACT body `POST /v1/workspaces/:ws/domains` accepts as
  *     `application/json` on Nomos Cloud (package + per-workspace manifest overlay in
  *     one deploy).
+ *   * `<name>.proof.mts`               — the GENERATED PROOF (codegen_proof.ts): a
+ *     runnable, domain-shaped live e2e synthesized from the law's own directives /
+ *     queries / counts. Run it with `githolon proof`. Never fatal: an unsampleable
+ *     domain still compiles, the skip names its remedy.
  *
  * The engine entry is GENERATED (imports + one `registerEngine` call — the machinery
  * lives in `@githolon/dsl/engine-entry`), bundled with the SAME deterministic esbuild
@@ -69,7 +73,8 @@ import {
   writeIdentity,
   type Mod,
 } from "./build_package.js";
-import { generateTsClient } from "./codegen_ts.js";
+import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
+import { generateTsProof } from "./codegen_proof.js";
 
 const DSL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -288,7 +293,12 @@ async function main(): Promise<void> {
   if (!cfg || typeof cfg.name !== "string" || !Array.isArray(cfg.domains) || cfg.domains.length === 0) {
     fail(`config must default-export { name, domains: [{ key, modules }, ...] }`);
   }
-  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(cfg.name)) fail(`package name '${cfg.name}' is not a safe basename`);
+  // ANY readable name works ("tool-library", "tool_library", "Tool Library"):
+  // artifact FILENAMES keep it verbatim; generated SYMBOLS normalize it
+  // (toolLibraryClient, TOOL_LIBRARY_DOMAIN_HASH — see codegen_ts.ts).
+  if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(cfg.name)) {
+    fail(`package name '${cfg.name}' is not a safe basename (letters, digits, spaces, '.', '-', '_')`);
+  }
 
   const outDir = path.resolve(cfgDir, cfg.outDir ?? "build");
   mkdirSync(outDir, { recursive: true });
@@ -467,6 +477,21 @@ async function main(): Promise<void> {
   };
   const deployPath = path.join(outDir, `${cfg.name}.deploy.json`);
   writeFileSync(deployPath, JSON.stringify(deployBody) + "\n", "utf8");
+
+  // ── 4b. the GENERATED PROOF — a runnable, domain-shaped e2e synthesized from the
+  //        law itself (codegen_proof.ts): reshape the law, recompile, the proof
+  //        reshapes itself — no test rewriting. NEVER FATAL: a domain the
+  //        synthesizer can't sample yet still compiles — the skip names its remedy.
+  let proofPath: string | undefined;
+  let proofSkip: string | undefined;
+  try {
+    const proofSrc = generateTsProof(domainModules, { packageName: cfg.name, domainHash });
+    proofPath = path.join(outDir, `${cfg.name}.proof.mts`);
+    writeFileSync(proofPath, proofSrc, "utf8");
+  } catch (e) {
+    proofSkip = (e as Error).message;
+  }
+
   const summaryTxt = [
     `${cfg.name} — compiled Nomos domain package`,
     `law (domainHash): ${domainHash}   # sha256(${cfg.name}.package.usda) — content-addressed`,
@@ -477,7 +502,10 @@ async function main(): Promise<void> {
       `  queries: ${d.queries.join(", ") || "—"}   counts: ${d.counts.join(", ") || "—"}`,
     ]),
     `deploy: POST ${cfg.name}.deploy.json to /v1/workspaces/<ws>/domains (or: githolon deploy <ws>)`,
-    `typed client: ${cfg.name}.client.ts — ${cfg.name}Client(holon), law hash baked in`,
+    `typed client: ${cfg.name}.client.ts — ${tsClientFactoryName(domainModules[0]?.domain ?? domainModules[0]?.name ?? cfg.name)}(holon), law hash baked in`,
+    proofPath !== undefined
+      ? `generated proof: ${cfg.name}.proof.mts — run: githolon proof (live; ends ALL GREEN or names the jam)`
+      : `generated proof: SKIPPED — ${proofSkip}`,
     ``,
   ].join("\n");
   writeFileSync(path.join(outDir, `${cfg.name}.summary.txt`), summaryTxt, "utf8");
@@ -513,6 +541,11 @@ async function main(): Promise<void> {
   for (const [dom, h] of Object.entries(identity.hashes)) console.log(`             ${dom.padEnd(20)} ${h}`);
   for (const ex of identity.excluded) console.log(`             EXCLUDED ${ex.domain}: ${ex.reason}`);
   console.log(`  client     ${rel(clientPath)} (typed TS client — payloads, read models, query accessors)`);
+  if (proofPath !== undefined) {
+    console.log(`  proof      ${rel(proofPath)} (a runnable e2e GENERATED from your law — run: githolon proof)`);
+  } else {
+    console.log(`  proof      SKIPPED — ${proofSkip}`);
+  }
   if (dartOut !== undefined) {
     console.log(`  dart       ${rel(dartOut)}${path.sep} (${dartFiles.length} domain file(s) + vendored nomos_dsl support — typed Dart for Flutter)`);
   }
@@ -522,7 +555,11 @@ async function main(): Promise<void> {
   console.log(`  githolon ws create <ws> && githolon deploy <ws>   # the secret is saved + sent for you`);
   console.log(`  # raw lane: curl -X POST -H 'content-type: application/json' -H 'Authorization: Bearer <workspaceSecret>' \\`);
   console.log(`  #   --data-binary @${rel(deployPath)} https://nomos.captainapp.co.uk/v1/workspaces/<ws>/domains`);
-  console.log(`prove it: npm run e2e   # offline write -> sync -> admission -> cloud query, live`);
+  if (proofPath !== undefined) {
+    console.log(`prove it: npx githolon proof   # GENERATED from your law — offline write -> sync -> admission -> cloud reads, live`);
+  } else {
+    console.log(`prove it: npm run e2e   # offline write -> sync -> admission -> cloud query, live`);
+  }
 }
 
 await main();

package/src/index.ts

@@ -6,6 +6,9 @@
 // If a file isn't this / hosting this / authoring for this / proving this — it's gone.
 
 /** `@githolon/dsl` — the Nomos 2 domain-authoring DSL. */
+// ONE import for a domain file: `z` (payload schemas) rides along with the DSL, so
+// authors never juggle a separate zod dependency (or risk a second zod instance).
+export { z } from "zod";
 export {
   aggregate,
   instance,