@githolon/dsl 0.77.1 → 0.79.0

package/dart/CHANGELOG.md

@@ -1,3 +1,35 @@
+## 0.54.1
+
+- **Fix: principal normalization mismatch in signer recovery** — enrollment wrote
+  `identity:user:<uid>#signer` (the kernel-canonical captured principal) while the posture/preflight
+  reads stripped `user:` and reported false `missing-signer-enrollment` immediately after a
+  successful repair. One canonical normalizer now routes every surface; co2's five-step acceptance
+  (repair → immediate enrolled:true → canAuthor ok → birth admits) is the regression test, with
+  `user:`-shaped principals, proven failing-then-passing. Typed authz diagnosis now also rides the
+  `createWorkspace` relay (no more generic 422).
+
+## 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

@@ -48,7 +48,7 @@ const int kWebviewBridgeVersion = 1;
 /// 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.77.1';
+const String kExpectedRunnerBundleVersion = '0.78.1';
 
 /// 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
@@ -1229,6 +1229,7 @@ class NomosBridge {
     List<Map<String, Object?>>? attestations,
     bool? force,
     String? session,
+    String? authorSecret,
   }) =>
       offerOutcome(
         domain: domain,
@@ -1239,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]
@@ -1255,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
@@ -1274,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,
@@ -1558,7 +1564,20 @@ class NomosBridge {
       throw await _wrapDomainNotInstalled(e,
           domain: domain, domainHash: domainHash, requestedWorkspace: parent);
     }
-    return (r['verdict'] as Map?)?.cast<String, Object?>() ?? r;
+    final verdict = (r['verdict'] as Map?)?.cast<String, Object?>() ?? r;
+    // STRUCTURED AUTHZ REFUSAL (co2 DX): a refused relay used to surface only the generic 422 body.
+    // The JS relay now classifies the kernel refusal into `nomos.authz.*` errorInfo — mint the SAME
+    // typed error the offerDirective lane throws ([ParentSignerEnrollmentMissing]/[AuthzRefusedError])
+    // so the app sees the diagnosis (actor/keyHash/object/relation/cause), not prose. Non-authz
+    // refusals keep the verdict-return contract unchanged.
+    if (verdict['ok'] == false) {
+      final info = verdict['errorInfo'];
+      final code = info is Map ? (info['code'] ?? '').toString() : '';
+      if (code.startsWith('nomos.authz.')) {
+        throw nomosErrorFromInfo(NomosErrorInfo.fromJson(info));
+      }
+    }
+    return verdict;
   }
 
   /// SHARE a workspace/record with a user — the one-call cross-custody grant that lands in their home's
@@ -1692,6 +1711,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
@@ -2258,6 +2358,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.1"
   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.1
 
 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.1
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

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/parent_signer_recovery_test.dart

@@ -0,0 +1,151 @@
+// 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';
+// THE co2 REGRESSION SHAPE: the principal arrives ALREADY `user:`-qualified (the captured-actor wire
+// form — exactly what NomosScope/co2 pass). KERNEL TRUTH: the gate checks
+// `identity:<captured principal VERBATIM>`, so every read/repair below must resolve the object to
+// `identity:user:<uid>` — a stripped `identity:<uid>` is the normalization bug this test pins.
+const _principal = 'user:$_uid';
+
+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: _principal, publicKey: pub);
+      expect(v0['ok'], isNot(true));
+      expect(v0['cause'], 'missing-signer-enrollment');
+      expect(v0['actor'], _principal,
+          reason: 'the canonical actor is the principal VERBATIM — never stripped, never double-prefixed');
+      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: _principal, 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: _principal, publicKey: pub);
+      expect(posture0['enrolled'], false);
+      // KERNEL TRUTH (executor::signer_object): the object is identity:<captured principal VERBATIM>
+      // — `identity:user:<uid>`, NOT a stripped `identity:<uid>` (the co2 normalization bug).
+      expect(posture0['object'], 'identity:$_principal');
+      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: _principal, 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: _principal, 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: _principal, publicKey: pub);
+      expect(v1['ok'], true, reason: 'causes: ${v1['causes']}');
+
+      // 5b. co2's step-5 regression VERBATIM: immediately after repaired:true, the POSTURE read (with
+      // the SAME user:-qualified principal) reports enrolled:true against the canonical object.
+      final posture1 = await session.parentSignerEnrollment(
+          parent: _ws, principal: _principal, publicKey: pub);
+      expect(posture1['enrolled'], true,
+          reason: 'the repair wrote identity:$_principal — a second normalizer that strips user: '
+              'would read identity:$_uid and wrongly report missing-signer-enrollment');
+      expect(posture1['object'], 'identity:$_principal');
+
+      // 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_types/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.4.1
+
+- `canonicalPrincipal` / `signerObjectOf` — THE one principal normalizer (kernel truth:
+  `identity:<actor-verbatim>`, never stripped). All signer-recovery surfaces route through it.
+
+## 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/lib/src/principal.dart

@@ -54,3 +54,26 @@ class NomosDeviceSecret {
   @override
   String toString() => 'NomosDeviceSecret(***)';
 }
+
+/// THE ONE PRINCIPAL NORMALIZER (Dart surface — mirrors `@githolon/client` `canonicalPrincipal`).
+///
+/// KERNEL TRUTH (`executor/src/lib.rs::signer_object` + `verify_author_and_derive`): the
+/// authorization gate checks `identity:<captured principal VERBATIM>` where the captured principal
+/// is the actor string the offer presented (`user:<uid>` on every SDK lane). The kernel never strips
+/// or qualifies; neither may we. NEVER strip `user:`; qualify a bare auth-provider uid to
+/// `user:<uid>` exactly once, HERE. Every producer and consumer of `identity:*#signer` objects
+/// routes through this — a second normalizer is the bug (the co2 principal-normalization mismatch).
+///
+/// - `user:abc` → `user:abc` (verbatim)
+/// - `abc`      → `user:abc` (bare uid, qualified once)
+/// - any other namespaced subject (`key:<hash>`, …) rides verbatim
+/// - empty/whitespace → `''`
+String canonicalPrincipal(String? principal) {
+  final s = (principal ?? '').trim();
+  if (s.isEmpty) return '';
+  return s.contains(':') ? s : 'user:$s';
+}
+
+/// The Zanzibar OBJECT for a principal's signer relation — `identity:<canonical principal>`
+/// (mirrors `executor::signer_object` over the captured principal).
+String signerObjectOf(String? principal) => 'identity:${canonicalPrincipal(principal)}';

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.1
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.77.1",
+  "version": "0.79.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/build_package.ts

@@ -74,7 +74,7 @@ import { domainHash, emitManifestBytes } from "./manifest.js";
 import { collectValueObjectDescriptors } from "./value_object.js";
 import { emitUsd } from "./usd.js";
 import { expandCapabilityExports } from "./capability_exports.js";
-import { RelationTuple } from "./framework/relations.js";
+import { RelationTuple, relationTuplesByObject } from "./framework/relations.js";
 import { parentAttestedBirthMarker } from "./births.js";
 import { discoverUnsanctionedEnsures, sanctioningEnsureDirective } from "./secondary_ensure.js";
 import { assertIdOfLint } from "./idof_lint.js";
@@ -277,6 +277,21 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     }
   }
   const relationTypes = [...(spec.relationTypes ?? [])];
+  // RELATION-USING LAW AUTO-COMPOSES ITS AUDIT READ (co2 recovery DX — same idiom as the meter
+  // queries above): a domain that declares relation law (a relation schema, a `.requires(...)` gated
+  // directive, or relate-family/signer directives ensuring RelationTuple) gets the framework's
+  // `relationTuplesByObject` query appended (dedup by id) so the signer-recovery lanes
+  // (parentSignerEnrollment / ensureParentSignerEnrollment / canAuthor) can read the tuples on any
+  // workspace running the law — no tenant re-export to forget. ERA/OMIT RULE: a relation-free domain
+  // appends nothing (byte-identical module/package); a relation-using one gains the query on its NEXT
+  // recompile (a named, additive hash move the #58 evolve gate admits silently).
+  const usesRelations =
+    relationTypes.length > 0 ||
+    directives.some((d) => (d as { requiresRelationGate?: unknown }).requiresRelationGate !== undefined) ||
+    directives.some((d) => d.aggregateId === RelationTuple.id);
+  if (usesRelations && !queries.some((q) => q.id === relationTuplesByObject.id)) {
+    queries.push(relationTuplesByObject);
+  }
   // FIRST-CLASS VALUE OBJECTS (value_object.ts): the deduped, sorted descriptors of every
   // named VO the domain's aggregates carry (transitive nested VOs included) — the input to
   // the additive `nomosValueObjects` USD key. Omit-when-empty (era rule): a VO-free domain's

package/src/compile_package_main.ts

@@ -70,6 +70,7 @@ import {
   isFrameworkDirective,
   isFrameworkQuery,
 } from "./framework/framework_aggregates.js";
+import { RelationTuple, relationTuplesByObject } from "./framework/relations.js";
 import { finishCount, type AnyCount } from "./count.js";
 import type { QueryDecl } from "./query.js";
 import type { SpatialDecl } from "./spatial.js";
@@ -924,11 +925,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.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.52.0";
+const NOMOS_CLIENT_DEP = "^0.54.1";
 // 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).
@@ -1588,6 +1589,26 @@ async function main(): Promise<void> {
         if (!haveQuery.has(q.id)) queries.push(q);
       }
     }
+    // RELATION-USING LAW AUTO-COMPOSES ITS AUDIT READ (co2 recovery DX, same idiom as the birth-meter
+    // queries above): any domain that declares relation law — a relation schema, a `.requires(...)`
+    // gated directive, or the signer/grant primitives (directives ensuring `RelationTuple`) — gets the
+    // framework's `relationTuplesByObject` query appended (dedup by id), so the recovery lanes
+    // (parentSignerEnrollment / ensureParentSignerEnrollment / canAuthor) can read the signer tuples
+    // on ANY workspace running that law without the tenant remembering the re-export. ERA/OMIT RULE:
+    // a domain with no relation law emits NOTHING new (byte-identical package); a relation-using
+    // domain's package/openapi gain one query on its NEXT recompile — a named, expected hash move
+    // (the stable-ids doctrine: recompiles move identity/package hashes; already-deployed artifacts
+    // are untouched, and a query add is additive so the #58 evolve gate admits it silently).
+    {
+      const dirsAll = directivesOf(merged);
+      const usesRelations =
+        dirsAll.some((dir) => (dir as { requiresRelationGate?: unknown }).requiresRelationGate !== undefined) ||
+        dirsAll.some((dir) => (dir as { aggregateId?: string }).aggregateId === RelationTuple.id) ||
+        discover<RelationTypeDecl>(merged, isRelationTypeDecl).length > 0;
+      if (usesRelations && !queries.some((q) => q.id === relationTuplesByObject.id)) {
+        queries.push(relationTuplesByObject);
+      }
+    }
     const counts = [
       ...discover<AnyCount>(merged, isCountDecl),
       ...resolveNamed<AnyCount>(merged, d.counts, "counts"),