@githolon/dsl 0.86.1 → 0.88.0

package/dart/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.56.0
+
+- **NomosTestCloud (co2 #4)** — a headless, cloud-BOUND real-sync test harness: start/stop a local
+  `githolon cloud dev` (the same engine plane production runs), an online/offline PARTITION proxy
+  (`setOnline`) for deterministic link sever/heal, and remote head/commit inspection (`remoteHead`).
+  Sessions connect cloud-bound to `cloud.origin`; sync/convergence uses the existing `bridge.sync`.
+- **Typed snapshot lifecycle on NomosTestHarness (co2 #5)** — `snapshotWorkspace`/`snapshotPlane` and
+  `restoreWorkspace`/`restorePlane` over the per-workspace `export()`/`connect(restoreFrom:)`
+  primitives, with typed `WorkspaceSnapshot`/`PlaneSnapshot` (JSON round-trip, session/workspace
+  metadata). Migrate staged AppSim snapshots mechanically — no reaching into custody internals.
+- **`assertCompatible` surfaces a projection read failure (co2 #2)** as a distinct `projectionReadFailed`
+  cause (carrying the failed query) instead of reclassifying an evicted/failed session as `trulyNotDeployed`.
+
 ## 0.55.2
 
 - Session-state DX (co2): explicit workspace lifecycle `state` on `listWorkspaces()` —

package/dart/lib/nomos_headless.dart

@@ -39,6 +39,7 @@ library;
 
 export 'src/node_runner_transport.dart';
 export 'src/test_harness.dart';
+export 'src/dev_cloud.dart'; // NomosTestCloud (co2 #4 real-sync harness)
 // THE FULL SESSION SURFACE (task #86 gap 1): a headless test types everything the harness hands out —
 // [NomosSessionCredentials] (the `acquireSession` ifAbsentCredentials callback's return type),
 // [NomosBridge]/[NomosSession]/[NomosBbox]/[NomosCompat], the E2E sealing client

package/dart/lib/src/dev_cloud.dart

@@ -0,0 +1,199 @@
+// NOMOS TEST CLOUD (co2 #4) — a headless, real-sync test cloud for AppSim: start/stop a local
+// `githolon cloud dev` (the SAME engine plane production runs), front it with a PARTITION PROXY so a test can
+// go online/offline deterministically, and inspect the remote head/sequence — all sharing the production
+// bridge/session clients (the sessions connect to [origin] exactly like they connect to the real cloud).
+//
+// ```dart
+// final cloud = await NomosTestCloud.start(serverEntry: devServerPath);   // spawns the dev cloud + proxy
+// final harness = await NomosTestHarness.cluster(cloud: cloud.origin, ...); // cloud-BOUND sessions
+// // ... 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
+// cloud.setOnline(true);               // heal the partition
+// await harness.session('estate').sync(admit: true);   // converges; the write lands on remote main
+// final remote = await cloud.remoteHead('estate');      // inspect remote head + commit count
+// await cloud.stop();
+// ```
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+/// The remote custody state of one workspace on the test cloud (fork/custody inspection, co2 #4): the ledger
+/// tip the cloud serves + its commit count, read off `GET /v2/workspaces/<ws>`.
+class RemoteWorkspaceState {
+  final String workspace;
+  final bool initialized;
+  final String head;
+  final int commits;
+  const RemoteWorkspaceState({
+    required this.workspace,
+    required this.initialized,
+    required this.head,
+    required this.commits,
+  });
+  @override
+  String toString() =>
+      'RemoteWorkspaceState($workspace, ${initialized ? "born" : "unborn"}, head=${head.isEmpty ? "∅" : head.substring(0, head.length.clamp(0, 10))}, $commits commit(s))';
+}
+
+class NomosTestCloudException implements Exception {
+  final String message;
+  NomosTestCloudException(this.message);
+  @override
+  String toString() => 'NomosTestCloudException: $message';
+}
+
+class NomosTestCloud {
+  final Process _server;
+  final HttpServer _proxy;
+  final Uri _upstream; // the real dev-cloud origin the proxy forwards to
+  final HttpClient _client;
+  final void Function(String line)? _onDiagnostic;
+  bool _online = true;
+  bool _stopped = false;
+
+  NomosTestCloud._(this._server, this._proxy, this._upstream, this._client, this._onDiagnostic);
+
+  /// The base URL a cloud-BOUND session connects to (`connect(cloud: cloud.origin)`). Points at the PARTITION
+  /// PROXY, so [setOnline] deterministically severs/heals the whole plane's link to custody.
+  String get origin => 'http://${_proxy.address.host}:${_proxy.port}';
+
+  /// PARTITION control (co2 #4). `false` = OFFLINE — every request through the proxy fails fast (a severed
+  /// link), so writes stay LOCAL and syncs can't reach custody. `true` = ONLINE — traffic flows to the dev
+  /// cloud and peers converge. Deterministic: no timing races, the test decides exactly when the link exists.
+  void setOnline(bool online) {
+    _online = online;
+    _log('partition: ${online ? "ONLINE (link up)" : "OFFLINE (link severed)"}');
+  }
+
+  bool get online => _online;
+
+  /// Inspect a workspace's REMOTE head + commit count on the test cloud (custody/fork inspection). Reads the
+  /// live cloud state DIRECTLY (bypassing the partition proxy) — a test assertion about custody must see the
+  /// truth even while the app's link is partitioned OFFLINE.
+  Future<RemoteWorkspaceState> remoteHead(String workspace) async {
+    final body = await _getJson(_upstream.replace(path: '/v2/workspaces/$workspace'));
+    final ledger = (body['ledgerState'] as Map?)?.cast<String, Object?>() ?? const {};
+    return RemoteWorkspaceState(
+      workspace: workspace,
+      initialized: body['initialized'] == true,
+      head: (ledger['head'] ?? '').toString(),
+      commits: ((ledger['commits'] as num?) ?? 0).toInt(),
+    );
+  }
+
+  /// Start the test cloud: spawn `node <serverEntry> --port <n> [--ephemeral] [--data <dir>]`, wait until its
+  /// `/health` answers, then bring up the partition proxy in front of it. [serverEntry] is the dev-server
+  /// entry (`cloud/dev-server/server.mjs` in-repo, or `dist/dev-server.mjs` from a published `githolon`) — the
+  /// caller resolves it (the same seam the offline harness uses for its install helper). [node] defaults to
+  /// `node` on PATH.
+  static Future<NomosTestCloud> start({
+    required String serverEntry,
+    int port = 0,
+    bool ephemeral = true,
+    String? dataDir,
+    String node = 'node',
+    Duration readyTimeout = const Duration(seconds: 30),
+    void Function(String line)? onDiagnostic,
+  }) async {
+    final chosenPort = port == 0 ? await _freePort() : port;
+    final args = <String>[
+      serverEntry,
+      '--port', '$chosenPort',
+      if (ephemeral) '--ephemeral',
+      if (dataDir != null) ...['--data', dataDir],
+    ];
+    void log(String m) => onDiagnostic?.call('[nomos-test-cloud] $m');
+    log('spawning: $node ${args.join(' ')}');
+    final proc = await Process.start(node, args, mode: ProcessStartMode.normal);
+    proc.stdout.transform(utf8.decoder).transform(const LineSplitter()).listen((l) => log('server: $l'));
+    proc.stderr.transform(utf8.decoder).transform(const LineSplitter()).listen((l) => log('server!: $l'));
+
+    final upstream = Uri.parse('http://127.0.0.1:$chosenPort');
+    final client = HttpClient();
+    // Wait for /health.
+    final deadline = DateTime.now().add(readyTimeout);
+    var ready = false;
+    while (DateTime.now().isBefore(deadline)) {
+      try {
+        final req = await client.getUrl(upstream.replace(path: '/health'));
+        final resp = await req.close();
+        if (resp.statusCode == 200) { ready = true; await resp.drain<void>(); break; }
+        await resp.drain<void>();
+      } catch (_) {/* not up yet */}
+      await Future<void>.delayed(const Duration(milliseconds: 200));
+    }
+    if (!ready) {
+      proc.kill(ProcessSignal.sigkill);
+      throw NomosTestCloudException('the dev cloud did not answer /health within ${readyTimeout.inSeconds}s (serverEntry: $serverEntry)');
+    }
+    log('dev cloud healthy at $upstream');
+
+    // The partition proxy — forwards to the dev cloud when ONLINE, fails fast when OFFLINE.
+    final proxy = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
+    final cloud = NomosTestCloud._(proc, proxy, upstream, client, onDiagnostic);
+    proxy.listen(cloud._handleProxy);
+    log('partition proxy at ${cloud.origin} → $upstream');
+    return cloud;
+  }
+
+  Future<void> _handleProxy(HttpRequest req) async {
+    if (!_online) {
+      // OFFLINE — sever the link. Fail fast (503) so the client sees a dead-cloud, writes stay local, and a
+      // sync can't reach custody. (A 503 is the cleanest deterministic "link down" the Dart proxy can present.)
+      try {
+        req.response.statusCode = 503;
+        await req.drain<void>();
+        await req.response.close();
+      } catch (_) {}
+      return;
+    }
+    try {
+      final target = _upstream.replace(path: req.uri.path, query: req.uri.query.isEmpty ? null : req.uri.query);
+      final fwd = await _client.openUrl(req.method, target);
+      req.headers.forEach((name, values) { if (name.toLowerCase() != 'host') for (final v in values) fwd.headers.add(name, v); });
+      await fwd.addStream(req); // forward the request body
+      final resp = await fwd.close();
+      req.response.statusCode = resp.statusCode;
+      resp.headers.forEach((name, values) { for (final v in values) req.response.headers.add(name, v); });
+      await resp.pipe(req.response);
+    } catch (e) {
+      try { req.response.statusCode = 502; await req.response.close(); } catch (_) {}
+    }
+  }
+
+  Future<Map<String, Object?>> _getJson(Uri url) async {
+    final req = await _client.getUrl(url);
+    final resp = await req.close();
+    final text = await resp.transform(utf8.decoder).join();
+    if (resp.statusCode != 200) {
+      throw NomosTestCloudException('GET $url → ${resp.statusCode}: ${text.substring(0, text.length.clamp(0, 200))}');
+    }
+    return (jsonDecode(text) as Map).cast<String, Object?>();
+  }
+
+  void _log(String m) => _onDiagnostic?.call('[nomos-test-cloud] $m');
+
+  /// Deterministic teardown: close the proxy + kill the dev-server subprocess. Safe to call twice.
+  Future<void> stop() async {
+    if (_stopped) return;
+    _stopped = true;
+    _log('stopping');
+    try { await _proxy.close(force: true); } catch (_) {}
+    _server.kill(ProcessSignal.sigterm);
+    // Give it a moment, then SIGKILL if still alive.
+    try {
+      await _server.exitCode.timeout(const Duration(seconds: 5));
+    } on TimeoutException {
+      _server.kill(ProcessSignal.sigkill);
+    }
+    _client.close(force: true);
+  }
+
+  static Future<int> _freePort() async {
+    final s = await ServerSocket.bind(InternetAddress.loopbackIPv4, 0);
+    final p = s.port;
+    await s.close();
+    return p;
+  }
+}

package/dart/lib/src/session_bound.dart

@@ -79,6 +79,12 @@ enum SessionMismatchCause {
   /// The domain IS installed but its shape is older than what this client requires — the client
   /// expects a newer interface (recompile against the deployed law, or evolve the law).
   clientExpectsNewerInterface,
+
+  /// The session's PROJECTION READ itself failed terminally (an unmountable/failing query shape —
+  /// e.g. co2's compound-key mount error) — the workspace's law could NOT be read, so this is NOT
+  /// "no law deployed". The hint carries the failed query + workspace so the real fault surfaces
+  /// (co2 blocker #2 — never reclassify a projection-refresh terminal error as trulyNotDeployed).
+  projectionReadFailed,
 }
 
 /// Thrown by `XClient.bind(session)` (and by the lazy first-dispatch check of the synchronous
@@ -212,13 +218,21 @@ extension NomosSessionCompat on NomosSession {
       final offer = await interfaceOffer();
       if (offer != null) activeKeys = offer.keys.toList()..sort();
     } catch (e) {
+      // co2 blocker #2: a PROJECTION READ FAILURE (an unmountable/failing query shape — the runner surfaces
+      // `nomos.projection.read_failed` carrying the failed query) is NOT "not reachable" and MUST NOT be
+      // reclassified as trulyNotDeployed downstream — surface it as its own cause with the real fault text.
+      final isProjectionFault = e.toString().contains('nomos.projection.read_failed') ||
+          e.toString().contains('projection read failed');
       throw DomainClientSessionMismatch(
         expectedDomainKey: iface.domain,
         expectedDomainHash: iface.expectedDomainHash,
         expectedInterfaceHash: iface.expectedInterfaceHash,
         sessionId: workspace,
         sessionWorkspace: workspace,
-        hint: 'the session workspace is not reachable/mounted on this plane: $e',
+        cause: isProjectionFault ? SessionMismatchCause.projectionReadFailed : null,
+        hint: isProjectionFault
+            ? 'the workspace law could NOT be READ — a projection/mount failure (NOT undeployed law): $e'
+            : 'the session workspace is not reachable/mounted on this plane: $e',
       );
     }
 

package/dart/lib/src/test_harness.dart

@@ -148,14 +148,15 @@ class NomosTestHarness {
   final Duration? _phaseTimeout;
 
   NomosTestHarness._(this.bridge, this.workspace, this._transport, this._workdir,
-      this._onDiagnostic, this._sessionNames,
+      this._onDiagnostic, List<String> sessionNames,
       {Map<String, String> devicePublics = const {},
       this.frameworkHash,
       Map<String, List<String>> lawHashes = const {},
       Map<String, String> snapshots = const {},
       _InstallLane? installLane,
       Duration? phaseTimeout})
-      : _devicePublics = devicePublics,
+      : _sessionNames = List.of(sessionNames), // GROWABLE — restoreWorkspace may add a fresh session
+        _devicePublics = devicePublics,
         _lawHashes = Map.of(lawHashes),
         _snapshots = Map.of(snapshots),
         _installLane = installLane,
@@ -722,6 +723,75 @@ class NomosTestHarness {
     }
   }
 
+  // ── SNAPSHOT LIFECYCLE (co2 #5) — a typed async snapshot API over the per-workspace export()/restoreFrom
+  //    primitives, so staged AppSim snapshots migrate mechanically without reaching into custody internals. ──
+
+  /// Capture a typed [WorkspaceSnapshot] of one workspace's whole local holon (the bare nomos.git incl.
+  /// un-synced writes + the DLQ), with its head + law hashes + capture time. The bytes are the SAME
+  /// base64 `connect(restoreFrom:)` consumes — [restoreWorkspace] round-trips it. O(1)-ish (a tree serialize).
+  Future<WorkspaceSnapshot> snapshotWorkspace(String workspace) async {
+    final s = session(workspace); // throws NomosTestHarnessException if not a connected session
+    return _phased(
+      phase: 'snapshotWorkspace',
+      workspace: workspace,
+      awaiting: 'export',
+      timeout: _phaseTimeout ?? _kOtherDeadline,
+      onDiagnostic: _onDiagnostic,
+      run: () async {
+        final b64 = await s.export();
+        final head = await s.head();
+        return WorkspaceSnapshot(
+          workspace: workspace,
+          snapshotB64: b64,
+          head: head,
+          lawHashes: lawHashes(workspace),
+          capturedAt: DateTime.now().toUtc(),
+        );
+      },
+    );
+  }
+
+  /// Snapshot EVERY connected workspace on this plane into a typed [PlaneSnapshot] (session/workspace metadata
+  /// carried per entry). The plane-level twin of [snapshotWorkspace] — migrate a whole staged AppSim plane.
+  Future<PlaneSnapshot> snapshotPlane() async {
+    final out = <String, WorkspaceSnapshot>{};
+    for (final ws in _sessionNames) {
+      out[ws] = await snapshotWorkspace(ws);
+    }
+    return PlaneSnapshot(workspaces: Map.unmodifiable(out), capturedAt: DateTime.now().toUtc());
+  }
+
+  /// Restore a workspace FROM a [WorkspaceSnapshot] — re-open its session on this plane from the snapshot's
+  /// LOCAL CUSTODY (no network clone), replacing the resident holon. The workspace need not currently be a
+  /// session (a fresh restore is allowed); its name is taken from [snapshot] unless [into] overrides it.
+  Future<NomosSession> restoreWorkspace(WorkspaceSnapshot snapshot, {String? into}) async {
+    final ws = into ?? snapshot.workspace;
+    await _phased(
+      phase: 'restoreWorkspace',
+      workspace: ws,
+      awaiting: 'connect(restoreFrom:)',
+      timeout: _phaseTimeout ?? const Duration(seconds: 60),
+      onDiagnostic: _onDiagnostic,
+      run: () => _plane.connect(
+        workspace: ws,
+        session: ws,
+        clientId: '${_installLane?.clientId ?? 'test-runner'}-$ws',
+        restoreFrom: snapshot.snapshotB64,
+        allowUnborn: true,
+      ),
+    );
+    if (!_sessionNames.contains(ws)) _sessionNames.add(ws);
+    return bridge.session(ws);
+  }
+
+  /// Restore an entire [PlaneSnapshot] — every workspace re-opened from its snapshot. Migrates a staged plane
+  /// wholesale (the mechanical AppSim-snapshot migration co2 #5 asks for).
+  Future<void> restorePlane(PlaneSnapshot plane) async {
+    for (final entry in plane.workspaces.values) {
+      await restoreWorkspace(entry);
+    }
+  }
+
   /// Deterministic, idempotent, total-ordered teardown: stop the runner (SIGTERM → 5s deadline → SIGKILL,
   /// via [NodeRunnerTransport.dispose]), then delete the temp dir. Safe to call twice; safe to call after a
   /// failed setup. Nothing left running, nothing left on disk.
@@ -841,3 +911,65 @@ class NomosTestHarness {
     return out;
   }
 }
+
+/// A typed, self-describing snapshot of ONE workspace's local holon (co2 #5). [snapshotB64] is the exact
+/// base64 `connect(restoreFrom:)` consumes — the whole nomos.git incl. un-synced writes + the DLQ — plus the
+/// metadata that makes a staged snapshot mechanically migratable: the [workspace], its ledger [head] at
+/// capture, its installed [lawHashes], and [capturedAt] (UTC).
+class WorkspaceSnapshot {
+  final String workspace;
+  final String snapshotB64;
+  final String head;
+  final List<String> lawHashes;
+  final DateTime capturedAt;
+
+  const WorkspaceSnapshot({
+    required this.workspace,
+    required this.snapshotB64,
+    required this.head,
+    required this.lawHashes,
+    required this.capturedAt,
+  });
+
+  /// JSON round-trip so a staged snapshot persists to disk verbatim (the bytes + provenance).
+  Map<String, Object?> toJson() => {
+        'workspace': workspace,
+        'snapshotB64': snapshotB64,
+        'head': head,
+        'lawHashes': lawHashes,
+        'capturedAt': capturedAt.toUtc().toIso8601String(),
+      };
+
+  factory WorkspaceSnapshot.fromJson(Map<String, Object?> j) => WorkspaceSnapshot(
+        workspace: j['workspace'] as String,
+        snapshotB64: j['snapshotB64'] as String,
+        head: (j['head'] ?? '') as String,
+        lawHashes: ((j['lawHashes'] as List?) ?? const []).map((e) => '$e').toList(),
+        capturedAt: DateTime.parse((j['capturedAt'] ?? DateTime.now().toUtc().toIso8601String()) as String),
+      );
+
+  @override
+  String toString() =>
+      'WorkspaceSnapshot($workspace @ ${head.isEmpty ? "∅" : head.substring(0, head.length.clamp(0, 10))}, '
+      '${lawHashes.length} law(s), ${capturedAt.toIso8601String()})';
+}
+
+/// A typed snapshot of a WHOLE plane — every connected workspace keyed by name (co2 #5). Restore it with
+/// [NomosTestHarness.restorePlane] to migrate a staged multi-workspace AppSim scene wholesale.
+class PlaneSnapshot {
+  final Map<String, WorkspaceSnapshot> workspaces;
+  final DateTime capturedAt;
+
+  const PlaneSnapshot({required this.workspaces, required this.capturedAt});
+
+  Map<String, Object?> toJson() => {
+        'workspaces': workspaces.map((k, v) => MapEntry(k, v.toJson())),
+        'capturedAt': capturedAt.toUtc().toIso8601String(),
+      };
+
+  factory PlaneSnapshot.fromJson(Map<String, Object?> j) => PlaneSnapshot(
+        workspaces: ((j['workspaces'] as Map?) ?? const {}).map(
+            (k, v) => MapEntry('$k', WorkspaceSnapshot.fromJson((v as Map).cast<String, Object?>()))),
+        capturedAt: DateTime.parse((j['capturedAt'] ?? DateTime.now().toUtc().toIso8601String()) as String),
+      );
+}

package/dart/lib/testing.dart

@@ -11,3 +11,4 @@ library;
 
 export 'src/node_runner_transport.dart';
 export 'src/test_harness.dart';
+export 'src/dev_cloud.dart'; // NomosTestCloud (co2 #4 real-sync 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.55.2
+version: 0.56.0
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.86.1",
+  "version": "0.88.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_proof.ts

@@ -491,6 +491,20 @@ function authorityConformanceLegLines(
  * actor and assert it SUCCEEDS — proving that once relation R is granted, an actor holding R authors the gated
  * write (the exact loop the negative leg can't cover). Emits nothing when no granter is discoverable.
  */
+/** The canonical set of relation-bootstrap legs for a domain (co2 #2 multi-target): the `relationBootstraps[]`
+ *  array when present, else the singular `relationBootstrap` as a one-element list, else empty. */
+function allRelationBootstrapLegs(pl: ProofLegs): readonly RelationBootstrapLeg[] {
+  return pl.relationBootstraps ?? (pl.relationBootstrap !== undefined ? [pl.relationBootstrap] : []);
+}
+
+/** Emit the seed-then-prove lines for EVERY discovered gated-create authority leg (co2 #2), or — when the
+ *  domain has a gated create but NO seedable path — the single loud gap diagnostic. */
+function relationSeedLegsLines(pl: ProofLegs, factory: string, n: () => number, gap: string | undefined): string[] {
+  const legs = allRelationBootstrapLegs(pl);
+  if (legs.length === 0) return relationSeedLegLines(undefined, factory, n, gap);
+  return legs.flatMap((leg) => relationSeedLegLines(leg, factory, n, undefined));
+}
+
 function relationSeedLegLines(
   leg: RelationBootstrapLeg | undefined,
   factory: string,
@@ -605,6 +619,19 @@ function relationSeedLegLines(
   const prereqNote = (leg.prerequisiteSeeds ?? []).length > 0
     ? ` The grant needs prerequisite seed(s) [${(leg.prerequisiteSeeds ?? []).map((s) => s.directiveId).join(", ")}] run first (as the actor = founder).`
     : ``;
+  // TARGET PRECONDITION SETUPS (co2 #3): the gated establisher(s) for the target's `.requiresExisting`/`.where`
+  // parent — dispatched AFTER the grant (the actor now holds the relation), BEFORE the target, so its declared
+  // predicate (e.g. `lifecycle == "active"`) holds against the REAL parent, not a shape-only shell.
+  const precondLines = (leg.preconditionSetups ?? []).flatMap((s) => {
+    const lit = s.autoStamped.length > 0
+      ? `(() => { const p: Record<string, unknown> = { ...${JSON.stringify(s.payload)} }; ${s.autoStamped.map((f) => `p[${JSON.stringify(f)}] = new Date().toISOString();`).join(" ")} return p; })()`
+      : JSON.stringify(s.payload);
+    return [
+      `    // precondition: dispatch the REAL ${leg.domain}/${s.directiveId} (gated by "${s.requiresRelation ?? leg.relation}", already seated) so the target's declared predicate holds against real state.`,
+      `    await ${factory}(holon, { actor: ACTOR }).${s.directiveId}(${lit});`,
+      `    ok(\`relation bootstrap (precondition) — ${leg.domain}/${s.directiveId} established before ${leg.gatedDirectiveId} (real parent state, not a shell)\`);`,
+    ];
+  });
   return [
     `// ${n()}. RELATION BOOTSTRAP (seed-then-prove the POSITIVE): \`${leg.domain}/${leg.gatedDirectiveId}\` is GATED`,
     `//    (\`.requires("${leg.relation}")\`). \`${leg.domain}/${leg.grantDirectiveId}\` GRANTS "${leg.grantedRelation}" (${leg.via})${computedNote}.${prereqNote}`,
@@ -619,6 +646,7 @@ function relationSeedLegLines(
     `    // (1) grant "${leg.grantedRelation}" to ACTOR (the grant folds a writeTuple; subject seated on ACTOR).`,
     `    await ${factory}(holon, { actor: ACTOR }).${leg.grantDirectiveId}(${grantPayloadLit});`,
     `    ok(\`relation bootstrap (grant) — ${leg.domain}/${leg.grantDirectiveId} granted "${leg.grantedRelation}" to \${ACTOR}${leg.grantedRelation !== leg.relation ? ` (⇒ satisfies "${leg.relation}" via rewrite)` : ``}\`);`,
+    ...precondLines,
     `    // (2) the GATED write now SUCCEEDS under the seeded actor (holds "${leg.relation}"${leg.grantedRelation !== leg.relation ? ` via "${leg.grantedRelation}"` : ``}).`,
     `    await ${factory}(holon, { actor: ACTOR }).${leg.gatedDirectiveId}(${gatedPayloadLit});`,
     `    ok(\`relation bootstrap (prove) — ${leg.domain}/${leg.gatedDirectiveId} authored under the seeded holder of "${leg.relation}" (gated write SUCCEEDS once granted)\`);`,
@@ -712,6 +740,29 @@ export interface RelationBootstrapLeg {
    *  (each as the proof actor = founder, so their own write-once/author-binding invariants hold) BEFORE the
    *  grant — then the grant + the gated write succeed. A non-birth analog of {@link BornContextAuthority}. */
   readonly prerequisiteSeeds?: readonly PrerequisiteSeed[];
+  /** THE TARGET'S OWN PRECONDITION SETUPS (co2 #3). The gated create carries a `.requiresExisting`/`.where`
+   *  precondition reading ANOTHER aggregate by a payload-id field with a predicate (e.g. `createClassification
+   *  Draft` needs a `ClassificationScheme` at `p.schemeId` with `lifecycle == "active"`). The establishing
+   *  create (`createClassificationScheme`) is itself GATED by the SAME relation this leg already seats, and —
+   *  because the id field synthesizes deterministically to `"sample-<field>"` in BOTH — it writes the parent
+   *  at the exact id the target reads, WITH the real lifecycle its plan sets. The runner dispatches these AFTER
+   *  the grant (the actor holds the relation) and BEFORE the target, satisfying its declared predicate — not a
+   *  shape-only shell. Dependency-ordered. */
+  readonly preconditionSetups?: readonly PreconditionSetup[];
+}
+
+/** One target-precondition setup (co2 #3): a REAL create of a parent aggregate the gated target's precondition
+ *  reads, dispatched (as the actor, who holds the seated relation) BEFORE the target so its predicate holds. */
+export interface PreconditionSetup {
+  /** The establishing create directive id (e.g. `createClassificationScheme`). */
+  readonly directiveId: string;
+  /** Its synthesized payload — the id field (`.withId`) is RETAINED and matches the target's (both
+   *  `"sample-<field>"`), so it writes the parent at the exact instance the target's precondition reads. */
+  readonly payload: Record<string, unknown>;
+  readonly autoStamped: readonly string[];
+  /** The relation the establisher is gated by (informational; the runner dispatches it as the actor already
+   *  holding this leg's seated relation — the common case is the SAME relation as the target). */
+  readonly requiresRelation?: string;
 }
 
 /** One prerequisite seed the runner dispatches (as the proof actor = founder) BEFORE the grant — it
@@ -1148,11 +1199,19 @@ export function discoverBornContextAuthority(
   return undefined;
 }
 
-/** Does any workspaceInvariant fire ON `directiveId` — i.e. does that directive carry a PREREQUISITE (a
- *  declared invariant reading state another step must establish first)? A standalone replay of such a
- *  directive can FALSE-fail (the prior state is absent), so a born domain must prove via the genesis path. */
+/** Does any workspaceInvariant fire ON `directiveId` with a REAL cross-step PREREQUISITE — a declared read of
+ *  state ANOTHER step must establish first? A standalone replay of such a directive can FALSE-fail (the prior
+ *  state is absent), so a born domain must prove via the genesis path. co2 #2: a write-once SEED invariant
+ *  whose only reads are `pre:`-self-checks OR the directive's OWN output aggregate is NOT a cross-step
+ *  prerequisite (it's a self-absence check) — such a granter stays CLEAN and is a valid backtrack target. */
 function directiveHasPrerequisiteInvariant(mod: DomainModule, directiveId: string): boolean {
-  return (mod.workspaceInvariants ?? []).some((inv) => inv.on === directiveId);
+  const invs = (mod.workspaceInvariants ?? []).filter((inv) => inv.on === directiveId);
+  if (invs.length === 0) return false;
+  const dir = (mod.directives as Directive<unknown>[]).find((d) => d.id === directiveId);
+  const selfWritten = dir !== undefined ? probeWritesAggregateTypes(dir, `${mod.domain ?? mod.name}/${directiveId}`) : new Set<string>();
+  // A real prerequisite reads ≥1 aggregate this directive does NOT itself establish (pre:-self-checks already
+  // excluded in invariantReadAggregateTypes). If every read is self-written, it's a self-absence check → clean.
+  return invs.some((inv) => [...invariantReadAggregateTypes(inv)].some((agg) => !selfWritten.has(agg)));
 }
 
 /** The AGGREGATE TYPES a directive's plan writes (set/ensure/create ops) — used to find the sibling seed that
@@ -1244,6 +1303,63 @@ export function discoverPrerequisiteChain(mod: DomainModule, granter: Directive<
   return chain.length > 0 ? chain : undefined;
 }
 
+/**
+ * TARGET-PRECONDITION SETUPS (co2 #3). A gated create may carry a `.requiresExisting`/`.where` precondition
+ * reading a PARENT aggregate by a payload-id field with a predicate (e.g. `createClassificationDraft` needs a
+ * `ClassificationScheme` at `p.schemeId` with `lifecycle == "active"`). The proof must ESTABLISH that parent
+ * with REAL state — a shape-only shell fails the predicate (`classification-scheme-retired`). For each such
+ * precondition we find the parent's own create directive (`createClassificationScheme`, itself gated) and
+ * record it as a setup dispatched AFTER the grant / BEFORE the target: because the parent's id field
+ * synthesizes to the SAME `"sample-<field>"` the target reads, it writes the parent at the exact instance,
+ * WITH the lifecycle its real plan sets. Skips a self-precondition (the target's own aggregate) and any parent
+ * with no discoverable create (the predicate then arbitrates at the real gate — never a false green).
+ */
+function discoverPreconditionSetups(mod: DomainModule, gated: Directive<unknown>): PreconditionSetup[] {
+  const domain = mod.domain ?? mod.name;
+  const invariants = (mod.workspaceInvariants ?? []) as Array<WorkspaceInvariantDecl>;
+  const directives = mod.directives as Directive<unknown>[];
+  const gatedWrites = probeWritesAggregateTypes(gated, `${domain}/${gated.id}`);
+  const setups: PreconditionSetup[] = [];
+  const seen = new Set<string>();
+  for (const inv of invariants) {
+    if (inv.on !== gated.id) continue; // preconditions on THIS target only
+    for (const aggType of invariantReadAggregateTypes(inv)) {
+      if (gatedWrites.has(aggType)) continue; // self-precondition — the target establishes it in its own apply
+      // The parent's own ESTABLISHER — a directive that WRITES `aggType` at a DETERMINISTIC (dev-chosen) key:
+      // an `.ensures(<aggType>)` keyed upsert (the kernel's sanctioned non-minted-id lane), or a create-once
+      // (`.withId`). Its id field synthesizes to the SAME `"sample-<field>"` the target's precondition reads,
+      // so it writes the parent at the exact instance WITH the state its real plan sets. A truly MINTED
+      // `.creates` (kernel `<Type>_<uuid>`) has NO dev-chosen id to match the target's synthesized id — its
+      // raw-id create is refused by the mint gate anyway — so it is NOT a usable establisher here (the real
+      // gate then arbitrates the target, never a false green).
+      const creator = directives.find((d) => {
+        if (d === gated || typeof d?.payloadSchema !== "object" || d.birthsChild === true) return false;
+        if (!probeWritesAggregateTypes(d, `${domain}/${d.id}`).has(aggType)) return false;
+        const isEnsures = d.marker === "ensures";
+        const isCreateOnce = d.marker === "creates" && (d as { createOnceIdField?: unknown }).createOnceIdField !== undefined;
+        return isEnsures || isCreateOnce;
+      });
+      if (creator === undefined) continue;
+      if (seen.has(creator.id)) continue;
+      let synth: SynthesizedPayload;
+      try {
+        synth = synthesizePayload(creator.payloadSchema as z.ZodTypeAny, `${domain}/${creator.id}`);
+      } catch {
+        continue;
+      }
+      const payload: Record<string, unknown> = { ...synth.value };
+      seen.add(creator.id);
+      setups.push({
+        directiveId: creator.id,
+        payload,
+        autoStamped: synth.autoStamped,
+        ...(creator.requiresRelationGate !== undefined ? { requiresRelation: creator.requiresRelationGate.relation } : {}),
+      });
+    }
+  }
+  return setups;
+}
+
 /** Discover the RELATION-BOOTSTRAP leg for a module: the first gated (`.requires(R)`) directive plus the
  *  sibling that ESTABLISHES the actor's authority for R. In priority order: (1) a DIRECT granter of R (a
  *  `.grants(R)` marker or a plan-probed `writeTuple(R)`) — the original lane; (2) REWRITE-AWARE — when R is
@@ -1293,20 +1409,39 @@ export function discoverRelationBootstrapLeg(mod: DomainModule, gatedOverride?:
   //       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);
-  const findGranterFor = (rel: string): { granter: Directive<unknown>; via: "marker" | "inferred" } | undefined => {
-    const marked = candidates.find((d) => (d.grantsRelation ?? []).includes(rel));
-    if (marked !== undefined) return { granter: marked, via: "marker" };
-    const inferred = candidates.find((d) => probeGrantsRelation(d, rel, `${domain}/${d.id}`));
-    return inferred !== undefined ? { granter: inferred, via: "inferred" } : 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" }[] = [];
+    for (const d of candidates) if ((d.grantsRelation ?? []).includes(rel)) out.push({ granter: d, via: "marker" });
+    for (const d of candidates) if (!out.some((o) => o.granter === d) && probeGrantsRelation(d, rel, `${domain}/${d.id}`)) out.push({ granter: d, via: "inferred" });
+    return out;
   };
+  const findGranterFor = (rel: string): { granter: Directive<unknown>; via: "marker" | "inferred" } | undefined => findGrantersFor(rel)[0];
 
-  // (1) direct grant of R.
+  // (1) direct grant of R — WITH BACKTRACKING (co2 #2 "standards"): several directives may grant R (e.g. a
+  // workspace seed AND a generated administrator seed both write `admin`). PREFER a CLEAN granter (no
+  // prerequisite invariant → a standalone re-seat just works); else the FIRST granter whose prerequisite chain
+  // is satisfiable; else the first (the runner then names the gap). This backtracks instead of accepting the
+  // first `writeTuple(R)` match, which could be an unsuitable seed (the co2 symptom).
   let grantedRelation = relation;
   let via: "marker" | "inferred" | "computed-base" | "seed-path" = "marker";
   let seedSpeculative = false;
   let seedWritesRelations: string[] | undefined;
   let prerequisiteSeeds: PrerequisiteSeed[] | undefined;
-  let found = findGranterFor(relation);
+  const directGranters = findGrantersFor(relation);
+  let found: { granter: Directive<unknown>; via: "marker" | "inferred" } | undefined;
+  {
+    const clean = directGranters.find((g) => !directiveHasPrerequisiteInvariant(mod, g.granter.id));
+    if (clean !== undefined) {
+      found = clean;
+    } else {
+      for (const g of directGranters) {
+        const chain = discoverPrerequisiteChain(mod, g.granter);
+        if (chain !== undefined) { found = g; prerequisiteSeeds = chain; break; }
+      }
+      if (found === undefined) found = directGranters[0]; // none clean/satisfiable — keep the first (gap named at runtime)
+    }
+  }
   if (found !== undefined) {
     via = found.via;
   } else {
@@ -1429,9 +1564,44 @@ export function discoverRelationBootstrapLeg(mod: DomainModule, gatedOverride?:
     ...(seedWritesRelations !== undefined ? { seedWritesRelations } : {}),
     ...(prerequisiteSeeds !== undefined ? { prerequisiteSeeds } : {}),
     ...(granterAuthority !== undefined ? { granterAuthority } : {}),
+    ...((() => { const ps = discoverPreconditionSetups(mod, gated); return ps.length > 0 ? { preconditionSetups: ps } : {}; })()),
   };
 }
 
+/**
+ * MULTI-TARGET relation-bootstrap discovery (co2 ask #2). The singular {@link discoverRelationBootstrapLeg}
+ * proves ONE gated create per domain; this runs TARGET-SPECIFIC discovery for EVERY gated create/write, so a
+ * domain with (say) owner-, editor-, and publisher-gated creates emits ONE positive authority leg PER gated
+ * create instead of proving one and falsely labelling the rest `no seedable authority path found`. Each
+ * target reuses the same granter/seed/prerequisite discovery via the `gatedOverride` lane. A target with no
+ * discoverable path is simply absent from the result (the taxonomy audit then names ONLY the real gaps).
+ * De-duplicated by `gatedDirectiveId` (a target proven once is not re-emitted).
+ */
+export function discoverRelationBootstrapLegs(mod: DomainModule): RelationBootstrapLeg[] {
+  const directives = mod.directives as Directive<unknown>[];
+  const isGatedProvable = (d: Directive<unknown> | undefined): boolean =>
+    d?.requiresRelationGate !== undefined &&
+    typeof d.payloadSchema === "object" &&
+    d.birthsChild !== true &&
+    d.attestationAuthorizedGate === undefined;
+  const legs: RelationBootstrapLeg[] = [];
+  const seen = new Set<string>();
+  for (const target of directives.filter(isGatedProvable)) {
+    if (seen.has(target.id)) continue;
+    let leg: RelationBootstrapLeg | undefined;
+    try {
+      leg = discoverRelationBootstrapLeg(mod, target);
+    } catch {
+      leg = undefined;
+    }
+    if (leg !== undefined) {
+      legs.push(leg);
+      seen.add(leg.gatedDirectiveId);
+    }
+  }
+  return legs;
+}
+
 /** A discovered layer-3 SEED directive: a sibling (non-gated, non-birth) whose plan writes relation tuples,
  *  so replaying it SEATS relation authority the gate's rewrite may consume. Ranked by how many relations it
  *  writes (a broad genesis/owner seed outranks a single-relation grant). `undefined` ⇒ no such directive. */
@@ -1978,6 +2148,10 @@ export interface ProofLegs {
    *  discoverable granter of R (a `.grants(R)` marker, or a plan-probed granting `writeTuple`). Proves the
    *  gated write SUCCEEDS once R is granted (the seed-then-prove positive). Additive: absent ⇒ older/ungated. */
   readonly relationBootstrap?: RelationBootstrapLeg;
+  /** MULTI-TARGET (co2 #2) — one authority leg PER gated create/write when the domain has several. Present
+   *  iff >1 was discovered; `relationBootstrap` is `relationBootstraps[0]`. Readers should treat
+   *  `relationBootstraps ?? (relationBootstrap ? [relationBootstrap] : [])` as the canonical set. */
+  readonly relationBootstraps?: readonly RelationBootstrapLeg[];
 }
 
 /** Synthesize the standalone-create offline legs for one domain module, or `null` when it has no
@@ -2161,12 +2335,14 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
 
   // The relation-bootstrap leg (when the domain has a `.requires(R)`-gated directive AND a discoverable
   // granter of R). FAIL SOFT: no granter → no leg (the negative conformance leg still covers the gate).
-  let relationBootstrap: RelationBootstrapLeg | undefined;
+  // MULTI-TARGET (co2 #2): discover one authority leg per gated create/write, not just the first.
+  let relationBootstraps: RelationBootstrapLeg[] = [];
   try {
-    relationBootstrap = discoverRelationBootstrapLeg(mod);
+    relationBootstraps = discoverRelationBootstrapLegs(mod);
   } catch {
-    relationBootstrap = undefined;
+    relationBootstraps = [];
   }
+  const relationBootstrap: RelationBootstrapLeg | undefined = relationBootstraps[0];
 
   const legs: ProofKind[] = ["compile-valid"];
   if (standalone !== null) legs.push("standalone-provable");
@@ -2192,7 +2368,7 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
     if (standalone.directiveId !== undefined) provenCreateIds.add(standalone.directiveId);
     for (const ec of standalone.extraCreates ?? []) provenCreateIds.add(ec.directiveId);
   }
-  if (relationBootstrap !== undefined) provenCreateIds.add(relationBootstrap.gatedDirectiveId);
+  for (const rb of relationBootstraps) provenCreateIds.add(rb.gatedDirectiveId);
   for (const d of mod.directives as Directive<unknown>[]) {
     if (d?.marker !== "creates" || typeof d.payloadSchema !== "object" || d.birthsChild === true) continue;
     if (provenCreateIds.has(d.id)) continue; // proven by some leg — nothing to name
@@ -2242,6 +2418,7 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
     ...(childBirthWithSetup !== undefined ? { childBirth: childBirthWithSetup } : {}),
     ...(childBirths.length > 1 ? { childBirths } : {}),
     ...(relationBootstrap !== undefined ? { relationBootstrap } : {}),
+    ...(relationBootstraps.length > 1 ? { relationBootstraps } : {}),
   };
 }
 
@@ -2579,7 +2756,7 @@ function generateBirthOnlyProof(
     // non-birth directive whose authority is established by the birth genesis (co2 home's updateHomeProfile
     // via birthHome→seedHomeCreator). Emit it so the birth-only proof names it (the born-context proof itself
     // runs in the offline `githolon proof` lane). No-op when the domain has no gated directive.
-    ...relationSeedLegLines(primaryLegs.relationBootstrap, factory, n, primaryLegs.relationBootstrap === undefined ? diagnoseRelationBootstrapGap(mod) : undefined),
+    ...relationSeedLegsLines(primaryLegs, factory, n, diagnoseRelationBootstrapGap(mod)),
     `console.log(\`\\nALL GREEN — generated proof for "${opts.packageName}": deploy → child birth (\${WS} → the born child) → verified\`);`,
     ``,
     ...v2CatchFinally(),
@@ -2749,8 +2926,6 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   // THE RELATION-BOOTSTRAP LEG (the seed-then-prove positive): grant relation R to the proof actor, then prove
   // a `.requires(R)`-gated write SUCCEEDS under that actor. `undefined` ⇒ no gated directive or no discoverable
   // granter (the negative conformance leg still runs). Comes from the SAME `legsForDomain` synthesis (marker).
-  const relationBootstrap = primaryLegs.relationBootstrap;
-
   // Workspace-name slug: any package name → a safe, recognizable ws prefix.
   const slug =
     opts.packageName
@@ -3015,7 +3190,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   // the proof actor, then prove the gated write SUCCEEDS under that actor. Runs on the LOCAL holon (fetch
   // re-trapped). When no granter is discoverable but a gated directive exists, emits a CLEAR diagnostic naming
   // exactly what's missing (the negative conformance leg still covers the gate).
-  out.push(...relationSeedLegLines(relationBootstrap, factory, n, relationBootstrap === undefined ? diagnoseRelationBootstrapGap(mod) : undefined));
+  out.push(...relationSeedLegsLines(primaryLegs, factory, n, diagnoseRelationBootstrapGap(mod)));
 
   // THE CHILD-BIRTH LEG (G3, gap 2): when the primary domain has a `.births()` directive, prove the birth
   // END-TO-END against the cloud — drive the parent birth offer, then read the BORN child workspace it spawns.

package/src/compile_package_main.ts

@@ -1016,7 +1016,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.55.0";
+const NOMOS_CLIENT_DEP = "^0.56.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).
@@ -2676,6 +2676,29 @@ async function main(): Promise<void> {
         typeof dartCfg === "object" && dartCfg.barrel !== undefined ? dartCfg.barrel : defaultBarrel;
       dartFiles = emitDart(domainModules, dartOut, domainHash, packageInterface, dartSupportImport, dartBarrel, nomosCompat, dartNames);
     }
+    // COMPILE-VALID MUST MEAN COMPILABLE (co2): `githolon compile` reported success while the generated Dart
+    // had hard compiler errors (a duplicate id symbol, missing contract-id defs). Run `dart analyze` over the
+    // emitted Dart as a SYMBOL-RESOLUTION GATE — a real analysis ERROR fails the compile (with the analyzer's
+    // own output), so a broken package never passes `mountable ✓`. Best-effort: skipped (with a note, never a
+    // 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()}`);
+        }
+      }
+    }
   }
 
   // ── summary ──

package/src/dart_barrel_guard.ts

@@ -31,8 +31,11 @@ export interface BarrelExportedFile {
  *  Private (`_`-prefixed) names never leak through an `export`, so they cannot collide — excluded. */
 export function publicDartDeclarations(src: string): Set<string> {
   const names = new Set<string>();
+  // `extension type const <Id>(…)` is legal Dart — the optional `const` modifier sits between `extension
+  // type` and the identifier. Skip it so the captured name is the TYPE, not the keyword `const` (co2: the
+  // generated `extension type const CatalogueListingFieldValueId(String value)` was misread as a type `const`).
   const re =
-    /^(?:abstract\s+|base\s+|final\s+|sealed\s+|interface\s+|mixin\s+)*(?:class|enum|mixin|extension type|typedef)\s+([A-Za-z][A-Za-z0-9_]*)/gm;
+    /^(?:abstract\s+|base\s+|final\s+|sealed\s+|interface\s+|mixin\s+)*(?:class|enum|mixin|extension type|typedef)\s+(?:const\s+)?([A-Za-z][A-Za-z0-9_]*)/gm;
   for (let m = re.exec(src); m !== null; m = re.exec(src)) {
     if (!m[1]!.startsWith("_")) names.add(m[1]!);
   }

package/src/framework/home.ts

@@ -35,6 +35,8 @@ import { query } from "../query.js";
 import { birth } from "../births.js";
 import { workspaceInvariant, refAs } from "./workspace_invariant.js";
 import { identityRelations } from "./signing_identity.js";
+import { writeTuple } from "./relations.js";
+import { relationType, self, user, selfObject } from "../relation_schema.js";
 import { requireParentAttestedBirth, type ParentAttestedBirthMarker } from "../births.js";
 import { GenesisWarrant, seedGenesis } from "./genesis.js";
 
@@ -77,10 +79,38 @@ export const HomeOwner = aggregate("HomeOwner", {
   bornAt: t.string().merge(Lww),
 });
 
-/** The framework PRIMITIVE plan: stamp the home's owner + its self-committed name (singleton at the fixed id). */
+/**
+ * THE HOME-OWNER RELATION (the ReBAC authority spine, co2 ask #1). The {@link HomeOwner} aggregate is the
+ * ownership RECORD; this relation is the AUTHORIZATION spine a tenant can compute from. `seedHomeOwner` seats
+ * `(home:self, homeOwner, user:<owner>)` ATOMICALLY inside the same child genesis (before the warrant closes
+ * bootstrap), so a canonical `birthHome` yields a home whose owner passes role gates from intent 0 — a tenant
+ * declares `estateCreator = computed(homeOwner)` WITHOUT copying birth mechanics. Self-bound (object `home:
+ * self`, subject the owner) — the {@link homeNameBindsOwner} squat invariant already proves the owner is the
+ * rightful one, so no separate grant is needed.
+ */
+export const homeRelations = relationType("home").relation("homeOwner", {
+  rewrite: self(),
+  allow: [user()],
+});
+
+/** The framework PRIMITIVE plan: stamp the home's owner + its self-committed name (singleton at the fixed id),
+ *  AND atomically seat the canonical `homeOwner` relation tuple for the same self-bound principal (co2 #1). */
 export function writeHomeOwner(p: { principal: string; homeName: string; bornAt: string }): PlannedOp[] {
   const h = instance(HomeOwner, HOME_OWNER_ID);
-  return [set(h, "principal", p.principal), set(h, "homeName", p.homeName), set(h, "bornAt", p.bornAt)];
+  return [
+    set(h, "principal", p.principal),
+    set(h, "homeName", p.homeName),
+    set(h, "bornAt", p.bornAt),
+    // ATOMIC ReBAC seat — the owner subject is the canonical `user:<uid>` on HomeOwner.principal; grantedBy is
+    // the owner itself (self-bound, no external granter) and grantedAt rides the caller-stamped bornAt.
+    ...writeTuple({
+      object: selfObject(homeRelations),
+      relation: "homeOwner",
+      subject: p.principal,
+      grantedBy: p.principal,
+      grantedAt: p.bornAt,
+    }),
+  ];
 }
 
 /**