@githolon/dsl 0.60.0 → 0.60.2

package/dart/CHANGELOG.md

@@ -1,7 +1,12 @@
-## 0.39.0
+## 0.41.0
+- `NomosTestHarness` emits named phase-progress diagnostics (install → spawn runner → await ready → connect, plus per-session progress in `cluster`) and each `connect()` carries a `connectTimeout` (default 120s) that throws a NAMED remedy instead of hanging — so a multi-test AppSim run can tell install vs runner-wait vs session-block vs deadlock (co2 feedback).
+
+## 0.40.0
 - `connect(maxMounted: …)` — the realm's mounted-workspace budget (LRU park/remount above it); useful on memory-constrained devices holding many local workspaces.
 - MULTI-WORKSPACE BY DEFAULT IN TESTS: `NomosTestHarness.ephemeral` now connects a DECOY session alongside the workspace under test, and `harness.bridge` is a `NomosSession` HANDLE pinned to it (existing tenant tests work unchanged). Sole-session inference therefore never silently passes under the harness — an op that forgot its session refuses in your first test with the same `multiple sessions connected — pass session` a real multi-workspace app raises. Opt out with `decoySession: false`.
 - `NomosBridge.open(...)` — connect + pinned `NomosSession` handle in one call (`final home = await bridge.open(workspace: …); HomeClient(home)`): the recommended plane/handle shape; the bare bridge methods remain one-workspace sugar.
+
+## 0.39.0
 - Multi-session compat surface: `watchCompatibility` takes an optional `session`; `NomosSession` pins its compat watch, `compat`, and `onLawChanged` to ITS workspace (per-session `lawChanged` scoping — previously a multi-session plane's compat verdict was whichever session synced last, and a session's compat watch refused on a >1-session plane).
 
 ## 0.38.0

package/dart/lib/src/test_harness.dart

@@ -136,6 +136,7 @@ class NomosTestHarness {
     void Function(Future<void> Function())? registerTearDown,
     void Function(String line)? onDiagnostic,
     Duration readyTimeout = const Duration(seconds: 30),
+    Duration connectTimeout = const Duration(seconds: 120),
     bool decoySession = true,
   }) async {
     if (deployJsonPaths.isEmpty) {
@@ -162,8 +163,10 @@ class NomosTestHarness {
     final workdir = await Directory.systemTemp.createTemp('nomos-harness-');
     // Total-ordered teardown even on a mid-setup failure: build the transport lazily and clean up on throw.
     NodeRunnerTransport? transport;
+    final phase = (String m) { if (onDiagnostic != null) onDiagnostic('[nomos-test-harness] $m'); };
     try {
       final snapshot = '${workdir.path}/snapshot.bin';
+      phase('phase 1/4 installing ${deployJsonPaths.length} law package(s) offline into "$workspace" …');
       final info = await _runInstall(
           node: node,
           useInRepoScript: useInRepoScript,
@@ -175,6 +178,7 @@ class NomosTestHarness {
           runtimeDir: runtimeDir,
           onDiagnostic: onDiagnostic);
 
+      phase('phase 2/4 spawning the node runner (node=$node) …');
       transport = await NodeRunnerTransport.start(
         entry: entry,
         resolveFrom: resolveFrom,
@@ -187,16 +191,24 @@ class NomosTestHarness {
         onDiagnostic: onDiagnostic,
       );
       final plane = NomosBridge(transport);
+      phase('phase 3/4 awaiting runner ready (≤${readyTimeout.inSeconds}s) …');
       await plane.ready.timeout(readyTimeout,
           onTimeout: () => throw NomosTestHarnessException(
-              'the offline runner never signalled ready within $readyTimeout '
-              '(is `node` on PATH and ~/.holon/runtime warm?)'));
+              'the offline runner never signalled ready within ${readyTimeout.inSeconds}s '
+              '(phase 3/4: is `node` on PATH and ~/.holon/runtime warm? the runner process may have '
+              'failed to boot the engine — run with onDiagnostic to see its stderr)'));
+      phase('phase 4/4 connecting session "$workspace" (≤${connectTimeout.inSeconds}s) …');
       await plane.connect(
         cloud: 'https://offline.invalid', // ignored: the offline runner serves everything locally
         workspace: workspace,
         clientId: clientId,
         allowUnborn: true,
-      );
+      ).timeout(connectTimeout,
+          onTimeout: () => throw NomosTestHarnessException(
+              'connect("$workspace") did not complete within ${connectTimeout.inSeconds}s (phase 4/4) — '
+              'the runner is up but the session never mounted; a large ledger converge-fold can be slow, '
+              'raise connectTimeout, or run with onDiagnostic to see where it blocked'));
+      phase('ready — session "$workspace" connected (law ${(info['lawHashes'] as List?)?.isNotEmpty == true ? (info['lawHashes'] as List).first.toString().substring(0, 12) : "installed"})');
       // THE DECOY SESSION (multi-workspace by default in tests): sole-session inference is how
       // single-workspace assumptions ship — with one session connected, an op that forgot its session
       // silently works in tests and only refuses in production when the app connects its second
@@ -266,6 +278,7 @@ class NomosTestHarness {
     void Function(Future<void> Function())? registerTearDown,
     void Function(String line)? onDiagnostic,
     Duration readyTimeout = const Duration(seconds: 30),
+    Duration connectTimeout = const Duration(seconds: 120),
   }) async {
     if (workspaces.isEmpty) {
       throw NomosTestHarnessException(
@@ -312,6 +325,8 @@ class NomosTestHarness {
       }
 
       // 2. ONE runner / ONE bridge for the whole plane — no env restore default; each connect brings its own.
+      final phase = (String m) { if (onDiagnostic != null) onDiagnostic('[nomos-test-harness] $m'); };
+      phase('cluster: spawning the node runner for ${workspaces.length} workspace(s) …');
       transport = await NodeRunnerTransport.start(
         entry: entry,
         resolveFrom: resolveFrom,
@@ -323,24 +338,32 @@ class NomosTestHarness {
         onDiagnostic: onDiagnostic,
       );
       final bridge = NomosBridge(transport);
+      phase('cluster: awaiting runner ready (≤${readyTimeout.inSeconds}s) …');
       await bridge.ready.timeout(readyTimeout,
           onTimeout: () => throw NomosTestHarnessException(
-              'the offline runner never signalled ready within $readyTimeout '
-              '(is `node` on PATH and ~/.holon/runtime warm?)'));
+              'the offline runner never signalled ready within ${readyTimeout.inSeconds}s '
+              '(is `node` on PATH and ~/.holon/runtime warm? run with onDiagnostic to see the runner stderr)'));
 
       // 3. connect one SESSION per workspace, each restoring its OWN snapshot — LOCAL-ONLY (no cloud;
       //    these are local githolons on the device plane, offline by nature).
       final snapshotB64 = <String, String>{};
+      var _n = 0;
       for (final e in workspaces.entries) {
         snapshotB64[e.key] = base64Encode(await File(snapshots[e.key]!).readAsBytes());
+        phase('cluster: connecting session ${++_n}/${workspaces.length} "${e.key}" (≤${connectTimeout.inSeconds}s) …');
         await bridge.connect(
           workspace: e.key,
           session: e.key,
           clientId: '$clientId-${e.key}',
           restoreFrom: snapshotB64[e.key],
           allowUnborn: true,
-        );
+        ).timeout(connectTimeout,
+            onTimeout: () => throw NomosTestHarnessException(
+                'connect("${e.key}") did not complete within ${connectTimeout.inSeconds}s — the runner is up '
+                'but this session never mounted (a large ledger converge-fold can be slow; raise connectTimeout '
+                'or run with onDiagnostic)'));
       }
+      phase('cluster: ${workspaces.length} session(s) connected');
 
       // 3b. DEVICE-KEY the named sessions: mint a fresh in-kernel key on each (now that it is mounted) and
       //     RE-OPEN it with that key as its signing authorSecret — the resolver's attested-read signing key.

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.39.0
+version: 0.41.0
 
 environment:
   sdk: ^3.5.0

package/dart/test/test_harness_test.dart

@@ -107,6 +107,30 @@ void main() {
     );
   }, timeout: const Timeout(Duration(minutes: 2)));
 
+  test('DX: ephemeral emits phase-progress diagnostics (install → runner → ready → connect)', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final lines = <String>[];
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_guestbookDeployJson],
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      registerTearDown: addTearDown,
+      onDiagnostic: lines.add,
+    );
+    final joined = lines.join('\n');
+    // the four named phases are surfaced so an AppSim can tell install vs runner-wait vs connect-block.
+    expect(joined, contains('phase 1/4 installing'));
+    expect(joined, contains('phase 2/4 spawning the node runner'));
+    expect(joined, contains('phase 3/4 awaiting runner ready'));
+    expect(joined, contains('phase 4/4 connecting session'));
+    expect(joined, contains('ready — session "test-ws" connected'));
+    expect(harness.bridge, isNotNull);
+  }, timeout: const Timeout(Duration(minutes: 2)));
+
   test('OFFLINE: dispose is idempotent and removes the temp dir', () async {
     final skip = _missingPrereq();
     if (skip != null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.60.0",
+  "version": "0.60.2",
   "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_client.ts

@@ -350,6 +350,11 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `// Drives the REAL githolon over a NomosBridge (the WebView runner). Regenerated every compile; do`,
     `// not edit. Construct with a connected bridge:`,
     `//`,
+    // GENERATED-CODE lints: the bridge read/watch surface returns dynamic (JSON rows), so typed accessors
+    // do dynamic member access + casts by construction. Silence the lints that only make sense for
+    // hand-written code, so this file never adds noise to a tenant's analyzer output (co2 feedback).
+    `// ignore_for_file: avoid_dynamic_calls, unnecessary_this, prefer_const_constructors, unused_import, type_annotate_public_apis, always_specify_types`,
+    `//`,
     `//   final bridge = NomosBridge(transport);   // transport = your WebViewTransport`,
     `//   await bridge.ready;`,
     `//   await bridge.connect(cloud: cloud, workspace: ws, clientId: deviceId);`,

package/src/codegen_proof.ts

@@ -656,6 +656,10 @@ export interface RelationBootstrapLeg {
    *  would trip the seed's owner-binding prerequisite (HomeOwner unset) and FALSE-fail. When present, the
    *  runner IGNORES the standalone grant fields and proves via {@link BornContextAuthority}. */
   readonly bornContext?: BornContextAuthority;
+  /** THE GATED-GRANTER CHAIN (co2: `grantCo2EstateCreator` itself `.requires("co2Admin")`): the granter's
+   *  OWN gate bootstrapped recursively — the runner seats THIS authority first (its prerequisite seeds +
+   *  its grant on the same actor), then the outer grant admits. Depth/cycle-guarded at discovery. */
+  readonly granterAuthority?: RelationBootstrapLeg;
   /** THE PREREQUISITE-SEED CHAIN (the composed co2_platform / `seedPlatformAdmin` case). Present iff the
    *  granter (`grantDirectiveId`) carries a PREREQUISITE invariant whose state is established NOT by a birth
    *  genesis but by a SIBLING SEED in the SAME domain (e.g. `seedPlatformAdmin`'s `PlatformAdminBindsFounder`
@@ -1186,7 +1190,7 @@ export function discoverPrerequisiteChain(mod: DomainModule, granter: Directive<
  *  granter, so granting B makes the actor satisfy R. `undefined` ⇒ no gated directive, or no granter for R
  *  or any of its bases (the caller may then fall through to the seed-path lane; the negative conformance
  *  leg always still runs). */
-export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstrapLeg | undefined {
+export function discoverRelationBootstrapLeg(mod: DomainModule, gatedOverride?: Directive<unknown>, _seen: ReadonlySet<string> = new Set()): RelationBootstrapLeg | undefined {
   const domain = mod.domain ?? mod.name;
   const directives = mod.directives as Directive<unknown>[];
   const isGatedProvable = (d: Directive<unknown> | undefined): boolean =>
@@ -1198,8 +1202,15 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
   // naive standalone-create leg (isStandaloneCreate), so the bootstrap leg is its ONLY positive proof — seed
   // authority, then prove the CREATE is admitted. When no gated create exists, fall back to any gated write
   // (a gated `.mutates`/`.ensures`), so an un-created gated law is still proven.
-  const gated = directives.find((d) => isGatedProvable(d) && d.marker === "creates")
-    ?? directives.find((d) => isGatedProvable(d));
+  // `gatedOverride` targets a SPECIFIC gated directive instead (the gated-`.births()` case — excluded from
+  // the default scan because a birth is proven by its OWN leg; the override reuses the same granter/seed
+  // discovery to SEAT the birth's required relation).
+  const gated = gatedOverride !== undefined && gatedOverride.requiresRelationGate !== undefined && typeof gatedOverride.payloadSchema === "object"
+    ? gatedOverride
+    : gatedOverride !== undefined
+      ? undefined
+      : (directives.find((d) => isGatedProvable(d) && d.marker === "creates")
+        ?? directives.find((d) => isGatedProvable(d)));
   if (gated === undefined) return undefined;
   const relation = gated.requiresRelationGate!.relation;
 
@@ -1313,6 +1324,18 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
   if (found === undefined) return undefined; // no granter at all → the caller emits the diagnostic
   const granter = found.granter;
 
+  // GATED GRANTER (co2: grantCo2EstateCreator itself .requires("co2Admin")): recursively bootstrap the
+  // granter's OWN gate so the runner seats that authority first. Cycle/depth-guarded via the seen-set; an
+  // unresolvable granter gate still emits the leg WITHOUT the chain (the runner's refusal names the gap —
+  // never silently weaker than before this lane existed).
+  let granterAuthority: RelationBootstrapLeg | undefined;
+  if (granter.requiresRelationGate !== undefined && !_seen.has(granter.id) && _seen.size < 4) {
+    granterAuthority = discoverRelationBootstrapLeg(mod, granter, new Set([..._seen, gated.id, granter.id]));
+    // a born-context result proves INSIDE a born workspace — not a seatable pre-grant; drop it (the
+    // runner's refusal then names the granter's unseatable gate).
+    if (granterAuthority?.bornContext !== undefined) granterAuthority = undefined;
+  }
+
   // Synthesize the grant payload + resolve which fields route into subject / grantedBy (so runtime seats the
   // grant on the proof actor). Best-effort: an un-probable grant plan still emits the leg (runtime overwrites
   // any field whose name looks like a subject/grantedBy anyway).
@@ -1343,6 +1366,7 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
     ...(seedSpeculative ? { seedSpeculative: true } : {}),
     ...(seedWritesRelations !== undefined ? { seedWritesRelations } : {}),
     ...(prerequisiteSeeds !== undefined ? { prerequisiteSeeds } : {}),
+    ...(granterAuthority !== undefined ? { granterAuthority } : {}),
   };
 }
 
@@ -1464,6 +1488,12 @@ export interface ChildBirthLeg {
    *  parent workspace (home → estate is the canonical case), the proof runner drives this setup birth first
    *  and then authors the child birth inside the born parent. */
   readonly parentSetup?: ChildBirthParentSetup;
+  /** RELATION SETUP for a GATED birth (`.births().requires(R)`) with NO parent-birth authority path: the
+   *  relation-bootstrap discovery (granter marker / inferred writeTuple / computed base / prerequisite-seed
+   *  chain) reused to SEAT R on the birth actor before the runner drives the birth offer — the law's own
+   *  granters, never a proof-only backdoor. Absent when `parentSetup` covers authority or no granter is
+   *  discoverable (the runner then reports the gate refusal with the discovery gap named). */
+  readonly relationSetup?: RelationBootstrapLeg;
   /** COMPILE-TIME RECIPE DIAGNOSTICS (births DX): problems found by statically validating each genesis
    *  step against the composed package (missing child module, unknown seed directive, payload-schema
    *  mismatch, a plan that returns a non-array — the exact things that otherwise surface at proof time as
@@ -2041,7 +2071,19 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
   // The child-birth legs (one per `.births()` directive) — discovered by running each plan. A parent
   // with SEVERAL births (co2: birthCatalogueWorkspace + birthEstateWorkspace) keeps EVERY leg; keeping
   // only the first left the other children compile-valid-only (unprovable through their birth).
-  const childBirths = allBirths.filter((b) => b.parentDomain === domain).map((b) => attachParentSetup(b, allBirths));
+  const childBirths = allBirths.filter((b) => b.parentDomain === domain).map((b) => {
+    const withParent = attachParentSetup(b, allBirths);
+    // 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) {
+      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.
+      if (rb !== undefined && rb.bornContext === undefined) return { ...withParent, relationSetup: rb };
+    }
+    return withParent;
+  });
   const childBirthWithSetup = childBirths[0];
 
   // The relation-bootstrap leg (when the domain has a `.requires(R)`-gated directive AND a discoverable

package/src/compile_package_main.ts

@@ -888,14 +888,26 @@ function emitDartPackages(
   }
 
   const declared = new Set<string>();
-  for (const src of typesSources.values()) for (const n of declaredDartTypeNames(src)) declared.add(n);
+  const declaredByFile = new Map<string, Set<string>>();
+  for (const [f, src] of typesSources) {
+    const ns = declaredDartTypeNames(src);
+    declaredByFile.set(f, ns);
+    for (const n of ns) declared.add(n);
+  }
+  // Only import files that actually CONTRIBUTE an alias target — an alias `typedef A = B` needs B in scope,
+  // but a file no alias references needs no import (the `export` re-exports it). Importing every file
+  // produced unused_import warnings in the tenant's barrel (co2 feedback).
+  const aliasTargets = new Set(Object.keys(names ?? {}));
+  const aliasImportUris = [...typesSources.keys()]
+    .filter((f) => [...(declaredByFile.get(f) ?? [])].some((n) => aliasTargets.has(n)))
+    .map((f) => `${genRel}/${f}.dart`);
   const typesBarrel = [
     "// GENERATED by nomos-compile — the TYPES package's public entrypoint. DO NOT EDIT.",
     "// Pure data: payload classes, read models, VOs/enums, typed read accessors over the",
     "// injected NomosReads seams. Frontend-safe — no bridge, no sessions, no lifecycle.",
     "library;",
     "",
-    ...aliasImportLines(names, [...typesSources.keys()].map((f) => `${genRel}/${f}.dart`)),
+    ...aliasImportLines(names, aliasImportUris),
     `export 'package:nomos_types/nomos_types.dart';`,
     ...[...typesSources.keys()].map((f) => `export '${genRel}/${f}.dart';`),
     ...dartAliasLines(names, declared),
@@ -2291,6 +2303,19 @@ async function main(): Promise<void> {
     }
   }
   console.log(`  deploy     ${rel(deployPath)}`);
+  if (compact) {
+    // COMPACT PACKAGES ride a base64 blob (nomos:usdJsonB64) — a peer needs the b64 decode arm
+    // (kernel ≥ the 2026-07-04 release; every current cloud/browser/node runtime has it). A NATIVE
+    // (iOS/macOS AOT) client pins its OWN kernel binary: if that xcframework predates the arm, install
+    // fails with `parse embedded USDA IR: domain package missing USDA field nomos:usdJsonHex`. Flag it
+    // so the tenant isn't surprised (the requested "flag compact when targeting native").
+    console.log(``);
+    console.log(`  ⚠ compact package (base64 blob): requires a kernel with the b64 decode arm (≥ 2026-07-04).`);
+    console.log(`    Current cloud/browser/node runtimes have it. A NATIVE client (nomos_flutter iOS/macOS)`);
+    console.log(`    pins its OWN kernel — refetch the current NomosKernel.xcframework (rm ios/Frameworks/`);
+    console.log(`    NomosKernel.xcframework && pod install), or set { compact: false } for a hex package that`);
+    console.log(`    parses on every kernel (larger deploy body; may need the signed-upload deploy lane).`);
+  }
   console.log(``);
   console.log(`deploy (Nomos Cloud):`);
   console.log(`  githolon login --agent && githolon ws create <ws> && githolon deploy <ws>   # no secret — deploy is OPEN, kernel-judged at the offer gate`);