@githolon/dsl 0.35.0 → 0.37.0

package/dart/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.28.0
+
+- `NomosTestHarness` (`nomos_headless.dart`): ephemeral real-law fixtures — one call births a throwaway cloud workspace, deploys compiled `*.deploy.json` law, and hands out independent client replicas (`connect(clientId:)`) over the node runner. Identity defaults to the `githolon login --agent` session (`~/.holon/credentials.json`). Live-proven: birth → deploy → write on one replica → converge + typed read on another, 14s end-to-end.
+- HEADLESS TRANSPORT (`package:nomos_client/nomos_headless.dart`): `NodeRunnerTransport` — a `BridgeTransport` over the `@githolon/client` node runner (`runner/node-entry.mjs`) as a plain child process (NDJSON stdio). `flutter test` / `dart test` / CI drive the REAL githolon (byte-identical wasm, real ledger, real gate) through `NomosBridge` + the generated typed clients — no Flutter plugins, no WebView, no assets. Requires `node` on PATH + a resolvable `@githolon/client` (auto-resolved from the app's node_modules, or pass `entry:`). Proven end-to-end: connect → offerDirective → sync(admit) → typed query, and the same test green under both `dart test` and `flutter test`.
+
 ## 0.27.0
 
 - TYPED SNAPSHOT RECOVERY (corrupt local custody): `NomosBridge.connect(recover: true)` recovers IN-PLACE from a corrupt restoreFrom snapshot — salvages local-only authored writes (via the fallible `intents_above`, which stops at a missing-ancestor gap) + the DLQ, refolds FRESH from cloud, re-offers the salvaged work (deduped), re-queues the DLQ. The report rides `bridge.lastRecovery` = `{salvagedWrites, requeuedDeadLetters, unsalvageable}` — a write the current law refuses lands in `unsalvageable` + the DLQ (surfaced, never dropped). Also `holon.salvage()` / `holon.absorbSalvage()`. Closes the restoreFrom-leaves-read-model-empty case.

package/dart/lib/nomos_headless.dart

@@ -0,0 +1,19 @@
+/// The HEADLESS transport library — `dart:io` only, so it lives outside the main
+/// `package:nomos_client/nomos_client.dart` barrel (which stays web-safe).
+///
+/// ```dart
+/// import 'package:nomos_client/nomos_client.dart';
+/// import 'package:nomos_client/nomos_headless.dart';
+///
+/// final transport = await NodeRunnerTransport.start(resolveFrom: 'path/to/app');
+/// final bridge = NomosBridge(transport);
+/// await bridge.ready;
+/// await bridge.connect(cloud: ..., workspace: ..., clientId: 'test-runner');
+/// ```
+///
+/// The runner child process is the SAME `@githolon/client` every peer runs; the
+/// generated Dart clients drive it through [NomosBridge] exactly as in the app.
+library;
+
+export 'src/node_runner_transport.dart';
+export 'src/test_harness.dart';

package/dart/lib/src/node_runner_transport.dart

@@ -0,0 +1,125 @@
+// THE HEADLESS (NODE) TRANSPORT — a [BridgeTransport] over the `@githolon/client` node runner
+// (`runner/node-entry.mjs`), spawned as a plain child process speaking the ONE bridge protocol as
+// newline-delimited JSON on stdio. This is what lets `dart test` / `flutter test` / CI drive the REAL
+// githolon (the byte-identical wasm, the real ledger, the real gate) through [NomosBridge] and the
+// generated typed clients — no Flutter plugins, no WebView, no assets. The only environment requirement
+// is `node` on PATH plus a resolvable `@githolon/client` (any app that compiles domains already has both).
+//
+// This file is a PURE RELAY: no orchestration, no op knowledge — the protocol implementation lives in
+// createWebviewRunner (shared with the WebView path) and the orchestration in index.mjs, same as every peer.
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'webview_bridge.dart' show BridgeTransport;
+
+class NodeRunnerTransport implements BridgeTransport {
+  final Process _proc;
+  final StreamController<Map<String, Object?>> _incoming =
+      StreamController<Map<String, Object?>>.broadcast();
+  final void Function(String line)? _onDiagnostic;
+  bool _disposed = false;
+
+  NodeRunnerTransport._(this._proc, this._onDiagnostic) {
+    _proc.stdout
+        .transform(utf8.decoder)
+        .transform(const LineSplitter())
+        .listen((line) {
+      final s = line.trim();
+      if (s.isEmpty) return;
+      Object? decoded;
+      try {
+        decoded = jsonDecode(s);
+      } catch (_) {
+        _diag('[nomos-node-runner stdout] $line');
+        return;
+      }
+      if (decoded is Map && !_incoming.isClosed) {
+        _incoming.add(decoded.cast<String, Object?>());
+      }
+    }, onDone: () {
+      if (!_disposed && !_incoming.isClosed) {
+        _incoming.addError(
+            StateError('the nomos node runner exited unexpectedly'));
+      }
+    });
+    _proc.stderr
+        .transform(utf8.decoder)
+        .transform(const LineSplitter())
+        .listen((line) => _diag('[nomos-node-runner] $line'));
+  }
+
+  void _diag(String line) {
+    final f = _onDiagnostic;
+    if (f != null) {
+      f(line);
+    } else {
+      stderr.writeln(line);
+    }
+  }
+
+  /// Spawn the node runner and return the connected transport. Wrap it in a
+  /// [NomosBridge] and `await bridge.ready` (the runner posts `{event:'ready'}`
+  /// on boot), then `connect(...)` as any other transport.
+  ///
+  /// [entry] — path to `node-entry.mjs`. When omitted it is resolved with
+  /// `require.resolve('@githolon/client/runner/node-entry.mjs')` from
+  /// [resolveFrom] (default: the current directory), i.e. the consuming app's
+  /// own `node_modules`.
+  static Future<NodeRunnerTransport> start({
+    String? entry,
+    String? resolveFrom,
+    String node = 'node',
+    Map<String, String>? environment,
+    void Function(String line)? onDiagnostic,
+  }) async {
+    final entryPath = entry ??
+        await _resolveEntry(node, resolveFrom ?? Directory.current.path);
+    final proc = await Process.start(
+      node,
+      [entryPath],
+      environment: environment,
+      workingDirectory: resolveFrom,
+    );
+    return NodeRunnerTransport._(proc, onDiagnostic);
+  }
+
+  static Future<String> _resolveEntry(String node, String from) async {
+    final r = await Process.run(
+      node,
+      ['-p', "require.resolve('@githolon/client/runner/node-entry.mjs')"],
+      workingDirectory: from,
+    );
+    final out = (r.stdout as String).trim();
+    if (r.exitCode != 0 || out.isEmpty) {
+      throw StateError(
+          'cannot resolve @githolon/client/runner/node-entry.mjs from $from — '
+          'is @githolon/client installed (npm install)? stderr: ${r.stderr}');
+    }
+    return out;
+  }
+
+  @override
+  Stream<Map<String, Object?>> get messages => _incoming.stream;
+
+  @override
+  void send(Map<String, Object?> message) {
+    if (_disposed) throw StateError('NodeRunnerTransport is disposed');
+    _proc.stdin.writeln(jsonEncode(message));
+  }
+
+  /// Tear down: stop the runner process and close the message stream.
+  Future<void> dispose() async {
+    if (_disposed) return;
+    _disposed = true;
+    try {
+      await _proc.stdin.close();
+    } catch (_) {}
+    _proc.kill(ProcessSignal.sigterm);
+    await _proc.exitCode.timeout(const Duration(seconds: 5), onTimeout: () {
+      _proc.kill(ProcessSignal.sigkill);
+      return -9;
+    });
+    await _incoming.close();
+  }
+}

package/dart/lib/src/test_harness.dart

@@ -0,0 +1,235 @@
+// NOMOS TEST HARNESS — ephemeral real-law fixtures for headless app tests. One call births a throwaway
+// workspace on the cloud, deploys the given compiled domain packages (`build/<name>.deploy.json`), and hands
+// out [NomosBridge]s over [NodeRunnerTransport] — the REAL githolon (byte-identical wasm, real ledger, real
+// gate) driven by the same generated Dart clients the app UI uses, under `flutter test` / `dart test` / CI.
+//
+// ```dart
+// final harness = await NomosTestHarness.ephemeral(
+//   deployJsonPaths: ['build/guestbook.deploy.json'],
+// );
+// final bridge = await harness.connect(clientId: 'test-runner');
+// final app = GuestbookClient(bridge); // the generated client — same one the app uses
+// ...
+// await harness.dispose();
+// ```
+//
+// Identity: a birth needs a principal. Pass [principal]/[authToken] explicitly, or the harness falls back to
+// the `githolon` CLI session (`~/.holon/credentials.json`, minted by `npx githolon login --agent`) — the same
+// self-onboarded verified identity the compile/deploy tooling uses. The token rides `x-nomos-auth` as proof;
+// its `sub` claim rides `x-nomos-principal` (the transitional bare claim the birth lane requires until kernel
+// birth-verify lands).
+//
+// The harness is HOST-LANE plumbing only (create + deploy are the open, kernel-gated cloud endpoints — the
+// same calls `githolon ws create` / `githolon deploy` make); everything after rides the one bridge protocol.
+// Workspaces are throwaway: there is no open destroy lane (reclaim is law-gated), so `dispose()` tears down
+// the local transports and leaves the ledger — name them uniquely (the default) and let them age out.
+import 'dart:convert';
+import 'dart:io';
+import 'dart:math';
+
+import 'node_runner_transport.dart';
+import 'webview_bridge.dart' show NomosBridge;
+
+class NomosTestHarnessException implements Exception {
+  final String message;
+  NomosTestHarnessException(this.message);
+  @override
+  String toString() => 'NomosTestHarnessException: $message';
+}
+
+class NomosTestHarness {
+  /// The cloud base URL the harness (and every bridge it connects) talks to.
+  final String cloud;
+
+  /// The ephemeral workspace name this harness birthed.
+  final String workspace;
+
+  final String? _principal;
+  final String? _authToken;
+  final String? _nodeEntry;
+  final String? _resolveFrom;
+  final void Function(String line)? _onDiagnostic;
+  final List<NodeRunnerTransport> _transports = [];
+  bool _disposed = false;
+
+  NomosTestHarness._(this.cloud, this.workspace, this._principal,
+      this._authToken, this._nodeEntry, this._resolveFrom, this._onDiagnostic);
+
+  /// Birth a throwaway workspace and deploy the given compiled domain packages into it.
+  ///
+  /// [deployJsonPaths] — the `build/<name>.deploy.json` files `nomos-compile` emits (deployed in order;
+  /// platform/framework law first when one domain's law depends on another's).
+  /// [workspace] — override the minted `test-<hex>` name (e.g. to reuse a workspace across a suite).
+  /// [principal]/[authToken] — the identity the workspace is born for; defaults to the `githolon` CLI
+  /// session (`~/.holon/credentials.json`).
+  /// [nodeEntry]/[resolveFrom] — forwarded to [NodeRunnerTransport.start].
+  static Future<NomosTestHarness> ephemeral({
+    List<String> deployJsonPaths = const [],
+    String cloud = 'https://nomos.captainapp.co.uk',
+    String? workspace,
+    String? principal,
+    String? authToken,
+    String? nodeEntry,
+    String? resolveFrom,
+    void Function(String line)? onDiagnostic,
+  }) async {
+    final id = _identity(principal, authToken);
+    final ws = workspace ?? 'test-${_hex(12)}';
+    final harness = NomosTestHarness._(_stripSlash(cloud), ws, id.principal,
+        id.authToken, nodeEntry, resolveFrom, onDiagnostic);
+    await harness._create();
+    for (final p in deployJsonPaths) {
+      await harness.deployLaw(p);
+    }
+    return harness;
+  }
+
+  static String _brief(String s) => s.length > 600 ? '${s.substring(0, 600)}…[+${s.length - 600} chars]' : s;
+
+  /// Deploy one more compiled package (`<name>.deploy.json`) into the workspace — e.g. a law evolve mid-test.
+  Future<void> deployLaw(String deployJsonPath) async {
+    final f = File(deployJsonPath);
+    if (!f.existsSync()) {
+      throw NomosTestHarnessException(
+          'deploy json not found: $deployJsonPath — run `npx githolon compile` first');
+    }
+    final r = await _post('/v2/workspaces/$workspace/domains',
+        body: await f.readAsString(), contentType: 'application/json');
+    if (r.$1 >= 300 || !(r.$2['ok'] == true)) {
+      throw NomosTestHarnessException(
+          'deploy of $deployJsonPath to $workspace refused (${r.$1}): ${_brief(r.$3)}');
+    }
+  }
+
+  /// Spawn a fresh runner + bridge connected to the harness workspace. Each call is an independent
+  /// client replica (own clientId → own session branch), so multi-client convergence is testable.
+  Future<NomosBridge> connect({
+    String clientId = 'test-runner',
+    String? authToken,
+    String? authorSecret,
+    bool allowUnborn = false,
+  }) async {
+    if (_disposed) throw StateError('harness is disposed');
+    final transport = await NodeRunnerTransport.start(
+      entry: _nodeEntry,
+      resolveFrom: _resolveFrom,
+      onDiagnostic: _onDiagnostic,
+    );
+    _transports.add(transport);
+    final bridge = NomosBridge(transport);
+    await bridge.ready.timeout(const Duration(seconds: 30));
+    await bridge.connect(
+      cloud: cloud,
+      workspace: workspace,
+      clientId: clientId,
+      authToken: authToken ?? _authToken,
+      authorSecret: authorSecret,
+      allowUnborn: allowUnborn,
+    );
+    return bridge;
+  }
+
+  /// Tear down every runner this harness spawned. The throwaway workspace's ledger stays on the cloud
+  /// (there is no open destroy lane — reclaim is law-gated); its unique name keeps it inert.
+  Future<void> dispose() async {
+    if (_disposed) return;
+    _disposed = true;
+    for (final t in _transports) {
+      await t.dispose();
+    }
+    _transports.clear();
+  }
+
+  // ── host-lane plumbing ──
+
+  Future<void> _create() async {
+    final r = await _post('/v2/workspaces/$workspace');
+    if (r.$1 >= 300 || !(r.$2['ok'] == true)) {
+      throw NomosTestHarnessException(
+          'workspace birth for $workspace refused (${r.$1}): ${_brief(r.$3)} — '
+          'a birth needs a principal (npx githolon login --agent, or pass principal:/authToken:)');
+    }
+  }
+
+  Future<(int, Map<String, Object?>, String)> _post(String path,
+      {String? body, String? contentType}) async {
+    final client = HttpClient();
+    try {
+      final req = await client.postUrl(Uri.parse('$cloud$path'));
+      if (_authToken != null) req.headers.set('x-nomos-auth', _authToken);
+      if (_principal != null) req.headers.set('x-nomos-principal', _principal);
+      if (contentType != null) {
+        req.headers.contentType = ContentType.parse('$contentType; charset=utf-8');
+      }
+      if (body != null) req.add(utf8.encode(body));
+      final res = await req.close();
+      final text = await res.transform(utf8.decoder).join();
+      Map<String, Object?> decoded = const {};
+      try {
+        final d = jsonDecode(text);
+        if (d is Map) decoded = d.cast<String, Object?>();
+      } catch (_) {}
+      return (res.statusCode, decoded, text);
+    } finally {
+      client.close();
+    }
+  }
+
+  static ({String? principal, String? authToken}) _identity(
+      String? principal, String? authToken) {
+    var p = principal;
+    var t = authToken;
+    if (p == null && t == null) {
+      final creds = _holonCreds();
+      p = creds.principal;
+      t = creds.authToken;
+    }
+    // the token's own `sub` claim is the transitional bare principal claim the birth lane requires.
+    p ??= t != null ? _jwtSub(t) : null;
+    if (p == null && t == null) {
+      throw NomosTestHarnessException(
+          'no identity for the workspace birth — run `npx githolon login --agent` '
+          '(the harness reads ~/.holon/credentials.json) or pass principal:/authToken:');
+    }
+    return (principal: p, authToken: t);
+  }
+
+  static ({String? principal, String? authToken}) _holonCreds() {
+    try {
+      final home = Platform.environment['HOME'] ??
+          Platform.environment['USERPROFILE'] ??
+          '';
+      final f = File('$home/.holon/credentials.json');
+      if (!f.existsSync()) return (principal: null, authToken: null);
+      final d = jsonDecode(f.readAsStringSync()) as Map;
+      final session = (d['session'] as Map?)?.cast<String, Object?>();
+      return (
+        principal: session?['uid']?.toString() ?? d['principal']?.toString(),
+        authToken: session?['accessToken']?.toString(),
+      );
+    } catch (_) {
+      return (principal: null, authToken: null);
+    }
+  }
+
+  static String? _jwtSub(String token) {
+    final parts = token.split('.');
+    if (parts.length != 3) return null;
+    try {
+      final d = jsonDecode(
+          utf8.decode(base64Url.decode(base64Url.normalize(parts[1])))) as Map;
+      final sub = d['sub'];
+      return sub is String && sub.isNotEmpty ? sub : null;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  static String _stripSlash(String s) =>
+      s.endsWith('/') ? s.substring(0, s.length - 1) : s;
+
+  static String _hex(int n) {
+    final rng = Random.secure();
+    return List.generate(n, (_) => rng.nextInt(16).toRadixString(16)).join();
+  }
+}

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

package/dart/test/node_runner_transport_test.dart

@@ -0,0 +1,74 @@
+// The headless transport against the REAL node runner (`cloud/web-client/runner/node-entry.mjs`):
+// protocol round-trip through NomosBridge without touching the cloud — ready handshake, typed refusal
+// on a pre-connect op, unknown-op error. The live connect path is covered by the env-gated smoke below.
+@TestOn('vm')
+library;
+
+import 'dart:io';
+
+import 'package:nomos_client/nomos_client.dart';
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+String _repoEntry() {
+  // In-repo the runner lives beside us; consumers resolve it from node_modules instead.
+  final here = Directory.current.path;
+  final p = '$here/../../cloud/web-client/runner/node-entry.mjs';
+  if (!File(p).existsSync()) {
+    throw StateError('node-entry.mjs not found at $p');
+  }
+  return p;
+}
+
+void main() {
+  late NodeRunnerTransport transport;
+  late NomosBridge bridge;
+
+  setUp(() async {
+    transport = await NodeRunnerTransport.start(entry: _repoEntry());
+    bridge = NomosBridge(transport);
+  });
+
+  tearDown(() async {
+    await transport.dispose();
+  });
+
+  test('posts the ready handshake', () async {
+    await bridge.ready.timeout(const Duration(seconds: 15));
+  });
+
+  test('a pre-connect op answers a typed bridge error', () async {
+    await bridge.ready.timeout(const Duration(seconds: 15));
+    await expectLater(
+      bridge.head(),
+      throwsA(isA<NomosBridgeError>().having((e) => e.message, 'message',
+          contains('not connected'))),
+    );
+  });
+
+  test('requests are id-correlated (two in flight)', () async {
+    await bridge.ready.timeout(const Duration(seconds: 15));
+    final a = bridge.head().then((_) => 'ok', onError: (_) => 'err');
+    final b = bridge.metrics().then((_) => 'ok', onError: (_) => 'err');
+    expect(await a, 'err');
+    expect(await b, 'err');
+  });
+
+  test(
+    'LIVE smoke: connect + query against a real workspace',
+    skip: Platform.environment['NOMOS_HEADLESS_E2E'] == null
+        ? 'set NOMOS_HEADLESS_E2E=<workspace> (and optionally NOMOS_CLOUD) to run'
+        : null,
+    () async {
+      final ws = Platform.environment['NOMOS_HEADLESS_E2E']!;
+      final cloud = Platform.environment['NOMOS_CLOUD'] ??
+          'https://nomos.captainapp.co.uk';
+      await bridge.ready.timeout(const Duration(seconds: 15));
+      await bridge.connect(
+          cloud: cloud, workspace: ws, clientId: 'headless-test');
+      final head = await bridge.head();
+      expect(head, isNotEmpty);
+    },
+    timeout: const Timeout(Duration(minutes: 3)),
+  );
+}

package/dart/test/test_harness_test.dart

@@ -0,0 +1,70 @@
+// NomosTestHarness: unit coverage for the identity/jwt plumbing, plus the LIVE ephemeral fixture loop
+// (birth a throwaway ws → deploy real law → two client replicas → write on one, converge on the other).
+// The live test needs a `githolon login --agent` session (or NOMOS_PRINCIPAL) and is opt-in via NOMOS_LIVE=1.
+@TestOn('vm')
+library;
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+String _repoEntry() =>
+    '${Directory.current.path}/../../cloud/web-client/runner/node-entry.mjs';
+
+String _guestbookDeployJson() =>
+    '${Directory.current.path}/../../examples/guestbook/build/guestbook.deploy.json';
+
+void main() {
+  test('ephemeral without any identity refuses with a named remedy', () async {
+    // isolate from a real ~/.holon by pointing HOME at an empty dir
+    // (can't re-env the current isolate — so only run when no creds file exists).
+    final home = Platform.environment['HOME'] ?? '';
+    if (File('$home/.holon/credentials.json').existsSync()) {
+      markTestSkipped('a githolon session exists — the fallback would find it');
+      return;
+    }
+    await expectLater(
+      NomosTestHarness.ephemeral(),
+      throwsA(isA<NomosTestHarnessException>()),
+    );
+  });
+
+  test(
+    'LIVE: ephemeral fixture — birth, deploy law, write on one replica, read it on another',
+    skip: Platform.environment['NOMOS_LIVE'] != '1'
+        ? 'set NOMOS_LIVE=1 (needs a githolon login --agent session)'
+        : null,
+    () async {
+      final harness = await NomosTestHarness.ephemeral(
+        deployJsonPaths: [_guestbookDeployJson()],
+        nodeEntry: _repoEntry(),
+      );
+      try {
+        final writer = await harness.connect(clientId: 'writer');
+        final reader = await harness.connect(clientId: 'reader');
+        await writer.offerDirective(
+            domain: 'guestbook',
+            directiveId: 'signGuestbook',
+            payload: {
+              'author': 'harness',
+              'message': 'ephemeral fixture green',
+              'mood': 'delighted',
+              'signedAt': DateTime.now().toUtc().toIso8601String(),
+            });
+        await writer.sync(admit: true);
+        await reader.sync(admit: false);
+        final rows = await reader.query('entriesByAuthor', {'author': 'harness'});
+        expect(rows, hasLength(1));
+        expect(
+            (rows.first['data'] as Map)['message'], 'ephemeral fixture green');
+        stdout.writeln(
+            'live harness green: ws=${harness.workspace} rows=${jsonEncode(rows.first['data'])}');
+      } finally {
+        await harness.dispose();
+      }
+    },
+    timeout: const Timeout(Duration(minutes: 5)),
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.35.0",
+  "version": "0.37.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/attested.ts

@@ -28,6 +28,8 @@ import { NomosSourceFrontier } from "./attested_core.js";
 
 export {
   trustSource,
+  trustParent,
+  PARENT_TRUST_SENTINEL,
   foreignQuery,
   isTrustSourceDecl,
   NomosSourceFrontier,

package/src/attested_core.ts

@@ -94,6 +94,27 @@ export function trustSource(workspace: string, opts: TrustSourceOptions): TrustS
   return decl;
 }
 
+/** K2's genesis sentinel — `trustParent()` declares `genesis: "@parent"`; the kernel derives
+ *  identity from the reader's OWN birth certificate (kernel mirror:
+ *  `nomos_executor::PARENT_TRUST_SENTINEL`). */
+export const PARENT_TRUST_SENTINEL = "@parent";
+
+/**
+ * DECLARE trust in the reader's PARENT (K2, stage 4 — §1.3): the accepted attestor set is
+ * DERIVED from the reader's own birth certificate (`BirthAttestation.parentKey`, seeded at
+ * birth by the parent's offer-effect) plus any delegation cert the envelope carries that the
+ * parent key signed — zero hand-pinned keys, one-hop vouching by construction. `workspace`
+ * remains the ROUTABLE name (transport must know whom to ask); identity is the derived chain,
+ * never the name. Rotation = the source serves a fresh parent-signed delegation — no reader
+ * law change ever.
+ */
+export function trustParent(
+  workspace: string,
+  opts: Omit<TrustSourceOptions, "genesis" | "keyHashes" | "roster"> = {},
+): TrustSourceDecl {
+  return trustSource(workspace, { ...opts, genesis: PARENT_TRUST_SENTINEL, roster: "derived" });
+}
+
 /** Shape predicate for compile discovery (the `isQueryDecl` pattern). */
 export function isTrustSourceDecl(v: unknown): v is TrustSourceDecl {
   return (

package/src/framework/attested_receipts.ts

@@ -0,0 +1,185 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * framework/attested_receipts.ts — ATTESTATION RECEIPTS + EQUIVOCATION ACCOUNTABILITY
+ * (attested reads slice B, stage 3 — `architecture/attested_reads_design.md` §5).
+ *
+ * The SOURCE's ledger must REMEMBER what it vouched: every attested-read signature the
+ * read-attestor emits is leaf-accumulated (`sha256hex(attested_read_signed_bytes)` — derived,
+ * never carried) and SEALED into the source's own chain as one {@link NomosAttestationReceipt}
+ * per batch — one write covers up to 1024 reads. The seal is an ORDINARY OFFER
+ * ({@link recordAttestationBatch}, authored AS the enrolled `workspace:read-attestor` through
+ * the one gate); the kernel's `attestation_ledger_violation` arm DEMANDS the receipt's
+ * `batchRoot` be the Merkle root of its carried leaves on every door, so a chain-committed
+ * receipt is always internally consistent. The adapter only SCHEDULES the seal (the debounced-
+ * admission-alarm precedent: scheduling affects WHEN, never WHAT or WHETHER).
+ *
+ * The READER's half: {@link reportSourceEquivocation} folds a {@link NomosSourceDishonor} fact
+ * from two mutually-incriminating signed envelopes (same source key, same fold_root, same
+ * (queryId, args), DIVERGENT canonical results). The kernel verifies the evidence — pure
+ * carried bytes, the xwi posture — at author, edge admission, AND verify_chain; a forged or
+ * non-contradictory report is a typed refusal (`EquivocationEvidenceInvalid`). Once folded,
+ * a trust edge declaring `onDishonor: "refuse"` refuses every LATER attestation from that
+ * `(genesis, keyHash)` — position-aware like revocation, never retroactive.
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { t } from "../fields.js";
+import { Lww } from "../drivers.js";
+import { directive } from "../directive.js";
+import { set } from "../ops.js";
+import { query } from "../query.js";
+
+/** The framework-reserved receipt instance-id prefix (kernel mirror:
+ *  `nomos_executor::ATTESTATION_RECEIPT_PREFIX`). */
+export const ATTESTATION_RECEIPT_PREFIX = "attest-receipt:";
+
+/** The receipt instance id for a batch. */
+export function attestationReceiptId(batchId: string): string {
+  return ATTESTATION_RECEIPT_PREFIX + batchId;
+}
+
+/** The framework-reserved dishonor instance-id prefix (kernel mirror:
+ *  `nomos_executor::SOURCE_DISHONOR_PREFIX`). */
+export const SOURCE_DISHONOR_PREFIX = "source-dishonor:";
+
+/** The dishonor instance id for a proven `(sourceGenesis, keyHash)`. */
+export function sourceDishonorId(sourceGenesis: string, keyHash: string): string {
+  return `${SOURCE_DISHONOR_PREFIX}${sourceGenesis}:${keyHash}`;
+}
+
+/**
+ * NomosAttestationReceipt (§5.1) — ONE sealed batch of attested-read receipt leaves in the
+ * SOURCE's own chain. Each leaf = `sha256hex(attested_read_signed_bytes)` — it commits to the
+ * FULL attestation (query, args, canonical result, head, fold_root, epoch, time) with zero
+ * extra signed bytes and NO reader identity (least-disclosure). `receiptPath` (the kernel
+ * query op) serves Merkle inclusion `{batchRoot, index, path}` from the folded `leaves`.
+ */
+export const NomosAttestationReceipt = aggregate("NomosAttestationReceipt", {
+  /** `"<epoch>-<nSealedReceiptsInFold>-<keyHash8>"` — chain-derived mint (collision-free across remounts); promised on every envelope's `receipt_hint`. */
+  batchId: t.string().merge(Lww),
+  /** sha256 Merkle root over the batch's leaf hashes (kernel-verified == root(leaves) at the gate). */
+  batchRoot: t.string().merge(Lww),
+  /** The leaf count (kernel-verified == leaves.length at the gate). */
+  leafCount: t.int().merge(Lww),
+  /** The leaf hashes, in serve order (JSON array) — what `receiptPath` serves from. */
+  leaves: t.json().merge(Lww),
+  /** The `attested_at_ms` range the batch covers. */
+  firstAt: t.int().merge(Lww),
+  lastAt: t.int().merge(Lww),
+  /** The source chain position when the batch sealed. */
+  headAtSeal: t.string().merge(Lww),
+  foldRootAtSeal: t.string().merge(Lww),
+  /** Which read-attestor key signed every member of this batch (`sha256hex(pubkey)`). */
+  signerKeyHash: t.string().merge(Lww),
+});
+
+/** Audit read: the source's sealed receipt stream, by batch id. */
+export const attestationReceiptByBatch = query("attestationReceiptByBatch")
+  .key("batchId")
+  .returns(NomosAttestationReceipt);
+
+/**
+ * `recordAttestationBatch` (§5.2) — THE SEAL. One authored intent per batch, authored AS the
+ * enrolled `workspace:read-attestor` through the NORMAL offer gate (the key is an enrolled
+ * signer precisely so it can do this — §1.2's "one key, two duties"). The payload is the
+ * kernel's own `attestationOpenBatch` snapshot, carried verbatim by the adapter; the gate
+ * re-derives the Merkle root and refuses any drift (`AttestationReceiptInvalid`) — the
+ * adapter carries, never computes. Seal triggers (leafCount ≥ 1024 / age ≥ 60s / epoch change
+ * / unmount) are the kernel's verdict on the same snapshot; a failed seal retries, never
+ * drops silently.
+ */
+export const recordAttestationBatch = directive("recordAttestationBatch")
+  .ensures(NomosAttestationReceipt)
+  .payload(
+    z.object({
+      batchId: z.string().min(1),
+      batchRoot: z.string().min(1),
+      leafCount: z.number().int().positive(),
+      leaves: z.array(z.string().min(1)).min(1),
+      firstAt: z.number().int().nonnegative(),
+      lastAt: z.number().int().nonnegative(),
+      headAtSeal: z.string(),
+      foldRootAtSeal: z.string(),
+      signerKeyHash: z.string().min(1),
+    }),
+  )
+  .plan((p) => {
+    const r = instance(NomosAttestationReceipt, attestationReceiptId(p.batchId));
+    return [
+      set(r, "batchId", p.batchId),
+      set(r, "batchRoot", p.batchRoot),
+      set(r, "leafCount", p.leafCount),
+      set(r, "leaves", JSON.stringify(p.leaves)),
+      set(r, "firstAt", p.firstAt),
+      set(r, "lastAt", p.lastAt),
+      set(r, "headAtSeal", p.headAtSeal),
+      set(r, "foldRootAtSeal", p.foldRootAtSeal),
+      set(r, "signerKeyHash", p.signerKeyHash),
+    ];
+  });
+
+/**
+ * NomosSourceDishonor (§5.3) — a PROVEN equivocation, folded in the READER's (or a
+ * governor's) chain at `source-dishonor:<sourceGenesis>:<keyHash>`. The full evidence (the
+ * two signed envelopes) rides the committed intent's payload — the fact aggregate carries
+ * the identity tuple + when it was proven. Once folded, `onDishonor: "refuse"` trust edges
+ * refuse every LATER attestation from this `(genesis, keyHash)` (position-aware).
+ */
+export const NomosSourceDishonor = aggregate("NomosSourceDishonor", {
+  /** The equivocating source chain's genesis oid (its true identity). */
+  sourceGenesis: t.string().merge(Lww),
+  /** The equivocating read-attestor key (`sha256hex(pubkey)`). */
+  keyHash: t.string().merge(Lww),
+  /** The fold-root BOTH envelopes pinned — the state the source spoke of with two tongues. */
+  foldRoot: t.string().merge(Lww),
+  /** When the reporter proved it (ms — the reporter's clock, informational). */
+  provenAtMs: t.int().merge(Lww),
+});
+
+/** Audit read: the folded dishonor facts, by source genesis. */
+export const sourceDishonorByGenesis = query("sourceDishonorByGenesis")
+  .key("sourceGenesis")
+  .returns(NomosSourceDishonor);
+
+/** One carried evidence envelope (an attested read exactly as captured — §5.3 walk 1). */
+const evidenceEnvelope = z.object({
+  queryId: z.string().min(1),
+  args: z.record(z.string(), z.string()).default({}),
+  result: z.unknown(),
+  attestation: z.record(z.string(), z.unknown()),
+});
+
+/**
+ * `reportSourceEquivocation` (§5.3) — carry TWO signed attested-read envelopes; the KERNEL
+ * gate verifies (pure carried bytes): both ed25519 signatures, same source key, same
+ * `(source_genesis, fold_root, queryId, canonical args)`, DIVERGENT canonical results — and
+ * that the folded fact's id names exactly the proven `(genesis, keyHash)`. Forged or
+ * non-contradictory evidence is `EquivocationEvidenceInvalid` on every door. The plan trusts
+ * the payload's identity mirrors ONLY because the gate re-derives them from the evidence.
+ */
+export const reportSourceEquivocation = directive("reportSourceEquivocation")
+  .ensures(NomosSourceDishonor)
+  .payload(
+    z.object({
+      a: evidenceEnvelope,
+      b: evidenceEnvelope,
+      /** Mirror of the proven identity (kernel-checked against the verified evidence). */
+      sourceGenesis: z.string().min(1),
+      keyHash: z.string().min(1),
+      foldRoot: z.string().min(1),
+      provenAtMs: z.number().int().nonnegative(),
+    }),
+  )
+  .plan((p) => {
+    const d = instance(NomosSourceDishonor, sourceDishonorId(p.sourceGenesis, p.keyHash));
+    return [
+      set(d, "sourceGenesis", p.sourceGenesis),
+      set(d, "keyHash", p.keyHash),
+      set(d, "foldRoot", p.foldRoot),
+      set(d, "provenAtMs", p.provenAtMs),
+    ];
+  });

package/src/framework/source_roster.ts

@@ -0,0 +1,96 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * framework/source_roster.ts — K3 TRACKED ROSTERS (attested reads slice B, stage 5 —
+ * `architecture/attested_reads_design.md` §1.5).
+ *
+ * The reader's chain maintains a {@link NomosSourceRoster} per trusted source: a reader-side
+ * mirror of the SOURCE's own read-attestor signer roster, delivered as ATTESTED READS of the
+ * source's signer chain itself (the kernel-native `attestorRoster` query — the roster rides
+ * the SAME attested-read machinery as any foreign premise). `roster: "tracked"` on the trust
+ * edge activates the folded roster inside `accepted_keys`; rotation then needs ZERO reader
+ * law deploys, and a source-side revocation propagates on the reader's next sync.
+ *
+ * THE GROUNDED RECURSION (§1.5.2): a roster read's envelope is verified against the accepted
+ * set AS ALREADY FOLDED in the reader's prefix — the FIRST sync therefore verifies against
+ * the bootstrap trust (the K1 pins or the K2 birth-cert-derived key), which exists by
+ * construction before any roster does; every later sync verifies against the roster its own
+ * prefix folded. Deterministic at replay: the roster is reader-chain state.
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { t } from "../fields.js";
+import { Lww } from "../drivers.js";
+import { directive, type Directive } from "../directive.js";
+import { set } from "../ops.js";
+import { read } from "../read.js";
+import { foreignQuery } from "../attested_core.js";
+
+/** The framework-reserved roster instance-id prefix (kernel mirror:
+ *  `nomos_executor::SOURCE_ROSTER_PREFIX`). */
+export const SOURCE_ROSTER_PREFIX = "source-roster:";
+
+/** The roster instance id for a source genesis. */
+export function sourceRosterId(sourceGenesis: string): string {
+  return SOURCE_ROSTER_PREFIX + sourceGenesis;
+}
+
+/** The kernel-native source-side roster query id (`nomos_executor::ATTESTOR_ROSTER_QUERY`). */
+export const ATTESTOR_ROSTER_QUERY_ID = "attestorRoster";
+
+/**
+ * NomosSourceRoster (§1.5) — the reader's folded mirror of one source's read-attestor
+ * roster, keyed by the source's TRUE identity (`source-roster:<genesis>`). `rosterJson` is
+ * the `keyHash → leaf` map exactly as the source's signer chain folds it (a key is ACCEPTED
+ * iff its leaf's `status == "active"` — the position-aware revocation mirror); the kernel's
+ * `accepted_keys` reads THIS under `roster: "tracked"`.
+ */
+export const NomosSourceRoster = aggregate("NomosSourceRoster", {
+  /** The routable source name the edge was declared under (diagnostics). */
+  source: t.string().merge(Lww),
+  /** The `keyHash → enrollment leaf` map, JSON — as attested by the source's own chain. */
+  rosterJson: t.json().merge(Lww),
+  /** The source's `SignerEpoch` at the attested sync. */
+  currentEpoch: t.int().merge(Lww),
+});
+
+/** One roster row as the source's `attestorRoster` query answers it. */
+interface AttestorRosterRow {
+  id: string;
+  data: {
+    genesis: string;
+    currentEpoch: number;
+    keys: Record<string, unknown>;
+  };
+}
+
+/**
+ * BUILD the reader-side `syncSourceRoster` framework directive for ONE tracked source
+ * (§1.5.1) — export the result from the law that declares `trustSource(sourceWs, { roster:
+ * "tracked", … })`. Its plan performs `read(attestorRoster, {}, { from: sourceWs })` (an
+ * ordinary attested read — verified by the five-step arm against the accepted set the reader's
+ * PREFIX already folds: pins/birth-cert first, then the roster itself) and folds the answer
+ * into {@link NomosSourceRoster}. One directive per tracked source per law (the id embeds
+ * nothing — a law tracking several sources exports several via distinct ids).
+ */
+export function sourceRosterSync(sourceWs: string, directiveId = "syncSourceRoster"): Directive<Record<string, never>> {
+  const rosterQuery = foreignQuery(ATTESTOR_ROSTER_QUERY_ID);
+  return directive(directiveId)
+    .ensures(NomosSourceRoster)
+    .payload(z.object({}).strict())
+    .plan(() => {
+      const rows = read<AttestorRosterRow[]>(rosterQuery, {}, { from: sourceWs });
+      if (rows.length === 0) throw new Error("attestor-roster-empty");
+      const d = rows[0]!.data;
+      const r = instance(NomosSourceRoster, sourceRosterId(d.genesis));
+      return [
+        set(r, "source", sourceWs),
+        set(r, "rosterJson", JSON.stringify(d.keys ?? {})),
+        set(r, "currentEpoch", d.currentEpoch ?? 0),
+      ];
+    })
+    .readsFrom(sourceWs, rosterQuery) as Directive<Record<string, never>>;
+}

package/src/index.ts

@@ -124,6 +124,8 @@ export { read } from "./read.js";
 // surface (`trustSource`), the foreign query reference, and the reader-side SourceFrontier.
 export {
   trustSource,
+  trustParent,
+  PARENT_TRUST_SENTINEL,
   foreignQuery,
   NomosSourceFrontier,
   sourceFrontierId,
@@ -133,6 +135,31 @@ export {
   type TrustSourceOptions,
   type ForeignQueryRef,
 } from "./attested.js";
+// ATTESTATION RECEIPTS + EQUIVOCATION ACCOUNTABILITY (slice B stage 3 — §5): the source-side
+// sealed receipt batch + the reader-side proven-dishonor fact, both ordinary law the kernel's
+// `attestation_ledger_violation` arm guards on every door.
+export {
+  NomosAttestationReceipt,
+  recordAttestationBatch,
+  attestationReceiptByBatch,
+  attestationReceiptId,
+  ATTESTATION_RECEIPT_PREFIX,
+  NomosSourceDishonor,
+  reportSourceEquivocation,
+  sourceDishonorByGenesis,
+  sourceDishonorId,
+  SOURCE_DISHONOR_PREFIX,
+} from "./framework/attested_receipts.js";
+// K3 TRACKED ROSTERS (slice B stage 5 — §1.5): the reader-side folded source roster + the
+// per-source sync directive factory (roster updates ride the attested-read machinery itself,
+// grounded on the pins/birth-cert bootstrap).
+export {
+  NomosSourceRoster,
+  sourceRosterSync,
+  sourceRosterId,
+  SOURCE_ROSTER_PREFIX,
+  ATTESTOR_ROSTER_QUERY_ID,
+} from "./framework/source_roster.js";
 // THE BIRTH EFFECT (G3 — birth is a declared kernel primitive): a `.births()` directive's plan records the
 // child's genesis recipe via `birth(recipe)` (reuse `buildGenesisChain`); it rides the committed intent as a
 // declared output, and the kernel — reading the `.births` declaration off the law manifest (the