@githolon/dsl 0.70.2 → 0.72.0

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.
@@ -787,6 +796,20 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
   );
   const encPresent = encMap !== null;
   const encConst = encryptionConstName(opts.packageName);
+  // A package declaring ≥1 `.births()` directive emits the branded identity wrappers (below) its typed
+  // birth methods take for `actor`/`authorSecret`. Births-free packages emit nothing (byte-identical).
+  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);
@@ -945,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\`):`,
@@ -953,6 +1015,14 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string; returnCreated?: boolean }): Promise<string | { head: string; created?: { type: string; id: string }[]; workspace?: string }>;`,
     `  /** Opaque-bytes offer — retained for carriers that already hold an encoded envelope (back-compat). */`,
     `  offer(intentBytes: string | Uint8Array): Promise<string>;`,
+    ...(hasBirths
+      ? [
+          `  /** BIRTH A CHILD WORKSPACE (a signed CROSS-WORKSPACE governance offer to \`parent\`) — OPTIONAL:`,
+          `   *  @githolon/client's connect() attaches it. The generated \`.births()\` methods call this, binding`,
+          `   *  the declaring domain/directiveId/law hash so a frontend dev never hand-writes those raw strings. */`,
+          `  createWorkspace?(opts: { domain: string; directiveId: string; domainHash?: string; parent: string; actor: string; authorSecret?: string; payload?: unknown; name?: string; authToken?: string }): Promise<{ ok?: boolean; status?: number; body?: unknown }>;`,
+        ]
+      : []),
     `  /** The workspace this holon is bound to — the \`workspace\` of every [NomosRef] this client composes. */`,
     `  workspace: string;`,
     ...(encPresent
@@ -977,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().`,
@@ -1046,6 +1123,25 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     ``,
   );
 
+  // BRANDED IDENTITY WRAPPERS for the typed cross-workspace birth methods: `actor` (NomosPrincipal) and
+  // `authorSecret` (NomosDeviceSecret) are distinct branded strings, so a caller can't transpose the two
+  // (a bare-string swap would compile and silently misfire). Emitted iff the package declares `.births()`.
+  if (hasBirths) {
+    out.push(
+      `/** A verified principal identity (\`user:<uid>\` on the wire) — construct with [nomosPrincipal]. A distinct`,
+      ` *  branded type from [NomosDeviceSecret] so the two birth-method params can never be transposed. */`,
+      `export type NomosPrincipal = string & { readonly __nomosPrincipal: unique symbol };`,
+      `/** A device signing secret (base64) — construct with [nomosDeviceSecret]. Distinct from [NomosPrincipal]. */`,
+      `export type NomosDeviceSecret = string & { readonly __nomosDeviceSecret: unique symbol };`,
+      `/** Brand a principal: a bare uid (\`ada\`) or a wire string (\`user:ada\`) → \`user:ada\`. */`,
+      `export const nomosPrincipal = (uidOrWire: string): NomosPrincipal =>`,
+      `  (uidOrWire.startsWith("user:") ? uidOrWire : \`user:\${uidOrWire}\`) as NomosPrincipal;`,
+      `/** Brand a device signing secret (base64). */`,
+      `export const nomosDeviceSecret = (base64: string): NomosDeviceSecret => base64 as NomosDeviceSecret;`,
+      ``,
+    );
+  }
+
   if (encPresent) {
     out.push(
       `// ── E2E SEALING (the sealing client) — baked map + KeyStore + seal/read helpers ──`,
@@ -1686,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);
@@ -1723,6 +1822,27 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps, mint ? [mint.field] : [], placed, lazyReg, d.id)};`,
         ``,
       );
+      // A `.births()` directive is NOT a same-workspace write — it is a signed CROSS-WORKSPACE governance
+      // offer to a PARENT. It gets a typed `holon.createWorkspace(...)` wrapper (declaring domain +
+      // directiveId + baked domainHash bound at codegen time), NOT an `offerDirective`, so a frontend dev
+      // never hand-writes the four raw strings this replaces (the co2 production bug).
+      if ((d as { birthsChild?: boolean }).birthsChild === true) {
+        const birthPayload = stamps.length ? `stampNow(payload, ${JSON.stringify(stamps)})` : "payload";
+        const gateBirthDoc = gate ? ` GATED: needs \`actor\` (\`${gate.relation}\`).` : "";
+        methods.push(
+          `    /** Births a CHILD WORKSPACE (named by \`${payloadName}\`) 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, hence \`parent\`/\`actor\` (the requesting principal, e.g. \`user:<uid>\`) unlike the`,
+          `     *  other methods. Declaring domain, directiveId, and law hash are baked in; returns the parent gateway's`,
+          `     *  verdict. \`authorSecret\` defaults to the holon's device key.${gateBirthDoc} */`,
+          `    ${d.id}: (opts: { parent: string; actor: NomosPrincipal; authorSecret?: NomosDeviceSecret; payload: ${payloadName}; authToken?: string }): Promise<{ ok?: boolean; status?: number; body?: unknown }> => {`,
+          ...(gateGuard ? [`      if (!opts.actor || !opts.actor.trim()) throw new MissingOfferAuthority(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, ${JSON.stringify(gate!.relation)});`] : []),
+          `      const _payload = opts.payload;`,
+          `      return (holon.createWorkspace ?? (() => { throw new Error("this holon predates cross-workspace births — upgrade @githolon/client"); }))({ domain: ${JSON.stringify(domain)}, directiveId: ${JSON.stringify(d.id)}, domainHash, parent: opts.parent, actor: opts.actor, authorSecret: opts.authorSecret, payload: ${birthPayload.replace("payload", "_payload")}, authToken: opts.authToken });`,
+          `    },`,
+        );
+        continue;
+      }
       // THE ONE WRITE OUTCOME (architecture/nomos_ref.md): EVERY directive method returns Promise<NomosOutcome>
       // — `created` (typed refs of all minted aggregates, from returnCreated) + `head`, plus `target` for the
       // front-door-mint lane (the one statically-known addressed instance). One async block covers every case.
@@ -1822,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(

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":
@@ -433,16 +457,22 @@ const DART_SUPPORT_CORE_SRC = [
   "foreign_ref.dart",
   "activity.dart",
   "nomos_ref.dart",
+  // Branded identity wrappers (NomosPrincipal/NomosDeviceSecret) — the generated cross-workspace birth
+  // methods type `actor`/`authorSecret` as these (not bare strings), so both must vendor. Pure data.
+  "principal.dart",
   // 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";
@@ -869,7 +899,9 @@ const DART_TYPES_IMPORT = `import 'package:nomos_types/nomos_types.dart';`;
  *  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).
-const NOMOS_TYPES_DEP = "^0.1.4";
+// 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";
 
@@ -955,7 +987,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[] } {
@@ -964,8 +996,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[] = [];
@@ -1075,16 +1112,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`);
@@ -1187,6 +1248,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) };
 }
 
@@ -2345,7 +2462,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(