@githolon/dsl 0.101.5 → 0.102.0

package/src/codegen_dart_client.ts

@@ -7,21 +7,21 @@
  * ASYNC DART BRIDGE-CLIENT CODEGEN (#61) — the Flutter sibling of `codegen_ts.ts`.
  *
  * `codegen_dart.ts` emits the per-domain TYPES: read-model classes (`…ReadModel.fromProjected`),
- * typed intent DTOs (`…Payload.toPayloadJson()`), typed ids, enums. Until this file a Flutter app
+ * typed action inputs (`…Input` publicly; private directives retain `…Payload`), typed ids and enums. Until this file a Flutter app
  * still hand-typed directive ids + query ids against the raw `NomosBridge` (string + Map). This closes
  * that: ONE generated `<name>.client.dart` per domain, emitted by `nomos-compile` AFTER the package is
  * hashed (the deployed law's content hash baked in), carrying a `<Domain>Client` over a connected
  * [NomosBridge] (the WebView runner) with:
  *
- *   * a typed OFFER method per directive — takes the generated `…Payload`, serialises via its
- *     `toPayloadJson()`, auto-stamps omitted `…At` timestamps (the same caller-clock sugar the TS
+ *   * a typed OFFER method per directive — takes the generated input/implementation DTO, serialises via its
+ *     `nmsInternalToPayloadJson()`, auto-stamps omitted `…At` timestamps (the same caller-clock sugar the TS
  *     client applies), returns the new local head;
  *   * a typed declared-QUERY accessor per `query(...)` — one-shot `Future<List<…ReadModel>>` + a
  *     reactive `watch…` `Stream<List<…ReadModel>>`, parsed off the bridge's `{type,id,data}` rows;
  *   * by-id read/watch + a type-index `list…` per aggregate;
  *   * typed O(1) count/sum accessors.
  *
- * It IMPORTS the sibling `<name>.dart` (for the read-model + payload classes) and either the vendored
+ * It IMPORTS the sibling `<name>.dart` (for the read-model + input classes) and either the vendored
  * `nomos_client.dart` barrel or the package `nomos_client` barrel (for `NomosBridge`). NO manifest/hash impact —
  * pure frontend codegen, exactly like `codegen_dart.ts`. NO FALLBACK: an unsupported shape throws at compile
  * time.
@@ -46,18 +46,22 @@ import {
   dartRoleHelpers,
   registerDartNames,
   concreteClassName,
+  dartBusinessRecordInputs,
+  dartActionInputClassName,
   dartMemberName,
 } from "./codegen_dart.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
 import { autoStampFields, domainEncryptionMap, type EncDomainMap, type InterfaceAggShape } from "./codegen_ts.js";
 import { isNamespacedAggregate, qualifyReadProjectionType } from "./read_projection_namespace.js";
+import { isBusinessIntent } from "./intent.js";
 import { publicClientInterface, type DomainInterface } from "./shape_compat.js";
 import { BUSINESS_CORRECTION_DIRECTIVE } from "./framework/business_corrections.js";
 import { deriveDirectiveRecordTarget } from "./workspace_routing.js";
 import { buildNomosDescribeModel, type NomosDescribeModel } from "./describe_model.js";
 import { assertModelClientMemberAvailable } from "./generated_client_names.js";
 import { ownedRecordActionDirectiveId } from "./framework/owned_custody.js";
+import { contractTypeName } from "./contract.js";
 
 const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
 const lcFirst = (s: string) => (s.length ? s[0]!.toLowerCase() + s.slice(1) : s);
@@ -92,11 +96,31 @@ function dartRawJson(value: unknown): string {
 
 const dartStr = (s: string) => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
 
-/** The Dart param type for a query index key (int-kinded keys → `int`, else `String`). */
+/** The Dart param type for a query index key. Aggregate relations keep their canonical typed ref. */
 function dartKeyType(agg: AggregateHandle | undefined, key: string): string {
   const lead = key.includes(".") ? key.split(".")[0]! : key;
   const f = agg?.fields[lead] as Field | undefined;
-  return f && (f.kind === "int" || f.kind === "counter") ? "int" : "String";
+  if (f && (f.kind === "int" || f.kind === "counter")) return "int";
+  if (f?.kind === "ref") {
+    if (f.foreignRef !== undefined) {
+      const target = f.foreignRef.targetIsContract === true
+        ? contractTypeName(f.foreignRef.targetAggregateId)
+        : concreteClassName(f.foreignRef.targetAggregateId);
+      return `ForeignRef<${target}>`;
+    }
+    if (f.refAggregateId !== undefined) return `NomosRef<${concreteClassName(f.refAggregateId)}>`;
+  }
+  return "String";
+}
+
+function dartKeyExpr(agg: AggregateHandle | undefined, key: string): string {
+  const lead = key.includes(".") ? key.split(".")[0]! : key;
+  const field = agg?.fields[lead] as Field | undefined;
+  const param = dartKeyParam(key);
+  if (field?.kind !== "ref") return param;
+  return field.foreignRef !== undefined
+    ? `NmsInternalNomosRefs.id(${param}.ref)`
+    : `NmsInternalNomosRefs.id(${param})`;
 }
 
 /** A Dart-safe param identifier from a (possibly dotted) index key: `a.b.c` → `aBC`. */
@@ -112,7 +136,7 @@ function dartKeyParam(key: string): string {
  * session workspace (`_ws`, a getter on the client) + the row's type/id. Works for a `Map` (one-shot
  * `query`/`queryById` rows) or a `dynamic` (`watch` stream rows) — indexing resolves on both. */
 function rowToModel(model: string, rowVar: string, workspace = "_ws"): string {
-  return `${model}.fromProjected((${rowVar}['data'] as Map).cast<String, dynamic>(), (${rowVar}['id'] ?? '').toString(), ${workspace}, (${rowVar}['type'] ?? '').toString())`;
+  return `NmsInternalRecordOrigins.remember(${model}.fromProjected((${rowVar}['data'] as Map).cast<String, dynamic>(), (${rowVar}['id'] ?? '').toString(), ${workspace}, (${rowVar}['type'] ?? '').toString()), workspace: ${workspace}, type: (${rowVar}['type'] ?? '').toString(), id: (${rowVar}['id'] ?? '').toString())`;
 }
 
 export interface DartBridgeClientOptions {
@@ -186,10 +210,11 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     (a) => (a as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
   );
   const publicAggregateIds = new Set(publicAggregates.map((a) => a.id));
+  const publicDirectives = mod.applicationIntents ?? mod.directives;
   mod = {
     ...mod,
     aggregates: publicAggregates,
-    directives: mod.directives.filter(
+    directives: publicDirectives.filter(
       (d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
     ),
     ...(mod.queries === undefined
@@ -214,7 +239,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   const requiresKernelFeats = requiredKernelFeatures([mod]);
   const supportImport =
     opts.supportImport === "package"
-      ? "package:nomos_client/nomos_client.dart"
+      ? "package:nomos_client/src/nms_generated_runtime.dart"
       : "nomos_client.dart";
   const aggById = new Map<string, AggregateHandle>();
   for (const a of mod.aggregates) aggById.set(a.id, a);
@@ -255,17 +280,23 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   };
   const scopesExpr = (scopes: readonly { scope: string; owned?: true }[]): string =>
     `[${scopes.map((s) => `{${dartStr("scope")}: ${dartStr(s.scope)}${s.owned === true ? `, ${dartStr("owned")}: true` : ""}}`).join(", ")}]`;
+  const needsReadPrincipal = (typeId: string): boolean => {
+    const audience = aggById.get(typeId)?.audience;
+    return audience?.kind === "readableBy" || audience?.kind === "owned";
+  };
   const keysArg = (typeId: string): string => {
     const scopes = readScopesFor(typeId);
-    return scopes.length
-      ? `, await _readKeys(${scopesExpr(scopes)})`
-      : "";
+    if (scopes.length) {
+      return `, await _readKeys(${scopesExpr(scopes)})${needsReadPrincipal(typeId) ? ", actor" : ""}`;
+    }
+    return needsReadPrincipal(typeId) ? ", null, actor" : "";
   };
   const pastKeysArg = (typeId: string): string => {
     const scopes = readScopesFor(typeId);
-    return scopes.length
-      ? `, await _client._readKeys(${scopesExpr(scopes)})`
-      : "";
+    if (scopes.length) {
+      return `, await _client._readKeys(${scopesExpr(scopes)})${needsReadPrincipal(typeId) ? ", _client.actor" : ""}`;
+    }
+    return needsReadPrincipal(typeId) ? ", null, _client.actor" : "";
   };
   // The DISTINCT encryption scopes this domain defines (across encrypted reads + sealing directives) — the
   // set the owner ceremony rotates. Empty ⇒ no `encryption` getter is emitted for this domain.
@@ -310,13 +341,13 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   if (ownedScope !== undefined && Object.keys(ownedActions).length > 0) {
     methods.push(
       `  /// Share one record. The peer can read its history and future changes; Nomos owns the keys and policy.`,
-      `  Future<NomosOfferOutcome> share(NomosRef record, String peer) => _ownedRecordAction('share', record, peer);`,
+      `  Future<NomosOfferOutcome> share<TAggregate>(NomosRef<TAggregate> record, String peer) => _ownedRecordAction('share', record, peer);`,
       ``,
       `  /// Stop sharing one record. Earlier knowledge cannot be erased; future changes use a fresh private key.`,
-      `  Future<NomosOfferOutcome> unshare(NomosRef record, String peer) => _ownedRecordAction('unshare', record, peer);`,
+      `  Future<NomosOfferOutcome> unshare<TAggregate>(NomosRef<TAggregate> record, String peer) => _ownedRecordAction('unshare', record, peer);`,
       ``,
       `  /// Hand ownership, readable history and future authority for one record to another person.`,
-      `  Future<NomosOfferOutcome> transfer(NomosRef record, String peer) => _ownedRecordAction('transfer', record, peer);`,
+      `  Future<NomosOfferOutcome> transfer<TAggregate>(NomosRef<TAggregate> record, String peer) => _ownedRecordAction('transfer', record, peer);`,
       ``,
     );
   }
@@ -381,7 +412,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     );
   }
   for (const d of dirs) {
-    const payloadClass = `${cap(d.id)}Payload`;
+    const payloadClass = dartActionInputClassName(d);
     const stamps = autoStampFields((d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema);
     const method = safeMethod(d.id);
     // THE AUTHORITY GATE (codegen-time): a directive carrying `.requires(relation)` is GATED — its method
@@ -411,6 +442,28 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const createsDoc = (d as { marker?: string }).marker === "creates"
       ? ` The LAW mints the ${(d as { aggregateId?: string }).aggregateId ?? "aggregate"} id inside the sealed intent — it rides back on \`outcome.created\` (no id in the payload, no query-after).`
       : "";
+    const recordInputs = dartBusinessRecordInputs(d, mod.aggregates);
+    const principalField = d.businessPrincipalField;
+    const principalPrelude = principalField === undefined
+      ? []
+      : [
+          `    final nmsInternalPrincipal = actor ?? bridge.principal;`,
+          `    if (nmsInternalPrincipal == null || nmsInternalPrincipal.trim().isEmpty) {`,
+          `      throw MissingOfferAuthority(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, requires: 'the signed-in Nomos principal');`,
+          `    }`,
+        ];
+    const payloadJsonArgs = [
+      ...(principalField === undefined ? [] : ["nmsInternalPrincipal: nmsInternalPrincipal"]),
+      ...(recordInputs.length === 0
+        ? []
+        : [
+            "nmsInternalLocationOf: (record) => NmsInternalRecordOrigins.require(record).workspace",
+            "nmsInternalIdOf: (record) => NmsInternalRecordOrigins.require(record).id",
+          ]),
+    ];
+    const payloadJson = payloadJsonArgs.length === 0
+      ? "payload.nmsInternalToPayloadJson()"
+      : `payload.nmsInternalToPayloadJson(${payloadJsonArgs.join(", ")})`;
     const stampsDoc = stamps.length > 0 ? `\n  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.` : "";
     const directiveEncryption = encMap?.directives?.[d.id];
     if (directiveEncryption !== undefined) {
@@ -453,7 +506,8 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         ...(gateDoc ? [gateDoc] : []),
         `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload${ownedSeal && !wantAttest ? "" : `, {${ownedSeal ? "" : "bool seal = true"}${wantAttest ? `${ownedSeal ? "" : ", "}${attNamed}` : ""}}`}) async {`,
         ...(gateGuard ? [gateGuard] : []),
-        `    final data = payload.toPayloadJson();`,
+        ...principalPrelude,
+        `    final data = ${payloadJson};`,
         ...(stamps.length > 0
           ? [
               `    final now = DateTime.now().toUtc().toIso8601String();`,
@@ -474,21 +528,24 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         ...(gateDoc ? [gateDoc] : []),
         `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload${wantAttest ? ", {" + attNamed + "}" : ""}) {`,
         ...(gateGuard ? [gateGuard] : []),
-        `    final data = payload.toPayloadJson();`,
+        ...principalPrelude,
+        `    final data = ${payloadJson};`,
         `    final now = DateTime.now().toUtc().toIso8601String();`,
         ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
         `    return _offer(${dartStr(d.id)}, data${attArg});`,
         `  }`,
         ``,
       );
-    } else if (gateGuard) {
-      // A gated directive with no `…At` sugar still needs a block body for the throw guard.
+    } else if (gateGuard || principalPrelude.length > 0) {
+      // A gated or principal-bound directive with no timestamp sugar still needs a block body
+      // for the framework-owned identity guard and payload binding.
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
         gateDoc,
         `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload${wantAttest ? ", {" + attNamed + "}" : ""}) {`,
-        gateGuard,
-        `    return _offer(${dartStr(d.id)}, payload.toPayloadJson()${attArg});`,
+        ...(gateGuard ? [gateGuard] : []),
+        ...principalPrelude,
+        `    return _offer(${dartStr(d.id)}, ${payloadJson}${attArg});`,
         `  }`,
         ``,
       );
@@ -497,7 +554,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
         ...(gateDoc ? [gateDoc] : []),
         `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload${wantAttest ? ", {" + attNamed + "}" : ""}) =>`,
-        `      _offer(${dartStr(d.id)}, payload.toPayloadJson()${attArg});`,
+        `      _offer(${dartStr(d.id)}, ${payloadJson}${attArg});`,
         ``,
       );
     }
@@ -509,12 +566,13 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   // domain's key + directiveId + baked domainHash are all bound at codegen time, so a frontend dev
   // never hand-writes the four raw strings this replaces (the co2 production bug).
   for (const d of birthDirs) {
-    const payloadClass = `${cap(d.id)}Payload`;
     const method = safeMethod(d.id);
+    const publicMethod = isBusinessIntent(d) ? method : "birth";
     const gate = (d as { requiresRelationGate?: { relation: string } }).requiresRelationGate;
     const businessBirth = (d as unknown as {
       businessBirth?: { aggregateId: string; rootId: string; namespace: string; keyField: string; publicPayloadSchema: z.ZodTypeAny };
     }).businessBirth;
+    const payloadClass = dartActionInputClassName(d);
     if (businessBirth !== undefined) {
       const birthEncryption = encMap?.directives?.[d.id];
       const ownedBirthDescriptor = birthEncryption === undefined
@@ -523,12 +581,12 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       methods.push(
         `  /// Give one ${businessBirth.aggregateId} its own durable life. Nomos owns identity, authorship,`,
         `  /// provenance, persistence and recovery; the app supplies only business facts.`,
-        `  Future<NomosRef> birth(${payloadClass} payload) async {`,
+        `  Future<NomosRef<${concreteClassName(businessBirth.aggregateId)}>> ${publicMethod}(${payloadClass} payload) async {`,
         `    final principal = actor ?? bridge.principal;`,
         `    if (principal == null || principal.trim().isEmpty) {`,
         `      throw MissingOfferAuthority(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, requires: 'a signed-in Nomos session');`,
         `    }`,
-        `    final data = payload.toPayloadJson();`,
+        `    final data = payload.nmsInternalToPayloadJson();`,
         ...(ownedBirthDescriptor === undefined
           ? []
           : [
@@ -558,8 +616,10 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
               `      throw StateError('birth() returned a workspace different from the deterministic owned-custody address');`,
               `    }`,
             ]),
-        `    await bridge.sync();`,
-        `    return NomosRef(workspace: outcome.born.single, type: ${dartStr(businessBirth.aggregateId)}, id: ${dartStr(businessBirth.rootId)});`,
+        // Birth is a local, durable business commit. The application host's continuous custody lifecycle
+        // pushes it immediately when online and retries when offline; awaiting a network round here makes
+        // the supposedly offline-first business action hang behind transport availability.
+        `    return NmsInternalNomosRefs.create<${concreteClassName(businessBirth.aggregateId)}>(workspace: outcome.born.single, type: ${dartStr(businessBirth.aggregateId)}, id: ${dartStr(businessBirth.rootId)});`,
         `  }`,
         ``,
       );
@@ -600,7 +660,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       `        parent: explicitParent,`,
       `        actor: actor.wire,`,
       `        authorSecret: authorSecret?.wire,`,
-      `        payload: payload.toPayloadJson(),`,
+      `        payload: payload.nmsInternalToPayloadJson(),`,
       `        authToken: authToken,`,
       `      );`,
       `      return NomosOfferOutcome(`,
@@ -623,7 +683,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
           ]
         : []),
       `    await _preflightOnce();`,
-      `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: effActor, domainHash: domainHash);`,
+      `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.nmsInternalToPayloadJson(), actor: effActor, domainHash: domainHash);`,
       `  }`,
       ``,
     );
@@ -634,30 +694,31 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const model = readModelClassName(q.returns);
     const agg = aggById.get(q.returns);
     const params = q.key.map((k) => `required ${dartKeyType(agg, k)} ${dartKeyParam(k)}`).join(", ");
-    const argMap = `{${q.key.map((k) => `${dartStr(k)}: ${dartKeyParam(k)}`).join(", ")}}`;
+    const argMap = `{${q.key.map((k) => `${dartStr(k)}: ${dartKeyExpr(agg, k)}`).join(", ")}}`;
     const m = safeMethod(lcFirst(camel(q.id)));
     const qScopes = readScopesFor(q.returns);
     const qOwned = qScopes.some((scope) => scope.owned === true);
+    const qPrivate = needsReadPrincipal(q.returns);
     const qScopesExpr = scopesExpr(qScopes);
     methods.push(
       `  /// Declared query \`${q.id}\` (indexed probe — routed by the read manifest).${readScopesFor(q.returns).length ? " Encrypted field(s) decrypt when the bound [keyStore] holds the scope key; else they stay opaque envelopes." : ""}`,
       `  Future<List<${model}>> ${m}({${params}}) async =>`,
       qOwned
-        ? `      (await _readWithOwnedKeys(${qScopesExpr}, (keys) => bridge.query(${dartStr(q.id)}, ${argMap}, keys))).map((r) => ${rowToModel(model, "r")}).toList();`
+        ? `      (await _readWithOwnedKeys(${qScopesExpr}, (keys) => bridge.query(${dartStr(q.id)}, ${argMap}, keys${qPrivate ? ", actor" : ""}))).map((r) => ${rowToModel(model, "r")}).toList();`
         : `      (await bridge.query(${dartStr(q.id)}, ${argMap}${keysArg(q.returns)})).map((r) => ${rowToModel(model, "r")}).toList();`,
       ``,
       `  /// Reactive \`${q.id}\` — re-emits on every local change (cancel the subscription to stop).`,
       `  Stream<List<${model}>> watch${cap(camel(q.id))}({${params}}) =>`,
       qOwned
-        ? `      bridge.watch(${dartStr(q.id)}, ${argMap}).asyncMap((_) => _readWithOwnedKeys(${qScopesExpr}, (keys) => bridge.query(${dartStr(q.id)}, ${argMap}, keys))).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`
-        : `      bridge.watch(${dartStr(q.id)}, ${argMap}).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`,
+        ? `      bridge.watch(${dartStr(q.id)}, ${argMap}, null${qPrivate ? ", actor" : ""}).asyncMap((_) => _readWithOwnedKeys(${qScopesExpr}, (keys) => bridge.query(${dartStr(q.id)}, ${argMap}, keys${qPrivate ? ", actor" : ""}))).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`
+        : `      bridge.watch(${dartStr(q.id)}, ${argMap}${qPrivate ? ", null, actor" : ""}).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`,
       ``,
     );
     pastMethods.push(
       `  /// Declared query \`${q.id}\` in the verified world at [moment].`,
       `  Future<List<${model}>> ${m}({${params}}) async =>`,
       qOwned
-        ? `      (await _client._readWithOwnedKeys(${qScopesExpr}, (keys) => _client.bridge.queryAt(moment, ${dartStr(q.id)}, ${argMap}, keys))).map((r) => ${rowToModel(model, "r", "_client._ws")}).toList();`
+        ? `      (await _client._readWithOwnedKeys(${qScopesExpr}, (keys) => _client.bridge.queryAt(moment, ${dartStr(q.id)}, ${argMap}, keys${qPrivate ? ", _client.actor" : ""}))).map((r) => ${rowToModel(model, "r", "_client._ws")}).toList();`
         : `      (await _client.bridge.queryAt(moment, ${dartStr(q.id)}, ${argMap}${pastKeysArg(q.returns)})).map((r) => ${rowToModel(model, "r", "_client._ws")}).toList();`,
       ``,
     );
@@ -683,30 +744,36 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   // ── counts / sums → O(1) typed reads ──
   for (const c of (mod.counts ?? []).map((raw) => finishCount(raw))) {
     const m = safeMethod(lcFirst(camel(c.id)));
+    const aggregate = aggById.get(c.of);
+    const groupType = c.by == null ? "" : dartKeyType(aggregate, c.by);
+    const groupValue = c.by == null ? "" : dartKeyExpr(aggregate, c.by);
     methods.push(
       c.by != null
-        ? `  /// Declared count \`${c.id}\` — the maintained O(1) tally per \`${c.by}\`.\n  Future<int> ${m}(String ${dartKeyParam(c.by)}) => bridge.count(${dartStr(c.id)}, ${dartKeyParam(c.by)});`
+        ? `  /// Declared count \`${c.id}\` — the maintained O(1) tally per \`${c.by}\`.\n  Future<int> ${m}(${groupType} ${dartKeyParam(c.by)}) => bridge.count(${dartStr(c.id)}, ${groupValue});`
         : `  /// Declared count \`${c.id}\` — the maintained O(1) grand total.\n  Future<int> ${m}() => bridge.count(${dartStr(c.id)});`,
       ``,
     );
     pastMethods.push(
       c.by != null
-        ? `  /// Declared count \`${c.id}\` at [moment].\n  Future<int> ${m}(String ${dartKeyParam(c.by)}) => _client.bridge.countAt(moment, ${dartStr(c.id)}, ${dartKeyParam(c.by)});`
+        ? `  /// Declared count \`${c.id}\` at [moment].\n  Future<int> ${m}(${groupType} ${dartKeyParam(c.by)}) => _client.bridge.countAt(moment, ${dartStr(c.id)}, ${groupValue});`
         : `  /// Declared count \`${c.id}\` at [moment].\n  Future<int> ${m}() => _client.bridge.countAt(moment, ${dartStr(c.id)});`,
       ``,
     );
   }
   for (const s of (mod.sums ?? []).map((raw) => finishSum(raw))) {
     const m = safeMethod(lcFirst(camel(s.id)));
+    const aggregate = aggById.get(s.of);
+    const groupType = s.by == null ? "" : dartKeyType(aggregate, s.by);
+    const groupValue = s.by == null ? "" : dartKeyExpr(aggregate, s.by);
     methods.push(
       s.by != null
-        ? `  /// Declared sum \`${s.id}\` — the maintained O(1) total per \`${s.by}\`.\n  Future<int> ${m}(String ${dartKeyParam(s.by)}) => bridge.sum(${dartStr(s.id)}, ${dartKeyParam(s.by)});`
+        ? `  /// Declared sum \`${s.id}\` — the maintained O(1) total per \`${s.by}\`.\n  Future<int> ${m}(${groupType} ${dartKeyParam(s.by)}) => bridge.sum(${dartStr(s.id)}, ${groupValue});`
         : `  /// Declared sum \`${s.id}\` — the maintained O(1) grand total.\n  Future<int> ${m}() => bridge.sum(${dartStr(s.id)});`,
       ``,
     );
     pastMethods.push(
       s.by != null
-        ? `  /// Declared sum \`${s.id}\` at [moment].\n  Future<int> ${m}(String ${dartKeyParam(s.by)}) => _client.bridge.sumAt(moment, ${dartStr(s.id)}, ${dartKeyParam(s.by)});`
+        ? `  /// Declared sum \`${s.id}\` at [moment].\n  Future<int> ${m}(${groupType} ${dartKeyParam(s.by)}) => _client.bridge.sumAt(moment, ${dartStr(s.id)}, ${groupValue});`
         : `  /// Declared sum \`${s.id}\` at [moment].\n  Future<int> ${m}() => _client.bridge.sumAt(moment, ${dartStr(s.id)});`,
       ``,
     );
@@ -946,17 +1013,18 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const Cap = cap(camel(name));
     const aScopes = readScopesFor(agg.id);
     const aOwned = aScopes.some((scope) => scope.owned === true);
+    const aPrivate = needsReadPrincipal(agg.id);
     const aScopesExpr = scopesExpr(aScopes);
     const runtimeType = isNamespacedAggregate(agg) ? qualifyReadProjectionType(domain, agg.id) : agg.id;
     const byIdKeys = aScopes.length === 0
-      ? ""
+      ? (aPrivate ? ", null, actor" : "")
       : aOwned
-        ? `, await _readKeys(${aScopesExpr}, [{${dartStr("type")}: ${dartStr(runtimeType)}, ${dartStr("id")}: id}])`
+        ? `, await _readKeys(${aScopesExpr}, [{${dartStr("type")}: ${dartStr(runtimeType)}, ${dartStr("id")}: id}])${aPrivate ? ", actor" : ""}`
         : keysArg(agg.id);
     const pastByIdKeys = aScopes.length === 0
-      ? ""
+      ? (aPrivate ? ", null, _client.actor" : "")
       : aOwned
-        ? `, await _client._readKeys(${aScopesExpr}, [{${dartStr("type")}: ${dartStr(runtimeType)}, ${dartStr("id")}: id}])`
+        ? `, await _client._readKeys(${aScopesExpr}, [{${dartStr("type")}: ${dartStr(runtimeType)}, ${dartStr("id")}: id}])${aPrivate ? ", _client.actor" : ""}`
         : pastKeysArg(agg.id);
     methods.push(
       `  /// Read one ${agg.id} by aggregate id.${readScopesFor(agg.id).length ? " Encrypted field(s) decrypt when the bound [keyStore] holds the scope key." : ""}`,
@@ -966,14 +1034,20 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       `  /// Watch one ${agg.id} by aggregate id (local reactive read).`,
       `  Stream<List<${model}>> watch${Cap}ById(String id) =>`,
       aOwned
-        ? `      bridge.watchById(id).asyncMap((_) async => bridge.queryById(id, await _readKeys(${aScopesExpr}, [{${dartStr("type")}: ${dartStr(runtimeType)}, ${dartStr("id")}: id}]))).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`
-        : `      bridge.watchById(id).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`,
+        ? `      bridge.watchById(id, null${aPrivate ? ", actor" : ""}).asyncMap((_) async => bridge.queryById(id, await _readKeys(${aScopesExpr}, [{${dartStr("type")}: ${dartStr(runtimeType)}, ${dartStr("id")}: id}])${aPrivate ? ", actor" : ""})).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`
+        : `      bridge.watchById(id${aPrivate ? ", null, actor" : ""}).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`,
       ``,
       `  /// Every ${agg.id} (the type-index probe — O(result), not a scan).`,
       `  Future<List<${model}>> ${safeMethod(`list${Cap}s`)}() async =>`,
       aOwned
-        ? `      (await _readWithOwnedKeys(${aScopesExpr}, (keys) => bridge.query('aggregatesByType', {'__type': ${dartStr(agg.id)}}, keys))).map((r) => ${rowToModel(model, "r")}).toList();`
-        : `      (await bridge.query('aggregatesByType', {'__type': ${dartStr(agg.id)}}${keysArg(agg.id)})).map((r) => ${rowToModel(model, "r")}).toList();`,
+        ? `      (await _readWithOwnedKeys(${aScopesExpr}, (keys) => bridge.query('aggregatesByType', {'__type': ${dartStr(runtimeType)}}, keys${aPrivate ? ", actor" : ""}))).map((r) => ${rowToModel(model, "r")}).toList();`
+        : `      (await bridge.query('aggregatesByType', {'__type': ${dartStr(runtimeType)}}${keysArg(agg.id)})).map((r) => ${rowToModel(model, "r")}).toList();`,
+      ``,
+      `  /// Watch every ${agg.id} (the same indexed local read, re-emitted after each change).`,
+      `  Stream<List<${model}>> ${safeMethod(`watchAll${Cap}s`)}() =>`,
+      aOwned
+        ? `      bridge.watch('aggregatesByType', {'__type': ${dartStr(runtimeType)}}, null${aPrivate ? ", actor" : ""}).asyncMap((_) => _readWithOwnedKeys(${aScopesExpr}, (keys) => bridge.query('aggregatesByType', {'__type': ${dartStr(runtimeType)}}, keys${aPrivate ? ", actor" : ""}))).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`
+        : `      bridge.watch('aggregatesByType', {'__type': ${dartStr(runtimeType)}}${aPrivate ? ", null, actor" : ""}).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`,
       ``,
     );
     pastMethods.push(
@@ -984,8 +1058,8 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       `  /// Every ${agg.id} in the verified world at [moment].`,
       `  Future<List<${model}>> ${safeMethod(`list${Cap}s`)}() async =>`,
       aOwned
-        ? `      (await _client._readWithOwnedKeys(${aScopesExpr}, (keys) => _client.bridge.queryAt(moment, 'aggregatesByType', {'__type': ${dartStr(agg.id)}}, keys))).map((r) => ${rowToModel(model, "r", "_client._ws")}).toList();`
-        : `      (await _client.bridge.queryAt(moment, 'aggregatesByType', {'__type': ${dartStr(agg.id)}}${pastKeysArg(agg.id)})).map((r) => ${rowToModel(model, "r", "_client._ws")}).toList();`,
+        ? `      (await _client._readWithOwnedKeys(${aScopesExpr}, (keys) => _client.bridge.queryAt(moment, 'aggregatesByType', {'__type': ${dartStr(runtimeType)}}, keys${aPrivate ? ", _client.actor" : ""}))).map((r) => ${rowToModel(model, "r", "_client._ws")}).toList();`
+        : `      (await _client.bridge.queryAt(moment, 'aggregatesByType', {'__type': ${dartStr(runtimeType)}}${pastKeysArg(agg.id)})).map((r) => ${rowToModel(model, "r", "_client._ws")}).toList();`,
       ``,
     );
   }
@@ -1116,7 +1190,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `    return moments.where((moment) =>`,
     `        moment.domain == ${dartStr(domain)} && moment.action != null && actions.contains(moment.action)).map((moment) =>`,
     `          moment.action == ${dartStr(BUSINESS_CORRECTION_DIRECTIVE)} ? NomosMoment(`,
-    `            id: moment.id, occurredAt: moment.occurredAt, actorSubject: moment.actorSubject, domain: moment.domain, action: 'correction') : moment).toList();`,
+    `            id: moment.id, occurredAt: moment.occurredAt, performedBy: moment.performedBy, domain: moment.domain, action: 'correction') : moment).toList();`,
     `  }`,
     `  ${atClass} at(NomosMoment moment) => ${atClass}(_client, moment);`,
     `}`,
@@ -1203,9 +1277,9 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
           ? [
               `    final id = ${member};`,
               `    if (id == null) return null;`,
-              `    final rows = await client.${byIdMethod}(id.value);`,
+              `    final rows = await client.${byIdMethod}(NmsInternalNomosRefs.id(id));`,
             ]
-          : [`    final rows = await client.${byIdMethod}(${member}.value);`]),
+          : [`    final rows = await client.${byIdMethod}(NmsInternalNomosRefs.id(${member}));`]),
         `    return rows.isEmpty ? null : rows.first;`,
         `  }`,
         ``,
@@ -1238,9 +1312,9 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
           ? [
               `    final id = ${member};`,
               `    if (id == null) return null;`,
-              `    final rows = await client.${byIdMethod}(id.value);`,
+              `    final rows = await client.${byIdMethod}(NmsInternalNomosRefs.id(id));`,
             ]
-          : [`    final rows = await client.${byIdMethod}(${member}.value);`]),
+          : [`    final rows = await client.${byIdMethod}(NmsInternalNomosRefs.id(${member}));`]),
         `    return rows.isEmpty ? null : rows.first;`,
         `  }`,
         ``,
@@ -1249,7 +1323,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     for (const [fieldName, f] of foreignRefs) {
       const fr = f.foreignRef!;
       const targetType = fr.targetAggregateId;
-      // The resolver returns the target's CONCRETE class (what `ForeignRef<T>.resolve` decodes to). We can
+      // The resolver returns the target's CONCRETE class. We can
       // only reference it when it is reachable from this file: SAME-domain (already in the imported types),
       // or a CROSS-DOMAIN concrete target in the package (import its sibling `<name>.dart` `show`-limited).
       // A contract target (its DTO lives in the shared contracts file) or an unmapped target is left as the
@@ -1272,15 +1346,13 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       const method = safeMethod(`remote${cap(camel(member))}`);
       lines.push(
         `  /// Resolve \`${fieldName}\` (${agg.id}.${fieldName} -> ${targetType} @ another workspace, a`,
-        `  /// \`t.foreignRef\` locator) over the session-bound multi-workspace plane —`,
-        `  /// \`${member}.resolve(engine.foreignReader())\`, which opens the foreign workspace ON DEMAND`,
-        `  /// (no clone). This is the informational follow+read lane, NOT the law-grade attested-read one`,
-        `  /// (use \`${member}!.attest(engine.foreignReader())\` when your law depends on the foreign fact).`,
+        `  /// \`t.foreignRef\` locator) over the session-bound multi-workspace plane. The generated`,
+        `  /// implementation opens the foreign workspace on demand; tenant code sees only this business method.`,
         `  /// Null locator (absent / empty id or workspace) ⇒ null.`,
         `  Future<${targetConcrete}?> ${method}(NomosEngine engine, {String? cloud}) {`,
         `    final ref = ${member};`,
         `    if (ref == null) return Future<${targetConcrete}?>.value(null);`,
-        `    return ref.resolve(engine.foreignReader(cloud: cloud));`,
+        `    return NmsInternalForeignRefs.resolve(ref, engine.foreignReader(cloud: cloud));`,
         `  }`,
         ``,
       );
@@ -1313,14 +1385,14 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       `  /// history, decisions and evidence. The old events/transcript fields remain on [NomosDescription].`,
       `  Future<NomosDescription> describe({`,
       `    NomosDescribeSection section = NomosDescribeSection.root,`,
-      `    String? since, String? actor, String? category, int? limit,`,
+      `    String? since, String? performedBy, String? category, int? limit,`,
       `  }) async {`,
       `    final raw = await bridge.activityLog(limit: limit);`,
       `    var events = raw`,
       `        .map((r) => renderActivity(r.cast<String, dynamic>()))`,
       `        .whereType<ActivityEvent>()`,
       `        .toList();`,
-      `    if (actor != null) events = events.where((e) => e.actorSubject == actor).toList();`,
+      `    if (performedBy != null) events = events.where((e) => e.performedBy == performedBy).toList();`,
       `    if (category != null) events = events.where((e) => e.category == category).toList();`,
       `    if (since != null) events = events.where((e) => e.occurredAt.compareTo(since) >= 0).toList();`,
       `    final narrative = activityNarrative(events);`,
@@ -1359,8 +1431,8 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       `        summary: item['summary'] as String,`,
       `        details: item['details'] == null ? null : (item['details'] as Map).cast<String, dynamic>());`,
       `    }`,
-      `    List<NomosRef> eventRefs(ActivityEvent event) => event.refs.values`,
-      `        .map((ref) => NomosRef(workspace: ref.workspace, type: ref.type, id: ref.id)).toList();`,
+      `    List<NomosRef<Object?>> eventRefs(ActivityEvent event) => event.refs.values`,
+      `        .map((ref) => NmsInternalNomosRefs.create<Object?>(workspace: ref.workspace, type: ref.type, id: ref.id)).toList();`,
       `    String refusalReason(Object? raw) {`,
       `      final text = (raw ?? '').toString().toLowerCase();`,
       `      bool has(List<String> parts) => parts.any(text.contains);`,
@@ -1398,7 +1470,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       `        final label = aggregate['label'] as String;`,
       `        try {`,
       `          final rows = await bridge.query('aggregatesByType', {'__type': queryType});`,
-      `          final refs = rows.map((row) => NomosRef(`,
+      `          final refs = rows.map((row) => NmsInternalNomosRefs.create<Object?>(`,
       `            workspace: _ws, type: (row['type'] ?? type).toString(), id: (row['id'] ?? '').toString())).toList();`,
       `          final exact = aggregate['audience'] == 'public' || rows.isNotEmpty;`,
       `          items.add(NomosDescribeItem(`,
@@ -1417,14 +1489,14 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       `      summary = 'What changed, who changed it and when, read from verified committed testimony.';`,
       `      items = events.map((event) => NomosDescribeItem(`,
       `        kind: 'change', id: event.eventId, label: event.title, summary: event.message,`,
-      `        details: {'actor': event.actorSubject, 'occurredAt': event.occurredAt, 'domain': event.domain, 'kind': event.kind},`,
+      `        details: {'performedBy': event.performedBy, 'occurredAt': event.occurredAt, 'domain': event.domain, 'kind': event.kind},`,
       `        refs: eventRefs(event))).toList();`,
       `    } else if (section == NomosDescribeSection.decisions) {`,
       `      title = 'Decisions and work needing attention';`,
       `      summary = 'Recorded business reasons, pending merges and retained rejected work, plus declared conflict policy from the model.';`,
       `      items = events.where((event) => event.kind.endsWith('.correction')).map((event) => NomosDescribeItem(`,
       `        kind: 'decision', id: event.eventId, label: event.title, summary: event.message,`,
-      `        details: {'actor': event.actorSubject, 'occurredAt': event.occurredAt, 'domain': event.domain},`,
+      `        details: {'performedBy': event.performedBy, 'occurredAt': event.occurredAt, 'domain': event.domain},`,
       `        refs: eventRefs(event))).toList();`,
       `      final aggregateTypes = ((model['aggregateTypes'] as List?) ?? const [])`,
       `          .map((raw) => (raw as Map).cast<String, dynamic>()).toList();`,
@@ -1454,7 +1526,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       `          id: 'decision:\${aggregate['domain']}.\${aggregate['type']}:\${conflict['aggregateId']}:$field',`,
       `          label: 'Review $subject', summary: conflictSummary,`,
       `          details: {'domain': aggregate['domain'], 'type': aggregate['type'], 'field': field, 'status': status, 'versions': versions, 'next': status == 'ready' ? 'merge' : 'update-model'},`,
-      `          refs: [NomosRef(workspace: _ws, type: aggregate['type'].toString(), id: conflict['aggregateId'].toString())]));`,
+      `          refs: [NmsInternalNomosRefs.create<Object?>(workspace: _ws, type: aggregate['type'].toString(), id: conflict['aggregateId'].toString())]));`,
       `      }`,
       `      final modelPageItems = ((((model['pages'] as Map)['model'] as Map)['items'] as List?) ?? const [])`,
       `          .map((raw) => (raw as Map).cast<String, dynamic>()).where((item) => item['kind'] == 'verb').toList();`,
@@ -1481,7 +1553,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       `        NomosDescribeItem(kind: 'evidence', id: 'law', label: 'Generated law', summary: domainHash, details: {'domainHash': domainHash}),`,
       `        NomosDescribeItem(kind: 'evidence', id: 'reader', label: 'Verified reader', summary: this.actor ?? bridge.principal ?? 'anonymous', details: {'actor': this.actor ?? bridge.principal}),`,
       `        if (latest != null) NomosDescribeItem(kind: 'evidence', id: latest.eventId, label: 'Latest verified moment', summary: latest.eventId,`,
-      `          details: {'occurredAt': latest.occurredAt, 'actor': latest.actorSubject, 'domain': latest.domain, 'kind': latest.kind}),`,
+      `          details: {'occurredAt': latest.occurredAt, 'performedBy': latest.performedBy, 'domain': latest.domain, 'kind': latest.kind}),`,
       `      ];`,
       `    }`,
       `    return NomosDescription(`,
@@ -1505,23 +1577,14 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   }
 
   return [
-    `// AUTO-GENERATED by nomos-compile — typed ASYNC Dart client for domain "${domain}".`,
-    `// Drives the REAL githolon over a NomosBridge (the WebView runner). Regenerated every compile; do`,
-    `// not edit. SESSION-BOUND (architecture/session_bound_clients.md): construct with a NomosSession —`,
-    `// one session, one workspace, one domain interface, one actor context:`,
-    `//`,
+    `// AUTO-GENERATED by nomos-compile — private runtime implementation for domain "${domain}".`,
+    `// Regenerated every compile; do not edit or teach this file as an application entry point.`,
     // GENERATED-CODE lints: the bridge read/watch surface returns dynamic (JSON rows), so typed accessors
     // do dynamic member access + casts by construction. Silence the lints that only make sense for
     // hand-written code, so this file never adds noise to a tenant's analyzer output (co2 feedback).
     // (deprecated_member_use*: the compatibility shims intentionally delegate to the deprecated
     // engine-level lanes for one minor version.)
-    `// ignore_for_file: avoid_dynamic_calls, unnecessary_this, prefer_const_constructors, unused_import, type_annotate_public_apis, always_specify_types, deprecated_member_use, deprecated_member_use_from_same_package`,
-    `//`,
-    `//   final engine = NomosBridge(transport);   // the device's local plane (NomosEngine)`,
-    `//   await engine.ready;`,
-    `//   final session = await engine.open(cloud: cloud, workspace: ws, clientId: deviceId);`,
-    `//   final app = await ${className}.bind(session);   // preflights law compatibility (ask 5)`,
-    `//   await app.${dirs[0] ? safeMethod(dirs[0].id) : "someDirective"}(/* typed payload */);`,
+    `// ignore_for_file: avoid_dynamic_calls, unnecessary_this, prefer_const_constructors, unused_import, type_annotate_public_apis, always_specify_types, deprecated_member_use, deprecated_member_use_from_same_package, invalid_use_of_internal_member`,
     ``,
     // `dart:convert` is needed ONLY for the interface block's `jsonDecode` — the offer lane no longer encodes
     // any envelope (it routes through `bridge.offerDirective` → THE ONE ENCODER). Omit it when no interface.
@@ -1549,11 +1612,10 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     ...[...crossDomainImports.entries()]
       .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
       .map(([uri, names]) => `import '${uri}' show ${[...names].sort().join(", ")};`),
-    `// Re-export the sibling types (read models + payloads + the bridge runtime) so ONE import of this`,
-    `// client file gives an app the whole typed surface.`,
+    `// Re-export business types only. The runtime import above is an implementation dependency, never`,
+    `// a tenant API: exporting it would create a second raw bridge/session/sync application lane.`,
     ...(opts.typesImportUri !== undefined ? [`export '${opts.typesImportUri}';`] : [`export '${mod.name}.dart';`]),
     ...(opts.typesImportUri === undefined && opts.frameworkImportUri !== undefined ? [`export '${opts.frameworkImportUri}';`] : []),
-    `export '${supportImport}' show NomosBridge, NomosEngine, NomosSession, NomosSessionCompat, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion, NomosCompat, NomosCompatMember, NomosOfferOutcome, NomosCreated, NomosRef, NomosMoment, NomosClientInterface, DomainClientSessionMismatch, DomainNotInstalledForSession, SessionMismatchCause${manualEncryptionPresent ? ", NomosScopeKey, NomosKeyStore, EncryptionKeyUnavailable, WrappedKeyStore, NomosEncryption, NomosEpochResult, EncryptionMemberKeyMissing, EncryptionRosterMismatch" : ""};`,
     ``,
     `/// sha256 of the deployed \`.package.usda\` — the installed law this client offers under.`,
     `const String ${hashConst} = ${dartStr(opts.domainHash)};`,
@@ -1650,10 +1712,10 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `  /// \`await ${className}.open(bridge, ref: outcome.bornRefs.single)\` (or \`workspace: 'estate-42'\`).`,
     `  /// It ACQUIRES the workspace's session on [bridge] first (an already-open one is reused; a device-`,
     `  /// resident/parked/just-born one opens local-only in place) and THEN binds — so a not-open workspace`,
-    `  /// fails HERE, at open, never later on the client's first query. For a genuinely-absent cloud workspace,`,
-    `  /// \`acquireSession(ws, ifAbsentCredentials: ...)\` it yourself then [bind].`,
-    `  static Future<${className}> open(NomosBridge bridge, {NomosRef? ref, String? workspace, String? actor${manualEncryptionPresent ? ", NomosKeyStore? keyStore" : ""}}) async {`,
-    `    final ws = ref?.workspace ?? workspace;`,
+    `  /// fails HERE, at open, never later on the client's first query. The generated stateful application`,
+    `  /// privately retains refreshable cloud access for a genuinely-absent authorized workspace.`,
+    `  static Future<${className}> open<TAggregate>(NomosBridge bridge, {NomosRef<TAggregate>? ref, String? workspace, String? actor${manualEncryptionPresent ? ", NomosKeyStore? keyStore" : ""}}) async {`,
+    `    final ws = ref == null ? workspace : NmsInternalNomosRefs.workspace(ref);`,
     `    if (ws == null || ws.isEmpty) {`,
     `      throw ArgumentError('${className}.open: pass a workspace: or ref: — the workspace to open and bind');`,
     `    }`,
@@ -1697,11 +1759,11 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
           `    _ownedIdentityReady = true;`,
           `  }`,
           ``,
-          `  Future<NomosOfferOutcome> _ownedRecordAction(String action, NomosRef record, String peer) async {`,
+          `  Future<NomosOfferOutcome> _ownedRecordAction<TAggregate>(String action, NomosRef<TAggregate> record, String peer) async {`,
           `    await _preflightOnce();`,
           `    await _ensureOwnedIdentity();`,
-          `    if (record.workspace != _ws) throw ArgumentError('$action() cannot use a record from another workspace');`,
-          `    final directiveId = _ownedRecordActions[record.type]?[action];`,
+          `    if (NmsInternalNomosRefs.workspace(record) != _ws) throw ArgumentError('$action() cannot use a record from another workspace');`,
+          `    final directiveId = _ownedRecordActions[NmsInternalNomosRefs.type(record)]?[action];`,
           `    if (directiveId == null) throw ArgumentError('$action() needs a generated owned record reference');`,
           `    if (peer.trim().isEmpty) throw ArgumentError('$action() needs the person to act with');`,
           `    final payload = await bridge.nomosPrepareOwnedRecordAction(action: action, scope: ${dartStr(ownedScope)}, record: record, peer: peer);`,
@@ -1791,7 +1853,6 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       ? [
           `// ---- role policy (UI hints — the KERNEL GATE is the authority) ----`,
           roleHelpers,
-          ``,
         ]
       : []),
   ].join("\n");