@githolon/dsl 0.108.6 → 0.110.0

package/src/codegen_call_proto.ts

@@ -0,0 +1,1274 @@
+import type {
+  LawAnonymousValueFieldNode,
+  LawAnonymousValueTypeNode,
+  LawAnonymousValueVariantNode,
+  LawGraph,
+  LawIntentNode,
+  LawPayloadContractNode,
+  LawRowReadNode,
+  LawReadNode,
+  LawStructuralRef,
+  LawTypeNode,
+  LawValueTypeRef,
+} from "./law_graph.js";
+import type { GeometryKind } from "./fields.js";
+import { dartMemberName, unionArmClassName } from "./codegen_dart.js";
+import { mintStableId } from "./stable_ids.js";
+import { protobufFieldNumber } from "./protobuf_field_number.js";
+import { provenanceRowIdentity, provenanceFieldIdentity, provenanceAuthorIdentity, provenanceContestedIdentity } from "./provenance_wire.js";
+
+export interface TsCallProtoFieldAccess {
+  readonly value: string;
+  readonly present?: string;
+  /** The generated client has already lowered this nominal value to its
+   * canonical scalar/record representation. Do not validate/lower it twice. */
+  readonly canonical?: true;
+}
+
+export interface DartCallProtoFieldAccess {
+  readonly value: string;
+  readonly present?: string;
+  readonly slot?: true;
+  readonly omit?: true;
+}
+
+export interface CallProtoEncoder {
+  readonly functionName: string;
+  readonly typeUrl: string;
+  readonly publicDirective: string;
+  readonly source: readonly string[];
+}
+
+export interface OperationProtoLaw {
+  readonly graph: LawGraph;
+  readonly paths: ReadonlyMap<string, string>;
+  /** Additional private compiler operations which have a generated client
+   * encoder. Public intents are always included. */
+  readonly directives?: readonly string[];
+}
+
+export interface OperationProtoSchema {
+  readonly fileName: "operation_payloads.proto";
+  readonly dartFileName: "operation_payloads.pb.dart";
+  readonly source: string;
+}
+
+const symbol = (value: string): string =>
+  value.replace(/[^A-Za-z0-9_$]+/g, "_").replace(/^[^A-Za-z_$]/, "_$&");
+
+/**
+ * Derive a permanent Protobuf field identity from the stable law identity.
+ *
+ * This deliberately does not use declaration order. Adding a field therefore
+ * cannot renumber any existing field. The compiler rejects the vanishingly
+ * unlikely collision inside each message instead of creating a schema registry.
+ *
+ * ONE FACT, ONE REPRESENTATION. The Peer Office derives the same numbers when it
+ * encodes a call from a workspace's own installed law, so the definition lives in a
+ * dependency-free leaf both sides import (`./protobuf_field_number.ts`) and this
+ * compiler re-exports it. A second copy here is exactly the drift the doctrine forbids.
+ */
+export { protobufFieldNumber } from "./protobuf_field_number.js";
+
+function requireUniqueFieldNumbers(
+  fields: readonly { readonly label: string; readonly sid: string }[],
+  where: string,
+): void {
+  const numbers = new Map<number, string>();
+  for (const field of fields) {
+    const number = protobufFieldNumber(field.sid);
+    const prior = numbers.get(number);
+    if (prior !== undefined) {
+      throw new Error(
+        `call Protobuf codegen: ${where} maps both '${prior}' and '${field.label}' to field ${number}`,
+      );
+    }
+    numbers.set(number, field.label);
+  }
+}
+
+/**
+ * OpenUSD composition may share structurally identical anonymous records between
+ * operation contracts. `compileSparseLawGraphUsda` records that sharing by
+ * redirecting each duplicate field path to the canonical field prim. The wire
+ * identity must follow that composed path too; using the duplicate graph-local
+ * SID makes generated clients speak a different Protobuf schema from the law the
+ * kernel actually installs.
+ */
+export function composedWireIdentity(
+  paths: ReadonlyMap<string, string>,
+  entity: { readonly id: string; readonly sid: string; readonly wireKey?: string },
+): string {
+  if (entity.wireKey !== undefined) return entity.wireKey;
+  const path = paths.get(entity.id);
+  const canonical = path?.match(/\/(?:Fields\/f_|Variants\/v_)([0-9a-f]{16})$/i)?.[1];
+  return canonical ?? entity.sid;
+}
+
+interface NominalSumArm {
+  readonly discriminator: string;
+  readonly variant: LawAnonymousValueVariantNode;
+  readonly value: LawAnonymousValueTypeNode;
+}
+
+function nominalSumArms(
+  nodes: ReadonlyMap<string, LawGraph["nodes"][number]>,
+  sum: LawAnonymousValueTypeNode,
+  where: string,
+): 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(...)`);
+  }
+  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 discriminators = value.expression.fields.flatMap((fieldRef) => {
+      const field = nodes.get(fieldRef.id);
+      if (field?.kind !== "structural" || field.structuralKind !== "value-field" || field.name !== "type") return [];
+      const type = nodes.get(field.value.id);
+      return field.required && type?.kind === "structural" && type.structuralKind === "value-type" &&
+          type.expression.kind === "literal" && typeof type.expression.value === "string"
+        ? [type.expression.value]
+        : [];
+    });
+    if (discriminators.length !== 1) {
+      throw new Error(`${where} variant '${variant.entity.label}' needs one required literal type discriminator`);
+    }
+    return { discriminator: discriminators[0]!, variant, value };
+  });
+  requireUniqueFieldNumbers(
+    arms.map((arm) => ({ label: arm.discriminator, sid: arm.variant.entity.sid })),
+    `${where} union`,
+  );
+  return [...arms].sort((a, b) => a.discriminator.localeCompare(b.discriminator));
+}
+
+/**
+ * The public law intent that takes `directive` as one of its steps, when one exists.
+ *
+ * A directive a business intent composes (a private effect, or a capability obligation it
+ * `.directs`) is offered THROUGH that intent: its route and payload contract are the publisher's.
+ * The graph's typed step edge is the authority; codegen must not rediscover this by scanning
+ * TypeScript objects.
+ */
+export function publishingIntentOf(
+  graph: LawGraph,
+  domain: string,
+  directive: string,
+): LawIntentNode | undefined {
+  const direct = graph.nodes.find((node): node is LawIntentNode =>
+    node.kind === "intent" && (node.entity.label === directive || node.publicRoute === directive));
+  if (direct === undefined) throw new Error(`call Protobuf codegen: domain '${domain}' has no '${directive}' intent`);
+  const publishers = graph.nodes.filter((node): node is LawIntentNode =>
+    node.kind === "intent" &&
+    node.public &&
+    node.steps.some((step) => step.id === direct.entity.id));
+  if (publishers.length > 1) {
+    throw new Error(
+      `call Protobuf codegen: '${domain}/${directive}' is published by more than one law intent ` +
+        `(${publishers.map((publisher) => publisher.entity.label).join(", ")})`,
+    );
+  }
+  return publishers[0];
+}
+
+function operation(
+  graph: LawGraph,
+  domain: string,
+  directive: string,
+): {
+  readonly nodes: ReadonlyMap<string, LawGraph["nodes"][number]>;
+  readonly intent: LawIntentNode;
+  readonly contract: LawPayloadContractNode;
+  readonly publicDirective: string;
+  readonly typeUrl: string;
+} {
+  const nodes = new Map(graph.nodes.map((node) => [node.entity.id, node]));
+  const publisher = publishingIntentOf(graph, domain, directive);
+  const direct = graph.nodes.find((node): node is LawIntentNode =>
+    node.kind === "intent" && (node.entity.label === directive || node.publicRoute === directive))!;
+  // A composed directive is never a second client route: it is offered through its publisher.
+  const intent = publisher ?? direct;
+  const contract = nodes.get(intent.accepts.id);
+  if (contract?.kind !== "payload-contract") {
+    throw new Error(`call Protobuf codegen: '${domain}/${directive}' accepts no payload contract`);
+  }
+  return {
+    nodes,
+    intent,
+    contract,
+    publicDirective: intent.publicRoute ?? intent.entity.label,
+    typeUrl: `type.nomos.dev/nomos.operation.v1.Payload_${contract.entity.sid}`,
+  };
+}
+
+const fieldNode = (
+  nodes: ReadonlyMap<string, LawGraph["nodes"][number]>,
+  ref: LawStructuralRef<"value-field">,
+): LawAnonymousValueFieldNode => {
+  const node = nodes.get(ref.id);
+  if (node?.kind !== "structural" || node.structuralKind !== "value-field") {
+    throw new Error(`call Protobuf codegen: '${ref.id}' is not a value field`);
+  }
+  return node;
+};
+
+const typeNode = (
+  nodes: ReadonlyMap<string, LawGraph["nodes"][number]>,
+  id: string,
+): LawAnonymousValueTypeNode => {
+  const node = nodes.get(id);
+  if (node?.kind !== "structural" || node.structuralKind !== "value-type") {
+    throw new Error(`call Protobuf codegen: '${id}' is not a value type`);
+  }
+  return node;
+};
+
+export const structuralGeometryKind = (
+  nodes: ReadonlyMap<string, LawGraph["nodes"][number]>,
+  node: LawAnonymousValueTypeNode,
+): GeometryKind | undefined => {
+  // The IR carries the geo.* declaration. Do not guess from a record member
+  // named `type`: USDA and both generated languages must see the same fact.
+  return node.expression.semantic?.kind === "value-object"
+    ? node.expression.semantic.geometry ?? structuralDeclaredValueObject(nodes, node)?.geometry
+    : undefined;
+};
+
+const structuralDeclaredValueObject = (
+  nodes: ReadonlyMap<string, LawGraph["nodes"][number]>,
+  node: LawAnonymousValueTypeNode,
+): LawTypeNode | undefined => {
+  const semantic = node.expression.semantic;
+  if (semantic?.kind !== "value-object") return undefined;
+  return [...nodes.values()].find((candidate): candidate is LawTypeNode =>
+    candidate.kind === "type" &&
+    candidate.entity.label === semantic.name);
+};
+
+/** Anonymous structural SIDs are content-addressed under their immediate
+ * owner. Framework-owned shapes can therefore recur in several domains while
+ * resolving a nominal child to a different domain type. The wire message is
+ * contextual to the composed domain; nominal children retain their own stable
+ * declared identities. */
+const structuralWireIdentity = (
+  graph: LawGraph,
+  node: LawAnonymousValueTypeNode,
+): string => operationMessageIdentity(graph, node.entity.sid);
+
+/** Message-class identity inside one composed application schema. The Any
+ * type URL remains the stable law member/contract identity understood by the
+ * kernel; this contextual identity only prevents distinct domain projections
+ * from colliding in generated language bindings. */
+export const operationMessageIdentity = (
+  graph: LawGraph,
+  contractSid: string,
+): string => mintStableId(
+  `operation-wire:${graph.domain.entity.sid}:${contractSid}`,
+);
+
+export const protoMessageName = (kind: string, sid: string): string =>
+  `${kind}_${sid.replace(/[^A-Za-z0-9_]/g, "_")}`;
+
+export const protoFieldName = (sid: string): string =>
+  `f${sid.replace(/[^A-Za-z0-9_]/g, "_")}`;
+
+const dartProtoFieldName = protoFieldName;
+
+/**
+ * Generate the application operation schema from the same composed law graph
+ * that emits law.usda. This is the sole wire-schema authority: Dart/TypeScript
+ * bindings are produced from this file by protoc, never by handwritten tag
+ * writers in either generated client.
+ */
+export function generateOperationProtoSchema(
+  laws: readonly OperationProtoLaw[],
+): OperationProtoSchema {
+  const definitions = new Map<string, string>();
+  const add = (name: string, body: string): void => {
+    const prior = definitions.get(name);
+    if (prior !== undefined && prior !== body) {
+      throw new Error(
+        `operation Protobuf schema: '${name}' has two different composed definitions\n` +
+          `--- first ---\n${prior}\n--- second ---\n${body}`,
+      );
+    }
+    definitions.set(name, body);
+  };
+
+  for (const { graph, paths, directives } of laws) {
+    const nodes = new Map(graph.nodes.map((node) => [node.entity.id, node]));
+    const declaredValueObjects = new Map<string, LawTypeNode>(
+      graph.nodes.flatMap((node) =>
+        node.kind === "type"
+          ? [[node.entity.label, node] as const]
+          : []),
+    );
+    const field = (ref: LawStructuralRef<"value-field">): LawAnonymousValueFieldNode =>
+      fieldNode(nodes, ref);
+    const value = (id: string): LawAnonymousValueTypeNode => typeNode(nodes, id);
+
+    const valueRef = (ref: LawValueTypeRef, where: string): string => {
+      const node = nodes.get(ref.id);
+      if (node?.kind === "structural" && node.structuralKind === "value-type") {
+        return wireType(node, where);
+      }
+      if (node?.kind === "type") return ensureDeclaredType(node, where);
+      throw new Error(`operation Protobuf schema: '${where}' references no declared value type`);
+    };
+
+    const wireType = (node: LawAnonymousValueTypeNode, where: string): string => {
+      switch (node.expression.kind) {
+        case "default": return wireType(value(node.expression.value.id), where);
+        case "recursive": throw new Error(`operation Protobuf schema: '${where}' contains recursive values`);
+        case "string":
+        case "enum": return "string";
+        case "integer": return "sint64";
+        case "number": return "double";
+        case "boolean": return "bool";
+        case "literal": {
+          const literal = node.expression.value;
+          if (typeof literal === "string") return "string";
+          if (typeof literal === "boolean") return "bool";
+          if (typeof literal === "number" && Number.isInteger(literal)) return "sint64";
+          if (typeof literal === "number") return "double";
+          return ensureMessage(node, where);
+        }
+        case "null":
+        case "nullable":
+        case "record":
+        case "list":
+        case "map":
+        case "sum": return ensureMessage(node, where);
+        case "unknown": throw new Error(`operation Protobuf schema: '${where}' contains an unstructured value`);
+      }
+    };
+
+    const singularField = (type: string, name: string, number: number, comment: string): string => {
+      const scalar = type === "string" || type === "sint64" || type === "double" || type === "bool";
+      return `  // ${comment}\n  ${scalar ? "optional " : ""}${type} ${name} = ${number};`;
+    };
+
+    /** A custody field that admits explicit null has three states: omitted,
+     * explicit null, and value. Proto3 scalar presence carries only two, so the
+     * generated contract needs an explicit envelope. Its identity is derived
+     * from the stable law field, never declaration order. */
+    const nullableFieldType = (
+      field: Extract<LawGraph["nodes"][number], { readonly kind: "field" }>,
+      inner: string,
+      where: string,
+    ): string => {
+      const identity = operationMessageIdentity(
+        graph,
+        `${composedWireIdentity(paths, field.entity)}:nullable-result`,
+      );
+      const name = protoMessageName("NullableField", identity);
+      add(name, [
+        `message ${name} {`,
+        `  // True means the lawfully authored value is explicitly null.`,
+        `  oneof selected {`,
+        `    bool is_null = 1;`,
+        `    ${inner} value = 2;`,
+        `  }`,
+        `}`,
+      ].join("\n"));
+      return name;
+    };
+
+    /** The read shape of a `Surfaced(inner)` field is lawfully wider than its
+     * authored scalar: either one resolved value or the bounded observation set
+     * retained by the kernel. Generate that oneof from the field's stable law
+     * identity so static protoc bindings and the kernel's dynamic descriptor
+     * are the same contract. */
+    const surfacedFieldType = (
+      field: Extract<LawGraph["nodes"][number], { readonly kind: "field" }>,
+      inner: string,
+      where: string,
+    ): string => {
+      const identity = operationMessageIdentity(
+        graph,
+        `${composedWireIdentity(paths, field.entity)}:surfaced-result`,
+      );
+      const observation = protoMessageName("SurfacedObservation", identity);
+      const pending = protoMessageName("SurfacedPending", identity);
+      const surfaced = protoMessageName("SurfacedField", identity);
+      add(observation, [
+        `message ${observation} {`,
+        singularField(inner, "value", 1, `${where} competing value.`),
+        `  optional sint64 physical = 2;`,
+        `  optional uint32 logical = 3;`,
+        `  optional string replica = 4;`,
+        `  optional string author = 5;`,
+        `}`,
+      ].join("\n"));
+      add(pending, [
+        `message ${pending} {`,
+        `  repeated ${observation} observations = 1;`,
+        `}`,
+      ].join("\n"));
+      add(surfaced, [
+        `message ${surfaced} {`,
+        `  oneof selected {`,
+        `    ${inner} resolved = 1;`,
+        `    ${pending} pending = 2;`,
+        `  }`,
+        `}`,
+      ].join("\n"));
+      return surfaced;
+    };
+
+    const structuralDeclared = (node: LawAnonymousValueTypeNode): LawTypeNode | undefined => {
+      const semantic = node.expression.semantic;
+      return semantic?.kind === "value-object"
+        ? declaredValueObjects.get(semantic.name)
+        : undefined;
+    };
+
+    const ensureGeometryMessage = (name: string, geometry: GeometryKind): string => {
+      add(name, [
+        `message ${name} {`,
+        `  // RFC 7946 coordinates flattened into packed Protobuf primitives.`,
+        `  repeated double coordinates = 1 [packed = true];`,
+        ...(geometry === "Point"
+          ? []
+          : [`  // Cumulative coordinate counts after each position.`, `  repeated uint32 position_ends = 2 [packed = true];`]),
+        ...(geometry === "Polygon"
+          ? [`  // Cumulative position counts after each linear ring.`, `  repeated uint32 ring_ends = 3 [packed = true];`]
+          : []),
+        `}`,
+      ].join("\n"));
+      return name;
+    };
+
+    function ensureMessage(node: LawAnonymousValueTypeNode, where: string): string {
+      const geometry = structuralGeometryKind(nodes, node);
+      if (geometry !== undefined) {
+        return ensureGeometryMessage(
+          protoMessageName("Value", structuralWireIdentity(graph, node)),
+          geometry,
+        );
+      }
+      const nodeSid = structuralWireIdentity(graph, node);
+      switch (node.expression.kind) {
+        case "default": return wireType(value(node.expression.value.id), where);
+        case "recursive": throw new Error(`operation Protobuf schema: '${where}' contains recursive values`);
+        case "null": {
+          const name = protoMessageName("Null", nodeSid);
+          add(name, `message ${name} {}`);
+          return name;
+        }
+        case "literal": {
+          if (node.expression.value !== null) return wireType(node, where);
+          const name = protoMessageName("Null", nodeSid);
+          add(name, `message ${name} {}`);
+          return name;
+        }
+        case "nullable": {
+          const name = protoMessageName("Nullable", nodeSid);
+          const inner = wireType(value(node.expression.value.id), `${where}.value`);
+          add(name, [
+            `message ${name} {`,
+            `  oneof selected {`,
+            `    bool is_null = 1;`,
+            `    ${inner} value = 2;`,
+            `  }`,
+            `}`,
+          ].join("\n"));
+          return name;
+        }
+        case "record": {
+          const name = protoMessageName("Value", nodeSid);
+          const fields = node.expression.fields.map(field);
+          requireUniqueFieldNumbers(fields.map((item) => ({
+            label: item.name,
+            sid: composedWireIdentity(paths, item.entity),
+          })), where);
+          const lines = fields.map((item) => {
+            const sid = composedWireIdentity(paths, item.entity);
+            return singularField(
+              wireType(value(item.value.id), `${where}.${item.name}`),
+              protoFieldName(sid),
+              protobufFieldNumber(sid),
+              `${item.name}${item.required ? " (required by law)" : " (optional)"}`,
+            );
+          });
+          add(name, [`message ${name} {`, ...lines, `}`].join("\n"));
+          return name;
+        }
+        case "list": {
+          const name = protoMessageName("List", nodeSid);
+          const item = wireType(value(node.expression.element.id), `${where}[]`);
+          add(name, [`message ${name} {`, `  repeated ${item} items = 1;`, `}`].join("\n"));
+          return name;
+        }
+        case "map": {
+          const name = protoMessageName("Map", nodeSid);
+          const entry = protoMessageName("MapEntry", nodeSid);
+          const item = wireType(value(node.expression.value.id), `${where}.*`);
+          add(entry, [
+            `message ${entry} {`,
+            `  optional string key = 1;`,
+            singularField(item, "value", 2, "Map value."),
+            `}`,
+          ].join("\n"));
+          add(name, [`message ${name} {`, `  repeated ${entry} entries = 1;`, `}`].join("\n"));
+          return name;
+        }
+        case "sum": {
+          const name = protoMessageName("Sum", nodeSid);
+          const arms = nominalSumArms(nodes, node, where);
+          const lines = arms.map((arm) => {
+            const sid = composedWireIdentity(paths, arm.variant.entity);
+            return [
+              `    // ${arm.discriminator}`,
+              `    ${wireType(arm.value, `${where}.${arm.discriminator}`)} ${protoFieldName(sid)} = ${protobufFieldNumber(sid)};`,
+            ].join("\n");
+          });
+          add(name, [`message ${name} {`, `  oneof choice {`, ...lines, `  }`, `}`].join("\n"));
+          return name;
+        }
+        case "string":
+        case "enum":
+        case "integer":
+        case "number":
+        case "boolean": return wireType(node, where);
+        case "unknown": throw new Error(`operation Protobuf schema: '${where}' contains an unstructured value`);
+      }
+    }
+
+    function ensureDeclaredType(node: LawTypeNode, where: string): string {
+      if (node.form === "geometry") {
+        if (node.geometry === undefined) {
+          throw new Error(`operation Protobuf schema: '${where}' uses geometry without a declared kind`);
+        }
+        const name = protoMessageName("Value", node.entity.sid);
+        return ensureGeometryMessage(name, node.geometry);
+      }
+      if (node.form === "sum") {
+        const name = protoMessageName("Sum", node.entity.sid);
+        const arms = node.variants.map((ref) => {
+          const variant = nodes.get(ref.id);
+          if (variant?.kind !== "structural" || variant.structuralKind !== "value-variant" || variant.label === undefined) {
+            throw new Error(`operation Protobuf schema: '${where}' has an invalid declared sum arm '${ref.id}'`);
+          }
+          return variant;
+        });
+        requireUniqueFieldNumbers(
+          arms.map((arm) => ({ label: arm.label!, sid: composedWireIdentity(paths, arm.entity) })),
+          `${where} union`,
+        );
+        const lines = arms.map((arm) => {
+          const sid = composedWireIdentity(paths, arm.entity);
+          return [
+            `    // ${arm.label}`,
+            `    ${valueRef(arm.value, `${where}.${arm.label}`)} ${protoFieldName(sid)} = ${protobufFieldNumber(sid)};`,
+          ].join("\n");
+        });
+        add(name, [`message ${name} {`, `  oneof choice {`, ...lines, `  }`, `}`].join("\n"));
+        return name;
+      }
+      const name = protoMessageName("Value", node.entity.sid);
+      const fields = node.fields.map((ref) => {
+        const field = nodes.get(ref.id);
+        if (field?.kind !== "field") {
+          throw new Error(`operation Protobuf schema: '${where}' references non-field '${ref.id}'`);
+        }
+        return field;
+      });
+      requireUniqueFieldNumbers(
+        fields.map((item) => ({ label: item.entity.label, sid: composedWireIdentity(paths, item.entity) })),
+        where,
+      );
+      const lines = fields.map((item) => {
+        const sid = composedWireIdentity(paths, item.entity);
+        return singularField(
+          valueRef(item.value, `${where}.${item.entity.label}`),
+          protoFieldName(sid),
+          protobufFieldNumber(sid),
+          `${item.entity.label}${item.required ? " (required by law)" : " (optional)"}`,
+        );
+      });
+      add(name, [`message ${name} {`, ...lines, `}`].join("\n"));
+      return name;
+    }
+
+    const selected = new Map<string, LawIntentNode>();
+    for (const intent of graph.nodes.filter(
+      (node): node is LawIntentNode => node.kind === "intent" && node.public,
+    )) {
+      selected.set(intent.entity.id, intent);
+    }
+    for (const directive of directives ?? []) {
+      // Use the same publisher resolution as both generated call encoders.
+      // A private owned-record route can publish through another intent; its
+      // transport message must match the payload the encoder actually sends.
+      const resolved = operation(graph, graph.domain.entity.label, directive);
+      selected.set(resolved.intent.entity.id, resolved.intent);
+    }
+    for (const intent of selected.values()) {
+      const contract = nodes.get(intent.accepts.id);
+      if (contract?.kind !== "payload-contract") continue;
+      const name = protoMessageName("Payload", operationMessageIdentity(graph, contract.entity.sid));
+      const fields = contract.fields.map(field);
+      requireUniqueFieldNumbers(fields.map((item) => ({
+        label: item.name,
+        sid: composedWireIdentity(paths, item.entity),
+      })), `${graph.domain.entity.label}/${intent.entity.label}`);
+      const lines = fields.map((item) => {
+        const sid = composedWireIdentity(paths, item.entity);
+        return singularField(
+          wireType(value(item.value.id), `${intent.entity.label}.${item.name}`),
+          protoFieldName(sid),
+          protobufFieldNumber(sid),
+          `${item.name}${item.required ? " (required by law)" : " (optional)"}`,
+        );
+      });
+      add(name, [`message ${name} {`, ...lines, `}`].join("\n"));
+    }
+
+    for (const query of graph.nodes.filter(
+      (node): node is LawRowReadNode =>
+        node.kind === "read" && (node.readKind === "query" || node.readKind === "ordered"),
+    )) {
+      const fields = (query.readKind === "query" ? query.key : []).map((key) => {
+        const root = nodes.get(key.field.id);
+        if (root?.kind !== "field") {
+          throw new Error(
+            `query Protobuf schema: '${graph.domain.entity.label}/${query.entity.label}' ` +
+              `references non-field '${key.field.id}'`,
+          );
+        }
+        const terminalRef = key.path.at(-1);
+        const terminal = terminalRef === undefined ? root : nodes.get(terminalRef.id);
+        const terminalValue = terminal?.kind === "field" ||
+            (terminal?.kind === "structural" && terminal.structuralKind === "value-field")
+          ? terminal.value
+          : undefined;
+        const sid = terminal !== undefined && "entity" in terminal
+          ? composedWireIdentity(paths, terminal.entity)
+          : composedWireIdentity(paths, root.entity);
+        const scalar = (() => {
+          if (terminal?.kind === "structural" && terminal.structuralKind === "value-variant") {
+            return "string";
+          }
+          if (terminalValue !== undefined) {
+            let candidate = nodes.get(terminalValue.id);
+            const seen = new Set<string>();
+            while (
+              candidate?.kind === "structural" && candidate.structuralKind === "value-type" &&
+              (candidate.expression.kind === "default" || candidate.expression.kind === "nullable" || candidate.expression.kind === "recursive")
+            ) {
+              if (seen.has(candidate.entity.id)) break;
+              seen.add(candidate.entity.id);
+              candidate = nodes.get(candidate.expression.value.id);
+            }
+            if (candidate?.kind === "structural" && candidate.structuralKind === "value-type") {
+              switch (candidate.expression.kind) {
+                case "integer": return "sint64";
+                case "number": return "double";
+                case "boolean": return "bool";
+                case "string": case "enum": case "literal": return "string";
+              }
+            }
+          }
+          switch (root.storageKind) {
+            case "int": case "counter": return "sint64";
+            case "bool": return "bool";
+            case "string": case "enum": case "ref": case "set": return "string";
+          }
+          throw new Error(
+            `query Protobuf schema: '${graph.domain.entity.label}/${query.entity.label}' ` +
+              `cannot index '${key.authoredPath}' as a scalar law value`,
+          );
+        })();
+        return {
+          label: key.authoredPath,
+          sid,
+          line: singularField(
+            scalar,
+            protoFieldName(sid),
+            protobufFieldNumber(sid),
+            `${key.authoredPath} (required query key)`,
+          ),
+        };
+      });
+      requireUniqueFieldNumbers(fields, `${graph.domain.entity.label}/${query.entity.label} query`);
+      const name = protoMessageName("Query", operationMessageIdentity(graph, query.entity.sid));
+      add(name, [`message ${name} {`, ...fields.map((field) => field.line), `}`].join("\n"));
+
+      const contract = nodes.get(query.contract.id);
+      if (contract?.kind !== "read-contract" || contract.returns.kind !== "rows") {
+        throw new Error(
+          `query Protobuf schema: '${graph.domain.entity.label}/${query.entity.label}' has no row result contract`,
+        );
+      }
+      const aggregate = nodes.get(contract.returns.aggregate.id);
+      if (aggregate?.kind !== "aggregate") {
+        throw new Error(
+          `query Protobuf schema: '${graph.domain.entity.label}/${query.entity.label}' returns no aggregate`,
+        );
+      }
+      const rowName = protoMessageName("Read", operationMessageIdentity(graph, aggregate.entity.sid));
+      const rowFields: Array<{ readonly label: string; readonly sid: string; readonly line: string }> = [];
+      const idSid = `${aggregate.entity.sid}:result:id`;
+      rowFields.push({
+        label: "id",
+        sid: idSid,
+        line: singularField("string", protoFieldName(idSid), protobufFieldNumber(idSid), "Stable aggregate id."),
+      });
+      for (const fieldRef of aggregate.fields) {
+        const field = nodes.get(fieldRef.id);
+        if (field?.kind !== "field") {
+          throw new Error(`query Protobuf schema: '${aggregate.entity.label}' references non-field '${fieldRef.id}'`);
+        }
+        const sid = composedWireIdentity(paths, field.entity);
+        const where = `${aggregate.entity.label}.${field.entity.label}`;
+        const authored = valueRef(field.value, where);
+        const inner = field.mergeDrivers[0]?.kind === "Surfaced"
+          ? surfacedFieldType(field, authored, where)
+          : authored;
+        const type = field.nullable ? nullableFieldType(field, inner, where) : inner;
+        rowFields.push({
+          label: field.entity.label,
+          sid,
+          line: singularField(type, protoFieldName(sid), protobufFieldNumber(sid), `${field.entity.label}${field.required ? " (required by law)" : " (optional)"}`),
+        });
+      }
+      for (const read of graph.nodes.filter(
+        (node): node is LawReadNode =>
+          node.kind === "read" &&
+          node.of.id === aggregate.entity.id &&
+          (node.readKind === "derived" || node.readKind === "temporalEnum" || node.readKind === "combined"),
+      )) {
+        const readContract = nodes.get(read.contract.id);
+        if (readContract?.kind !== "read-contract" || readContract.returns.kind !== "scalar") {
+          throw new Error(`query Protobuf schema: computed read '${read.entity.label}' has no scalar contract`);
+        }
+        const sid = composedWireIdentity(paths, read.entity);
+        rowFields.push({
+          label: read.entity.label,
+          sid,
+          line: singularField(
+            valueRef(readContract.returns.value, `${aggregate.entity.label}.${read.entity.label}`),
+            protoFieldName(sid),
+            protobufFieldNumber(sid),
+            `${read.entity.label} (computed read)`,
+          ),
+        });
+      }
+      const attributed = aggregate.fields.map(ref => nodes.get(ref.id)).filter(
+        (node): node is Extract<LawGraph["nodes"][number], { kind: "field" }> =>
+          node?.kind === "field" && node.mergeDrivers[0]?.kind === "Attributed",
+      );
+      if (attributed.length > 0) {
+        add("ProvenanceAuthor", `message ProvenanceAuthor { oneof selected { bool is_null = 1; string value = 2; } }`);
+        add("FieldProvenance", [
+          `message FieldProvenance {`,
+          singularField("ProvenanceAuthor", protoFieldName(provenanceAuthorIdentity), protobufFieldNumber(provenanceAuthorIdentity), "Verified author, explicitly null when unknown."),
+          singularField("bool", protoFieldName(provenanceContestedIdentity), protobufFieldNumber(provenanceContestedIdentity), "Whether the current value displaced a concurrent version."),
+          `}`,
+        ].join("\n"));
+        const sid = provenanceRowIdentity(aggregate.entity.sid);
+        const name = protoMessageName("ReadProvenance", operationMessageIdentity(graph, sid));
+        const members = attributed.map(field => ({
+          label: field.entity.label, sid: provenanceFieldIdentity(composedWireIdentity(paths, field.entity)),
+        }));
+        requireUniqueFieldNumbers(members, `${aggregate.entity.label} provenance`);
+        add(name, [`message ${name} {`, ...members.map(field => singularField(
+          "FieldProvenance", protoFieldName(field.sid), protobufFieldNumber(field.sid), field.label,
+        )), `}`].join("\n"));
+        rowFields.push({ label: "__prov", sid, line: singularField(name, protoFieldName(sid), protobufFieldNumber(sid), "Existing per-field provenance, absent before attribution.") });
+      }
+      requireUniqueFieldNumbers(rowFields, `${graph.domain.entity.label}/${aggregate.entity.label} result`);
+      add(rowName, [`message ${rowName} {`, ...rowFields.map((field) => field.line), `}`].join("\n"));
+
+      const resultName = protoMessageName("QueryResult", operationMessageIdentity(graph, query.entity.sid));
+      const rowsSid = `${query.entity.sid}:result:rows`;
+      const cursorSid = `${query.entity.sid}:result:cursor`;
+      const doneSid = `${query.entity.sid}:result:done`;
+      requireUniqueFieldNumbers([
+        { label: "rows", sid: rowsSid },
+        { label: "cursor", sid: cursorSid },
+        { label: "done", sid: doneSid },
+      ], `${graph.domain.entity.label}/${query.entity.label} result envelope`);
+      add(resultName, [
+        `message ${resultName} {`,
+        `  repeated ${rowName} ${protoFieldName(rowsSid)} = ${protobufFieldNumber(rowsSid)};`,
+        singularField("string", protoFieldName(cursorSid), protobufFieldNumber(cursorSid), "Opaque continuation cursor when paging."),
+        singularField("bool", protoFieldName(doneSid), protobufFieldNumber(doneSid), "Whether the page reached the current frontier."),
+        `}`,
+      ].join("\n"));
+    }
+  }
+
+  return {
+    fileName: "operation_payloads.proto",
+    dartFileName: "operation_payloads.pb.dart",
+    source: [
+      `syntax = "proto3";`,
+      `package nomos.operation.v1;`,
+      ``,
+      `// GENERATED from the composed Nomos law graph. DO NOT EDIT.`,
+      `// Field numbers are permanent stable-law identities; names are diagnostic only.`,
+      ``,
+      ...[...definitions.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .flatMap(([, definition]) => [definition, ``]),
+    ].join("\n"),
+  };
+}
+
+export const TS_CALL_PROTO_PRELUDE = [
+  `declare const _nmsGeneratedCallBrand: unique symbol;`,
+  `interface NmsGeneratedCall<Domain extends string = string, Directive extends string = string> {`,
+  `  readonly domain: Domain;`,
+  `  readonly directive: Directive;`,
+  `  readonly protobufType: string;`,
+  `  readonly protobufPayload: Uint8Array;`,
+  `  readonly routingCandidates: readonly string[];`,
+  `  readonly [_nmsGeneratedCallBrand]: readonly [Domain, Directive];`,
+  `}`,
+  `const _nmsGeneratedCall = <Domain extends string, Directive extends string>(domain: Domain, directive: Directive, protobufType: string, protobufPayload: Uint8Array, routingCandidates: readonly string[]): NmsGeneratedCall<Domain, Directive> =>`,
+  `  ({ domain, directive, protobufType, protobufPayload, routingCandidates: [...new Set(routingCandidates)] }) as unknown as NmsGeneratedCall<Domain, Directive>;`,
+  `const _nmsProtoString = (value: string, routingCandidates: string[]): string => {`,
+  `  routingCandidates.push(value);`,
+  `  return value;`,
+  `};`,
+  `const _nmsProtoInt = (value: number): bigint => {`,
+  `  if (!Number.isSafeInteger(value)) throw new TypeError("Nomos integers must be safe integers");`,
+  `  return BigInt(value);`,
+  `};`,
+  `const _nmsProtoNumber = (value: number): number => {`,
+  `  if (!Number.isFinite(value)) throw new TypeError("Nomos numbers must be finite");`,
+  `  return value;`,
+  `};`,
+  ``,
+] as const;
+
+export const DART_CALL_PROTO_PRELUDE = [
+  `Int64 _nmsProtoInt(num value) {`,
+  `  if (!value.isFinite || value != value.truncateToDouble() || value.abs() > 9007199254740991) {`,
+  `    throw ArgumentError.value(value, 'value', 'Nomos integers must be safe integers');`,
+  `  }`,
+  `  return Int64(value.toInt());`,
+  `}`,
+  `double _nmsProtoNumber(num value) {`,
+  `  final result = value.toDouble();`,
+  `  if (!result.isFinite) throw ArgumentError.value(value, 'value', 'Nomos numbers must be finite');`,
+  `  return result;`,
+  `}`,
+  ``,
+] as const;
+
+function tsCanonicalValue(
+  value: string,
+  node: LawAnonymousValueTypeNode,
+  workspace: string,
+  field: string,
+  valueIsCanonical = false,
+): string {
+  const semantic = node.expression.semantic;
+  if (semantic === undefined || valueIsCanonical) return value;
+  switch (semantic.kind) {
+    case "id-reference": return `_nmsReferenceId(${value}, ${JSON.stringify(semantic.target)}, ${semantic.targetKind === "contract" ? '\"\"' : workspace}, ${JSON.stringify(field)})`;
+    case "address-reference": return `_nmsCheckedReferenceData(${value}, ${JSON.stringify(semantic.target)}, "", ${JSON.stringify(field)})`;
+    case "versioned-reference": return `({ pinned: _nmsReferenceData(${value}.pinned), series: _nmsReferenceData(${value}.series) })`;
+    case "recipient": return `_nmsRecipientAddress(${value}, ${JSON.stringify(field)})`;
+    default: return value;
+  }
+}
+
+function dartCanonicalValue(
+  value: string,
+  node: LawAnonymousValueTypeNode,
+  valueIsCanonical = false,
+): string {
+  const semantic = node.expression.semantic;
+  if (semantic === undefined || valueIsCanonical) return value;
+  switch (semantic.kind) {
+    case "id-reference": return `NmsInternalNomosRefs.id(${value})`;
+    case "address-reference": return `(workspace: NmsInternalNomosRefs.workspace(${value}), type: NmsInternalNomosRefs.type(${value}), id: NmsInternalNomosRefs.id(${value}))`;
+    case "versioned-reference": return `(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)))`;
+    case "recipient": return `NmsInternalRecipients.address(${value})`;
+    case "sha256-digest":
+    case "git-object-id":
+    case "branded-id":
+    case "unit": return `${value}.value`;
+    default: return value;
+  }
+}
+
+/** Emit one exact Protobuf operation encoder from the same graph as law.usda. */
+export function emitTsCallProtoEncoder(
+  graph: LawGraph,
+  paths: ReadonlyMap<string, string>,
+  domain: string,
+  directive: string,
+  payloadType: string,
+  access?: ReadonlyMap<string, TsCallProtoFieldAccess>,
+): CallProtoEncoder {
+  const spec = operation(graph, domain, directive);
+  const fields = spec.contract.fields.map((ref) => fieldNode(spec.nodes, ref));
+  requireUniqueFieldNumbers(fields.map((field) => ({
+    label: field.name,
+    sid: composedWireIdentity(paths, field.entity),
+  })), `${domain}/${directive}`);
+  let local = 0;
+  const fresh = (prefix: string): string => `_${prefix}${local++}`;
+
+  /** Build a MessageInitShape expression for protoc-gen-es. Nested records,
+   * lists, maps and unions stay typed objects until the maintained Protobuf
+   * runtime serializes the one top-level generated message. */
+  const emitValue = (raw: string, typeId: string, where: string, valueIsCanonical = false): string => {
+    const node = typeNode(spec.nodes, typeId);
+    const value = tsCanonicalValue(raw, node, "nmsInternalWorkspace", where, valueIsCanonical);
+    const geometry = structuralGeometryKind(spec.nodes, node);
+    if (geometry !== undefined) {
+      const selected = fresh("geometry");
+      const coordinates = fresh("coordinates");
+      if (geometry === "Point") {
+        return `(() => { const ${selected} = ${value}; return { coordinates: [...${selected}.coordinates] }; })()`;
+      }
+      const positions = fresh("positionEnds");
+      if (geometry === "Polygon") {
+        const rings = fresh("ringEnds");
+        const ring = fresh("ring");
+        const position = fresh("position");
+        return `(() => { const ${selected} = ${value}; const ${coordinates}: number[] = []; const ${positions}: number[] = []; const ${rings}: number[] = []; let _nmsPositionCount = 0; for (const ${ring} of ${selected}.coordinates) { for (const ${position} of ${ring}) { ${coordinates}.push(...${position}); ${positions}.push(${coordinates}.length); _nmsPositionCount += 1; } ${rings}.push(_nmsPositionCount); } return { coordinates: ${coordinates}, positionEnds: ${positions}, ringEnds: ${rings} }; })()`;
+      }
+      const position = fresh("position");
+      return `(() => { const ${selected} = ${value}; const ${coordinates}: number[] = []; const ${positions}: number[] = []; for (const ${position} of ${selected}.coordinates) { ${coordinates}.push(...${position}); ${positions}.push(${coordinates}.length); } return { coordinates: ${coordinates}, positionEnds: ${positions} }; })()`;
+    }
+    switch (node.expression.kind) {
+      case "default": return emitValue(value, node.expression.value.id, where);
+      case "recursive": throw new Error(`call Protobuf codegen: '${domain}/${directive}' contains recursive values`);
+      case "nullable": {
+        const selected = fresh("nullable");
+        return `(() => { const ${selected} = ${value}; return ${selected} === null ? { selected: { case: "isNull" as const, value: true } } : { selected: { case: "value" as const, value: ${emitValue(selected, node.expression.value.id, where)} } }; })()`;
+      }
+      case "string":
+      case "enum":
+        return `_nmsProtoString(${value}, _nmsRoutingCandidates)`;
+      case "integer": return `_nmsProtoInt(${value})`;
+      case "number": return `_nmsProtoNumber(${value})`;
+      case "boolean": return value;
+      case "null": return `{}`;
+      case "literal": {
+        const literal = JSON.stringify(node.expression.value);
+        if (typeof node.expression.value === "string") return `_nmsProtoString(${literal}, _nmsRoutingCandidates)`;
+        if (typeof node.expression.value === "boolean") return literal;
+        if (typeof node.expression.value === "number" && Number.isInteger(node.expression.value)) return `BigInt(${literal})`;
+        if (typeof node.expression.value === "number") return literal;
+        return `{}`;
+      }
+      case "record": {
+        const recordFields = node.expression.fields.map((ref) => fieldNode(spec.nodes, ref));
+        requireUniqueFieldNumbers(recordFields.map((item) => ({
+          label: item.name,
+          sid: composedWireIdentity(paths, item.entity),
+        })), where);
+        const selected = fresh("record");
+        const properties = recordFields.map((child) => {
+          const childRaw = `${selected}[${JSON.stringify(child.name)}]`;
+          const fieldName = protoFieldName(composedWireIdentity(paths, child.entity));
+          const encoded = emitValue(child.required ? childRaw : `(${childRaw})!`, child.value.id, `${where}.${child.name}`);
+          return `${fieldName}: ${child.required ? encoded : `${childRaw} === undefined ? undefined : ${encoded}`}`;
+        });
+        return `(() => { const ${selected} = (${value})!; return { ${properties.join(", ")} }; })()`;
+      }
+      case "list": {
+        const item = fresh("item");
+        // Parenthesize the nested expression: when the list element is itself
+        // a generated message initializer (`{ items: ... }`), an unwrapped
+        // arrow body is parsed as a statement block and silently becomes
+        // `void[]` instead of the declared nested value.
+        return `{ items: ${value}.map((${item}) => (${emitValue(item, node.expression.element.id, `${where}[]`)})) }`;
+      }
+      case "map": {
+        const entries = fresh("entries");
+        const key = fresh("key");
+        const item = fresh("item");
+        return `(() => { const ${entries} = Object.entries(${value}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0); return { entries: ${entries}.map(([${key}, ${item}]) => ({ key: _nmsProtoString(${key}, _nmsRoutingCandidates), value: ${emitValue(item, node.expression.value.id, `${where}.*`)} })) }; })()`;
+      }
+      case "sum": {
+        const arms = nominalSumArms(spec.nodes, node, `${domain}/${directive} ${where}`);
+        const selected = fresh("sum");
+        const cases: string[] = [];
+        for (const arm of arms) {
+          const fieldName = protoFieldName(composedWireIdentity(paths, arm.variant.entity));
+          cases.push(`case ${JSON.stringify(arm.discriminator)}: return { choice: { case: ${JSON.stringify(fieldName)} as const, value: ${emitValue(selected, arm.value.entity.id, `${where}.${arm.discriminator}`)} } };`);
+        }
+        return `(() => { const ${selected} = ${value}; switch (${selected}.type) { ${cases.join(" ")} default: throw new TypeError("Unknown nominal union arm: " + String((${selected} as unknown as { readonly type?: unknown }).type)); } })()`;
+      }
+      case "unknown": throw new Error(`call Protobuf codegen: '${domain}/${directive}' contains an unstructured value at ${where}`);
+    }
+  };
+
+  const messageName = protoMessageName("Payload", operationMessageIdentity(graph, spec.contract.entity.sid));
+  const schema = `_nmsop.${messageName}Schema`;
+  const properties: string[] = [];
+  const lines = [
+    `function _nmsCallProto_${symbol(domain)}_${symbol(directive)}(payload: ${payloadType}, nmsInternalWorkspace: string): NmsGeneratedCall<${JSON.stringify(domain)}, ${JSON.stringify(spec.publicDirective)}> {`,
+    `  const _nmsRoutingCandidates: string[] = [];`,
+  ];
+  for (const field of fields) {
+    const fieldAccess = access?.get(field.name);
+    if (fieldAccess?.present === "false") continue;
+    const raw = fieldAccess?.value ?? `payload[${JSON.stringify(field.name)}]`;
+    const fieldName = protoFieldName(composedWireIdentity(paths, field.entity));
+    if (field.required) properties.push(`${fieldName}: ${emitValue(raw, field.value.id, field.name, fieldAccess?.canonical === true)}`);
+    else {
+      const optional = fresh("optional");
+      lines.push(`  const ${optional} = ${raw};`);
+      properties.push(`${fieldName}: ${optional} !== undefined && (${fieldAccess?.present ?? "true"}) ? ${emitValue(`${optional}!`, field.value.id, field.name, fieldAccess?.canonical === true)} : undefined`);
+    }
+  }
+  lines.push(
+    `  const message = create(${schema}, { ${properties.join(", ")} });`,
+    `  return _nmsGeneratedCall(${JSON.stringify(domain)}, ${JSON.stringify(spec.publicDirective)}, ${JSON.stringify(spec.typeUrl)}, toBinary(${schema}, message), _nmsRoutingCandidates);`,
+    `}`,
+    ``,
+  );
+  return {
+    functionName: `_nmsCallProto_${symbol(domain)}_${symbol(directive)}`,
+    typeUrl: spec.typeUrl,
+    publicDirective: spec.publicDirective,
+    source: lines,
+  };
+}
+
+const dartString = (value: string): string =>
+  `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\$/g, "\\$")}'`;
+
+/** Dart twin of {@link emitTsCallProtoEncoder}; both derive the same field identities. */
+export function emitDartCallProtoEncoder(
+  graph: LawGraph,
+  paths: ReadonlyMap<string, string>,
+  domain: string,
+  directive: string,
+  payloadType: string,
+  access: ReadonlyMap<string, DartCallProtoFieldAccess>,
+  extraParameters: readonly string[] = [],
+): CallProtoEncoder {
+  const spec = operation(graph, domain, directive);
+  const fields = spec.contract.fields.map((ref) => fieldNode(spec.nodes, ref));
+  requireUniqueFieldNumbers(fields.map((field) => ({
+    label: field.name,
+    sid: composedWireIdentity(paths, field.entity),
+  })), `${domain}/${directive}`);
+  let local = 0;
+  const fresh = (prefix: string): string => `_${prefix}${local++}`;
+  const structuralProtoName = (kind: string, node: LawAnonymousValueTypeNode): string =>
+    protoMessageName(kind, structuralWireIdentity(graph, node));
+  const emitValue = (
+    out: string[],
+    raw: string,
+    typeId: string,
+    where: string,
+    accept: (expression: string) => void,
+    valueIsCanonical = false,
+  ): void => {
+    const node = typeNode(spec.nodes, typeId);
+    const semantic = node.expression.semantic;
+    const lowersNominalReference = semantic?.kind === "id-reference" ||
+      semantic?.kind === "address-reference" ||
+      semantic?.kind === "versioned-reference" ||
+      semantic?.kind === "recipient";
+    const value = dartCanonicalValue(raw, node, valueIsCanonical);
+    const geometry = structuralGeometryKind(spec.nodes, node);
+    if (geometry !== undefined) {
+      const message = fresh("geometryMessage");
+      const position = fresh("position");
+      out.push(`final ${message} = _nmsop.${structuralProtoName("Value", node)}();`);
+      if (geometry === "Point") {
+        out.push(`${message}.coordinates.addAll(${value}.coordinates.map((coordinate) => coordinate.toDouble()));`);
+      } else if (geometry === "Polygon") {
+        const ring = fresh("ring");
+        const count = fresh("positionCount");
+        out.push(`var ${count} = 0;`, `for (final ${ring} in ${value}.coordinates) {`, `  for (final ${position} in ${ring}) {`, `    ${message}.coordinates.addAll(${position}.map((coordinate) => coordinate.toDouble()));`, `    ${message}.positionEnds.add(${message}.coordinates.length);`, `    ${count} += 1;`, `  }`, `  ${message}.ringEnds.add(${count});`, `}`);
+      } else {
+        out.push(`for (final ${position} in ${value}.coordinates) {`, `  ${message}.coordinates.addAll(${position}.map((coordinate) => coordinate.toDouble()));`, `  ${message}.positionEnds.add(${message}.coordinates.length);`, `}`);
+      }
+      accept(message);
+      return;
+    }
+    switch (node.expression.kind) {
+      case "default": emitValue(out, value, node.expression.value.id, where, accept); return;
+      case "recursive": throw new Error(`Dart call Protobuf codegen: '${domain}/${directive}' contains recursive values`);
+      case "nullable": {
+        const selected = fresh("nullable");
+        const message = fresh("nullableMessage");
+        out.push(
+          `final ${selected} = ${value};`,
+          `final ${message} = _nmsop.${structuralProtoName("Nullable", node)}();`,
+          `if (${selected} == null) {`,
+          `  ${message}.isNull = true;`,
+          `} else {`,
+        );
+        const body: string[] = [];
+        emitValue(body, selected, node.expression.value.id, where, (expression) => {
+          body.push(`  ${message}.value = ${expression};`);
+        });
+        out.push(...body.map((line) => `  ${line}`), `}`);
+        accept(message);
+        return;
+      }
+      case "string": out.push(`_nmsRoutingCandidates.add(${value});`); accept(value); return;
+      case "enum": out.push(`_nmsRoutingCandidates.add(${value}.wire);`); accept(`${value}.wire`); return;
+      case "integer": accept(`_nmsProtoInt(${value})`); return;
+      case "number": accept(`_nmsProtoNumber(${value})`); return;
+      case "boolean": accept(value); return;
+      case "null": accept(`_nmsop.${structuralProtoName("Null", node)}()`); return;
+      case "literal": {
+        const literal = node.expression.value;
+        if (typeof literal === "string") {
+          out.push(`_nmsRoutingCandidates.add(${dartString(literal)});`);
+          accept(dartString(literal));
+        } else if (typeof literal === "boolean") accept(String(literal));
+        else if (typeof literal === "number" && Number.isInteger(literal)) accept(`Int64(${literal})`);
+        else if (typeof literal === "number") accept(String(literal));
+        else accept(`_nmsop.${structuralProtoName("Null", node)}()`);
+        return;
+      }
+      case "record": {
+        const recordFields = node.expression.fields.map((ref) => fieldNode(spec.nodes, ref));
+        requireUniqueFieldNumbers(recordFields.map((item) => ({
+          label: item.name,
+          sid: composedWireIdentity(paths, item.entity),
+        })), where);
+        const message = fresh("recordMessage");
+        out.push(`final ${message} = _nmsop.${structuralProtoName("Value", node)}();`);
+        for (const child of recordFields) {
+          const childRaw = `${value}.${dartMemberName(child.name)}`;
+          const member = `${message}.${dartProtoFieldName(composedWireIdentity(paths, child.entity))}`;
+          const body: string[] = [];
+          emitValue(
+            body,
+            child.required ? childRaw : `${childRaw}!`,
+            child.value.id,
+            `${where}.${child.name}`,
+            (expression) => body.push(`${member} = ${expression};`),
+            valueIsCanonical || lowersNominalReference,
+          );
+          if (child.required) out.push(...body);
+          else out.push(`if (${childRaw} != null) {`, ...body.map((line) => `  ${line}`), `}`);
+        }
+        accept(message);
+        return;
+      }
+      case "list": {
+        const item = fresh("item");
+        const message = fresh("listMessage");
+        out.push(`final ${message} = _nmsop.${structuralProtoName("List", node)}();`, `for (final ${item} in ${value}) {`);
+        const body: string[] = [];
+        emitValue(body, item, node.expression.element.id, `${where}[]`, (expression) => {
+          body.push(`${message}.items.add(${expression});`);
+        });
+        out.push(...body.map((line) => `  ${line}`), `}`);
+        accept(message);
+        return;
+      }
+      case "map": {
+        const key = fresh("key");
+        const item = fresh("item");
+        const message = fresh("mapMessage");
+        const entry = fresh("mapEntry");
+        const keys = fresh("mapKeys");
+        out.push(
+          `final ${message} = _nmsop.${structuralProtoName("Map", node)}();`,
+          `final ${keys} = ${value}.keys.toList()..sort();`,
+          `for (final ${key} in ${keys}) {`,
+          `  final ${item} = ${value}[${key}]!;`,
+          `  _nmsRoutingCandidates.add(${key});`,
+          `  final ${entry} = _nmsop.${structuralProtoName("MapEntry", node)}()..key = ${key};`,
+        );
+        const body: string[] = [];
+        emitValue(body, item, node.expression.value.id, `${where}.*`, (expression) => {
+          body.push(`${entry}.value = ${expression};`);
+        });
+        out.push(...body.map((line) => `  ${line}`), `  ${message}.entries.add(${entry});`, `}`);
+        accept(message);
+        return;
+      }
+      case "sum": {
+        const arms = nominalSumArms(spec.nodes, node, `${domain}/${directive} ${where}`);
+        const sumSemantic = node.expression.semantic;
+        const sumName = sumSemantic?.kind === "value-object"
+          ? sumSemantic.name
+          : undefined;
+        if (sumName === undefined) {
+          throw new Error(`Dart call Protobuf codegen: '${domain}/${directive}' contains a non-nominal sum at ${where}`);
+        }
+        const selected = fresh("sum");
+        const message = fresh("sumMessage");
+        out.push(`final ${selected} = ${value};`, `final ${message} = _nmsop.${structuralProtoName("Sum", node)}();`);
+        arms.forEach((arm, index) => {
+          const armType = unionArmClassName(sumName, arm.discriminator);
+          const armValue = fresh("arm");
+          const member = `${message}.${dartProtoFieldName(composedWireIdentity(paths, arm.variant.entity))}`;
+          out.push(`${index === 0 ? "if" : "else if"} (${selected} is ${armType}) {`, `  final ${armValue} = ${selected} as ${armType};`);
+          const body: string[] = [];
+          emitValue(body, armValue, arm.value.entity.id, `${where}.${arm.discriminator}`, (expression) => {
+            body.push(`${member} = ${expression};`);
+          });
+          out.push(...body.map((line) => `  ${line}`), `}`);
+        });
+        out.push(`else { throw ArgumentError.value(${selected}, ${dartString(sumName)}, 'Unknown nominal union arm'); }`);
+        accept(message);
+        return;
+      }
+      case "unknown": throw new Error(`Dart call Protobuf codegen: '${domain}/${directive}' contains an unstructured value at ${where}`);
+    }
+  };
+
+  const parameters = [`${payloadType} payload`, ...extraParameters].join(", ");
+  const message = fresh("payloadMessage");
+  const lines = [
+    `NmsGeneratedCall _nmsCallProto_${symbol(domain)}_${symbol(directive)}(${parameters}) {`,
+    `  final ${message} = _nmsop.${protoMessageName("Payload", operationMessageIdentity(graph, spec.contract.entity.sid))}();`,
+    `  final _nmsRoutingCandidates = <String>[];`,
+  ];
+  for (const field of fields) {
+    const fieldAccess = access.get(field.name);
+    if (fieldAccess?.omit === true || fieldAccess?.present === "false") continue;
+    const raw = fieldAccess?.slot === true ? `${fieldAccess.value}.value` : fieldAccess?.value ?? `payload.${dartMemberName(field.name)}`;
+    const fieldSemantic = typeNode(spec.nodes, 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";
+    const body: string[] = [];
+    const member = `${message}.${dartProtoFieldName(composedWireIdentity(paths, field.entity))}`;
+    emitValue(body, raw, field.value.id, field.name, (expression) => {
+      body.push(`${member} = ${expression};`);
+    }, fieldValueIsCanonical);
+    if (field.required) lines.push(...body.map((line) => `  ${line}`));
+    else lines.push(`  if (${fieldAccess?.present ?? `${raw} != null`}) {`, ...body.map((line) => `    ${line}`), `  }`);
+  }
+  lines.push(
+    `  return NmsInternalGeneratedCalls.create(`,
+    `    domain: ${dartString(domain)},`,
+    `    directive: ${dartString(spec.publicDirective)},`,
+    `    protobufType: ${dartString(spec.typeUrl)},`,
+    `    protobufPayload: ${message}.writeToBuffer(),`,
+    `  );`,
+    `}`,
+    ``,
+  );
+  return {
+    functionName: `_nmsCallProto_${symbol(domain)}_${symbol(directive)}`,
+    typeUrl: spec.typeUrl,
+    publicDirective: spec.publicDirective,
+    source: lines,
+  };
+}