@githolon/dsl 0.108.0 → 0.108.1

package/src/codegen_call_usda.ts

@@ -0,0 +1,1111 @@
+import type {
+  LawAnonymousValueFieldNode,
+  LawAnonymousValueTypeNode,
+  LawAnonymousValueVariantNode,
+  LawGraph,
+  LawIntentNode,
+  LawPayloadContractNode,
+  LawStructuralRef,
+} from "./law_graph.js";
+import { dartMemberName, unionArmClassName } from "./codegen_dart.js";
+
+export interface TsCallUsdaEncoder {
+  readonly functionName: string;
+  readonly source: readonly string[];
+}
+
+export interface TsCallUsdaFieldAccess {
+  readonly value: string;
+  readonly present?: string;
+}
+
+export interface DartCallUsdaFieldAccess {
+  /** Typed Dart expression for this canonical payload field. */
+  readonly value: string;
+  /** Whether an optional/defaulted field is present. Required fields omit this. */
+  readonly present?: string;
+  /** The expression is an exhaustive NomosSlot rather than its contained value. */
+  readonly slot?: true;
+  /** Compile-time proof that an optional framework field is absent. */
+  readonly omit?: true;
+}
+
+export interface DartCallUsdaEncoder {
+  readonly functionName: string;
+  readonly source: readonly string[];
+}
+
+const symbol = (value: string): string =>
+  value.replace(/[^A-Za-z0-9_$]+/g, "_").replace(/^[^A-Za-z_$]/, "_$&");
+
+const requiredPath = (paths: ReadonlyMap<string, string>, id: string, what: string): string => {
+  const path = paths.get(id);
+  if (path === undefined) throw new Error(`call USDA codegen: ${what} '${id}' has no rendered law path`);
+  return path;
+};
+
+const pathLeaf = (path: string): string => path.slice(path.lastIndexOf("/") + 1);
+
+interface NominalSumArm {
+  readonly discriminator: string;
+  readonly variant: LawAnonymousValueVariantNode;
+  readonly value: LawAnonymousValueTypeNode;
+}
+
+/** Resolve only the DSL's nominal `variant(...)` shape. Arbitrary structural
+ * unions remain refused: a generated call must have one stable discriminator,
+ * one exact law variant identity and one statically known arm type. */
+function nominalSumArms(
+  nodes: ReadonlyMap<string, LawGraph["nodes"][number]>,
+  sum: LawAnonymousValueTypeNode,
+  where: string,
+): { readonly name: string; readonly arms: readonly NominalSumArm[] } {
+  if (sum.expression.kind !== "sum" || sum.expression.semantic?.kind !== "value-object") {
+    throw new Error(
+      `${where} contains a structural sum; declare it with variant(...) so its discriminator and arms are nominal`,
+    );
+  }
+  const arms = sum.expression.variants.map((ref): NominalSumArm => {
+    const variant = nodes.get(ref.id);
+    if (variant?.kind !== "structural" || variant.structuralKind !== "value-variant") {
+      throw new Error(`${where} references non-variant '${ref.id}'`);
+    }
+    const value = nodes.get(variant.value.id);
+    if (value?.kind !== "structural" || value.structuralKind !== "value-type" || value.expression.kind !== "record") {
+      throw new Error(`${where} variant '${variant.entity.label}' is not a nominal record arm`);
+    }
+    const discriminator = value.expression.fields.flatMap((fieldRef) => {
+      const field = nodes.get(fieldRef.id);
+      if (
+        field?.kind !== "structural" ||
+        field.structuralKind !== "value-field" ||
+        field.name !== "type" ||
+        field.required !== true
+      ) return [];
+      const type = nodes.get(field.value.id);
+      return type?.kind === "structural" &&
+          type.structuralKind === "value-type" &&
+          type.expression.kind === "literal" &&
+          typeof type.expression.value === "string"
+        ? [type.expression.value]
+        : [];
+    });
+    if (discriminator.length !== 1) {
+      throw new Error(
+        `${where} variant '${variant.entity.label}' does not carry one required literal 'type' discriminator`,
+      );
+    }
+    if (variant.label !== undefined && variant.label !== discriminator[0]) {
+      throw new Error(
+        `${where} variant '${variant.label}' disagrees with discriminator '${discriminator[0]}'`,
+      );
+    }
+    return { discriminator: discriminator[0]!, variant, value };
+  });
+  const discriminators = new Set(arms.map((arm) => arm.discriminator));
+  if (arms.length === 0 || discriminators.size !== arms.length) {
+    throw new Error(`${where} must carry at least one uniquely discriminated nominal variant arm`);
+  }
+  return {
+    name: sum.expression.semantic.name,
+    arms: [...arms].sort((left, right) => left.discriminator.localeCompare(right.discriminator)),
+  };
+}
+
+/** Shared USDA syntax helpers emitted once into a generated TypeScript client.
+ * They write only OpenUSD syntax primitives; domain shape remains expanded into schema-specific
+ * functions by {@link emitTsCallUsdaEncoder}. */
+export const TS_CALL_USDA_PRELUDE = [
+  `declare const _nmsGeneratedCallBrand: unique symbol;`,
+  `interface NmsGeneratedCall<Domain extends string = string, Directive extends string = string> {`,
+  `  readonly domain: Domain;`,
+  `  readonly directive: Directive;`,
+  `  readonly canonicalUsda: Uint8Array;`,
+  `  readonly routingCandidates: readonly string[];`,
+  `  readonly [_nmsGeneratedCallBrand]: readonly [Domain, Directive];`,
+  `}`,
+  `const _nmsGeneratedCall = <Domain extends string, Directive extends string>(domain: Domain, directive: Directive, canonicalUsda: Uint8Array, routingCandidates: readonly string[]): NmsGeneratedCall<Domain, Directive> =>`,
+  `  ({ domain, directive, canonicalUsda, routingCandidates: [...new Set(routingCandidates)] }) as unknown as NmsGeneratedCall<Domain, Directive>;`,
+  ``,
+  `declare const _nmsGeneratedQueryBrand: unique symbol;`,
+  `interface NmsGeneratedQuery<Domain extends string = string, Query extends string = string> {`,
+  `  readonly domain: Domain;`,
+  `  readonly query: Query;`,
+  `  readonly canonicalArgumentsUsda: Uint8Array;`,
+  `  readonly [_nmsGeneratedQueryBrand]: readonly [Domain, Query];`,
+  `}`,
+  `const _nmsGeneratedQuery = <Domain extends string, Query extends string>(domain: Domain, query: Query, canonicalArgumentsUsda: Uint8Array): NmsGeneratedQuery<Domain, Query> =>`,
+  `  ({ domain, query, canonicalArgumentsUsda }) as NmsGeneratedQuery<Domain, Query>;`,
+  ``,
+  // The same generated call encoder runs in browsers, Dart's JS runner and the
+  // sealed QuickJS engine.  TextEncoder is a browser/Node convenience, not an
+  // ECMAScript primitive, so keep UTF-8 lowering inside the generated,
+  // deterministic transport instead of making host globals part of law.
+  `const _nmsUsdaUtf8 = (value: string): Uint8Array => {`,
+  `  const bytes: number[] = [];`,
+  `  for (let index = 0; index < value.length; index += 1) {`,
+  `    let point = value.charCodeAt(index);`,
+  `    if (point >= 0xd800 && point <= 0xdbff && index + 1 < value.length) {`,
+  `      const low = value.charCodeAt(index + 1);`,
+  `      if (low >= 0xdc00 && low <= 0xdfff) { point = 0x10000 + ((point - 0xd800) << 10) + (low - 0xdc00); index += 1; }`,
+  `    }`,
+  `    if (point <= 0x7f) bytes.push(point);`,
+  `    else if (point <= 0x7ff) bytes.push(0xc0 | (point >> 6), 0x80 | (point & 0x3f));`,
+  `    else if (point <= 0xffff) bytes.push(0xe0 | (point >> 12), 0x80 | ((point >> 6) & 0x3f), 0x80 | (point & 0x3f));`,
+  `    else bytes.push(0xf0 | (point >> 18), 0x80 | ((point >> 12) & 0x3f), 0x80 | ((point >> 6) & 0x3f), 0x80 | (point & 0x3f));`,
+  `  }`,
+  `  return Uint8Array.from(bytes);`,
+  `};`,
+  `const _nmsUsdaQuote = (value: string): string => {`,
+  `  let out = "\\\"";`,
+  `  for (const character of value) {`,
+  `    const point = character.codePointAt(0)!;`,
+  `    if (character === "\\\"") out += "\\\\\\\"";`,
+  `    else if (character === "\\\\") out += "\\\\\\\\";`,
+  `    else if (character === "\\n") out += "\\\\n";`,
+  `    else if (character === "\\r") out += "\\\\r";`,
+  `    else if (character === "\\t") out += "\\\\t";`,
+  `    else if (character === "\\b") out += "\\\\b";`,
+  `    else if (character === "\\f") out += "\\\\f";`,
+  `    else if (point < 0x20 || (point >= 0x7f && point <= 0x9f)) out += "\\\\u" + point.toString(16).padStart(4, "0");`,
+  `    else out += character;`,
+  `  }`,
+  `  return out + "\\\"";`,
+  `};`,
+  `const _nmsUsdaLine = (out: string[], depth: number, value: string): void => { out.push("    ".repeat(depth) + value); };`,
+  `const _nmsUsdaBegin = (out: string[], depth: number, type: string, path: string): void => {`,
+  `  const name = path.slice(path.lastIndexOf("/") + 1);`,
+  `  _nmsUsdaLine(out, depth, "def " + type + " " + _nmsUsdaQuote(name));`,
+  `  _nmsUsdaLine(out, depth, "{");`,
+  `};`,
+  `const _nmsUsdaRel = (out: string[], depth: number, name: string, target: string): void =>`,
+  `  _nmsUsdaLine(out, depth, "custom rel " + name + " = <" + target + ">");`,
+  `const _nmsUsdaString = (out: string[], depth: number, type: "string" | "token", name: string, value: string): void =>`,
+  `  _nmsUsdaLine(out, depth, "custom uniform " + type + " " + name + " = " + _nmsUsdaQuote(value));`,
+  `const _nmsUsdaScalar = (out: string[], depth: number, type: "bool" | "int64" | "double", name: string, value: string): void =>`,
+  `  _nmsUsdaLine(out, depth, "custom uniform " + type + " " + name + " = " + value);`,
+  `const _nmsUsdaClose = (out: string[], depth: number): void => _nmsUsdaLine(out, depth, "}");`,
+  `const _nmsUsdaChildren = (out: string[], children: string[]): void => { if (children.length > 0) { out.push(""); out.push(...children); } };`,
+  `const _nmsUsdaDouble = (value: number): string => {`,
+  `  if (!Number.isFinite(value)) throw new TypeError("Nomos USDA numbers must be finite");`,
+  `  return Number.isInteger(value) ? value.toFixed(1) : String(value);`,
+  `};`,
+  `const _nmsUsdaInt = (value: number): string => {`,
+  `  if (!Number.isSafeInteger(value)) throw new TypeError("Nomos USDA integers must be safe integers");`,
+  `  return String(value);`,
+  `};`,
+  ``,
+] as const;
+
+/** OpenUSD syntax primitives for generated Dart clients. These helpers never
+ * inspect domain values: every value access is expanded into a directive-
+ * specific encoder by {@link emitDartCallUsdaEncoder}. */
+export const DART_CALL_USDA_PRELUDE = [
+  `String _nmsUsdaQuote(String value) {`,
+  `  final out = StringBuffer('"');`,
+  `  for (final point in value.runes) {`,
+  `    switch (point) {`,
+  `      case 0x22: out.write(r'\\"');`,
+  `      case 0x5c: out.write(r'\\\\');`,
+  `      case 0x0a: out.write(r'\\n');`,
+  `      case 0x0d: out.write(r'\\r');`,
+  `      case 0x09: out.write(r'\\t');`,
+  `      case 0x08: out.write(r'\\b');`,
+  `      case 0x0c: out.write(r'\\f');`,
+  `      default:`,
+  `        if (point < 0x20 || (point >= 0x7f && point <= 0x9f)) {`,
+  `          out.write('\\\\u\${point.toRadixString(16).padLeft(4, '0')}');`,
+  `        } else {`,
+  `          out.write(String.fromCharCode(point));`,
+  `        }`,
+  `    }`,
+  `  }`,
+  `  return (out..write('"')).toString();`,
+  `}`,
+  `void _nmsUsdaLine(List<String> out, int depth, String value) => out.add('    ' * depth + value);`,
+  `void _nmsUsdaBegin(List<String> out, int depth, String type, String path) {`,
+  `  final name = path.substring(path.lastIndexOf('/') + 1);`,
+  `  _nmsUsdaLine(out, depth, 'def $type \${_nmsUsdaQuote(name)}');`,
+  `  _nmsUsdaLine(out, depth, '{');`,
+  `}`,
+  `void _nmsUsdaRel(List<String> out, int depth, String name, String target) =>`,
+  `    _nmsUsdaLine(out, depth, 'custom rel $name = <$target>');`,
+  `void _nmsUsdaString(List<String> out, int depth, String type, String name, String value) =>`,
+  `    _nmsUsdaLine(out, depth, 'custom uniform $type $name = \${_nmsUsdaQuote(value)}');`,
+  `void _nmsUsdaScalar(List<String> out, int depth, String type, String name, String value) =>`,
+  `    _nmsUsdaLine(out, depth, 'custom uniform $type $name = $value');`,
+  `void _nmsUsdaClose(List<String> out, int depth) => _nmsUsdaLine(out, depth, '}');`,
+  `void _nmsUsdaChildren(List<String> out, List<String> children) {`,
+  `  if (children.isEmpty) return;`,
+  `  out..add('')..addAll(children);`,
+  `}`,
+  `String _nmsUsdaDouble(double value) {`,
+  `  if (!value.isFinite) throw ArgumentError.value(value, 'value', 'Nomos USDA numbers must be finite');`,
+  `  return value == value.truncateToDouble() ? value.toStringAsFixed(1) : value.toString();`,
+  `}`,
+  `String _nmsUsdaInt(num value) {`,
+  `  if (!value.isFinite || value != value.truncateToDouble()) {`,
+  `    throw ArgumentError.value(value, 'value', 'Nomos USDA integers must be finite whole numbers');`,
+  `  }`,
+  `  return value.toInt().toString();`,
+  `}`,
+  ``,
+] as const;
+
+/** Emit one directive-specific encoder directly from the same graph/path projection as law.usda.
+ * No schema descriptor, recursive value bag or runtime field-name lookup survives into the client. */
+export function emitTsCallUsdaEncoder(
+  graph: LawGraph,
+  paths: ReadonlyMap<string, string>,
+  domain: string,
+  directive: string,
+  payloadType: string,
+  access?: ReadonlyMap<string, TsCallUsdaFieldAccess>,
+): TsCallUsdaEncoder {
+  const nodes = new Map<string, LawGraph["nodes"][number]>(
+    graph.nodes.map((node) => [node.entity.id, node]),
+  );
+  const intent = graph.nodes.find((node): node is LawIntentNode =>
+    node.kind === "intent" && (node.entity.label === directive || node.publicRoute === directive));
+  if (intent === undefined) {
+    throw new Error(`call USDA codegen: domain '${domain}' has no law intent for '${directive}'`);
+  }
+  const contract = nodes.get(intent.accepts.id);
+  if (contract?.kind !== "payload-contract") {
+    throw new Error(`call USDA codegen: '${domain}/${directive}' accepts no payload contract`);
+  }
+  const functionName = `_nmsCallUsda_${symbol(domain)}_${symbol(directive)}`;
+  const intentPath = requiredPath(paths, intent.entity.id, "intent");
+  const contractPath = requiredPath(paths, contract.entity.id, "contract");
+  let local = 0;
+  const fresh = (prefix: string): string => `_${prefix}${local++}`;
+
+  const fieldNode = (ref: LawStructuralRef<"value-field">): LawAnonymousValueFieldNode => {
+    const node = nodes.get(ref.id);
+    if (node?.kind !== "structural" || node.structuralKind !== "value-field") {
+      throw new Error(`call USDA codegen: '${ref.id}' is not a value field`);
+    }
+    return node;
+  };
+  const typeNode = (id: string): LawAnonymousValueTypeNode => {
+    const node = nodes.get(id);
+    if (node?.kind !== "structural" || node.structuralKind !== "value-type") {
+      throw new Error(`call USDA codegen: '${id}' is not an anonymous value type`);
+    }
+    return node;
+  };
+
+  const emitValue = (
+    out: string[],
+    value: string,
+    valuePath: string,
+    typeId: string,
+    fieldPath: string | undefined,
+    depth: number,
+    valueIsCanonical = false,
+  ): void => {
+    const node = typeNode(typeId);
+    const typePath = requiredPath(paths, typeId, "value type");
+    const semantic = node.expression.semantic;
+    const fieldLabel = fieldPath ?? typePath;
+    const lowersNominalReference = semantic?.kind === "id-reference" ||
+      semantic?.kind === "address-reference" ||
+      semantic?.kind === "versioned-reference" ||
+      semantic?.kind === "recipient";
+    const canonicalValue = valueIsCanonical || semantic === undefined
+      ? value
+      : semantic.kind === "id-reference"
+        ? `_nmsReferenceId(${value}, ${JSON.stringify(semantic.target)}, nmsInternalWorkspace, ${JSON.stringify(fieldLabel)})`
+        : semantic.kind === "address-reference"
+          ? `_nmsCheckedReferenceData(${value}, ${JSON.stringify(semantic.target)}, "", ${JSON.stringify(fieldLabel)})`
+          : semantic.kind === "versioned-reference"
+            ? `({ pinned: _nmsReferenceData(${value}.pinned), series: _nmsReferenceData(${value}.series) })`
+            : semantic.kind === "recipient"
+              ? `_nmsRecipientAddress(${value}, ${JSON.stringify(fieldLabel)})`
+              : value;
+    const begin = (primType: string): void => {
+      out.push(`_nmsUsdaBegin(${outName}, ${depth}, ${JSON.stringify(primType)}, ${valuePath});`);
+      if (fieldPath !== undefined) {
+        out.push(`_nmsUsdaRel(${outName}, ${depth + 1}, "nomos:field", ${JSON.stringify(fieldPath)});`);
+      }
+      out.push(`_nmsUsdaRel(${outName}, ${depth + 1}, "nomos:type", ${JSON.stringify(typePath)});`);
+    };
+    const outName = fresh("out");
+    // Each value writes into its own lexical alias. This lets nested records/lists collect children
+    // without a generic tree representation and keeps every generated field access explicit.
+    out.push(`{ const ${outName} = ${currentOut};`);
+    switch (node.expression.kind) {
+      case "default":
+        emitValue(out, canonicalValue, valuePath, node.expression.value.id, fieldPath, depth, valueIsCanonical);
+        break;
+      case "recursive":
+        throw new Error(
+          `call USDA codegen: '${domain}/${directive}' contains recursive values; ` +
+            "add a schema-specific bounded representation before release",
+        );
+      case "nullable":
+        {
+        const nullable = fresh("nullable");
+        out.push(`const ${nullable} = ${canonicalValue};`);
+        out.push(`if (${nullable} === null) {`);
+        begin("NomosNullValue");
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        out.push(`} else {`);
+        emitValue(
+          out,
+          nullable,
+          valuePath,
+          node.expression.value.id,
+          fieldPath,
+          depth,
+          valueIsCanonical,
+        );
+        out.push(`}`);
+        break;
+        }
+      case "string":
+        out.push(`_nmsRoutingCandidates.push(${canonicalValue});`);
+        begin("NomosStringValue");
+        out.push(`_nmsUsdaString(${outName}, ${depth + 1}, "string", "nomos:value", ${canonicalValue});`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      case "enum":
+        begin("NomosTokenValue");
+        out.push(`_nmsUsdaString(${outName}, ${depth + 1}, "token", "nomos:value", ${canonicalValue});`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      case "integer":
+        begin("NomosIntValue");
+        out.push(`_nmsUsdaScalar(${outName}, ${depth + 1}, "int64", "nomos:value", _nmsUsdaInt(${canonicalValue}));`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      case "number":
+        begin("NomosNumberValue");
+        out.push(`_nmsUsdaScalar(${outName}, ${depth + 1}, "double", "nomos:value", _nmsUsdaDouble(${canonicalValue}));`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      case "boolean":
+        begin("NomosBoolValue");
+        out.push(`_nmsUsdaScalar(${outName}, ${depth + 1}, "bool", "nomos:value", ${canonicalValue} ? "true" : "false");`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      case "null":
+        begin("NomosNullValue");
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      case "literal": {
+        const literal = node.expression.value;
+        if (typeof literal === "string") {
+          out.push(`_nmsRoutingCandidates.push(${JSON.stringify(literal)});`);
+          begin("NomosStringValue");
+          out.push(`_nmsUsdaString(${outName}, ${depth + 1}, "string", "nomos:value", ${JSON.stringify(literal)});`);
+        } else if (typeof literal === "boolean") {
+          begin("NomosBoolValue");
+          out.push(`_nmsUsdaScalar(${outName}, ${depth + 1}, "bool", "nomos:value", ${literal ? '"true"' : '"false"'});`);
+        } else if (typeof literal === "number" && Number.isInteger(literal)) {
+          begin("NomosIntValue");
+          out.push(`_nmsUsdaScalar(${outName}, ${depth + 1}, "int64", "nomos:value", _nmsUsdaInt(${literal}));`);
+        } else if (typeof literal === "number") {
+          begin("NomosNumberValue");
+          out.push(`_nmsUsdaScalar(${outName}, ${depth + 1}, "double", "nomos:value", _nmsUsdaDouble(${literal}));`);
+        } else {
+          throw new Error(`call USDA codegen: unsupported literal in '${domain}/${directive}'`);
+        }
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      }
+      case "record": {
+        begin("NomosRecordValue");
+        const children = fresh("children");
+        out.push(`const ${children}: string[] = [];`);
+        for (const ref of node.expression.fields) {
+          const child = fieldNode(ref);
+          const childPath = requiredPath(paths, child.entity.id, "value field");
+          const expression = `${canonicalValue}[${JSON.stringify(child.name)}]`;
+          const body: string[] = [];
+          if (child.required) {
+            withOut(children, () => emitValue(
+              body,
+              expression,
+              `${valuePath} + ${JSON.stringify(`/${pathLeaf(childPath)}`)}`,
+              child.value.id,
+              childPath,
+              depth + 1,
+              valueIsCanonical || lowersNominalReference,
+            ));
+            out.push(...body);
+          } else {
+            const optional = fresh("optional");
+            withOut(children, () => emitValue(
+              body,
+              optional,
+              `${valuePath} + ${JSON.stringify(`/${pathLeaf(childPath)}`)}`,
+              child.value.id,
+              childPath,
+              depth + 1,
+              valueIsCanonical || lowersNominalReference,
+            ));
+            out.push(
+              `const ${optional} = ${expression};`,
+              `if (${optional} !== undefined) {`,
+              ...body,
+              `}`,
+            );
+          }
+        }
+        out.push(`_nmsUsdaChildren(${outName}, ${children});`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      }
+      case "list": {
+        const elementTypeId = node.expression.element.id;
+        begin("NomosListValue");
+        const children = fresh("children");
+        const index = fresh("index");
+        out.push(`const ${children}: string[] = [];`);
+        out.push(`for (let ${index} = 0; ${index} < ${canonicalValue}.length; ${index}++) {`);
+        const body: string[] = [];
+        withOut(children, () => emitValue(
+          body,
+          `${canonicalValue}[${index}]!`,
+          `${valuePath} + "/i_" + String(${index}).padStart(8, "0")`,
+          elementTypeId,
+          undefined,
+          depth + 1,
+        ));
+        out.push(...body, `}`);
+        out.push(`_nmsUsdaChildren(${outName}, ${children});`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      }
+      case "map": {
+        const mapValueTypeId = node.expression.value.id;
+        begin("NomosMapValue");
+        const children = fresh("children");
+        const entries = fresh("entries");
+        const index = fresh("index");
+        const key = fresh("key");
+        const entryValue = fresh("value");
+        const entryPath = fresh("entryPath");
+        out.push(`const ${children}: string[] = [];`);
+        out.push(`const ${entries} = Object.entries(${canonicalValue}).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);`);
+        out.push(`for (let ${index} = 0; ${index} < ${entries}.length; ${index}++) {`);
+        out.push(`const [${key}, ${entryValue}] = ${entries}[${index}]!;`);
+        out.push(`_nmsRoutingCandidates.push(${key});`);
+        out.push(`const ${entryPath} = ${valuePath} + "/e_" + String(${index}).padStart(8, "0");`);
+        out.push(`_nmsUsdaBegin(${children}, ${depth + 1}, "NomosMapEntry", ${entryPath});`);
+        out.push(`_nmsUsdaString(${children}, ${depth + 2}, "string", "nomos:key", ${key});`);
+        const body: string[] = [];
+        withOut(children, () => emitValue(
+          body,
+          entryValue,
+          `${entryPath} + "/Value"`,
+          mapValueTypeId,
+          undefined,
+          depth + 2,
+        ));
+        out.push(`if (${body.length} > 0) ${children}.push("");`, ...body);
+        out.push(`_nmsUsdaClose(${children}, ${depth + 1});`, `}`);
+        out.push(`_nmsUsdaChildren(${outName}, ${children});`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      }
+      case "sum": {
+        const nominal = nominalSumArms(nodes, node, `call USDA codegen: '${domain}/${directive}'`);
+        const selected = fresh("sum");
+        const discriminator = fresh("discriminator");
+        out.push(`const ${selected} = ${canonicalValue};`);
+        out.push(`const ${discriminator} = ${selected}.type;`);
+        out.push(`switch (${discriminator}) {`);
+        for (const arm of nominal.arms) {
+          const armValue = fresh("arm");
+          const variantPath = requiredPath(paths, arm.variant.entity.id, "value variant");
+          out.push(`case ${JSON.stringify(arm.discriminator)}: {`);
+          out.push(`const ${armValue} = ${selected};`);
+          begin("NomosSumValue");
+          out.push(`_nmsUsdaRel(${outName}, ${depth + 1}, "nomos:variant", ${JSON.stringify(variantPath)});`);
+          const children = fresh("children");
+          out.push(`const ${children}: string[] = [];`);
+          const body: string[] = [];
+          withOut(children, () => emitValue(
+            body,
+            armValue,
+            `${valuePath} + "/Value"`,
+            arm.value.entity.id,
+            undefined,
+            depth + 1,
+          ));
+          out.push(...body);
+          out.push(`_nmsUsdaChildren(${outName}, ${children});`);
+          out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+          out.push(`break;`, `}`);
+        }
+        out.push(
+          `default: throw new TypeError(${JSON.stringify(`Unknown ${nominal.name} variant arm`)} + ": " + String(${discriminator}));`,
+          `}`,
+        );
+        break;
+      }
+      case "unknown":
+        throw new Error(
+          `call USDA codegen: '${domain}/${directive}' contains ${node.expression.kind}; ` +
+          `replace the unstructured value or add a schema-specific sum encoder before release`,
+        );
+    }
+    out.push(`}`);
+  };
+
+  let currentOut = "out";
+  const withOut = (name: string, fn: () => void): void => {
+    const prior = currentOut;
+    currentOut = name;
+    try { fn(); } finally { currentOut = prior; }
+  };
+
+  const lines = [
+    `function ${functionName}(payload: ${payloadType}, nmsInternalWorkspace: string): NmsGeneratedCall<${JSON.stringify(domain)}, ${JSON.stringify(directive)}> {`,
+    `  const _nmsRoutingCandidates: string[] = [];`,
+    `  const out = [`,
+    `    "#usda 1.0",`,
+    `    "(",`,
+    `    "    defaultPrim = \\"Change\\"",`,
+    `    ")",`,
+    `    "",`,
+    `    "def NomosChange \\"Change\\"",`,
+    `    "{",`,
+    `    "    custom rel nomos:directive = <${intentPath}>",`,
+    `    "",`,
+    `    "    def NomosCall \\"Call\\"",`,
+    `    "    {",`,
+    `    "        custom rel nomos:contract = <${contractPath}>",`,
+    `    "",`,
+    `    "        def NomosRecordValue \\"Payload\\"",`,
+    `    "        {",`,
+    `    "            custom rel nomos:type = <${contractPath}>",`,
+    `  ];`,
+  ];
+  const children = fresh("payloadChildren");
+  lines.push(`  const ${children}: string[] = [];`);
+  for (const ref of (contract as LawPayloadContractNode).fields) {
+    const field = fieldNode(ref);
+    const path = requiredPath(paths, field.entity.id, "payload field");
+    const fieldAccess = access?.get(field.name);
+    // A generated caller can prove a compiler-owned optional field is absent.
+    // Do not emit a dead encoder body: TypeScript still checks unreachable
+    // branches, and absence must not require a fake sentinel of the field type.
+    if (fieldAccess?.present === "false") continue;
+    const expression = fieldAccess?.value ?? `payload[${JSON.stringify(field.name)}]`;
+    const fieldSemantic = typeNode(field.value.id).expression.semantic;
+    const fieldValueIsCanonical = fieldAccess !== undefined && (
+      fieldSemantic?.kind === "id-reference" ||
+      fieldSemantic?.kind === "address-reference" ||
+      fieldSemantic?.kind === "versioned-reference" ||
+      fieldSemantic?.kind === "recipient"
+    );
+    const body: string[] = [];
+    if (field.required) {
+      withOut(children, () => emitValue(
+        body,
+        expression,
+        JSON.stringify(`/Change/Call/Payload/${pathLeaf(path)}`),
+        field.value.id,
+        path,
+        3,
+        fieldValueIsCanonical,
+      ));
+      lines.push(...body.map((line) => `  ${line}`));
+    } else {
+      const optional = fresh("optional");
+      withOut(children, () => emitValue(
+        body,
+        optional,
+        JSON.stringify(`/Change/Call/Payload/${pathLeaf(path)}`),
+        field.value.id,
+        path,
+        3,
+        fieldValueIsCanonical,
+      ));
+      lines.push(
+        `  if (${fieldAccess?.present ?? `${expression} !== undefined`}) {`,
+        `    const ${optional} = ${expression};`,
+        ...body.map((line) => `    ${line}`),
+        `  }`,
+      );
+    }
+  }
+  lines.push(
+    `  _nmsUsdaChildren(out, ${children});`,
+    `  _nmsUsdaClose(out, 2);`,
+    `  _nmsUsdaClose(out, 1);`,
+    `  _nmsUsdaClose(out, 0);`,
+    `  return _nmsGeneratedCall(${JSON.stringify(domain)}, ${JSON.stringify(directive)}, _nmsUsdaUtf8(out.join("\\n") + "\\n"), _nmsRoutingCandidates);`,
+    `}`,
+    ``,
+  );
+  return { functionName, source: lines };
+}
+
+const dartString = (value: string): string =>
+  `'${value
+    .replace(/\\/g, "\\\\")
+    .replace(/'/g, "\\'")
+    .replace(/\$/g, "\\$")}'`;
+
+/** Emit one schema-specific Dart encoder for the same canonical call USDA as
+ * the TypeScript client. The caller supplies compile-time field expressions;
+ * generated code never reflects over a payload or builds a recursive value
+ * bag. Unsupported shapes refuse package compilation. */
+export function emitDartCallUsdaEncoder(
+  graph: LawGraph,
+  paths: ReadonlyMap<string, string>,
+  domain: string,
+  directive: string,
+  payloadType: string,
+  access: ReadonlyMap<string, DartCallUsdaFieldAccess>,
+  extraParameters: readonly string[] = [],
+): DartCallUsdaEncoder {
+  const nodes = new Map<string, LawGraph["nodes"][number]>(
+    graph.nodes.map((node) => [node.entity.id, node]),
+  );
+  const intent = graph.nodes.find((node): node is LawIntentNode =>
+    node.kind === "intent" &&
+    (node.entity.label === directive || node.publicRoute === directive));
+  if (intent === undefined) {
+    throw new Error(`Dart call USDA codegen: domain '${domain}' has no law intent for '${directive}'`);
+  }
+  const contract = nodes.get(intent.accepts.id);
+  if (contract?.kind !== "payload-contract") {
+    throw new Error(`Dart call USDA codegen: '${domain}/${directive}' accepts no payload contract`);
+  }
+  const functionName = `_nmsCallUsda_${symbol(domain)}_${symbol(directive)}`;
+  const intentPath = requiredPath(paths, intent.entity.id, "intent");
+  const contractPath = requiredPath(paths, contract.entity.id, "contract");
+  let local = 0;
+  const fresh = (prefix: string): string => `_${prefix}${local++}`;
+
+  const fieldNode = (ref: LawStructuralRef<"value-field">): LawAnonymousValueFieldNode => {
+    const node = nodes.get(ref.id);
+    if (node?.kind !== "structural" || node.structuralKind !== "value-field") {
+      throw new Error(`Dart call USDA codegen: '${ref.id}' is not a value field`);
+    }
+    return node;
+  };
+  const typeNode = (id: string): LawAnonymousValueTypeNode => {
+    const node = nodes.get(id);
+    if (node?.kind !== "structural" || node.structuralKind !== "value-type") {
+      throw new Error(`Dart call USDA codegen: '${id}' is not an anonymous value type`);
+    }
+    return node;
+  };
+
+  let currentOut = "out";
+  const withOut = (name: string, fn: () => void): void => {
+    const prior = currentOut;
+    currentOut = name;
+    try {
+      fn();
+    } finally {
+      currentOut = prior;
+    }
+  };
+
+  const emitValue = (
+    out: string[],
+    value: string,
+    valuePath: string,
+    typeId: string,
+    fieldPath: string | undefined,
+    depth: number,
+    valueIsCanonical = false,
+  ): void => {
+    const node = typeNode(typeId);
+    const typePath = requiredPath(paths, typeId, "value type");
+    const semantic = node.expression.semantic;
+    const lowersNominalReference = semantic?.kind === "id-reference" ||
+      semantic?.kind === "address-reference" ||
+      semantic?.kind === "versioned-reference" ||
+      semantic?.kind === "recipient";
+    const canonicalValue = valueIsCanonical || semantic === undefined
+      ? value
+      : semantic.kind === "id-reference"
+        ? `NmsInternalNomosRefs.id(${value})`
+        : semantic.kind === "address-reference"
+          ? `(workspace: NmsInternalNomosRefs.workspace(${value}), type: NmsInternalNomosRefs.type(${value}), id: NmsInternalNomosRefs.id(${value}))`
+          : semantic.kind === "versioned-reference"
+            ? `(pinned: (workspace: NmsInternalNomosRefs.workspace(${value}.pinned), type: NmsInternalNomosRefs.type(${value}.pinned), id: NmsInternalNomosRefs.id(${value}.pinned)), series: (workspace: NmsInternalNomosRefs.workspace(${value}.series), type: NmsInternalNomosRefs.type(${value}.series), id: NmsInternalNomosRefs.id(${value}.series)))`
+            : semantic.kind === "recipient"
+              ? `NmsInternalRecipients.address(${value})`
+              : semantic.kind === "sha256-digest" ||
+                  semantic.kind === "git-object-id" ||
+                  semantic.kind === "branded-id" ||
+                  semantic.kind === "unit"
+                ? `${value}.value`
+                : value;
+    const outName = fresh("out");
+    const begin = (primitive: string): void => {
+      out.push(`_nmsUsdaBegin(${outName}, ${depth}, ${dartString(primitive)}, ${valuePath});`);
+      if (fieldPath !== undefined) {
+        out.push(`_nmsUsdaRel(${outName}, ${depth + 1}, 'nomos:field', ${dartString(fieldPath)});`);
+      }
+      out.push(`_nmsUsdaRel(${outName}, ${depth + 1}, 'nomos:type', ${dartString(typePath)});`);
+    };
+    out.push(`{ final ${outName} = ${currentOut};`);
+    switch (node.expression.kind) {
+      case "default":
+      case "recursive":
+        emitValue(out, canonicalValue, valuePath, node.expression.value.id, fieldPath, depth, valueIsCanonical);
+        break;
+      case "nullable": {
+        const nullable = fresh("nullable");
+        out.push(`final ${nullable} = ${canonicalValue};`);
+        out.push(`if (${nullable} == null) {`);
+        begin("NomosNullValue");
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        out.push(`} else {`);
+        emitValue(
+          out,
+          nullable,
+          valuePath,
+          node.expression.value.id,
+          fieldPath,
+          depth,
+          valueIsCanonical,
+        );
+        out.push(`}`);
+        break;
+      }
+      case "string":
+        begin("NomosStringValue");
+        out.push(`_nmsUsdaString(${outName}, ${depth + 1}, 'string', 'nomos:value', ${canonicalValue});`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      case "enum":
+        begin("NomosTokenValue");
+        out.push(`_nmsUsdaString(${outName}, ${depth + 1}, 'token', 'nomos:value', ${canonicalValue}.wire);`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      case "integer":
+        begin("NomosIntValue");
+        out.push(`_nmsUsdaScalar(${outName}, ${depth + 1}, 'int64', 'nomos:value', _nmsUsdaInt(${canonicalValue}));`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      case "number":
+        begin("NomosNumberValue");
+        out.push(`_nmsUsdaScalar(${outName}, ${depth + 1}, 'double', 'nomos:value', _nmsUsdaDouble((${canonicalValue}).toDouble()));`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      case "boolean":
+        begin("NomosBoolValue");
+        out.push(`_nmsUsdaScalar(${outName}, ${depth + 1}, 'bool', 'nomos:value', ${canonicalValue} ? 'true' : 'false');`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      case "null":
+        begin("NomosNullValue");
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      case "literal": {
+        const literal = node.expression.value;
+        if (typeof literal === "string") {
+          begin("NomosStringValue");
+          out.push(`_nmsUsdaString(${outName}, ${depth + 1}, 'string', 'nomos:value', ${dartString(literal)});`);
+        } else if (typeof literal === "boolean") {
+          begin("NomosBoolValue");
+          out.push(`_nmsUsdaScalar(${outName}, ${depth + 1}, 'bool', 'nomos:value', '${literal ? "true" : "false"}');`);
+        } else if (typeof literal === "number" && Number.isInteger(literal)) {
+          begin("NomosIntValue");
+          out.push(`_nmsUsdaScalar(${outName}, ${depth + 1}, 'int64', 'nomos:value', _nmsUsdaInt(${literal}));`);
+        } else if (typeof literal === "number") {
+          begin("NomosNumberValue");
+          out.push(`_nmsUsdaScalar(${outName}, ${depth + 1}, 'double', 'nomos:value', _nmsUsdaDouble(${literal}));`);
+        } else {
+          throw new Error(`Dart call USDA codegen: unsupported literal in '${domain}/${directive}'`);
+        }
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      }
+      case "record": {
+        begin("NomosRecordValue");
+        const children = fresh("children");
+        out.push(`final ${children} = <String>[];`);
+        for (const ref of node.expression.fields) {
+          const child = fieldNode(ref);
+          const childPath = requiredPath(paths, child.entity.id, "value field");
+          const expression = `${canonicalValue}.${dartMemberName(child.name)}`;
+          const body: string[] = [];
+          if (child.required) {
+            withOut(children, () =>
+              emitValue(
+                body,
+                expression,
+                `${valuePath} + ${dartString(`/${pathLeaf(childPath)}`)}`,
+                child.value.id,
+                childPath,
+                depth + 1,
+                valueIsCanonical || lowersNominalReference,
+              ));
+            out.push(...body);
+          } else {
+            const optional = fresh("optional");
+            withOut(children, () =>
+              emitValue(
+                body,
+                optional,
+                `${valuePath} + ${dartString(`/${pathLeaf(childPath)}`)}`,
+                child.value.id,
+                childPath,
+                depth + 1,
+                valueIsCanonical || lowersNominalReference,
+              ));
+            out.push(
+              `final ${optional} = ${expression};`,
+              `if (${optional} != null) {`,
+              ...body,
+              `}`,
+            );
+          }
+        }
+        out.push(`_nmsUsdaChildren(${outName}, ${children});`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      }
+      case "list": {
+        const elementTypeId = node.expression.element.id;
+        begin("NomosListValue");
+        const children = fresh("children");
+        const index = fresh("index");
+        out.push(`final ${children} = <String>[];`);
+        out.push(`for (var ${index} = 0; ${index} < ${canonicalValue}.length; ${index}++) {`);
+        const body: string[] = [];
+        withOut(children, () =>
+          emitValue(
+            body,
+            `${canonicalValue}[${index}]`,
+            `${valuePath} + '/i_' + ${index}.toString().padLeft(8, '0')`,
+            elementTypeId,
+            undefined,
+            depth + 1,
+          ));
+        out.push(...body, `}`);
+        out.push(`_nmsUsdaChildren(${outName}, ${children});`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      }
+      case "map": {
+        const mapValueTypeId = node.expression.value.id;
+        begin("NomosMapValue");
+        const children = fresh("children");
+        const entries = fresh("entries");
+        const index = fresh("index");
+        const entry = fresh("entry");
+        const entryPath = fresh("entryPath");
+        out.push(`final ${children} = <String>[];`);
+        out.push(`final ${entries} = ${canonicalValue}.entries.toList()..sort((left, right) => left.key.compareTo(right.key));`);
+        out.push(`for (var ${index} = 0; ${index} < ${entries}.length; ${index}++) {`);
+        out.push(`final ${entry} = ${entries}[${index}];`);
+        out.push(`final ${entryPath} = ${valuePath} + '/e_' + ${index}.toString().padLeft(8, '0');`);
+        out.push(`_nmsUsdaBegin(${children}, ${depth + 1}, 'NomosMapEntry', ${entryPath});`);
+        out.push(`_nmsUsdaString(${children}, ${depth + 2}, 'string', 'nomos:key', ${entry}.key);`);
+        const body: string[] = [];
+        withOut(children, () =>
+          emitValue(
+            body,
+            `${entry}.value`,
+            `${entryPath} + '/Value'`,
+            mapValueTypeId,
+            undefined,
+            depth + 2,
+          ));
+        out.push(`if (${body.length} > 0) ${children}.add('');`, ...body);
+        out.push(`_nmsUsdaClose(${children}, ${depth + 1});`, `}`);
+        out.push(`_nmsUsdaChildren(${outName}, ${children});`);
+        out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+        break;
+      }
+      case "sum": {
+        const nominal = nominalSumArms(nodes, node, `Dart call USDA codegen: '${domain}/${directive}'`);
+        const selected = fresh("sum");
+        out.push(`final ${selected} = ${canonicalValue};`);
+        nominal.arms.forEach((arm, index) => {
+          const armType = unionArmClassName(nominal.name, arm.discriminator);
+          const armValue = fresh("arm");
+          const variantPath = requiredPath(paths, arm.variant.entity.id, "value variant");
+          out.push(`${index === 0 ? "if" : "else if"} (${selected} is ${armType}) {`);
+          out.push(`final ${armValue} = ${selected} as ${armType};`);
+          begin("NomosSumValue");
+          out.push(`_nmsUsdaRel(${outName}, ${depth + 1}, 'nomos:variant', ${dartString(variantPath)});`);
+          const children = fresh("children");
+          out.push(`final ${children} = <String>[];`);
+          const body: string[] = [];
+          withOut(children, () => emitValue(
+            body,
+            armValue,
+            `${valuePath} + '/Value'`,
+            arm.value.entity.id,
+            undefined,
+            depth + 1,
+          ));
+          out.push(...body);
+          out.push(`_nmsUsdaChildren(${outName}, ${children});`);
+          out.push(`_nmsUsdaClose(${outName}, ${depth});`);
+          out.push(`}`);
+        });
+        out.push(
+          `else { throw ArgumentError.value(${selected}, ${dartString(nominal.name)}, ${dartString("Unknown nominal variant arm")}); }`,
+        );
+        break;
+      }
+      case "unknown":
+        throw new Error(
+          `Dart call USDA codegen: '${domain}/${directive}' contains ${node.expression.kind}; ` +
+          "replace the unstructured value or generate an exhaustive sum encoder before release",
+        );
+    }
+    out.push(`}`);
+  };
+
+  const lines = [
+    `NmsGeneratedCall ${functionName}(${[
+      `${payloadType} payload`,
+      ...extraParameters,
+    ].join(", ")}) {`,
+    `  final out = <String>[`,
+    `    '#usda 1.0',`,
+    `    '(',`,
+    `    '    defaultPrim = "Change"',`,
+    `    ')',`,
+    `    '',`,
+    `    'def NomosChange "Change"',`,
+    `    '{',`,
+    `    '    custom rel nomos:directive = <${intentPath}>',`,
+    `    '',`,
+    `    '    def NomosCall "Call"',`,
+    `    '    {',`,
+    `    '        custom rel nomos:contract = <${contractPath}>',`,
+    `    '',`,
+    `    '        def NomosRecordValue "Payload"',`,
+    `    '        {',`,
+    `    '            custom rel nomos:type = <${contractPath}>',`,
+    `  ];`,
+  ];
+  const children = fresh("payloadChildren");
+  lines.push(`  final ${children} = <String>[];`);
+  for (const ref of (contract as LawPayloadContractNode).fields) {
+    const field = fieldNode(ref);
+    const fieldAccess = access.get(field.name);
+    if (fieldAccess === undefined) {
+      throw new Error(
+        `Dart call USDA codegen: '${domain}/${directive}' has no typed access for '${field.name}'`,
+      );
+    }
+    if (fieldAccess.omit === true) {
+      if (field.required) {
+        throw new Error(
+          `Dart call USDA codegen: required '${domain}/${directive}.${field.name}' cannot be omitted`,
+        );
+      }
+      continue;
+    }
+    const path = requiredPath(paths, field.entity.id, "payload field");
+    const fieldSemantic = typeNode(field.value.id).expression.semantic;
+    const fieldValueIsCanonical = fieldSemantic?.kind === "id-reference" ||
+      fieldSemantic?.kind === "address-reference" ||
+      fieldSemantic?.kind === "versioned-reference" ||
+      fieldSemantic?.kind === "recipient" ||
+      fieldSemantic?.kind === "sha256-digest" ||
+      fieldSemantic?.kind === "git-object-id" ||
+      fieldSemantic?.kind === "branded-id" ||
+      fieldSemantic?.kind === "unit";
+    if (fieldAccess.slot === true) {
+      const nullable = typeNode(field.value.id);
+      if (nullable.expression.kind !== "nullable") {
+        throw new Error(
+          `Dart call USDA codegen: slot '${domain}/${directive}.${field.name}' is not nullable in the canonical contract`,
+        );
+      }
+      const nullableInnerType = nullable.expression.value.id;
+      const nullablePath = requiredPath(paths, field.value.id, "nullable value type");
+      const nullBody = [
+        `_nmsUsdaBegin(${children}, 3, 'NomosNullValue', ${dartString(`/Change/Call/Payload/${pathLeaf(path)}`)});`,
+        `_nmsUsdaRel(${children}, 4, 'nomos:field', ${dartString(path)});`,
+        `_nmsUsdaRel(${children}, 4, 'nomos:type', ${dartString(nullablePath)});`,
+        `_nmsUsdaClose(${children}, 3);`,
+      ];
+      const presentBody: string[] = [];
+      withOut(children, () =>
+        emitValue(
+          presentBody,
+          "nmsInternalValue",
+          dartString(`/Change/Call/Payload/${pathLeaf(path)}`),
+          nullableInnerType,
+          path,
+          3,
+          false,
+        ));
+      lines.push(
+        `  ${fieldAccess.value}.when<void>(`,
+        `    omitted: () {},`,
+        `    explicitNull: () {`,
+        ...nullBody.map((line) => `      ${line}`),
+        `    },`,
+        `    present: (nmsInternalValue) {`,
+        ...presentBody.map((line) => `      ${line}`),
+        `    },`,
+        `  );`,
+      );
+      continue;
+    }
+    if (field.required) {
+      const body: string[] = [];
+      withOut(children, () =>
+        emitValue(
+          body,
+          fieldAccess.value,
+          dartString(`/Change/Call/Payload/${pathLeaf(path)}`),
+          field.value.id,
+          path,
+          3,
+          fieldValueIsCanonical,
+        ));
+      lines.push(...body.map((line) => `  ${line}`));
+    } else {
+      const present = fieldAccess.present;
+      if (present === undefined) {
+        throw new Error(
+          `Dart call USDA codegen: optional '${domain}/${directive}.${field.name}' has no typed presence expression`,
+        );
+      }
+      const optional = fresh("optional");
+      const body: string[] = [];
+      withOut(children, () =>
+        emitValue(
+          body,
+          optional,
+          dartString(`/Change/Call/Payload/${pathLeaf(path)}`),
+          field.value.id,
+          path,
+          3,
+          fieldValueIsCanonical,
+        ));
+      lines.push(
+        `  if (${present}) {`,
+        `    final ${optional} = ${fieldAccess.value};`,
+        ...body.map((line) => `    ${line}`),
+        `  }`,
+      );
+    }
+  }
+  lines.push(
+    `  _nmsUsdaChildren(out, ${children});`,
+    `  _nmsUsdaClose(out, 2);`,
+    `  _nmsUsdaClose(out, 1);`,
+    `  _nmsUsdaClose(out, 0);`,
+    `  return NmsInternalGeneratedCalls.create(`,
+    `    domain: ${dartString(domain)},`,
+    `    directive: ${dartString(directive)},`,
+    `    canonicalUsda: Uint8List.fromList(utf8.encode('\${out.join('\\n')}\\n')),`,
+    `  );`,
+    `}`,
+    ``,
+  );
+  return { functionName, source: lines };
+}