@githolon/dsl 0.70.2 → 0.72.0

package/dart_types/lib/src/principal.dart

@@ -0,0 +1,56 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/// BRANDED IDENTITY TYPES for the generated cross-workspace birth methods.
+///
+/// A `.births()` directive's generated wrapper takes an `actor` (WHO births) and an optional
+/// `authorSecret` (the signing key). Both were previously bare strings — two adjacent same-shaped
+/// params that a caller can transpose with NO compiler error and a silent runtime failure (the same
+/// bug class as a raw `domain`/`directiveId` swap). These wrappers make the transposition a type
+/// error: `NomosPrincipal` and `NomosDeviceSecret` are distinct types, so passing one where the other
+/// belongs won't compile. The generated method unwraps `.wire` to call the (unchanged) runtime
+/// primitive `NomosBridge.createWorkspace(actor: String, authorSecret: String?, …)`.
+
+/// A verified principal identity (`user:<uid>` on the wire). Construct with [NomosPrincipal.user]
+/// from a bare uid, or [NomosPrincipal.parse] from a `user:<uid>` wire string.
+class NomosPrincipal {
+  /// The bare uid (no `user:` prefix).
+  final String uid;
+  const NomosPrincipal._(this.uid);
+
+  /// From a bare uid (e.g. an auth-provider user id) — the common case.
+  factory NomosPrincipal.user(String uid) => NomosPrincipal._(uid);
+
+  /// From a `user:<uid>` wire string — throws [ArgumentError] on any other shape.
+  factory NomosPrincipal.parse(String wire) {
+    if (!wire.startsWith('user:')) {
+      throw ArgumentError('NomosPrincipal.parse: expected "user:<uid>", got "$wire"');
+    }
+    return NomosPrincipal._(wire.substring(5));
+  }
+
+  /// The wire form the kernel seals as the captured principal: `user:<uid>`.
+  String get wire => 'user:$uid';
+
+  @override
+  bool operator ==(Object other) => other is NomosPrincipal && other.uid == uid;
+  @override
+  int get hashCode => uid.hashCode;
+  @override
+  String toString() => wire;
+}
+
+/// A device signing secret (base64). A distinct type from [NomosPrincipal] so it can't be swapped
+/// with `actor`; its [toString] NEVER leaks the secret (redacted), so it is safe in logs/errors.
+class NomosDeviceSecret {
+  final String _base64;
+  const NomosDeviceSecret(this._base64);
+
+  /// The base64 wire form handed to the (unchanged) runtime primitive.
+  String get wire => _base64;
+
+  @override
+  String toString() => 'NomosDeviceSecret(***)';
+}

package/dart_types/lib/src/surfaced.dart

@@ -0,0 +1,208 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/// SURFACED MERGE CONFLICTS (architecture/surfaced_merge_conflict.md) — the
+/// user-resolvable third merge posture. A field declared `.merge(Surfaced(inner))`
+/// reads as the PLAIN scalar once resolved, or — while genuinely concurrent writes
+/// await a human pick — as the pending envelope
+/// `{"__surfaced":{"pending":[{value, author, occurredAt}, ...]}}` (ALWAYS 2+
+/// competing observations — a single-observation set read-collapses to the plain
+/// scalar; bounded, cap 8).
+///
+/// The generated read models type such a field as `SurfacedValue<T>?`; app code
+/// branches on [SurfacedValue.isPending] (or the generated `has…PendingConflict`
+/// accessor) and resolves the conflict with an ORDINARY next write — a domain
+/// directive that `set()`s the field. No transformation happens here: this types
+/// the kernel's exact read-collapse JSON.
+library;
+
+import 'wire.dart' show Hlc;
+
+/// The pending-envelope discriminator key in the read-collapse JSON.
+const String surfacedEnvelopeKey = '__surfaced';
+
+/// The JSON key of an observation's writer principal — pinned in ONE place
+/// (kernel b215430d confirmed it as exactly `author`, a nullable uid string).
+const String surfacedAuthorKey = 'author';
+
+/// One competing observation retained on a pending Surfaced field: the written
+/// [value], the HLC stamp it was written at, and the writer principal ([author],
+/// NULLABLE — an observation folded where no intent context existed carries none).
+class SurfacedObservation<T> {
+  final T value;
+  final Hlc occurredAt;
+  final String? author;
+
+  const SurfacedObservation({
+    required this.value,
+    required this.occurredAt,
+    this.author,
+  });
+
+  /// Decode one `{value, occurredAt, author?}` entry; [decodeT] turns the raw
+  /// JSON `value` leaf into the field's typed Dart value.
+  factory SurfacedObservation.fromJson(
+    Map<String, dynamic> json,
+    T Function(dynamic) decodeT,
+  ) =>
+      SurfacedObservation(
+        value: decodeT(json['value']),
+        occurredAt: Hlc.fromJson(
+            (json['occurredAt'] as Map).cast<String, dynamic>()),
+        author: json[surfacedAuthorKey] as String?,
+      );
+
+  @override
+  bool operator ==(Object other) =>
+      other is SurfacedObservation<T> &&
+      other.value == value &&
+      other.occurredAt == occurredAt &&
+      other.author == author;
+
+  @override
+  int get hashCode => Object.hash(value, occurredAt, author);
+
+  @override
+  String toString() =>
+      'SurfacedObservation(value: $value, occurredAt: $occurredAt, author: $author)';
+}
+
+/// A Surfaced field's read value: [SurfacedResolved] (the plain scalar — the
+/// steady state, byte-identical to any other field) or [SurfacedPending] (the
+/// kernel retained BOTH sides of a genuinely concurrent write for a human pick).
+sealed class SurfacedValue<T> {
+  const SurfacedValue();
+
+  /// Decode a raw read-collapse leaf: the `{"__surfaced":{...}}` envelope becomes
+  /// [SurfacedPending]; any other value is the resolved scalar (via [decodeT]).
+  factory SurfacedValue.fromJson(dynamic json, T Function(dynamic) decodeT) {
+    if (json is Map && json.containsKey(surfacedEnvelopeKey)) {
+      final env =
+          (json[surfacedEnvelopeKey] as Map).cast<String, dynamic>();
+      final rawPending = (env['pending'] as List? ?? const []);
+      return SurfacedPending<T>(List.unmodifiable(rawPending.map((o) =>
+          SurfacedObservation<T>.fromJson(
+              (o as Map).cast<String, dynamic>(), decodeT))));
+    }
+    return SurfacedResolved<T>(decodeT(json));
+  }
+
+  /// Tolerant field decode off a flat projection `data` map: absent/null ⇒ null
+  /// (the PARTIAL-FOLD doctrine — a freshly-folded aggregate may not carry the
+  /// field yet); present ⇒ [SurfacedValue.fromJson].
+  static SurfacedValue<T>? decode<T>(
+    Map<String, dynamic> data,
+    String key,
+    T Function(dynamic) decodeT,
+  ) {
+    final raw = data[key];
+    if (raw == null) return null;
+    return SurfacedValue<T>.fromJson(raw, decodeT);
+  }
+
+  /// True while the field awaits a resolution (competing observations retained).
+  bool get isPending => this is SurfacedPending<T>;
+
+  /// The resolved scalar, or null while pending.
+  T? get valueOrNull {
+    final self = this;
+    return self is SurfacedResolved<T> ? self.value : null;
+  }
+
+  /// The competing observations while pending; const empty once resolved.
+  List<SurfacedObservation<T>> get pending {
+    final self = this;
+    return self is SurfacedPending<T>
+        ? self.observations
+        : const [];
+  }
+}
+
+/// 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, never a consumer acking it. The workspace-wide surface is
+/// HETEROGENEOUS, so each observation's `value` is `Object?` here — the
+/// per-field typed seam stays on the read models ([SurfacedValue]).
+class PendingConflictRow {
+  /// The aggregate's logical type (e.g. `Doc`).
+  final String aggregateType;
+
+  /// The conflicted instance's aggregate id.
+  final String aggregateId;
+
+  /// The Surfaced field awaiting a resolution.
+  final String field;
+
+  /// The competing observations (2+, bounded) — value/author/occurredAt.
+  final List<SurfacedObservation<Object?>> observations;
+
+  const PendingConflictRow({
+    required this.aggregateType,
+    required this.aggregateId,
+    required this.field,
+    required this.observations,
+  });
+
+  factory PendingConflictRow.fromJson(Map<String, dynamic> json) =>
+      PendingConflictRow(
+        aggregateType: json['aggregateType'] as String,
+        aggregateId: json['aggregateId'] as String,
+        field: json['field'] as String,
+        observations: List.unmodifiable(
+            (json['observations'] as List? ?? const []).map((o) =>
+                SurfacedObservation<Object?>.fromJson(
+                    (o as Map).cast<String, dynamic>(), (v) => v))),
+      );
+
+  @override
+  String toString() =>
+      'PendingConflictRow($aggregateType:$aggregateId.$field, ${observations.length} observations)';
+}
+
+/// The steady state: the field folded to one value (never conflicted, or a
+/// resolution write superseded the pending set).
+final class SurfacedResolved<T> extends SurfacedValue<T> {
+  final T value;
+  const SurfacedResolved(this.value);
+
+  @override
+  bool operator ==(Object other) =>
+      other is SurfacedResolved<T> && other.value == value;
+
+  @override
+  int get hashCode => Object.hash('SurfacedResolved', value);
+
+  @override
+  String toString() => 'SurfacedResolved($value)';
+}
+
+/// The conflict state: the bounded competing observations (ALWAYS 2+ — a
+/// single-observation set read-collapses to the plain scalar; cap 8,
+/// deterministically pruned by the kernel). Show them; let a human pick; write
+/// the pick back with an ordinary domain directive.
+final class SurfacedPending<T> extends SurfacedValue<T> {
+  final List<SurfacedObservation<T>> observations;
+  const SurfacedPending(this.observations);
+
+  @override
+  bool operator ==(Object other) {
+    if (other is! SurfacedPending<T>) return false;
+    if (other.observations.length != observations.length) return false;
+    for (var i = 0; i < observations.length; i++) {
+      if (other.observations[i] != observations[i]) return false;
+    }
+    return true;
+  }
+
+  @override
+  int get hashCode =>
+      Object.hashAll(['SurfacedPending', ...observations]);
+
+  @override
+  String toString() => 'SurfacedPending($observations)';
+}

package/dart_types/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Pure kernel wire/data types for Nomos Dart frontends — no transport, no bridge,
   no runtime. The hand-written serde-JSON-compatible types plus the offer codec,
   reactive read engine, schema validation, and data-only error/trace types.
-version: 0.1.4
+version: 0.2.0
 
 environment:
   sdk: ^3.5.0

package/dart_types/test/surfaced_test.dart

@@ -0,0 +1,69 @@
+import 'package:nomos_types/nomos_types.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('SurfacedValue', () {
+    test('a plain scalar decodes RESOLVED', () {
+      final v = SurfacedValue<String>.fromJson('hello', (x) => x as String);
+      expect(v, isA<SurfacedResolved<String>>());
+      expect(v.isPending, isFalse);
+      expect(v.valueOrNull, 'hello');
+      expect(v.pending, isEmpty);
+    });
+
+    test('the __surfaced envelope decodes PENDING (value + occurredAt + nullable author)', () {
+      final v = SurfacedValue<String>.fromJson({
+        '__surfaced': {
+          'pending': [
+            {
+              'value': 'a',
+              'occurredAt': {'physical': 10, 'logical': 1, 'replica': 7},
+              'author': 'user:ada',
+            },
+            {
+              'value': 'b',
+              'occurredAt': {'physical': 11, 'logical': 0, 'replica': 9},
+              // no author — an observation folded without intent context.
+            },
+          ],
+        },
+      }, (x) => x as String);
+      expect(v, isA<SurfacedPending<String>>());
+      expect(v.isPending, isTrue);
+      expect(v.valueOrNull, isNull);
+      expect(v.pending, hasLength(2));
+      expect(v.pending[0].value, 'a');
+      expect(v.pending[0].author, 'user:ada');
+      expect(v.pending[0].occurredAt, const Hlc(physical: 10, logical: 1, replica: 7));
+      expect(v.pending[1].value, 'b');
+      expect(v.pending[1].author, isNull);
+    });
+
+    test('decode() off a flat data map: absent/null => null (partial-fold doctrine)', () {
+      expect(SurfacedValue.decode<String>({}, 'title', (x) => x as String), isNull);
+      expect(SurfacedValue.decode<String>({'title': null}, 'title', (x) => x as String), isNull);
+      final v = SurfacedValue.decode<String>({'title': 't'}, 'title', (x) => x as String);
+      expect(v, const SurfacedResolved<String>('t'));
+    });
+
+    test('value equality holds on both arms', () {
+      expect(const SurfacedResolved<String>('x'), const SurfacedResolved<String>('x'));
+      final p1 = SurfacedValue<String>.fromJson({
+        '__surfaced': {
+          'pending': [
+            {'value': 'a', 'occurredAt': {'physical': 1, 'logical': 0, 'replica': 1}},
+          ],
+        },
+      }, (x) => x as String);
+      final p2 = SurfacedValue<String>.fromJson({
+        '__surfaced': {
+          'pending': [
+            {'value': 'a', 'occurredAt': {'physical': 1, 'logical': 0, 'replica': 1}},
+          ],
+        },
+      }, (x) => x as String);
+      expect(p1, p2);
+      expect(p1.hashCode, p2.hashCode);
+    });
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.70.2",
+  "version": "0.72.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/aggregate.ts

@@ -14,6 +14,7 @@
  * string: a typo'd handle is a compile error.
  */
 import type { Field } from "./fields.js";
+import { admitsNull } from "./fields.js";
 import { satisfiesContract, type ContractHandle } from "./contract.js";
 
 /**
@@ -160,6 +161,14 @@ export interface AggregateHandle<
    *  checked). Codegen marks the aggregate as implementing them so cross-domain refs can target the CONTRACT
    *  instead of this concrete type. Additive metadata (not hashed law). OMITTED when it implements none. */
   readonly implementsContracts?: readonly string[];
+  /** THE DECLARED DART PRODUCT NAME (`.dartName("Site")`, architecture/dart_naming.md). When set, EVERY
+   *  Dart codegen site that would otherwise derive a name from the aggregate WIRE id (the concrete
+   *  aggregate class, the `<stem>ReadModel` projection class, the `<stem>Id` typed-id class, the
+   *  `read/watch<Name>ById` accessors, and `ForeignRef<Target>` targets pointing at this aggregate) uses
+   *  this name instead. Pure codegen PRESENTATION — the wire id / stable ids / projection type tag are
+   *  UNCHANGED, and TS codegen stays id-derived. Additive, NON-law (never hashed — like `implementsContracts`);
+   *  OMITTED when unset (a package with no `.dartName()` emits byte-identical Dart). */
+  readonly dartClassName?: string;
   /**
    * FRAMEWORK-SHARED brand (Dart-codegen hygiene). Set (by `framework/framework_aggregates.ts`)
    * ONLY on the framework-owned aggregate singletons declared in `dsl/src/framework/` — most
@@ -232,19 +241,34 @@ export interface AggregateHandle<
 
 /** The fluent AUDIENCE declarations returned by {@link aggregate} (secure-by-default). Each returns a
  *  copy of the handle with the read audience set; you call exactly one at the declaration site. */
+/** A settled aggregate handle that STILL accepts the cosmetic `.dartName()` (so it chains after a
+ *  terminal audience declaration — `aggregate(...).public().dartName("Site")`), but not another
+ *  audience choice. `.dartName()` itself returns the full fluent surface (so either order works). */
+export type NameableHandle<Id extends string, F extends Record<string, Field>> = AggregateHandle<Id, F> & {
+  dartName(name: string): AggregateHandle<Id, F> & AudienceMethods<Id, F>;
+};
+
 export interface AudienceMethods<Id extends string, F extends Record<string, Field>> {
   /** Anyone may read (plaintext) — the deliberate public exception. */
-  public(): AggregateHandle<Id, F>;
+  public(): NameableHandle<Id, F>;
   /** Holders of `capability` may read (gate-enforced) — sugar over `requires(cap)`. */
-  readableBy(capability: string): AggregateHandle<Id, F>;
+  readableBy(capability: string): NameableHandle<Id, F>;
   /** The owner (+ per-record grantees) read; owner = the verified author, stamped into `ownerField`
    *  (default `__owner`); operator-blind. NOTE: full owned read-scoping + E2E land in the next slice. */
-  owned(ownerField?: string): AggregateHandle<Id, F>;
+  owned(ownerField?: string): NameableHandle<Id, F>;
   /** DOMAIN CONTRACTS: assert this aggregate satisfies `contract`'s public shape (compile-checked — a
    *  mismatch throws naming the field). Chainable; records the contract so cross-domain refs can target it. */
   implements(contract: ContractHandle): AggregateHandle<Id, F> & AudienceMethods<Id, F>;
+  /** DART PRODUCT NAME: declare the Dart-side name for this aggregate (`.dartName("Site")`) — Dart codegen
+   *  only, non-law, additive (see {@link AggregateHandle.dartName}). Validated NOW: `name` must be a legal
+   *  Dart type identifier (`/^[A-Z][A-Za-z0-9_]*$/`). Cross-aggregate collision is validated at compile.
+   *  Chainable; re-declaration overwrites. */
+  dartName(name: string): AggregateHandle<Id, F> & AudienceMethods<Id, F>;
 }
 
+/** A legal Dart TYPE identifier for `.dartName()` — PascalCase-ish (leading upper, then word chars). */
+const DART_TYPE_NAME_RE = /^[A-Z][A-Za-z0-9_]*$/;
+
 export function aggregate<const Id extends string, F extends Record<string, Field>>(
   id: Id,
   fields: F,
@@ -300,6 +324,27 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
       }
     }
   }
+  // SURFACED MERGE CONFLICTS (architecture/surfaced_merge_conflict.md): `.merge(Surfaced(inner))`
+  // is v1-scoped to Lww-class SCALAR fields — the pending set holds competing scalar values a
+  // human picks between. The factory already refuses a non-Lww-class INNER; this refuses the
+  // wrapper on a field whose VALUE isn't a wholesale-replace scalar (a set/map/counter/position
+  // field's value space has no "pick one of two scalars" meaning) and on a null-admitting field
+  // (the tri-state NomosSlot and the pending envelope would fight over the same read surface).
+  for (const [name, f] of Object.entries(stored)) {
+    const field = f as Field;
+    if ((field.driver as { kind?: string }).kind !== "Surfaced") continue;
+    if (field.kind === "set" || field.kind === "map" || field.kind === "counter" || field.kind === "position") {
+      throw new Error(
+        `aggregate '${id}': field '${name}' is .merge(Surfaced(...)) but its kind is '${field.kind}' — Surfaced wraps Lww-class SCALAR fields only in v1 (a '${field.kind}' field already has a conflict-free structural merge)`,
+      );
+    }
+    if (admitsNull(field)) {
+      throw new Error(
+        `aggregate '${id}': field '${name}' is .merge(Surfaced(...)) but also admits null (t.nullable/t.clearable) — Surfaced + the tri-state null slot is not supported in v1; drop one of the two`,
+      );
+    }
+  }
+
   // The `.meta()` fields (plaintext-metadata opt-out on owned aggregates) — recorded for the compiler.
   const metaFields = Object.entries(stored)
     .filter(([, f]) => (f as Field).isMeta === true)
@@ -363,24 +408,36 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
     audience: Audience | undefined,
     visibility: ReadVisibility | undefined,
     contracts: readonly string[] = [],
+    dartNameDecl: string | undefined = undefined,
   ): AggregateHandle<Id, F> & AudienceMethods<Id, F> => ({
     ...base,
     ...(audience !== undefined ? { audience } : {}),
     ...(visibility !== undefined ? { visibility } : {}),
     ...(contracts.length > 0 ? { implementsContracts: contracts } : {}),
-    public: () => build({ kind: "public" }, undefined, contracts),
+    ...(dartNameDecl !== undefined ? { dartClassName: dartNameDecl } : {}),
+    public: () => build({ kind: "public" }, undefined, contracts, dartNameDecl),
     readableBy: (cap: string) => {
       const v = requires(cap); // validates the capability name
-      return build({ kind: "readableBy", cap: v.requires }, v, contracts);
+      return build({ kind: "readableBy", cap: v.requires }, v, contracts, dartNameDecl);
     },
-    owned: (ownerField: string = OWNER_FIELD) => build({ kind: "owned", ownerField }, undefined, contracts),
+    owned: (ownerField: string = OWNER_FIELD) => build({ kind: "owned", ownerField }, undefined, contracts, dartNameDecl),
     // DOMAIN CONTRACTS: assert this aggregate satisfies `contractHandle`'s public shape — compile-checked
     // NOW (a mismatch throws a typed error naming the field). Records the contract so cross-domain refs may
     // target it. Chainable (`.implements(A).implements(B)`); the aggregate keeps its concrete fields.
     implements: (contractHandle: ContractHandle) => {
       const verdict = satisfiesContract(id, stored as Record<string, Field>, contractHandle);
       if (!verdict.ok) throw new Error(verdict.reason);
-      return build(audience, visibility, contracts.includes(contractHandle.id) ? contracts : [...contracts, contractHandle.id]);
+      return build(audience, visibility, contracts.includes(contractHandle.id) ? contracts : [...contracts, contractHandle.id], dartNameDecl);
+    },
+    // DART PRODUCT NAME: validate the identifier shape NOW; store it (Dart codegen only, non-law).
+    dartName: (name: string) => {
+      if (!DART_TYPE_NAME_RE.test(name)) {
+        throw new Error(
+          `aggregate '${id}': .dartName(${JSON.stringify(name)}) must be a legal Dart type identifier ` +
+            `matching ${DART_TYPE_NAME_RE} (PascalCase — a leading uppercase letter, then letters/digits/underscore)`,
+        );
+      }
+      return build(audience, visibility, contracts, name);
     },
   });
 

package/src/build_package.ts

@@ -77,6 +77,8 @@ import { expandCapabilityExports } from "./capability_exports.js";
 import { RelationTuple } from "./framework/relations.js";
 import { parentAttestedBirthMarker } from "./births.js";
 import { discoverUnsanctionedEnsures, sanctioningEnsureDirective } from "./secondary_ensure.js";
+import { assertIdOfLint } from "./idof_lint.js";
+import { assertSurfacedResolvers } from "./surfaced_lint.js";
 
 // ─────────────────────────────────────────────────────────────────────────────────
 // composeDomainModule — the named-keys `module(...)`
@@ -388,6 +390,23 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
       }
     : null;
 
+  // THE PAYLOAD-REF idOf LINT (dart_codegen_parity.md P2 — ref ergonomics): plan-probe every
+  // directive and refuse a directive whose payload feeds a ref/foreignRef field from a
+  // provably-bare (unbranded) `z.string()` — see `idof_lint.ts` for the exact, deliberately
+  // narrow scope. Compile-time only, no manifest/wire/hash effect.
+  assertIdOfLint(directives, spec.domain ?? spec.name);
+
+  // THE SURFACED-RESOLVER LINT (surfaced_lint.ts — the fail-closed teeth): every
+  // `.merge(Surfaced(...))` field must have EXACTLY ONE `.resolves()` directive, whose plan
+  // provably set()s the field from a payload field. Returns the resolver bindings the typed
+  // `resolve…` helper codegen consumes. Compile-time only — no manifest/wire/hash effect;
+  // a Surfaced-free domain runs zero checks (byte-identical).
+  const surfacedResolvers = assertSurfacedResolvers(
+    aggregates,
+    directives,
+    spec.domain ?? spec.name,
+  );
+
   return {
     name: spec.name,
     domain: spec.domain ?? spec.name,
@@ -398,6 +417,9 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     // ROLE SUGAR codegen metadata — NOT law (not hashed): drives the `canEdit<Agg>`/`canView<Agg>`
     // UI-hint helpers. Omit-when-empty (a role-free domain is byte-identical).
     ...(roles.length > 0 ? { roles } : {}),
+    // SURFACED RESOLVER BINDINGS — NOT law (not hashed, like `roles`): drives the generated
+    // typed `resolve…` helpers + the `pendingConflicts` accessor. Omit-when-empty (era rule).
+    ...(surfacedResolvers.length > 0 ? { surfacedResolvers } : {}),
     ...(queries.length > 0 ? { queries } : {}),
     ...(counts.length > 0 ? { counts } : {}),
     ...(spatials.length > 0 ? { spatials } : {}),