@githolon/dsl 0.50.0 → 0.52.0

package/dart/example/nomos_secure_key_store.dart

@@ -0,0 +1,82 @@
+// COPY THIS INTO YOUR FLUTTER APP. It is an EXAMPLE, not part of the `nomos_client` library: it depends on
+// `flutter_secure_storage`, which the pure-Dart `nomos_client` package deliberately does NOT depend on (so
+// the protocol logic stays Flutter-free and unit-testable). This is the ~40 lines of app-specific glue for
+// where your device secret lives — the E2E key CUSTODY policy is yours; the protocol plumbing is not.
+//
+// THE SEALING CLIENT (e2e_sealing_client.md): a generated `<Domain>Client(bridge, keyStore: ...)` seals
+// encrypted directive fields before dispatch + decrypts encrypted read fields automatically. The `keyStore`
+// is the ONE thing you supply. `WrappedKeyStore` (in `nomos_client`) is the default: it unwraps this
+// principal's on-chain WrappedKeys with a DEVICE SECRET. This example shows where that device secret lives —
+// the platform keychain / Keystore via `flutter_secure_storage` — so it survives app restarts, stays off the
+// chain, and never leaves the device.
+//
+// WIRING (once per signed-in principal):
+//   final store = await SecureDeviceKeyStore.open(bridge: bridge, principal: myUid);
+//   final app = NotesClient(bridge, actor: myUid, keyStore: store);   // reads decrypt, writes seal
+//   final rows = await app.notesByOwner(owner: myUid);                // `body` comes back plaintext
+//
+// The OWNER ceremony (grantAndWrap / revokeAndRotate / rotate) uses the SAME device pubkey this store
+// publishes — see `<Domain>Client(bridge, actor: owner).encryption`.
+
+import 'dart:convert';
+
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+import 'package:nomos_client/nomos_client.dart';
+
+/// A [NomosKeyStore] whose device secret is held in the platform keychain (iOS Keychain / Android Keystore)
+/// via `flutter_secure_storage`. It delegates the scope-key unwrap to the framework's [WrappedKeyStore]; the
+/// only thing it adds is DURABLE, PLATFORM-PROTECTED custody of the X25519 device secret.
+class SecureDeviceKeyStore implements NomosKeyStore {
+  final WrappedKeyStore _inner;
+
+  /// This device's X25519 PUBLIC key — publish it (publishEncKey) / hand it to the owner as `publicKey` on
+  /// `grantAndWrap` so the scope key can be wrapped TO this device.
+  final String devicePublicKey;
+
+  SecureDeviceKeyStore._(this._inner, this.devicePublicKey);
+
+  /// Open (or first-time provision) the store for `principal`. On first run it MINTS an X25519 device keypair
+  /// in the kernel, persists the SECRET in secure storage, and returns the store; on later runs it reuses it.
+  static Future<SecureDeviceKeyStore> open({
+    required NomosBridge bridge,
+    required String principal,
+    FlutterSecureStorage storage = const FlutterSecureStorage(),
+  }) async {
+    final secretKey = 'nomos.enc.deviceSecret.$principal';
+    final publicKey = 'nomos.enc.devicePublic.$principal';
+    var secret = await storage.read(key: secretKey);
+    var public = await storage.read(key: publicKey);
+    if (secret == null || public == null) {
+      // FIRST RUN: mint the device keypair (secret stays client-side, never on chain) and persist it.
+      final kp = await bridge.cryptoKeygen();
+      secret = (kp['secret'] ?? '').toString();
+      public = (kp['public'] ?? '').toString();
+      await storage.write(key: secretKey, value: secret);
+      await storage.write(key: publicKey, value: public);
+    }
+    final inner = WrappedKeyStore(
+        bridge: bridge, principal: principal, deviceSecret: secret);
+    return SecureDeviceKeyStore._(inner, public);
+  }
+
+  @override
+  Future<NomosScopeKey?> scopeKey(String scope) => _inner.scopeKey(scope);
+
+  @override
+  Future<List<NomosScopeKey>> readKeys(List<String> scopes) =>
+      _inner.readKeys(scopes);
+
+  /// Convenience: the JSON a `publishEncKey` payload carries (bind the device pubkey to this principal on
+  /// chain so an owner's `grantAndWrap` can resolve it without you passing `publicKey` each time).
+  Map<String, Object?> publishPayload({required String publishedAt}) => {
+        'principal': _inner.principal,
+        'encPublicKey': devicePublicKey,
+        'publishedAt': publishedAt,
+      };
+
+  @override
+  String toString() => 'SecureDeviceKeyStore(${jsonEncode({
+        'principal': _inner.principal,
+        'devicePublicKey': devicePublicKey,
+      })})';
+}

package/dart/lib/src/webview_bridge.dart

@@ -15,6 +15,7 @@
 library;
 
 import 'dart:async';
+import 'dart:convert';
 import 'dart:math';
 
 import 'errors.dart' show nomosErrorFromInfo;
@@ -382,6 +383,287 @@ class WrappedKeyStore implements NomosKeyStore {
   }
 }
 
+// ── E2E OWNER CEREMONY (the sealing client, slice 2) — the owner-side twin of [WrappedKeyStore]. Domain-
+//   agnostic, so it lives here (re-exported per client) exactly like the KeyStore. It composes the framework
+//   key-epoch fan-out (`advanceKeyEpoch`, dispatched by its REAL id) with the domain's own grant/revoke
+//   directive, resolving the roster + each member's wrap-target pubkey FROM THE CHAIN — so the operator-blind
+//   handshake (grant → advance epoch → wrap to every member) is ONE call. Mirror of the TS `_ownerEncryption`. ──
+
+/// Thrown by the owner ceremony when a roster member has NO wrap-target key (no publishEncKey on chain, no
+/// prior wrap, no supplied override) — the ceremony NEVER wraps to a default (fail-closed; a keyless member
+/// is "not yet a member", per e2e_encryption.md's FOOTGUNS).
+class EncryptionMemberKeyMissing implements Exception {
+  final String principal;
+  final String scope;
+  String get code => 'nomos.crypto.member_key_missing';
+  String get recommendedAction => 'publishEncKey';
+  EncryptionMemberKeyMissing(this.principal, this.scope);
+  @override
+  String toString() =>
+      'EncryptionMemberKeyMissing: cannot wrap the "$scope" scope key to member "$principal" — no encryption public key on chain (publishEncKey) and none supplied (fail-closed)';
+}
+
+/// Thrown when the resolved roster != the caller's declared `expectRoster` BEFORE dispatch — pre-firing the
+/// kernel fan-out gate (wrap set == roster) so a rotation against a stale roster view never spends an epoch.
+class EncryptionRosterMismatch implements Exception {
+  final String scope;
+  final List<String> missing;
+  final List<String> extra;
+  String get code => 'nomos.crypto.roster_mismatch';
+  String get recommendedAction => 'reconcileRoster';
+  EncryptionRosterMismatch(this.scope, this.missing, this.extra);
+  @override
+  String toString() =>
+      'EncryptionRosterMismatch: roster for "$scope" != expected (the fan-out gate would refuse): missing $missing, unexpected $extra';
+}
+
+/// The outcome of an epoch-advancing ceremony verb: the new local [head], the [epoch] opened, and the
+/// [roster] the key was wrapped to.
+class NomosEpochResult {
+  final String head;
+  final int epoch;
+  final List<String> roster;
+  const NomosEpochResult(
+      {required this.head, required this.epoch, required this.roster});
+}
+
+/// THE OWNER CEREMONY surface — `<Domain>Client(bridge, actor: owner).encryption`. All three verbs open a
+/// FRESH epoch (a fresh 32-byte secret) and fan the wraps to the resolved roster; the membership change (if
+/// any) is the domain grant/revoke dispatched first, in the same call.
+class NomosEncryption {
+  final NomosBridge bridge;
+  final String domain;
+  final String? domainHash;
+  final String? actor;
+
+  /// The encryption scopes this domain defines (each a `requires(cap)`).
+  final List<String> scopes;
+
+  NomosEncryption(
+      {required this.bridge,
+      required this.domain,
+      this.domainHash,
+      this.actor,
+      required this.scopes});
+
+  String _defScope([String? scope]) {
+    if (scope != null && scope.isNotEmpty) return scope;
+    if (scopes.length == 1) return scopes.first;
+    throw StateError(
+        'this domain defines ${scopes.length} encryption scopes $scopes — pass a scope to pick one');
+  }
+
+  // A BARE scope IS `workspace:self#<relation>` (the era rule); a per-record scope is `<type>:<id>#<relation>`.
+  ({String object, String relation}) _parseScope(String scope) {
+    final h = scope.indexOf('#');
+    return h < 0
+        ? (object: 'workspace:self', relation: scope)
+        : (object: scope.substring(0, h), relation: scope.substring(h + 1));
+  }
+
+  /// The CURRENT roster of a scope (active direct-grant members, principal-form). Defaults to the sole scope.
+  Future<List<String>> roster([String? scope]) => _readRoster(_defScope(scope));
+
+  Future<List<String>> _readRoster(String scope) async {
+    final s = _parseScope(scope);
+    final rows =
+        await bridge.queryById('reltuple-${s.object}-${s.relation}');
+    final subjects = rows.isEmpty
+        ? const <String, dynamic>{}
+        : ((rows.first['data'] as Map?)?['subjects'] as Map?) ??
+            const <String, dynamic>{};
+    final out = <String>[];
+    subjects.forEach((subj, leafRaw) {
+      Map? leaf;
+      try {
+        leaf = leafRaw is String
+            ? jsonDecode(leafRaw) as Map
+            : (leafRaw as Map);
+      } catch (_) {
+        leaf = null;
+      }
+      final status = leaf?['status'];
+      if (status != null && status != 'active') return;
+      final p = subj.toString();
+      out.add(p.startsWith('user:') ? p.substring(5) : p);
+    });
+    out.sort();
+    return out;
+  }
+
+  Future<int> _currentEpoch(String scope) async {
+    final rows = await bridge.queryById('keyscope-$scope');
+    if (rows.isEmpty) return -1;
+    final e = (rows.first['data'] as Map?)?['currentEpoch'];
+    return e is num ? e.toInt() : -1;
+  }
+
+  Future<String> _freshScopeKey() async {
+    final kp = await bridge.cryptoKeygen();
+    final secret = base64Decode((kp['secret'] ?? '').toString());
+    return base64Encode(secret.sublist(0, 32)); // the 32-byte epoch secret; NEVER lands on chain
+  }
+
+  Future<String?> _memberPubKey(String principal,
+      {String? newcomer, String? newcomerPub, Map<String, String>? memberKeys}) async {
+    if (memberKeys != null && memberKeys[principal] != null) {
+      return memberKeys[principal];
+    }
+    if (newcomer == principal && newcomerPub != null) return newcomerPub;
+    // Published enc key (encKeyByPrincipal) — present only when the domain composed the registry; tolerate absence.
+    try {
+      final reg =
+          await bridge.query('encKeyByPrincipal', {'principal': principal});
+      if (reg.isNotEmpty) {
+        final pub = (reg.first['data'] as Map?)?['encPublicKey'];
+        if (pub != null && pub.toString().isNotEmpty) return pub.toString();
+      }
+    } catch (_) {/* not routed — fall through to the prior-wrap lane */}
+    // The member's most-recent WrappedKey pins the pubkey it was last sealed to (rotation needs no re-publish).
+    try {
+      final wraps = await bridge
+          .query('wrappedKeysByRecipient', {'recipientPrincipal': principal});
+      int bestEpoch = -1;
+      String? bestPub;
+      for (final w in wraps) {
+        final d = (w['data'] as Map?) ?? const {};
+        final pub = d['recipientPubKey'];
+        final ep = (d['epoch'] as num?)?.toInt() ?? 0;
+        if (pub != null && ep >= bestEpoch) {
+          bestEpoch = ep;
+          bestPub = pub.toString();
+        }
+      }
+      if (bestPub != null) return bestPub;
+    } catch (_) {/* not routed */}
+    return null;
+  }
+
+  Future<NomosEpochResult> _advance(
+    String scope, {
+    String? addPrincipal,
+    String? addPublicKey,
+    List<String> remove = const [],
+    String? scopeKey,
+    Map<String, String>? memberKeys,
+    List<String>? expectRoster,
+    String? openedAt,
+  }) async {
+    final roster = (await _readRoster(scope)).toSet();
+    if (addPrincipal != null) roster.add(addPrincipal);
+    roster.removeAll(remove);
+    final members = roster.toList()..sort();
+    // PRE-FIRE the fan-out gate: if the caller declared the roster it means to wrap, refuse on drift.
+    if (expectRoster != null) {
+      final want = expectRoster.toSet();
+      final missing = (want.difference(roster).toList())..sort();
+      final extra = members.where((m) => !want.contains(m)).toList();
+      if (missing.isNotEmpty || extra.isNotEmpty) {
+        throw EncryptionRosterMismatch(scope, missing, extra);
+      }
+    }
+    final key = scopeKey ?? await _freshScopeKey();
+    final wraps = <Map<String, Object?>>[];
+    for (final principal in members) {
+      final pub = await _memberPubKey(principal,
+          newcomer: addPrincipal, newcomerPub: addPublicKey, memberKeys: memberKeys);
+      if (pub == null) throw EncryptionMemberKeyMissing(principal, scope);
+      final w = await bridge.cryptoWrapKey(recipientPub: pub, scopeKey: key);
+      wraps.add({
+        'recipientPrincipal': principal,
+        'recipientPubKey': pub,
+        'hpkeEpk': (w['hpkeEpk'] ?? '').toString(),
+        'ct': (w['ct'] ?? '').toString(),
+      });
+    }
+    final epoch = (await _currentEpoch(scope)) + 1; // forward-only: strictly increments
+    final head = await bridge.offerDirective(
+      domain: domain,
+      directiveId: 'advanceKeyEpoch',
+      payload: {
+        'scope': scope,
+        'epoch': epoch,
+        'openedAt': openedAt ?? DateTime.now().toUtc().toIso8601String(),
+        'wraps': wraps,
+      },
+      actor: actor,
+      domainHash: domainHash,
+    );
+    return NomosEpochResult(head: head, epoch: epoch, roster: members);
+  }
+
+  /// Grant a newcomer + open a fresh epoch wrapping the key to EVERY member (incl. the newcomer). Dispatches
+  /// `grantDirective(grantPayload)` first, then `advanceKeyEpoch`. `publicKey` is the newcomer's X25519 key
+  /// (else resolved from an on-chain publishEncKey). Existing members' keys come from their prior wraps.
+  Future<NomosEpochResult> grantAndWrap({
+    required String principal,
+    String? publicKey,
+    String? scope,
+    required String grantDirective,
+    required Map<String, Object?> grantPayload,
+    String? scopeKey,
+    Map<String, String>? memberKeys,
+    List<String>? expectRoster,
+    String? openedAt,
+  }) async {
+    final s = _defScope(scope);
+    await bridge.offerDirective(
+        domain: domain,
+        directiveId: grantDirective,
+        payload: grantPayload,
+        actor: actor,
+        domainHash: domainHash);
+    return _advance(s,
+        addPrincipal: principal,
+        addPublicKey: publicKey,
+        scopeKey: scopeKey,
+        memberKeys: memberKeys,
+        expectRoster: expectRoster,
+        openedAt: openedAt);
+  }
+
+  /// Revoke a member + open a fresh epoch re-wrapping the key to the SURVIVORS only. FORWARD-ONLY: the removed
+  /// member gets no NEW reads, but old ciphertext it already holds a key for stays readable (not re-encrypted).
+  Future<NomosEpochResult> revokeAndRotate({
+    required String principal,
+    String? scope,
+    required String revokeDirective,
+    required Map<String, Object?> revokePayload,
+    String? scopeKey,
+    Map<String, String>? memberKeys,
+    List<String>? expectRoster,
+    String? openedAt,
+  }) async {
+    final s = _defScope(scope);
+    await bridge.offerDirective(
+        domain: domain,
+        directiveId: revokeDirective,
+        payload: revokePayload,
+        actor: actor,
+        domainHash: domainHash);
+    return _advance(s,
+        remove: [principal],
+        scopeKey: scopeKey,
+        memberKeys: memberKeys,
+        expectRoster: expectRoster,
+        openedAt: openedAt);
+  }
+
+  /// Routine rotation — open a fresh epoch re-wrapping the key to the CURRENT roster (no membership change).
+  Future<NomosEpochResult> rotate({
+    String? scope,
+    String? scopeKey,
+    Map<String, String>? memberKeys,
+    List<String>? expectRoster,
+    String? openedAt,
+  }) =>
+      _advance(_defScope(scope),
+          scopeKey: scopeKey,
+          memberKeys: memberKeys,
+          expectRoster: expectRoster,
+          openedAt: openedAt);
+}
+
 /// The result of [NomosBridge.offerCreates]: the new local [head] plus every aggregate the plan minted.
 class NomosOfferOutcome {
   final String head;

package/lsp_server.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// 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.
+
+// `githolon lsp` launcher — the twin of `check_package.mjs`: resolve `tsx` (the caller's, else the
+// DSL's own dependency) and run `src/lsp_main.ts` under it. The server imports the tenant's TS domain
+// modules IN-PROCESS on every re-check (needs the tsx ESM loader). stdio is inherited so the LSP wire
+// (stdin/stdout, JSON-RPC) passes through untouched; the editor spawns this and talks to it directly.
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DSL_DIR = path.dirname(fileURLToPath(import.meta.url));
+const MAIN = path.join(DSL_DIR, "src", "lsp_main.ts");
+
+function resolvePkgDir(name, fromDir) {
+  try {
+    const req = createRequire(pathToFileURL(path.join(fromDir, "noop.js")));
+    return path.dirname(req.resolve(`${name}/package.json`));
+  } catch {
+    return undefined;
+  }
+}
+
+const tsxDir = resolvePkgDir("tsx", process.cwd()) ?? resolvePkgDir("tsx", DSL_DIR);
+if (!tsxDir) {
+  console.error("githolon lsp: tsx not found — reinstall @githolon/dsl (tsx is one of its dependencies)");
+  process.exit(1);
+}
+const tsxPkg = JSON.parse(readFileSync(path.join(tsxDir, "package.json"), "utf8"));
+const tsxBinRel = typeof tsxPkg.bin === "string" ? tsxPkg.bin : tsxPkg.bin?.tsx;
+const tsxCli = path.join(tsxDir, tsxBinRel ?? "dist/cli.mjs");
+
+// spawn (not execFileSync) so the long-lived server's stdio streams stay connected for the session.
+const child = spawn(process.execPath, [tsxCli, MAIN, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+});
+child.on("exit", (code) => process.exit(code ?? 0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.50.0",
+  "version": "0.52.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",
@@ -47,7 +47,8 @@
     "!dart/.dart_tool",
     "!dart/build",
     "compile_package.mjs",
-    "check_package.mjs"
+    "check_package.mjs",
+    "lsp_server.mjs"
   ],
   "publishConfig": {
     "access": "public"
@@ -59,6 +60,8 @@
   "dependencies": {
     "esbuild": "0.24.2",
     "tsx": "^4.19.2",
+    "vscode-languageserver": "^9.0.1",
+    "vscode-languageserver-textdocument": "^1.0.12",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/src/check_package_main.ts

@@ -10,13 +10,22 @@
  * discovery), runs {@link checkDomainModules}, prints the unified report, and exits
  * non-zero on any REFUSE-level finding. `compile` runs the same twins implicitly.
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { composeDomainModule, type Mod } from "./build_package.js";
 import type { DomainModule } from "./codegen_dart.js";
-import { checkDomainModules, formatFindings, hasRefusal } from "./law_check.js";
+import { checkDomainModules, formatFindings, hasRefusal, type Finding } from "./law_check.js";
+import { LawSourceMap } from "./law_source_map.js";
+import {
+  currentEvolveLaw,
+  evolveDiff,
+  evolveLawFromDeployJson,
+  evolveLawFromLockfile,
+  type EvolveLaw,
+  type StableIdLockfile,
+} from "./evolve_preview.js";
 
 interface DomainConfig {
   key: string;
@@ -40,35 +49,169 @@ function fail(msg: string): never {
  * applies the secondary-ensure auto-declare). Returns the composed modules ready for the twins.
  */
 export async function loadComposedModules(configArg: string): Promise<DomainModule[]> {
+  return (await loadComposedModulesWithSources(configArg)).modules;
+}
+
+/**
+ * Like {@link loadComposedModules}, but ALSO returns the domain-key → ORDERED module file paths map
+ * (the source map's input — the composed DomainModule does not retain source paths, so the check/LSP
+ * lane threads them through). The config is the one place that names both the domain key and its files.
+ */
+export async function loadComposedModulesWithSources(
+  configArg: string,
+): Promise<{ modules: DomainModule[]; domainFiles: Map<string, string[]> }> {
   const configPath = path.resolve(process.cwd(), configArg);
   if (!existsSync(configPath)) fail(`config not found: ${configPath}`);
   const cfgDir = path.dirname(configPath);
-  const cfgModule = (await import(pathToFileURL(configPath).href)) as { default?: PackageConfig };
+  // Cache-bust the config import so a re-load (the LSP re-check) sees edits, not the first-import cache.
+  const cfgUrl = `${pathToFileURL(configPath).href}?t=${Date.now()}`;
+  const cfgModule = (await import(cfgUrl)) as { default?: PackageConfig };
   const cfg = cfgModule.default;
   if (!cfg || typeof cfg.name !== "string" || !Array.isArray(cfg.domains) || cfg.domains.length === 0) {
     fail(`config must default-export { name, domains: [{ key, modules }, ...] }`);
   }
   const composed: DomainModule[] = [];
+  const domainFiles = new Map<string, string[]>();
   for (const d of cfg.domains) {
     if (typeof d.key !== "string" || !Array.isArray(d.modules) || d.modules.length === 0) {
       fail(`each domain needs { key, modules: [path, ...] }; got ${JSON.stringify(d)}`);
     }
     const mods: Mod[] = [];
+    const files: string[] = [];
     for (const rel of d.modules) {
       const abs = path.resolve(cfgDir, rel);
       if (!existsSync(abs)) fail(`domain '${d.key}': module not found: ${abs}`);
-      mods.push((await import(pathToFileURL(abs).href)) as Mod);
+      files.push(abs);
+      // Cache-bust so a re-import (the LSP re-check after an edit) re-evaluates the edited module.
+      mods.push((await import(`${pathToFileURL(abs).href}?t=${Date.now()}`)) as Mod);
     }
+    domainFiles.set(d.key, files);
     composed.push(composeDomainModule({ name: d.name ?? d.key, domain: d.key, modules: mods }));
   }
-  return composed;
+  return { modules: composed, domainFiles };
+}
+
+/**
+ * Load the PRIOR law surface for `--against <path>` (the evolve preview's baseline). The supported
+ * prior is a DEPLOY.JSON (`build/<name>.deploy.json`), a BUILD DIR / package dir containing one, or
+ * the committed `nomos.stable-ids.json` LOCKFILE (aggregate identity only — no directive payloads).
+ * A live `https://…` prior is NOT supported (the installed package's stable-ids aren't retrievable
+ * from GET /domains); point `--against` at the deployed law's committed deploy.json instead.
+ */
+function loadPriorEvolveLaw(arg: string): { law: EvolveLaw; source: string; note?: string } {
+  if (/^https?:\/\//.test(arg)) {
+    fail(
+      `--against does not support a live URL (${arg}) — the installed package's #58 stable-ids are ` +
+        `not retrievable from GET /domains. Point --against at the deployed law's build/<name>.deploy.json.`,
+    );
+  }
+  const abs = path.resolve(process.cwd(), arg);
+  if (!existsSync(abs)) fail(`--against: prior not found: ${abs}`);
+  // Resolve a directory to a deploy.json (build dir or package dir) or its lockfile.
+  let file = abs;
+  if (statSync(abs).isDirectory()) {
+    const deploy = findDeployJson(abs);
+    const lock = path.join(abs, "nomos.stable-ids.json");
+    if (deploy !== undefined) file = deploy;
+    else if (existsSync(lock)) file = lock;
+    else fail(`--against: no *.deploy.json or nomos.stable-ids.json under ${abs}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (e) {
+    fail(`--against: could not parse ${file}: ${(e as Error).message}`);
+  }
+  const p = parsed as Record<string, unknown>;
+  if (p.domains !== undefined && p.interface === undefined && p.packageUsda === undefined) {
+    return {
+      law: evolveLawFromLockfile(parsed as StableIdLockfile),
+      source: file,
+      note: `prior is a lockfile — aggregate/field identity is diffed, but directive payload changes cannot be (deploy.json carries the interface).`,
+    };
+  }
+  return { law: evolveLawFromDeployJson(parsed as never), source: file };
+}
+
+/** Find a `*.deploy.json` under a directory — directly, or one level down in `build/`. */
+function findDeployJson(dir: string): string | undefined {
+  const scan = (d: string): string | undefined => {
+    if (!existsSync(d)) return undefined;
+    const hit = readdirSync(d).find((f) => f.endsWith(".deploy.json"));
+    return hit !== undefined ? path.join(d, hit) : undefined;
+  };
+  return scan(dir) ?? scan(path.join(dir, "build"));
+}
+
+/** Read the committed `nomos.stable-ids.json` lockfile beside the config (the CURRENT identity). */
+function loadCwdLockfile(configArg: string): StableIdLockfile | undefined {
+  const cfgDir = path.dirname(path.resolve(process.cwd(), configArg));
+  const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
+  if (!existsSync(lockPath)) return undefined;
+  try {
+    return JSON.parse(readFileSync(lockPath, "utf8")) as StableIdLockfile;
+  } catch {
+    return undefined;
+  }
 }
 
 async function main(): Promise<void> {
   const argv = process.argv.slice(2);
-  const configArg = argv.find((a) => !a.startsWith("--")) ?? "nomos.package.mjs";
-  const modules = await loadComposedModules(configArg);
-  const findings = checkDomainModules(modules);
+  // The positional config must SKIP flag VALUES (`check --against prior.json` has no
+  // positional — `prior.json` belongs to the flag, not the config slot).
+  const againstIdx = argv.findIndex((a) => a === "--against");
+  const positionals = argv.filter((a, i) => !a.startsWith("--") && i !== againstIdx + 1);
+  const configArg = positionals[0] ?? "nomos.package.mjs";
+  const againstArg =
+    againstIdx >= 0
+      ? argv[againstIdx + 1]
+      : argv.find((a) => a.startsWith("--against="))?.slice("--against=".length);
+
+  const asJson = argv.includes("--json");
+
+  const { modules, domainFiles } = await loadComposedModulesWithSources(configArg);
+  const findings: Finding[] = [...checkDomainModules(modules)];
+
+  // ── EVOLVE PREVIEW (--against): diff the current build against a prior law + pre-fire the gate. ──
+  let evolveDispositions: Record<string, unknown> | undefined;
+  if (againstIdx >= 0 || againstArg !== undefined) {
+    if (againstArg === undefined || againstArg.startsWith("--")) {
+      fail(`--against needs a path: --against <build/<name>.deploy.json | build dir | nomos.stable-ids.json>`);
+    }
+    const lock = loadCwdLockfile(configArg);
+    if (lock === undefined && !asJson) {
+      console.log(
+        "githolon check: --against — no nomos.stable-ids.json in the config dir; the current law's stable ids " +
+          "fall back to NAMES (a rename would read as removal+add). Run `githolon compile` first for a sid-accurate preview.",
+      );
+    }
+    const prior = loadPriorEvolveLaw(againstArg);
+    if (prior.note !== undefined && !asJson) console.log(`githolon check: --against note — ${prior.note}`);
+    const current = currentEvolveLaw(modules, lock);
+    const diff = evolveDiff(prior.law, current);
+    findings.push(...diff.findings);
+    if (Object.keys(diff.dispositions).length > 0) evolveDispositions = diff.dispositions;
+    if (!asJson) console.log(`githolon check: evolve preview against ${prior.source}`);
+  }
+
+  // ── --json: emit the findings as a machine-readable array (the LSP + tooling surface). Each finding
+  //    is enriched with its source {file, line, column} when the source map can locate the declaration.
+  if (asJson) {
+    const srcMap = new LawSourceMap(domainFiles);
+    const out = findings.map((f) => {
+      const loc = srcMap.locate(f.domain, f.directiveId);
+      return {
+        domain: f.domain,
+        ...(f.directiveId !== undefined ? { directiveId: f.directiveId } : {}),
+        level: f.level,
+        what: f.what,
+        fix: f.fix,
+        ...(loc !== undefined ? { file: loc.file, line: loc.line, column: loc.column, fallback: loc.fallback } : {}),
+      };
+    });
+    process.stdout.write(JSON.stringify(out) + "\n");
+    process.exit(hasRefusal(findings) ? 1 : 0);
+  }
 
   console.log(`githolon check: ${findings.length} finding(s)`);
   for (const line of formatFindings(findings)) {
@@ -77,6 +220,14 @@ async function main(): Promise<void> {
   }
   if (findings.length === 0) console.log("  all clear — no static twin flagged anything");
 
+  // The consolidated, pasteable dispositions the destructive evolves demand (per domain).
+  if (evolveDispositions !== undefined) {
+    console.log(
+      "\ngitholon check: to admit the destructive evolve, add `dispositions` to the domain's deploy JSON:",
+    );
+    console.log(JSON.stringify(evolveDispositions, null, 2));
+  }
+
   process.exit(hasRefusal(findings) ? 1 : 0);
 }