@githolon/dsl 0.108.0 → 0.108.1

package/src/codegen_result_usda.ts

@@ -0,0 +1,685 @@
+import type { z } from "zod";
+
+import {
+  admitsNull,
+  isGitObjectIdSchema,
+  isSha256DigestSchema,
+  type Field,
+  type ValueObjectDescriptor,
+  type ValueObjectFieldDescriptor,
+} from "./fields.js";
+import {
+  zodArrayElement,
+  zodDef,
+  zodEnumValues,
+  zodKind,
+  zodObjectShape,
+} from "./zod_introspection.js";
+
+export interface TsResultField {
+  readonly name: string;
+  readonly lawPath: string;
+  readonly field?: Field;
+  readonly projectionSchema?: z.ZodTypeAny;
+  readonly required: boolean;
+  readonly attributed?: boolean;
+}
+
+export interface TsResultAggregate {
+  readonly typeName: string;
+  readonly lawPath: string;
+  readonly fields: readonly TsResultField[];
+}
+
+/** A constrained parser for the canonical USDA emitted by the Nomos kernel.
+ * It is syntax machinery, not a tenant value model: generated decoders below
+ * name every accepted aggregate and field relationship at compile time. */
+export const TS_RESULT_USDA_PRELUDE = [
+  `type _NmsUsdaProperty = { readonly name: string; readonly value: string | number | boolean | readonly string[] };`,
+  `type _NmsUsdaPrim = { readonly typeName: string; readonly name: string; readonly properties: readonly _NmsUsdaProperty[]; readonly children: readonly _NmsUsdaPrim[] };`,
+  `const _nmsUsdaUnquote = (source: string): string => {`,
+  `  if (!source.startsWith('"') || !source.endsWith('"')) throw new Error("invalid USDA string");`,
+  `  let out = "";`,
+  `  for (let i = 1; i < source.length - 1; i += 1) {`,
+  `    const c = source[i]!; if (c !== "\\\\") { out += c; continue; }`,
+  `    const e = source[++i]; if (e === undefined) throw new Error("truncated USDA escape");`,
+  `    if (e === "n") out += "\\n"; else if (e === "r") out += "\\r"; else if (e === "t") out += "\\t";`,
+  `    else if (e === "b") out += "\\b"; else if (e === "f") out += "\\f"; else if (e === '"' || e === "\\\\") out += e;`,
+  `    else if (e === "u") { const hex = source.slice(i + 1, i + 5); if (!/^[0-9a-fA-F]{4}$/.test(hex)) throw new Error("invalid USDA unicode escape"); out += String.fromCharCode(Number.parseInt(hex, 16)); i += 4; }`,
+  `    else throw new Error("unsupported USDA escape: " + e);`,
+  `  } return out;`,
+  `};`,
+  `const _nmsUsdaAtom = (raw: string): string | number | boolean | readonly string[] => {`,
+  `  const value = raw.trim();`,
+  `  if (value.startsWith('"')) return _nmsUsdaUnquote(value);`,
+  `  if (value === "true" || value === "false") return value === "true";`,
+  `  if (/^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$/.test(value)) return Number(value);`,
+  `  if (value.startsWith("<") && value.endsWith(">")) return value.slice(1, -1);`,
+  `  if (value.startsWith("[") && value.endsWith("]")) {`,
+  `    const body = value.slice(1, -1).trim(); if (!body) return [];`,
+  `    return body.split(",").map((entry) => _nmsUsdaAtom(entry)).map((entry) => { if (typeof entry !== "string") throw new Error("USDA relationship array is not textual"); return entry; });`,
+  `  }`,
+  `  throw new Error("unsupported USDA value " + value);`,
+  `};`,
+  `const _nmsParseResultUsda = (bytes: Uint8Array): _NmsUsdaPrim => {`,
+  `  const lines = new TextDecoder("utf-8", { fatal: true }).decode(bytes).split(/\\r?\\n/);`,
+  `  const roots: { typeName: string; name: string; properties: _NmsUsdaProperty[]; children: _NmsUsdaPrim[] }[] = [];`,
+  `  const stack: typeof roots = []; let pending: (typeof roots)[number] | undefined;`,
+  `  for (const original of lines) { const line = original.trim(); if (!line || line.startsWith("#") || line === "(" || line === ")" || line.startsWith("defaultPrim")) continue;`,
+  `    const declaration = /^def\\s+([A-Za-z_][A-Za-z0-9_]*)\\s+("(?:[^"\\\\]|\\\\.)*")$/.exec(line);`,
+  `    if (declaration) { pending = { typeName: declaration[1]!, name: _nmsUsdaUnquote(declaration[2]!), properties: [], children: [] }; continue; }`,
+  `    if (line === "{") { if (!pending) throw new Error("USDA scope has no declaration"); const parent = stack.at(-1); if (parent) parent.children.push(pending); else roots.push(pending); stack.push(pending); pending = undefined; continue; }`,
+  `    if (line === "}") { if (!stack.pop()) throw new Error("unbalanced USDA scope"); continue; }`,
+  `    const property = /^custom(?:\\s+uniform)?\\s+(?:rel|[A-Za-z0-9_\\[\\]]+)\\s+([A-Za-z0-9_:]+)\\s*=\\s*(.+)$/.exec(line);`,
+  `    if (property) { const owner = stack.at(-1); if (!owner) throw new Error("USDA property outside prim"); owner.properties.push({ name: property[1]!, value: _nmsUsdaAtom(property[2]!) }); continue; }`,
+  `    throw new Error("unsupported canonical USDA line: " + line);`,
+  `  }`,
+  `  if (stack.length || roots.length !== 1) throw new Error("USDA result must contain one balanced root prim"); return roots[0]!;`,
+  `};`,
+  `const _nmsUsdaProperty = (prim: _NmsUsdaPrim, name: string) => prim.properties.find((property) => property.name === name)?.value;`,
+  `const _nmsResultUsdaRel = (prim: _NmsUsdaPrim, name: string): string | undefined => { const value = _nmsUsdaProperty(prim, name); return typeof value === "string" ? value : undefined; };`,
+  `const _nmsUsdaRows = (bytes: Uint8Array): readonly _NmsUsdaPrim[] => { const root = _nmsParseResultUsda(bytes); if (root.typeName !== "NomosReadResult") throw new Error("expected NomosReadResult"); const rows = root.children.find((child) => child.typeName === "NomosListValue" && child.name === "Rows"); if (!rows) throw new Error("NomosReadResult has no Rows"); return rows.children; };`,
+  `const _nmsConflictUsdaRows = (bytes: Uint8Array): readonly _NmsUsdaPrim[] => { const root = _nmsParseResultUsda(bytes); if (root.typeName !== "NomosPendingConflicts" || root.name !== "Conflicts") throw new Error("expected NomosPendingConflicts"); const rows = root.children.find((child) => child.typeName === "NomosListValue" && child.name === "Rows"); if (!rows) throw new Error("NomosPendingConflicts has no Rows"); return rows.children; };`,
+  `type _NmsConflictCount = { readonly aggregatePath: string; readonly count: number };`,
+  `type _NmsConflictSummary = { readonly total: number; readonly ready: number; readonly evolutionRequired: number; readonly byAggregate: readonly _NmsConflictCount[] };`,
+  `const _nmsConflictUsdaSummary = (bytes: Uint8Array): _NmsConflictSummary => { const root = _nmsParseResultUsda(bytes); if (root.typeName !== "NomosPendingConflictSummary" || root.name !== "ConflictSummary") throw new Error("expected NomosPendingConflictSummary"); const integer = (name: string): number => { const value = _nmsUsdaProperty(root, name); if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(name + " is not an unsigned integer"); return value; }; const counts = root.children.find((child) => child.typeName === "NomosConflictCounts" && child.name === "ByAggregate"); if (!counts) throw new Error("NomosPendingConflictSummary has no ByAggregate counts"); return { total: integer("nomos:total"), ready: integer("nomos:ready"), evolutionRequired: integer("nomos:evolutionRequired"), byAggregate: counts.children.map((entry) => { const aggregatePath = _nmsResultUsdaRel(entry, "nomos:type"); const count = _nmsUsdaProperty(entry, "nomos:count"); if (aggregatePath === undefined || typeof count !== "number" || !Number.isSafeInteger(count) || count < 0) throw new Error("invalid NomosConflictCount"); return { aggregatePath, count }; }) }; };`,
+  `const _nmsUsdaPage = (bytes: Uint8Array): { readonly rows: readonly _NmsUsdaPrim[]; readonly cursor: string | null; readonly done: boolean } => { const root = _nmsParseResultUsda(bytes); if (root.typeName !== "NomosReadResult") throw new Error("expected NomosReadResult"); const rows = root.children.find((child) => child.typeName === "NomosListValue" && child.name === "Rows"); if (!rows) throw new Error("NomosReadResult has no Rows"); const cursor = _nmsUsdaProperty(root, "nomos:cursor"); const done = _nmsUsdaProperty(root, "nomos:done"); if (cursor !== undefined && typeof cursor !== "string") throw new Error("NomosReadResult cursor is not textual"); if (typeof done !== "boolean") throw new Error("NomosReadResult has no boolean done marker"); return { rows: rows.children, cursor: cursor ?? null, done }; };`,
+  `const _nmsUsdaField = (row: _NmsUsdaPrim, lawPath: string): _NmsUsdaPrim | undefined => row.children.find((child) => _nmsResultUsdaRel(child, "nomos:field") === lawPath);`,
+  `const _nmsUsdaRequired = (row: _NmsUsdaPrim, lawPath: string): _NmsUsdaPrim => { const value = _nmsUsdaField(row, lawPath); if (!value) throw new Error("USDA row omits required law field " + lawPath); return value; };`,
+  `const _nmsUsdaStringValue = (prim: _NmsUsdaPrim): string => { const value = _nmsUsdaProperty(prim, "nomos:value"); if (typeof value !== "string") throw new Error("USDA value is not string/token"); return value; };`,
+  `const _nmsUsdaNumberValue = (prim: _NmsUsdaPrim): number => { const value = _nmsUsdaProperty(prim, "nomos:value"); if (typeof value !== "number") throw new Error("USDA value is not numeric"); return value; };`,
+  `const _nmsUsdaBoolValue = (prim: _NmsUsdaPrim): boolean => { const value = _nmsUsdaProperty(prim, "nomos:value"); if (typeof value !== "boolean") throw new Error("USDA value is not bool"); return value; };`,
+  `const _nmsUsdaJsonValue = (prim: _NmsUsdaPrim): unknown => {`,
+  `  if (prim.typeName === "NomosNullValue") return null; if (prim.typeName === "NomosBoolValue") return _nmsUsdaBoolValue(prim);`,
+  `  if (prim.typeName === "NomosIntValue" || prim.typeName === "NomosNumberValue") return _nmsUsdaNumberValue(prim); if (prim.typeName === "NomosStringValue" || prim.typeName === "NomosTokenValue") return _nmsUsdaStringValue(prim);`,
+  `  if (prim.typeName === "NomosJsonValue") { const value = prim.children.find((child) => child.name === "Value"); if (!value) throw new Error("NomosJsonValue has no Value"); return _nmsUsdaJsonValue(value); }`,
+  `  if (prim.typeName === "NomosJsonArray") return prim.children.map(_nmsUsdaJsonValue);`,
+  `  if (prim.typeName === "NomosJsonObject") { const out: Record<string, unknown> = {}; for (const member of prim.children) { const key = _nmsUsdaProperty(member, "nomos:key"); const value = member.children.find((child) => child.name === "Value"); if (typeof key !== "string" || !value) throw new Error("invalid NomosJsonMember"); out[key] = _nmsUsdaJsonValue(value); } return out; }`,
+  `  throw new Error("unsupported nominal JSON prim " + prim.typeName);`,
+  `};`,
+  `const _nmsUsdaTypedMapValue = <T>(prim: _NmsUsdaPrim, decode: (value: _NmsUsdaPrim, key: string) => T): { readonly [key: string]: T } => { const entries: Array<readonly [string, T]> = []; for (const entry of prim.children) { const key = _nmsUsdaProperty(entry, "nomos:key"); const value = entry.children.find((child) => child.name === "Value"); if (typeof key !== "string" || !value) throw new Error("invalid NomosMapEntry"); entries.push([key, decode(value, key)]); } return Object.fromEntries(entries) as { readonly [key: string]: T }; };`,
+  `const _nmsVoObject = (value: unknown, path: string): object => { if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError(path + " must be an object"); return value; };`,
+  `const _nmsVoField = (value: object, name: string): unknown => Reflect.get(value, name);`,
+  `const _nmsVoExactKeys = (value: object, expected: readonly string[], path: string): void => { const allowed = new Set(expected); for (const key of Object.keys(value)) if (!allowed.has(key)) throw new TypeError(path + " has undeclared field " + key); };`,
+  `const _nmsVoString = (value: unknown, path: string): string => { if (typeof value !== "string") throw new TypeError(path + " must be a string"); return value; };`,
+  `const _nmsVoNumber = (value: unknown, path: string, integer: boolean): number => { if (typeof value !== "number" || !Number.isFinite(value) || (integer && !Number.isInteger(value))) throw new TypeError(path + (integer ? " must be an integer" : " must be a finite number")); return value; };`,
+  `const _nmsVoBoolean = (value: unknown, path: string): boolean => { if (typeof value !== "boolean") throw new TypeError(path + " must be a boolean"); return value; };`,
+  `const _nmsVoArray = (value: unknown, path: string): readonly unknown[] => { if (!Array.isArray(value)) throw new TypeError(path + " must be an array"); return value; };`,
+  `const _nmsVoEnum = <const Values extends readonly string[]>(value: unknown, allowed: Values, path: string): Values[number] => { if (typeof value !== "string" || !allowed.includes(value as Values[number])) throw new TypeError(path + " has an unknown enum value"); return value as Values[number]; };`,
+  `const _nmsVoLiteral = <T extends string>(value: unknown, expected: T, path: string): T => { if (value !== expected) throw new TypeError(path + " must equal " + expected); return expected; };`,
+  `const _nmsVoMap = <T>(value: unknown, path: string, decode: (entry: unknown, key: string) => T): { readonly [key: string]: T } => { const object = _nmsVoObject(value, path); return Object.fromEntries(Object.keys(object).map((key) => [key, decode(_nmsVoField(object, key), key)])) as { readonly [key: string]: T }; };`,
+  ``,
+] as const;
+
+const voSymbol = (value: string): string =>
+  value.replace(/[^A-Za-z0-9_$]+/g, "_").replace(/^[^A-Za-z_$]/, "_$&");
+
+const voDecoderName = (name: string): string =>
+  `_nmsDecodeValueObject_${voSymbol(name)}`;
+
+const voFieldDecode = (
+  field: ValueObjectFieldDescriptor,
+  value: string,
+  path: string,
+  workspace: string
+): string => {
+  switch (field.type) {
+    case "string": {
+      const decoded = `_nmsVoString(${value}, ${path})`;
+      if (field.idOf !== undefined) {
+        return `_nmsRef<${field.idOf}>(${workspace}, ${JSON.stringify(
+          field.idOf
+        )}, ${decoded})`;
+      }
+      if (field.digest === "sha256") return `sha256Digest(${decoded})`;
+      return field.brand === undefined
+        ? decoded
+        : `${decoded} as ${field.brand}`;
+    }
+    case "number":
+      return `_nmsVoNumber(${value}, ${path}, ${
+        field.int === true ? "true" : "false"
+      })`;
+    case "boolean":
+      return `_nmsVoBoolean(${value}, ${path})`;
+    case "enum":
+      return `_nmsVoEnum(${value}, ${JSON.stringify(field.values)}, ${path})`;
+    case "literal":
+      return `_nmsVoLiteral(${value}, ${JSON.stringify(field.value)}, ${path})`;
+    case "array":
+      return `_nmsVoArray(${value}, ${path}).map((entry, index) => ${voFieldDecode(
+        field.items,
+        "entry",
+        `${path} + "[" + index + "]"`,
+        workspace
+      )})`;
+    case "map":
+      return `_nmsVoMap(${value}, ${path}, (entry, key) => ${voFieldDecode(
+        field.values,
+        "entry",
+        `${path} + "." + key`,
+        workspace
+      )})`;
+    case "object":
+    case "geometry":
+      return `${voDecoderName(field.ref)}(${value}, ${workspace}, ${path})`;
+  }
+};
+
+/** Generate exact value-object validators from the descriptor graph that also
+ * generates the public interfaces. An untrusted USDA value becomes nominal
+ * only after every field, optional arm and discriminator has been checked. */
+export function emitTsValueObjectDecoders(
+  descriptors: readonly ValueObjectDescriptor[]
+): readonly string[] {
+  const lines: string[] = [];
+  const geometryDepth = (geometry: string): number => {
+    switch (geometry) {
+      case "Point":
+        return 1;
+      case "LineString":
+      case "MultiPoint":
+        return 2;
+      case "Polygon":
+        return 3;
+      default:
+        throw new Error(`unsupported geometry '${geometry}'`);
+    }
+  };
+  const coordinates = (
+    value: string,
+    path: string,
+    remaining: number
+  ): string =>
+    remaining === 0
+      ? `_nmsVoNumber(${value}, ${path}, false)`
+      : `_nmsVoArray(${value}, ${path}).map((entry, index) => ${coordinates(
+          "entry",
+          `${path} + "[" + index + "]"`,
+          remaining - 1
+        )})`;
+
+  for (const descriptor of descriptors) {
+    const name = voDecoderName(descriptor.name);
+    if (descriptor.geometry !== undefined) {
+      lines.push(
+        `const ${name} = (value: unknown, _workspace: string, path = ${JSON.stringify(
+          descriptor.name
+        )}): ${descriptor.name} => {`,
+        `  const object = _nmsVoObject(value, path); _nmsVoExactKeys(object, ["type", "coordinates"], path);`,
+        `  return { type: _nmsVoLiteral(_nmsVoField(object, "type"), ${JSON.stringify(
+          descriptor.geometry
+        )}, path + ".type"), coordinates: ${coordinates(
+          `_nmsVoField(object, "coordinates")`,
+          `path + ".coordinates"`,
+          geometryDepth(descriptor.geometry)
+        )} };`,
+        `};`,
+        ``
+      );
+      continue;
+    }
+    if (descriptor.union !== undefined) {
+      lines.push(
+        `const ${name} = (value: unknown, workspace: string, path = ${JSON.stringify(
+          descriptor.name
+        )}): ${descriptor.name} => {`,
+        `  const object = _nmsVoObject(value, path); const type = _nmsVoString(_nmsVoField(object, "type"), path + ".type");`,
+        `  switch (type) {`
+      );
+      for (const [armName, arm] of Object.entries(descriptor.union)) {
+        if ("ref" in arm) {
+          lines.push(
+            `    case ${JSON.stringify(
+              armName
+            )}: _nmsVoExactKeys(object, ["type", "value"], path); return { type: ${JSON.stringify(
+              armName
+            )}, value: ${voDecoderName(
+              arm.ref
+            )}(_nmsVoField(object, "value"), workspace, path + ".value") };`
+          );
+          continue;
+        }
+        const fields = Object.entries(arm.fields);
+        lines.push(
+          `    case ${JSON.stringify(armName)}: {`,
+          `      _nmsVoExactKeys(object, ${JSON.stringify([
+            "type",
+            ...fields.map(([field]) => field),
+          ])}, path);`
+        );
+        for (const [field] of fields) {
+          lines.push(
+            `      const field_${voSymbol(
+              field
+            )} = _nmsVoField(object, ${JSON.stringify(field)});`
+          );
+        }
+        lines.push(`      return { type: ${JSON.stringify(armName)},`);
+        for (const [field, spec] of fields) {
+          const raw = `field_${voSymbol(field)}`;
+          const decoded = voFieldDecode(
+            spec,
+            raw,
+            `path + ${JSON.stringify(`.${field}`)}`,
+            "workspace"
+          );
+          lines.push(
+            spec.optional === true
+              ? `        ...(${raw} === undefined ? {} : { ${JSON.stringify(
+                  field
+                )}: ${decoded} }),`
+              : `        ${JSON.stringify(field)}: ${decoded},`
+          );
+        }
+        lines.push(`      };`, `    }`);
+      }
+      lines.push(
+        `    default: throw new TypeError(path + " has unknown discriminator " + type);`,
+        `  }`,
+        `};`,
+        ``
+      );
+      continue;
+    }
+    const fields = Object.entries(descriptor.fields ?? {});
+    lines.push(
+      `const ${name} = (value: unknown, workspace: string, path = ${JSON.stringify(
+        descriptor.name
+      )}): ${descriptor.name} => {`,
+      `  const object = _nmsVoObject(value, path); _nmsVoExactKeys(object, ${JSON.stringify(
+        fields.map(([field]) => field)
+      )}, path);`
+    );
+    for (const [field] of fields) {
+      lines.push(
+        `  const field_${voSymbol(
+          field
+        )} = _nmsVoField(object, ${JSON.stringify(field)});`
+      );
+    }
+    lines.push(`  return {`);
+    for (const [field, spec] of fields) {
+      const raw = `field_${voSymbol(field)}`;
+      const decoded = voFieldDecode(
+        spec,
+        raw,
+        `path + ${JSON.stringify(`.${field}`)}`,
+        "workspace"
+      );
+      lines.push(
+        spec.optional === true
+          ? `    ...(${raw} === undefined ? {} : { ${JSON.stringify(
+              field
+            )}: ${decoded} }),`
+          : `    ${JSON.stringify(field)}: ${decoded},`
+      );
+    }
+    lines.push(`  };`, `};`, ``);
+  }
+  return lines;
+}
+
+const decodeSurfacedScalar = (field: Field, expression: string): string => {
+  const path = JSON.stringify("Surfaced observation value");
+  switch (field.kind) {
+    case "string": {
+      const value = `_nmsVoString(${expression}, ${path})`;
+      return isSha256DigestSchema(field.zod)
+        ? `sha256Digest(${value})`
+        : isGitObjectIdSchema(field.zod)
+        ? `gitObjectId(${value})`
+        : value;
+    }
+    case "position":
+      return `_nmsVoString(${expression}, ${path})`;
+    case "int":
+    case "counter":
+      return `_nmsVoNumber(${expression}, ${path}, true)`;
+    case "bool":
+      return `_nmsVoBoolean(${expression}, ${path})`;
+    case "enum":
+      return `_nmsVoEnum(${expression}, ${JSON.stringify(
+        zodEnumValues(field.zod)
+      )}, ${path})`;
+    case "ref": {
+      const id = `_nmsVoString(${expression}, ${path})`;
+      return field.foreignRef === undefined &&
+        field.nomosRef === undefined &&
+        field.versionedForeignRef === undefined &&
+        field.refAggregateId !== undefined
+        ? `_nmsRef<${field.refAggregateId}>(workspace, ${JSON.stringify(
+            field.refAggregateId
+          )}, ${id})`
+        : id;
+    }
+    default:
+      throw new Error(
+        `result USDA codegen does not support Surfaced field kind '${field.kind}'`
+      );
+  }
+};
+
+/** Emit the value decoder for one observation in the kernel-owned pending
+ * conflict index. The wrapper is framework syntax, while the value itself is
+ * decoded from the same DSL Field that generates the aggregate read model. */
+export const tsConflictObservationValue = (
+  field: Field,
+  expression: string
+): string =>
+  decodeSurfacedScalar(field, `_nmsUsdaJsonValue(${expression})`);
+
+const decode = (field: Field, expression: string): string => {
+  const structured =
+    field.nomosRef !== undefined || field.versionedForeignRef !== undefined;
+  const authored =
+    field.driver.kind === "Surfaced"
+      ? `_nmsDecodeSurfaced(_nmsUsdaJsonValue(${expression}), (value) => ${decodeSurfacedScalar(
+          field,
+          "value"
+        )})`
+      : structured
+      ? `_nmsUsdaJsonValue(${expression})`
+      : (() => {
+          switch (field.kind) {
+            case "string":
+              return isSha256DigestSchema(field.zod)
+                ? `sha256Digest(_nmsUsdaStringValue(${expression}))`
+                : isGitObjectIdSchema(field.zod)
+                ? `gitObjectId(_nmsUsdaStringValue(${expression}))`
+                : `_nmsUsdaStringValue(${expression})`;
+            case "position":
+              return `_nmsUsdaStringValue(${expression})`;
+            case "ref": {
+              // A same-workspace reference is not a string in the generated API. The
+              // kernel's canonical USDA stores its stable id; reconstruct the nominal
+              // reference here while the decoder still has the authenticated workspace.
+              // Foreign/atomic/versioned references need additional generated fields and
+              // are completed by the generated hydration pass immediately afterwards.
+              if (
+                field.foreignRef === undefined &&
+                field.nomosRef === undefined &&
+                field.versionedForeignRef === undefined &&
+                field.refAggregateId !== undefined
+              ) {
+                return `_nmsRef<${
+                  field.refAggregateId
+                }>(workspace, ${JSON.stringify(
+                  field.refAggregateId
+                )}, _nmsUsdaStringValue(${expression}))`;
+              }
+              return `_nmsUsdaStringValue(${expression})`;
+            }
+            case "int":
+            case "counter":
+              return `_nmsUsdaNumberValue(${expression})`;
+            case "bool":
+              return `_nmsUsdaBoolValue(${expression})`;
+            case "enum":
+              return `_nmsUsdaStringValue(${expression}) as ${enumUnion(
+                field
+              )}`;
+            case "set":
+              return `${expression}.children.map(_nmsUsdaStringValue)`;
+            case "json":
+              return field.valueObject === undefined
+                ? `_nmsUsdaJsonValue(${expression}) as ${
+                    field.jsonShape === "object"
+                      ? "Record<string, unknown>"
+                      : "unknown"
+                  }`
+                : `${voDecoderName(
+                    field.valueObject.name
+                  )}(_nmsUsdaJsonValue(${expression}), workspace)`;
+            case "evidence":
+              return `_nmsUsdaJsonValue(${expression}) as EvidenceRef`;
+            case "map": {
+              const inner =
+                field.mapValueKind === "int"
+                  ? "_nmsUsdaNumberValue"
+                  : field.mapValueKind === "json"
+                  ? "_nmsUsdaJsonValue"
+                  : "_nmsUsdaStringValue";
+              const target =
+                field.mapValueVo?.name ??
+                (field.mapValueKind === "int"
+                  ? "number"
+                  : field.mapValueKind === "json"
+                  ? "unknown"
+                  : "string");
+              return field.mapValueVo === undefined
+                ? `_nmsUsdaTypedMapValue<${target}>(${expression}, (value) => ${inner}(value) as ${target})`
+                : `_nmsUsdaTypedMapValue<${target}>(${expression}, (value, key) => ${voDecoderName(
+                    field.mapValueVo.name
+                  )}(_nmsUsdaJsonValue(value), workspace, ${JSON.stringify(
+                    field.mapValueVo.name
+                  )} + "." + key))`;
+            }
+            default:
+              throw new Error(
+                `result USDA codegen does not support field kind '${field.kind}'`
+              );
+          }
+        })();
+  return admitsNull(field)
+    ? `(${expression}.typeName === "NomosNullValue" ? null : ${authored})`
+    : authored;
+};
+
+const projectionPresence = (
+  schema: z.ZodTypeAny
+): { readonly schema: z.ZodTypeAny; readonly optional: boolean } => {
+  let inner = schema;
+  let optional = false;
+  while (zodKind(inner) === "optional" || zodKind(inner) === "default") {
+    optional = true;
+    const next = zodDef(inner).innerType;
+    if (next === undefined) {
+      throw new Error("projection USDA codegen: wrapper has no inner schema");
+    }
+    inner = next;
+  }
+  return { schema: inner, optional };
+};
+
+/** Decode one engine-projected value from the exact schema authored on the read.
+ * This deliberately emits structural validation rather than returning `unknown` and
+ * asserting the desired result type. The read schema is the sole type authority. */
+const decodeProjectionValue = (
+  schema: z.ZodTypeAny,
+  value: string,
+  path: string
+): string => {
+  const { schema: inner } = projectionPresence(schema);
+  switch (zodKind(inner)) {
+    case "nullable": {
+      const nested = zodDef(inner).innerType;
+      if (nested === undefined) {
+        throw new Error("projection USDA codegen: nullable has no inner schema");
+      }
+      return `(${value} === null ? null : ${decodeProjectionValue(
+        nested,
+        value,
+        path
+      )})`;
+    }
+    case "string":
+      return `_nmsVoString(${value}, ${path})`;
+    case "enum":
+      return `_nmsVoEnum(${value}, ${JSON.stringify(
+        zodEnumValues(inner)
+      )}, ${path})`;
+    case "boolean":
+      return `_nmsVoBoolean(${value}, ${path})`;
+    case "number":
+      return `_nmsVoNumber(${value}, ${path}, false)`;
+    case "literal": {
+      const expected = zodDef(inner).values?.[0] ?? zodDef(inner).value;
+      if (typeof expected !== "string") {
+        throw new Error(
+          "projection USDA codegen: only textual literals are supported"
+        );
+      }
+      return `_nmsVoLiteral(${value}, ${JSON.stringify(expected)}, ${path})`;
+    }
+    case "array":
+      return `_nmsVoArray(${value}, ${path}).map((entry, index) => ${decodeProjectionValue(
+        zodArrayElement(inner),
+        "entry",
+        `${path} + "[" + index + "]"`
+      )})`;
+    case "record": {
+      const recordValue = zodDef(inner).valueType;
+      if (recordValue === undefined) {
+        throw new Error("projection USDA codegen: record has no value schema");
+      }
+      return `_nmsVoMap(${value}, ${path}, (entry, key) => ${decodeProjectionValue(
+        recordValue,
+        "entry",
+        `${path} + "." + key`
+      )})`;
+    }
+    case "object": {
+      const fields = Object.entries(zodObjectShape(inner));
+      const expected = JSON.stringify(fields.map(([name]) => name));
+      const members = fields.map(([name, field]) => {
+        const selected = `_nmsVoField(object, ${JSON.stringify(name)})`;
+        const presence = projectionPresence(field);
+        const decoded = decodeProjectionValue(
+          presence.schema,
+          selected,
+          `path + ${JSON.stringify(`.${name}`)}`
+        );
+        return presence.optional
+          ? `...(${selected} === undefined ? {} : { ${JSON.stringify(
+              name
+            )}: ${decoded} })`
+          : `${JSON.stringify(name)}: ${decoded}`;
+      });
+      return `((projected, path) => { const object = _nmsVoObject(projected, path); _nmsVoExactKeys(object, ${expected}, path); return { ${members.join(
+        ", "
+      )} }; })(${value}, ${path})`;
+    }
+    default:
+      throw new Error(
+        `projection USDA codegen: unsupported declared schema '${zodKind(inner)}'`
+      );
+  }
+};
+
+const decodeProjection = (schema: z.ZodTypeAny, expression: string): string =>
+  decodeProjectionValue(
+    schema,
+    `_nmsUsdaJsonValue(${expression})`,
+    JSON.stringify("Projected read value")
+  );
+
+const enumUnion = (field: Field): string => {
+  try {
+    const values = zodEnumValues(field.zod);
+    return values.length
+      ? values.map((value) => JSON.stringify(value)).join(" | ")
+      : "string";
+  } catch {
+    return "string";
+  }
+};
+
+export function emitTsResultDecoder(
+  aggregate: TsResultAggregate
+): readonly string[] {
+  const functionName = `_nmsDecode${aggregate.typeName}Rows`;
+  const local = (name: string) =>
+    `field_${name.replace(/[^A-Za-z0-9_$]/g, "_")}`;
+  const members = aggregate.fields.map(
+    ({ name, lawPath, field, projectionSchema, required }) => {
+      const selected = `_nmsUsdaField(row, ${JSON.stringify(lawPath)})`;
+      const value = required
+        ? `_nmsUsdaRequired(row, ${JSON.stringify(lawPath)})`
+        : `${local(name)}!`;
+      const authored =
+        field !== undefined
+          ? decode(field, value)
+          : projectionSchema !== undefined
+          ? decodeProjection(projectionSchema, value)
+          : (() => {
+              throw new Error(
+                `result USDA decoder field '${name}' has no DSL schema`
+              );
+            })();
+      return required
+        ? `      ${JSON.stringify(name)}: ${authored},`
+        : `      ${JSON.stringify(name)}: (${local(
+            name
+          )} = ${selected}) === undefined ? undefined : ${authored},`;
+    }
+  );
+  const declarations = aggregate.fields
+    .filter((field) => !field.required)
+    .map(({ name }) => `    let ${local(name)}: _NmsUsdaPrim | undefined;`);
+  const attributed = aggregate.fields.filter(
+    (field) => field.attributed === true
+  );
+  const requiresHydration = aggregate.fields.some(
+    ({ field }) =>
+      field !== undefined &&
+      (field.foreignRef !== undefined ||
+        field.nomosRef !== undefined ||
+        field.versionedForeignRef !== undefined)
+  );
+  const dataAssertion = requiresHydration
+    ? ` as unknown as ${aggregate.typeName}`
+    : ` satisfies ${aggregate.typeName}`;
+  const provenance =
+    attributed.length === 0
+      ? []
+      : [
+          `      "__prov": {`,
+          ...attributed.map(({ name, lawPath }) => {
+            const selected = `_nmsUsdaField(row, ${JSON.stringify(lawPath)})`;
+            return `        ...(${selected} === undefined ? {} : { ${JSON.stringify(
+              name
+            )}: { author: typeof _nmsUsdaProperty(${selected}!, "nomos:author") === "string" ? _nmsUsdaProperty(${selected}!, "nomos:author") as string : null, wasContested: _nmsUsdaProperty(${selected}!, "nomos:wasContested") === true } }),`;
+          }),
+          `      },`,
+        ];
+  return [
+    `const ${functionName} = (bytes: Uint8Array, workspace: string): Row<${aggregate.typeName}>[] => _nmsUsdaRows(bytes).map((row) => {`,
+    `  if (_nmsResultUsdaRel(row, "nomos:type") !== ${JSON.stringify(
+      aggregate.lawPath
+    )}) throw new Error("USDA row has the wrong law type for ${
+      aggregate.typeName
+    }");`,
+    `  const id = _nmsUsdaProperty(row, "nomos:id"); if (typeof id !== "string") throw new Error("USDA row has no string identity");`,
+    ...declarations,
+    `  return {`,
+    `    data: {`,
+    ...members,
+    ...provenance,
+    `    }${dataAssertion},`,
+    `    ref: _nmsRef<${aggregate.typeName}>(workspace, ${JSON.stringify(
+      aggregate.typeName
+    )}, id),`,
+    `    type: ${JSON.stringify(aggregate.typeName)},`,
+    `  };`,
+    `});`,
+    `const _nmsDecode${aggregate.typeName}Page = (bytes: Uint8Array, workspace: string): { rows: Row<${aggregate.typeName}>[]; cursor: string | null; done: boolean } => { const page = _nmsUsdaPage(bytes); return { rows: page.rows.map((row) => {`,
+    `  if (_nmsResultUsdaRel(row, "nomos:type") !== ${JSON.stringify(
+      aggregate.lawPath
+    )}) throw new Error("USDA row has the wrong law type for ${
+      aggregate.typeName
+    }");`,
+    `  const id = _nmsUsdaProperty(row, "nomos:id"); if (typeof id !== "string") throw new Error("USDA row has no string identity");`,
+    ...declarations,
+    `  return { data: {`,
+    ...members,
+    ...provenance,
+    `  }${dataAssertion}, ref: _nmsRef<${
+      aggregate.typeName
+    }>(workspace, ${JSON.stringify(
+      aggregate.typeName
+    )}, id), type: ${JSON.stringify(aggregate.typeName)} };`,
+    `}), cursor: page.cursor, done: page.done }; };`,
+    ``,
+  ];
+}