@githolon/dsl 0.71.0 → 0.72.1

package/src/compile_package_main.ts

@@ -225,6 +225,30 @@ interface PackageConfig {
           readonly types: string;
           readonly client: string;
           readonly test?: string;
+          /**
+           * MIGRATION-ONLY COMPAT PACKAGE (architecture/dart_naming.md). When set, `dart.names` alias
+           * `typedef`s are routed HERE (a standalone `<compat>` pub package of pure typedefs over the
+           * real `types` package) INSTEAD of the types barrel — a clearly-labeled, deletable-when-done
+           * shim so callers can migrate to the real names at their own pace. Its `pubspec.yaml` is
+           * scaffolded only-if-missing (tenant-owned versioning) and depends on the types package. When
+           * UNSET, `dart.names` land in the types barrel exactly as before (fully backward compatible).
+           */
+          readonly compat?: string;
+          /**
+           * BARREL PROMOTION POLICY (Jack's namespaces-not-prefixes directive, architecture/dart_naming.md).
+           * Each generated per-domain `.dart` file is ALREADY its own Dart library — `import
+           * 'package:<types>/src/generated/estate.dart' as estate;` then `estate.Site` is real, working
+           * namespacing regardless of this flag. This ONLY governs whether the top-level package barrel
+           * ALSO flat-re-exports every domain's classes into one unqualified scope:
+           *   • `'all'` (DEFAULT) — flat-export every domain file (today's ergonomics; the single-domain
+           *     common case is unaffected). Byte-identical to before this flag existed.
+           *   • `'explicit'` — for MULTI-domain packages: the barrel re-exports only the SHARED core
+           *     (framework/contracts/activity + nomos_types), NOT the per-domain aggregate/read-model
+           *     classes, so two domains that both name a `Site` never silently share a flat scope —
+           *     consumers disambiguate with `as`-prefixed per-domain imports. A SINGLE-domain package is
+           *     unaffected (no collision risk ⇒ the lone domain stays flat-exported, byte-identical).
+           */
+          readonly barrelExports?: "all" | "explicit";
         };
         /**
          * PUBLIC ALIASES for generated type names (`{ "EstateEstateCustomFieldDefinitionFieldType":
@@ -439,13 +463,16 @@ const DART_SUPPORT_CORE_SRC = [
   // The custody-lifecycle types (NomosCustodyBreak/NomosCustodyStatus/CustodyBreakPolicy) — the generated
   // client + the vendored bridge reference them through the barrel, so they must vendor. Pure data.
   "custody.dart",
+  // SURFACED MERGE CONFLICTS: SurfacedValue<T>/SurfacedObservation<T> — a generated read model with a
+  // `.merge(Surfaced(...))` field references them through the barrel, so they must vendor. Pure data.
+  "surfaced.dart",
 ] as const;
 // The RUNTIME support files, vendored from `nomos_client` (dsl/dart/lib/src): the async WebView
 // bridge the generated `<name>.client.dart` drives, and the provider surface. Their
 // `package:nomos_types/...` imports are rewritten to the local vendored shim (see emitDart).
 // (`home.dart` is NOT vendored — the home-onboarding runtime drags `package:crypto`; nothing the
 // codegen emits references it.)
-const DART_SUPPORT_RUNTIME_SRC = ["provider.dart", "webview_bridge.dart"] as const;
+const DART_SUPPORT_RUNTIME_SRC = ["provider.dart", "webview_bridge.dart", "session_bound.dart"] as const;
 const DART_SUPPORT_SRC = [...DART_SUPPORT_CORE_SRC, ...DART_SUPPORT_RUNTIME_SRC] as const;
 /** The local shim replacing `package:nomos_types/nomos_types.dart` inside vendored runtime files. */
 const VENDORED_TYPES_SHIM = "nomos_types.dart";
@@ -871,12 +898,16 @@ const DART_TYPES_IMPORT = `import 'package:nomos_types/nomos_types.dart';`;
 /** Version constraints the scaffolded pubspecs pin — move together with the Dart packages' releases.
  *  Caret on 0.x is EXACT-MINOR (`^0.45.0` = `<0.46.0`), so these must track the CURRENT release, not
  *  just the floor generated code needs — a lagging pin forces tenants into dependency_overrides. */
-// 0.1.4: custody-lifecycle types (CustodyBreakPolicy et al).
-// 0.2.0: branded birth identities (NomosPrincipal/NomosDeviceSecret) — the generated cross-workspace
-//        `.births()` methods type actor/authorSecret as these, so a layered package needs nomos_types 0.2.0.
-const NOMOS_TYPES_DEP = "^0.2.0";
-// 0.46.0: custody lifecycle on NomosBridge/NomosSession (onCustodyBreak/custodyStatus/salvage lanes).
-const NOMOS_CLIENT_DEP = "^0.46.0";
+// 0.3.0: SurfacedValue<T>/SurfacedObservation/PendingConflictRow — generated Surfaced-field typing +
+//        the pendingConflicts read rows.
+const NOMOS_TYPES_DEP = "^0.3.0";
+// 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
+//         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
+//         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
+const NOMOS_CLIENT_DEP = "^0.48.1";
+// DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
+// and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
+// land back in dependency_overrides (the exact co2 report this closes, third occurrence).
 
 const isPubPackageName = (s: string): boolean => /^[a-z][a-z0-9_]*$/.test(s);
 
@@ -960,7 +991,7 @@ function emitDartPackages(
   dartOut: string,
   domainHash: string,
   packageInterface: Record<string, DomainInterface>,
-  packages: { readonly types: string; readonly client: string; readonly test?: string },
+  packages: { readonly types: string; readonly client: string; readonly test?: string; readonly compat?: string; readonly barrelExports?: "all" | "explicit" },
   names: Readonly<Record<string, string>> | undefined,
   compat?: NomosCompat,
 ): { written: string[]; cursed: string[] } {
@@ -969,8 +1000,13 @@ function emitDartPackages(
       fail(`dart.packages.${role}: '${String(name)}' is not a valid pub package name (lower_snake_case)`);
     }
   }
-  const roleNames = [packages.types, packages.client, ...(packages.test !== undefined ? [packages.test] : [])];
-  if (new Set(roleNames).size !== roleNames.length) fail(`dart.packages: types/client/test names must be distinct`);
+  const roleNames = [
+    packages.types,
+    packages.client,
+    ...(packages.test !== undefined ? [packages.test] : []),
+    ...(packages.compat !== undefined ? [packages.compat] : []),
+  ];
+  if (new Set(roleNames).size !== roleNames.length) fail(`dart.packages: types/client/test/compat names must be distinct`);
 
   const shared = collectDartSharedSymbols(modules);
   const written: string[] = [];
@@ -1080,16 +1116,40 @@ function emitDartPackages(
   const aliasImportUris = [...typesSources.keys()]
     .filter((f) => [...(declaredByFile.get(f) ?? [])].some((n) => aliasTargets.has(n)))
     .map((f) => `${genRel}/${f}.dart`);
+  // COMPAT ROUTING (architecture/dart_naming.md): when `packages.compat` is set, the `dart.names`
+  // typedefs go into a SEPARATE migration-only package instead of the types barrel. The types barrel
+  // then carries NO aliases (fully humane vs. compat separation); when compat is UNSET, aliases land
+  // in the types barrel exactly as before.
+  const compatPackage = packages.compat;
+  const routeAliasesToCompat = compatPackage !== undefined && compatPackage !== "" && names !== undefined && Object.keys(names).length > 0;
+  const barrelNames = routeAliasesToCompat ? undefined : names;
+  const barrelAliasImportUris = routeAliasesToCompat ? [] : aliasImportUris;
+  // BARREL PROMOTION POLICY (dart_naming.md): `'explicit'` on a MULTI-domain package stops the barrel
+  // flat-exporting per-domain aggregate/read-model classes (consumers use `as`-prefixed per-domain
+  // imports); the shared core (framework/contracts/activity) still flat-exports. A single-domain package
+  // (no collision risk) is UNAFFECTED — byte-identical to `'all'`.
+  const domainFileBases = new Set(modules.map((m) => m.name));
+  const explicitBarrel = packages.barrelExports === "explicit" && modules.length > 1;
+  const typesExportKeys = explicitBarrel
+    ? [...typesSources.keys()].filter((f) => !domainFileBases.has(f))
+    : [...typesSources.keys()];
+  const explicitBarrelNote = explicitBarrel
+    ? [
+        `// barrelExports: 'explicit' — per-domain aggregate/read-model classes are NOT flat-exported here.`,
+        `// Import a domain with a prefix instead, e.g. \`import '${genRel}/<domain>.dart' as <domain>;\`.`,
+      ]
+    : [];
   const typesBarrel = [
     "// GENERATED by nomos-compile — the TYPES package's public entrypoint. DO NOT EDIT.",
     "// Pure data: payload classes, read models, VOs/enums, typed read accessors over the",
     "// injected NomosReads seams. Frontend-safe — no bridge, no sessions, no lifecycle.",
     "library;",
     "",
-    ...aliasImportLines(names, aliasImportUris),
+    ...explicitBarrelNote,
+    ...aliasImportLines(barrelNames, barrelAliasImportUris),
     `export 'package:nomos_types/nomos_types.dart';`,
-    ...[...typesSources.keys()].map((f) => `export '${genRel}/${f}.dart';`),
-    ...dartAliasLines(names, declared),
+    ...typesExportKeys.map((f) => `export '${genRel}/${f}.dart';`),
+    ...dartAliasLines(barrelNames, declared),
     "",
   ];
   const typesBarrelPath = path.join(pkgDir(packages.types), "lib", `${packages.types}.dart`);
@@ -1192,6 +1252,62 @@ function emitDartPackages(
     );
   }
 
+  // ── the COMPAT package (optional, MIGRATION-ONLY) — pure `dart.names` typedefs over the types package ──
+  // Routed here (instead of the types barrel) when `dart.packages.compat` is set: a standalone, clearly
+  // labeled, deletable-when-done shim. The typedefs resolve because they import the types barrel (which
+  // re-exports every generated symbol). Validated fail-closed by `dartAliasLines` against the types surface.
+  if (routeAliasesToCompat) {
+    const compatName = compatPackage!;
+    if (!isPubPackageName(compatName)) {
+      fail(`dart.packages.compat: '${compatName}' is not a valid pub package name (lower_snake_case)`);
+    }
+    const compatGen = freshGenDir(compatName);
+    const typesImportForCompat = `package:${packages.types}/${packages.types}.dart`;
+    const compatFile = [
+      "// GENERATED by nomos-compile — MIGRATION-ONLY compat aliases. DO NOT EDIT.",
+      `//`,
+      `// MIGRATION-ONLY — delete this package (\`${compatName}\`) once callers have moved to the real`,
+      `// names in \`${packages.types}\`. Every symbol below is a plain \`typedef\` over the real generated`,
+      `// type; it exists solely to keep pre-rename imports compiling during a migration. It adds NO`,
+      `// behaviour and SHOULD NOT accrete new entries — new code imports \`${packages.types}\` directly.`,
+      "library;",
+      "",
+      `import '${typesImportForCompat}';`,
+      ...dartAliasLines(names, declared),
+      "",
+    ];
+    const compatSrcPath = path.join(compatGen, `${compatName}_aliases.dart`);
+    writeFileSync(compatSrcPath, compatFile.join("\n"), "utf8");
+    written.push(compatSrcPath);
+    const compatBarrel = [
+      "// GENERATED by nomos-compile — the COMPAT package's public entrypoint. DO NOT EDIT.",
+      `// MIGRATION-ONLY — delete \`${compatName}\` once callers use the real names in \`${packages.types}\`.`,
+      "library;",
+      "",
+      `export '${typesImportForCompat}';`,
+      `export '${genRel}/${compatName}_aliases.dart';`,
+      "",
+    ];
+    const compatBarrelPath = path.join(pkgDir(compatName), "lib", `${compatName}.dart`);
+    writeFileSync(compatBarrelPath, compatBarrel.join("\n"), "utf8");
+    written.push(compatBarrelPath);
+    scaffoldPubspec(
+      pkgDir(compatName),
+      [
+        `name: ${compatName}`,
+        `description: MIGRATION-ONLY Nomos name-compat shim (typedefs over ${packages.types}). Delete once migrated.`,
+        `version: 0.1.0`,
+        `publish_to: none # tenant-owned: remove to publish`,
+        `environment:`,
+        `  sdk: ^3.5.0`,
+        `dependencies:`,
+        `  ${packages.types}:`,
+        `    path: ../${packages.types} # co-emitted sibling; replace with a hosted constraint when publishing`,
+        ``,
+      ].join("\n"),
+    );
+  }
+
   return { written, cursed: cursedNameHints(declared, names) };
 }
 
@@ -2350,7 +2466,7 @@ async function main(): Promise<void> {
           typeof dartCfg.packages.client !== "string")))
   ) {
     fail(
-      `config key 'dart' must be false, true, or { out?: "relative/dir", support?: "vendored" | "package", barrel?: "snake_case_name", packages?: { types, client, test? }, names?: { Generated: "Alias" } }; got ${JSON.stringify(dartCfg)}`,
+      `config key 'dart' must be false, true, or { out?: "relative/dir", support?: "vendored" | "package", barrel?: "snake_case_name", packages?: { types, client, test?, compat? }, names?: { Generated: "Alias" } }; got ${JSON.stringify(dartCfg)}`,
     );
   }
   const dartPackages = typeof dartCfg === "object" ? dartCfg.packages : undefined;

package/src/directive.ts

@@ -310,6 +310,17 @@ export interface Directive<P = unknown> {
    * to before this existed (the markers only emit the already-existing invariant era key, when used).
    */
   readonly preconditions?: PreconditionDescriptor[];
+  /**
+   * THE DESIGNATED SURFACED RESOLVER (surfaced_merge_conflict.md — the DX layer). Set by
+   * `.resolves("field")`: this directive is THE designated resolver of its target aggregate's named
+   * `.merge(Surfaced(...))` field — the one the generated typed `resolve…` helper dispatches. EXACTLY ONE
+   * directive may resolve each Surfaced field, and every Surfaced field MUST have one (both enforced at
+   * `composeDomainModule`, fail-closed — see `surfaced_lint.ts`). NON-LAW, additive codegen metadata (the
+   * `description`/`grantsRelation` class): it changes NO manifest/hash — in the KERNEL sense any gated
+   * directive that set()s the field still resolves the conflict; this only designates which one the typed
+   * helper binds. Omit-when-absent (a non-resolving directive is byte-identical).
+   */
+  readonly resolvesField?: string;
   /**
    * CALLER-SUPPLIED-ID CREATE-ONCE (`.creates(Agg)….withId(idFn)`). When set, the directive `creates` the
    * aggregate at an APP-SUPPLIED stable id (`idFn(payload)`, like `.ensures`) rather than a minted id,
@@ -485,6 +496,17 @@ export interface RequirableDirective<P> extends Directive<P> {
    * Accumulates + dedups; additive + non-destructive. A directive that never calls this is byte-identical.
    */
   grants(relation: string): RequirableDirective<P>;
+  /**
+   * Designate this directive THE resolver of its target aggregate's Surfaced `field`
+   * (`directive("retitleDoc").mutates(Doc)….resolves("title")`). The generated typed resolution helper
+   * (TS + Dart) binds to it: `resolve…(conflict, chosenValue)` desugars to dispatching THIS directive.
+   * ESCAPE HATCH (kernel truth): any gated directive that set()s the field still resolves the conflict
+   * in the kernel sense — `.resolves()` only designates which one the typed helper dispatches. Enforced
+   * fail-closed at compile: the field must be a declared `.merge(Surfaced(...))` field of the target
+   * aggregate, EXACTLY ONE directive may resolve it, and every Surfaced field must have a resolver.
+   * NON-LAW + additive (the `.doc()` class) — a directive that never calls this is byte-identical.
+   */
+  resolves(field: string): RequirableDirective<P>;
 }
 
 /** Stage 1: id + a referential marker (which fixes the target aggregate). */
@@ -871,6 +893,24 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       const mergedQueries = [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
       return makeRequirable({ ...base, birthsChild: true, declaredQueryReads: mergedQueries });
     },
+    resolves(field: string): RequirableDirective<P> {
+      // THE DESIGNATED SURFACED RESOLVER: record which Surfaced field this directive resolves. Field
+      // existence / Surfaced-ness / exactly-one-per-field are judged at `composeDomainModule` (the
+      // aggregate handles are in hand there); here only the shape is checked. Non-law, additive.
+      if (typeof field !== "string" || field.length === 0) {
+        throw new Error(
+          `directive('${base.id}').resolves(field) needs a non-empty field name — the Surfaced field ` +
+            `this directive is the designated resolver of (e.g. .resolves("title")).`,
+        );
+      }
+      if (base.resolvesField !== undefined && base.resolvesField !== field) {
+        throw new Error(
+          `directive('${base.id}').resolves("${field}"): already .resolves("${base.resolvesField}") — ` +
+            `a directive designates AT MOST ONE Surfaced field (write a second directive for the other).`,
+        );
+      }
+      return makeRequirable({ ...base, resolvesField: field });
+    },
     grants(relation: string): RequirableDirective<P> {
       // PROOF-TOOLING PRODUCER MARKER (symmetric to `.requires`): record that this directive establishes
       // `relation` (its plan folds a granting `writeTuple`). NO kernel/manifest effect — a pure static hint

package/src/drivers.ts

@@ -36,7 +36,8 @@ export type KernelDriverKind =
   | "Conflict"
   | "RemoveWins"
   | "Counter"
-  | "LastPosition";
+  | "LastPosition"
+  | "Surfaced";
 /**
  * Drivers in the design palette the kernel does not yet merge. Currently EMPTY —
  * every palette driver encodes. Kept as a (never-)union so a future palette
@@ -48,7 +49,7 @@ export type DriverKind = KernelDriverKind | PaletteOnlyKind;
 
 export interface Driver {
   readonly kind: DriverKind;
-  /** Only present for MapOf. */
+  /** Only present for MapOf / Surfaced. */
   readonly inner?: Driver;
   /** Only present for `LwwBy`: the named time-authority principal (a verified userId). */
   readonly principal?: string;
@@ -95,6 +96,61 @@ export const LastPosition: Driver = { kind: "LastPosition" };
 export const RemoveWins: Driver = { kind: "RemoveWins" };
 export const Counter: Driver = { kind: "Counter" };
 
+/** The Lww-class inner drivers `Surfaced` may wrap in v1 (wholesale-replace scalars —
+ *  the pending set holds competing SCALAR values a human picks between). */
+const SURFACED_INNER_KINDS: ReadonlySet<DriverKind> = new Set<DriverKind>([
+  "Lww",
+  "LwwCausal",
+  "LwwBy",
+]);
+
+/**
+ * `merge(Surfaced(inner))` — the USER-RESOLVABLE third merge posture
+ * (architecture/surfaced_merge_conflict.md; kernel `merge_field` arm in
+ * `nomos2/kernel/src/lib.rs`). On a GENUINELY CONCURRENT write (the divergent
+ * 3-way merge lane — two session branches touching the field between syncs) the
+ * kernel neither silently folds to a winner NOR drops the field: it retains BOTH
+ * competing values as a bounded pending-observation set (cap 8, deterministically
+ * pruned) that a read surfaces as `{"__surfaced":{"pending":[{value, author,
+ * occurredAt}, ...]}}` — ALWAYS 2+ competing observations (a single-observation
+ * set read-collapses to the plain scalar) — so an app can show a "pick one" UI.
+ * Linear writes and
+ * fast-forwards behave EXACTLY as the inner driver (`Surfaced(LwwBy(p))` keeps
+ * `p`'s write filter); pending sets form ONLY under real concurrency.
+ *
+ * RESOLUTION IS AN ORDINARY NEXT WRITE — a `.mutates(...)` directive the domain
+ * author writes that `set()`s the field on top of the pending state. It
+ * fast-forwards the field to plain Resolved (byte-identical to any other field
+ * thereafter); no new write-authority primitive exists or is needed.
+ *
+ * CAVEATS: observations carry `{value, author, occurredAt}` where `author` (the
+ * writer principal) is nullable — an observation folded where no intent context
+ * exists carries no author. v1 wraps Lww-class SCALAR inners only: `Lww`,
+ * `LwwCausal`, `LwwBy(principal)` (a concurrent add to an `AddWins` set already
+ * commutes without conflict; surfacing a map/counter has no v1 meaning).
+ */
+export const Surfaced = (inner: Driver): Driver => {
+  if (inner === null || typeof inner !== "object" || typeof inner.kind !== "string") {
+    throw new Error(
+      `Surfaced(inner) needs an inner merge driver — e.g. Surfaced(Lww) or Surfaced(LwwBy("updatedAt")).`,
+    );
+  }
+  if (!SURFACED_INNER_KINDS.has(inner.kind)) {
+    throw new Error(
+      `Surfaced(${inner.kind}) is not supported — Surfaced wraps an Lww-class SCALAR inner driver only ` +
+        `(Lww, LwwCausal, LwwBy) in v1. A pending set holds competing scalar values a human picks between; ` +
+        `'${inner.kind}' ${
+          inner.kind === "Surfaced"
+            ? "is already Surfaced — nesting adds nothing"
+            : inner.kind === "AddWins" || inner.kind === "RemoveWins" || inner.kind === "Counter"
+              ? "already merges concurrent writes without conflict by design"
+              : "is not a wholesale-replace scalar merge"
+        }.`,
+    );
+  }
+  return { kind: "Surfaced", inner };
+};
+
 // Drivers in the palette the kernel does NOT yet merge — currently NONE. A future
 // palette driver added ahead of its `merge_field` arm goes here; `encodeDriver`
 // throws for it rather than emit a wire driver the kernel can't merge.
@@ -127,6 +183,11 @@ export function encodeDriver(d: Driver): WireDriver {
     case "MapOf":
       if (!d.inner) throw new Error("MapOf driver is missing its inner driver");
       return { MapOf: encodeDriver(d.inner) };
+    case "Surfaced":
+      // serde newtype variant `Driver::Surfaced(Box<Driver>)` → `{ "Surfaced": <inner> }`
+      // (externally tagged, mirroring MapOf exactly).
+      if (!d.inner) throw new Error("Surfaced driver is missing its inner driver");
+      return { Surfaced: encodeDriver(d.inner) };
     default:
       if (PALETTE_ONLY.has(d.kind)) {
         throw new Error(

package/src/idof_lint.ts

@@ -0,0 +1,144 @@
+// 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.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * THE PAYLOAD-REF idOf LINT (`architecture/dart_codegen_parity.md` P2 — ref ergonomics). A
+ * `t.ref(Target)` / `t.foreignRef(Target)` field on the AGGREGATE/read-model side already
+ * generates a TYPED id class (`SiteId`, `codegen_dart.ts`). Nothing enforced the payload SIDE
+ * carried the matching brand — a directive author can write `siteId: z.string()` in the
+ * payload and never discover `idOf(Site)` exists, so the generated Dart payload class carries a
+ * raw `String` while the read model carries `SiteId`: an asymmetry that forces manual
+ * `.value` unwrap/rewrap at the UI boundary and lets a mistyped id compile silently.
+ *
+ * THIS PASS closes that gap at COMPILE time: for every directive, plan-PROBE it (reusing the
+ * exact primitive the proof generator's own discovery legs use — `probePlanOps` /
+ * `synthesizePayload`, `codegen_proof.ts` — NOT a new AST interpreter) and, for every emitted
+ * field op that targets a ref-kind field, check whether the op's value is traceable to a
+ * TOP-LEVEL payload field whose zod schema is a bare (unbranded) string. If so: REFUSE, naming
+ * the directive, the payload field, the ref field, and its target aggregate, with the fix.
+ *
+ * SCOPE (deliberately narrow — a narrower lint with zero false positives beats a broad one with
+ * false refusals, per the authoring guidance):
+ *   - Only DIRECT, first-order plans: `create(Agg).set("ref", payload.path)` /
+ *     `setEntry(instance(Agg,...), "ref", key, payload.path)` — i.e. shapes the plan-probe
+ *     mechanism already observes as ONE emitted op whose `value` is byte-identical to a
+ *     TOP-LEVEL synthesized payload field's sample value. A value that is transformed,
+ *     concatenated, or nested more than one level deep inside the payload does NOT match
+ *     (no false positive — it simply isn't flagged; this is intentionally NOT full dataflow
+ *     analysis over the plan body).
+ *   - Only fires when the payload field's own sampled value round-trips EXACTLY into the op
+ *     (relies on `synthesizePayload`'s per-field-distinguishable string samples,
+ *     `"sample-<field>"` — the same discriminator the proof generator's own subject/grant-field
+ *     resolution already trusts, see `resolveGrantSubjectFields`).
+ *   - A directive whose plan can't be probed (unsynthesizable payload, or the plan throws under
+ *     the synthesized sample) is SKIPPED — best-effort, matching every other plan-probe
+ *     consumer in `codegen_proof.ts` (never a false refusal from an exotic shape).
+ *   - `idOf(Agg)` AND `brandedId(Name)` both satisfy the lint (either brand types the Dart/TS
+ *     side); only a truly BARE `z.string()` (through `.optional()`/`.default()`/`.nullable()`)
+ *     refuses.
+ *
+ * NOT era-gated: this is a pure Dart/TS-codegen build-time guard (like the domain-contracts
+ * circular-import guard in `compile_package_main.ts`) — it has no wire/manifest/kernel effect,
+ * changes no hash, and never touches already-deployed law. It only judges whether `nomos-compile`
+ * accepts a directive's SOURCE shape, exactly the same posture as that circular-dependency guard.
+ * A domain already using `idOf`/`brandedId` (or one with no ref-fed payload field at all) compiles
+ * exactly as before; only a directive whose payload feeds a ref field with a provably-bare string
+ * newly refuses — which is the intended fail-closed behaviour, not an accidental regression.
+ */
+import type { z } from "zod";
+
+import type { Directive } from "./directive.js";
+import type { FieldOp } from "./ops.js";
+import { probePlanOps } from "./codegen_proof.js";
+import { zodKind, zodDef, zodObjectShape } from "./codegen_ts.js";
+import { idOfMetaOf, brandedIdMetaOf } from "./value_object.js";
+
+/** A typed idOf-lint violation — the message names the directive, field, ref, and target. */
+export class IdOfLintError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "IdOfLintError";
+  }
+}
+
+/** Short, lower-camel/PascalCase-preserving stem of an aggregate id (`inventory.EstateSite` → `EstateSite`),
+ *  matching the same "identity is the tail segment" convention `directive.ts`'s `shortName` uses. */
+function shortAggName(aggregateId: string): string {
+  return aggregateId.includes(".") ? aggregateId.slice(aggregateId.lastIndexOf(".") + 1) : aggregateId;
+}
+
+/** Peel `.optional()`/`.default()`/`.nullable()` to the innermost schema (mirrors `idOfMetaOf`/
+ *  `brandedIdMetaOf`'s own peeling, so a wrapped bare string is still caught). */
+function isBareString(zt: z.ZodTypeAny): boolean {
+  let cur: z.ZodTypeAny | undefined = zt;
+  for (let hops = 0; cur !== undefined && hops < 16; hops++) {
+    if (idOfMetaOf(cur) !== undefined || brandedIdMetaOf(cur) !== undefined) return false;
+    const kind = zodKind(cur);
+    if (kind === "string") return true;
+    if (kind !== "optional" && kind !== "default" && kind !== "nullable") return false;
+    cur = zodDef(cur).innerType;
+  }
+  return false;
+}
+
+/** Resolve a ref-kind field op's TARGET aggregate id (`t.ref` → `refAggregateId`/thunk; `t.foreignRef` →
+ *  `foreignRef.targetAggregateId`). `undefined` when neither meta is present (an exotic/hand-built field). */
+function refTargetOf(op: FieldOp): string | undefined {
+  const f = op.targetField as
+    | { refAggregateId?: string; foreignRef?: { targetAggregateId?: string } }
+    | undefined;
+  if (f === undefined) return undefined;
+  return f.refAggregateId ?? f.foreignRef?.targetAggregateId;
+}
+
+/**
+ * Run the idOf lint over one directive: plan-probe it and refuse on the first payload-fed
+ * ref-field mismatch. Throws {@link IdOfLintError}; a directive the prober can't run through
+ * (unsynthesizable payload / plan throws) is silently skipped — best-effort, no false refusal.
+ */
+export function assertIdOfLintForDirective(dir: Directive<unknown>, where: string): void {
+  const probed = probePlanOps(dir, where);
+  if (probed === undefined) return;
+  let shape: Record<string, z.ZodTypeAny>;
+  try {
+    shape = zodObjectShape(dir.payloadSchema as z.ZodTypeAny);
+  } catch {
+    return;
+  }
+  // Reverse index: sampled STRING value → the top-level payload field name(s) that produced it.
+  // `synthesizePayload` gives every string-kind field a DISTINCT `"sample-<field>"` value (or a
+  // schema-constrained fallback), so an exact match is unambiguous in practice.
+  const byValue = new Map<string, string>();
+  for (const [name, value] of Object.entries(probed.synth.value)) {
+    if (typeof value === "string") byValue.set(value, name);
+  }
+  for (const op of probed.ops) {
+    if (op.kind !== "set" && op.kind !== "setEntry") continue;
+    if (typeof op.value !== "string") continue;
+    const targetAgg = refTargetOf(op);
+    if (targetAgg === undefined) continue; // not a ref-kind field (or one the DSL can't name a target for)
+    const payloadField = byValue.get(op.value);
+    if (payloadField === undefined) continue; // not traceable to a top-level payload field — no verdict
+    const fieldSchema = shape[payloadField];
+    if (fieldSchema === undefined || !isBareString(fieldSchema)) continue; // already idOf/brandedId — fine
+    const onAgg = shortAggName(op.aggregateType ?? op.aggregateId);
+    const targetName = shortAggName(targetAgg);
+    throw new IdOfLintError(
+      `directive '${dir.id}': payload field '${payloadField}' feeds ref field '${onAgg}.${op.field}' ` +
+        `(-> ${targetName}) but is a plain z.string() — wrap it as idOf(${targetName}) so the generated ` +
+        `Dart/TS carry the typed id, matching the read model. (dart_codegen_parity.md P2)`,
+    );
+  }
+}
+
+/** Run the idOf lint over every directive in a domain. `domain` names the module for the probe's
+ *  error-context strings (`synthesizePayload`'s `where`). Throws on the FIRST violation. */
+export function assertIdOfLint(directives: readonly Directive<unknown>[], domain: string): void {
+  for (const dir of directives) {
+    assertIdOfLintForDirective(dir, `${domain}/${dir.id}`);
+  }
+}

package/src/index.ts

@@ -93,6 +93,7 @@ export {
   LastPosition,
   RemoveWins,
   Counter,
+  Surfaced,
   encodeDriver,
   type Driver,
   type DriverKind,

package/src/usd_layers.ts

@@ -109,6 +109,8 @@ export function usdaStringArray(items: readonly string[]): string {
 export function driverToken(driver: WireDriver): string {
   if (typeof driver === "string") return driver;
   if ("LwwBy" in driver) return `LwwBy(${driver.LwwBy})`;
+  // `Surfaced(<inner>)` — the user-resolvable posture stays legible in the tree too.
+  if ("Surfaced" in driver) return `Surfaced(${driverToken(driver.Surfaced)})`;
   return `MapOf(${driverToken(driver.MapOf)})`;
 }
 
@@ -117,6 +119,9 @@ export function parseDriverToken(token: string): WireDriver {
   if (token.startsWith("MapOf(") && token.endsWith(")")) {
     return { MapOf: parseDriverToken(token.slice("MapOf(".length, -1)) };
   }
+  if (token.startsWith("Surfaced(") && token.endsWith(")")) {
+    return { Surfaced: parseDriverToken(token.slice("Surfaced(".length, -1)) };
+  }
   // `LwwBy(<principal>)` — the principal is an opaque non-empty string (uids carry
   // hyphens, so it is NOT the bare-identifier shape the unit-driver branch validates).
   if (token.startsWith("LwwBy(") && token.endsWith(")")) {

package/src/wire.ts

@@ -219,7 +219,10 @@ export type WireDriver =
   | "Counter"
   | "LastPosition"
   | { LwwBy: string }
-  | { MapOf: WireDriver };
+  | { MapOf: WireDriver }
+  // `Surfaced(Box<Driver>)` — the user-resolvable third merge posture
+  // (architecture/surfaced_merge_conflict.md): `{ "Surfaced": <inner> }`.
+  | { Surfaced: WireDriver };
 
 /** `Schema = BTreeMap<FieldId, Driver>` — a plain object, field -> Driver. */
 export type WireSchema = Record<string, WireDriver>;