@githolon/dsl 0.114.0 → 0.116.2

package/src/codegen_call_usda.ts

@@ -200,7 +200,8 @@ export const TS_CALL_USDA_PRELUDE = [
   `    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 if (point < 0x20 || point === 0x7f) out += "\\\\x" + point.toString(16).padStart(2, "0");`,
+  `    else if (point >= 0xd800 && point <= 0xdfff) throw new TypeError("Nomos USDA strings cannot carry a lone surrogate");`,
   `    else out += character;`,
   `  }`,
   `  return out + "\\\"";`,
@@ -254,8 +255,10 @@ export const DART_CALL_USDA_PRELUDE = [
   `      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')}');`,
+  `        if (point < 0x20 || point == 0x7f) {`,
+  `          out.write('\\\\x\${point.toRadixString(16).padLeft(2, '0')}');`,
+  `        } else if (point >= 0xd800 && point <= 0xdfff) {`,
+  `          throw ArgumentError.value(value, 'value', 'Nomos USDA strings cannot carry a lone surrogate');`,
   `        } else {`,
   `          out.write(String.fromCharCode(point));`,
   `        }`,

package/src/codegen_dart.ts

@@ -699,6 +699,8 @@ export interface AggFieldSpec {
   dartType: string;
   /** A canonical semantic string wrapper whose wire representation remains String. */
   semanticString?: "sha256" | "git-object-id";
+  /** A typed id (`t.brandedId(Name)` / `t.uuid()`): the zero-cost extension type wrapping the wire String. */
+  brandedId?: string;
   enumValues?: string[];
   /** For an own-id string field represented as `NomosRef<TAggregate>`. */
   valueClass?: string;
@@ -923,6 +925,9 @@ function readKeyParamSpec(
   if (fieldSpec.semanticString === "git-object-id") {
     return { dartType: "GitObjectId", valueExpr: `${paramName}.value` };
   }
+  if (fieldSpec.brandedId !== undefined) {
+    return { dartType: fieldSpec.brandedId, valueExpr: `${paramName}.value` };
+  }
   return { dartType: "String", valueExpr: paramName };
 }
 
@@ -1032,7 +1037,9 @@ function aggFieldSpec(
   // field schema marked them `.optional()`.
   const optional = isCollectionKind(field.kind) ? false : field.isOptional;
   switch (field.kind) {
-    case "string":
+    case "string": {
+      // A TYPED ID field (`t.brandedId(Name)` / `t.uuid()`) reads as its extension type, never a String.
+      const brand = valueClass === undefined ? brandedIdMetaOf(field.zod as z.ZodTypeAny) : undefined;
       return {
         name,
         wireName,
@@ -1042,9 +1049,10 @@ function aggFieldSpec(
             ? "Sha256Digest"
             : isGitObjectIdSchema(field.zod as z.ZodTypeAny)
               ? "GitObjectId"
-              : "String"
+              : brand ?? "String"
           : `NomosRef<${valueClass}>`,
         optional,
+        ...(brand !== undefined ? { brandedId: brand } : {}),
         ...(valueClass === undefined && isSha256DigestSchema(field.zod as z.ZodTypeAny)
           ? { semanticString: "sha256" as const }
           : {}),
@@ -1055,6 +1063,7 @@ function aggFieldSpec(
           ? { valueClass, valueAggregateType }
           : {}),
       };
+    }
     case "json":
       // A NAMED VALUE OBJECT (`ValueObject.field()`) types as its generated Dart class
       // (typed decode via `.fromProjected`, the EvidenceRef pattern). Otherwise
@@ -2124,54 +2133,16 @@ function voToJsonExpr(f: ValueObjectFieldDescriptor, expr: string, depth = 0): s
   }
 }
 
-/** Deep json equality/hash helpers shared by every generated VO class — emitted ONCE
- * per file when the file emits ≥1 VO class (`toJson()`-based value equality). */
-function emitVoHelpers(includeCopyWithSentinel: boolean): string {
+/** File-level helpers for generated VO classes — the copyWith absent-vs-null sentinel, emitted ONCE
+ * per file when a VO class needs it. Value equality is NOT emitted here: every VO's `==` / `hashCode`
+ * call `NmsInternalValueIdentity` (nomos_types), the Dart implementation of the law's
+ * `nomos.vo-canonical.v1` encoding (CAP-853) — one definition across runtimes. */
+function emitVoHelpers(): string {
   return [
-    ...(includeCopyWithSentinel
-      ? [
-          `/// The copyWith ABSENT-vs-null sentinel: an omitted optional param keeps the current`,
-          `/// value; an explicit \`null\` clears it. (Dart cannot distinguish the two otherwise.)`,
-          `const Object _voUnset = Object();`,
-          ``,
-        ]
-      : []),
-    `/// Deep json equality for generated value-object classes (toJson-based).`,
-    `bool _voJsonEq(Object? a, Object? b) {`,
-    `  if (a is Map && b is Map) {`,
-    `    if (a.length != b.length) {`,
-    `      return false;`,
-    `    }`,
-    `    for (final k in a.keys) {`,
-    `      if (!b.containsKey(k) || !_voJsonEq(a[k], b[k])) {`,
-    `        return false;`,
-    `      }`,
-    `    }`,
-    `    return true;`,
-    `  }`,
-    `  if (a is List && b is List) {`,
-    `    if (a.length != b.length) {`,
-    `      return false;`,
-    `    }`,
-    `    for (var i = 0; i < a.length; i++) {`,
-    `      if (!_voJsonEq(a[i], b[i])) {`,
-    `        return false;`,
-    `      }`,
-    `    }`,
-    `    return true;`,
-    `  }`,
-    `  return a == b;`,
-    `}`,
+    `/// The copyWith ABSENT-vs-null sentinel: an omitted optional param keeps the current`,
+    `/// value; an explicit \`null\` clears it. (Dart cannot distinguish the two otherwise.)`,
+    `const Object _voUnset = Object();`,
     ``,
-    `/// Deep json hash for generated value-object classes (toJson-based).`,
-    `int _voJsonHash(Object? v) {`,
-    `  if (v is Map) {`,
-    `    return Object.hashAllUnordered(`,
-    `        v.entries.map((e) => Object.hash(e.key, _voJsonHash(e.value))));`,
-    `  }`,
-    `  if (v is List) return Object.hashAll(v.map(_voJsonHash));`,
-    `  return v.hashCode;`,
-    `}`,
   ].join("\n");
 }
 
@@ -2252,9 +2223,9 @@ function emitUnionClasses(d: ValueObjectDescriptor): string {
         `  /// A copy with [value] replaced.`,
         `  ${cls} copyWith({${arm.ref}? value}) => ${cls}(value ?? this.value);`,
         `  @override`,
-        `  bool operator ==(Object other) => other is ${cls} && _voJsonEq(other.toJson(), toJson());`,
+        `  bool operator ==(Object other) => other is ${cls} && NmsInternalValueIdentity.equals(other.toJson(), toJson());`,
         `  @override`,
-        `  int get hashCode => _voJsonHash(toJson());`,
+        `  int get hashCode => NmsInternalValueIdentity.hash(toJson());`,
         `}`,
       ].join("\n");
     }
@@ -2304,9 +2275,9 @@ function emitUnionClasses(d: ValueObjectDescriptor): string {
       ``,
       ...emitCopyWith(cls, fields.map((x) => ({ member: x.member, dartType: dartTypeOfVoField(x.f, cls, x.wireName), optional: x.optional || x.f.nullable === true }))),
       `  @override`,
-      `  bool operator ==(Object other) => other is ${cls} && _voJsonEq(other.toJson(), toJson());`,
+      `  bool operator ==(Object other) => other is ${cls} && NmsInternalValueIdentity.equals(other.toJson(), toJson());`,
       `  @override`,
-      `  int get hashCode => _voJsonHash(toJson());`,
+      `  int get hashCode => NmsInternalValueIdentity.hash(toJson());`,
       `}`,
     ].join("\n");
   });
@@ -2323,9 +2294,9 @@ function emitUnionClasses(d: ValueObjectDescriptor): string {
     `  @override`,
     `  Map<String, Object?> toJson() => raw;`,
     `  @override`,
-    `  bool operator ==(Object other) => other is ${d.name}Unknown && _voJsonEq(other.raw, raw);`,
+    `  bool operator ==(Object other) => other is ${d.name}Unknown && NmsInternalValueIdentity.equals(other.raw, raw);`,
     `  @override`,
-    `  int get hashCode => _voJsonHash(raw);`,
+    `  int get hashCode => NmsInternalValueIdentity.hash(raw);`,
     `}`,
   ].join("\n");
 
@@ -2423,10 +2394,10 @@ function emitValueObjectClass(d: ValueObjectDescriptor): string {
       ``,
       `  @override`,
       `  bool operator ==(Object other) =>`,
-      `      other is ${d.name} && _voJsonEq(other.toJson(), toJson());`,
+      `      other is ${d.name} && NmsInternalValueIdentity.equals(other.toJson(), toJson());`,
       ``,
       `  @override`,
-      `  int get hashCode => _voJsonHash(toJson());`,
+      `  int get hashCode => NmsInternalValueIdentity.hash(toJson());`,
       `}`,
     ].join("\n");
   }
@@ -2489,10 +2460,10 @@ function emitValueObjectClass(d: ValueObjectDescriptor): string {
     ``,
     `  @override`,
     `  bool operator ==(Object other) =>`,
-    `      other is ${d.name} && _voJsonEq(other.toJson(), toJson());`,
+    `      other is ${d.name} && NmsInternalValueIdentity.equals(other.toJson(), toJson());`,
     ``,
     `  @override`,
-    `  int get hashCode => _voJsonHash(toJson());`,
+    `  int get hashCode => NmsInternalValueIdentity.hash(toJson());`,
     `}`,
   ].join("\n");
 }
@@ -3172,6 +3143,11 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
             ? `() { final v = ${reader}; return v == null ? null : GitObjectId(v); }()`
             : `GitObjectId(${reader})`;
         }
+        if (s.brandedId !== undefined) {
+          return opt
+            ? `() { final v = ${reader}; return v == null ? null : ${s.brandedId}(v); }()`
+            : `${s.brandedId}(${reader})`;
+        }
         return reader;
       }
     case "json":
@@ -3260,7 +3236,9 @@ function slotDecodeCallback(s: AggFieldSpec, mode: "aggregate" | "readModel"): s
         ? `(v) => Sha256Digest(v as String)`
         : s.semanticString === "git-object-id"
           ? `(v) => GitObjectId(v as String)`
-          : `(v) => v as String`;
+          : s.brandedId !== undefined
+            ? `(v) => ${s.brandedId}(v as String)`
+            : `(v) => v as String`;
     case "json":
       if (s.voClass !== undefined) {
         return `(v) => ${s.voClass}.fromProjected((v as Map).cast<String, Object?>())`;
@@ -3413,6 +3391,11 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
             ? `() { final v = ${reader}; return v == null ? null : GitObjectId(v); }()`
             : `GitObjectId(${reader})`;
         }
+        if (s.brandedId !== undefined) {
+          return opt
+            ? `() { final v = ${reader}; return v == null ? null : ${s.brandedId}(v); }()`
+            : `${s.brandedId}(${reader})`;
+        }
         return reader;
       }
     case "json":
@@ -4993,6 +4976,65 @@ export interface GenerateDartDomainOptions {
    * because it was present in the composed law.
    */
   readonly additionalValueObjects?: readonly ValueObjectDescriptor[];
+  /** Branded-id extension types another file (the package's `nomos_framework.dart`) declares because ≥2
+   *  domains use them; this domain references them via {@link frameworkImportUri}. */
+  readonly skipBrandNames?: ReadonlySet<string>;
+  /** Branded-id extension types this file declares for the package (the framework file's shared set). */
+  readonly extraBrandNames?: readonly string[];
+}
+
+/**
+ * Every branded-id name (`brandedId(...)`, `t.brandedId(...)`, `t.uuid()`) whose Dart extension type this
+ * domain's generated types reference: typed-id aggregate fields, top-level payload fields of its public
+ * directives (business births render their public payload), and value-object fields. The package counts
+ * these per domain so a brand used by two domains is declared ONCE, in the framework file.
+ */
+export function dartBrandNamesForModule(mod: DomainModule): Set<string> {
+  const brands = new Set<string>();
+  const publicAggregates = mod.aggregates.filter(
+    (a) => (a as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
+  );
+  for (const agg of publicAggregates) {
+    for (const f of Object.values(agg.fields as Record<string, Field>)) {
+      if (f.kind !== "string") continue;
+      const b = brandedIdMetaOf(f.zod as z.ZodTypeAny);
+      if (b !== undefined) brands.add(b);
+    }
+  }
+  const directives = (mod.applicationIntents ?? mod.directives)
+    .filter((d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true)
+    .map((d) => {
+      const birth = (d as { businessBirth?: { publicPayloadSchema?: z.ZodTypeAny } }).businessBirth;
+      return birth?.publicPayloadSchema === undefined ? d : { ...d, payloadSchema: birth.publicPayloadSchema };
+    });
+  for (const dir of directives) {
+    const schema = (dir as { payloadSchema?: unknown }).payloadSchema;
+    if (!schema || typeof schema !== "object" || zodTypeName(schema as z.ZodTypeAny) !== "ZodObject") continue;
+    const rawShape = (zodDef(schema as z.ZodTypeAny) as { shape?: Record<string, z.ZodTypeAny> | (() => Record<string, z.ZodTypeAny>) }).shape;
+    const shp = typeof rawShape === "function" ? rawShape() : rawShape ?? {};
+    for (let zt of Object.values(shp)) {
+      for (let hops = 0; hops < 8 && (zodTypeName(zt) === "ZodOptional" || zodTypeName(zt) === "ZodDefault" || zodTypeName(zt) === "ZodArray"); hops++) {
+        zt = zodTypeName(zt) === "ZodArray" ? zodArrayElement(zt) : zodInnerType(zt);
+      }
+      const b = brandedIdMetaOf(zt);
+      if (b !== undefined) brands.add(b);
+    }
+  }
+  const walk = (f: ValueObjectFieldDescriptor): void => {
+    if (f.type === "string" && f.brand !== undefined && f.idOf === undefined) brands.add(f.brand);
+    else if (f.type === "array") walk(f.items);
+    else if (f.type === "map") walk(f.values);
+  };
+  for (const d of [
+    ...collectValueObjectDescriptors(publicAggregates),
+    ...collectPayloadValueObjectDescriptors(directives),
+  ]) {
+    for (const f of Object.values(d.fields ?? {})) walk(f);
+    for (const arm of Object.values(d.union ?? {})) {
+      if ("fields" in arm) for (const f of Object.values(arm.fields)) walk(f);
+    }
+  }
+  return brands;
 }
 
 /** Generate the full Dart source for one domain module. */
@@ -5098,6 +5140,16 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     else if (f.type === "array") walkUnitField(f.items);
     else if (f.type === "map") walkUnitField(f.values);
   };
+  // TYPED-ID aggregate fields (`t.brandedId(Name)` / `t.uuid()`) declare their extension type with the
+  // aggregate that owns them (skipping aggregates another file declares).
+  for (const agg of mod.aggregates) {
+    if (opts.skipAggregateIds?.has(agg.id) === true) continue;
+    for (const f of Object.values(agg.fields as Record<string, Field>)) {
+      if (f.kind !== "string") continue;
+      const b = brandedIdMetaOf(f.zod as z.ZodTypeAny);
+      if (b !== undefined) brandNames.add(b);
+    }
+  }
   for (const d of localValueObjects) {
     for (const f of Object.values(d.fields ?? {})) walkUnitField(f);
     for (const arm of Object.values(d.union ?? {})) {
@@ -5128,6 +5180,8 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
       } catch { /* an unsupported payload shape is reported by the payload emitter, not here */ }
     }
   }
+  for (const b of opts.skipBrandNames ?? []) brandNames.delete(b);
+  for (const b of opts.extraBrandNames ?? []) brandNames.add(b);
   const unitBlock = [...unitNames].sort().map((u) => [
     `/// UNIT \`${u}\` — a ZERO-COST wrapper over the wire's plain JSON number (Dart extension`,
     `/// type): passing a bare double (or another unit) where [${u}] is required is a COMPILE`,
@@ -5150,7 +5204,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     ...(brandBlock !== "" ? [brandBlock] : []),
     ...(localValueObjects.length > 0
       ? [
-          emitVoHelpers(needsVoCopyWithSentinel),
+          ...(needsVoCopyWithSentinel ? [emitVoHelpers()] : []),
           ...localValueObjects.flatMap((d) => [
             ...voEnumFields(d)
               .filter((e) => e.declaredName === undefined)

package/src/codegen_dart_client.ts

@@ -1,3 +1,4 @@
+import { BUSINESS_BIRTH_KEY_PAYLOAD_FIELD } from "./births.js";
 import { dartRefusalDecoders } from "./codegen_refusal.js";
 // NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
 // remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
@@ -99,7 +100,7 @@ import { publicClientInterface, type DomainInterface } from "./compatibility_gra
 import { emitApplicationCompatibilityUsda } from "./compatibility_usda.js";
 import { BUSINESS_CORRECTION_DIRECTIVE } from "./framework/business_corrections.js";
 import { deriveDirectiveRecordTarget } from "./workspace_routing.js";
-import { voMetaOf } from "./value_object.js";
+import { brandedIdMetaOf, voMetaOf } from "./value_object.js";
 import {
   buildNomosDescribeModel,
   type NomosDescribeModel,
@@ -389,6 +390,11 @@ function dartKeyType(
   if (f?.kind === "string" && isSha256DigestSchema(f.zod as z.ZodTypeAny)) {
     return "Sha256Digest";
   }
+  // A typed-id key (`t.brandedId(Name)` / `t.uuid()`) is its extension type, never a bare String.
+  if (f?.kind === "string" && !key.includes(".")) {
+    const brand = brandedIdMetaOf(f.zod as z.ZodTypeAny);
+    if (brand !== undefined) return brand;
+  }
   if (f?.kind === "string" && isGitObjectIdSchema(f.zod as z.ZodTypeAny)) {
     return "GitObjectId";
   }
@@ -435,6 +441,13 @@ function dartKeyExpr(agg: AggregateHandle | undefined, key: string): string {
   ) {
     return `${param}.value`;
   }
+  if (
+    field?.kind === "string" &&
+    !key.includes(".") &&
+    brandedIdMetaOf(field.zod as z.ZodTypeAny) !== undefined
+  ) {
+    return `${param}.value`;
+  }
   if (field?.kind !== "ref") return param;
   return field.foreignRef !== undefined
     ? `NmsInternalNomosRefs.id(${param}.ref)`
@@ -491,6 +504,8 @@ function dartUsdaBasePresentValue(
         ? `Sha256Digest(${value})`
         : spec.semanticString === "git-object-id"
         ? `GitObjectId(${value})`
+        : spec.brandedId !== undefined
+        ? `${spec.brandedId}(${value})`
         : value;
     }
     case "ref": {
@@ -1305,7 +1320,7 @@ export function generateDartDomainClient(
     const compilerInternal = sourceTrustViaIds.has(directive.id);
     const businessBirth = (
       directive as unknown as {
-        businessBirth?: { publicPayloadSchema: z.ZodTypeAny };
+        businessBirth?: { publicPayloadSchema: z.ZodTypeAny; keyField?: string };
       }
     ).businessBirth;
     const specs = introspectPayload(
@@ -1360,6 +1375,15 @@ export function generateDartDomainClient(
       arguments_.push("principal", "bornAt");
       access.set("principal", { value: "nmsInternalBirthPrincipal" });
       access.set("bornAt", { value: "nmsInternalBornAt" });
+      // A minted birth's law admits a key the client reserved ahead of dispatch (CAP-804).
+      if (businessBirth.keyField === undefined) {
+        extraParameters.push("String? nmsInternalBirthKey");
+        arguments_.push("nmsInternalBirthKey");
+        access.set(BUSINESS_BIRTH_KEY_PAYLOAD_FIELD, {
+          value: "nmsInternalBirthKey!",
+          present: "nmsInternalBirthKey != null",
+        });
+      }
     }
     for (const input of dartBusinessRecordInputs(directive, mod.aggregates)) {
       const origin = `NmsInternalRecordOrigins.require(payload.${input.argument})`;
@@ -1954,7 +1978,8 @@ export function generateDartDomainClient(
           domain: string;
           rootId: string;
           namespace: string;
-          keyField: string;
+          keyField?: string;
+          keyType?: { type: string; brand: string };
           seedDirectiveId?: string;
           genesisDirectiveIds?: readonly string[];
           publicPayloadSchema: z.ZodTypeAny;
@@ -2010,6 +2035,18 @@ export function generateDartDomainClient(
       const birthSpecsByName = new Map(
         birthSpecs.map((spec) => [spec.name, spec])
       );
+      // A minted birth (the default) has no business key; an owned one seals to the child's address
+      // before dispatch, so it reserves its key from the kernel's own minter and hands it to the law.
+      const mintedBirth = businessBirth.keyField === undefined;
+      const birthKeyPrelude = !mintedBirth
+        ? []
+        : ownedBirthDescriptor === undefined
+        ? [`    const String? nmsInternalBirthKey = null;`]
+        : [
+            `    final String? nmsInternalBirthKey = await session.mintId(${dartStr(
+              businessBirth.aggregateId
+            )});`,
+          ];
       const ownedBirthPrelude =
         ownedBirthDescriptor === undefined
           ? []
@@ -2017,9 +2054,17 @@ export function generateDartDomainClient(
               `    final nmsInternalOwnedKey = await session.nomosOwnedBirthScopeKey(`,
               `        ${dartStr(ownedBirthDescriptor.scope)}, ${dartStr(
                 businessBirth.namespace
-              )}, payload.${dartMemberName(businessBirth.keyField)}, ${dartStr(
-                birthRuntimeType!
-              )}, ${dartStr(businessBirth.rootId)});`,
+              )}, ${
+                mintedBirth
+                  ? "nmsInternalBirthKey!"
+                  : `payload.${dartMemberName(businessBirth.keyField!)}${
+                      businessBirth.keyType?.type === "brandedId" || businessBirth.keyType?.type === "uuid"
+                        ? ".value"
+                        : ""
+                    }`
+              }, ${dartStr(birthRuntimeType!)}, ${dartStr(
+                businessBirth.rootId
+              )});`,
               `    final nmsInternalOwnedKeySubject = nmsInternalOwnedKey.ownedKeySubject;`,
               `    if (nmsInternalOwnedKeySubject == null || nmsInternalOwnedKeySubject.isEmpty) {`,
               `      throw StateError('Nomos did not return the framework-owned device identity for .owned() custody');`,
@@ -2148,6 +2193,7 @@ export function generateDartDomainClient(
               ),
             ]),
         `    final bornAt = DateTime.now().toUtc().toIso8601String();`,
+        ...birthKeyPrelude,
         ...ownedBirthPrelude,
         ...birthSealPrelude,
         ...(birthEncryption === undefined

package/src/codegen_dart_facade.ts

@@ -5,6 +5,7 @@ import { refusalContracts, refusalType, refusalDecoder } from "./codegen_refusal
 // application contract: business inputs in, business ids/models out. It deliberately has no public
 // session/session/workspace/actor/sync surface.
 import type { z } from "zod";
+import { brandedIdMetaOf } from "./value_object.js";
 
 import type { AggregateHandle } from "./aggregate.js";
 import type { Directive } from "./directive.js";
@@ -153,6 +154,11 @@ function keyType(
   ) {
     return "GitObjectId";
   }
+  // A typed-id key (`t.brandedId(Name)` / `t.uuid()`) is its extension type, never a bare String.
+  if (field?.kind === "string" && !key.includes(".")) {
+    const brand = brandedIdMetaOf(field.zod as z.ZodTypeAny);
+    if (brand !== undefined) return brand;
+  }
   return "String";
 }
 
@@ -381,7 +387,7 @@ export function generateDartApplication(
           const source = aggregate.fields[name]!;
           const value = source.kind === "enum" ? `${access}?.wire`
             : source.kind === "ref" ? `${access}?.id`
-            : source.kind === "string" && (isSha256DigestSchema(source.zod) || isGitObjectIdSchema(source.zod)) ? `${access}?.value`
+            : source.kind === "string" && (isSha256DigestSchema(source.zod) || isGitObjectIdSchema(source.zod) || brandedIdMetaOf(source.zod as z.ZodTypeAny) !== undefined) ? `${access}?.value`
             : access;
           return `      ${member(name)}: ${value},`;
         }),
@@ -900,7 +906,9 @@ export function generateDartApplication(
           aggregateId: string;
           namespace: string;
           rootId: string;
-          keyField: string;
+          keyMode?: "minted" | "field";
+          keyField?: string;
+          keyType?: { type: string; brand: string };
         };
         birthsChild?: boolean;
       }
@@ -993,39 +1001,53 @@ export function generateDartApplication(
           `    return _nmsReception.fetchWorkspace(reference.workspace);`,
           `  }`,
           ``,
-          `  /// Open the ${birth.aggregateId} whose ${birth.keyField} is [key].`,
-          `  /// THE OFFICE NAMES THE WORKSPACE this key addresses: the derivation is law,`,
-          `  /// and a generated copy of it would silently address a different workspace`,
-          `  /// the moment either side moved.`,
-          `  Future<${targetApplication}> open(String key) async => _nmsOpenReference(`,
-          `    NmsInternalNomosRefs.create<${rootType}>(`,
-          `      workspace: await _nmsReception.keyedBirthWorkspace(`,
-          `        namespace: ${JSON.stringify(birth.namespace)}, key: key,`,
-          `      ),`,
-          `      type: ${JSON.stringify(birth.aggregateId)},`,
-          `      id: ${JSON.stringify(birth.rootId)},`,
-          `    ),`,
-          `  );`,
-          ``,
-          `  /// Fetch the ${birth.aggregateId} whose ${birth.keyField} is [key] onto this device now,`,
-          `  /// opening and reading nothing: its placement's follow mounts the provider's head in`,
-          `  /// the background. Completes once that follow exists (e.g. prefetching every workspace`,
-          `  /// a list names, all at once, so each is local before it is tapped).`,
-          `  Future<void> fetch(String key) async => _nmsReception.fetchWorkspace(`,
-          `    await _nmsReception.keyedBirthWorkspace(`,
-          `      namespace: ${JSON.stringify(birth.namespace)}, key: key,`,
-          `    ),`,
-          `  );`,
-          ``,
-          `  /// Kernel-owned progress updates while [open] prepares this workspace.`,
-          `  /// ONE LANE: the stream is the whole surface. A synchronous snapshot`,
-          `  /// would have to answer before the office has named the workspace, so`,
-          `  /// it could only ever answer null or hold a cached name of its own.`,
-          `  Stream<ApplicationWorkspaceOpenProgress> watchOpenProgress(String key) =>`,
-          `      Stream<String>.fromFuture(_nmsReception.keyedBirthWorkspace(`,
-          `        namespace: ${JSON.stringify(birth.namespace)}, key: key,`,
-          `      )).asyncExpand(_nmsReception.streams.workspaceOpenProgress);`,
-          ``,
+          // Open/fetch BY KEY exist only for a birth keyed by a declared business fact. A minted birth
+          // (the default) has no business key: its address is the NomosRef its birth returned.
+          // The key param is the key field's TYPED ID (its extension type, declared with the birth payload in
+          // this domain's types); `.value` is its wire string.
+          ...(birth.keyField === undefined
+            ? []
+            : (() => {
+              const typedKey = birth.keyType !== undefined &&
+                (birth.keyType.type === "brandedId" || birth.keyType.type === "uuid");
+              const keyParam = typedKey ? `${birth.keyType!.brand} key` : "String key";
+              const keyWire = typedKey ? "key.value" : "key";
+              return [
+              `  /// Open the ${birth.aggregateId} whose ${birth.keyField} is [key].`,
+              `  /// THE OFFICE NAMES THE WORKSPACE this key addresses: the derivation is law,`,
+              `  /// and a generated copy of it would silently address a different workspace`,
+              `  /// the moment either side moved.`,
+              `  Future<${targetApplication}> open(${keyParam}) async => _nmsOpenReference(`,
+              `    NmsInternalNomosRefs.create<${rootType}>(`,
+              `      workspace: await _nmsReception.keyedBirthWorkspace(`,
+              `        namespace: ${JSON.stringify(birth.namespace)}, key: ${keyWire},`,
+              `      ),`,
+              `      type: ${JSON.stringify(birth.aggregateId)},`,
+              `      id: ${JSON.stringify(birth.rootId)},`,
+              `    ),`,
+              `  );`,
+              ``,
+              `  /// Fetch the ${birth.aggregateId} whose ${birth.keyField} is [key] onto this device now,`,
+              `  /// opening and reading nothing: its placement's follow mounts the provider's head in`,
+              `  /// the background. Completes once that follow exists (e.g. prefetching every workspace`,
+              `  /// a list names, all at once, so each is local before it is tapped).`,
+              `  Future<void> fetch(${keyParam}) async => _nmsReception.fetchWorkspace(`,
+              `    await _nmsReception.keyedBirthWorkspace(`,
+              `      namespace: ${JSON.stringify(birth.namespace)}, key: ${keyWire},`,
+              `    ),`,
+              `  );`,
+              ``,
+              `  /// Kernel-owned progress updates while [open] prepares this workspace.`,
+              `  /// ONE LANE: the stream is the whole surface. A synchronous snapshot`,
+              `  /// would have to answer before the office has named the workspace, so`,
+              `  /// it could only ever answer null or hold a cached name of its own.`,
+              `  Stream<ApplicationWorkspaceOpenProgress> watchOpenProgress(${keyParam}) =>`,
+              `      Stream<String>.fromFuture(_nmsReception.keyedBirthWorkspace(`,
+              `        namespace: ${JSON.stringify(birth.namespace)}, key: ${keyWire},`,
+              `      )).asyncExpand(_nmsReception.streams.workspaceOpenProgress);`,
+              ``,
+              ];
+            })()),
         ]);
         addCollectionMember(birth.aggregateId, "mine", [
           `  /// The ${birth.aggregateId} lives founded by the signed-in person.`,

package/src/codegen_dart_framework_calls.ts

@@ -1,3 +1,4 @@
+import { assertDomainRequirements, type DomainUnitRequirement } from "./domain_requirements.js";
 import type { z } from "zod";
 
 import type { Directive } from "./directive.js";
@@ -177,6 +178,12 @@ export function generateDartApplicationFrameworkCalls(
     readonly lawUnitSet: string;
     /** The compiled package closure (`build/<name>.law.usdz`): the bytes a device stages. Not what a target serves. */
     readonly lawPackageSha256: string;
+    /**
+     * THE PER-DOMAIN REQUIREMENTS (CAP-666): per application domain key, its unit hash and the identity of its
+     * generated compatibility requirement. Absent or empty emits an empty table (a package with no application
+     * interface); the getter itself is always emitted, since the runtime interface is exhaustive.
+     */
+    readonly domainRequirements?: readonly DomainUnitRequirement[];
   },
 ): string | undefined {
   for (const [name, value] of [["law unit set", descriptor.lawUnitSet], ["package", descriptor.lawPackageSha256]] as const) {
@@ -184,6 +191,8 @@ export function generateDartApplicationFrameworkCalls(
       throw new Error(`Dart framework call codegen: the application's ${name} identity must be 64 lowercase hex, not '${value}'`);
     }
   }
+  const domainRequirements = [...(descriptor.domainRequirements ?? [])].sort((a, b) => a.domainKey < b.domainKey ? -1 : a.domainKey > b.domainKey ? 1 : 0);
+  assertDomainRequirements(domainRequirements);
   const frameworkEnumDartTypes = collectFixedFrameworkDartEnums().dartTypes;
   const fixedEmitted = FIXED_CALLS.flatMap((definition) => laws.flatMap((law) => {
     const declares = law.graph.nodes.some((node) =>
@@ -622,7 +631,7 @@ export function generateDartApplicationFrameworkCalls(
     `import 'package:fixnum/fixnum.dart' show Int64;`,
     `import 'operation_payloads.pb.dart' as _nmsop;`,
     `import 'package:nomos_types/nomos_kernel_protocol.dart' show BirthCertificate;`,
-    `import 'package:nomos_types/nomos_types.dart' show NomosSlot, Sha256Digest;`,
+    `import 'package:nomos_types/nomos_types.dart' show NomosDomainRequirement, NomosSlot, Sha256Digest;`,
     `import 'package:nomos_client/src/application_framework_calls.dart';`,
     `import 'package:nomos_client/src/generated_call.dart';`,
     ``,
@@ -651,6 +660,16 @@ export function generateDartApplicationFrameworkCalls(
     `  String get lawUnitSet => ${JSON.stringify(descriptor.lawUnitSet)};`,
     `  @override`,
     `  String get lawPackageSha256 => ${JSON.stringify(descriptor.lawPackageSha256)};`,
+    `  @override`,
+    ...(domainRequirements.length === 0
+      ? [`  Map<String, NomosDomainRequirement> get domainRequirements => const {};`]
+      : [
+          `  Map<String, NomosDomainRequirement> get domainRequirements => const {`,
+          ...domainRequirements.map((requirement) =>
+            `    ${JSON.stringify(requirement.domainKey)}: NomosDomainRequirement(domainKey: ${JSON.stringify(requirement.domainKey)}, `
+            + `unitSha256: ${JSON.stringify(requirement.unitSha256)}, requirementSha256: ${JSON.stringify(requirement.requirementSha256)}),`),
+          `  };`,
+        ]),
     ``,
     ...methods,
     `}`,