@githolon/dsl 0.1.0

package/src/codegen_ts.ts

@@ -0,0 +1,365 @@
+// 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.
+
+/**
+ * TS CLIENT CODEGEN (#10) — the WEB sibling of `codegen_dart.ts`.
+ *
+ * Dart apps get generated payload classes / read models / typed query accessors;
+ * until this file, a web app on `@githolon/client` hand-typed directive ids and
+ * payload shapes against the raw `dispatch()` surface. `generateTsClient(modules,
+ * opts)` closes that: ONE generated `.ts` file per package, emitted by
+ * `nomos-compile` AFTER the package is hashed (the deployed law's content hash is
+ * baked in as a constant), carrying:
+ *
+ *   * 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 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
+ *     derived/combined read fields merged in (typed off their declared zod returns).
+ *     EVERY field is `?`: a projection row carries only what has folded so far;
+ *   * a CLIENT FACTORY per domain — typed `dispatch` wrappers bound to the baked
+ *     domainHash, typed declared-query accessors, and by-id read/watch helpers —
+ *     over a STRUCTURAL `NomosHolon` interface, so the file has ZERO imports and
+ *     binds to `@githolon/client`'s `connect()` result (browser or node) as-is.
+ *
+ * Like every emitter here: NO FALLBACK. An unsupported zod shape throws at compile
+ * time, never degrades to `any` silently.
+ */
+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 { finishSum } from "./sum.js";
+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 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();
+
+// ── zod → TS (the same `_def ?? def` convention as codegen_dart's walker) ─────────
+
+type ZodInternalDef = {
+  type?: string | z.ZodTypeAny;
+  innerType?: z.ZodTypeAny;
+  element?: z.ZodTypeAny;
+  shape?: Record<string, z.ZodTypeAny> | (() => Record<string, z.ZodTypeAny>);
+  entries?: Record<string, string | number>;
+  options?: z.ZodTypeAny[];
+  value?: unknown;
+  values?: readonly unknown[];
+  valueType?: z.ZodTypeAny;
+};
+
+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 {
+  const t = zodDef(zt).type;
+  return typeof t === "string" ? t : "unknown";
+}
+
+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;
+  if (entries !== undefined) return Object.values(entries).map(String);
+  throw new Error("codegen-ts: ZodEnum has no values");
+}
+
+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;
+  const raw = zt as unknown as { shape?: Record<string, z.ZodTypeAny> };
+  if (raw.shape !== undefined) return raw.shape;
+  throw new Error("codegen-ts: ZodObject has no shape");
+}
+
+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;
+  throw new Error("codegen-ts: ZodArray has no element type");
+}
+
+const union = (parts: string[]) => [...new Set(parts)].join(" | ");
+const paren = (t: string) => (t.includes("|") || t.includes("&") ? `(${t})` : t);
+
+/** Recursive zod → TS type text. NO FALLBACK: an unhandled shape throws. */
+function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
+  switch (zodKind(zt)) {
+    case "string":
+      return "string";
+    case "number":
+      return "number"; // `.int()` is a runtime constraint; TS has one number type
+    case "boolean":
+      return "boolean";
+    case "enum":
+      return union(zodEnumValues(zt).map((v) => JSON.stringify(v)));
+    case "literal": {
+      const def = zodDef(zt);
+      const v = def.value !== undefined ? def.value : def.values?.[0];
+      return JSON.stringify(v);
+    }
+    case "array":
+      return `${paren(tsTypeOfZod(zodArrayElement(zt), indent))}[]`;
+    case "object": {
+      const shape = zodObjectShape(zt);
+      const inner = indent + "  ";
+      const fields = Object.entries(shape).map(([name, raw]) => {
+        let f = raw as z.ZodTypeAny;
+        let optional = false;
+        while (zodKind(f) === "optional" || zodKind(f) === "default") {
+          optional = true;
+          f = zodDef(f).innerType!;
+        }
+        return `${inner}${name}${optional ? "?" : ""}: ${tsTypeOfZod(f, inner)};`;
+      });
+      return fields.length ? `{\n${fields.join("\n")}\n${indent}}` : "Record<string, never>";
+    }
+    case "record": {
+      const vt = zodDef(zt).valueType;
+      return `Record<string, ${vt ? tsTypeOfZod(vt, indent) : "unknown"}>`;
+    }
+    case "optional":
+    case "default":
+      return `${tsTypeOfZod(zodDef(zt).innerType!, indent)} | undefined`;
+    case "nullable":
+      return `${tsTypeOfZod(zodDef(zt).innerType!, indent)} | null`;
+    case "union":
+      return union((zodDef(zt).options ?? []).map((o) => tsTypeOfZod(o, indent)));
+    case "unknown":
+    case "any":
+      return "unknown";
+    default:
+      throw new Error(`codegen-ts: unsupported zod shape '${zodKind(zt)}' — extend tsTypeOfZod`);
+  }
+}
+
+// ── DSL Field → read-model TS type (the projection's decode surface) ──────────────
+
+function tsTypeOfField(field: Field): string {
+  switch (field.kind) {
+    case "string":
+      return "string";
+    case "int":
+      return "number";
+    case "enum":
+      try {
+        return union(zodEnumValues(field.zod as z.ZodTypeAny).map((v) => JSON.stringify(v)));
+      } catch {
+        return "string";
+      }
+    case "ref":
+      return "string"; // the related aggregate's id
+    case "json":
+      return field.jsonShape === "object" ? "Record<string, unknown>" : "unknown";
+    case "set":
+      return "string[]"; // `t.set(t.string())` is the one set shape (fields.ts)
+    case "map": {
+      const v =
+        field.mapValueKind === "string" ? "string"
+        : field.mapValueKind === "int" ? "number"
+        : "unknown";
+      return `Record<string, ${v}>`;
+    }
+    default:
+      throw new Error(`codegen-ts: unsupported field kind '${field.kind}' — extend tsTypeOfField`);
+  }
+}
+
+/** A loose TS type for a derived/combined field's declared zod `returns`. */
+function tsTypeOfReturns(returns: unknown): string {
+  try {
+    return tsTypeOfZod(returns as z.ZodTypeAny, "  ");
+  } catch {
+    return "unknown";
+  }
+}
+
+// ── duck-typed scans (the same shapes the engine entry + compiler discover) ───────
+
+function aggregatesOf(mod: Record<string, unknown>): AggregateHandle[] {
+  const out: AggregateHandle[] = [];
+  for (const v of Object.values(mod)) {
+    if (v && typeof v === "object" && (v as { __isAggregateHandle?: boolean }).__isAggregateHandle === true) {
+      out.push(v as AggregateHandle);
+    }
+  }
+  return out;
+}
+
+// ── the generator ─────────────────────────────────────────────────────────────────
+
+export interface TsClientOptions {
+  /** The package name (`nomos.package.mjs` `name`) — used for the hash constant. */
+  readonly packageName: string;
+  /** sha256 of the built `.package.usda` — the law this client dispatches under. */
+  readonly domainHash: string;
+}
+
+export function generateTsClient(modules: readonly DomainModule[], opts: TsClientOptions): string {
+  const hashConst = `${upperSnake(opts.packageName)}_DOMAIN_HASH`;
+  const out: string[] = [];
+  out.push(
+    `// AUTO-GENERATED by nomos-compile — typed TS client for package "${opts.packageName}".`,
+    `// Regenerated on every compile; do not edit. Zero imports: bind it to any holon`,
+    `// 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";`,
+    `//   const holon = await connect({ cloud, workspace, clientId });`,
+    `//   const app = ${lcFirst(camel(modules[0]?.domain ?? "domain"))}Client(holon);`,
+    ``,
+    `/** sha256 of the deployed \`.package.usda\` — the installed law this client dispatches under. */`,
+    `export const ${hashConst} = ${JSON.stringify(opts.domainHash)};`,
+    ``,
+    `/** One projection row: the aggregate's wire type, its id, and the folded fields. */`,
+    `export interface Row<T> { type: string; id: string; data: T }`,
+    ``,
+    `/** The holon surface this client binds to (structurally satisfied by @githolon/client). */`,
+    `export interface NomosHolon {`,
+    `  dispatch(domain: string, directiveId: string, payload: unknown, opts: { domainHash: string }): Promise<string>;`,
+    `  query(queryId: string, params?: Record<string, unknown>): Promise<unknown>;`,
+    `  queryById(aggregateId: string): Promise<unknown>;`,
+    `  watchById(aggregateId: string, cb: (rows: unknown) => void, opts?: { intervalMs?: number }): () => void;`,
+    `  /** Declared-count / declared-sum O(1) reads (maintained by the read engine). */`,
+    `  count(countId: string, groupKey?: string): Promise<number>;`,
+    `  sum(sumId: string, groupKey?: string): Promise<number>;`,
+    `  /** The DEAD-LETTER QUEUE — refused-but-legitimate intents the app must handle`,
+    `   *  explicitly (inspect → retry after a law fix → or discard). Work is never lost. */`,
+    `  deadLetters(): Promise<{ id?: string; oid: string; source: string; error: string; domain?: string | null; directiveId?: string | null; at: string }[]>;`,
+    `  retryDeadLetter(id: string): Promise<{ ok: boolean; head?: string; alreadyOnMain?: boolean; error?: string }>;`,
+    `  discardDeadLetter(id: string): Promise<{ ok: boolean; removed: number }>;`,
+    `}`,
+    ``,
+  );
+
+  // ── read models: one interface per aggregate wire type (deduped), deriveds/combineds merged ──
+  const aggByType = new Map<string, AggregateHandle>();
+  const extrasByType = new Map<string, string[]>();
+  for (const mod of modules) {
+    for (const agg of mod.aggregates as AggregateHandle[]) aggByType.set(agg.id, agg);
+    for (const d of (mod.deriveds ?? []) as DerivedDecl[]) {
+      (extrasByType.get(d.of) ?? extrasByType.set(d.of, []).get(d.of)!).push(
+        `  /** derived read field (engine-projected) */\n  ${d.id}?: ${tsTypeOfReturns(d.returns)};`,
+      );
+    }
+    for (const c of (mod.combineds ?? []) as CombinedDecl[]) {
+      (extrasByType.get(c.of) ?? extrasByType.set(c.of, []).get(c.of)!).push(
+        `  /** combined read field (engine-projected via \`${c.refField}\` → ${c.reads}) */\n  ${c.id}?: ${tsTypeOfReturns(c.returns)};`,
+      );
+    }
+  }
+  out.push(`// ── read models (projection \`data\` shapes; every field is partial-fold optional) ──`, ``);
+  for (const [typeId, agg] of [...aggByType].sort(([a], [b]) => a.localeCompare(b))) {
+    out.push(`export interface ${typeId}Data {`);
+    for (const [name, field] of Object.entries(agg.fields)) {
+      out.push(`  ${name}?: ${tsTypeOfField(field as Field)};`);
+    }
+    for (const extra of extrasByType.get(typeId) ?? []) out.push(extra);
+    out.push(`}`, ``);
+  }
+
+  // ── payload types + per-domain client factories ──
+  const usedPayloadNames = new Set<string>();
+  for (const mod of modules) {
+    const domain = mod.domain ?? mod.name;
+    const dirs = (mod.directives as Directive<unknown>[]).filter(
+      (d) => d && typeof d.id === "string" && typeof (d as { payloadSchema?: unknown }).payloadSchema === "object",
+    );
+    out.push(`// ── domain "${domain}" ──`, ``);
+
+    const methods: string[] = [];
+    for (const d of dirs) {
+      let payloadName = `${cap(d.id)}Payload`;
+      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;
+      out.push(
+        `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema). */`,
+        `export type ${payloadName} = ${tsTypeOfZod(schema, "")};`,
+        ``,
+      );
+      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 }),`,
+      );
+    }
+
+    for (const q of (mod.queries ?? []) as QueryDecl[]) {
+      const agg = aggByType.get(q.returns);
+      const params = q.key
+        .map((k) => {
+          const lead = k.includes(".") ? k.split(".")[0]! : k;
+          const f = agg?.fields[lead] as Field | undefined;
+          const t = f ? (f.kind === "int" ? "number" : "string") : "string";
+          return `${JSON.stringify(k)}: ${t}`;
+        })
+        .join("; ");
+      methods.push(
+        `    /** Declared query \`${q.id}\` (indexed probe — routed by the read manifest). */`,
+        `    ${lcFirst(camel(q.id))}: (params: { ${params} }) => holon.query(${JSON.stringify(q.id)}, params) as Promise<Row<${q.returns}Data>[]>,`,
+      );
+    }
+
+    for (const c of (mod.counts ?? []).map((raw) => finishCount(raw))) {
+      const grouped = c.by != null;
+      methods.push(
+        `    /** Declared count \`${c.id}\` — the maintained O(1) ${grouped ? `tally per \`${c.by}\`` : "grand total"}. */`,
+        grouped
+          ? `    ${lcFirst(camel(c.id))}: (${c.by}: string) => holon.count(${JSON.stringify(c.id)}, ${c.by}),`
+          : `    ${lcFirst(camel(c.id))}: () => holon.count(${JSON.stringify(c.id)}),`,
+      );
+    }
+    for (const s of (mod.sums ?? []).map((raw) => finishSum(raw))) {
+      const grouped = s.by != null;
+      methods.push(
+        `    /** Declared sum \`${s.id}\` — the maintained O(1) ${grouped ? `total per \`${s.by}\`` : "grand total"}. */`,
+        grouped
+          ? `    ${lcFirst(camel(s.id))}: (${s.by}: string) => holon.sum(${JSON.stringify(s.id)}, ${s.by}),`
+          : `    ${lcFirst(camel(s.id))}: () => holon.sum(${JSON.stringify(s.id)}),`,
+      );
+    }
+    for (const agg of mod.aggregates as AggregateHandle[]) {
+      methods.push(
+        `    /** Read one ${agg.id} by aggregate id. */`,
+        `    ${lcFirst(camel(agg.id))}ById: (id: string) => holon.queryById(id) as Promise<Row<${agg.id}Data>[]>,`,
+        `    /** Every ${agg.id} (the type-index probe — O(result), not a scan). */`,
+        `    list${agg.id}s: () => holon.query("aggregatesByType", { __type: ${JSON.stringify(agg.id)} }) as Promise<Row<${agg.id}Data>[]>,`,
+        `    /** Watch one ${agg.id} by aggregate id (local reactive read; returns stop()). */`,
+        `    watch${agg.id}ById: (id: string, cb: (rows: Row<${agg.id}Data>[]) => void, opts?: { intervalMs?: number }) =>`,
+        `      holon.watchById(id, cb as (rows: unknown) => void, opts),`,
+      );
+    }
+
+    out.push(
+      `/** Typed client for the \`${domain}\` domain, bound to a connected holon. */`,
+      `export function ${lcFirst(camel(domain))}Client(holon: NomosHolon, domainHash: string = ${hashConst}) {`,
+      `  return {`,
+      `    domain: ${JSON.stringify(domain)} as const,`,
+      `    domainHash,`,
+      ...methods,
+      `  };`,
+      `}`,
+      ``,
+    );
+  }
+
+  return out.join("\n");
+}