@githolon/dsl 0.113.4 → 0.115.0

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
@@ -3172,6 +3181,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 +3274,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 +3429,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 +5014,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 +5178,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 +5218,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`,

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": {
@@ -815,7 +830,7 @@ function emitDartUsdaResultDecoder(
 }
 
 export interface DartClientOptions {
-  /** Content identity of the built typed USDA closure (`.law.usdz`). */
+  /** THE LAW the client is generated against: the unit set identity of `build/<name>.units` (CAP-773). */
   readonly domainHash: string;
   /** Flutter asset key for the compiler-authored USDZ transport. Generated
    * child openers use it to inherit an accepted parent model through the
@@ -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
@@ -2282,19 +2328,30 @@ export function generateDartDomainClient(
     const qOwned = qScopes.some((scope) => scope.owned === true);
     const qPrivate = needsReadPrincipal(q.returns);
     const qScopesExpr = scopesExpr(qScopes);
+    // CAP-731: a declared rows watch whose keys the client does not re-derive per read merges
+    // kernel row deltas (O(changed) per local write) instead of re-decoding the whole result.
+    // Ordered reads keep complete results: their order is the law's, not the id's.
+    const rowsWatch = (keys: string) =>
+      `session.nmsWatchRows(${queryCall}, decode: (result) => ${decodeRows}(result, _ws), idOf: (row) => row.ref.id${keys}${
+        qPrivate ? ", principal: actor" : ""
+      })`;
     const nominalWatch = qOwned
       ? `session.nmsWatch(${queryCall}${
           qPrivate ? ", principal: actor" : ""
         }).asyncMap((result) async => _readWithOwnedKeys(${qScopesExpr}, (keys) async => ${decodeRows}(await session.nmsQuery(${queryCall}, keys${
           qPrivate ? ", actor" : ""
         }), _ws), (row) => row.ref, initial: await ${decodeRows}(result, _ws)))`
+      : ordered !== undefined
+      ? qScopes.length
+        ? `Stream.fromFuture(_readKeys(${qScopesExpr})).asyncExpand((keys) => session.nmsWatch(${queryCall}, keys: keys${
+            qPrivate ? ", principal: actor" : ""
+          }).asyncMap((result) => ${decodeRows}(result, _ws)))`
+        : `session.nmsWatch(${queryCall}${
+            qPrivate ? ", principal: actor" : ""
+          }).asyncMap((result) => ${decodeRows}(result, _ws))`
       : qScopes.length
-      ? `Stream.fromFuture(_readKeys(${qScopesExpr})).asyncExpand((keys) => session.nmsWatch(${queryCall}, keys: keys${
-          qPrivate ? ", principal: actor" : ""
-        }).asyncMap((result) => ${decodeRows}(result, _ws)))`
-      : `session.nmsWatch(${queryCall}${
-          qPrivate ? ", principal: actor" : ""
-        }).asyncMap((result) => ${decodeRows}(result, _ws))`;
+      ? `Stream.fromFuture(_readKeys(${qScopesExpr})).asyncExpand((keys) => ${rowsWatch(", keys: keys")})`
+      : rowsWatch("");
     if (ordered !== undefined) {
       const resultType = ordered.limit === 1 ? `${model}?` : `List<${model}>`;
       const select = ordered.limit === 1 ? "rows.isEmpty ? null : rows.single" : "rows";
@@ -3530,7 +3587,7 @@ export function generateDartDomainClient(
       `      final latest = events.isEmpty ? null : events.first;`,
       `      items = [`,
       `        NomosDescribeItem(kind: 'evidence', id: 'workspace', label: 'Workspace', summary: _ws, details: {'workspace': _ws}),`,
-      `        NomosDescribeItem(kind: 'evidence', id: 'law', label: 'Generated law', summary: domainHash, details: {'domainHash': domainHash}),`,
+      `        NomosDescribeItem(kind: 'evidence', id: 'law', label: 'Generated law (unit set)', summary: domainHash, details: {'lawUnitSet': domainHash}),`,
       `        NomosDescribeItem(kind: 'evidence', id: 'reader', label: 'Verified reader', summary: this.actor ?? 'anonymous', details: {'actor': this.actor}),`,
       `        if (latest != null) NomosDescribeItem(kind: 'evidence', id: latest.eventId, label: 'Latest verified moment', summary: latest.eventId,`,
       `          details: {'occurredAt': latest.occurredAt, 'performedBy': latest.performedBy, 'domain': latest.domain, 'kind': latest.kind}),`,
@@ -3630,7 +3687,8 @@ export function generateDartDomainClient(
       ? [`export '${opts.frameworkImportUri}';`]
       : []),
     ``,
-    `/// Content identity of the installed typed USDA closure (transported as \`.law.usdz\`).`,
+    `/// The law this client was generated against: its unit set identity (\`build/<name>.units.sha256\`).`,
+    `/// Each workspace serves a closure its own kernel composes from those units; never sent with an offer.`,
     `const String ${hashConst} = ${dartStr(opts.domainHash)};`,
     ``,
     ...(opts.emitActivity === true

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.`,
@@ -1907,6 +1929,7 @@ export function generateDartApplication(
     `// AUTO-GENERATED by nomos-compile — the tenant application surface for "${domain}".`,
     `// Business facts in, business records out. Runtime lifecycle is deliberately absent.`,
     `export 'package:nomos_client/src/write_progress.dart' show NomosWrite, NomosWriteProgress, NomosWritePhase;`,
+    `export 'package:nomos_client/src/rows_watch.dart' show NomosRows, NomosRowProjection, NomosRowsProjectionStream;`,
     ...((mod.workspaceInvariants ?? []).some(rule => rule.refusal) ? [
       `export 'package:nomos_types/nomos_types.dart' show AdmissionDecision, Admitted, DomainRefused, FrameworkRefused, UnsupportedRefusalContract, NomosDomainRefusalEvidence, KernelRefusalCode;`,
     ] : []),

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";
@@ -173,15 +174,25 @@ export function dartFrameworkOperationDirectiveIds(
 export function generateDartApplicationFrameworkCalls(
   laws: readonly DartFrameworkCallLaw[],
   descriptor: {
-    /** The compiled law package identity — the descriptor's own closure, `currentLaw[<application-home domain>]`. */
-    readonly lawSha256: string;
+    /** THE LAW the application is compiled as: the unit set identity of `build/<name>.units` (CAP-773). */
+    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 {
-  if (!/^[0-9a-f]{64}$/.test(descriptor.lawSha256)) {
-    throw new Error(
-      `Dart framework call codegen: the application birth contract needs the compiled law package sha256 identity, not '${descriptor.lawSha256}'`,
-    );
+  for (const [name, value] of [["law unit set", descriptor.lawUnitSet], ["package", descriptor.lawPackageSha256]] as const) {
+    if (!/^[0-9a-f]{64}$/.test(value)) {
+      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) =>
@@ -619,8 +630,8 @@ export function generateDartApplicationFrameworkCalls(
     `import 'dart:typed_data' show Uint8List;`,
     `import 'package:fixnum/fixnum.dart' show Int64;`,
     `import 'operation_payloads.pb.dart' as _nmsop;`,
-    `import 'package:nomos_types/nomos_kernel_protocol.dart' show ApplicationBirthContract, BirthCertificate;`,
-    `import 'package:nomos_types/nomos_types.dart' show NomosSlot, Sha256Digest;`,
+    `import 'package:nomos_types/nomos_kernel_protocol.dart' show BirthCertificate;`,
+    `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';`,
     ``,
@@ -646,8 +657,19 @@ export function generateDartApplicationFrameworkCalls(
     `  @override`,
     `  String get parentModelAuthoritySeatId => ${JSON.stringify(PARENT_MODEL_AUTHORITY_SEAT_ID)};`,
     `  @override`,
-    `  ApplicationBirthContract get applicationBirthContract =>`,
-    `      ApplicationBirthContract(lawSha256: ${JSON.stringify(descriptor.lawSha256)});`,
+    `  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,
     `}`,

package/src/codegen_dart_scenario.ts

@@ -123,6 +123,7 @@ export function generateDartScenario(
     `import 'package:nomos_client/src/reception/reception_session.dart' show NmsReceptionUser, NmsReceptionSessionView;`,
     `import 'package:nomos_client/src/nms_generated_runtime.dart' show NomosSession;`,
     `import 'package:nomos_client/src/nms_test_environment.dart' show NomosTestCloud, NomosTestHarness, NomosTestFrontier;`,
+    `import 'package:nomos_flutter/testing.dart' show registerNomosNativeTestPeerHost;`,
     ``,
     `// The office names the framework's identity anchor; a scenario never re-derives it.`,
     `Future<NmsReceptionSessionView> _nmsTestReception(`,
@@ -212,6 +213,9 @@ export function generateDartScenario(
     `    void Function(Future<void> Function())? registerTearDown,`,
     `  }) async {`,
     `    final person = signedInAs ?? ${testPerson}.named('test');`,
+    `    // Make the Apple native test peer host available; NOMOS_TEST_PEER_HOST=native selects it.`,
+    `    // Registering never selects it, so the default Node peer is unchanged.`,
+    `    registerNomosNativeTestPeerHost();`,
     `    final packageFiles = await _applicationPackages();`,
     `    final environment = await NomosTestHarness.ephemeral(`,
     `      lawUsdzPaths: packageFiles.map((file) => file.path).toList(growable: false),`,
@@ -244,6 +248,9 @@ export function generateDartScenario(
     `    if (serverEntry == null || serverEntry.isEmpty) {`,
     `      throw StateError('Connected scenarios require the Nomos test cloud. Run this test through githolon test.');`,
     `    }`,
+    `    // Make the Apple native test peer host available; NOMOS_TEST_PEER_HOST=native selects it.`,
+    `    // Registering never selects it, so the default Node peer is unchanged.`,
+    `    registerNomosNativeTestPeerHost();`,
     `    final applicationName = 'test-application-\${DateTime.now().microsecondsSinceEpoch}';`,
     `    final packageFiles = await _applicationPackages();`,
     `    final cloud = await NomosTestCloud.start(`,

package/src/codegen_proof.ts

@@ -32,6 +32,7 @@
  * Deterministic codegen: the emitted bytes are a pure function of the modules +
  * package name + domain hash — no timestamps or generation-time randomness.
  */
+import { BUSINESS_BIRTH_KEY_PAYLOAD_FIELD } from "./births.js";
 import type { z } from "zod";
 
 import { BUSINESS_BIRTH_SEED_PAYLOAD_FIELD, type AggregateHandle } from "./aggregate.js";
@@ -2836,10 +2837,12 @@ function attachBusinessEncryption(
   const directive = (mod?.directives as Directive<unknown>[] | undefined)?.find(
     (candidate) => candidate.id === leg.birthDirectiveId,
   ) as (Directive<unknown> & {
-    businessBirth?: { namespace?: string; keyField?: string };
+    businessBirth?: { namespace?: string; keyField?: string; keyMode?: string };
   }) | undefined;
   const namespace = directive?.businessBirth?.namespace;
-  const keyField = directive?.businessBirth?.keyField;
+  // A minted birth's key rides the hidden reserved-key field (CAP-804).
+  const keyField = directive?.businessBirth?.keyField
+    ?? (directive?.businessBirth?.keyMode === "minted" ? BUSINESS_BIRTH_KEY_PAYLOAD_FIELD : undefined);
   const offered = packageInterface[leg.parentDomain];
   const offeredAggregate = offered === undefined
     ? undefined