@githolon/dsl 0.70.2 → 0.72.0

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,10 +191,20 @@ 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 ──
-  const dirs = (mod.directives as AnyDirective[]).filter(
+  // 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
+  // (below), NOT an `offerOutcome`; excluded here so a frontend dev can never call it as a local write.
+  const allDirs = (mod.directives as AnyDirective[]).filter(
     (d) => d && typeof d.id === "string" && typeof (d as { payloadSchema?: unknown }).payloadSchema === "object",
   );
+  const birthDirs = allDirs.filter((d) => (d as { birthsChild?: boolean }).birthsChild === true);
+  const dirs = allDirs.filter((d) => (d as { birthsChild?: boolean }).birthsChild !== true);
   for (const d of dirs) {
     const payloadClass = `${cap(d.id)}Payload`;
     const stamps = autoStampFields((d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema);
@@ -227,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);`,
         `  }`,
         ``,
       );
@@ -242,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);`,
         `  }`,
         ``,
       );
@@ -253,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());`,
         `  }`,
         ``,
       );
@@ -262,12 +280,85 @@ 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());`,
         ``,
       );
     }
   }
 
+  // ── `.births()` directives → typed CROSS-WORKSPACE birth (bridge.createWorkspace) ──
+  // Each births a CHILD WORKSPACE under `parent` via a signed governance offer routed by the PARENT'S
+  // law (POST /v2/workspaces/<parent>/<directiveId>) — never a same-workspace write. The declaring
+  // domain's key + directiveId + baked domainHash are all bound at codegen time, so a frontend dev
+  // never hand-writes the four raw strings this replaces (the co2 production bug).
+  for (const d of birthDirs) {
+    const payloadClass = `${cap(d.id)}Payload`;
+    const method = safeMethod(d.id);
+    const gate = (d as { requiresRelationGate?: { relation: string } }).requiresRelationGate;
+    methods.push(
+      `  /// 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,`,
+      `  }) 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: 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);`,
+      `  }`,
+      ``,
+    );
+  }
+
   // ── declared queries → one-shot + reactive ──
   for (const q of (mod.queries ?? []) as QueryDecl[]) {
     const model = readModelClassName(q.returns);
@@ -324,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 =>`,
@@ -345,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(
@@ -397,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
@@ -427,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)};`,
@@ -477,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 {`,
@@ -484,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.
@@ -536,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 {