@githolon/dsl 0.88.0 → 0.90.0

package/dart/lib/src/dev_cloud.dart

@@ -5,7 +5,7 @@
 //
 // ```dart
 // final cloud = await NomosTestCloud.start(serverEntry: devServerPath);   // spawns the dev cloud + proxy
-// final harness = await NomosTestHarness.cluster(cloud: cloud.origin, ...); // cloud-BOUND sessions
+// final harness = await NomosTestHarness.cloudBound(cloud: cloud, deployJsonPaths: [...], platformWorkspace: 'co2-platform', subject: 'user:test');
 // // ... author offline ...
 // cloud.setOnline(false);              // PARTITION — the up leg can't reach custody
 // await harness.session('estate').sync(admit: true);   // stays local; nothing lands remotely

package/dart/lib/src/test_harness.dart

@@ -33,6 +33,9 @@
 import 'dart:convert';
 import 'dart:io';
 
+import 'package:crypto/crypto.dart' show sha256;
+
+import 'dev_cloud.dart';
 import 'node_runner_transport.dart';
 import 'webview_bridge.dart' show NomosBridge, NomosSession;
 
@@ -147,6 +150,25 @@ class NomosTestHarness {
   /// When set, overrides EVERY phase's default deadline (see [HarnessPhaseTimeout]).
   final Duration? _phaseTimeout;
 
+  /// The test cloud a [cloudBound] harness runs against (null for the offline constructors). Partition it
+  /// with [NomosTestCloud.setOnline]; assert remote custody with [NomosTestCloud.remoteHead].
+  final NomosTestCloud? testCloud;
+
+  /// The HOME workspace a [cloudBound] harness mounted (born remotely by the platform ceremony). Null for
+  /// the offline constructors.
+  final String? homeWorkspace;
+
+  /// The mounted home as a [NomosSession] (the [cloudBound] app-shaped entry point — bind the generated
+  /// `HomeClient` to it). Throws for an offline harness (no home ceremony ran).
+  NomosSession get homeSession {
+    final ws = homeWorkspace;
+    if (ws == null) {
+      throw NomosTestHarnessException(
+          'homeSession is only available on a cloudBound harness (this one was built by ephemeral/cluster)');
+    }
+    return session(ws);
+  }
+
   NomosTestHarness._(this.bridge, this.workspace, this._transport, this._workdir,
       this._onDiagnostic, List<String> sessionNames,
       {Map<String, String> devicePublics = const {},
@@ -154,7 +176,9 @@ class NomosTestHarness {
       Map<String, List<String>> lawHashes = const {},
       Map<String, String> snapshots = const {},
       _InstallLane? installLane,
-      Duration? phaseTimeout})
+      Duration? phaseTimeout,
+      this.testCloud,
+      this.homeWorkspace})
       : _sessionNames = List.of(sessionNames), // GROWABLE — restoreWorkspace may add a fresh session
         _devicePublics = devicePublics,
         _lawHashes = Map.of(lawHashes),
@@ -613,6 +637,226 @@ class NomosTestHarness {
     }
   }
 
+  /// CLOUD-BOUND HARNESS (co2's real-app topology): a [NomosTestCloud] plays the remote control plane, the
+  /// REAL authenticated home-birth ceremony runs REMOTELY on [platformWorkspace], and the born home is
+  /// mounted into ONE local engine plane as a normal cloud-bound [NomosSession] ([homeSession]). From there
+  /// the app shape holds exactly: generated `.births()` directives run LOCALLY (the app never clones the
+  /// platform), children open as sibling sessions (`outcome.bornRefs.single.acquire(harness.bridge)`),
+  /// writes/projections work offline, and [converge] establishes remote custody parent-first when
+  /// connectivity returns ([NomosTestCloud.setOnline]). Entirely inside the test cloud's trust universe.
+  ///
+  /// ```dart
+  /// final cloud = await NomosTestCloud.start(serverEntry: devServer);
+  /// final h = await NomosTestHarness.cloudBound(
+  ///   cloud: cloud, deployJsonPaths: ['build/co2.deploy.json'],
+  ///   platformWorkspace: 'co2-platform', subject: 'user:test');
+  /// final home = h.homeSession;                    // the app's entry point
+  /// cloud.setOnline(false);                        // PARTITION
+  /// // ... local births + writes ...
+  /// cloud.setOnline(true);
+  /// await h.converge();                            // home first, then locally-born children
+  /// expect((await cloud.remoteHead(home.workspace)).initialized, isTrue);
+  /// ```
+  static Future<NomosTestHarness> cloudBound({
+    required NomosTestCloud cloud,
+    required List<String> deployJsonPaths,
+    String platformWorkspace = 'test-platform',
+    required String subject,
+    String? authToken,
+    String clientId = 'test-runner',
+    String? nodeEntry,
+    String? resolveFrom,
+    String node = 'node',
+    bool autoTearDown = true,
+    void Function(Future<void> Function())? registerTearDown,
+    void Function(String line)? onDiagnostic,
+    Duration readyTimeout = const Duration(seconds: 30),
+    Duration connectTimeout = const Duration(seconds: 120),
+    Duration? phaseTimeout,
+    bool decoySession = true,
+  }) async {
+    if (deployJsonPaths.isEmpty) {
+      throw NomosTestHarnessException(
+          'no deployJsonPaths — pass the build/<name>.deploy.json `npx githolon compile` emits');
+    }
+    final entry = nodeEntry ??
+        await _resolveEntry(node, resolveFrom ?? Directory.current.path);
+    final bareUid = subject.startsWith('user:') ? subject.substring(5) : subject;
+    final http = HttpClient();
+    Future<Map<String, Object?>> post(String path, Object? body,
+        {Map<String, String> headers = const {}}) async {
+      final req = await http.postUrl(Uri.parse('${cloud.origin}$path'));
+      req.headers.set('content-type', 'application/json');
+      req.headers.set('x-nomos-principal', bareUid);
+      if (authToken != null) req.headers.set('x-nomos-auth', authToken);
+      headers.forEach(req.headers.set);
+      if (body != null) req.add(utf8.encode(body is String ? body : jsonEncode(body)));
+      final resp = await req.close();
+      final text = await resp.transform(utf8.decoder).join();
+      final decoded = (jsonDecode(text) as Map).cast<String, Object?>();
+      if (resp.statusCode >= 300 || decoded['ok'] == false) {
+        throw NomosTestHarnessException(
+            'cloudBound setup: POST $path → ${resp.statusCode}: ${text.substring(0, text.length.clamp(0, 400))}');
+      }
+      return decoded;
+    }
+
+    final workdir = await Directory.systemTemp.createTemp('nomos-harness-');
+    NodeRunnerTransport? transport;
+    try {
+      // 1/5 — the remote control plane: create the platform workspace + deploy the law under the test
+      //       cloud's own trust universe (its K_root; nothing here touches production).
+      String? frameworkHash;
+      final lawHashes = <String>[];
+      await _phased(
+          phase: '1/5: create platform + deploy law on the test cloud',
+          workspace: platformWorkspace,
+          awaiting: 'POST /v2/workspaces + /domains',
+          timeout: phaseTimeout ?? _kInstallDeadline,
+          onDiagnostic: onDiagnostic,
+          run: () async {
+            final created = await post('/v2/workspaces/$platformWorkspace', null);
+            frameworkHash =
+                ((created['controller'] as Map?)?['domainHash'])?.toString();
+            for (final p in deployJsonPaths) {
+              final body = await File(p).readAsString();
+              await post('/v2/workspaces/$platformWorkspace/domains', body);
+              final summary = ((jsonDecode(body) as Map)['summary'] as Map?);
+              final h = summary?['domainHash']?.toString();
+              if (h != null && h.isNotEmpty) lawHashes.add(h);
+            }
+          });
+      if (frameworkHash == null || frameworkHash!.isEmpty) {
+        throw NomosTestHarnessException(
+            'cloudBound: the test cloud returned no controller.domainHash — cannot run the birth ceremony (frameworkHash unknown)');
+      }
+      if (lawHashes.isEmpty) {
+        throw NomosTestHarnessException(
+            'cloudBound: no deploy.json carried a summary.domainHash — cannot run the birth ceremony (lawHash unknown)');
+      }
+      // 2/5 — THE HOME CEREMONY, remotely: the platform's own gateway offer births the home (the ONE
+      //       control-plane contact; the app lane below never touches the platform again).
+      String? home;
+      await _phased(
+          phase: '2/5: remote home-birth ceremony',
+          workspace: platformWorkspace,
+          awaiting: 'POST /v2/workspaces/$platformWorkspace/birthHome',
+          timeout: phaseTimeout ?? _kInstallDeadline,
+          onDiagnostic: onDiagnostic,
+          run: () async {
+            final out = await post('/v2/workspaces/$platformWorkspace/birthHome', {
+              'owner': subject,
+              'frameworkHash': frameworkHash,
+              'lawHash': lawHashes.first,
+              'bornAt': DateTime.now().toUtc().toIso8601String(),
+            });
+            final born = (out['born'] as List?) ?? const [];
+            final bornNames = born.map((b) => (b as Map)['workspace']?.toString()).whereType<String>().where((w) => w.isNotEmpty).toList();
+            home = bornNames.isEmpty ? null : bornNames.first;
+            home ??= _homeNameOf(subject); // deterministic fallback (home-<sha256(subject)[..40]>)
+          });
+      // 3/5 — the LOCAL engine plane, CLOUD-BOUND (no offline env: the runner pulls the runtime + the
+      //       home's custody from the test cloud like a real device).
+      transport = await _phased(
+          phase: '3/5: spawn the node runner (cloud-bound)',
+          awaiting: 'Process.start($node)',
+          timeout: phaseTimeout ?? _kSpawnDeadline,
+          onDiagnostic: onDiagnostic,
+          run: () => NodeRunnerTransport.start(
+              entry: entry, resolveFrom: resolveFrom, node: node, onDiagnostic: onDiagnostic));
+      final plane = NomosBridge(transport!);
+      await _phased(
+          phase: '4/5: runner ready',
+          awaiting: "event:'ready'",
+          timeout: phaseTimeout ?? readyTimeout,
+          onDiagnostic: onDiagnostic,
+          run: () => plane.ready);
+      // 5/5 — mount the born home as a normal cloud-bound session (clone from the test cloud).
+      await _phased(
+          phase: '5/5: mount the born home',
+          workspace: home,
+          awaiting: 'connect(cloud:, workspace: $home)',
+          timeout: phaseTimeout ?? connectTimeout,
+          onDiagnostic: onDiagnostic,
+          run: () => plane.connect(
+                cloud: cloud.origin,
+                workspace: home!,
+                clientId: clientId,
+                authToken: authToken,
+              ));
+      // NO DECOY on a cloudBound harness: the app is genuinely multi-workspace (the home plus every
+      // locally-born child), so the plane is never sole-session — the decoy the offline  harness
+      // needs (to break single-session inference) would just be a spurious local-only workspace here.
+      final _ = decoySession; // (accepted for signature parity; a cloudBound plane needs no decoy)
+      final harness = NomosTestHarness._(
+        plane.session(home!),
+        home!,
+        transport,
+        workdir,
+        onDiagnostic,
+        [home!],
+        frameworkHash: frameworkHash,
+        lawHashes: {home!: lawHashes},
+        phaseTimeout: phaseTimeout,
+        testCloud: cloud,
+        homeWorkspace: home,
+      );
+      if (autoTearDown && registerTearDown != null) {
+        registerTearDown(() => harness.dispose());
+      }
+      return harness;
+    } catch (e) {
+      try { transport?.dispose(); } catch (_) {}
+      try { await workdir.delete(recursive: true); } catch (_) {}
+      rethrow;
+    } finally {
+      http.close(force: true);
+    }
+  }
+
+  /// The framework home-slot derivation (`home-<sha256(subject)[0..40]>`) — the fallback when the birth
+  /// offer response carries no `born` surface (an older dev cloud).
+  static String _homeNameOf(String subject) =>
+      'home-${sha256.convert(utf8.encode(subject)).toString().substring(0, 40)}';
+
+  /// CONVERGE local custody with the test cloud (co2 topology step 8): sync every connected session —
+  /// PARENT-FIRST by connect order, so the home's chain lands remotely and its birth offer-effects create
+  /// each locally-born child's remote custody BEFORE that child's own sync converges against it. Repeats
+  /// until every session reports neither `pushFailed` nor `stillAhead`, or [timeout] (then throws with the
+  /// per-workspace last verdicts). Returns the final sync result per workspace.
+  Future<Map<String, Map<String, Object?>>> converge(
+      {Duration timeout = const Duration(seconds: 120), List<String>? workspaces}) async {
+    // Every LIVE session on the plane (not the harness's construction-time list — a locally-born child
+    // acquired after construction must converge too), PARENT-FIRST: the home syncs before its children, so
+    // its birth offer-effect creates each child's remote custody BEFORE that child pushes its own writes.
+    final live = bridge.connectedSessions.where((w) => w != _decoyWorkspace).toList();
+    final hw = homeWorkspace;
+    if (hw != null && live.remove(hw)) live.insert(0, hw); // the parent leads
+    final targets = workspaces ?? live;
+    final last = <String, Map<String, Object?>>{};
+    final pending = List.of(targets);
+    final deadline = DateTime.now().add(timeout);
+    while (pending.isNotEmpty) {
+      for (final ws in List.of(pending)) {
+        try {
+          final r = (await bridge.session(ws).sync(admit: true)).cast<String, Object?>();
+          last[ws] = r;
+          if (r['pushFailed'] != true && r['stillAhead'] != true) pending.remove(ws);
+        } catch (e) {
+          last[ws] = {'error': e.toString()};
+        }
+      }
+      if (pending.isEmpty) break;
+      if (DateTime.now().isAfter(deadline)) {
+        throw NomosTestHarnessException(
+            'converge: ${pending.length} workspace(s) did not converge within ${timeout.inSeconds}s — '
+            '${pending.map((w) => '$w: ${jsonEncode(last[w] ?? {})}').join('; ')}');
+      }
+      await Future<void>.delayed(const Duration(milliseconds: 500));
+    }
+    return last;
+  }
+
   // ── CUSTODY DIAGNOSTIC HELPERS (architecture/session_bound_clients.md ask 9) ──
 
   /// The raw multi-workspace plane under [bridge] (the session handle a single-workspace harness

package/dart/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.56.0
+version: 0.57.0
 
 environment:
   sdk: ^3.5.0

package/dart/test/cloud_bound_topology_test.dart

@@ -0,0 +1,140 @@
+// THE CLOUD-BOUND TOPOLOGY ACCEPTANCE (co2's exact 10-step ask) — the real-app shape end-to-end:
+//
+//   1. the remote platform births the home (the ONE control-plane contact — the authenticated ceremony);
+//   2. the app mounts the home locally (a normal cloud-bound NomosSession; co2-platform is never cloned);
+//   3. the network PARTITIONS (NomosTestCloud.setOnline(false));
+//   4. the home births the estate LOCALLY (`birthEstateWorkspace` — a `.births()` offer on this device);
+//   5. the estate opens as a sibling session and ACCEPTS LOCAL WRITES while offline;
+//   6. UI-facing queries return those writes immediately (no sync awaited, ever);
+//   7. the network HEALS;
+//   8. `harness.converge()` establishes remote custody PARENT-FIRST (the home's synced chain folds the
+//      birth offer-effect remotely, creating the estate's custody; then the estate converges against it);
+//   9. a FRESH observer (the dev cloud's own remote projection) sees the estate writes;
+//  10. custody is REAL on both: remote heads born with commits (the dev cloud adopted the chains through
+//      the same gate everything else uses — replay IS validation).
+//
+// Entirely inside the test cloud's trust universe: nothing here touches production K_root or custody.
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+String get _root => '${Directory.current.path}/../..';
+String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.mjs';
+String get _devServer => '$_root/cloud/dev-server/server.mjs';
+String get _deploy =>
+    '$_root/bench/scale/fixtures/cloud-topology/build/cloud-topology.deploy.json';
+const _subject = 'user:topology-test';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  if (!File(_devServer).existsSync()) return 'in-repo dev server not found at $_devServer';
+  if (!File(_deploy).existsSync()) {
+    return 'compile the fixture: cd bench/scale/fixtures/cloud-topology && node ../../../../dsl/compile_package.mjs — missing $_deploy';
+  }
+  return null;
+}
+
+void main() {
+  test('the co2 topology: remote home ceremony → local estate birth offline → converge → remote custody',
+      () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final diag = Platform.environment['NOMOS_HARNESS_DIAG'] == '1'
+        ? (String l) => stderr.writeln(l)
+        : null;
+    final cloud = await NomosTestCloud.start(serverEntry: _devServer, onDiagnostic: diag);
+    NomosTestHarness? harness;
+    try {
+      // 1+2 — the remote ceremony + the local mount, in one constructor (the app's boot path).
+      harness = await NomosTestHarness.cloudBound(
+        cloud: cloud,
+        deployJsonPaths: [_deploy],
+        platformWorkspace: 'topology-platform',
+        subject: _subject,
+        nodeEntry: _repoEntry,
+        onDiagnostic: diag,
+      );
+      final home = harness.homeSession;
+      expect(home.workspace, startsWith('home-'),
+          reason: 'the remote ceremony born the deterministic home slot');
+      final remoteHome = await cloud.remoteHead(home.workspace);
+      expect(remoteHome.initialized, isTrue,
+          reason: 'the home was born REMOTELY (custody exists before the app ever mounted it)');
+
+      // 3 — PARTITION.
+      cloud.setOnline(false);
+
+      // 4 — the home births the estate LOCALLY (the app lane never needs the network).
+      final outcome = await harness.bridge.session(home.workspace).offerCreates(
+        domain: 'home',
+        directiveId: 'birthEstateWorkspace',
+        payload: {
+          'owner': _subject,
+          'frameworkHash': harness.frameworkHash,
+          'lawHash': harness.lawHashes(home.workspace).first,
+          'bornAt': '2026-07-14T00:00:00Z',
+        },
+        actor: _subject,
+      );
+      expect(outcome.born, isNotEmpty, reason: 'the local .births() offer spawned the estate');
+      final estateWs = outcome.born.single;
+      expect(estateWs, startsWith('estate-'));
+
+      // 5 — the estate opens as a sibling session and accepts a LOCAL WRITE while offline.
+      final estate = await harness.bridge.acquireSession(estateWs);
+      await estate.offerCreates(
+        domain: 'estate',
+        directiveId: 'writeEstateNote',
+        payload: {'author': _subject, 'body': 'written offline', 'writtenAt': '2026-07-14T00:00:01Z'},
+        actor: _subject,
+      );
+
+      // 6 — the UI-facing query returns the write IMMEDIATELY (local projection; nothing awaited sync).
+      final localRows = await estate.query('notesByAuthor', {'author': _subject});
+      expect(localRows, hasLength(1));
+      expect((localRows.single['data'] as Map)['body'], 'written offline');
+
+      // …and the estate has NO remote custody yet — the partition is real.
+      final remoteEstateOffline = await cloud.remoteHead(estateWs);
+      expect(remoteEstateOffline.initialized, isFalse,
+          reason: 'while partitioned, the locally-born estate must have NO remote custody');
+
+      // 7+8 — HEAL, then converge parent-first (home's chain lands; its birth offer-effect creates the
+      // estate's remote custody; the estate then converges against it).
+      cloud.setOnline(true);
+      await harness.converge(timeout: const Duration(seconds: 180));
+
+      // 9 — a FRESH observer: the dev cloud's own remote projection serves the estate write.
+      final http = HttpClient();
+      try {
+        final req = await http.getUrl(Uri.parse(
+            '${cloud.origin}/v2/workspaces/$estateWs/notesByAuthor?author=${Uri.encodeQueryComponent(_subject)}'));
+        final resp = await req.close();
+        final body = jsonDecode(await resp.transform(utf8.decoder).join());
+        final rows = ((body as Map)['rows'] as List?) ?? const [];
+        expect(rows, hasLength(1),
+            reason: 'the remote projection (a fresh observer) serves the offline-written note after converge');
+        expect(((rows.single as Map)['data'] as Map)['body'], 'written offline');
+      } finally {
+        http.close(force: true);
+      }
+
+      // 10 — custody is REAL on both (the dev cloud adopted the chains through the one gate).
+      final remoteHome2 = await cloud.remoteHead(home.workspace);
+      final remoteEstate2 = await cloud.remoteHead(estateWs);
+      expect(remoteHome2.initialized, isTrue);
+      expect(remoteHome2.commits, greaterThan(0));
+      expect(remoteEstate2.initialized, isTrue,
+          reason: 'converge established the estate\'s remote custody (parent birth folded remotely)');
+      expect(remoteEstate2.commits, greaterThan(0));
+    } finally {
+      try { await harness?.dispose(); } catch (_) {}
+      await cloud.stop();
+    }
+  }, timeout: const Timeout(Duration(minutes: 6)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.88.0",
+  "version": "0.90.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/codegen_dart.ts

@@ -2139,8 +2139,32 @@ function emitDartContractClass(c: import("./contract.js").ContractHandle): strin
  * import header so `compile_package_main`'s uniform rewrite (→ vendored relative / → nomos_types) applies;
  * the classes themselves reference only nomos_types primitives (+ shared VO classes), so the file is PURE.
  */
-export function generateDartContracts(contracts: readonly import("./contract.js").ContractHandle[]): string {
+export function generateDartContracts(
+  contracts: readonly import("./contract.js").ContractHandle[],
+  opts: {
+    /** The shared `nomos_framework.dart` import URI when that file exists — contract-used VOs (e.g. a
+     *  `ReferenceCode.field()`) render inside the DTOs, and their classes are HOISTED there (layer-zero),
+     *  so contracts.dart must import it (co2 #117b). */
+    readonly frameworkImportUri?: string;
+    /** Local aggregates' typed-id class names — a contract named after a local aggregate must NOT
+     *  re-declare its `<X>Id` (the aggregate's own class, with `.fromRow`, already exists). */
+    readonly aggregateIdClassNames?: ReadonlySet<string>;
+  } = {},
+): string {
   const sorted = [...contracts].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  // CONTRACT TYPED IDS (co2 #117a): `idOf(SomeContract)` in a payload types the field `<ContractId>Id` —
+  // exactly like an aggregate's typed id — but a contract has no aggregate emitter to declare the class.
+  // Emit each contract's id as a ZERO-COST String extension type here (the shared layer every domain
+  // imports): a const ctor from the wire string + `.value` — the exact surface the generated payloads use.
+  const idTypes = sorted
+    .map((c) => typedIdClassForAggregateType(c.id))
+    .filter((cls) => !(opts.aggregateIdClassNames?.has(cls) ?? false))
+    .map((cls) => [
+      `/// TYPED CONTRACT ID \`${cls}\` — a ZERO-COST nominal String (Dart extension type): the id of the`,
+      `/// foreign aggregate behind the contract, as \`idOf(<Contract>)\` payload fields carry it. Construct`,
+      `/// it from a \`ForeignRef.id\` / a queried row id: \`${cls}(ref.id)\`; \`.value\` is the wire string.`,
+      `extension type const ${cls}(String value) {}`,
+    ].join("\n"));
   return [
     `// GENERATED by nomos-compile — the package's shared domain CONTRACTS (public DTOs). DO NOT EDIT.`,
     `// Every domain depends on this shared layer; no domain imports another's concrete types (the acyclic graph).`,
@@ -2149,6 +2173,9 @@ export function generateDartContracts(contracts: readonly import("./contract.js"
     `library;`,
     ``,
     `import 'package:nomos_client/nomos_client.dart';`,
+    ...(opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),
+    ``,
+    ...idTypes,
     ``,
     ...sorted.map(emitDartContractClass),
     ``,
@@ -4250,7 +4277,9 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   const brandNames = new Set<string>();
   const walkUnitField = (f: ValueObjectFieldDescriptor): void => {
     if (f.type === "number" && f.unit !== undefined) unitNames.add(f.unit);
-    else if (f.type === "string" && f.brand !== undefined) brandNames.add(f.brand);
+    // A standalone brandedId declares its own extension type; an idOf REFERENCE does NOT — the aggregate
+    // emits the canonical `<Agg>Id` class (with `.fromRow`), so re-declaring it here dup'd the symbol (co2).
+    else if (f.type === "string" && f.brand !== undefined && f.idOf === undefined) brandNames.add(f.brand);
     else if (f.type === "array") walkUnitField(f.items);
     else if (f.type === "map") walkUnitField(f.values);
   };

package/src/codegen_proof.ts

@@ -48,7 +48,7 @@ import { clearDirectiveId } from "./clear_directive.js";
 import { voMetaOf, voSample } from "./value_object.js";
 import { mintedCreateField } from "./workspace_routing.js";
 import { deterministicPorts } from "./ctx.js";
-import { __setDispatchDomain } from "./framework/relations.js";
+import { __setDispatchDomain, __setDispatchContext } from "./framework/relations.js";
 import { __resetBirths, __drainBirths } from "./births.js";
 import { __resetAuthoring, __drainAuthoring } from "./authoring.js";
 import { __resetReads, __drainReads } from "./read.js";
@@ -127,10 +127,20 @@ function uniquifyBirthPayload(
   disc: string,
   schema: z.ZodTypeAny | undefined,
 ): Record<string, unknown> {
+  // Deterministic 12-hex discriminator for FORMAT-CONSTRAINED samples (a uuid-shaped subject can't take a
+  // `-<disc>` suffix — the field schema would refuse it; vary the uuid TAIL instead, format-preserving).
+  const discHex = [...disc].reduce((h, ch) => (Math.imul(h, 31) + ch.charCodeAt(0)) >>> 0, 7).toString(16).padStart(8, "0").repeat(2).slice(0, 12);
   const suffixed: Record<string, unknown> = {};
   let changed = false;
   for (const [k, v] of Object.entries(payload)) {
     if (typeof v === "string" && v.startsWith("sample-")) { suffixed[k] = `${v}-${disc}`; changed = true; }
+    else if (typeof v === "string" && v.includes(ZERO_UUID)) {
+      // The synthesized subject/uuid sentinel — uniquify the tail so sibling birth legs derive DISTINCT
+      // deterministic child names (co2 #118 follow-on: six gated births each parentSetup-birthed the SAME
+      // home — the second one found it already born, `born=[]`, and the leg died).
+      suffixed[k] = v.replace(ZERO_UUID, `00000000-0000-0000-0000-${discHex}`);
+      changed = true;
+    }
     else suffixed[k] = v;
   }
   if (!changed) return payload;
@@ -151,11 +161,28 @@ function uniquifyBirthPayload(
   return suffixed;
 }
 
+// Constrained-string candidates probed against a field's OWN schema when the readable `sample-<field>`
+// fails it (a `.regex()/.length()/.email()/.url()` bound — co2: a locale-pattern `defaultLocale` was
+// handed `sample-defaultLocale`, violating its own schema and killing the whole leg downstream). Ordered
+// common-first; the READABLE sample stays the first try so unconstrained fields are byte-stable.
+const STRING_CANDIDATES: readonly string[] = [
+  "sample", "en", "en-GB", "AA", "A1", "a", "1", "2026-01-01", "2026-01-01T00:00:00Z",
+  "a@example.com", "https://example.com", "#000000", "00000000-0000-0000-0000-000000000000",
+  "0000000000000000000000000000000000000000000000000000000000000000", // a 64-hex digest
+];
 function sampleString(zt: z.ZodTypeAny, field: string): string {
   const readable = `sample-${field}`;
   if (zt.safeParse(readable).success) return readable;
   for (const cand of SUBJECT_CANDIDATES) if (zt.safeParse(cand).success) return cand;
-  return readable;
+  for (const cand of STRING_CANDIDATES) if (zt.safeParse(cand).success) return cand;
+  // NO INVALID SAMPLE (co2): returning a schema-violating string poisons every consumer downstream (the
+  // recipe probe, the proof leg, the generated .mts) with a mystery refusal — throw NAMED instead (the
+  // callers' try/catch degrades to the same honest skip an unsynthesizable shape gets).
+  throw new Error(
+    `codegen-proof: field '${field}': no sample satisfies its own string schema (a .regex()/.length() ` +
+      `bound none of the ${1 + SUBJECT_CANDIDATES.length + STRING_CANDIDATES.length} candidates fit) — ` +
+      `loosen the pattern, or prove that directive by hand in test/e2e.mts`,
+  );
 }
 
 // Candidate numbers probed against a field's own schema (in a sensible order) so a `.min()/.max()/
@@ -1408,7 +1435,17 @@ export function discoverRelationBootstrapLeg(mod: DomainModule, gatedOverride?:
   //   (2) COMPUTED-BASE: when R is computed, walk the relation-schema rewrite for the directly-grantable BASE
   //       relations B (e.g. gate `estateMember` → `estateOwner`/`admin`), and find a granter for a base —
   //       granting B makes the actor satisfy R through the computed chain (what estate's seed does).
-  const candidates = directives.filter((d) => d !== gated && typeof d?.payloadSchema === "object" && d.birthsChild !== true);
+  // A `.delegatedRole(...)` granter verifies a SIGNED delegation cert no synthesizer can produce — it can
+  // never be seated by a proof (the cert gate refuses the sample), so it is NOT a candidate (the computed-
+  // base/seed lanes then find the law's seatable path instead — co2 #118: acceptDelegatedCatalogueCreator
+  // shadowed seedHomeCreator and the leg died on the cert gate).
+  const candidates = directives.filter(
+    (d) =>
+      d !== gated &&
+      typeof d?.payloadSchema === "object" &&
+      d.birthsChild !== true &&
+      (d as { delegatedRoleGate?: unknown }).delegatedRoleGate === undefined,
+  );
   // ALL granters of `rel`, ordered: `.grants(R)` markers first (unambiguous), then plan-probed `writeTuple(R)`.
   const findGrantersFor = (rel: string): { granter: Directive<unknown>; via: "marker" | "inferred" }[] => {
     const out: { granter: Directive<unknown>; via: "marker" | "inferred" }[] = [];
@@ -1948,7 +1985,7 @@ export function discoverChildBirthLegOrReason(
     const seedDir = (childMod.directives as Directive<unknown>[]).find((d) => d?.id === childSeedDirectiveId);
     if (seedDir !== undefined) {
       childSeedAggregateId = seedDir.aggregateId;
-      childSeedInstanceId = discoverSingletonInstanceId(seedDir);
+      childSeedInstanceId = discoverSingletonInstanceId(seedDir, childMod);
       const q = ((childMod.queries ?? []) as QueryDecl[]).find((qq) => qq.returns === seedDir.aggregateId && qq.key.length > 0);
       if (q !== undefined) childQuery = { id: q.id, key: q.key };
     }
@@ -2038,7 +2075,19 @@ function attachParentSetup(leg: ChildBirthLeg, allBirths: readonly ChildBirthLeg
 /** Discover the SINGLETON instance id a seed directive writes (a fixed `<Agg>:self`-shaped id), by running
  *  its plan with a probe payload + birth-probe globals and reading the first written op's instance id when
  *  it is a constant (the same id across two distinct probe payloads). `undefined` ⇒ not a fixed singleton. */
-function discoverSingletonInstanceId(seedDir: Directive<unknown>): string | undefined {
+function discoverSingletonInstanceId(seedDir: Directive<unknown>, ownerMod?: DomainModule): string | undefined {
+  // RELATION-NAMESPACING PARITY (co2 #118 follow-on): the ENGINE qualifies a `writeTuple` object token /
+  // bare `<type>:<id>` by the dispatching domain (`<domain>__<type>`) for the domain's local non-global
+  // relationTypes — so the FOLDED tuple's instance id is the QUALIFIED one. Probe under the same dispatch
+  // context (the same classification the engine builds), else the discovered singleton id is the bare
+  // variant and the runner's read-back misses the row the genesis actually seeded.
+  const qualifiable = new Set<string>();
+  for (const rt of (ownerMod?.relationTypes ?? []) as unknown as Array<{ type: string; global?: boolean; relations: Map<string, unknown> | Record<string, unknown> }>) {
+    if (rt.global === true) continue;
+    const rels = rt.relations instanceof Map ? [...rt.relations.keys()] : Object.keys(rt.relations ?? {});
+    for (const rel of rels) qualifiable.add(`${rt.type}#${rel}`);
+  }
+  const domain = ownerMod !== undefined ? (ownerMod.domain ?? ownerMod.name) : undefined;
   const idsFor = (seed: number): string | undefined => {
     let synth: SynthesizedPayload;
     try {
@@ -2056,6 +2105,9 @@ function discoverSingletonInstanceId(seedDir: Directive<unknown>): string | unde
       __resetAuthoring();
       __resetReads();
       __resetBirths();
+      // Probe under the OWNER DOMAIN's dispatch context so a relation-tuple singleton id qualifies exactly
+      // as the engine folds it (`<domain>__<type>:…`) — see the qualifiable set built above.
+      if (domain !== undefined) __setDispatchContext({ domain, qualifiable });
       try {
         const returned = seedDir.plan(payload as never, deterministicPorts({ physical: seed, replica: 1 }));
         const ops = [...__drainAuthoring(), ...(Array.isArray(returned) ? returned : [])];
@@ -2064,6 +2116,7 @@ function discoverSingletonInstanceId(seedDir: Directive<unknown>): string | unde
       } catch {
         id = undefined;
       } finally {
+        if (domain !== undefined) __setDispatchContext(undefined);
         try { __drainReads(); __drainBirths(); } catch { /* drained */ }
       }
     });
@@ -2320,10 +2373,13 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
       const uniq = uniquifyBirthPayload(withParent.birthPayload, b.birthDirectiveId, schema);
       if (uniq !== withParent.birthPayload) withParent = { ...withParent, birthPayload: uniq };
     }
-    // A GATED birth with no parent-birth authority path: seat its relation via the SAME granter/seed
-    // discovery the relation-bootstrap leg uses (the law's own authority path, e.g. co2's
-    // seedPlatformFounder → seedPlatformAdmin → grantCo2EstateCreator → birthEstateWorkspace).
-    if (withParent.birthRequiresRelation !== undefined && withParent.parentSetup === undefined) {
+    // A GATED birth: seat its relation via the SAME granter/seed discovery the relation-bootstrap leg uses
+    // (the law's own authority path, e.g. co2's seedPlatformFounder → seedPlatformAdmin →
+    // grantCo2EstateCreator → birthEstateWorkspace). ALSO when a parentSetup exists (co2 #118): a parent
+    // birth's genesis does NOT necessarily seat the gated relation (co2's homeCreator is claimed POST-birth
+    // by the owner via seedHomeCreator), so the runner seats the discovered path INSIDE the born parent —
+    // as the birth actor — before the gated birth.
+    if (withParent.birthRequiresRelation !== undefined) {
       const birthDir = (mod.directives as Directive<unknown>[]).find((d) => d?.id === b.birthDirectiveId);
       const rb = birthDir !== undefined ? discoverRelationBootstrapLeg(mod, birthDir) : undefined;
       // a born-context path proves INSIDE a born workspace — not a seatable pre-grant; leave it to the gap diagnostic.

package/src/compile_package_main.ts

@@ -47,7 +47,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { expandCapabilityExports, isCapabilityDecl } from "./capability_exports.js";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -59,6 +59,7 @@ import {
   generateDartActivityRegistry,
   collectActivityDescriptors,
   collectPayloadIdOfTargets,
+  typedIdClassForAggregateType,
   type DartImport,
   type DartRefImport,
   type DomainModule,
@@ -503,6 +504,14 @@ function collectPackageContracts(modules: readonly DomainModule[]): ContractHand
   return [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 }
 
+/** Every aggregate's generated typed-id class name across the package — the collision guard for the
+ *  contract typed-id emission (a contract named after a local aggregate must not re-declare `<X>Id`). */
+function packageAggregateIdClassNames(modules: readonly DomainModule[]): Set<string> {
+  const out = new Set<string>();
+  for (const m of modules) for (const a of m.aggregates) out.add(typedIdClassForAggregateType(a.id));
+  return out;
+}
+
 /**
  * CROSS-DOMAIN REF TRAVERSAL map (dart_codegen_parity.md §2a follow-on): every aggregate id in the package
  * → its owning domain (`domain` for the generated client class name; `name` for the sibling
@@ -578,7 +587,10 @@ interface DartSharedSymbols {
   /** The synthetic module whose emit IS `nomos_framework.dart` — undefined when nothing is shared. */
   readonly frameworkMod: DomainModule | undefined;
 }
-function collectDartSharedSymbols(modules: readonly DomainModule[]): DartSharedSymbols {
+function collectDartSharedSymbols(
+  modules: readonly DomainModule[],
+  packageContracts: readonly ContractHandle[] = [],
+): DartSharedSymbols {
   type ModDirective = DomainModule["directives"][number];
   type ModQuery = NonNullable<DomainModule["queries"]>[number];
   const frameworkAggById = new Map<string, AggregateHandle>();
@@ -600,9 +612,28 @@ function collectDartSharedSymbols(modules: readonly DomainModule[]): DartSharedS
       voDescriptorByName.set(d.name, d);
     }
   }
-  const sharedVoNames: ReadonlySet<string> = new Set(
-    [...voDomainsByName.entries()].filter(([, n]) => n > 1).map(([name]) => name),
-  );
+  // CONTRACT-USED VOs ARE LAYER-ZERO (co2 #117): a VO referenced by a contract FIELD (e.g. a
+  // `ReferenceCode.field()` inside `contract(...)`) is rendered inside `contracts.dart` — the shared layer
+  // every domain imports and which may import NO domain file (the acyclic rule). So its class must live in
+  // `nomos_framework.dart` REGARDLESS of how many domains use it (a single-domain VO would otherwise land in
+  // that domain's file, unreachable from contracts.dart). Transitive deps included (a nested VO renders too).
+  const contractVoNames = new Set<string>();
+  for (const c of packageContracts) {
+    for (const f of Object.values(c.fields)) {
+      const meta = (f as { valueObject?: { descriptor: { name: string }; dependencies: readonly { name: string }[] } }).valueObject;
+      if (meta === undefined) continue;
+      contractVoNames.add(meta.descriptor.name);
+      voDescriptorByName.set(meta.descriptor.name, meta.descriptor as NonNullable<DomainModule["valueObjects"]>[number]);
+      for (const dep of meta.dependencies) {
+        contractVoNames.add(dep.name);
+        voDescriptorByName.set(dep.name, dep as NonNullable<DomainModule["valueObjects"]>[number]);
+      }
+    }
+  }
+  const sharedVoNames: ReadonlySet<string> = new Set([
+    ...[...voDomainsByName.entries()].filter(([, n]) => n > 1).map(([name]) => name),
+    ...contractVoNames,
+  ]);
   const sharedVos = [...sharedVoNames].sort().map((name) => voDescriptorByName.get(name)!);
   const hasFrameworkSymbols =
     frameworkAggs.length > 0 || frameworkDirs.length > 0 || frameworkQueries.length > 0 || sharedVos.length > 0;
@@ -814,7 +845,8 @@ function emitDart(
   //      • QUERIES — the top-level `watch<Q>`/`read<Q>` accessors.
   //    Per-domain files SKIP each and IMPORT the shared file; clients RE-EXPORT it (Dart de-dups the
   //    same-library re-export). So a barrel over all domains needs NO `hide` clause.
-  const shared = collectDartSharedSymbols(modules);
+  const packageContracts = collectPackageContracts(modules);
+  const shared = collectDartSharedSymbols(modules, packageContracts);
   const { frameworkAggIds, frameworkDirIds, frameworkQueryIds, sharedVoNames, hasFrameworkSymbols } = shared;
   const frameworkImportUri = hasFrameworkSymbols ? `${FRAMEWORK_FILE}.dart` : undefined;
 
@@ -845,10 +877,12 @@ function emitDart(
   }
   // 2a-bis. the shared DOMAIN CONTRACTS file (`contracts.dart`) — every public DTO class, ONCE. Pure
   //         (nomos_types + VOs). A foreignRef targeting a contract imports THIS, never the concrete domain.
-  const packageContracts = collectPackageContracts(modules);
   const contractsImportUri = packageContracts.length > 0 ? `${CONTRACTS_FILE}.dart` : undefined;
   if (packageContracts.length > 0) {
-    writeGenerated(CONTRACTS_FILE, generateDartContracts(packageContracts));
+    writeGenerated(CONTRACTS_FILE, generateDartContracts(packageContracts, {
+      ...(frameworkImportUri !== undefined ? { frameworkImportUri } : {}),
+      aggregateIdClassNames: packageAggregateIdClassNames(modules),
+    }));
   }
   // 2a-ter. the shared ACTIVITY REGISTRY (`activity_registry.dart`) — the pure `renderActivity`, ONCE. Emitted
   //         iff a directive opts in via `.activity(...)` (activity-free packages stay byte-identical). Pure
@@ -1016,7 +1050,7 @@ const NOMOS_TYPES_DEP = "^0.4.1";
 // 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.56.0";
+const NOMOS_CLIENT_DEP = "^0.57.0";
 // 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).
@@ -1120,7 +1154,8 @@ function emitDartPackages(
   ];
   if (new Set(roleNames).size !== roleNames.length) fail(`dart.packages: types/client/test/compat names must be distinct`);
 
-  const shared = collectDartSharedSymbols(modules);
+  const packageContracts = collectPackageContracts(modules);
+  const shared = collectDartSharedSymbols(modules, packageContracts);
   const written: string[] = [];
   const genRel = DART_GENERATED_SUBDIR.split(path.sep).join("/");
 
@@ -1175,9 +1210,13 @@ function emitDartPackages(
   if (shared.frameworkMod !== undefined) writeTypes(FRAMEWORK_FILE, generateDartDomain(shared.frameworkMod));
   // DOMAIN CONTRACTS (layered): the shared `contracts.dart` DTO file in the TYPES package (pure —
   // nomos_types + VOs). A contract-target foreignRef imports THIS sibling, never the concrete domain.
-  const packageContracts = collectPackageContracts(modules);
   const contractsImportUri = packageContracts.length > 0 ? `${CONTRACTS_FILE}.dart` : undefined;
-  if (packageContracts.length > 0) writeTypes(CONTRACTS_FILE, generateDartContracts(packageContracts));
+  if (packageContracts.length > 0) {
+    writeTypes(CONTRACTS_FILE, generateDartContracts(packageContracts, {
+      ...(shared.frameworkMod !== undefined ? { frameworkImportUri: `${FRAMEWORK_FILE}.dart` } : {}),
+      aggregateIdClassNames: packageAggregateIdClassNames(modules),
+    }));
+  }
   // ACTIVITY REGISTRY (layered): the pure `renderActivity` in the TYPES package (nomos_types only). The
   // client resolves it through the types-package barrel (which re-exports every types file). Opt-in only.
   const packageActivity = collectActivityDescriptors(modules);
@@ -1476,6 +1515,26 @@ async function main(): Promise<void> {
   if (!existsSync(configPath)) fail(`config not found: ${configPath}`);
   const cfgDir = path.dirname(configPath);
 
+  // DUAL-INSTANCE GUARD (DX): the law's `import "@githolon/dsl"` resolves from the LAW's own node_modules,
+  // while this compiler runs from wherever it was invoked. Two DIFFERENT dsl instances silently split every
+  // module-level registry (the fluent-authoring drain, brands, markers) — plans probe empty, lints
+  // false-fire, ids drift. Detect the skew and WARN LOUDLY with the two paths (never fail — a
+  // deliberately-vendored setup may be intentional, and same-version split instances still work for
+  // compilation itself, which imports the law through the compiler's own module graph).
+  try {
+    const lawReq = createRequire(pathToFileURL(path.join(cfgDir, "noop.js")));
+    const lawDslPkg = lawReq.resolve("@githolon/dsl/package.json");
+    const ownDslPkg = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    if (path.resolve(lawDslPkg) !== path.resolve(ownDslPkg)) {
+      const vOf = (p: string): string => { try { return (JSON.parse(readFileSync(p, "utf8")) as { version?: string }).version ?? "?"; } catch { return "?"; } };
+      console.error(
+        `⚠ nomos-compile: TWO @githolon/dsl instances — the law resolves ${vOf(lawDslPkg)} at ${path.dirname(lawDslPkg)}, but this compiler runs ${vOf(path.resolve(ownDslPkg))} at ${path.dirname(path.resolve(ownDslPkg))}. ` +
+          `Split instances split the DSL's module registries (phantom lint errors, empty plan probes, id drift) — even at the same version string when the code differs. ` +
+          `Run the law package's OWN \`npx githolon compile\`, or align the two installs.`,
+      );
+    }
+  } catch { /* no dsl resolvable from the law dir (vendored/workspace setups) — nothing to compare */ }
+
   const cfgModule = (await import(pathToFileURL(configPath).href)) as { default?: PackageConfig };
   const cfg = cfgModule.default;
   if (!cfg || typeof cfg.name !== "string" || !Array.isArray(cfg.domains) || cfg.domains.length === 0) {
@@ -2683,20 +2742,67 @@ async function main(): Promise<void> {
     // false red) when `dart` is absent or the package's deps aren't resolved yet (needs `pub get`). Opt out
     // with NOMOS_SKIP_DART_ANALYZE=1.
     if (dartOut !== undefined && process.env.NOMOS_SKIP_DART_ANALYZE !== "1") {
-      try {
-        execFileSync("dart", ["analyze", "--no-fatal-warnings", dartOut], { stdio: "pipe", encoding: "utf8" });
-        console.log(`  dart ✓     generated Dart analyzes clean (compile-valid ⇒ compilable)`);
-      } catch (e) {
-        const err = e as { status?: number; stdout?: string; stderr?: string; code?: string };
-        const out = `${err.stdout ?? ""}${err.stderr ?? ""}`;
-        if (err.code === "ENOENT") {
-          console.log(`  dart —     analyze skipped (dart not on PATH); the generated Dart is UNVERIFIED`);
-        } else if (/isn't a package dependency|Target of URI doesn't exist: 'package:|run .?(dart |flutter )?pub get|No pubspec\.yaml/i.test(out) && !/\berror •/.test(out)) {
-          // Deps not resolved (pub get not run) rather than a codegen bug — skip, don't false-fail.
-          console.log(`  dart —     analyze skipped (package deps not resolved — run \`dart pub get\` in ${path.relative(process.cwd(), dartOut)}); the generated Dart is UNVERIFIED`);
-        } else {
-          fail(`the generated Dart package does NOT compile — \`dart analyze\` found errors (compile-valid must mean compilable). Fix the law/codegen or set NOMOS_SKIP_DART_ANALYZE=1 to emit anyway:\n${out.trim()}`);
+      // The emitted PACKAGE dirs (each has a pubspec.yaml): the layered emit produces several under `dartOut`;
+      // a flat emit puts one at `dartOut`. Analyze each — but RESOLVE its deps first (`dart pub get`), else
+      // the analyzer reports unresolved `package:` imports as errors and the gate can't tell a codegen bug
+      // from an un-got package (the co2 "analyze skipped → false success" trap).
+      const dOut: string = dartOut;
+      // Analyze exactly THE FILES THIS COMPILE EMITTED (`dartFiles`) — never the whole dir, which would
+      // sweep in the transactional `.nomos-bak` backup and any stale legacy-layout leftovers and judge the
+      // compile on files it did not write. First `dart pub get` each emitted PACKAGE (a dir up-chain with a
+      // pubspec) so `package:` imports resolve; a self-contained vendored emit has no pubspec (no get needed).
+      const emittedDart = dartFiles.filter((f) => f.endsWith(".dart"));
+      const pkgDirOf = (file: string): string | undefined => {
+        let dir = path.dirname(file);
+        for (let hops = 0; hops < 8; hops++) {
+          if (existsSync(path.join(dir, "pubspec.yaml"))) return dir;
+          if (path.resolve(dir) === path.resolve(dOut) || dir === path.dirname(dir)) return undefined;
+          dir = path.dirname(dir);
         }
+        return undefined;
+      };
+      // Only files under a PUB PACKAGE (a pubspec up-chain) are verifiable — a VENDORED no-pubspec emit's
+      // runtime `package:nomos_client` imports cannot resolve without a package config, so judging those
+      // files would false-fail every vendored fixture. Analyze the in-package set; note the loose remainder.
+      const inPackage = emittedDart.filter((f) => pkgDirOf(f) !== undefined);
+      const pkgDirs = [...new Set(inPackage.map(pkgDirOf).filter((d): d is string => d !== undefined))];
+      let dartMissing = false;
+      let unresolved: string | undefined;
+      for (const pkg of pkgDirs) {
+        try {
+          execFileSync("dart", ["pub", "get"], { cwd: pkg, stdio: "pipe", encoding: "utf8" });
+        } catch (e) {
+          const err = e as { code?: string; stdout?: string; stderr?: string };
+          if (err.code === "ENOENT") { dartMissing = true; break; }
+          unresolved = `${path.relative(process.cwd(), pkg)}: ${`${err.stdout ?? ""}${err.stderr ?? ""}`.trim().split("\n").slice(-3).join(" ")}`;
+        }
+      }
+      // Only analyze when EVERY package's deps resolved: `dart analyze` against an unresolved package reports
+      // every framework symbol (NomosRef, …) as undefined — a meaningless flood, not a real defect. An
+      // unresolved dep is already surfaced as UNVERIFIED below (e.g. a fixture pinning an as-yet-unpublished
+      // nomos_client — it verifies for real the moment that version lands).
+      if (!dartMissing && unresolved === undefined && inPackage.length > 0) {
+        try {
+          execFileSync("dart", ["analyze", "--no-fatal-warnings", ...inPackage], { stdio: "pipe", encoding: "utf8" });
+        } catch (e) {
+          const err = e as { code?: string; stdout?: string; stderr?: string };
+          if (err.code === "ENOENT") { dartMissing = true; }
+          else {
+            const out = `${err.stdout ?? ""}${err.stderr ?? ""}`.trim();
+            fail(`the generated Dart does NOT compile — \`dart analyze\` found errors (compile-valid must mean compilable). Fix the law/codegen or set NOMOS_SKIP_DART_ANALYZE=1 to emit anyway:\n${out}`);
+          }
+        }
+      }
+      if (dartMissing) {
+        // No `dart` on PATH — we genuinely cannot verify. Say so LOUDLY (never a `✓`), so a broken client is
+        // NOT reported as a clean compile; installing dart turns this into a real gate.
+        console.log(`  dart ⚠     UNVERIFIED — \`dart\` is not on PATH, so the generated Dart could NOT be analyzed (install dart to gate it)`);
+      } else if (unresolved !== undefined) {
+        console.log(`  dart ⚠     UNVERIFIED — \`dart pub get\` failed, so analysis is incomplete (${unresolved})`);
+      } else if (inPackage.length > 0) {
+        console.log(`  dart ✓     generated Dart analyzes clean (compile-valid ⇒ compilable)`);
+      } else if (emittedDart.length > 0) {
+        console.log(`  dart —     vendored (no pub package) emit — runtime package imports are unverifiable without a pubspec; analysis skipped (use dart.packages for a fully-gated pub package)`);
       }
     }
   }

package/src/fields.ts

@@ -170,7 +170,7 @@ export type ValueObjectFieldDescriptor =
   /** A plain string, OR a BRANDED nominal string when `brand` is present (a `brandedId(...)`
    * — the generated TS branded alias / Dart extension-type wrapper's name). Wire-identical
    * to a plain string; the brand is a compile-time nominal tag only. */
-  | { readonly type: "string"; readonly brand?: string; readonly optional?: true }
+  | { readonly type: "string"; readonly brand?: string; readonly idOf?: string; readonly optional?: true }
   /** `int: true` when the zod carried `.int()` (Dart `int`, TS `number`); `unit` when the field
    * was declared through `unit(...)` — the generated Dart extension-type wrapper's name. */
   | { readonly type: "number"; readonly int?: true; readonly unit?: string; readonly optional?: true }

package/src/value_object.ts

@@ -362,16 +362,16 @@ function describeZod(
   if (ownBrand !== undefined) return takeVoField(ownBrand as ValueObjectFieldMeta, deps);
   switch (zodKind(schema)) {
     case "string": {
-      const brand = (schema as unknown as Record<symbol, unknown>)[NOMOS_BRANDED_ID_BRAND]
-        ?? (schema as unknown as Record<symbol, unknown>)[NOMOS_IDOF_BRAND];
-      // idOf's brand is the aggregate type name; a payload idOf surfaces as `<Agg>Id`.
-      const brandName =
-        typeof (schema as unknown as Record<symbol, unknown>)[NOMOS_BRANDED_ID_BRAND] === "string"
-          ? (brand as string)
-          : typeof brand === "string"
-            ? `${brand}Id`
-            : undefined;
-      return brandName !== undefined ? { type: "string", brand: brandName } : { type: "string" };
+      const brandedBrand = (schema as unknown as Record<symbol, unknown>)[NOMOS_BRANDED_ID_BRAND];
+      const idOfAgg = (schema as unknown as Record<symbol, unknown>)[NOMOS_IDOF_BRAND];
+      // idOf(Agg) REFERENCES the aggregate's canonical typed-id class `<Agg>Id` (emitted ONCE by the
+      // aggregate) — it must NOT re-declare a standalone extension type (that duplicated the id symbol and
+      // stripped its `.fromRow`, co2). Carry `idOf` so the emitter references + imports it and skips the
+      // brand-extension-type emission. A standalone `brandedId("X")` still declares its own extension type.
+      if (typeof idOfAgg === "string") {
+        return { type: "string", brand: `${idOfAgg}Id`, idOf: idOfAgg };
+      }
+      return typeof brandedBrand === "string" ? { type: "string", brand: brandedBrand } : { type: "string" };
     }
     case "record": {
       if (zodRecordKeyKind(schema) !== "string") {