@githolon/dsl 0.71.0 → 0.72.1

package/src/codegen_dart_client.ts

@@ -33,7 +33,14 @@ import type { Field } from "./fields.js";
 import type { Directive } from "./directive.js";
 import type { QueryDecl } from "./query.js";
 import type { DomainModule } from "./codegen_dart.js";
-import { cap, readModelClassName, dartRoleHelpers } from "./codegen_dart.js";
+import {
+  cap,
+  readModelClassName,
+  dartRoleHelpers,
+  registerDartNames,
+  concreteClassName,
+  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";
@@ -139,6 +146,7 @@ export interface DartBridgeClientOptions {
 
 /** Generate the `<name>.client.dart` async bridge client for one domain module. */
 export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClientOptions): string {
+  registerDartNames(mod.aggregates); // `.dartName` overrides for read-model class names in the client.
   const domain = mod.domain ?? mod.name;
   const className = dartClientClassName(domain);
   const hashConst = dartHashConstName(mod.name);
@@ -183,6 +191,11 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
 
   const methods: string[] = [];
 
+  // 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
+  // the structural interface (#72). `bind(session)` / `session.assertCompatible(...)` consume it.
+  const compatInterfaceHash = (opts.compat as { interfaceHash?: string } | undefined)?.interfaceHash;
+
   // ── directives → typed offer ──
   // A `.births()` directive (birthsChild === true) is NOT a same-workspace write — it is a signed
   // cross-workspace governance offer to a PARENT. It gets a typed `bridge.createWorkspace(...)` wrapper
@@ -232,7 +245,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
             ]
           : []),
         `    await _sealPayload(data, ${dartStr(d.id)}, seal);`,
-        `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
+        `    return _offer(${dartStr(d.id)}, data);`,
         `  }`,
         ``,
       );
@@ -247,7 +260,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         `    final data = payload.toPayloadJson();`,
         `    final now = DateTime.now().toUtc().toIso8601String();`,
         ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
-        `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
+        `    return _offer(${dartStr(d.id)}, data);`,
         `  }`,
         ``,
       );
@@ -258,7 +271,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
         gateDoc,
         `  Future<NomosOfferOutcome> ${method}(${payloadClass} payload) {`,
         gateGuard,
-        `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: actor, domainHash: domainHash);`,
+        `    return _offer(${dartStr(d.id)}, payload.toPayloadJson());`,
         `  }`,
         ``,
       );
@@ -267,7 +280,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) =>`,
-        `      bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: actor, domainHash: domainHash);`,
+        `      _offer(${dartStr(d.id)}, payload.toPayloadJson());`,
         ``,
       );
     }
@@ -281,31 +294,67 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   for (const d of birthDirs) {
     const payloadClass = `${cap(d.id)}Payload`;
     const method = safeMethod(d.id);
+    const gate = (d as { requiresRelationGate?: { relation: string } }).requiresRelationGate;
     methods.push(
-      `  /// Births a CHILD WORKSPACE named by \`${payloadClass}\` under [parent], via a SIGNED cross-workspace`,
-      `  /// governance offer to the parent's \`${domain}/${d.id}\` law (POST /v2/workspaces/<parent>/${d.id}) —`,
-      `  /// NOT a same-workspace write, which is why it takes [parent]/[actor] (the requesting principal, e.g.`,
-      `  /// \`user:<uid>\`) unlike the other generated methods. The declaring domain, directiveId, and law hash`,
-      `  /// are baked in. Returns the parent gateway's verdict; [authorSecret] defaults to the bridge's device key.`,
-      `  /// [actor] is a [NomosPrincipal] and [authorSecret] a [NomosDeviceSecret] — distinct types so the two`,
-      `  /// can never be transposed (a bare-string swap would silently misfire).`,
-      `  Future<Map<String, Object?>> ${method}({`,
-      `    required String parent,`,
-      `    required NomosPrincipal actor,`,
-      `    NomosDeviceSecret? authorSecret,`,
+      `  /// Births a CHILD WORKSPACE named by \`${payloadClass}\` — a \`.births()\` offer on THIS client's`,
+      `  /// session, whose workspace IS the parent (session_bound_clients.md ask 4: no loose parent string).`,
+      `  /// Returns the typed [NomosOfferOutcome]: \`outcome.born\` names the child, \`outcome.bornRefs\` are`,
+      `  /// followable — \`final child = await engine.follow(outcome.bornRefs.single);\` mounts it, typed`,
+      `  /// client construction is then \`await ChildClient.bind(child)\`. [actor] (a [NomosPrincipal])`,
+      `  /// overrides this client's own \`actor\` for the offer.`,
+      `  ///`,
+      `  /// COMPATIBILITY SHIM (one minor version): passing the deprecated [parent] with a workspace that is`,
+      `  /// NOT this session's routes the old SIGNED cross-workspace gateway relay`,
+      `  /// (POST /v2/workspaces/<parent>/${d.id}); its verdict rides \`outcome.gatewayVerdict\`. [authorSecret]/`,
+      `  /// [authToken] only apply on that legacy lane.`,
+      `  Future<NomosOfferOutcome> ${method}({`,
       `    required ${payloadClass} payload,`,
+      `    NomosPrincipal? actor,`,
+      `    @Deprecated('the birth parent IS the session workspace — bind this client to the PARENT session '`,
+      `        '(session_bound_clients.md ask 4); an explicit different parent rides the legacy gateway relay '`,
+      `        'one more minor version') String? parent,`,
+      `    NomosDeviceSecret? authorSecret,`,
       `    String? authToken,`,
-      `  }) =>`,
-      `      bridge.createWorkspace(`,
+      `  }) async {`,
+      `    final ws = _ws;`,
+      `    final explicitParent = parent;`,
+      `    if (explicitParent != null && explicitParent.isNotEmpty && explicitParent != ws) {`,
+      `      // LEGACY GATEWAY SHIM — the pre-session-bound cross-workspace relay, delegated unchanged.`,
+      `      if (actor == null) {`,
+      `        throw MissingOfferAuthority(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, requires: 'a requesting principal (actor) on the legacy parent-relay lane');`,
+      `      }`,
+      `      final verdict = await bridge.createWorkspace(`,
       `        domain: ${dartStr(domain)},`,
       `        directiveId: ${dartStr(d.id)},`,
       `        domainHash: domainHash,`,
-      `        parent: parent,`,
+      `        parent: explicitParent,`,
       `        actor: actor.wire,`,
       `        authorSecret: authorSecret?.wire,`,
       `        payload: payload.toPayloadJson(),`,
       `        authToken: authToken,`,
       `      );`,
+      `      return NomosOfferOutcome(`,
+      `          head: (verdict['head'] ?? '').toString(),`,
+      `          created: const [],`,
+      `          workspace: explicitParent,`,
+      `          gatewayVerdict: verdict);`,
+      `    }`,
+      `    if (ws.isEmpty) {`,
+      `      throw StateError(`,
+      `          '${method}: bind this client to the PARENT NomosSession (${className}.bind(session)) — '`,
+      `          'the birth parent IS the session workspace, never a loose string');`,
+      `    }`,
+      `    final effActor = actor?.wire ?? this.actor;`,
+      ...(gate !== undefined
+        ? [
+            `    if (effActor == null || effActor.trim().isEmpty) {`,
+            `      throw MissingOfferAuthority(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, requires: ${dartStr(gate.relation)});`,
+            `    }`,
+          ]
+        : []),
+      `    await _preflightOnce();`,
+      `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: payload.toPayloadJson(), actor: effActor, domainHash: domainHash);`,
+      `  }`,
       ``,
     );
   }
@@ -366,11 +415,64 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     );
   }
 
+  // ── 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).
+  const resolverBindings = (mod as { surfacedResolvers?: import("./surfaced_lint.js").SurfacedResolverBinding[] }).surfacedResolvers ?? [];
+  if (resolverBindings.length > 0) {
+    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();`,
+      ``,
+      `  /// 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());`,
+      ``,
+    );
+    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 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,`,
+        `      {Map<String, Object?> rest = const {}}) {`,
+        ...(gate !== undefined
+          ? [
+              `    if (actor == null || actor!.trim().isEmpty) {`,
+              `      throw MissingOfferAuthority(domain: ${dartStr(domain)}, directiveId: ${dartStr(b.directiveId)}, requires: ${dartStr(gate.relation)});`,
+              `    }`,
+            ]
+          : []),
+        `    final data = <String, Object?>{...rest, ${dartStr(b.idPayloadField)}: conflict.aggregateId, ${dartStr(b.valuePayloadField)}: chosen};`,
+        `    return _offer(${dartStr(b.directiveId)}, data);`,
+        `  }`,
+        ``,
+      );
+    }
+  }
+
   // ── per-aggregate by-id read/watch + type-index list ──
   for (const agg of mod.aggregates) {
     const model = readModelClassName(agg.id);
-    const lc = lcFirst(camel(agg.id));
-    const Cap = cap(camel(agg.id));
+    // Accessor method-name stem honours `.dartName` (e.g. `EstateSite` + .dartName("Site") → `siteById`,
+    // `watchSiteById`, `listSites`) so the whole Dart surface renames consistently.
+    const name = concreteClassName(agg.id);
+    const lc = lcFirst(camel(name));
+    const Cap = cap(camel(name));
     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 =>`,
@@ -387,6 +489,67 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     );
   }
 
+  // ── REF-TRAVERSAL ACCESSORS (dart_codegen_parity.md P2 — ref ergonomics) ──
+  // For every SAME-WORKSPACE `t.ref(Target)` field whose target aggregate is ALSO in THIS domain module
+  // (so its by-id accessor is right here on this SAME client class), emit a companion extension method
+  // that resolves the stored ref id to the actual target row — reusing the EXISTING `<target>ById`
+  // by-id accessor above (no second read path, no new bridge op). SCOPE (deliberately narrow):
+  //   - `t.foreignRef` fields are NOT covered — a foreign ref crosses workspaces (its own locator +
+  //     attested-read trust plumbing, a different lane entirely; `ForeignRef<T>` stays as-is).
+  //   - a same-workspace ref field whose target aggregate is a CROSS-DOMAIN reference (not present in
+  //     `mod.aggregates`) is skipped too — its by-id accessor lives on a DIFFERENT domain's generated
+  //     client, unreachable from an extension scoped to this file.
+  // A domain with no resolvable ref field emits none of this (byte-identical to before this existed).
+  const refExtensions: string[] = [];
+  for (const agg of mod.aggregates) {
+    const model = readModelClassName(agg.id);
+    const refFields = Object.entries(agg.fields).filter(([, f]) => {
+      const field = f as Field;
+      return field.kind === "ref" && field.foreignRef === undefined && field.refAggregateId !== undefined;
+    }) as [string, Field][];
+    const targetableFields = refFields.filter(([, f]) => aggById.has(f.refAggregateId!));
+    if (targetableFields.length === 0) continue;
+    const lines: string[] = [
+      `/// Ref-traversal accessors for [${model}] (dart_codegen_parity.md P2) — resolve a stored ref id`,
+      `/// to the actual target row via the SAME by-id read lane already exposed above.`,
+      `extension ${model}Refs on ${model} {`,
+    ];
+    for (const [fieldName, f] of targetableFields) {
+      const targetType = f.refAggregateId!;
+      const targetModel = readModelClassName(targetType);
+      const targetConcrete = concreteClassName(targetType);
+      const targetLc = lcFirst(camel(targetConcrete));
+      const byIdMethod = safeMethod(`${targetLc}ById`);
+      const member = dartMemberName(fieldName);
+      // `siteId` → `site` (the common `<name>Id` ref-field convention); anything else gets a `Ref`
+      // suffix so the resolver method never collides with the stored field's own getter.
+      const methodStem = member.length > 2 && member.endsWith("Id") ? member.slice(0, -2) : `${member}Ref`;
+      const method = safeMethod(methodStem);
+      // NULLABILITY: the read-model member's Dart type follows the PROJECTION's own nullability, not
+      // the DSL schema's `.optional()` — a partial fold decodes every scalar `null` when absent
+      // (`emitReadModel`'s own doc: "PARTIAL folds"), so the member is nullable UNLESS the field is
+      // `.fromBirth()` (birth-presence law — the ONE case the projection types non-null).
+      const memberNullable = f.isFromBirth !== true;
+      lines.push(
+        `  /// Resolve \`${fieldName}\` (${agg.id}.${fieldName} -> ${targetType}) by dispatching to`,
+        `  /// [${className}.${byIdMethod}] — the existing by-id read lane, never a second one.`,
+        `  Future<${targetModel}?> ${method}(${className} client) async {`,
+        ...(memberNullable
+          ? [
+              `    final id = ${member};`,
+              `    if (id == null) return null;`,
+              `    final rows = await client.${byIdMethod}(id.value);`,
+            ]
+          : [`    final rows = await client.${byIdMethod}(${member}.value);`]),
+        `    return rows.isEmpty ? null : rows.first;`,
+        `  }`,
+        ``,
+      );
+    }
+    lines.push(`}`);
+    refExtensions.push(lines.join("\n"));
+  }
+
   // ── activity feed → typed reactive + one-shot (declared `.activity(...)`) ──
   if (opts.emitActivity === true) {
     methods.push(
@@ -439,17 +602,20 @@ 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. Construct with a connected bridge:`,
+    `// not edit. SESSION-BOUND (architecture/session_bound_clients.md): construct with a NomosSession —`,
+    `// one session, one workspace, one domain interface, one actor context:`,
     `//`,
     // 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).
-    `// ignore_for_file: avoid_dynamic_calls, unnecessary_this, prefer_const_constructors, unused_import, type_annotate_public_apis, always_specify_types`,
+    // (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 bridge = NomosBridge(transport);   // transport = your WebViewTransport`,
-    `//   await bridge.ready;`,
-    `//   await bridge.connect(cloud: cloud, workspace: ws, clientId: deviceId);`,
-    `//   final app = ${className}(bridge);`,
+    `//   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 */);`,
     ``,
     // `dart:convert` is needed ONLY for the interface block's `jsonDecode` — the offer lane no longer encodes
@@ -469,7 +635,7 @@ 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, NomosSession, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion, NomosCompat, NomosCompatMember, NomosOfferOutcome, NomosCreated, NomosRef${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, NomosClientInterface, DomainClientSessionMismatch, DomainNotInstalledForSession, SessionMismatchCause${encPresent ? ", 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)};`,
@@ -519,6 +685,29 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       : []),
     `  ${className}(this.bridge, {this.domainHash = ${hashConst}, this.actor${encPresent ? ", 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`,
+    `  /// structural interface (#72). Consumed by [bind] and by \`session.assertCompatible(${className}.interface)\`.`,
+    `  static const NomosClientInterface interface = NomosClientInterface(`,
+    `    domain: ${dartStr(domain)},`,
+    `    expectedDomainHash: ${hashConst},`,
+    ...(compatInterfaceHash !== undefined ? [`    expectedInterfaceHash: ${dartStr(compatInterfaceHash)},`] : []),
+    ...(opts.interface !== undefined ? [`    interfaceJson: ${interfaceConstNameDart(mod.name)},`] : []),
+    ...(opts.compat !== undefined ? [`    compatJson: ${compatConstNameDart(mod.name)},`] : []),
+    `  );`,
+    ``,
+    `  /// THE SESSION-BOUND CONSTRUCTION PATH (session_bound_clients.md asks 2/5): bind this client to`,
+    `  /// [session] with an ASYNC PREFLIGHT — the session's workspace must be reachable, hold the`,
+    `  /// \`${domain}\` domain, and serve a structurally compatible interface (#72 shape-compat, the ONE`,
+    `  /// compatibility notion). An incompatible session throws [DomainClientSessionMismatch]`,
+    `  /// 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 {`,
+    `    await session.assertCompatible(interface);`,
+    `    return ${className}(session, actor: actor${encPresent ? ", keyStore: keyStore" : ""}).._preflighted = true;`,
+    `  }`,
+    ``,
     `  /// The session workspace this client is bound to (from the [NomosSession] handle, when constructed with`,
     `  /// one) — the \`workspace\` of every read row's canonical [NomosRef]. '' on a bare (non-session) bridge.`,
     `  String get _ws {`,
@@ -526,6 +715,31 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `    return b is NomosSession ? b.workspace : '';`,
     `  }`,
     ``,
+    `  /// The [NomosSession] this client dispatches through, when session-bound (the blessed shape);`,
+    `  /// null on a bare (non-session) bridge. Inspectable context: \`client.session?.workspace\`.`,
+    `  NomosSession? get session {`,
+    `    final b = bridge;`,
+    `    return b is NomosSession ? b : null;`,
+    `  }`,
+    ``,
+    `  // LAZY PREFLIGHT (the can't-await constructor path): the first dispatch runs the same`,
+    `  // assertCompatible check bind() runs eagerly. Only when session-bound; a bare bridge keeps the`,
+    `  // pre-session behavior (the kernel gate remains the fail-closed floor either way).`,
+    `  bool _preflighted = false;`,
+    `  Future<void> _preflightOnce() async {`,
+    `    if (_preflighted) return;`,
+    `    _preflighted = true;`,
+    `    final b = bridge;`,
+    `    if (b is NomosSession) await b.assertCompatible(interface);`,
+    `  }`,
+    ``,
+    `  /// 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) async {`,
+    `    await _preflightOnce();`,
+    `    return bridge.offerOutcome(domain: ${dartStr(domain)}, directiveId: directiveId, payload: payload, actor: actor, domainHash: domainHash);`,
+    `  }`,
+    ``,
     ...(encPresent ? dartEncClassMembers(encMap!) : []),
     // 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.
@@ -578,6 +792,9 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     ...methods,
     `}`,
     ``,
+    ...(refExtensions.length > 0
+      ? [`// ---- ref-traversal accessors (dart_codegen_parity.md P2) ----`, refExtensions.join("\n\n"), ``]
+      : []),
     ...(roleHelpers !== ""
       ? [
           `// ---- role policy (UI hints — the KERNEL GATE is the authority) ----`,

package/src/codegen_openapi.ts

@@ -192,6 +192,26 @@ export function generateOpenApiFragment(
       { name: "bbox", in: "query", required: true, schema: { type: "string" }, description: "minX,minY,maxX,maxY" },
     ]);
   }
+  // THE PENDING-CONFLICTS READ (surfaced_merge_conflict.md — the DX layer): a domain declaring
+  // ≥1 `.merge(Surfaced(...))` field emits the reserved, workspace-wide `nomosPendingConflicts`
+  // read — the maintained "decisions needed" index (rows: {aggregateType, aggregateId, field,
+  // observations}). DECLARED BY THE LAW ITSELF (the era-key idiom, like nomosInvariantGate):
+  // emitted iff a Surfaced field is declared, so a Surfaced-free domain's fragment — and thus
+  // its openapi/package bytes — is byte-identical to before this existed. No params: the read
+  // is workspace-wide (the reserved id IS the selector).
+  const declaresSurfaced = module.aggregates.some((a) =>
+    Object.values((a.fields ?? {}) as Record<string, Field>).some(
+      (f) => (f.driver as { kind?: string } | undefined)?.kind === "Surfaced",
+    ),
+  );
+  if (declaresSurfaced) {
+    getRead(
+      "nomosPendingConflicts",
+      "pending Surfaced merge conflicts across the workspace (maintained; derived, not drained)",
+      { kind: "pendingConflicts" },
+      [],
+    );
+  }
 
   return {
     openapi: "3.1.0",

package/src/codegen_proof.ts

@@ -778,7 +778,11 @@ function probePlanOpsWithPayload(
   return ops;
 }
 
-function probePlanOps(
+/** PUBLIC (dart_codegen_parity.md P2 / idof_lint.ts): the same plan-probe primitive the proof generator's
+ *  own discovery legs use — run a directive's plan under a synthesized sample payload + deterministic probe
+ *  ports and return the emitted field ops alongside the sample that produced them. Reused (not reinvented)
+ *  by the payload-ref idOf lint to match an op's value back to the payload field that fed it. */
+export function probePlanOps(
   dir: Directive<unknown>,
   where: string,
 ): { ops: FieldOp[]; synth: SynthesizedPayload; probePayload: Record<string, unknown> } | undefined {

package/src/codegen_ts.ts

@@ -470,7 +470,16 @@ function tsTypeOfPayload(
 // ── DSL Field → read-model TS type (the projection's decode surface) ──────────────
 
 function tsTypeOfField(field: Field): string {
-  const base = tsBaseTypeOfField(field);
+  let base = tsBaseTypeOfField(field);
+  // SURFACED MERGE CONFLICTS (architecture/surfaced_merge_conflict.md): the FIRST driver that
+  // changes a field's generated type. A `.merge(Surfaced(...))` field reads as the plain scalar
+  // once resolved, or the `{__surfaced:{pending:[...]}}` envelope while genuinely concurrent
+  // writes await a human pick — typed as the discriminated union `SurfacedValue<T>` (emitted
+  // once per file that needs it). The client does NO transformation; this types the exact
+  // read-collapse JSON.
+  if ((field.driver as { kind?: string } | undefined)?.kind === "Surfaced") {
+    base = `SurfacedValue<${base}>`;
+  }
   // NULL SEMANTICS (null_semantics.md): a `nullable`/`explicit-empty` field ADMITS a domain `null`,
   // so its read-model type carries the `| null` arm (distinct from the `?` partial-fold absence a
   // non-null-admitting field gets). A `forbid` json/VO field NEVER gets the null arm.
@@ -792,6 +801,15 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   const hasBirths = modules.some((m) =>
     (m.directives as Directive<unknown>[]).some((d) => (d as { birthsChild?: boolean })?.birthsChild === true),
   );
+  // SURFACED MERGE CONFLICTS: a package declaring ≥1 `.merge(Surfaced(...))` field emits the
+  // `SurfacedValue<T>` union + guard (below). Surfaced-free packages emit nothing (byte-identical).
+  const hasSurfaced = modules.some((m) =>
+    m.aggregates.some((a) =>
+      Object.values(a.fields as Record<string, Field>).some(
+        (f) => (f.driver as { kind?: string } | undefined)?.kind === "Surfaced",
+      ),
+    ),
+  );
   // ACTIVITY FEED (architecture/activity_descriptors.md): the package's declared `.activity(...)` descriptors.
   // Empty ⇒ NOTHING activity-related emits (byte-identical to a pre-activity compile).
   const activityEntries = collectActivityDescriptors(modules);
@@ -950,6 +968,45 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     ` *  at runtime and the recursive edge is typed here). Named recursion TS resolves fine. */`,
     `export type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };`,
     ``,
+    // SURFACED MERGE CONFLICTS (architecture/surfaced_merge_conflict.md): the read-collapse union for a
+    // `.merge(Surfaced(...))` field — the plain scalar once resolved, or the pending envelope while
+    // genuinely concurrent writes await a human pick. Emitted ONLY when the package declares one.
+    ...(hasSurfaced
+      ? [
+          `/** One competing observation on a PENDING Surfaced field. \`author\` is the writer principal —`,
+          ` *  nullable (an observation folded where no intent context existed carries none). The author`,
+          ` *  JSON key is pinned in ONE place: this property name (kernel b215430d — exactly "author"). */`,
+          `export interface SurfacedObservation<T> {`,
+          `  value: T;`,
+          `  occurredAt: { physical: number; logical: number; replica: number };`,
+          `  author?: string | null;`,
+          `}`,
+          `/** The PENDING read-collapse of a \`.merge(Surfaced(...))\` field: the kernel retained BOTH sides`,
+          ` *  of a genuinely concurrent write (ALWAYS 2+ observations — a single-observation set collapses`,
+          ` *  to the plain scalar; bounded, cap 8) instead of silently picking a winner. Resolve`,
+          ` *  it with an ORDINARY next write (a \`.mutates()\` directive that set()s the field) — the field`,
+          ` *  then reads as the plain scalar again, indistinguishable from any other field. */`,
+          `export interface SurfacedPending<T> { __surfaced: { pending: SurfacedObservation<T>[] } }`,
+          `/** A Surfaced field's read value: the resolved scalar, or the pending envelope under conflict. */`,
+          `export type SurfacedValue<T> = T | SurfacedPending<T>;`,
+          `/** True iff \`v\` is the pending-conflict envelope (narrows to [SurfacedPending]). */`,
+          `export function isSurfacedPending<T>(v: SurfacedValue<T> | null | undefined): v is SurfacedPending<T> {`,
+          `  return typeof v === "object" && v !== null && "__surfaced" in (v as Record<string, unknown>);`,
+          `}`,
+          `/** ONE row of the workspace-wide \`pendingConflicts()\` read (reserved id \`nomosPendingConflicts\`):`,
+          ` *  a (aggregate, field) whose folded state awaits a human pick. MAINTAINED like counts/sums`,
+          ` *  (fold-time, O(pending) to read) and DERIVED, NOT DRAINED — a resolution write folding in removes`,
+          ` *  the row by derivation. The workspace-wide surface is HETEROGENEOUS, so each observation's`,
+          ` *  \`value\` is \`unknown\` here — the per-field typed seam stays on the read models (\`SurfacedValue<T>\`). */`,
+          `export interface PendingConflictRow {`,
+          `  aggregateType: string;`,
+          `  aggregateId: string;`,
+          `  field: string;`,
+          `  observations: SurfacedObservation<unknown>[];`,
+          `}`,
+          ``,
+        ]
+      : []),
     `/** The holon surface this client binds to (structurally satisfied by @githolon/client). */`,
     `export interface NomosHolon {`,
     `  /** THE ONE ENCODER offer (the single v2-envelope codec lives in @githolon/client \`encodeIntentOfferBytes\`):`,
@@ -990,6 +1047,13 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           `  queryById(aggregateId: string): Promise<unknown>;`,
         ]),
     `  watchById(aggregateId: string, cb: (rows: unknown) => void, opts?: { intervalMs?: number }): () => void;`,
+    ...(hasSurfaced
+      ? [
+          `  /** The workspace-wide pending Surfaced-conflict read (reserved id \`nomosPendingConflicts\`).`,
+          `   *  OPTIONAL member: structural binding tolerates a pre-Surfaced holon (the accessor throws at call). */`,
+          `  pendingConflicts?(): Promise<PendingConflictRow[]>;`,
+        ]
+      : []),
     `  /** Declared-count / declared-sum O(1) reads (maintained by the read engine). */`,
     `  count(countId: string, groupKey?: string): Promise<number>;`,
   `  /** THE SPATIAL READ (R*Tree probe): rows intersecting the bbox — same row shape as query().`,
@@ -1718,10 +1782,13 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       for (const dir of Object.values(dm.directives)) for (const f of Object.values(dir)) s.add(f.scope);
       return [...s].sort();
     })();
+    // directiveId → its emitted payload TYPE name (the surfaced `resolve…` helpers reference it).
+    const dirPayloadNames = new Map<string, string>();
     for (const d of dirs) {
       let payloadName = `${cap(d.id)}Payload`;
       if (usedPayloadNames.has(payloadName)) payloadName = `${cap(camel(domain))}${cap(d.id)}Payload`;
       usedPayloadNames.add(payloadName);
+      dirPayloadNames.set(d.id, payloadName);
       const schema = (d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema;
       const stamps = autoStampFields(schema);
       const mint = mintPlan?.get(d.id);
@@ -1875,6 +1942,51 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           : `    ${lcFirst(camel(s.id))}: () => holon.sum(${JSON.stringify(s.id)}),`,
       );
     }
+
+    // ── SURFACED CONFLICT DX (surfaced_merge_conflict.md): the workspace-wide pendingConflicts
+    // accessor + one typed `resolve…` helper per designated `.resolves()` directive. Emitted iff
+    // this domain declares a Surfaced field (byte-identical otherwise — the era rule).
+    const resolverBindings = (mod as { surfacedResolvers?: import("./surfaced_lint.js").SurfacedResolverBinding[] }).surfacedResolvers ?? [];
+    if (resolverBindings.length > 0) {
+      methods.push(
+        `    /** PENDING SURFACED CONFLICTS across the workspace — the maintained "decisions needed" read`,
+        `     *  (reserved id \`nomosPendingConflicts\`; derived, not drained: a resolution write removes its`,
+        `     *  row by derivation). Pair each row with its typed \`resolve…\` helper below. */`,
+        `    pendingConflicts: () => {`,
+        `      if (!holon.pendingConflicts) throw new Error("this holon predates pendingConflicts reads — upgrade @githolon/client");`,
+        `      return holon.pendingConflicts();`,
+        `    },`,
+        `    /** Watch the pending Surfaced conflicts (local reactive read; returns stop()). */`,
+        `    watchPendingConflicts: (cb: (rows: PendingConflictRow[]) => void, opts?: { intervalMs?: number }) => {`,
+        `      if (!holon.pendingConflicts) throw new Error("this holon predates pendingConflicts reads — upgrade @githolon/client");`,
+        `      let stopped = false;`,
+        `      let last = "";`,
+        `      const tick = async () => { try { const rows = await holon.pendingConflicts!(); const j = JSON.stringify(rows); if (!stopped && j !== last) { last = j; cb(rows); } } catch { /* projection catching up */ } };`,
+        `      void tick();`,
+        `      const t = setInterval(tick, opts?.intervalMs ?? 1000);`,
+        `      return () => { stopped = true; clearInterval(t); };`,
+        `    },`,
+      );
+      for (const b of resolverBindings) {
+        if (b.valuePayloadField === undefined) continue; // probe couldn't bind — dispatch the directive directly.
+        const payloadName = dirPayloadNames.get(b.directiveId);
+        if (payloadName === undefined) continue;
+        const helper = `resolve${cap(camel(b.aggregateId))}${cap(camel(b.field))}`;
+        const idField = b.idPayloadField;
+        const bound = [b.valuePayloadField, ...(idField !== undefined ? [idField] : [])];
+        const restType = `Omit<${payloadName}, ${bound.map((f) => JSON.stringify(f)).join(" | ")}>`;
+        const conflictParam = idField !== undefined ? `conflict: string | PendingConflictRow, ` : ``;
+        const payloadExpr = `{ ...(rest ?? {}), ${idField !== undefined ? `${JSON.stringify(idField)}: typeof conflict === "string" ? conflict : conflict.aggregateId, ` : ``}${JSON.stringify(b.valuePayloadField)}: chosen } as ${payloadName}`;
+        methods.push(
+          `    /** RESOLVE a pending conflict on \`${b.aggregateId}.${b.field}\` by dispatching the DESIGNATED`,
+          `     *  resolver \`${b.directiveId}\` with the chosen value${idField !== undefined ? ` (the conflict row — or the bare aggregate id — names the instance)` : ""}.`,
+          `     *  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. */`,
+          `    ${helper}: (${conflictParam}chosen: ${payloadName}[${JSON.stringify(b.valuePayloadField)}], rest?: ${restType}): Promise<NomosOutcome> =>`,
+          `      _outcome(holon.workspace, holon.offerDirective(${JSON.stringify(domain)}, ${JSON.stringify(b.directiveId)}, ${payloadExpr}, { domainHash, actor, returnCreated: true }) as Promise<string | { head: string; created?: { type: string; id: string }[] }>),`,
+        );
+      }
+    }
     for (const agg of mod.aggregates as AggregateHandle[]) {
       const aScopes = readScopesFor(agg.id);
       methods.push(