@githolon/dsl 0.100.6 → 0.101.0

package/src/codegen_dart_client.ts

@@ -28,7 +28,13 @@
  */
 import type { z } from "zod";
 
-import type { AggregateHandle } from "./aggregate.js";
+import {
+  BUSINESS_BIRTH_SEED_PAYLOAD_FIELD,
+  OWNED_CUSTODY_PAYLOAD_FIELD,
+  OWNED_KEY_PAYLOAD_FIELD,
+  OWNED_PREMINTED_RECORDS_PAYLOAD_FIELD,
+  type AggregateHandle,
+} from "./aggregate.js";
 import type { Field } from "./fields.js";
 import type { Directive } from "./directive.js";
 import type { QueryDecl } from "./query.js";
@@ -45,6 +51,13 @@ import {
 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 { 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";
 
 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);
@@ -98,8 +111,8 @@ function dartKeyParam(key: string): string {
 /** Parse ONE bridge row (`{type,id,data}`) into a typed read model, composing the canonical `.ref` from the
  * 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): string {
-  return `${model}.fromProjected((${rowVar}['data'] as Map).cast<String, dynamic>(), (${rowVar}['id'] ?? '').toString(), _ws, (${rowVar}['type'] ?? '').toString())`;
+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())`;
 }
 
 export interface DartBridgeClientOptions {
@@ -131,9 +144,9 @@ export interface DartBridgeClientOptions {
    */
   readonly typesImportUri?: string;
   /**
-   * ACTIVITY FEED (architecture/activity_descriptors.md): true iff the PACKAGE declares ≥1 directive
-   * `.activity(...)`. When set the client emits `watchActivity()` / `activityLog()` (folding the bridge's
-   * raw committed-intent rows through the shared pure `renderActivity`). Off ⇒ byte-identical to before.
+   * ACTIVITY + SELF-DESCRIPTION (architecture/activity_descriptors.md). The package compiler always sets
+   * this, including for an action-free package (empty history is still explainable). Direct codegen callers
+   * may leave it off when they explicitly need the legacy narrow surface.
    */
   readonly emitActivity?: boolean;
   /**
@@ -143,6 +156,8 @@ export interface DartBridgeClientOptions {
    * omitted. Only meaningful when {@link emitActivity} is set.
    */
   readonly activityImportUri?: string;
+  /** Compiler-known half of the one-root-plus-six `describe()` surface. */
+  readonly describeModel?: NomosDescribeModel;
   /**
    * CROSS-DOMAIN REF TRAVERSAL (dart_codegen_parity.md §2a follow-on): every aggregate id in the
    * PACKAGE → the domain module that owns it (`domain` for the client class name, `name` for the
@@ -186,6 +201,14 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   };
   registerDartNames(mod.aggregates); // `.dartName` overrides for read-model class names in the client.
   const domain = mod.domain ?? mod.name;
+  assertModelClientMemberAvailable(mod);
+  const describeModel = opts.describeModel ?? buildNomosDescribeModel([mod], domain);
+  const clientInterface = opts.interface === undefined
+    ? undefined
+    : publicClientInterface(
+        [mod],
+        { [domain]: opts.interface as unknown as DomainInterface },
+      )[domain];
   const className = dartClientClassName(domain);
   const hashConst = dartHashConstName(mod.name);
   const requiresKernelFeats = requiredKernelFeatures([mod]);
@@ -195,6 +218,15 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       : "nomos_client.dart";
   const aggById = new Map<string, AggregateHandle>();
   for (const a of mod.aggregates) aggById.set(a.id, a);
+  const conflictAggregateType = (aggregateId: string): string => {
+    const aggregate = aggById.get(aggregateId);
+    if (aggregate === undefined) {
+      throw new Error(`generated conflict policy refers to unknown aggregate '${aggregateId}' in domain '${domain}'`);
+    }
+    return isNamespacedAggregate(aggregate)
+      ? qualifyReadProjectionType(domain, aggregateId)
+      : aggregateId;
+  };
 
   // ROLE SUGAR — the `canEdit<Agg>`/`canView<Agg>` UI-hint helpers live HERE (the client package, which may
   // import runtime), NOT in the pure types file: they `jsonDecode` the folded RelationTuple leaf, and the
@@ -205,30 +237,89 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   // below emits (the generated Dart client is byte-identical to a pre-sealing compile). Same map + sids as
   // the TS client (one source of truth: `domainEncryptionMap`); requires the baked interface for the sids.
   const encMap: EncDomainMap | null =
-    opts.interface !== undefined
-      ? domainEncryptionMap(mod, opts.interface as { aggregates?: Record<string, InterfaceAggShape> })
+    clientInterface !== undefined
+      ? domainEncryptionMap(mod, clientInterface as { aggregates?: Record<string, InterfaceAggShape> })
       : null;
   const encPresent = encMap !== null;
+  const manualEncryptionPresent = encMap !== null &&
+    [...Object.values(encMap.directives), ...Object.values(encMap.reads)].some((fields) =>
+      Object.values(fields).some((field) => field.owned !== true),
+    );
   /** The distinct scopes a read of `typeId` must inject keys for (empty ⇒ nothing encrypted on it). */
-  const readScopesFor = (typeId: string): string[] => {
+  const readScopesFor = (typeId: string): { scope: string; owned?: true }[] => {
     const r = encMap?.reads?.[typeId];
-    return r === undefined ? [] : [...new Set(Object.values(r).map((x) => x.scope))].sort();
+    if (r === undefined) return [];
+    const byKey = new Map<string, { scope: string; owned?: true }>();
+    for (const x of Object.values(r)) byKey.set(`${x.scope}:${x.owned === true}`, x);
+    return [...byKey.values()].sort((a, b) => a.scope.localeCompare(b.scope));
   };
+  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 keysArg = (typeId: string): string => {
     const scopes = readScopesFor(typeId);
-    return scopes.length ? `, await _readKeys([${scopes.map((s) => dartStr(s)).join(", ")}])` : "";
+    return scopes.length
+      ? `, await _readKeys(${scopesExpr(scopes)})`
+      : "";
+  };
+  const pastKeysArg = (typeId: string): string => {
+    const scopes = readScopesFor(typeId);
+    return scopes.length
+      ? `, await _client._readKeys(${scopesExpr(scopes)})`
+      : "";
   };
   // 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.
   const domScopes: string[] = (() => {
     if (encMap === null) return [];
     const s = new Set<string>();
-    for (const r of Object.values(encMap.reads)) for (const f of Object.values(r)) s.add(f.scope);
-    for (const dir of Object.values(encMap.directives)) for (const f of Object.values(dir)) s.add(f.scope);
+    for (const r of Object.values(encMap.reads)) for (const f of Object.values(r)) if (f.owned !== true) s.add(f.scope);
+    for (const dir of Object.values(encMap.directives)) for (const f of Object.values(dir)) if (f.owned !== true) s.add(f.scope);
     return [...s].sort();
   })();
+  const ownedScopes: string[] = (() => {
+    if (encMap === null) return [];
+    const scopes = new Set<string>();
+    for (const r of Object.values(encMap.reads)) for (const f of Object.values(r)) if (f.owned === true) scopes.add(f.scope);
+    for (const dir of Object.values(encMap.directives)) for (const f of Object.values(dir)) if (f.owned === true) scopes.add(f.scope);
+    return [...scopes].sort();
+  })();
+  if (ownedScopes.length > 1) {
+    throw new Error(`dart codegen: owned business state in domain '${domain}' unexpectedly uses more than one framework scope`);
+  }
+  const ownedScope = ownedScopes[0];
 
   const methods: string[] = [];
+  const pastMethods: string[] = [];
+  const pastDeclarations: string[] = [];
+  const conflictDeclarations: string[] = [];
+  const ownedActions = Object.fromEntries(
+    (mod.aggregates as AggregateHandle[])
+      .filter((aggregate) => aggregate.audience?.kind === "owned")
+      .map((aggregate) => {
+        const type = isNamespacedAggregate(aggregate) ? qualifyReadProjectionType(domain, aggregate.id) : aggregate.id;
+        return [type, {
+          share: ownedRecordActionDirectiveId("share", aggregate.id),
+          unshare: ownedRecordActionDirectiveId("unshare", aggregate.id),
+          transfer: ownedRecordActionDirectiveId("transfer", aggregate.id),
+        }];
+      }),
+  );
+  const ownedActionsDart = `{${Object.entries(ownedActions).map(([type, actions]) =>
+    `${dartStr(type)}: {${Object.entries(actions).map(([action, directive]) => `${dartStr(action)}: ${dartStr(directive)}`).join(", ")}}`,
+  ).join(", ")}}`;
+  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);`,
+      ``,
+      `  /// 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);`,
+      ``,
+      `  /// Hand ownership, readable history and future authority for one record to another person.`,
+      `  Future<NomosOfferOutcome> transfer(NomosRef record, String peer) => _ownedRecordAction('transfer', record, peer);`,
+      ``,
+    );
+  }
 
   // THE STATIC INTERFACE DESCRIPTOR (`XClient.interface`, session_bound_clients.md asks 5/9) —
   // what this client EXPECTS of a workspace: the domain key, the law hash it compiled under, and
@@ -246,6 +337,49 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   );
   const birthDirs = allDirs.filter((d) => (d as { birthsChild?: boolean }).birthsChild === true);
   const dirs = allDirs.filter((d) => (d as { birthsChild?: boolean }).birthsChild !== true);
+  const correctionActions = dirs.filter(
+    (d) => (d as { businessBirth?: unknown }).businessBirth === undefined,
+  );
+  if (correctionActions.length > 0) {
+    const correctionsClass = `${className}Corrections`;
+    const outcomeClass = `${className}CorrectionOutcome`;
+    methods.push(
+      `  /// Correct this principal's latest business change. The framework owns target selection and replay.`,
+      `  ${correctionsClass} get corrections => ${correctionsClass}(this);`,
+      ``,
+    );
+    pastDeclarations.push(
+      `/// Result of a reasoned business correction. Framework intent and testimony ids remain private.`,
+      `class ${outcomeClass} {`,
+      `  final bool ok;`,
+      `  final String kind;`,
+      `  final String? reason;`,
+      `  final String? message;`,
+      `  final String? head;`,
+      `  const ${outcomeClass}({required this.ok, required this.kind, this.reason, this.message, this.head});`,
+      `  factory ${outcomeClass}.fromJson(Map<String, Object?> json) => ${outcomeClass}(`,
+      `      ok: json['ok'] == true, kind: (json['kind'] ?? '') as String,`,
+      `      reason: json['reason'] as String?, message: json['message'] as String?, head: json['head'] as String?);`,
+      `}`,
+      ``,
+      `/// One business correction lane. Application code provides only its reason.`,
+      `class ${correctionsClass} {`,
+      `  final ${className} _client;`,
+      `  const ${correctionsClass}(this._client);`,
+      `  Future<${outcomeClass}> undo(String reason) => _apply('undo', reason);`,
+      `  Future<${outcomeClass}> redo(String reason) => _apply('redo', reason);`,
+      `  Future<${outcomeClass}> _apply(String kind, String reason) async {`,
+      `    if (reason.trim().isEmpty) throw ArgumentError('corrections.\$kind() needs a reason');`,
+      `    final result = await _client.bridge.correctMostRecent(`,
+      `      kind: kind, domain: ${dartStr(domain)},`,
+      `      actions: const [${correctionActions.map((d) => dartStr(d.id)).join(", ")}],`,
+      `      reason: reason, domainHash: _client.domainHash, actor: _client.actor);`,
+      `    return ${outcomeClass}.fromJson(result);`,
+      `  }`,
+      `}`,
+      ``,
+    );
+  }
   for (const d of dirs) {
     const payloadClass = `${cap(d.id)}Payload`;
     const stamps = autoStampFields((d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema);
@@ -278,12 +412,46 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       ? ` 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 stampsDoc = stamps.length > 0 ? `\n  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.` : "";
-    if (encMap?.directives?.[d.id] !== undefined) {
+    const directiveEncryption = encMap?.directives?.[d.id];
+    if (directiveEncryption !== undefined) {
+      const ownedSeal = Object.values(directiveEncryption).every((field) => field.owned === true);
+      const targetAggregate = ownedSeal ? aggById.get((d as { aggregateId?: string }).aggregateId ?? "") : undefined;
+      const recordTarget = targetAggregate === undefined ? undefined : deriveDirectiveRecordTarget(d, targetAggregate);
+      if (ownedSeal && recordTarget === undefined) {
+        throw new Error(
+          `dart codegen: cannot derive the record targeted by encrypted owned directive '${domain}/${d.id}'. ` +
+            `Address it from one string payload field, one deterministic instance, or create it with create(Aggregate).`,
+        );
+      }
+      const runtimeType = targetAggregate === undefined
+        ? undefined
+        : isNamespacedAggregate(targetAggregate)
+          ? qualifyReadProjectionType(domain, targetAggregate.id)
+          : targetAggregate.id;
+      const recordPrelude = recordTarget === undefined || runtimeType === undefined
+        ? []
+        : recordTarget.kind === "premint"
+          ? [
+              `    final ownedRecordType = ${dartStr(runtimeType)};`,
+              `    final ownedRecordId = await bridge.mintId(ownedRecordType);`,
+              `    const ownedRecordPreMinted = true;`,
+            ]
+          : recordTarget.kind === "payload"
+            ? [
+                `    final ownedRecordType = ${dartStr(runtimeType)};`,
+                `    final ownedRecordId = (data[${dartStr(recordTarget.field)}] ?? '').toString();`,
+                `    const ownedRecordPreMinted = false;`,
+              ]
+            : [
+                `    final ownedRecordType = ${dartStr(runtimeType)};`,
+                `    final ownedRecordId = ${dartStr(recordTarget.id)};`,
+                `    const ownedRecordPreMinted = false;`,
+              ];
       methods.push(
         `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the typed [NomosOfferOutcome].${createsDoc}`,
-        `  /// Encrypted field(s) are SEALED via the bound [keyStore] before dispatch (pass \`seal: false\` to skip).${stampsDoc}`,
+        `  /// ${ownedSeal ? "Owned content is encrypted automatically by Nomos." : "Encrypted field(s) are SEALED via the bound [keyStore] before dispatch (pass `seal: false` to skip)."}${stampsDoc}`,
         ...(gateDoc ? [gateDoc] : []),
-        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload, {bool seal = true${wantAttest ? ", " + attNamed : ""}}) async {`,
+        `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload${ownedSeal && !wantAttest ? "" : `, {${ownedSeal ? "" : "bool seal = true"}${wantAttest ? `${ownedSeal ? "" : ", "}${attNamed}` : ""}}`}) async {`,
         ...(gateGuard ? [gateGuard] : []),
         `    final data = payload.toPayloadJson();`,
         ...(stamps.length > 0
@@ -292,7 +460,8 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
               ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
             ]
           : []),
-        `    await _sealPayload(data, ${dartStr(d.id)}, seal);`,
+        ...recordPrelude,
+        `    await _sealPayload(data, ${dartStr(d.id)}, ${ownedSeal ? "true" : "seal"}${ownedSeal ? ", null, ownedRecordType, ownedRecordId, ownedRecordPreMinted" : ""});`,
         `    return _offer(${dartStr(d.id)}, data${attArg});`,
         `  }`,
         ``,
@@ -344,9 +513,13 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const method = safeMethod(d.id);
     const gate = (d as { requiresRelationGate?: { relation: string } }).requiresRelationGate;
     const businessBirth = (d as unknown as {
-      businessBirth?: { aggregateId: string; rootId: string };
+      businessBirth?: { aggregateId: string; rootId: string; namespace: string; keyField: string; publicPayloadSchema: z.ZodTypeAny };
     }).businessBirth;
     if (businessBirth !== undefined) {
+      const birthEncryption = encMap?.directives?.[d.id];
+      const ownedBirthDescriptor = birthEncryption === undefined
+        ? undefined
+        : Object.values(birthEncryption).find((field) => field.owned === true);
       methods.push(
         `  /// Give one ${businessBirth.aggregateId} its own durable life. Nomos owns identity, authorship,`,
         `  /// provenance, persistence and recovery; the app supplies only business facts.`,
@@ -356,12 +529,35 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         `      throw MissingOfferAuthority(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, requires: 'a signed-in Nomos session');`,
         `    }`,
         `    final data = payload.toPayloadJson();`,
+        ...(ownedBirthDescriptor === undefined
+          ? []
+          : [
+              `    final ownedBirthKey = await bridge.nomosOwnedBirthScopeKey(`,
+              `        ${dartStr(ownedBirthDescriptor.scope)}, ${dartStr(businessBirth.namespace)}, data[${dartStr(businessBirth.keyField)}]);`,
+            ]),
+        ...(birthEncryption === undefined
+          ? []
+          : [
+              `    final sealedGenesis = Map<String, dynamic>.from(data);`,
+              `    await _sealPayload(sealedGenesis, ${dartStr(d.id)}, true${ownedBirthDescriptor === undefined ? "" : ", ownedBirthKey"});`,
+              `    data[${dartStr(BUSINESS_BIRTH_SEED_PAYLOAD_FIELD)}] = jsonEncode(sealedGenesis);`,
+              ...(ownedBirthDescriptor === undefined
+                ? []
+                : [`    data[${dartStr(OWNED_KEY_PAYLOAD_FIELD)}] = ownedBirthKey.ownedKeySubject;`]),
+            ]),
         `    data['principal'] = principal;`,
         `    data['bornAt'] = DateTime.now().toUtc().toIso8601String();`,
         `    final outcome = await _offer(${dartStr(d.id)}, data);`,
         `    if (outcome.born.length != 1) {`,
         `      throw StateError('birth() committed without returning exactly one born workspace');`,
         `    }`,
+        ...(ownedBirthDescriptor === undefined
+          ? []
+          : [
+              `    if (ownedBirthKey.workspace == null || outcome.born.single != ownedBirthKey.workspace) {`,
+              `      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)});`,
         `  }`,
@@ -440,14 +636,29 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     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 m = safeMethod(lcFirst(camel(q.id)));
+    const qScopes = readScopesFor(q.returns);
+    const qOwned = qScopes.some((scope) => scope.owned === true);
+    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 =>`,
-      `      (await bridge.query(${dartStr(q.id)}, ${argMap}${keysArg(q.returns)})).map((r) => ${rowToModel(model, "r")}).toList();`,
+      qOwned
+        ? `      (await _readWithOwnedKeys(${qScopesExpr}, (keys) => bridge.query(${dartStr(q.id)}, ${argMap}, keys))).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}}) =>`,
-      `      bridge.watch(${dartStr(q.id)}, ${argMap}).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`,
+      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());`,
+      ``,
+    );
+    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.bridge.queryAt(moment, ${dartStr(q.id)}, ${argMap}${pastKeysArg(q.returns)})).map((r) => ${rowToModel(model, "r", "_client._ws")}).toList();`,
       ``,
     );
   }
@@ -478,6 +689,12 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         : `  /// 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}() => _client.bridge.countAt(moment, ${dartStr(c.id)});`,
+      ``,
+    );
   }
   for (const s of (mod.sums ?? []).map((raw) => finishSum(raw))) {
     const m = safeMethod(lcFirst(camel(s.id)));
@@ -487,42 +704,57 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         : `  /// 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}() => _client.bridge.sumAt(moment, ${dartStr(s.id)});`,
+      ``,
+    );
   }
 
-  // ── SURFACED CONFLICT DX (surfaced_merge_conflict.md): the workspace-wide pendingConflicts
-  // read/watch + one typed `resolve…` helper per designated `.resolves()` directive. Emitted iff
-  // this domain declares a Surfaced field (Surfaced-free packages emit nothing — the era rule).
+  // ── BUSINESS MERGE CONFLICT DX: keep the heterogeneous Nomos index behind an aggregate-specific,
+  // chained API. A pending conflict is a typed reference to its own `merge(...)` capability; callers
+  // inspect all versions and produce a merge result rather than choosing a winner.
   const resolverBindings = (mod as { surfacedResolvers?: import("./surfaced_lint.js").SurfacedResolverBinding[] }).surfacedResolvers ?? [];
   if (resolverBindings.length > 0) {
+    const conflictsClass = `${cap(camel(domain))}Conflicts`;
+    const summaryClass = `${cap(camel(domain))}ConflictSummary`;
+    const rowClass = `_${cap(camel(domain))}PendingConflictRow`;
+    const aggregateConflictsClass = (aggregateId: string) => {
+      const aggregateName = cap(camel(concreteClassName(aggregateId)));
+      return aggregateName === cap(camel(domain))
+        ? `${aggregateName}AggregateConflicts`
+        : `${aggregateName}Conflicts`;
+    };
+    const byAggregate = new Map<string, typeof resolverBindings>();
+    for (const binding of resolverBindings) {
+      byAggregate.set(binding.aggregateId, [...(byAggregate.get(binding.aggregateId) ?? []), binding]);
+    }
     methods.push(
-      `  /// PENDING SURFACED CONFLICTS across the workspace — the maintained "decisions needed" read`,
-      `  /// (reserved id \`nomosPendingConflicts\`; DERIVED, NOT DRAINED: a resolution write folding in`,
-      `  /// removes its row by derivation). Pair each row with its typed \`resolve…\` helper below.`,
-      `  Future<List<PendingConflictRow>> pendingConflicts() async =>`,
-      `      (await bridge.pendingConflicts()).map(PendingConflictRow.fromJson).toList();`,
+      `  /// Pending business merges: summary → aggregate → typed conflict → merge().`,
+      `  ${conflictsClass} get conflicts => ${conflictsClass}(this);`,
       ``,
-      `  /// Reactive pending-conflicts read — re-emits whenever the maintained index changes.`,
-      `  Stream<List<PendingConflictRow>> watchPendingConflicts() =>`,
-      `      bridge.watchPendingConflicts().map((rows) => rows`,
-      `          .map((r) => PendingConflictRow.fromJson((r as Map).cast<String, dynamic>()))`,
-      `          .toList());`,
+      `  /// Nomos-internal aggregate-filtered index used only by generated conflict references.`,
+      `  Future<List<${rowClass}>> _pendingConflictRows(String aggregateType) async =>`,
+      `      (await bridge.pendingConflictsFor(aggregateType)).map(${rowClass}.fromJson).toList();`,
       ``,
     );
     for (const b of resolverBindings) {
       if (b.valuePayloadField === undefined || b.idPayloadField === undefined) continue; // probe couldn't bind — dispatch the directive method directly.
       const agg = aggById.get(b.aggregateId);
       const fieldKind = (agg?.fields[b.field] as Field | undefined)?.kind;
-      const chosenType = fieldKind === "string" ? "String" : fieldKind === "int" ? "int" : "Object?";
-      const helper = safeMethod(`resolve${cap(camel(concreteClassName(b.aggregateId)))}${cap(camel(b.field))}`);
+      const mergedType = fieldKind === "string" || fieldKind === "ref" || fieldKind === "enum"
+        ? "String"
+        : fieldKind === "int"
+          ? "int"
+          : fieldKind === "bool"
+            ? "bool"
+            : "Object?";
+      const helper = `_merge${cap(camel(concreteClassName(b.aggregateId)))}${cap(camel(b.field))}`;
       const dir = allDirs.find((d) => d.id === b.directiveId);
       const gate = (dir as { requiresRelationGate?: { relation: string } } | undefined)?.requiresRelationGate;
       methods.push(
-        `  /// RESOLVE a pending conflict on \`${b.aggregateId}.${b.field}\` by dispatching the DESIGNATED`,
-        `  /// resolver \`${b.directiveId}\` with [chosen] (the conflict row names the instance; extra required`,
-        `  /// payload fields ride [rest]). ESCAPE HATCH: any gated directive that sets the field still`,
-        `  /// resolves the conflict in the kernel sense; \`.resolves()\` only designates which one THIS`,
-        `  /// typed helper dispatches.`,
-        `  Future<NomosOfferOutcome> ${helper}(PendingConflictRow conflict, ${chosenType} chosen,`,
+        `  Future<NomosOfferOutcome> ${helper}(${rowClass} conflict, ${mergedType} merged,`,
         `      {Map<String, Object?> rest = const {}}) {`,
         ...(gate !== undefined
           ? [
@@ -531,12 +763,177 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
               `    }`,
             ]
           : []),
-        `    final data = <String, Object?>{...rest, ${dartStr(b.idPayloadField)}: conflict.aggregateId, ${dartStr(b.valuePayloadField)}: chosen};`,
-        `    return _offer(${dartStr(b.directiveId)}, data);`,
+        `    final data = <String, Object?>{...rest, ${dartStr(b.idPayloadField)}: conflict.aggregateId, ${dartStr(b.valuePayloadField)}: merged};`,
+        `    return _offer(${dartStr(b.directiveId)}, data, conflictSnapshots: [<String, Object?>{`,
+        `      'aggregateType': conflict.aggregateType, 'aggregateId': conflict.aggregateId,`,
+        `      'field': conflict.field, 'targetSchema': conflict.targetSchema, 'token': conflict.snapshot,`,
+        `    }]);`,
         `  }`,
         ``,
       );
     }
+
+    conflictDeclarations.push(
+      `/// Framework conflict row decoded by this generated client. It is local to the`,
+      `/// generated release so schema-aware conflict DX never waits on a core package cast.`,
+      `class ${rowClass} {`,
+      `  final String aggregateType;`,
+      `  final String aggregateId;`,
+      `  final String field;`,
+      `  final String status;`,
+      `  final String targetSchema;`,
+      `  final List<SurfacedObservation<Object?>> observations;`,
+      `  final Map<String, dynamic>? evolution;`,
+      `  final String snapshot;`,
+      `  const ${rowClass}({required this.aggregateType, required this.aggregateId, required this.field, required this.status, required this.targetSchema, required this.observations, required this.evolution, required this.snapshot});`,
+      `  factory ${rowClass}.fromJson(Map<String, dynamic> json) {`,
+      `    final snapshot = json['snapshot'];`,
+      `    final targetSchema = json['targetSchema'];`,
+      `    if (snapshot is! String || snapshot.isEmpty || targetSchema is! String || targetSchema.isEmpty) {`,
+      `      throw StateError('conflicts need a Nomos runtime with schema-pinned immutable snapshots');`,
+      `    }`,
+      `    return ${rowClass}(`,
+      `      aggregateType: json['aggregateType'] as String, aggregateId: json['aggregateId'] as String,`,
+      `      field: json['field'] as String, status: json['status'] as String? ?? 'evolutionRequired',`,
+      `      targetSchema: targetSchema, snapshot: snapshot,`,
+      `      evolution: (json['evolution'] as Map?)?.cast<String, dynamic>(),`,
+      `      observations: List.unmodifiable((json['observations'] as List? ?? const []).map((o) => SurfacedObservation<Object?>.fromJson((o as Map).cast<String, dynamic>(), (v) => v))),`,
+      `    );`,
+      `  }`,
+      `}`,
+      ``,
+      `/// Workspace-wide pending-merge totals, derived from Nomos's maintained conflict index.`,
+      `class ${summaryClass} {`,
+      `  final int total;`,
+      `  final int ready;`,
+      `  final int evolutionRequired;`,
+      `  final Map<String, int> byAggregate;`,
+      `  const ${summaryClass}({required this.total, required this.ready, required this.evolutionRequired, required this.byAggregate});`,
+      `}`,
+      ``,
+      `/// Chained conflict API for the \`${domain}\` domain.`,
+      `class ${conflictsClass} {`,
+      `  final ${className} _client;`,
+      `  const ${conflictsClass}(this._client);`,
+      ``,
+      `  Future<${summaryClass}> summary() async {`,
+      `    final summary = await _client.bridge.pendingConflictSummary();`,
+      `    final byAggregate = (summary['byAggregate'] as Map? ?? const {}).map(`,
+      `        (key, value) => MapEntry(key.toString(), (value as num).toInt()));`,
+      `    return ${summaryClass}(`,
+      `      total: (summary['total'] as num? ?? 0).toInt(),`,
+      `      ready: (summary['ready'] as num? ?? 0).toInt(),`,
+      `      evolutionRequired: (summary['evolutionRequired'] as num? ?? 0).toInt(),`,
+      `      byAggregate: Map.unmodifiable(byAggregate),`,
+      `    );`,
+      `  }`,
+      ...[...byAggregate.keys()].map((aggregateId) =>
+        `  ${aggregateConflictsClass(aggregateId)} get ${lcFirst(camel(concreteClassName(aggregateId)))} => ${aggregateConflictsClass(aggregateId)}(_client);`,
+      ),
+      `}`,
+      ``,
+    );
+
+    for (const [aggregateId, bindings] of byAggregate) {
+      const runtimeAggregateType = conflictAggregateType(aggregateId);
+      const aggregateName = cap(camel(concreteClassName(aggregateId)));
+      const aggregateConflict = `${aggregateName}PendingConflict`;
+      conflictDeclarations.push(
+        `/// One pending merge on \`${aggregateId}\`; narrow by subtype to call its typed merge.`,
+        `sealed class ${aggregateConflict} {`,
+        `  const ${aggregateConflict}();`,
+        `  String get aggregateId;`,
+        `  String get field;`,
+        `}`,
+        ``,
+      );
+      for (const b of bindings) {
+        if (b.valuePayloadField === undefined || b.idPayloadField === undefined) continue;
+        const agg = aggById.get(b.aggregateId);
+        const fieldKind = (agg?.fields[b.field] as Field | undefined)?.kind;
+        const mergedType = fieldKind === "string" || fieldKind === "ref" || fieldKind === "enum"
+          ? "String"
+          : fieldKind === "int"
+            ? "int"
+            : fieldKind === "bool"
+              ? "bool"
+              : "Object?";
+        const typeName = `${aggregateName}${cap(camel(b.field))}Conflict`;
+        const evolutionTypeName = `${aggregateName}${cap(camel(b.field))}ConflictEvolutionRequired`;
+        const helper = `_merge${aggregateName}${cap(camel(b.field))}`;
+        conflictDeclarations.push(
+          `/// Pending versions of \`${aggregateId}.${b.field}\`. [merge] commits a result that may`,
+          `/// equal either version or be a new reconciled business value.`,
+          `final class ${typeName} extends ${aggregateConflict} {`,
+          `  final ${rowClass} _details;`,
+          `  final ${className} _client;`,
+          `  const ${typeName}._(this._details, this._client);`,
+          `  @override`,
+          `  String get aggregateId => _details.aggregateId;`,
+          `  @override`,
+          `  String get field => _details.field;`,
+          ``,
+          `  List<SurfacedObservation<${mergedType}>> get versions => List.unmodifiable(`,
+          `      _details.observations.map((o) => SurfacedObservation<${mergedType}>(`,
+          `          value: o.value as ${mergedType}, occurredAt: o.occurredAt, author: o.author)));`,
+          ``,
+          `  Future<NomosOfferOutcome> merge(`,
+          `      ${mergedType} Function(List<SurfacedObservation<${mergedType}>> versions) reconcile,`,
+          `      {Map<String, Object?> rest = const {}}) =>`,
+          `      _client.${helper}(_details, reconcile(versions), rest: rest);`,
+          `}`,
+          ``,
+          `/// The pending values span field schemas. No merge method exists until Nomos can`,
+          `/// deterministically evolve every version to the current business type.`,
+          `final class ${evolutionTypeName} extends ${aggregateConflict} {`,
+          `  final ${rowClass} _details;`,
+          `  const ${evolutionTypeName}._(this._details);`,
+          `  @override`,
+          `  String get aggregateId => _details.aggregateId;`,
+          `  @override`,
+          `  String get field => _details.field;`,
+          `  Map<String, dynamic> get evolution => _details.evolution ?? const {};`,
+          `}`,
+          ``,
+        );
+      }
+      conflictDeclarations.push(
+        `/// Aggregate-specific pending merges for \`${aggregateId}\`.`,
+        `class ${aggregateConflictsClass(aggregateId)} {`,
+        `  final ${className} _client;`,
+        `  const ${aggregateConflictsClass(aggregateId)}(this._client);`,
+        ``,
+        `  Future<List<${aggregateConflict}>> pending() async {`,
+        `    final rows = await _client._pendingConflictRows(${dartStr(runtimeAggregateType)});`,
+        `    final out = <${aggregateConflict}>[];`,
+        `    for (final row in rows) {`,
+        `      if (row.aggregateType != ${dartStr(runtimeAggregateType)}) {`,
+        `        throw StateError('Nomos returned a conflict outside the generated aggregate filter');`,
+        `      }`,
+        `      switch (row.field) {`,
+        ...bindings.flatMap((b) => {
+          if (b.valuePayloadField === undefined || b.idPayloadField === undefined) return [];
+          const typeName = `${aggregateName}${cap(camel(b.field))}Conflict`;
+          const evolutionTypeName = `${aggregateName}${cap(camel(b.field))}ConflictEvolutionRequired`;
+          return [
+            `        case ${dartStr(b.field)}:`,
+            `          if (row.status == 'ready') {`,
+            `            out.add(${typeName}._(row, _client));`,
+            `          } else if (row.status == 'evolutionRequired') {`,
+            `            out.add(${evolutionTypeName}._(row));`,
+            `          } else {`,
+            `            throw StateError('Nomos returned an unknown conflict status: \${row.status}');`,
+            `          }`,
+          ];
+        }),
+        `      }`,
+        `    }`,
+        `    return List.unmodifiable(out);`,
+        `  }`,
+        `}`,
+        ``,
+      );
+    }
   }
 
   // ── per-aggregate by-id read/watch + type-index list ──
@@ -547,22 +944,194 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const name = concreteClassName(agg.id);
     const lc = lcFirst(camel(name));
     const Cap = cap(camel(name));
+    const aScopes = readScopesFor(agg.id);
+    const aOwned = aScopes.some((scope) => scope.owned === true);
+    const aScopesExpr = scopesExpr(aScopes);
+    const runtimeType = isNamespacedAggregate(agg) ? qualifyReadProjectionType(domain, agg.id) : agg.id;
+    const byIdKeys = aScopes.length === 0
+      ? ""
+      : aOwned
+        ? `, await _readKeys(${aScopesExpr}, [{${dartStr("type")}: ${dartStr(runtimeType)}, ${dartStr("id")}: id}])`
+        : keysArg(agg.id);
+    const pastByIdKeys = aScopes.length === 0
+      ? ""
+      : aOwned
+        ? `, await _client._readKeys(${aScopesExpr}, [{${dartStr("type")}: ${dartStr(runtimeType)}, ${dartStr("id")}: id}])`
+        : 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." : ""}`,
       `  Future<List<${model}>> ${safeMethod(`${lc}ById`)}(String id) async =>`,
-      `      (await bridge.queryById(id${keysArg(agg.id)})).map((r) => ${rowToModel(model, "r")}).toList();`,
+      `      (await bridge.queryById(id${byIdKeys})).map((r) => ${rowToModel(model, "r")}).toList();`,
       ``,
       `  /// Watch one ${agg.id} by aggregate id (local reactive read).`,
       `  Stream<List<${model}>> watch${Cap}ById(String id) =>`,
-      `      bridge.watchById(id).map((rows) => rows.map((r) => ${rowToModel(model, "r")}).toList());`,
+      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());`,
       ``,
       `  /// Every ${agg.id} (the type-index probe — O(result), not a scan).`,
       `  Future<List<${model}>> ${safeMethod(`list${Cap}s`)}() async =>`,
-      `      (await bridge.query('aggregatesByType', {'__type': ${dartStr(agg.id)}}${keysArg(agg.id)})).map((r) => ${rowToModel(model, "r")}).toList();`,
+      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();`,
+      ``,
+    );
+    pastMethods.push(
+      `  /// Read one ${agg.id} by aggregate id in the verified world at [moment].`,
+      `  Future<List<${model}>> ${safeMethod(`${lc}ById`)}(String id) async =>`,
+      `      (await _client.bridge.queryByIdAt(moment, id${pastByIdKeys})).map((r) => ${rowToModel(model, "r", "_client._ws")}).toList();`,
+      ``,
+      `  /// 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();`,
       ``,
     );
   }
 
+  if (opts.emitActivity === true) methods.push(
+    `  /// Adopt THIS generated model. Nomos proves it against current history; a deliberate`,
+    `  /// difference returns a decision whose accept(reason) re-proves and records the reason.`,
+    `  NomosModel get model => NomosModel(_adoptGeneratedModel, _restorePreviousGeneratedModel);`,
+    ``,
+    `  NomosModelReview _nomosModelReview(Map<String, Object?>? report) {`,
+    `    final differences = <NomosModelDifference>[];`,
+    `    for (final raw in ((report?['divergences'] as List?) ?? const [])) {`,
+    `      final difference = (raw as Map).cast<String, Object?>();`,
+    `      final rawArea = difference['domain'];`,
+    `      final area = rawArea is String && !rawArea.contains('nomos_internal') ? rawArea : null;`,
+    `      final rawAction = difference['directiveId'];`,
+    `      final action = rawAction is String && !rawAction.contains('nomos_internal') ? rawAction : null;`,
+    `      final rawKind = difference['kind']?.toString();`,
+    `      final kind = rawKind == 'plan-divergence'`,
+    `          ? NomosModelDifferenceKind.outcome`,
+    `          : rawKind == 'unsupported-premise' || rawKind == 'read-conflict'`,
+    `              ? NomosModelDifferenceKind.evidence`,
+    `              : NomosModelDifferenceKind.rules;`,
+    `      final subject = action ?? (kind == NomosModelDifferenceKind.outcome ? 'A business action' : 'A historical action');`,
+    `      final summary = kind == NomosModelDifferenceKind.outcome`,
+    `          ? '\$subject would produce a different result under this model.'`,
+    `          : kind == NomosModelDifferenceKind.evidence`,
+    `              ? 'Nomos could not reproduce all evidence needed by \$subject.'`,
+    `              : "\$subject is not accepted by this model's rules.";`,
+    `      differences.add(NomosModelDifference(kind: kind, area: area, action: action, summary: summary));`,
+    `    }`,
+    `    final evolve = (report?['evolve'] as Map?)?.cast<String, Object?>();`,
+    `    if (report != null && evolve?['ok'] != true && !differences.any((d) => d.kind == NomosModelDifferenceKind.rules)) {`,
+    `      differences.add(const NomosModelDifference(kind: NomosModelDifferenceKind.rules, summary: 'This model does not yet explain how to interpret every existing value.'));`,
+    `    }`,
+    `    if (report != null && (report['sourceVerified'] != true || report['complete'] != true)`,
+    `        && !differences.any((d) => d.kind == NomosModelDifferenceKind.evidence)) {`,
+    `      differences.add(const NomosModelDifference(kind: NomosModelDifferenceKind.evidence, summary: 'Nomos could not re-prove every premise in the current business history.'));`,
+    `    }`,
+    `    final projection = (report?['projection'] as Map?)?.cast<String, Object?>();`,
+    `    int number(String name) => (report?[name] as num?)?.toInt() ?? 0;`,
+    `    return NomosModelReview(`,
+    `      checkedActions: number('replayedIntents'), candidateActions: number('candidateIntents'),`,
+    `      sameOutcome: projection?['equal'] as bool?, differences: differences);`,
+    `  }`,
+    ``,
+    `  Future<NomosModelAdoption> _adoptGeneratedModel([String? because]) async {`,
+    `    final raw = await bridge.nomosFrameworkAdoptGeneratedModel(`,
+    `      domain: ${dartStr(domain)}, candidateHash: domainHash, because: because);`,
+    `    final reportRaw = raw['report'];`,
+    `    final report = reportRaw is Map ? reportRaw.cast<String, Object?>() : null;`,
+    `    final review = _nomosModelReview(report);`,
+    `    final stage = raw['stage']?.toString();`,
+    `    if (stage == 'promoted' && raw['ok'] == true) {`,
+    `      return NomosModelAdoption.adopted(`,
+    `        summary: 'Nomos proved this model against current history and made it active.', review: review);`,
+    `    }`,
+    `    if (stage == 'acceptance') {`,
+    `      return NomosModelAdoption.needsDecision(`,
+    `        summary: 'This model would change prior business outcomes. Review the differences and record why that is intended.',`,
+    `        review: review, accept: (reason) => _adoptGeneratedModel(reason));`,
+    `    }`,
+    `    final evolve = (report?['evolve'] as Map?)?.cast<String, Object?>();`,
+    `    final summary = stage == 'identity'`,
+    `        ? 'Sign in before adopting this model so the decision is accountable.'`,
+    `        : report != null && report['sourceVerified'] != true`,
+    `            ? 'The current history could not be verified. Nothing changed and the current model remains active.'`,
+    `            : report != null && report['complete'] != true`,
+    `                ? 'Nomos could not re-prove every historical dependency. Nothing changed and the current model remains active.'`,
+    `                : report != null && evolve?['ok'] != true`,
+    `                    ? 'This model cannot yet interpret every existing value. Nothing changed and the current model remains active.'`,
+    `                    : 'The workspace changed or refused this adoption. Nothing changed; ask Nomos to try again.';`,
+    `    return NomosModelAdoption.blocked(summary: summary, review: review);`,
+    `  }`,
+    ``,
+    `  Future<NomosModelRestoration> _restorePreviousGeneratedModel([String? because]) async {`,
+    `    final raw = await bridge.nomosFrameworkRestorePreviousGeneratedModel(`,
+    `      domain: ${dartStr(domain)}, currentHash: domainHash, because: because);`,
+    `    final reportRaw = raw['report'];`,
+    `    final report = reportRaw is Map ? reportRaw.cast<String, Object?>() : null;`,
+    `    final review = _nomosModelReview(report);`,
+    `    final stage = raw['stage']?.toString();`,
+    `    if (stage == 'restored' && raw['ok'] == true) {`,
+    `      return NomosModelRestoration.restored(`,
+    `        summary: 'Nomos re-proved current history and restored the previous model.', review: review);`,
+    `    }`,
+    `    if (stage == 'acceptance') {`,
+    `      return NomosModelRestoration.needsDecision(`,
+    `        summary: 'Restoring the previous model changes which rules govern future work. Review the effects and record why restoration is intended.',`,
+    `        review: review, accept: (reason) => _restorePreviousGeneratedModel(reason));`,
+    `    }`,
+    `    final evolve = (report?['evolve'] as Map?)?.cast<String, Object?>();`,
+    `    final error = raw['error']?.toString();`,
+    `    final summary = stage == 'identity'`,
+    `        ? 'Sign in before restoring a model so the decision is accountable.'`,
+    `        : error?.contains('restore-no-previous') == true`,
+    `            ? 'This is the first model for this business; there is no previous model to restore.'`,
+    `            : error?.contains('restore-current-changed') == true`,
+    `                ? 'The current model changed before restoration could finish. Nothing changed; ask Nomos to review again.'`,
+    `                : report != null && report['sourceVerified'] != true`,
+    `                    ? 'The current history could not be verified. Nothing changed and the current model remains active.'`,
+    `                    : report != null && report['complete'] != true`,
+    `                        ? 'Nomos could not re-prove every historical dependency. Nothing changed and the current model remains active.'`,
+    `                        : report != null && evolve?['ok'] != true`,
+    `                            ? 'The previous model cannot safely interpret every existing value. Nothing changed and the current model remains active.'`,
+    `                            : 'The workspace refused restoration. Nothing changed and the current model remains active.';`,
+    `    return NomosModelRestoration.blocked(summary: summary, review: review);`,
+    `  }`,
+    ``,
+  );
+
+  const pastClass = `${className}Past`;
+  const atClass = `${className}At`;
+  methods.push(
+    `  /// Read the same typed business world at a verified point in its history.`,
+    `  ${pastClass} get past => ${pastClass}(this);`,
+    ``,
+  );
+  pastDeclarations.push(
+    `/// The accountable timeline for a [${className}]. Commit identities remain opaque inside [NomosMoment].`,
+    `class ${pastClass} {`,
+    `  final ${className} _client;`,
+    `  const ${pastClass}(this._client);`,
+    ``,
+    `  Future<List<NomosMoment>> moments({int limit = 100}) async {`,
+    `    final moments = await _client.bridge.moments(limit: limit);`,
+    `    const actions = <String>{${[...allDirs.map((directive) => directive.id), ...(correctionActions.length > 0 ? [BUSINESS_CORRECTION_DIRECTIVE] : [])].map(dartStr).join(", ")}};`,
+    `    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();`,
+    `  }`,
+    `  ${atClass} at(NomosMoment moment) => ${atClass}(_client, moment);`,
+    `}`,
+    ``,
+    `/// A read-only, business-shaped view of [${className}] at one verified [moment].`,
+    `class ${atClass} {`,
+    `  final ${className} _client;`,
+    `  final NomosMoment moment;`,
+    `  const ${atClass}(this._client, this.moment);`,
+    ``,
+    ...pastMethods,
+    `}`,
+    ``,
+  );
+
   // ── REF-TRAVERSAL ACCESSORS (dart_codegen_parity.md P2 + §2a follow-on — ref ergonomics) ──
   // For every reference field on a read model, emit a companion extension method that resolves the
   // stored locator to the actual target row, composed ONLY from surface that already exists (no new
@@ -720,29 +1289,32 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     refExtensions.push(lines.join("\n"));
   }
 
-  // ── activity feed → typed reactive + one-shot (declared `.activity(...)`) ──
+  // ── activity feed → typed reactive + one-shot (automatic baseline; `.activity(...)` enriches) ──
   if (opts.emitActivity === true) {
     methods.push(
       `  /// THE ACTIVITY FEED (architecture/activity_descriptors.md): fold the committed intent log into typed`,
-      `  /// [ActivityEvent]s (declared \`.activity(...)\`). Re-emits on every new committed intent; a directive`,
-      `  /// with no declared activity is dropped. Cancel the subscription to stop.`,
+      `  /// [ActivityEvent]s (automatic baseline; \`.activity(...)\` enriches it). Re-emits on every new`,
+      `  /// committed intent; a directive`,
+      `  /// outside this generated business package is dropped. Cancel the subscription to stop.`,
       `  Stream<List<ActivityEvent>> watchActivity() =>`,
       `      bridge.watchActivity().map((rows) => rows`,
       `          .map((r) => renderActivity((r as Map).cast<String, dynamic>()))`,
       `          .whereType<ActivityEvent>()`,
       `          .toList());`,
       ``,
-      `  /// One-shot: the current committed activity log, folded to typed [ActivityEvent]s (declared \`.activity(...)\`).`,
+      `  /// One-shot: the current committed activity log, folded to typed [ActivityEvent]s.`,
       `  Future<List<ActivityEvent>> activityLog({String? base, int? limit}) async =>`,
       `      (await bridge.activityLog(base: base, limit: limit))`,
       `          .map((r) => renderActivity(r.cast<String, dynamic>()))`,
       `          .whereType<ActivityEvent>()`,
       `          .toList();`,
       ``,
-      `  /// NARRATIVE (for an in-app LLM): the workspace story — the activity log folded to typed events + a`,
-      `  /// plain-English [ActivityNarrative.transcript] grounded in the VERIFIED log. Filter by [actor] /`,
-      `  /// [category] / [since] (ISO occurredAt lower bound); [limit] caps the rows pulled. Newest-first.`,
-      `  Future<ActivityNarrative> describe({String? since, String? actor, String? category, int? limit}) async {`,
+      `  /// THE SELF-DESCRIPTION: root links to exactly six grounded pages — model, current state, rules,`,
+      `  /// 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,`,
+      `  }) async {`,
       `    final raw = await bridge.activityLog(limit: limit);`,
       `    var events = raw`,
       `        .map((r) => renderActivity(r.cast<String, dynamic>()))`,
@@ -751,7 +1323,170 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       `    if (actor != null) events = events.where((e) => e.actorSubject == actor).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();`,
-      `    return activityNarrative(events);`,
+      `    final narrative = activityNarrative(events);`,
+      `    var organisation = const NomosOrganisationDescription(complete: false, children: []);`,
+      `    try {`,
+      `      final children = (await bridge.nomosFrameworkChildWorkspaces()).map((child) {`,
+      `        final workspace = child['workspace']?.toString() ?? '';`,
+      `        final status = child['status']?.toString() ?? 'unknown';`,
+      `        final summary = status == 'active'`,
+      `            ? 'This part of the organisation is active. Follow its generated description to continue.'`,
+      `            : status == 'retired'`,
+      `                ? 'This part of the organisation is retired. Its recorded history remains explainable.'`,
+      `                : status == 'reclaimed'`,
+      `                    ? "This part of the organisation was reclaimed. Its birth remains part of this workspace's history."`,
+      `                    : 'This part of the organisation has a newer lifecycle this client does not understand. Its link remains visible.';`,
+      `        return NomosDescribeChild(`,
+      `          workspace: workspace, status: status, bornAt: child['bornAt']?.toString(), label: workspace,`,
+      `          question: 'What does this part of the organisation do, and what has happened there?', summary: summary);`,
+      `      }).where((child) => child.workspace.isNotEmpty).toList();`,
+      `      organisation = NomosOrganisationDescription(complete: children.every((child) => child.status != 'unknown'), children: children);`,
+      `    } catch (_) {`,
+      `      // An old/unavailable runtime cannot prove a leaf. Keep incompleteness explicit.`,
+      `    }`,
+      `    final model = (jsonDecode(_nomosDescribeModelJson) as Map).cast<String, dynamic>();`,
+      `    final links = ((model['links'] as List?) ?? const [])`,
+      `        .map((raw) {`,
+      `          final link = (raw as Map).cast<String, dynamic>();`,
+      `          return NomosDescribeLink(`,
+      `            section: NomosDescribeSection.values.byName(link['section'] as String),`,
+      `            label: link['label'] as String, question: link['question'] as String, summary: link['summary'] as String);`,
+      `        }).toList();`,
+      `    NomosDescribeItem staticItem(dynamic raw) {`,
+      `      final item = (raw as Map).cast<String, dynamic>();`,
+      `      return NomosDescribeItem(`,
+      `        kind: item['kind'] as String, id: item['id'] as String, label: item['label'] as String,`,
+      `        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();`,
+      `    String refusalReason(Object? raw) {`,
+      `      final text = (raw ?? '').toString().toLowerCase();`,
+      `      bool has(List<String> parts) => parts.any(text.contains);`,
+      `      if (has(const ['evolve', 'schema', 'projection', 'retype', 'removed field', 'law drift', 'law-drift', 'cross-version', 'older model', 'authored under'])) return 'model-change';`,
+      `      if (has(const ['attest', 'evidence', 'source session', 'source unreachable', 'read unreachable'])) return 'evidence';`,
+      `      if (has(const ['permission', 'unauthor', 'forbidden', 'requires relation', 'relation gate', 'signer', 'principal', 'access denied', 'not enrolled'])) return 'permission';`,
+      `      if (has(const ['precondition', 'invariant', 'constraint', 'validation', 'invalid payload', 'business rule', 'required field', 'must be'])) return 'business-rule';`,
+      `      return 'review';`,
+      `    }`,
+      `    String refusalSummary(String reason, String action) {`,
+      `      switch (reason) {`,
+      `        case 'permission': return '$action was retained because its author did not have the required business permission.';`,
+      `        case 'business-rule': return '$action was retained because it did not satisfy the business rules declared for that action.';`,
+      `        case 'model-change': return '$action was created under a model the workspace cannot currently interpret. It remains available while other work continues.';`,
+      `        case 'evidence': return '$action was retained because required verified business evidence was unavailable.';`,
+      `        default: return '$action was retained for review and has not changed the business state.';`,
+      `      }`,
+      `    }`,
+      ``,
+      `    var title = model['title'] as String;`,
+      `    var summary = model['summary'] as String;`,
+      `    var items = <NomosDescribeItem>[];`,
+      `    if (section == NomosDescribeSection.model || section == NomosDescribeSection.rules) {`,
+      `      final pages = (model['pages'] as Map).cast<String, dynamic>();`,
+      `      final page = (pages[section.name] as Map).cast<String, dynamic>();`,
+      `      title = page['title'] as String; summary = page['summary'] as String;`,
+      `      items = ((page['items'] as List?) ?? const []).map(staticItem).toList();`,
+      `    } else if (section == NomosDescribeSection.current) {`,
+      `      title = 'Current state';`,
+      `      summary = 'The business records this session is allowed to read now. An unavailable type stays named without leaking its contents.';`,
+      `      for (final rawAggregate in ((model['aggregateTypes'] as List?) ?? const [])) {`,
+      `        final aggregate = (rawAggregate as Map).cast<String, dynamic>();`,
+      `        final type = aggregate['type'] as String;`,
+      `        final queryType = aggregate['queryType'] as String;`,
+      `        final label = aggregate['label'] as String;`,
+      `        try {`,
+      `          final rows = await bridge.query('aggregatesByType', {'__type': queryType});`,
+      `          final refs = rows.map((row) => NomosRef(`,
+      `            workspace: _ws, type: (row['type'] ?? type).toString(), id: (row['id'] ?? '').toString())).toList();`,
+      `          final exact = aggregate['audience'] == 'public' || rows.isNotEmpty;`,
+      `          items.add(NomosDescribeItem(`,
+      `            kind: 'current', id: '\${aggregate['domain']}.\$type', label: label,`,
+      `            summary: exact ? '\${rows.length} \$label record\${rows.length == 1 ? '' : 's'} visible now.' : 'No \$label records are visible to this session.',`,
+      `            details: {'domain': aggregate['domain'], 'type': type, 'audience': aggregate['audience'], if (exact) 'count': rows.length else 'status': 'none-visible'}, refs: refs));`,
+      `        } catch (_) {`,
+      `          items.add(NomosDescribeItem(`,
+      `            kind: 'current', id: '\${aggregate['domain']}.\$type', label: label,`,
+      `            summary: '\$label exists in the model, but this session cannot read its current records.',`,
+      `            details: {'domain': aggregate['domain'], 'type': type, 'audience': aggregate['audience'], 'status': 'unavailable'}));`,
+      `        }`,
+      `      }`,
+      `    } else if (section == NomosDescribeSection.history) {`,
+      `      title = 'Verified business history';`,
+      `      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},`,
+      `        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},`,
+      `        refs: eventRefs(event))).toList();`,
+      `      final aggregateTypes = ((model['aggregateTypes'] as List?) ?? const [])`,
+      `          .map((raw) => (raw as Map).cast<String, dynamic>()).toList();`,
+      `      for (final conflict in await bridge.pendingConflicts()) {`,
+      `        Map<String, dynamic>? aggregate;`,
+      `        for (final candidate in aggregateTypes) {`,
+      `          if (candidate['queryType'] == conflict['aggregateType']) { aggregate = candidate; break; }`,
+      `        }`,
+      `        if (aggregate == null) continue;`,
+      `        final field = (conflict['field'] ?? '').toString();`,
+      `        final pages = (model['pages'] as Map).cast<String, dynamic>();`,
+      `        final ruleItems = (((pages['rules'] as Map)['items'] as List?) ?? const [])`,
+      `            .map((raw) => (raw as Map).cast<String, dynamic>());`,
+      `        Map<String, dynamic>? rule;`,
+      `        final ruleId = '\${aggregate['domain']}.\${aggregate['type']}.$field.merge';`,
+      `        for (final candidate in ruleItems) { if (candidate['id'] == ruleId) { rule = candidate; break; } }`,
+      `        final subject = rule?['label']?.toString() ?? '\${aggregate['label']} $field';`,
+      `        final status = conflict['status']?.toString() ?? 'ready';`,
+      `        final versions = status == 'ready'`,
+      `            ? ((conflict['observations'] as List?)?.length ?? 0)`,
+      `            : ((((conflict['evolution'] as Map?)?['sourceSchemas']) as List?)?.length ?? 0);`,
+      `        final conflictSummary = status == 'ready'`,
+      `            ? '$subject has $versions competing versions waiting for one business merge.'`,
+      `            : '$subject cannot yet be compared because the model does not explain every earlier value. The disagreement remains pending while unrelated work continues.';`,
+      `        items.add(NomosDescribeItem(`,
+      `          kind: status == 'ready' ? 'pending-merge' : 'evolution-required',`,
+      `          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())]));`,
+      `      }`,
+      `      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();`,
+      `      for (final entry in await bridge.deadLetters()) {`,
+      `        final domain = entry['domain']; final directive = entry['directiveId'];`,
+      `        if (domain is! String || directive is! String) continue;`,
+      `        Map<String, dynamic>? action;`,
+      `        for (final candidate in modelPageItems) { if (candidate['id'] == '$domain.$directive') { action = candidate; break; } }`,
+      `        if (action == null) continue;`,
+      `        final reason = refusalReason(entry['error']); final actionLabel = action['label'].toString();`,
+      `        items.add(NomosDescribeItem(kind: 'rejected-action', id: 'rejected:\${entry['id'] ?? entry['oid']}',`,
+      `          label: 'Review $actionLabel', summary: refusalSummary(reason, actionLabel),`,
+      `          details: {'domain': domain, 'action': directive, 'status': 'retained', 'reason': reason, 'refusedAt': entry['at'], 'canRetry': true}));`,
+      `      }`,
+      `      final pages = (model['pages'] as Map).cast<String, dynamic>();`,
+      `      final rules = ((pages['rules'] as Map)['items'] as List?) ?? const [];`,
+      `      items.addAll(rules.where((raw) => (raw as Map)['kind'] == 'conflict-rule' || raw['kind'] == 'merge-rule').map(staticItem));`,
+      `    } else if (section == NomosDescribeSection.evidence) {`,
+      `      title = 'Evidence';`,
+      `      summary = 'Opaque identities tying this answer to one workspace, one generated law and its verified business history.';`,
+      `      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: '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}),`,
+      `      ];`,
+      `    }`,
+      `    return NomosDescription(`,
+      `      section: section, title: title, summary: summary, items: items, links: links, organisation: organisation,`,
+      `      events: events, transcript: narrative.transcript);`,
       `  }`,
       ``,
       `  /// NARRATIVE for ONE thing: the story of the aggregate [aggregateId] — events whose declared refs`,
@@ -790,7 +1525,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     ``,
     // `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.
-    ...(opts.interface !== undefined || roleHelpers !== "" ? [`import 'dart:convert';`, ``] : []),
+    ...(clientInterface !== undefined || roleHelpers !== "" || opts.emitActivity === true ? [`import 'dart:convert';`, ``] : []),
     `import '${supportImport}';`,
     // Layered-packages mode: the sibling types live in their OWN package — one barrel import
     // replaces both the relative types import and the relative framework import.
@@ -818,18 +1553,25 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `// client file gives an app the whole typed surface.`,
     ...(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, NomosClientInterface, DomainClientSessionMismatch, DomainNotInstalledForSession, SessionMismatchCause${encPresent ? ", NomosScopeKey, NomosKeyStore, EncryptionKeyUnavailable, WrappedKeyStore, NomosEncryption, NomosEpochResult, EncryptionMemberKeyMissing, EncryptionRosterMismatch" : ""};`,
+    `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)};`,
     ``,
-    ...(opts.interface !== undefined
+    ...(opts.emitActivity === true
+      ? [
+          `/// Compiler-known business language and policy; verified runtime facts join it behind describe().`,
+          `const String _nomosDescribeModelJson = ${dartRawJson(describeModel)};`,
+          ``,
+        ]
+      : []),
+    ...(clientInterface !== undefined
       ? [
           `/// This client's STRUCTURAL INTERFACE REQUIREMENT (#72) as JSON — the directives (payload`,
           `/// shapes) + aggregates (read shapes, sid-keyed) it depends on. \`connect()\` negotiates this`,
           `/// against the workspace's installed offer by SHAPE (stable-id subtyping), not by law hash,`,
           `/// so the domain can evolve without republishing this client.`,
-          `const String ${interfaceConstNameDart(mod.name)} = ${dartRawJson(opts.interface)};`,
+          `const String ${interfaceConstNameDart(mod.name)} = ${dartRawJson(clientInterface)};`,
           ``,
         ]
       : []),
@@ -842,6 +1584,8 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
           ``,
         ]
       : []),
+    ...pastDeclarations,
+    ...conflictDeclarations,
     `/// Typed async client for the \`${domain}\` domain, bound to a connected [NomosBridge].`,
     `///`,
     `/// Pass \`actor\` (the verified principal uid) to author AS that user — the bridge's \`offerDirective\` op`,
@@ -857,7 +1601,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `  /// The verified principal uid every offer is authored as (sealed as \`security.actor\` by the one encoder).`,
     `  /// Null ⇒ open (un-gated) authoring; a gated directive then throws [MissingOfferAuthority].`,
     `  final String? actor;`,
-    ...(encPresent
+    ...(manualEncryptionPresent
       ? [
           ``,
           `  /// THE KEY CUSTODY surface (E2E sealing). When set, encrypted directive fields SEAL automatically`,
@@ -866,7 +1610,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
           `  final NomosKeyStore? keyStore;`,
         ]
       : []),
-    `  ${className}(this.bridge, {this.domainHash = ${hashConst}, this.actor${encPresent ? ", this.keyStore" : ""}});`,
+    `  ${className}(this.bridge, {this.domainHash = ${hashConst}, this.actor${manualEncryptionPresent ? ", this.keyStore" : ""}});`,
     ``,
     `  /// THE STATIC INTERFACE DESCRIPTOR (session_bound_clients.md asks 5/9): what this client EXPECTS`,
     `  /// of the workspace it binds to — the domain key, the law hash it was generated against, and the`,
@@ -879,7 +1623,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `    domain: ${dartStr(domain)},`,
     `    expectedDomainHash: ${hashConst},`,
     ...(compatInterfaceHash !== undefined ? [`    expectedInterfaceHash: ${dartStr(compatInterfaceHash)},`] : []),
-    ...(opts.interface !== undefined ? [`    interfaceJson: ${interfaceConstNameDart(mod.name)},`] : []),
+    ...(clientInterface !== undefined ? [`    interfaceJson: ${interfaceConstNameDart(mod.name)},`] : []),
     ...(opts.compat !== undefined ? [`    compatJson: ${compatConstNameDart(mod.name)},`] : []),
     `  );`,
     ``,
@@ -890,13 +1634,16 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `  /// IMMEDIATELY — at provider construction, not two clicks into the app. The synchronous`,
     `  /// constructor remains for codepaths that can't await; it lazily runs the SAME preflight on the`,
     `  /// first dispatch.`,
-    `  static Future<${className}> bind(NomosSession session, {String? actor${encPresent ? ", NomosKeyStore? keyStore" : ""}}) async {`,
+    `  static Future<${className}> bind(NomosSession session, {String? actor${manualEncryptionPresent ? ", NomosKeyStore? keyStore" : ""}}) async {`,
     `    await session.assertCompatible(interface);`,
     `    // RELEASE COHERENCE: the cloud's kernel must support what this law needs (e.g. a compound-key query`,
     `    // needs 'compoundKeys'). Throws a typed KernelCoherenceError on a stale/mismatched cloud kernel,`,
     `    // up front — not an opaque deep-fold refusal. Best-effort (no-op if the cloud advertises no caps).`,
     `    await session.assertKernelCoherence(requiresKernel, lawHash: ${hashConst});`,
-    `    return ${className}(session, actor: actor${encPresent ? ", keyStore: keyStore" : ""}).._preflighted = true;`,
+    ...(ownedScope === undefined
+      ? []
+      : [`    await session.nomosEnsureOwnedIdentity(scope: ${dartStr(ownedScope)}, domain: ${dartStr(domain)}, domainHash: ${hashConst});`]),
+    `    return ${className}(session, actor: actor${manualEncryptionPresent ? ", keyStore: keyStore" : ""}).._preflighted = true${ownedScope === undefined ? "" : ".._ownedIdentityReady = true"};`,
     `  }`,
     ``,
     `  /// OPEN-THEN-BIND (session_bound_clients.md ask 3) — the ONE-CALL path for a born/resident workspace:`,
@@ -905,13 +1652,13 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `  /// 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${encPresent ? ", NomosKeyStore? keyStore" : ""}}) async {`,
+    `  static Future<${className}> open(NomosBridge bridge, {NomosRef? ref, String? workspace, String? actor${manualEncryptionPresent ? ", NomosKeyStore? keyStore" : ""}}) async {`,
     `    final ws = ref?.workspace ?? workspace;`,
     `    if (ws == null || ws.isEmpty) {`,
     `      throw ArgumentError('${className}.open: pass a workspace: or ref: — the workspace to open and bind');`,
     `    }`,
     `    final session = await bridge.acquireSession(ws);`,
-    `    return bind(session, actor: actor${encPresent ? ", keyStore: keyStore" : ""});`,
+    `    return bind(session, actor: actor${manualEncryptionPresent ? ", keyStore: keyStore" : ""});`,
     `  }`,
     ``,
     `  /// The session workspace this client is bound to (from the [NomosSession] handle, when constructed with`,
@@ -939,18 +1686,53 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `    if (b is NomosSession) await b.assertCompatible(interface);`,
     `  }`,
     ``,
+    ...(ownedScope === undefined || Object.keys(ownedActions).length === 0
+      ? []
+      : [
+          `  static const Map<String, Map<String, String>> _ownedRecordActions = ${ownedActionsDart};`,
+          `  bool _ownedIdentityReady = false;`,
+          `  Future<void> _ensureOwnedIdentity() async {`,
+          `    if (_ownedIdentityReady) return;`,
+          `    await bridge.nomosEnsureOwnedIdentity(scope: ${dartStr(ownedScope)}, domain: ${dartStr(domain)}, domainHash: domainHash);`,
+          `    _ownedIdentityReady = true;`,
+          `  }`,
+          ``,
+          `  Future<NomosOfferOutcome> _ownedRecordAction(String action, NomosRef 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 (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);`,
+          `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: directiveId, payload: payload, actor: actor, domainHash: domainHash);`,
+          `  }`,
+          ``,
+        ]),
     ...(dirs.length > 0 || birthDirs.some((d) => (d as { businessBirth?: unknown }).businessBirth !== undefined)
       ? [
           `  /// THE ONE DISPATCH LANE every generated directive method routes through: lazy preflight, then`,
           `  /// the session's offer (the generated-internal use of the engine-level lane).`,
-          `  Future<NomosOfferOutcome> _offer(String directiveId, Object? payload, {List<Map<String, Object?>>? attestations}) async {`,
+          `  Future<NomosOfferOutcome> _offer(String directiveId, Object? payload, {List<Map<String, Object?>>? attestations, List<Map<String, Object?>>? conflictSnapshots}) async {`,
           `    await _preflightOnce();`,
-          `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: directiveId, payload: payload, actor: actor, domainHash: domainHash, attestations: attestations);`,
+          `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: directiveId, payload: payload, actor: actor, domainHash: domainHash, attestations: attestations, nomosConflictSnapshots: conflictSnapshots);`,
           `  }`,
           ``,
         ]
       : []),
-    ...(encPresent ? dartEncClassMembers(encMap!) : []),
+    ...(encPresent ? dartEncClassMembers(encMap!, manualEncryptionPresent) : []),
+    ...(ownedScope === undefined
+      ? []
+      : [
+          `  /// Opt into all-device-loss recovery with one explicitly designated person.`,
+          `  NomosRecovery get recovery => NomosRecovery(`,
+          `      bridge: bridge, domain: ${dartStr(domain)}, domainHash: domainHash, scope: ${dartStr(ownedScope)});`,
+          ``,
+          `  /// Add another of this person's devices. Requests are opaque; Nomos owns the handoff.`,
+          `  NomosDevices get devices => NomosDevices(`,
+          `      bridge: bridge, domain: ${dartStr(domain)}, domainHash: domainHash, actor: actor, scope: ${dartStr(ownedScope)});`,
+          ``,
+        ]),
     // THE OWNER CEREMONY (slice 2): grantAndWrap / revokeAndRotate / rotate — the operator-blind key-epoch
     // handshake as one call. Bind `actor` (the owner) to author the fan-out. Only for a domain with a scope.
     ...(domScopes.length > 0
@@ -963,7 +1745,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
           ``,
         ]
       : []),
-    ...(opts.interface !== undefined
+    ...(clientInterface !== undefined
       ? [
           `  /// This client's structural interface requirement (#72) as JSON — hand it to the`,
           `  /// bridge's compatibility check to negotiate by SHAPE against the workspace's offer.`,
@@ -1016,40 +1798,97 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
 }
 
 /** The in-class E2E-sealing members: the baked map + the seal/read private helpers. */
-function dartEncClassMembers(encMap: EncDomainMap): string[] {
+function dartEncClassMembers(encMap: EncDomainMap, manualEncryptionPresent: boolean): string[] {
   return [
     `  /// The baked E2E-sealing map (compile-time, from the SAME sids the law was compiled with): which`,
     `  /// directive payload fields seal → { scope, aggSid, fieldSid }, and which read-model fields decrypt.`,
     `  static final Map<String, dynamic> encryptionMap = (jsonDecode(${dartRawJson(encMap)}) as Map).cast<String, dynamic>();`,
     ``,
-    `  /// Seal the mapped encrypted fields of \`data\` in place before dispatch. No keyStore / \`seal == false\``,
-    `  /// ⇒ passthrough (today's behavior); a held key seals; a missing key throws [EncryptionKeyUnavailable].`,
-    `  Future<void> _sealPayload(Map<String, dynamic> data, String directiveId, bool seal) async {`,
-    `    if (!seal || keyStore == null) return;`,
+    `  /// Seal the mapped encrypted fields of \`data\` in place before dispatch. Ordinary encryption may`,
+    `  /// use the bound keyStore; .owned() keys are held internally by the connected Nomos client.`,
+    `  Future<void> _sealPayload(Map<String, dynamic> data, String directiveId, bool seal, [NomosScopeKey? ownedKeyOverride, String? ownedRecordType, String? ownedRecordId, bool ownedRecordPreMinted = false]) async {`,
     `    final fields = (encryptionMap['directives'] as Map)[directiveId] as Map?;`,
     `    if (fields == null) return;`,
+    `    if (!seal) {`,
+    `      if (fields.values.any((raw) => (raw as Map)['owned'] == true)) {`,
+    `        throw StateError('.owned() encryption cannot be disabled');`,
+    `      }`,
+    `      return;`,
+    `    }`,
+    `    NomosScopeKey? ownedKey = ownedKeyOverride;`,
+    `    Map? owned;`,
+    `    for (final raw in fields.values) {`,
+    `      final candidate = raw as Map;`,
+    `      if (candidate['owned'] == true) { owned = candidate; break; }`,
+    `    }`,
+    `    if (owned != null) {`,
+    `      if (ownedKey == null && (ownedRecordType == null || ownedRecordType.isEmpty || ownedRecordId == null || ownedRecordId.isEmpty)) {`,
+    `        throw StateError('Nomos could not derive the owned record identity before sealing; recompile the client and law together');`,
+    `      }`,
+    `      ownedKey ??= await bridge.nomosOwnedScopeKey(owned['scope'] as String, recordType: ownedRecordType, recordId: ownedRecordId);`,
+    `      final subject = ownedKey.ownedKeySubject;`,
+    `      if (subject == null || subject.isEmpty) {`,
+    `        throw StateError('Nomos did not return the framework-owned device identity for .owned() custody');`,
+    `      }`,
+    `      data[${JSON.stringify(OWNED_KEY_PAYLOAD_FIELD)}] = subject;`,
+    `      if (ownedKey.ownedCustody != null && ownedKey.ownedCustody!.isNotEmpty) {`,
+    `        data[${JSON.stringify(OWNED_CUSTODY_PAYLOAD_FIELD)}] = ownedKey.ownedCustody;`,
+    `      }`,
+    `      if (ownedRecordPreMinted) {`,
+    `        data[${JSON.stringify(OWNED_PREMINTED_RECORDS_PAYLOAD_FIELD)}] = [{'type': ownedRecordType, 'id': ownedRecordId}];`,
+    `      }`,
+    `    }`,
     `    for (final entry in fields.entries) {`,
     `      final field = entry.key as String;`,
     `      final m = entry.value as Map;`,
     `      if (data[field] == null) continue;`,
     `      final scope = m['scope'] as String;`,
-    `      final sk = await keyStore!.scopeKey(scope);`,
+    `      NomosScopeKey? sk = m['owned'] == true ? ownedKey : ${manualEncryptionPresent ? "keyStore == null ? null : await keyStore!.scopeKey(scope)" : "null"};`,
     `      if (sk == null) throw EncryptionKeyUnavailable(scope, field);`,
     `      data[field] = await bridge.cryptoSealField(`,
-    `        scopeKey: sk.key, scope: scope, epoch: sk.epoch,`,
+    `        scopeKey: sk.key, scope: m['owned'] == true ? sk.scope : scope, epoch: sk.epoch,`,
     `        aggSid: m['aggSid'] as String, fieldSid: m['fieldSid'] as String,`,
     `        plaintext: data[field].toString(),`,
     `      );`,
     `    }`,
     `  }`,
     ``,
-    `  /// The read keys to inject for \`scopes\`, or null when there is nothing to inject (no keyStore / no`,
-    `  /// held keys) — the read then behaves exactly as today (encrypted fields stay opaque envelopes).`,
-    `  Future<List<NomosScopeKey>?> _readKeys(List<String> scopes) async {`,
-    `    if (keyStore == null || scopes.isEmpty) return null;`,
-    `    final keys = await keyStore!.readKeys(scopes);`,
+    `  /// Read keys for ordinary app-custodied scopes plus framework-custodied .owned() scopes.`,
+    `  Future<List<NomosScopeKey>?> _readKeys(List<Map<String, Object?>> scopes, [List<Map<String, String>> records = const []]) async {`,
+    `    if (scopes.isEmpty) return null;`,
+    ...(manualEncryptionPresent
+      ? [`    final ordinary = scopes.where((s) => s['owned'] != true).map((s) => s['scope']! as String).toSet().toList();`]
+      : []),
+    `    final keys = ${manualEncryptionPresent ? "keyStore == null || ordinary.isEmpty ? <NomosScopeKey>[] : await keyStore!.readKeys(ordinary)" : "<NomosScopeKey>[]"};`,
+    `    for (final descriptor in scopes) {`,
+    `      if (descriptor['owned'] != true) continue;`,
+    `      final scope = descriptor['scope']! as String;`,
+    `      for (final record in records) {`,
+    `        final type = record['type']!;`,
+    `        final id = record['id']!;`,
+    `        final held = await bridge.nomosOwnedScopeKeys(scope, recordType: type, recordId: id);`,
+    `        for (final key in held) {`,
+    `          if (!keys.any((candidate) => candidate.scope == key.scope && candidate.epoch == key.epoch)) keys.add(key);`,
+    `        }`,
+    `      }`,
+    `    }`,
     `    return keys.isEmpty ? null : keys;`,
     `  }`,
     ``,
+    `  /// Multi-row owned reads are two local indexed reads: discover only authorized ciphertext rows,`,
+    `  /// derive those record keys, then repeat with decryption. No key or crypto concept reaches the app.`,
+    `  Future<List<Map<String, dynamic>>> _readWithOwnedKeys(`,
+    `    List<Map<String, Object?>> scopes,`,
+    `    Future<List<Map<String, dynamic>>> Function(List<NomosScopeKey>? keys) read,`,
+    `  ) async {`,
+    `    final first = await read(await _readKeys(scopes));`,
+    `    if (!scopes.any((scope) => scope['owned'] == true) || first.isEmpty) return first;`,
+    `    final records = first.map((row) => {`,
+    `      'type': (row['type'] ?? row['__type'] ?? '').toString(),`,
+    `      'id': (row['id'] ?? row['__id'] ?? '').toString(),`,
+    `    }).where((record) => record['type']!.isNotEmpty && record['id']!.isNotEmpty).toList();`,
+    `    return read(await _readKeys(scopes, records));`,
+    `  }`,
+    ``,
   ];
 }