@githolon/dsl 0.108.0 → 0.108.2

package/src/codegen_dart_framework_calls.ts

@@ -0,0 +1,291 @@
+import type { z } from "zod";
+
+import type { Directive } from "./directive.js";
+import type { DomainModule } from "./codegen_dart.js";
+import { dartMemberName, introspectPayload } from "./codegen_dart.js";
+import type { PayloadFieldSpec } from "./codegen_dart.js";
+import {
+  DART_CALL_USDA_PRELUDE,
+  emitDartCallUsdaEncoder,
+  type DartCallUsdaFieldAccess,
+} from "./codegen_call_usda.js";
+import type { LawGraph } from "./law_graph.js";
+import { fixedFrameworkCallDefinitions } from "./framework_call_definitions.js";
+import { APPLICATION_HOME_DOMAIN } from "./framework/application_home_domain.js";
+import { workspaceSharingInvitationRedeemPayload } from "./workspace_sharing.js";
+import { zodArrayElement, zodDef, zodObjectShape } from "./zod_introspection.js";
+
+type AnyDirective = Directive<unknown>;
+
+const frameworkFieldAccess = (field: PayloadFieldSpec): DartCallUsdaFieldAccess => {
+  const member = `payload.${dartMemberName(field.name)}`;
+  if (field.nullAdmits === true) return { value: member, slot: true };
+  const value = field.optional ? `${member}!` : member;
+  const present = field.optional ? { present: `${member} != null` } : {};
+  switch (field.shape) {
+    case "scalar":
+    case "enum":
+    case "strList":
+    case "wrappedList":
+    case "refList":
+    case "record":
+    case "recordList":
+    case "stringMap":
+    case "vo":
+    case "voList":
+      return { value, ...present };
+    case "wrapped":
+      return { value: `${value}.value`, ...present };
+    default:
+      throw new Error(
+        `Dart framework call codegen: fixed field '${field.name}' uses unsupported '${field.shape}' input`,
+      );
+  }
+};
+
+const FIXED_CALLS = fixedFrameworkCallDefinitions
+  .filter((definition) => definition.dartBirth === true)
+  .map((definition) => ({ kind: definition.kind, directive: definition.directive.id }));
+
+const certificateArgumentType = (field: PayloadFieldSpec): string | undefined =>
+  (field.name === "certificate" || field.name === "delegationCertificate") && field.shape === "record"
+    ? `BirthCertificate${field.optional ? "?" : ""}`
+    : field.name === "links" && field.shape === "recordList"
+      ? "List<BirthCertificate>"
+      : undefined;
+
+const certificatePayloadExpression = (field: PayloadFieldSpec): string | undefined =>
+  (field.name === "certificate" || field.name === "delegationCertificate") && field.shape === "record"
+    ? field.optional
+      ? `${dartMemberName(field.name)} == null ? null : _nmsBirthCertificateLawValue(${dartMemberName(field.name)})`
+      : `_nmsBirthCertificateLawValue(${dartMemberName(field.name)})`
+    : field.name === "links" && field.shape === "recordList"
+      ? "links.map(_nmsBirthCertificateLawValue).toList(growable: false)"
+      : undefined;
+
+const birthCertificateMemberExpression = (name: string): string => {
+  switch (name) {
+    case "child":
+    case "founder":
+    case "verified":
+    case "parentId":
+      return `certificate.${name}`;
+    case "parentKey":
+    case "signature":
+      return `base64Encode(certificate.${name})`;
+    case "epoch":
+      return "certificate.epoch.toInt()";
+    case "verifiedVia":
+    case "idpToken":
+    case "authProviderIssuer":
+    case "authProviderJwks":
+    case "authProviderAudience": {
+      const cap = name[0]!.toUpperCase() + name.slice(1);
+      return `certificate.has${cap}() ? certificate.${name} : null`;
+    }
+    case "capturedClock":
+      return "certificate.hasCapturedClock() ? certificate.capturedClock.toInt() : null";
+    default:
+      throw new Error(
+        `Dart framework call codegen: BirthCertificate law field '${name}' has no generated Protobuf binding`,
+      );
+  }
+};
+
+export interface DartFrameworkCallLaw {
+  readonly module: DomainModule;
+  readonly graph: LawGraph;
+  readonly paths: ReadonlyMap<string, string>;
+}
+
+/** Emit the pre-bind framework call factory from the exact composed law graph.
+ * The output contains no schemas or dynamic values: every field access and USDA
+ * relationship is expanded by the compiler. */
+export function generateDartApplicationFrameworkCalls(
+  laws: readonly DartFrameworkCallLaw[],
+): string | undefined {
+  const fixedEmitted = FIXED_CALLS.flatMap((definition) => laws.flatMap((law) => {
+    const declares = law.graph.nodes.some((node) =>
+      node.kind === "intent" &&
+      (node.entity.label === definition.directive || node.publicRoute === definition.directive));
+    if (!declares) return [];
+    const directive = (law.module.directives as AnyDirective[]).find((candidate) =>
+      candidate.id === definition.directive);
+    if (directive === undefined) {
+      throw new Error(
+        `Dart framework call codegen: '${law.graph.domain.entity.label}/${definition.directive}' has no authored directive`,
+      );
+    }
+    const fields = introspectPayload(
+      directive.payloadSchema as z.ZodTypeAny,
+      new Map(),
+    );
+    const parameterType = (field: (typeof fields)[number]) => field.nullAdmits === true
+      ? `NomosSlot<${field.dartType}>`
+      : `${field.dartType}${field.optional ? "?" : ""}`;
+    const payloadType = `({${fields.map((field) =>
+      `${parameterType(field)} ${dartMemberName(field.name)}`).join(", ")}})`;
+    const access = new Map<string, DartCallUsdaFieldAccess>(fields.map((field) => [
+      field.name,
+      frameworkFieldAccess(field),
+    ]));
+    const encoder = emitDartCallUsdaEncoder(
+      law.graph,
+      law.paths,
+      law.graph.domain.entity.label,
+      definition.directive,
+      payloadType,
+      access,
+    );
+    return [{ ...definition, domain: law.graph.domain.entity.label, fields, payloadType, encoder, routeByDirective: false as const }];
+  }));
+  const invitationEmitted = laws.flatMap((law) =>
+    (law.module.applicationWorkspaceSharing ?? []).map((policy) => {
+      const directive = policy.invitationLaw.redeem as AnyDirective;
+      const fields = introspectPayload(directive.payloadSchema as z.ZodTypeAny, new Map());
+      const parameterType = (field: (typeof fields)[number]) => field.nullAdmits === true
+        ? `NomosSlot<${field.dartType}>`
+        : `${field.dartType}${field.optional ? "?" : ""}`;
+      const payloadType = `({${fields.map((field) =>
+        `${parameterType(field)} ${dartMemberName(field.name)}`).join(", ")}})`;
+      const access = new Map<string, DartCallUsdaFieldAccess>(fields.map((field) => [
+        field.name,
+        frameworkFieldAccess(field),
+      ]));
+      const encoder = emitDartCallUsdaEncoder(
+        law.graph,
+        law.paths,
+        law.graph.domain.entity.label,
+        directive.id,
+        payloadType,
+        access,
+      );
+      return {
+        kind: "redeemInvitation",
+        directive: directive.id,
+        domain: law.graph.domain.entity.label,
+        fields,
+        payloadType,
+        encoder,
+        routeByDirective: true as const,
+      };
+    }));
+  const emitted = [...fixedEmitted, ...invitationEmitted];
+  if (emitted.length === 0) return undefined;
+
+  const certificateEntry = emitted.find((entry) =>
+    entry.fields.some((field) => certificateArgumentType(field) !== undefined));
+  const certificateField = certificateEntry?.fields
+    .find((field) => certificateArgumentType(field) !== undefined);
+  const certificateRecordType = certificateField === undefined
+    ? undefined
+    : certificateField.shape === "record"
+      ? certificateField.dartType
+      : /^List<(.+)>$/.exec(certificateField.dartType)?.[1];
+  const certificateRecordFields = certificateRecordType === undefined
+    ? []
+    : (() => {
+        if (certificateEntry === undefined || certificateField === undefined) {
+          throw new Error("Dart framework call codegen: cannot locate the BirthCertificate law record");
+        }
+        const directive = (laws.find((law) => law.graph.domain.entity.label === certificateEntry.domain)?.module.directives as AnyDirective[] | undefined)
+          ?.find((candidate) => candidate.id === certificateEntry.directive);
+        if (directive === undefined) {
+          throw new Error("Dart framework call codegen: cannot locate the BirthCertificate directive");
+        }
+        let schema = zodObjectShape(directive.payloadSchema as z.ZodTypeAny)[certificateField.name];
+        if (schema === undefined) {
+          throw new Error("Dart framework call codegen: cannot locate the BirthCertificate payload field");
+        }
+        while (zodDef(schema).innerType !== undefined) schema = zodDef(schema).innerType!;
+        if (certificateField.shape === "recordList") schema = zodArrayElement(schema);
+        return introspectPayload(schema, new Map());
+      })();
+
+  const invitationContractFields = introspectPayload(
+    workspaceSharingInvitationRedeemPayload,
+    new Map(),
+  );
+  const fixedMethodFields = new Map(
+    fixedFrameworkCallDefinitions
+      .filter((definition) => definition.dartBirth === true)
+      .map((definition) => [
+        definition.kind,
+        introspectPayload(definition.directive.payloadSchema as z.ZodTypeAny, new Map()),
+      ] as const),
+  );
+  // The runtime interface is deliberately exhaustive. A composed application implements every
+  // method even when its law has no matching route; that method then fails locally at the typed
+  // switch instead of making the generated class abstract or inventing a dynamic fallback.
+  const methods = [...new Set([
+    ...fixedFrameworkCallDefinitions
+      .filter((definition) => definition.dartBirth === true)
+      .map((definition) => definition.kind),
+    "redeemInvitation",
+  ])].flatMap((kind) => {
+    const alternatives = emitted.filter((entry) => entry.kind === kind);
+    const fields = alternatives[0]?.fields ?? fixedMethodFields.get(kind) ?? invitationContractFields;
+    const routeByDirective = kind === "redeemInvitation" || alternatives.some((entry) => entry.routeByDirective);
+    const parameterType = (field: (typeof fields)[number]) => field.nullAdmits === true
+      ? `NomosSlot<${field.dartType}>`
+      : `${field.dartType}${field.optional ? "?" : ""}`;
+    const signature = fields.map((field) =>
+      `    ${field.optional ? "" : "required "}${certificateArgumentType(field) ?? parameterType(field)} ${dartMemberName(field.name)},`);
+    const payload = fields.map((field) =>
+      `      ${dartMemberName(field.name)}: ${certificatePayloadExpression(field) ?? dartMemberName(field.name)},`);
+    return [
+      `  @override`,
+      `  NmsGeneratedCall ${kind}({`,
+      `    required String domain,`,
+      `    required String workspace,`,
+      ...(routeByDirective ? [`    required String directive,`] : []),
+      ...signature,
+      `  }) {`,
+      `    final payload = (`,
+      ...payload,
+      `    );`,
+      `    return switch (${routeByDirective ? "'$domain/$directive'" : "domain"}) {`,
+      ...alternatives.map((entry) =>
+        `      ${JSON.stringify(routeByDirective ? `${entry.domain}/${entry.directive}` : entry.domain)} => ${entry.encoder.functionName}(payload),`),
+      `      _ => throw StateError("The compiled application has no '${kind}' call in domain '$domain'."),`,
+      `    };`,
+      `  }`,
+      ``,
+    ];
+  });
+
+  return [
+    `// AUTO-GENERATED by nomos-compile — pre-bind framework calls for this exact application law.`,
+    `// No host authority or payload schema lives here. Do not edit.`,
+    `// ignore_for_file: invalid_use_of_internal_member, unused_element, unused_import, unused_shown_name`,
+    `import 'dart:convert' show base64Encode, utf8;`,
+    `import 'dart:typed_data' show Uint8List;`,
+    `import 'package:nomos_types/nomos_kernel_protocol.dart' show BirthCertificate;`,
+    `import 'package:nomos_types/nomos_types.dart' show NomosSlot, Sha256Digest;`,
+    `import 'package:nomos_client/src/application_framework_calls.dart';`,
+    `import 'package:nomos_client/src/generated_call.dart';`,
+    ``,
+    ...DART_CALL_USDA_PRELUDE,
+    ...(certificateRecordType === undefined
+      ? []
+      : [
+          `${certificateRecordType} _nmsBirthCertificateLawValue(BirthCertificate certificate) => (`,
+          ...certificateRecordFields.map((field) =>
+            `  ${dartMemberName(field.name)}: ${birthCertificateMemberExpression(field.name)},`),
+          `);`,
+          ``,
+        ]),
+    ...emitted.flatMap((entry) => entry.encoder.source),
+    `final class _NmsCompiledApplicationFrameworkCalls implements NmsApplicationFrameworkCalls {`,
+    `  const _NmsCompiledApplicationFrameworkCalls();`,
+    `  @override`,
+    `  String get applicationHomeDomain => ${JSON.stringify(APPLICATION_HOME_DOMAIN)};`,
+    ``,
+    ...methods,
+    `}`,
+    ``,
+    `const NmsApplicationFrameworkCalls nomosInternalApplicationFrameworkCalls =`,
+    `    _NmsCompiledApplicationFrameworkCalls();`,
+    ``,
+  ].join("\n");
+}

package/src/codegen_dart_scenario.ts

@@ -91,6 +91,7 @@ export function generateDartScenario(
     readonly applicationFile?: string;
     readonly applicationModules?: readonly DomainModule[];
     readonly applicationMaxChildWorkspacesPerUser?: number;
+    readonly applicationFrameworkCallsFile?: string;
   } = {},
 ): string {
   const domain = options.surfaceName ?? mod.domain ?? mod.name;
@@ -116,6 +117,9 @@ export function generateDartScenario(
     `import 'package:flutter/widgets.dart' show WidgetsFlutterBinding;`,
     `import 'package:${clientPackage}/${clientPackage}.dart' show ${application};`,
     `import 'package:${clientPackage}/src/generated/${applicationFile}.dart' show ${bind};`,
+    ...(options.applicationFrameworkCallsFile === undefined
+      ? []
+      : [`import 'package:${clientPackage}/src/generated/${options.applicationFrameworkCallsFile}.dart' show nomosInternalApplicationFrameworkCalls;`]),
     `import 'package:nomos_flutter/src/generated_application_host.dart' show NmsInternalApplicationUserBinding;`,
     `import 'package:nomos_client/src/home.dart' show nmsInternalReceivingGroupNameOf;`,
     `import 'package:nomos_client/src/nms_test_environment.dart' show NomosTestCloud, NomosTestHarness;`,
@@ -196,6 +200,9 @@ export function generateDartScenario(
     `    final packageFiles = await _applicationPackages();`,
     `    final environment = await NomosTestHarness.ephemeral(`,
     `      lawUsdzPaths: packageFiles.map((file) => file.path).toList(growable: false),`,
+    ...(options.applicationFrameworkCallsFile === undefined
+      ? []
+      : [`      applicationFrameworkCalls: nomosInternalApplicationFrameworkCalls,`]),
     ...(options.applicationMaxChildWorkspacesPerUser === undefined
       ? []
       : [`      applicationMaxChildWorkspacesPerUser: ${options.applicationMaxChildWorkspacesPerUser},`]),

package/src/codegen_proof.ts

@@ -2228,10 +2228,9 @@ export function discoverChildBirthLegOrReason(
     businessBirth?: { aggregateId?: string; publicPayloadSchema?: z.ZodTypeAny };
   }).businessBirth;
   if (businessBirth !== undefined) {
-    // The real generated client fills this opaque carrier with locally sealed genesis facts. Discovery only
-    // needs the recipe's shape, so an empty JSON object preserves the synthesized plaintext facts while
-    // exercising the same parsing branch without inventing a key inside the compiler.
-    probePayload[BUSINESS_BIRTH_SEED_PAYLOAD_FIELD] = "{}";
+    // The real generated client fills this typed carrier with locally sealed genesis facts. Discovery
+    // preserves the synthesized facts while avoiding any parallel string serialization boundary.
+    probePayload[BUSINESS_BIRTH_SEED_PAYLOAD_FIELD] = { ...probePayload };
   }
   try {
     withBirthProbeGlobals(() => {

package/src/codegen_provider_dart.ts

@@ -56,7 +56,6 @@ import { z } from "zod";
 import {
   cap,
   introspectPayload,
-  toJsonExpr,
   type PayloadFieldSpec,
 } from "./codegen_dart.js";
 
@@ -163,7 +162,14 @@ function obligationCtorParam(s: PayloadFieldSpec): string {
  */
 function obligationFromJsonExpr(s: PayloadFieldSpec): string {
   const raw = `j['${s.name}']`;
-  switch (s.toJson) {
+  switch (s.shape) {
+    case "record":
+    case "recordList":
+    case "stringMap":
+      throw new Error(
+        `provider Dart codegen: obligation field '${s.name}' is a typed composite; ` +
+          "generate its protobuf provider contract instead of decoding it from JSON",
+      );
     case "scalar": {
       // int reads tolerate a JSON number that decodes as double/int; cast via `as num`.
       if (s.dartType === "int") {
@@ -189,10 +195,19 @@ function obligationFromJsonExpr(s: PayloadFieldSpec): string {
         ? `(${raw} as List<Object?>?)?.cast<String>()`
         : `(${raw} as List<Object?>).cast<String>()`;
     }
-    case "json": {
-      // A nested object → `Map<String,Object?>`; a `List<Object?>` payload (rare) stays
-      // a list. The Dart type drives the cast.
-      return s.optional ? `${raw} as ${s.dartType}?` : `${raw} as ${s.dartType}`;
+    case "wrappedList": {
+      const elem = s.dartType.replace(/^List<(.*)>$/, "$1");
+      const wrapped = s.wrappedScalarKind === "number"
+        ? `${elem}((e as num).toDouble())`
+        : `${elem}(e as String)`;
+      const decode = `(${raw} as List).map((e) => ${wrapped}).toList(growable: false)`;
+      return s.optional ? `${raw} == null ? null : ${decode}` : decode;
+    }
+    case "refList": {
+      const target = s.dartType.replace(/^List<NomosRef<(.*)>>$/, "$1");
+      const wireType = s.referenceType ?? target;
+      const decode = `(${raw} as List).map((e) => NmsInternalNomosRefs.create<${target}>(workspace: '', type: '${wireType}', id: e as String)).toList(growable: false)`;
+      return s.optional ? `${raw} == null ? null : ${decode}` : decode;
     }
     case "vo": {
       // A declared value object — decode through the generated class (typed both ways).
@@ -473,6 +488,5 @@ export function emitProviderSdk(
   enumDartTypes: Map<string, string>,
 ): string {
   if (tasks.length === 0) return "";
-  void toJsonExpr; // symmetry marker (see doc); the encode reuses the peer payload classes.
   return tasks.map((t) => emitProviderTask(t, enumDartTypes)).join("\n\n");
 }

package/src/codegen_query_usda.ts

@@ -0,0 +1,214 @@
+import type { LawGraph, LawQueryReadNode } from "./law_graph.js";
+
+export type QueryScalarKind = "string" | "reference" | "token" | "integer" | "boolean";
+
+export interface DartQueryUsdaParameter {
+  readonly authoredPath: string;
+  readonly name: string;
+  readonly type: "String" | "int" | "bool";
+  readonly value: string;
+  readonly kind: QueryScalarKind;
+}
+
+export interface DartQueryUsdaEncoder {
+  readonly functionName: string;
+  readonly call: string;
+  readonly source: readonly string[];
+}
+
+export interface TsQueryUsdaParameter {
+  readonly authoredPath: string;
+  readonly name: string;
+  readonly type: "string" | "number" | "boolean";
+  readonly value: string;
+  readonly kind: QueryScalarKind;
+}
+
+export interface TsQueryUsdaEncoder {
+  readonly functionName: string;
+  readonly call: string;
+  readonly source: readonly string[];
+}
+
+const symbol = (value: string): string =>
+  value.replace(/[^A-Za-z0-9_$]+/g, "_").replace(/^[^A-Za-z_$]/, "_$&");
+
+const pathLeaf = (path: string): string => path.slice(path.lastIndexOf("/") + 1);
+
+const dartString = (value: string): string => JSON.stringify(value);
+
+/**
+ * Emit one query-specific USDA encoder from the same composed graph that emitted law.usda.
+ *
+ * There is intentionally no schema interpreter or generic value bag in the generated runtime:
+ * each parameter has one Dart type, one OpenUSD value type and exact query/field relationships.
+ */
+export function emitDartQueryUsdaEncoder(
+  graph: LawGraph,
+  paths: ReadonlyMap<string, string>,
+  domain: string,
+  queryId: string,
+  parameters: readonly DartQueryUsdaParameter[],
+): DartQueryUsdaEncoder {
+  const query = graph.nodes.find(
+    (node): node is LawQueryReadNode =>
+      node.kind === "read" && node.readKind === "query" && node.entity.label === queryId,
+  );
+  if (query === undefined) {
+    throw new Error(`query USDA codegen: domain '${domain}' has no law query '${queryId}'`);
+  }
+  const queryPath = paths.get(query.entity.id);
+  if (queryPath === undefined) {
+    throw new Error(`query USDA codegen: '${domain}/${queryId}' has no rendered law path`);
+  }
+  if (query.key.length !== parameters.length) {
+    throw new Error(
+      `query USDA codegen: '${domain}/${queryId}' has ${query.key.length} law keys but ${parameters.length} generated parameters`,
+    );
+  }
+  const functionName = `_nmsQueryUsda_${symbol(domain)}_${symbol(queryId)}`;
+  const signature = parameters.map((parameter) => `${parameter.type} ${parameter.name}`).join(", ");
+  const lines = [
+    `NmsGeneratedQuery ${functionName}(${signature}) {`,
+    `  final out = <String>[`,
+    `    '#usda 1.0',`,
+    `    '(',`,
+    `    '    defaultPrim = "Query"',`,
+    `    ')',`,
+    `    '',`,
+    `    'def NomosQuery "Query"',`,
+    `    '{',`,
+    `    '    custom rel nomos:query = <${queryPath}>',`,
+    `    '',`,
+    `    '    def NomosQueryArguments "Arguments"',`,
+    `    '    {',`,
+    `  ];`,
+  ];
+  for (let index = 0; index < parameters.length; index++) {
+    const parameter = parameters[index]!;
+    const key = query.key[index]!;
+    if (key.authoredPath !== parameter.authoredPath) {
+      throw new Error(
+        `query USDA codegen: '${domain}/${queryId}' key ${index} is '${key.authoredPath}', not '${parameter.authoredPath}'`,
+      );
+    }
+    const fieldPath = paths.get(key.field.id);
+    if (fieldPath === undefined) {
+      throw new Error(
+        `query USDA codegen: '${domain}/${queryId}.${parameter.authoredPath}' has no rendered field path`,
+      );
+    }
+    const valuePath = `/Query/Arguments/${pathLeaf(fieldPath)}`;
+    const [primType, declaredType, expression] = (() => {
+      switch (parameter.kind) {
+        case "string":
+          return ["NomosStringValue", "string", `_nmsUsdaQuote(${parameter.name})`] as const;
+        case "reference":
+          return ["NomosReferenceValue", "string", `_nmsUsdaQuote(${parameter.name})`] as const;
+        case "token":
+          return ["NomosTokenValue", "token", `_nmsUsdaQuote(${parameter.name})`] as const;
+        case "integer":
+          return ["NomosIntValue", "int64", `_nmsUsdaInt(${parameter.name})`] as const;
+        case "boolean":
+          return ["NomosBoolValue", "bool", `${parameter.name} ? 'true' : 'false'`] as const;
+      }
+    })();
+    lines.push(
+      `  _nmsUsdaBegin(out, 2, ${dartString(primType)}, ${dartString(valuePath)});`,
+      `  _nmsUsdaRel(out, 3, 'nomos:field', ${dartString(fieldPath)});`,
+      `  _nmsUsdaLine(out, 3, 'custom uniform string[] nomos:keyPath = [' + _nmsUsdaQuote(${dartString(parameter.authoredPath)}) + ']');`,
+      `  _nmsUsdaLine(out, 3, 'custom uniform ${declaredType} nomos:value = ' + ${expression});`,
+      `  _nmsUsdaClose(out, 2);`,
+    );
+  }
+  lines.push(
+    `  _nmsUsdaClose(out, 1);`,
+    `  _nmsUsdaClose(out, 0);`,
+    `  return NmsInternalGeneratedQueries.create(`,
+    `    domain: ${dartString(domain)},`,
+    `    query: ${dartString(queryId)},`,
+    `    canonicalArgumentsUsda: Uint8List.fromList(utf8.encode('\${out.join('\\n')}\\n')),`,
+    `  );`,
+    `}`,
+    ``,
+  );
+  return {
+    functionName,
+    call: `${functionName}(${parameters.map((parameter) => parameter.value).join(", ")})`,
+    source: lines,
+  };
+}
+
+export function emitTsQueryUsdaEncoder(
+  graph: LawGraph,
+  paths: ReadonlyMap<string, string>,
+  domain: string,
+  queryId: string,
+  parameters: readonly TsQueryUsdaParameter[],
+): TsQueryUsdaEncoder {
+  const query = graph.nodes.find(
+    (node): node is LawQueryReadNode =>
+      node.kind === "read" && node.readKind === "query" && node.entity.label === queryId,
+  );
+  if (query === undefined) throw new Error(`query USDA codegen: domain '${domain}' has no law query '${queryId}'`);
+  const queryPath = paths.get(query.entity.id);
+  if (queryPath === undefined) throw new Error(`query USDA codegen: '${domain}/${queryId}' has no rendered law path`);
+  if (query.key.length !== parameters.length) {
+    throw new Error(`query USDA codegen: '${domain}/${queryId}' key/parameter length differs`);
+  }
+  const functionName = `_nmsQueryUsda_${symbol(domain)}_${symbol(queryId)}`;
+  const lines = [
+    `function ${functionName}(${parameters.map((parameter) => `${parameter.name}: ${parameter.type}`).join(", ")}): NmsGeneratedQuery<${JSON.stringify(domain)}, ${JSON.stringify(queryId)}> {`,
+    `  const out: string[] = [`,
+    `    "#usda 1.0",`,
+    `    "(",`,
+    `    '    defaultPrim = "Query"',`,
+    `    ")",`,
+    `    "",`,
+    `    'def NomosQuery "Query"',`,
+    `    "{",`,
+    `    "    custom rel nomos:query = <${queryPath}>",`,
+    `    "",`,
+    `    '    def NomosQueryArguments "Arguments"',`,
+    `    "    {",`,
+    `  ];`,
+  ];
+  for (let index = 0; index < parameters.length; index++) {
+    const parameter = parameters[index]!;
+    const key = query.key[index]!;
+    if (key.authoredPath !== parameter.authoredPath) {
+      throw new Error(`query USDA codegen: '${domain}/${queryId}' key ${index} identity differs`);
+    }
+    const fieldPath = paths.get(key.field.id);
+    if (fieldPath === undefined) throw new Error(`query USDA codegen: '${domain}/${queryId}.${parameter.authoredPath}' has no field path`);
+    const valuePath = `/Query/Arguments/${pathLeaf(fieldPath)}`;
+    const [primType, declaredType, expression] = (() => {
+      switch (parameter.kind) {
+        case "string": return ["NomosStringValue", "string", `_nmsUsdaQuote(${parameter.name})`] as const;
+        case "reference": return ["NomosReferenceValue", "string", `_nmsUsdaQuote(${parameter.name})`] as const;
+        case "token": return ["NomosTokenValue", "token", `_nmsUsdaQuote(${parameter.name})`] as const;
+        case "integer": return ["NomosIntValue", "int64", `_nmsUsdaInt(${parameter.name})`] as const;
+        case "boolean": return ["NomosBoolValue", "bool", `${parameter.name} ? "true" : "false"`] as const;
+      }
+    })();
+    lines.push(
+      `  _nmsUsdaBegin(out, 2, ${JSON.stringify(primType)}, ${JSON.stringify(valuePath)});`,
+      `  _nmsUsdaRel(out, 3, "nomos:field", ${JSON.stringify(fieldPath)});`,
+      `  _nmsUsdaLine(out, 3, "custom uniform string[] nomos:keyPath = [" + _nmsUsdaQuote(${JSON.stringify(parameter.authoredPath)}) + "]");`,
+      `  _nmsUsdaLine(out, 3, "custom uniform ${declaredType} nomos:value = " + ${expression});`,
+      `  _nmsUsdaClose(out, 2);`,
+    );
+  }
+  lines.push(
+    `  _nmsUsdaClose(out, 1);`,
+    `  _nmsUsdaClose(out, 0);`,
+    `  return _nmsGeneratedQuery(${JSON.stringify(domain)}, ${JSON.stringify(queryId)}, _nmsUsdaUtf8(out.join("\\n") + "\\n"));`,
+    `}`,
+    ``,
+  );
+  return {
+    functionName,
+    call: `${functionName}(${parameters.map((parameter) => parameter.value).join(", ")})`,
+    source: lines,
+  };
+}