@githolon/dsl 0.9.0 → 0.11.0

package/dart/example/nomos_webview_transport.dart

@@ -0,0 +1,63 @@
+// COPY THIS INTO YOUR FLUTTER APP. It is an EXAMPLE, not part of the `nomos_dsl` library: it depends on
+// `webview_flutter`, which the pure-Dart `nomos_dsl` package deliberately does NOT depend on (so the bridge
+// protocol logic stays Flutter-free and unit-testable). This ~50-line transport is the only app-specific glue.
+//
+// It implements `BridgeTransport` (from `package:nomos_dsl/nomos_dsl.dart`) over a `webview_flutter`
+// WebViewController loading the published `nomos-runner` bundle:
+//   • host → runner: `controller.runJavaScript("window.__nomosSend(<json>)")`
+//   • runner → host: a `JavaScriptChannel("NomosHost")` whose onMessage feeds the bridge's message stream.
+//
+// WIRING (in your widget's initState):
+//   final controller = WebViewController()
+//     ..setJavaScriptMode(JavaScriptMode.unrestricted);
+//   final transport = WebViewTransport(controller);          // registers the NomosHost channel
+//   await controller.loadFlutterAsset('assets/nomos/nomos-runner.html');
+//   final bridge = NomosBridge(transport);
+//   await bridge.ready;                                       // resolves on the runner's {event:ready}
+//   await bridge.connect(cloud: 'https://nomos.captainapp.co.uk', workspace: myWs, clientId: deviceId);
+//   final head = await bridge.dispatch(domain: 'guestbook', directiveId: 'signGuestbook',
+//       payload: {'author': 'ada', 'message': 'hi', 'mood': 'delighted'}, domainHash: GUESTBOOK_DOMAIN_HASH);
+//   final rows = await bridge.query('entriesByAuthor', {'author': 'ada'});
+//
+// (Put the runner bundle at `assets/nomos/nomos-runner.{html,js}` and declare it under `flutter: assets:`.)
+
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:nomos_dsl/nomos_dsl.dart';
+import 'package:webview_flutter/webview_flutter.dart';
+
+/// A [BridgeTransport] over a `webview_flutter` controller hosting the `nomos-runner` bundle.
+class WebViewTransport implements BridgeTransport {
+  final WebViewController controller;
+  final _incoming = StreamController<Map<String, Object?>>.broadcast();
+
+  WebViewTransport(this.controller) {
+    // runner → host: the bundle posts JSON strings on the "NomosHost" channel.
+    controller.addJavaScriptChannel(
+      'NomosHost',
+      onMessageReceived: (JavaScriptMessage m) {
+        try {
+          final decoded = jsonDecode(m.message);
+          if (decoded is Map) _incoming.add(decoded.cast<String, Object?>());
+        } catch (_) {/* a non-JSON console line — ignore */}
+      },
+    );
+  }
+
+  @override
+  Stream<Map<String, Object?>> get messages => _incoming.stream;
+
+  @override
+  void send(Map<String, Object?> message) {
+    // host → runner: hand the JSON to the bundle. Double-encode so it survives as a JS string literal.
+    final json = jsonEncode(message);
+    controller.runJavaScript('window.__nomosSend(${jsonEncode(json)})');
+  }
+
+  /// Call once, right after the page finishes loading (e.g. from `NavigationDelegate.onPageFinished`), so the
+  /// runner flushes any message (the initial `{event:"ready"}`) it emitted before this channel was wired.
+  void flushReady() => controller.runJavaScript('window.__nomosReady && window.__nomosReady()');
+
+  void dispose() => _incoming.close();
+}

package/dart/lib/nomos_dsl.dart

@@ -28,6 +28,9 @@ export 'src/driver.dart';
 export 'src/dispatch.dart';
 export 'src/subscriptions.dart';
 export 'src/schema_validation.dart';
+// THE WEBVIEW BRIDGE (app-binding boundary) — the async Dart runtime that drives the REAL githolon running
+// in a WebView, so the generated typed client never needs a `MemoryPersistence` fake.
+export 'src/webview_bridge.dart';
 // The PROVIDER boundary (server-side capability-provider SDK runtime: TaskOutcome /
 // TaskSuccess / TaskFailure / TaskResult / TaskProvider / HostClock). The symmetric twin
 // of `dispatch.dart`; the generated per-task provider classes build on it.

package/dart/lib/src/webview_bridge.dart

@@ -0,0 +1,161 @@
+// 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.
+
+/// THE WEBVIEW BRIDGE — the Dart half of the app-binding boundary. A Flutter app talks to the REAL githolon
+/// (the `@githolon/client` runner running in a WebView on mobile / the same page on Flutter web) over ONE
+/// stable message protocol, so the generated typed Dart client drives the real kernel — never a
+/// `MemoryPersistence` pretending to be a GitHolon.
+///
+/// A WebView round-trip is ASYNC, so the bridge is async (unlike the sync FRB `Authorer` in `dispatch.dart`).
+/// The generated per-domain Dart client wraps a [NomosBridge]; the bridge owns request/reply correlation +
+/// reactive `watch` streams. The platform TRANSPORT ([BridgeTransport]) is injected — `dart:js_util` on web,
+/// a WebView JS-channel on mobile — so this protocol logic is pure Dart + fully unit-testable.
+library;
+
+import 'dart:async';
+
+/// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
+const int kWebviewBridgeVersion = 1;
+
+/// 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.
+abstract interface class BridgeTransport {
+  void send(Map<String, Object?> message);
+  Stream<Map<String, Object?>> get messages;
+}
+
+/// A typed refusal surfaced from the githolon's gate (a law refusal, a drift, a malformed op). Carries the
+/// human-first message verbatim — the generated client lets it throw, loudly, exactly like the TS client.
+class NomosBridgeError implements Exception {
+  final String message;
+  NomosBridgeError(this.message);
+  @override
+  String toString() => 'NomosBridgeError: $message';
+}
+
+/// THE BRIDGE. Construct over a [BridgeTransport], `await ready`, then `connect(...)` and drive the holon.
+class NomosBridge {
+  final BridgeTransport _transport;
+  final Map<int, Completer<Object?>> _pending = {};
+  final Map<String, StreamController<List<dynamic>>> _watches = {};
+  final Completer<void> _ready = Completer<void>();
+  int _seq = 0;
+  late final StreamSubscription<Map<String, Object?>> _sub;
+
+  NomosBridge(this._transport) {
+    _sub = _transport.messages.listen(_onMessage);
+  }
+
+  /// Completes once the runner has posted `{ event: "ready" }` (the wasm + client are booted).
+  Future<void> get ready => _ready.future;
+
+  void _onMessage(Map<String, Object?> m) {
+    if (m['v'] != kWebviewBridgeVersion) return; // a foreign-version message is ignored (forward-compatible)
+    final event = m['event'];
+    if (event == 'ready') {
+      if (!_ready.isCompleted) _ready.complete();
+      return;
+    }
+    if (event == 'watch') {
+      final ctrl = _watches[m['subId']];
+      if (ctrl != null && !ctrl.isClosed) ctrl.add((m['rows'] as List?) ?? const []);
+      return;
+    }
+    final id = m['id'];
+    if (id is! int) return;
+    final completer = _pending.remove(id);
+    if (completer == null) return;
+    if (m['ok'] == true) {
+      completer.complete(m['result']);
+    } else {
+      completer.completeError(NomosBridgeError((m['error'] ?? 'the githolon refused the request').toString()));
+    }
+  }
+
+  /// Send one request and await the typed reply (the runner answers ok/error). The ONLY low-level call —
+  /// every typed method below is a thin wrapper, so the request/reply contract lives in exactly one place.
+  Future<Object?> _call(String op, [Map<String, Object?> args = const {}]) {
+    final id = ++_seq;
+    final completer = Completer<Object?>();
+    _pending[id] = completer;
+    _transport.send({'v': kWebviewBridgeVersion, 'id': id, 'op': op, 'args': args});
+    return completer.future;
+  }
+
+  Map<String, Object?> _asMap(Object? v) => (v as Map?)?.cast<String, Object?>() ?? const {};
+  List<Map<String, dynamic>> _asRows(Object? v) =>
+      ((_asMap(v)['rows'] as List?) ?? const []).map((e) => (e as Map).cast<String, dynamic>()).toList();
+
+  // ── the runtime-aware surface (the boundary the generated Dart client wraps) ──
+
+  /// Open the user/estate workspace: pull its ledger, boot the local holon under the installed law.
+  Future<void> connect({required String cloud, required String workspace, String? clientId, String? authToken, String? restoreFrom}) async {
+    await _call('connect', {'cloud': cloud, 'workspace': workspace, if (clientId != null) 'clientId': clientId, if (authToken != null) 'authToken': authToken, if (restoreFrom != null) 'restoreFrom': restoreFrom});
+  }
+
+  /// LOCAL-FIRST write: author `directiveId` under `domainHash`. Returns the new local head; durable on [sync].
+  Future<String> dispatch({required String domain, required String directiveId, required Map<String, Object?> payload, required String domainHash}) async {
+    final r = _asMap(await _call('dispatch', {'domain': domain, 'directiveId': directiveId, 'payload': payload, 'domainHash': domainHash}));
+    return r['head'].toString();
+  }
+
+  /// §5 cross-custody delivery: a `recordShare` carrying a pre-signed §3 quote into a home holon.
+  Future<String> deliverShare({required Map<String, Object?> quote, required String domainHash}) async {
+    final r = _asMap(await _call('deliverShare', {'quote': quote, 'domainHash': domainHash}));
+    return r['head'].toString();
+  }
+
+  /// A declared query's rows from the local projection.
+  Future<List<Map<String, dynamic>>> query(String queryId, [Map<String, Object?> params = const {}]) async =>
+      _asRows(await _call('query', {'queryId': queryId, 'params': params}));
+
+  /// A single aggregate by id (the by-id read).
+  Future<List<Map<String, dynamic>>> queryById(String id) async => _asRows(await _call('queryById', {'id': id}));
+
+  /// A maintained O(1) count / sum.
+  Future<int> count(String countId, [String group = '']) async => ((_asMap(await _call('count', {'countId': countId, 'group': group}))['count']) as num).toInt();
+  Future<int> sum(String sumId, [String group = '']) async => ((_asMap(await _call('sum', {'sumId': sumId, 'group': group}))['sum']) as num).toInt();
+
+  /// Push local writes → the session branch → cloud admission, and pull canonical main back.
+  Future<Map<String, Object?>> sync({bool admit = true}) async => _asMap(await _call('sync', {'admit': admit}));
+
+  /// Diagnostics — is the expected law installed/active/drift-free here? (The generated client surfaces it
+  /// so the app can answer "can I author this directive, and if not what deploy fixes it".)
+  Future<Map<String, Object?>> lawStatus(String hash) async => _asMap(await _call('lawStatus', {'hash': hash}));
+
+  /// Reactive local read: a stream of row-sets that re-emits on every local change. Cancelling the
+  /// subscription tells the runner to drop the watch.
+  Stream<List<dynamic>> watch(String queryId, [Map<String, Object?> params = const {}]) =>
+      _watchStream(kind: 'query', queryId: queryId, params: params);
+  Stream<List<dynamic>> watchById(String id) => _watchStream(kind: 'byId', id: id);
+
+  Stream<List<dynamic>> _watchStream({required String kind, String? queryId, Map<String, Object?>? params, String? id}) {
+    final subId = 'w${++_seq}';
+    late final StreamController<List<dynamic>> ctrl;
+    ctrl = StreamController<List<dynamic>>(
+      onListen: () => _call('watch', {'subId': subId, 'kind': kind, if (queryId != null) 'queryId': queryId, if (params != null) 'params': params, if (id != null) 'id': id}),
+      onCancel: () async {
+        _watches.remove(subId);
+        try { await _call('unwatch', {'subId': subId}); } catch (_) {}
+      },
+    );
+    _watches[subId] = ctrl;
+    return ctrl.stream;
+  }
+
+  /// Tear down: stop the transport subscription + fail any in-flight calls.
+  Future<void> dispose() async {
+    await _sub.cancel();
+    for (final c in _pending.values) {
+      if (!c.isCompleted) c.completeError(NomosBridgeError('bridge disposed'));
+    }
+    _pending.clear();
+    for (final w in _watches.values) {
+      if (!w.isClosed) await w.close();
+    }
+    _watches.clear();
+  }
+}

package/dart/test/webview_bridge_test.dart

@@ -0,0 +1,225 @@
+// NOMOS — the WEBVIEW BRIDGE protocol test (the Dart half of the app-binding boundary). A FAKE transport
+// stands in for the WebView runner (`webview-runner.mjs`): it auto-answers each request from a stub holon,
+// exactly as the real runner would, so the bridge's request/reply correlation, reactive `watch` streams, and
+// error framing are proven in pure Dart — no browser, no MemoryPersistence. The bridge and the JS runner are
+// the two ends of ONE protocol (`kWebviewBridgeVersion`).
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:nomos_dsl/nomos_dsl.dart';
+import 'package:test/test.dart';
+
+/// A fake runner-over-a-transport: records sent requests, replies the way `webview-runner.mjs` does, and can
+/// push reactive `watch` events. Lets us drive [NomosBridge] without a real WebView.
+class FakeRunner implements BridgeTransport {
+  final _incoming = StreamController<Map<String, Object?>>.broadcast();
+  final List<Map<String, Object?>> sent = [];
+  String? lastWatchSubId;
+
+  FakeRunner() {
+    // the runner announces readiness at construction.
+    scheduleMicrotask(() => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+  }
+
+  @override
+  Stream<Map<String, Object?>> get messages => _incoming.stream;
+
+  @override
+  void send(Map<String, Object?> message) {
+    sent.add(message);
+    final id = message['id'] as int;
+    final op = message['op'] as String;
+    final args = (message['args'] as Map).cast<String, Object?>();
+    // reply exactly as the runner's ops do (the contract both ends share).
+    Map<String, Object?> reply(Object? result) => {'v': kWebviewBridgeVersion, 'id': id, 'ok': true, 'result': result};
+    scheduleMicrotask(() {
+      switch (op) {
+        case 'connect': _incoming.add(reply({'workspace': args['workspace']})); break;
+        case 'dispatch':
+          // a directive the law refuses answers ok:false (the runner frames the gate's verdict).
+          if (args['directiveId'] == 'refuseMe') {
+            _incoming.add({'v': kWebviewBridgeVersion, 'id': id, 'ok': false, 'error': 'the law refused this intent'});
+          } else {
+            _incoming.add(reply({'head': 'HEAD-${args['directiveId']}'}));
+          }
+          break;
+        case 'deliverShare': _incoming.add(reply({'head': 'HEAD-share'})); break;
+        case 'query': _incoming.add(reply({'rows': [{'id': 'a', 'data': {'q': args['queryId']}}]})); break;
+        case 'queryById': _incoming.add(reply({'rows': [{'id': args['id'], 'data': {'ok': true}}]})); break;
+        case 'count': _incoming.add(reply({'count': 7})); break;
+        case 'sync': _incoming.add(reply({'pushed': true})); break;
+        case 'lawStatus': _incoming.add(reply({'installed': true, 'drifted': false})); break;
+        case 'badop': _incoming.add({'v': kWebviewBridgeVersion, 'id': id, 'ok': false, 'error': 'the law refused this intent'}); break;
+        case 'watch': lastWatchSubId = args['subId'] as String; _incoming.add(reply({'subId': args['subId']})); break;
+        case 'unwatch': _incoming.add(reply({'subId': args['subId']})); break;
+        default: _incoming.add({'v': kWebviewBridgeVersion, 'id': id, 'ok': false, 'error': "unknown op '$op'"});
+      }
+    });
+  }
+
+  /// Simulate the holon firing a reactive change to an active watch.
+  void pushWatch(String subId, List<dynamic> rows) => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'watch', 'subId': subId, 'rows': rows});
+}
+
+/// A transport that answers EVERY request with one canned `result` (the golden corpus's reply) and records
+/// the request the bridge sent — so we can assert both halves of the wire contract from the Dart side.
+class ReplayTransport implements BridgeTransport {
+  final Map<String, Object?> result;
+  final _incoming = StreamController<Map<String, Object?>>.broadcast();
+  Map<String, Object?>? lastRequest;
+  ReplayTransport(this.result) {
+    scheduleMicrotask(() => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+  }
+  @override
+  Stream<Map<String, Object?>> get messages => _incoming.stream;
+  @override
+  void send(Map<String, Object?> message) {
+    lastRequest = message;
+    final id = message['id'];
+    scheduleMicrotask(() => _incoming.add({'v': kWebviewBridgeVersion, 'id': id, 'ok': true, 'result': result}));
+  }
+}
+
+/// Load the shared golden corpus (the same file the JS runner test replays). Probed across the candidate
+/// working dirs `dart test` may run from, so it doesn't depend on one invocation cwd.
+Map<String, Object?> _loadCorpus() {
+  const candidates = [
+    '../../cloud/web-client/test/fixtures/bridge-protocol.golden.json', // cwd = dsl/dart (the usual)
+    'cloud/web-client/test/fixtures/bridge-protocol.golden.json', // cwd = repo root
+    '../../../cloud/web-client/test/fixtures/bridge-protocol.golden.json',
+  ];
+  for (final p in candidates) {
+    final f = File(p);
+    if (f.existsSync()) return (jsonDecode(f.readAsStringSync()) as Map).cast<String, Object?>();
+  }
+  fail('golden corpus not found from ${Directory.current.path}; tried $candidates');
+}
+
+/// Drive one corpus op through the typed bridge method and return its typed result (so we can compare it to
+/// what the corpus says the unwrapped value should be).
+Future<Object?> _invoke(NomosBridge b, String op, Map<String, Object?> a) async {
+  switch (op) {
+    case 'connect':
+      await b.connect(cloud: a['cloud'] as String, workspace: a['workspace'] as String, clientId: a['clientId'] as String?);
+      return null;
+    case 'dispatch':
+      return b.dispatch(domain: a['domain'] as String, directiveId: a['directiveId'] as String, payload: (a['payload'] as Map).cast<String, Object?>(), domainHash: a['domainHash'] as String);
+    case 'deliverShare':
+      return b.deliverShare(quote: (a['quote'] as Map).cast<String, Object?>(), domainHash: a['domainHash'] as String);
+    case 'query':
+      return b.query(a['queryId'] as String, (a['params'] as Map).cast<String, Object?>());
+    case 'queryById':
+      return b.queryById(a['id'] as String);
+    case 'count':
+      return b.count(a['countId'] as String, a['group'] as String);
+    case 'sum':
+      return b.sum(a['sumId'] as String, a['group'] as String);
+    case 'sync':
+      return b.sync(admit: a['admit'] as bool);
+    case 'lawStatus':
+      return b.lawStatus(a['hash'] as String);
+    default:
+      fail('corpus op not wired into the Dart bridge: $op');
+  }
+}
+
+/// What the corpus says the typed (unwrapped) return value should be, given the reply's `result`.
+Object? _expectedTyped(String op, Map<String, Object?> result) {
+  switch (op) {
+    case 'dispatch':
+    case 'deliverShare':
+      return result['head'];
+    case 'query':
+    case 'queryById':
+      return result['rows'];
+    case 'count':
+      return result['count'];
+    case 'sum':
+      return result['sum'];
+    case 'sync':
+    case 'lawStatus':
+      return result;
+    default:
+      return null; // connect: void
+  }
+}
+
+void main() {
+  // ── THE GOLDEN CORPUS — the cross-language conformance the JS runner replays too ──
+  // For each case: call the typed bridge method with the corpus `args`, then assert (1) the request the bridge
+  // SENT carries exactly those args, and (2) the typed value the bridge parsed from the corpus `result` matches.
+  // The JS runner asserts the SAME corpus from the other side — so neither end can drift the wire alone.
+  group('golden corpus (shared with the JS runner)', () {
+    final corpus = _loadCorpus();
+    final cases = (corpus['cases'] as List).cast<Map<String, Object?>>();
+    test('version pins the bridge version', () => expect(corpus['version'], kWebviewBridgeVersion));
+    for (final c in cases) {
+      final op = c['op'] as String;
+      final args = (c['args'] as Map).cast<String, Object?>();
+      final result = (c['result'] as Map).cast<String, Object?>();
+      test("'$op' request args + parsed result match the corpus", () async {
+        final transport = ReplayTransport(result);
+        final bridge = NomosBridge(transport);
+        await bridge.ready;
+        final typed = await _invoke(bridge, op, args);
+        expect((transport.lastRequest!['args'] as Map).cast<String, Object?>(), equals(args), reason: 'sent request args');
+        if (op != 'connect') expect(typed, equals(_expectedTyped(op, result)), reason: 'parsed typed result');
+        await bridge.dispose();
+      });
+    }
+  });
+
+  late FakeRunner runner;
+  late NomosBridge bridge;
+  setUp(() { runner = FakeRunner(); bridge = NomosBridge(runner); });
+  tearDown(() => bridge.dispose());
+
+  test('ready completes once the runner boots', () async {
+    await bridge.ready.timeout(const Duration(seconds: 1));
+  });
+
+  test('dispatch round-trips a typed head; args reach the runner verbatim', () async {
+    await bridge.ready;
+    final head = await bridge.dispatch(domain: 'guestbook', directiveId: 'signGuestbook', payload: {'author': 'ada'}, domainHash: 'abc');
+    expect(head, 'HEAD-signGuestbook');
+    final req = runner.sent.firstWhere((m) => m['op'] == 'dispatch');
+    expect((req['args'] as Map)['payload'], {'author': 'ada'});
+    expect((req['args'] as Map)['domainHash'], 'abc');
+  });
+
+  test('connect / deliverShare / query / queryById / count / sync / lawStatus all wrap the runner', () async {
+    await bridge.ready;
+    await bridge.connect(cloud: 'https://c', workspace: 'ws', clientId: 'c1');
+    expect(await bridge.deliverShare(quote: {'publicKey': 'k'}, domainHash: 'h'), 'HEAD-share');
+    expect((await bridge.query('byAuthor', {'author': 'ada'})).first['data'], {'q': 'byAuthor'});
+    expect((await bridge.queryById('Entry_1')).first['id'], 'Entry_1');
+    expect(await bridge.count('entries'), 7);
+    expect(await bridge.sync(), {'pushed': true});
+    expect(await bridge.lawStatus('abc'), {'installed': true, 'drifted': false});
+  });
+
+  test('watch is a reactive stream; a runner push reaches the listener; cancel unwatches', () async {
+    await bridge.ready;
+    final got = <List<dynamic>>[];
+    final sub = bridge.watch('byAuthor', {'author': 'ada'}).listen(got.add);
+    await Future<void>.delayed(Duration.zero); // let the watch register
+    runner.pushWatch(runner.lastWatchSubId!, [{'id': 'a', 'data': {'n': 2}}]);
+    await Future<void>.delayed(Duration.zero);
+    expect(got, [[{'id': 'a', 'data': {'n': 2}}]]);
+    await sub.cancel();
+    expect(runner.sent.any((m) => m['op'] == 'unwatch'), isTrue);
+  });
+
+  test('a law refusal throws NomosBridgeError with the verbatim message', () async {
+    await bridge.ready;
+    Object? err;
+    try {
+      await bridge.dispatch(domain: 'x', directiveId: 'refuseMe', payload: {}, domainHash: 'h');
+    } on NomosBridgeError catch (e) {
+      err = e;
+    }
+    expect(err, isA<NomosBridgeError>());
+    expect((err as NomosBridgeError).message, contains('law refused'));
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.9.0",
+  "version": "0.11.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/framework/home.ts

@@ -32,8 +32,14 @@ import { directive } from "../directive.js";
 import { create } from "../authoring.js";
 import { set, type PlannedOp } from "../ops.js";
 import { query } from "../query.js";
+import { workspaceInvariant, refAs } from "./workspace_invariant.js";
 import { identityRelations } from "./signing_identity.js";
 
+// `nomos.sha256` — the TRUSTLESS, pure hash computed IN the githolon (Rust sha2 bound in the sealed engine;
+// see deterministic-rquickjs). Available as a global to plans + invariant predicates (like `nomos.mint`); it
+// lets the home law re-derive `home-<hash(owner)>` itself, so the SQUAT invariant runs in-law on every peer.
+declare const nomos: { sha256(input: string): string };
+
 /** The KEY DIRECTORY is the `signer` relation — re-exported so a home holon's law composes it (the
  *  identity's public device keys, enrolled via `enrollSigner`, checked by the gate). */
 export { identityRelations };
@@ -47,30 +53,58 @@ export { identityRelations };
  * `seedHomeOwner`, kept off the open session lane), so a tenant cannot forge ownership.
  */
 export const HOME_OWNER_ID = "home-owner:self";
+/** A home holon's SELF-COMMITTED NAME prefix — `home-<sha256(subject)>` (the client's `homeNameOf` + the
+ *  squat invariant both derive it). The home's chain commits to its own routing name, so the bailiff can
+ *  bind the name to the CONTENT (custody) while the LAW guarantees the name hashes its owner. */
+export const HOME_NAME_PREFIX = "home-";
+export const HOME_NAME_HASH_LEN = 40;
 export const HomeOwner = aggregate("HomeOwner", {
   /** The identity this home belongs to — the canonical `user:<uid>` subject the §3 gate binds quotes to. */
   principal: t.string().merge(Lww),
+  /** THE HOME'S SELF-COMMITTED NAME (`home-<sha256(principal)>`) — the squat invariant asserts it hashes the
+   *  owner, so the chain's claimed name can ONLY be its rightful owner's slot (home_holons §5). */
+  homeName: t.string().merge(Lww),
   /** ISO-8601, caller-stamped (determinism — no clock in the plan). */
   bornAt: t.string().merge(Lww),
 });
 
-/** The framework PRIMITIVE plan: stamp the home's owner (singleton at the fixed id the gate reads). */
-export function writeHomeOwner(p: { principal: string; bornAt: string }): PlannedOp[] {
+/** The framework PRIMITIVE plan: stamp the home's owner + its self-committed name (singleton at the fixed id). */
+export function writeHomeOwner(p: { principal: string; homeName: string; bornAt: string }): PlannedOp[] {
   const h = instance(HomeOwner, HOME_OWNER_ID);
-  return [set(h, "principal", p.principal), set(h, "bornAt", p.bornAt)];
+  return [set(h, "principal", p.principal), set(h, "homeName", p.homeName), set(h, "bornAt", p.bornAt)];
 }
 
 /**
- * `seedHomeOwner` — the birth-door directive that stamps the home's owner at the fixed singleton id. A
- * CONTROL-PLANE write: the host authors it once at lazy birth (after resolving who the home is for); the
- * open session lane structurally REFUSES it (by directive id, like the §6 handoff seals), so a tenant
- * cannot overwrite ownership. `.ensures` (a deterministic-keyed singleton, not a minted record).
+ * `seedHomeOwner` — the birth-door directive that stamps the home's owner + its self-committed `homeName` at
+ * the fixed singleton id. A CONTROL-PLANE write: the host authors it once at lazy birth; the open session
+ * lane structurally REFUSES it (by directive id). `.ensures` (a deterministic-keyed singleton). The `homeName`
+ * is caller-supplied but the {@link homeNameBindsOwner} invariant proves it `== home-<sha256(principal)>`,
+ * so a squatter cannot claim a name slot that doesn't hash to ITS own owner.
  */
 export const seedHomeOwner = directive("seedHomeOwner")
   .ensures(HomeOwner)
-  .payload(z.object({ principal: z.string().min(1), bornAt: z.string().min(1) }))
+  .payload(z.object({ principal: z.string().min(1), homeName: z.string().min(1), bornAt: z.string().min(1) }))
   .plan((p) => writeHomeOwner(p));
 
+/**
+ * THE SQUAT INVARIANT (home_holons §5) — a home holon's self-committed `homeName` MUST be the hash of its
+ * owner: `homeName == home-<sha256(principal)>`. Declared by the home law, it EXECUTES at the one gate — and
+ * crucially at `verify_chain` (the bailiff's upload-birth): a squatter's chain (claiming `home-<hash(bob)>`
+ * but owned by `mallory`) FAILS the home law's OWN gate during adoption — refused IN THE GITHOLON, BY THE LAW,
+ * never by a host check. The host only routes the chain to the name it commits to (custody). `nomos.sha256`
+ * re-derives the hash in-law on every peer, so the verdict is identical everywhere.
+ */
+export const homeNameBindsOwner = workspaceInvariant("HomeNameBindsOwner")
+  .on("seedHomeOwner")
+  .reads(() => [refAs("owner", "HomeOwner", HOME_OWNER_ID)])
+  .assert(({ owner }) => {
+    const o = (owner ?? {}) as { principal?: string; homeName?: string };
+    const expected = HOME_NAME_PREFIX + nomos.sha256(String(o.principal ?? "")).slice(0, HOME_NAME_HASH_LEN);
+    return o.homeName === expected
+      ? { accept: true }
+      : { reject: "a home's name must hash its owner (home-<sha256(principal)>) — refusing a squatted home" };
+  });
+
 /**
  * THE SHARED-WITH-ME INDEX (§5) — one record per cross-custody attestation delivered to this home holon:
  * a signed edge `<asserterWorkspace> : <object> # <relation> @ this-identity`, indexed LOCALLY so the

package/src/index.ts

@@ -243,8 +243,11 @@ export {
   sharedByWorkspace,
   HomeOwner,
   HOME_OWNER_ID,
+  HOME_NAME_PREFIX,
+  HOME_NAME_HASH_LEN,
   seedHomeOwner,
   writeHomeOwner,
+  homeNameBindsOwner,
 } from "./framework/home.js";
 // THE GENESIS WARRANT (identity_keys.md step 0) — the in-history birth fact that lets
 // the gate's genesis clause admit a founding control-plane grant on a virgin chain.