@githolon/dsl 0.77.0 → 0.78.0

package/dart/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 0.54.0
+
+- **Parent-signer recovery** (the reborn-parent scar): `ensureParentSignerEnrollment(...)` —
+  idempotent verify-and-repair of `identity:<uid>#signer` on a configured parent (one relation read
+  when healthy; lawful repair via the discovered signing directive — enrollSigner pre-warrant, the
+  keyless enrollFirstDevice lane on a warranted parent); `parentSignerEnrollment(...)` posture read;
+  `devicePublicOf(secret)`.
+- **`canAuthor(directiveId, ...)` preflight** — evaluates the gate's premises read-only and returns
+  the typed verdict ({actor, keyHash, cause}) BEFORE the user fills a form;
+  `NomosSession.canAuthorTyped` throws the typed error.
+- Gate refusals classify into `nomos.authz.*` typed errors (see nomos_types 0.4.0). Requires the
+  paired runner bundle >= 0.78.0.
+
+## 0.53.0
+
+- **Stale-baked-bundle detection.** The runner bundle stamps its release version into the `ready`
+  frame (build-time injected — it cannot lie); the bridge refuses an older or pre-stamp bundle at
+  boot with the typed `StaleRunnerBundle` naming found/expected and the `flutter clean` remedy.
+  Flutter silently keeping an old baked bundle across a pub upgrade is now a one-line error at app
+  start instead of behavioral archaeology. `allowStaleRunnerBundle: true` is the deliberate
+  mixed-version escape hatch. Requires the paired runner bundle >= 0.77.1 (nomos_flutter 0.53.7).
+
 ## 0.52.0
 
 - **Offer ack decoupled from watch fan-out** (co2's 2.08s 3×3-grid report): the durable acknowledgement

package/dart/lib/src/webview_bridge.dart

@@ -43,6 +43,34 @@ typedef NomosEngine = NomosBridge;
 /// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
 const int kWebviewBridgeVersion = 1;
 
+/// THE EXPECTED RUNNER-BUNDLE VERSION FLOOR — the @githolon/client release this nomos_client version
+/// ships alongside. The bundle stamps its own version into the ready frame; anything OLDER (or a
+/// pre-stamp bundle, which reports nothing) is a stale baked asset and fails loudly at boot.
+/// MUST move with the paired @githolon/client release — a release-hygiene test pairs it with the
+/// runner stamp (the pubspec-pins pattern).
+const String kExpectedRunnerBundleVersion = '0.78.0';
+
+/// A STALE BAKED RUNNER BUNDLE: the app's built assets carry an older nomos-runner.js than this
+/// nomos_client release ships — Flutter's build cache kept it across a pub upgrade. Thrown from
+/// [NomosBridge.ready] at boot (loud, immediate, named) instead of letting one-version-old runtime
+/// behavior masquerade as framework bugs.
+class StaleRunnerBundle implements Exception {
+  StaleRunnerBundle({required this.found, required this.expected});
+
+  /// The bundle's self-reported version (null = a pre-stamp bundle, definitionally stale).
+  final String? found;
+
+  /// The minimum version this nomos_client release expects ([kExpectedRunnerBundleVersion]).
+  final String expected;
+
+  @override
+  String toString() =>
+      'StaleRunnerBundle: the baked nomos-runner.js is ${found ?? "un-stamped (pre-0.77.1)"} but this '
+      'nomos_client expects >= $expected. Flutter kept an old bundle across the upgrade — run '
+      '`flutter clean` and rebuild (verify with shasum of flutter_assets/.../nomos-runner.js), or pass '
+      'NomosBridge(..., allowStaleRunnerBundle: true) for a deliberate mixed-version setup.';
+}
+
 /// The platform channel to the WebView runner: send a JSON-shaped message; receive the runner's messages.
 /// Web impl jsifies/dartifies over `dart:js_util`; mobile impl JSON-encodes over a WebView JS-channel. The
 /// bridge treats messages as plain `Map<String, Object?>` — the transport owns the channel serialization.
@@ -743,13 +771,37 @@ class NomosBridge {
   final String _traceId = _newTraceId();
   late final StreamSubscription<Map<String, Object?>> _sub;
 
-  NomosBridge(this._transport) {
+  NomosBridge(this._transport, {this.allowStaleRunnerBundle = false}) {
     _sub = _transport.messages.listen(_onMessage);
   }
 
+  /// Escape hatch for DELIBERATE mixed-version setups (framework dev, A/B probes): accept a runner
+  /// bundle older than [kExpectedRunnerBundleVersion] instead of failing [ready].
+  final bool allowStaleRunnerBundle;
+
+  /// null = acceptable; otherwise the typed boot error. "unbundled-dev" (the in-repo source lane)
+  /// always passes; a missing stamp means a pre-stamp (definitionally stale) bundle.
+  StaleRunnerBundle? _staleBundleError(Object? bundleVersion) {
+    final v = bundleVersion is String ? bundleVersion : null;
+    if (v == 'unbundled-dev') return null;
+    if (v != null && _semverAtLeast(v, kExpectedRunnerBundleVersion)) return null;
+    return StaleRunnerBundle(found: v, expected: kExpectedRunnerBundleVersion);
+  }
+
+  static bool _semverAtLeast(String v, String min) {
+    List<int> parse(String s) =>
+        s.split('-').first.split('.').map((p) => int.tryParse(p) ?? 0).toList();
+    final a = parse(v), b = parse(min);
+    for (var i = 0; i < 3; i++) {
+      final x = i < a.length ? a[i] : 0, y = i < b.length ? b[i] : 0;
+      if (x != y) return x > y;
+    }
+    return true;
+  }
+
   /// A SESSION VIEW's super-constructor: shares the parent's [_transport] but does NOT subscribe (the parent
   /// owns the one message loop + all correlation). Only [NomosSession] uses it.
-  NomosBridge._view(this._transport);
+  NomosBridge._view(this._transport) : allowStaleRunnerBundle = false;
 
   static Random _traceRandom() {
     try {
@@ -798,6 +850,18 @@ class NomosBridge {
     }
     final event = m['event'];
     if (event == 'ready') {
+      // THE STALE-BAKED-BUNDLE CHECK: Flutter's build system can silently keep an OLD runner bundle
+      // baked into an app across a correct pub upgrade — invisible version skew that cost a real
+      // tenant two archaeology hunts. The bundle stamps its release version into the ready frame;
+      // an older-than-expected (or missing — i.e. pre-stamp) bundle fails LOUDLY at boot with the
+      // remedy, instead of misbehaving subtly at runtime. "unbundled-dev" (the in-repo source lane
+      // the test harness drives) always passes; `allowStaleRunnerBundle: true` on the constructor is
+      // the deliberate-mixed-versions escape hatch.
+      final stale = _staleBundleError(m['bundleVersion']);
+      if (stale != null && !allowStaleRunnerBundle) {
+        if (!_ready.isCompleted) _ready.completeError(stale);
+        return;
+      }
       if (!_ready.isCompleted) _ready.complete();
       return;
     }
@@ -1165,6 +1229,7 @@ class NomosBridge {
     List<Map<String, Object?>>? attestations,
     bool? force,
     String? session,
+    String? authorSecret,
   }) =>
       offerOutcome(
         domain: domain,
@@ -1175,6 +1240,7 @@ class NomosBridge {
         attestations: attestations,
         force: force,
         session: session,
+        authorSecret: authorSecret,
       );
 
   /// THE ONE OUTCOME-RETURNING OFFER LANE — [offerDirective] answering the full typed [NomosOfferOutcome]
@@ -1191,6 +1257,9 @@ class NomosBridge {
     List<Map<String, Object?>>? attestations,
     bool? force,
     String? session,
+    // Per-offer signing key (base64 device secret): sign THIS offer with a specific device key instead
+    // of the connect-time one — the parent-directed lanes (sibling births after a signer repair) use it.
+    String? authorSecret,
   }) async {
     final Map<String, Object?> r;
     // OFFER SPAN TAXONOMY (bridge legs): stamp the Dart-side send/receive around the op; the runner
@@ -1210,6 +1279,7 @@ class NomosBridge {
         if (attestations != null) 'attestations': attestations,
         if (force != null) 'force': force,
         if (session != null) 'session': session,
+        if (authorSecret != null) 'authorSecret': authorSecret,
       }));
     } catch (e) {
       throw await _wrapDomainNotInstalled(e,
@@ -1628,6 +1698,87 @@ class NomosBridge {
         if (authToken != null) 'authToken': authToken,
       }));
 
+  /// Derive the device key's base64 PUBLIC half from its base64 SECRET seed, inside the LOCAL kernel
+  /// (the secret never leaves the device). The recovery lanes use this when only the secret was
+  /// persisted (the device-key store keeps just the seed) — e.g. to mint a device-BOUND IdP token
+  /// (`authTokenForDevice(publicKey)`) for the keyless re-enroll lane.
+  Future<String> devicePublicOf(String secret) async =>
+      (_asMap(await _call('devicePublicOf', {'secret': secret}))['public'] ?? '')
+          .toString();
+
+  /// PARENT-AUTHORITY POSTURE (read-only diagnostic): is this device key a LIVE `signer` for
+  /// `principal` on `parent`'s chain (`identity:<principal>#signer@key:<sha256(publicKey)>`)? One O(1)
+  /// relation read over the open gateway; nothing is authored. Returns
+  /// `{parent, principal, keyHash, object, relation, enrolled, revoked, checkedAt}`.
+  Future<Map<String, Object?>> parentSignerEnrollment(
+          {required String parent,
+          required String principal,
+          String? keyHash,
+          String? publicKey,
+          String? authToken}) async =>
+      _asMap(await _call('parentSignerEnrollment', {
+        'parent': parent,
+        'principal': principal,
+        if (keyHash != null) 'keyHash': keyHash,
+        if (publicKey != null) 'publicKey': publicKey,
+        if (authToken != null) 'authToken': authToken,
+      }));
+
+  /// IDEMPOTENT PARENT-SIGNER RECOVERY — ensure this device key is a live `signer` on `parent`,
+  /// lawfully restoring the tuple a parent custody REBIRTH lost (the device key + the born home stay
+  /// valid; no home rebirth, no hand-posted secrets). Already enrolled ⇒ pure no-op (`repaired:false`).
+  /// Absent ⇒ re-authors the enrollment via the parent's OWN installed signing directive, DISCOVERED
+  /// from its law (never a hardcoded framework domain — a tenant-composed `co2_platform` works);
+  /// `domain`/`directiveId` override the discovery. A REVOKED key is never silently re-enrolled.
+  /// TWO LAWFUL LANES, kernel-decided: a WARRANTED parent (the reborn-platform case) admits a fresh
+  /// device-signer only via the keyless `enrollFirstDevice` — pass the device-bound [idToken]
+  /// (+ [verifiedVia], the parent's AuthProvider issuer); a PRE-WARRANT parent admits the founding
+  /// `enrollSigner` (no token needed).
+  /// Returns `{parent, principal, keyHash, enrolled, repaired, domain?, directiveId?, checkedAt}`.
+  Future<Map<String, Object?>> ensureParentSignerEnrollment(
+          {required String parent,
+          required String principal,
+          String? publicKey,
+          String? authorSecret,
+          String? domain,
+          String? directiveId,
+          String? authToken,
+          String? idToken,
+          String? verifiedVia}) async =>
+      _asMap(await _call('ensureParentSignerEnrollment', {
+        'parent': parent,
+        'principal': principal,
+        if (publicKey != null) 'publicKey': publicKey,
+        if (authorSecret != null) 'authorSecret': authorSecret,
+        if (domain != null) 'domain': domain,
+        if (directiveId != null) 'directiveId': directiveId,
+        if (authToken != null) 'authToken': authToken,
+        if (idToken != null) 'idToken': idToken,
+        if (verifiedVia != null) 'verifiedVia': verifiedVia,
+      }));
+
+  /// AUTHORING PREFLIGHT — evaluate the SAME premises the kernel's authorization gate judges,
+  /// READ-ONLY, and return a typed verdict WITHOUT authoring — so the app catches a doomed write
+  /// (e.g. a reborn parent missing this device's signer tuple) BEFORE the user fills a form.
+  /// `ws` targets another workspace (pass the PARENT to preflight a sibling birth). Returns
+  /// `{ok, ws, directiveId, actor, keyHash, cause, causes, domain?, relation?, object?, error?, checkedAt}`
+  /// where `cause` ∈ {directive-not-found, no-signing-key, missing-signer-enrollment, revoked-signer,
+  /// missing-role, null}. Use [canAuthorTyped] on a [NomosSession] for the typed-error variant.
+  Future<Map<String, Object?>> canAuthor(String directiveId,
+          {String? ws,
+          String? principal,
+          String? publicKey,
+          String? keyHash,
+          String? authToken}) async =>
+      _asMap(await _call('canAuthor', {
+        'directiveId': directiveId,
+        if (ws != null) 'ws': ws,
+        if (principal != null) 'principal': principal,
+        if (publicKey != null) 'publicKey': publicKey,
+        if (keyHash != null) 'keyHash': keyHash,
+        if (authToken != null) 'authToken': authToken,
+      }));
+
   /// VERIFY_CHAIN — the kernel's from-genesis self-verification of THIS holon's folded ledger (read-only:
   /// contiguity → every intent re-admitted through the ONE gate against the state folded from the prefix). For
   /// a WARRANTED home this RE-FIRES the parent-attested-birth cert door on the cold-replay lane — so a
@@ -2194,6 +2345,42 @@ class NomosSession extends NomosBridge {
   @override
   Future<void> dispose() async {}
 
+  /// TYPED AUTHORING PREFLIGHT — [NomosBridge.canAuthor], returning the raw verdict when the write
+  /// would admit and THROWING the matching typed error when it would not: a missing parent signer
+  /// tuple throws [ParentSignerEnrollmentMissing] (its `recommendedAction` names the ONE remedy —
+  /// [ensureParentSignerEnrollment]); any other failing premise throws [AuthzRefusedError] carrying
+  /// the evaluated {workspace, actor, keyHash, object, relation, cause}. Nothing is authored.
+  Future<Map<String, Object?>> canAuthorTyped(String directiveId,
+      {String? ws,
+      String? principal,
+      String? publicKey,
+      String? keyHash,
+      String? authToken}) async {
+    final v = await canAuthor(directiveId,
+        ws: ws, principal: principal, publicKey: publicKey, keyHash: keyHash, authToken: authToken);
+    if (v['ok'] == true) return v;
+    final cause = v['cause']?.toString();
+    final target = v['ws']?.toString() ?? ws ?? workspace;
+    final info = NomosErrorInfo(
+      code: cause == 'missing-signer-enrollment'
+          ? 'nomos.authz.signer_enrollment_missing'
+          : 'nomos.authz.refused',
+      message:
+          'canAuthor($directiveId) on $target: premise "$cause" failed for ${v['actor'] ?? principal ?? '(unknown actor)'}',
+      workspace: target,
+      operation: 'canAuthor',
+      attributes: {
+        if (v['actor'] != null) 'nomos.authz.actor': v['actor'],
+        if (v['keyHash'] != null) 'nomos.authz.keyHash': v['keyHash'],
+        if (v['object'] != null) 'nomos.authz.object': v['object'],
+        if (v['relation'] != null) 'nomos.authz.relation': v['relation'],
+        'nomos.authz.directiveId': directiveId,
+        if (cause != null) 'nomos.authz.cause': cause,
+      },
+    );
+    throw nomosErrorFromInfo(info);
+  }
+
   // NO per-method Stream/watch/snapshot overrides live here anymore — the base class routes ALL event
   // dispatch + plane state through [_eventPlane] (and law-scopes compat/onLawChanged via [_sessionName]),
   // and the watch ops still carry this session's workspace because their registration goes through the

package/dart/pubspec.lock

@@ -191,7 +191,7 @@ packages:
       path: "../dart_types"
       relative: true
     source: path
-    version: "0.3.0"
+    version: "0.4.0"
   package_config:
     dependency: transitive
     description:

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.52.0
+version: 0.54.0
 
 environment:
   sdk: ^3.5.0
@@ -20,7 +20,7 @@ dependencies:
   # The pure-data core (wire types, offer codec, NomosReads, schema validation, error
   # info). nomos_client depends on and re-exports it, so existing imports are unchanged.
   # For local monorepo dev, pubspec_overrides.yaml points this at ../dart_types.
-  nomos_types: ^0.3.0
+  nomos_types: ^0.4.0
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

package/dart/test/acquire_session_test.dart

@@ -17,7 +17,7 @@ class FakeRunner implements BridgeTransport {
 
   FakeRunner({this.resident = const []}) {
     scheduleMicrotask(
-        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready', 'bundleVersion': 'unbundled-dev'}));
   }
 
   int get connectCount => sent.where((m) => m['op'] == 'connect').length;

package/dart/test/bundle_version_pairing_test.dart

@@ -0,0 +1,40 @@
+// THE VERSION-PAIRING TRIPWIRE (the pubspec-pins pattern): kExpectedRunnerBundleVersion must equal
+// the @githolon/client version this repo is about to release (cloud/web-client/package.json) — a
+// client release without the Dart floor bump (or vice versa) fails the suite, so the stale-bundle
+// check can neither lag (missing real staleness) nor lead (refusing the current bundle).
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('kExpectedRunnerBundleVersion pairs with cloud/web-client/package.json', () {
+    final f = File('${Directory.current.path}/../../cloud/web-client/package.json');
+    if (!f.existsSync()) {
+      markTestSkipped('monorepo layout not present (published-package test run)');
+      return;
+    }
+    final v = (jsonDecode(f.readAsStringSync()) as Map)['version'] as String;
+    if (kExpectedRunnerBundleVersion == v) return; // released state: exact pair
+    // PENDING-RELEASE state: the floor may lead package.json by exactly the bump a queued
+    // changeset will apply (the changesets flow bumps package.json only when the version PR
+    // merges). Anything else — lagging, or leading with no changeset queued — is drift.
+    final changesets = Directory('${Directory.current.path}/../../.changeset')
+        .listSync()
+        .whereType<File>()
+        .where((c) => c.path.endsWith('.md') && !c.path.endsWith('README.md'))
+        .where((c) => c.readAsStringSync().contains('@githolon/client'));
+    expect(changesets, isNotEmpty,
+        reason: 'kExpectedRunnerBundleVersion ($kExpectedRunnerBundleVersion) != @githolon/client '
+            '($v) and NO client changeset is queued — bump the floor WITH the client release '
+            '(the stale-bundle floor must move with the bundle it ships beside)');
+    List<int> parse(String x) =>
+        x.split('.').map((p) => int.tryParse(p) ?? 0).toList();
+    final a = parse(kExpectedRunnerBundleVersion), b = parse(v);
+    final leads = a[0] > b[0] ||
+        (a[0] == b[0] && (a[1] > b[1] || (a[1] == b[1] && a[2] > b[2])));
+    expect(leads, isTrue,
+        reason: 'the floor must LEAD (never lag) package.json while a release is queued');
+  });
+}

package/dart/test/errors_test.dart

@@ -68,6 +68,58 @@ void main() {
     expect(l.recommendedAction, NomosRecommendedAction.retry);
   });
 
+  test('authz signer_enrollment_missing mints ParentSignerEnrollmentMissing with the ONE remedy', () {
+    final e = nomosErrorFromInfo(info(
+      'nomos.authz.signer_enrollment_missing',
+      workspace: 'co2-platform',
+      attrs: {
+        'nomos.authz.actor': 'user:u-1',
+        'nomos.authz.keyHash': 'abab',
+        'nomos.authz.object': 'identity:u-1',
+        'nomos.authz.directiveId': 'birthEstateWorkspace',
+      },
+    ));
+    expect(e, isA<NomosBridgeError>());
+    expect(e, isA<AuthzRefusedError>());
+    expect(e, isA<ParentSignerEnrollmentMissing>());
+    final p = e as ParentSignerEnrollmentMissing;
+    expect(p.cause, 'missing-signer-enrollment');
+    expect(p.workspace, 'co2-platform');
+    expect(p.actor, 'user:u-1');
+    expect(p.keyHash, 'abab');
+    expect(p.object, 'identity:u-1');
+    expect(p.relation, 'signer');
+    expect(p.directiveId, 'birthEstateWorkspace');
+    expect(p.recommendedAction, NomosRecommendedAction.ensureParentSignerEnrollment);
+  });
+
+  test('authz cause=missing-signer-enrollment routes to ParentSignerEnrollmentMissing even under the generic code', () {
+    final e = nomosErrorFromInfo(info(
+      'nomos.authz.refused',
+      attrs: {'nomos.authz.cause': 'missing-signer-enrollment', 'nomos.authz.actor': 'user:u-9'},
+    ));
+    expect(e, isA<ParentSignerEnrollmentMissing>());
+  });
+
+  test('authz missing_role stays AuthzRefusedError — role-absent is DISTINGUISHED from signer-absent', () {
+    final e = nomosErrorFromInfo(info(
+      'nomos.authz.missing_role',
+      workspace: 'ws-1',
+      attrs: {
+        'nomos.authz.cause': 'missing-role',
+        'nomos.authz.relation': 'creator',
+        'nomos.authz.object': 'workspace:self',
+        'nomos.authz.actor': 'user:u-2',
+      },
+    ));
+    expect(e, isA<AuthzRefusedError>());
+    expect(e, isNot(isA<ParentSignerEnrollmentMissing>()));
+    final a = e as AuthzRefusedError;
+    expect(a.cause, 'missing-role');
+    expect(a.relation, 'creator');
+    expect(a.object, 'workspace:self');
+  });
+
   test('custody.* still mints CustodyError (unchanged), unknown codes stay generic', () {
     expect(nomosErrorFromInfo(info('nomos.custody.missing_object')), isA<CustodyError>());
     final g = nomosErrorFromInfo(info('nomos.bridge.error'));

package/dart/test/fixtures/wedge/wedge-entry.mjs

@@ -7,7 +7,7 @@ import { createInterface } from "node:readline";
 const post = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
 const wedgeOp = process.env.NOMOS_WEDGE_OP || "connect"; // default: wedge the KEYED reconnect (co2's shape)
 const wedgeOnlyKeyed = process.env.NOMOS_WEDGE_ONLY_KEYED !== "0";
-post({ v: 1, event: "ready" });
+post({ v: 1, event: "ready", bundleVersion: "unbundled-dev" });
 const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
 rl.on("line", (line) => {
   const s = line.trim();

package/dart/test/parent_signer_recovery_test.dart

@@ -0,0 +1,134 @@
+// PARENT-SIGNER RECOVERY — the Dart surface leg (offline, the real runner + wasm).
+//
+// The co2 gap: after a parent custody rebirth the device key stays valid but the parent's chain no
+// longer carries `identity:<uid>#signer` — and there was NO published Dart recovery path. This proves
+// the new surfaces end-to-end over the node runner:
+//   · `canAuthor` / `canAuthorTyped` — the read-only preflight returns the TYPED verdict
+//     (cause `missing-signer-enrollment` → ParentSignerEnrollmentMissing) BEFORE any authoring;
+//   · `ensureParentSignerEnrollment` — idempotent verify-and-repair on the parent (repairs when the
+//     tuple is absent, pure no-op when live) with the signing directive DISCOVERED from the law;
+//   · `parentSignerEnrollment` — the diagnostic posture read;
+//   · after the repair, canAuthor flips ok and a SIGNED birthEstateWorkspace admits.
+// (The warranted-reborn-parent kernel legs — the exact refusal + the keyless enrollFirstDevice
+// recovery — are proven on the wasm by bench/scale/parent_signer_recovery.smoke.mjs.)
+@TestOn('vm')
+library;
+
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:nomos_types/nomos_types.dart'
+    show ParentSignerEnrollmentMissing, NomosRecommendedAction;
+import 'package:test/test.dart';
+
+String get _root => '${Directory.current.path}/../..';
+String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.mjs';
+String get _deploy =>
+    '$_root/bench/scale/fixtures/estate-birth-signed/build/estate-birth-signed.deploy.json';
+String get _runtimeDir => '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+const _ws = 'estate-birth-signed';
+const _uid = 'sample-owner';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  if (!File(_deploy).existsSync()) {
+    return 'compile the fixture: cd bench/scale/fixtures/estate-birth-signed && node ../../../../dsl/compile_package.mjs';
+  }
+  if (!File('$_runtimeDir/holon.wasm').existsSync()) {
+    return 'warm ~/.holon/runtime first (run any `githolon` command once)';
+  }
+  return null;
+}
+
+void main() {
+  test(
+      'canAuthor preflights the missing parent signer TYPED, ensureParentSignerEnrollment repairs it, '
+      'and the signed birth then admits', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_deploy],
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      workspace: _ws,
+    );
+    try {
+      final session = harness.bridge.session(_ws);
+      final device = await session.mintDeviceKey();
+      final pub = device['public']!.toString();
+      final secret = device['secret']!.toString();
+
+      // devicePublicOf re-derives the public half from the persisted seed (the Dart key store keeps
+      // only the secret) — the recovery lanes depend on this.
+      expect(await session.devicePublicOf(secret), pub);
+
+      // 1. THE PREFLIGHT, broken state: the verdict names the failing premise BEFORE any authoring.
+      final v0 = await session.canAuthor('birthEstateWorkspace',
+          ws: _ws, principal: _uid, publicKey: pub);
+      expect(v0['ok'], isNot(true));
+      expect(v0['cause'], 'missing-signer-enrollment');
+      expect(v0['actor'], 'user:$_uid');
+      expect((v0['keyHash'] ?? '').toString(), hasLength(64));
+
+      // ...and the TYPED variant throws the ONE error with the ONE remedy.
+      await expectLater(
+        session.canAuthorTyped('birthEstateWorkspace', ws: _ws, principal: _uid, publicKey: pub),
+        throwsA(isA<ParentSignerEnrollmentMissing>()
+            .having((e) => e.recommendedAction, 'recommendedAction',
+                NomosRecommendedAction.ensureParentSignerEnrollment)
+            .having((e) => e.workspace, 'workspace', _ws)),
+      );
+
+      // 2. THE POSTURE READ agrees (diagnostic; nothing authored).
+      final posture0 = await session.parentSignerEnrollment(
+          parent: _ws, principal: _uid, publicKey: pub);
+      expect(posture0['enrolled'], false);
+      expect(posture0['object'], 'identity:$_uid');
+      expect(posture0['relation'], 'signer');
+
+      // 3. THE REPAIR — idempotent; the signing directive is DISCOVERED from the installed law
+      //    (this fixture composes it under domain "home", NOT the framework "workspaces").
+      final r1 = await session.ensureParentSignerEnrollment(
+          parent: _ws, principal: _uid, publicKey: pub, authorSecret: secret);
+      expect(r1['enrolled'], true);
+      expect(r1['repaired'], true);
+      expect(r1['domain'], 'home',
+          reason: 'discovery must find the tenant-composed domain, never assume "workspaces"');
+
+      // 4. Re-run = pure no-op (the idempotence contract).
+      final r2 = await session.ensureParentSignerEnrollment(
+          parent: _ws, principal: _uid, publicKey: pub, authorSecret: secret);
+      expect(r2['enrolled'], true);
+      expect(r2['repaired'], false);
+
+      // 5. The preflight flips OK…
+      final v1 = await session.canAuthor('birthEstateWorkspace',
+          ws: _ws, principal: _uid, publicKey: pub);
+      expect(v1['ok'], true, reason: 'causes: ${v1['causes']}');
+
+      // 6. …and the SIGNED sibling birth ADMITS (per-offer signing key — the repaired device).
+      final lawHash = harness.lawHashes(_ws).first;
+      final outcome = await session.offerCreates(
+        domain: 'home',
+        directiveId: 'birthEstateWorkspace',
+        payload: {
+          'owner': 'user:$_uid',
+          'frameworkHash': harness.frameworkHash,
+          'lawHash': lawHash,
+          'bornAt': '2026-07-12T00:00:00Z',
+        },
+        actor: 'user:$_uid',
+        authorSecret: secret,
+      );
+      expect(outcome.head, isNotEmpty);
+      expect(outcome.born, isNotEmpty,
+          reason: 'the estate child births after the signer repair');
+    } finally {
+      await harness.dispose();
+    }
+  }, timeout: const Timeout(Duration(minutes: 3)));
+}

package/dart/test/stale_bundle_test.dart

@@ -0,0 +1,65 @@
+// THE STALE-BAKED-BUNDLE CHECK (the countermeasure to the co2 incidents where Flutter's build
+// cache silently kept an old nomos-runner.js across a correct pub upgrade). ready carries the
+// bundle's self-stamped version; the bridge refuses stale/pre-stamp bundles LOUDLY at boot.
+import 'dart:async';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+class _StampedRunner implements BridgeTransport {
+  _StampedRunner(this.stamp) {
+    scheduleMicrotask(() => _incoming.add({
+          'v': kWebviewBridgeVersion,
+          'event': 'ready',
+          if (stamp != null) 'bundleVersion': stamp,
+        }));
+  }
+  final String? stamp;
+  final _incoming = StreamController<Map<String, Object?>>.broadcast();
+  @override
+  Stream<Map<String, Object?>> get messages => _incoming.stream;
+  @override
+  void send(Map<String, Object?> message) {}
+}
+
+void main() {
+  test('a PRE-STAMP bundle (no bundleVersion) fails ready with StaleRunnerBundle', () async {
+    final b = NomosBridge(_StampedRunner(null));
+    await expectLater(b.ready, throwsA(isA<StaleRunnerBundle>()));
+  });
+
+  test('an OLDER stamp fails ready, and the error names found/expected + the remedy', () async {
+    final b = NomosBridge(_StampedRunner('0.53.1'));
+    Object? err;
+    try {
+      await b.ready;
+    } catch (e) {
+      err = e;
+    }
+    expect(err, isA<StaleRunnerBundle>());
+    final s = err.toString();
+    expect(s, contains('0.53.1'));
+    expect(s, contains(kExpectedRunnerBundleVersion));
+    expect(s, contains('flutter clean'));
+  });
+
+  test('the CURRENT stamp passes', () async {
+    final b = NomosBridge(_StampedRunner(kExpectedRunnerBundleVersion));
+    await b.ready; // completes
+  });
+
+  test('a NEWER stamp passes (forward-compatible)', () async {
+    final b = NomosBridge(_StampedRunner('99.0.0'));
+    await b.ready;
+  });
+
+  test('unbundled-dev (the in-repo source lane) always passes', () async {
+    final b = NomosBridge(_StampedRunner('unbundled-dev'));
+    await b.ready;
+  });
+
+  test('allowStaleRunnerBundle is the deliberate escape hatch', () async {
+    final b = NomosBridge(_StampedRunner('0.1.0'), allowStaleRunnerBundle: true);
+    await b.ready;
+  });
+}

package/dart/test/webview_bridge_test.dart

@@ -20,7 +20,7 @@ class FakeRunner implements BridgeTransport {
   FakeRunner() {
     // the runner announces readiness at construction.
     scheduleMicrotask(
-        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready', 'bundleVersion': 'unbundled-dev'}));
   }
 
   @override
@@ -183,7 +183,7 @@ class ReplayTransport implements BridgeTransport {
   Map<String, Object?>? lastRequest;
   ReplayTransport(this.result) {
     scheduleMicrotask(
-        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready', 'bundleVersion': 'unbundled-dev'}));
   }
   @override
   Stream<Map<String, Object?>> get messages => _incoming.stream;

package/dart_types/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.4.0
+
+- Typed authorization diagnosis errors: `AuthzRefusedError` ({workspace, actor, keyHash, object,
+  relation, directiveId, cause}) and `ParentSignerEnrollmentMissing` (the one remedy named:
+  `ensureParentSignerEnrollment`) — "valid user, but this device cannot prove it" and "user lacks
+  the role" are now distinct typed diagnoses. `NomosRecommendedAction.ensureParentSignerEnrollment`.
+
 ## 0.3.0
 
 - `SurfacedValue<T>` — the typed read surface for `Surfaced(inner)` merge-driver fields: sealed

package/dart_types/lib/src/errors.dart

@@ -23,6 +23,7 @@ import 'error_info.dart' show NomosBridgeError, NomosErrorInfo;
 NomosBridgeError nomosErrorFromInfo(NomosErrorInfo info) {
   if (info.code.startsWith('nomos.custody.')) return CustodyError.fromInfo(info);
   if (info.code.startsWith('nomos.law.')) return LawMismatchError.fromInfo(info);
+  if (info.code.startsWith('nomos.authz.')) return AuthzRefusedError.fromInfo(info);
   if (info.code.startsWith('nomos.auth.')) return AuthError.fromInfo(info);
   if (info.code.startsWith('nomos.load.')) return LoadError.fromInfo(info);
   return NomosBridgeError(info.message, info: info);
@@ -56,6 +57,11 @@ class NomosRecommendedAction {
   /// Re-open the holon / reconnect fresh (the loaded runtime is unusable).
   static const reopen = 'reopen';
 
+  /// Restore the device signer on the parent workspace (`ensureParentSignerEnrollment` /
+  /// [NomosScope.home] repairs it automatically on reopen) — the ONE remedy for
+  /// [ParentSignerEnrollmentMissing] (a reborn parent that lost the signer tuple).
+  static const ensureParentSignerEnrollment = 'ensureParentSignerEnrollment';
+
   /// No automatic remedy — surface to a human.
   static const none = 'none';
 
@@ -76,6 +82,8 @@ class NomosRecommendedAction {
         return 'retry the operation';
       case reopen:
         return 'reopen the holon (reconnect fresh)';
+      case ensureParentSignerEnrollment:
+        return 'restore the device signer on the parent (ensureParentSignerEnrollment / NomosScope.home repairs it on reopen)';
       case none:
         return 'no automatic remedy — inspect the error';
       default:
@@ -175,6 +183,136 @@ class LawMismatchError extends NomosBridgeError {
   String toString() => 'LawMismatchError($code): $mismatchMessage';
 }
 
+/// AUTHZ REFUSAL — the kernel's relation/signer gate refused an authored intent (`nomos.authz.*`).
+/// ONE structured diagnosis instead of hand-comparing relation tuples across two workspaces: it names
+/// the evaluated [workspace], [actor], [keyHash], [object], [relation] and the [cause] the gate
+/// distinguished:
+///   - `missing-signer-enrollment` — the signature is valid but `identity:<actor>#signer@key:<keyHash>`
+///     is absent on the judging workspace (the reborn-parent case) → [ParentSignerEnrollmentMissing].
+///   - `missing-role` — the signer binding held (or was not required) but the directive's
+///     `.requires(<relation>)` tuple is absent for the actor on [object].
+/// These fields ride the UNSEALED presentation lanes only (verdict / 422 body / bridge errorInfo) —
+/// never the sealed chain bytes.
+class AuthzRefusedError extends NomosBridgeError {
+  /// The stable machine code, e.g. `nomos.authz.signer_enrollment_missing`.
+  final String code;
+
+  /// The workspace whose gate judged the offer (e.g. the PARENT for a sibling birth).
+  final String? workspace;
+
+  /// The evaluated actor (`user:<uid>`).
+  final String? actor;
+
+  /// sha256(device public key) — the on-chain `key:<hash>` subject the gate checked.
+  final String? keyHash;
+
+  /// The Zanzibar object checked (e.g. `identity:<uid>` / `workspace:self`).
+  final String? object;
+
+  /// The required relation (`signer` for the enrollment premise; the `.requires(...)` relation otherwise).
+  final String? relation;
+
+  /// The refused directive, when known.
+  final String? directiveId;
+
+  /// WHICH premise failed: `missing-signer-enrollment` | `missing-role` | `revoked-signer` | …
+  final String? cause;
+
+  /// The named remedy.
+  final String recommendedAction;
+
+  AuthzRefusedError({
+    required this.code,
+    required String message,
+    this.workspace,
+    this.actor,
+    this.keyHash,
+    this.object,
+    this.relation,
+    this.directiveId,
+    this.cause,
+    this.recommendedAction = NomosRecommendedAction.none,
+    NomosErrorInfo? info,
+  }) : super(message, info: info);
+
+  factory AuthzRefusedError.fromInfo(NomosErrorInfo info) {
+    String? attr(String name) {
+      final v = info.attributes['nomos.authz.$name'] ?? info.attributes[name];
+      return v?.toString();
+    }
+
+    final cause = attr('cause');
+    final fields = (
+      workspace: info.workspace,
+      actor: attr('actor'),
+      keyHash: attr('keyHash') ?? attr('key_hash'),
+      object: attr('object'),
+      relation: attr('relation'),
+      directiveId: attr('directiveId') ?? attr('directive_id') ?? attr('directive'),
+    );
+    if (info.code == 'nomos.authz.signer_enrollment_missing' || cause == 'missing-signer-enrollment') {
+      return ParentSignerEnrollmentMissing(
+        message: info.message,
+        workspace: fields.workspace,
+        actor: fields.actor,
+        keyHash: fields.keyHash,
+        object: fields.object,
+        directiveId: fields.directiveId,
+        info: info,
+      );
+    }
+    return AuthzRefusedError(
+      code: info.code,
+      message: info.message,
+      workspace: fields.workspace,
+      actor: fields.actor,
+      keyHash: fields.keyHash,
+      object: fields.object,
+      relation: fields.relation,
+      directiveId: fields.directiveId,
+      cause: cause,
+      recommendedAction: attr('recommendedAction') ?? attr('recommended_action') ?? NomosRecommendedAction.none,
+      info: info,
+    );
+  }
+
+  @override
+  String toString() =>
+      'AuthzRefusedError($code${workspace != null ? ', workspace: $workspace' : ''}'
+      '${actor != null ? ', actor: $actor' : ''}${keyHash != null ? ', keyHash: $keyHash' : ''}'
+      '${object != null ? ', object: $object' : ''}${relation != null ? ', relation: $relation' : ''}'
+      '${cause != null ? ', cause: $cause' : ''}, recommendedAction: $recommendedAction): $message';
+}
+
+/// PARENT SIGNER ENROLLMENT MISSING (`nomos.authz.signer_enrollment_missing`) — the device key is valid
+/// and enrolled in the home, but the judging PARENT's chain (e.g. after a custody REBIRTH) no longer
+/// carries the `identity:<actor>#signer@key:<keyHash>` tuple, so a correctly-signed offer (a sibling
+/// birth like `birthEstateWorkspace`) is refused. THE ONE SUPPORTED REMEDY:
+/// `session.ensureParentSignerEnrollment(...)` — [NomosScope.home] runs it automatically on reopen.
+class ParentSignerEnrollmentMissing extends AuthzRefusedError {
+  ParentSignerEnrollmentMissing({
+    required String message,
+    String? workspace,
+    String? actor,
+    String? keyHash,
+    String? object,
+    String? directiveId,
+    NomosErrorInfo? info,
+  }) : super(
+          code: 'nomos.authz.signer_enrollment_missing',
+          message: message,
+          workspace: workspace,
+          actor: actor,
+          keyHash: keyHash,
+          object: object,
+          relation: 'signer',
+          directiveId: directiveId,
+          cause: 'missing-signer-enrollment',
+          recommendedAction: NomosRecommendedAction.ensureParentSignerEnrollment,
+          info: info,
+        );
+}
+
 /// AUTH — the auth-provider token was missing/malformed/expired/rejected, or its issuer does not match the
 /// workspace's law-declared key (`nomos.auth.*`, e.g. `nomos.auth.issuer_mismatch`, `nomos.auth.token_invalid`,
 /// `nomos.auth.token_expired`). REMEDY is always `reauth`: acquire a fresh token and reconnect.

package/dart_types/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Pure kernel wire/data types for Nomos Dart frontends — no transport, no bridge,
   no runtime. The hand-written serde-JSON-compatible types plus the offer codec,
   reactive read engine, schema validation, and data-only error/trace types.
-version: 0.3.0
+version: 0.4.0
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.77.0",
+  "version": "0.78.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/compile_package_main.ts

@@ -924,11 +924,11 @@ const DART_TYPES_IMPORT = `import 'package:nomos_types/nomos_types.dart';`;
  *  just the floor generated code needs — a lagging pin forces tenants into dependency_overrides. */
 // 0.3.0: SurfacedValue<T>/SurfacedObservation/PendingConflictRow — generated Surfaced-field typing +
 //        the pendingConflicts read rows.
-const NOMOS_TYPES_DEP = "^0.3.0";
+const NOMOS_TYPES_DEP = "^0.4.0";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.52.0";
+const NOMOS_CLIENT_DEP = "^0.54.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).