@githolon/dsl 0.48.1 → 0.50.0

package/check_package.mjs

@@ -0,0 +1,46 @@
+#!/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 check` launcher — the twin of `compile_package.mjs`: resolve `tsx`
+// (the caller's, else the DSL's own dependency) and run `src/check_package_main.ts`
+// under it (the main dynamically imports the caller's TS domain modules, which
+// needs the tsx ESM loader). Resolution goes through Node's resolver (createRequire),
+// NOT node_modules/.bin paths — hoisted/workspace installs put the bin shims elsewhere.
+import { execFileSync } 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", "check_package_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 check: 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");
+
+try {
+  execFileSync(process.execPath, [tsxCli, MAIN, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  });
+} catch (e) {
+  process.exit(e.status ?? 1);
+}

package/dart/lib/src/test_harness.dart

@@ -66,7 +66,11 @@ class NomosTestHarness {
   /// [runtimeDir] — the runtime cache (default `~/.holon/runtime`); must hold `holon.wasm` + `packages.json`.
   /// [nodeEntry] — path to `node-entry.mjs`; when omitted it is resolved from [resolveFrom] via
   /// `require.resolve('@githolon/client/runner/node-entry.mjs')`.
-  /// [installHelper] — path to `offline-install.mjs`; defaults to the file beside [nodeEntry].
+  /// [installHelper] — the offline law-install lane. An EXISTING `.mjs` file is run as a node script (the
+  /// in-repo `offline-install.mjs`, the default when it exists beside [nodeEntry]); anything else is a
+  /// githolon COMMAND LINE whose `harness-install` subcommand is driven (the default `npx githolon` when the
+  /// in-repo helper is absent — a published tenant needs nothing but `githolon`). E.g. force the subcommand
+  /// with `installHelper: 'node /abs/cli/dist/cli.mjs'`.
   /// [registerTearDown] — pass the test framework's `addTearDown` to auto-[dispose] when the test ends
   /// (feature-detecting `package:test` from a library is not clean in Dart, so this is explicit and safe).
   /// [autoTearDown] — when true (default) and [registerTearDown] is given, registers [dispose] as a teardown.
@@ -90,8 +94,18 @@ class NomosTestHarness {
     }
     final entry = nodeEntry ??
         await _resolveEntry(node, resolveFrom ?? Directory.current.path);
-    final helper = installHelper ??
-        '${File(entry).parent.path}/offline-install.mjs';
+    // THE INSTALL LANE. [installHelper] is the one seam (PACKAGING NOTE above): either the in-repo
+    // `offline-install.mjs` node script, OR the published `githolon harness-install` subcommand (the CLI
+    // bundles the engine + this exact install sequence, so a published tenant needs nothing but `githolon`).
+    //  • an EXISTING `.mjs` file  ⇒ run it as a node script (the in-repo default when present);
+    //  • anything else            ⇒ treat it as a githolon COMMAND LINE and drive `harness-install`
+    //    (default `npx githolon` when the in-repo helper is absent; the test forces this lane by passing
+    //    e.g. `installHelper: 'node /abs/cli/dist/cli.mjs'`).
+    final resolvedHelper =
+        installHelper ?? '${File(entry).parent.path}/offline-install.mjs';
+    final useInRepoScript =
+        resolvedHelper.endsWith('.mjs') && File(resolvedHelper).existsSync();
+    final githolonCmd = installHelper == null ? 'npx githolon' : resolvedHelper;
 
     // A FRESH temp dir per harness — the snapshot + any transient runner state live here and nowhere else,
     // so dispose() leaves nothing behind.
@@ -102,7 +116,9 @@ class NomosTestHarness {
       final snapshot = '${workdir.path}/snapshot.bin';
       await _runInstall(
           node: node,
-          helper: helper,
+          useInRepoScript: useInRepoScript,
+          inRepoScript: resolvedHelper,
+          githolonCmd: githolonCmd,
           deployJsonPaths: deployJsonPaths,
           workspace: workspace,
           snapshot: snapshot,
@@ -182,29 +198,45 @@ class NomosTestHarness {
 
   static Future<void> _runInstall({
     required String node,
-    required String helper,
+    required bool useInRepoScript,
+    required String inRepoScript,
+    required String githolonCmd,
     required List<String> deployJsonPaths,
     required String workspace,
     required String snapshot,
     String? runtimeDir,
     void Function(String line)? onDiagnostic,
   }) async {
-    if (!File(helper).existsSync()) {
-      throw NomosTestHarnessException(
-          'offline-install helper not found at $helper — pass installHelper: explicitly '
-          '(it ships beside node-entry.mjs)');
-    }
-    final r = await Process.run(node, [
-      helper,
+    // Both lanes take the SAME flags (--deploy/--workspace/--out/--runtime) and print the SAME one-line JSON
+    // contract; only the leading command differs (node <script> vs `<githolon...> harness-install`).
+    final common = <String>[
       '--deploy', deployJsonPaths.join(','),
       '--workspace', workspace,
       '--out', snapshot,
       if (runtimeDir != null) ...['--runtime', runtimeDir],
-    ]);
+    ];
+    final String executable;
+    final List<String> args;
+    if (useInRepoScript) {
+      executable = node;
+      args = [inRepoScript, ...common];
+    } else {
+      // `githolonCmd` is a command line (e.g. `npx githolon` or `node /abs/cli.mjs`) — split into tokens.
+      final tokens =
+          githolonCmd.trim().split(RegExp(r'\s+')).where((t) => t.isNotEmpty).toList();
+      if (tokens.isEmpty) {
+        throw NomosTestHarnessException(
+            'no install helper resolved — pass installHelper: (an offline-install.mjs path, or a githolon command)');
+      }
+      executable = tokens.first;
+      args = [...tokens.skip(1), 'harness-install', ...common];
+    }
+    final tag = useInRepoScript ? 'offline-install' : 'harness-install';
+    final r = await Process.run(executable, args);
     final err = (r.stderr as String).trim();
     if (err.isNotEmpty) {
       for (final line in err.split('\n')) {
-        (onDiagnostic ?? stderr.writeln)('[offline-install] $line');
+        (onDiagnostic ?? stderr.writeln)('[$tag] $line');
       }
     }
     if (r.exitCode != 0) {

package/dart/lib/src/webview_bridge.dart

@@ -292,6 +292,96 @@ class NomosBbox {
       {'minLng': minLng, 'minLat': minLat, 'maxLng': maxLng, 'maxLat': maxLat};
 }
 
+// ── E2E SEALING (the sealing client) — the GENERIC key-custody surface. Generated domain clients bake the
+//   per-domain map + seal/read helpers, but these types are domain-agnostic, so they live here (in the
+//   nomos_client library) exactly like [MissingOfferAuthority] — one definition, re-exported per client. ──
+
+/// A held E2E scope key: the base64 symmetric key + the epoch it belongs to (forward-only rotation).
+class NomosScopeKey {
+  final String scope;
+  final int epoch;
+  final String key;
+  const NomosScopeKey(
+      {required this.scope, required this.epoch, required this.key});
+  Map<String, Object?> toJson() => {'scope': scope, 'epoch': epoch, 'key': key};
+}
+
+/// The app-supplied KEY CUSTODY surface (E2E sealing). Supply one to a generated `<Domain>Client` and its
+/// encrypted directive fields SEAL automatically before dispatch + encrypted read fields DECRYPT
+/// automatically. [WrappedKeyStore] is the default over the on-chain WrappedKeys; an app may implement this
+/// to source keys from secure storage (the key custody policy stays the app's; the protocol plumbing does not).
+abstract class NomosKeyStore {
+  /// The CURRENT (highest-epoch) scope key, for SEALING a write. null ⇒ EncryptionKeyUnavailable.
+  Future<NomosScopeKey?> scopeKey(String scope);
+
+  /// EVERY held key for these scopes (all epochs), injected on reads so old ciphertext also decrypts.
+  Future<List<NomosScopeKey>> readKeys(List<String> scopes);
+}
+
+/// Thrown when a write must seal an encrypted field but the KeyStore holds no key for its scope — the write
+/// NEVER falls through to a plaintext dispatch (the sid-envelope gate would refuse it anyway; we pre-fire).
+class EncryptionKeyUnavailable implements Exception {
+  final String scope;
+  final String field;
+  String get code => 'nomos.crypto.key_unavailable';
+  String get recommendedAction => 'obtainScopeKey';
+  EncryptionKeyUnavailable(this.scope, this.field);
+  @override
+  String toString() =>
+      'EncryptionKeyUnavailable: cannot seal "$field": no scope key held for "$scope" (obtain the cap + wrap the scope epoch first)';
+}
+
+/// THE DEFAULT KeyStore — unwraps this principal's on-chain WrappedKeys with its device secret, caching per
+/// scope. Mirror of the documented reader handshake (e2e_encryption.md): the secret stays client-side, the
+/// operator stays blind. Key custody (where `deviceSecret` lives — enclave, password-derived, …) is the app's.
+class WrappedKeyStore implements NomosKeyStore {
+  final NomosBridge bridge;
+  final String principal;
+  final String deviceSecret;
+  final Map<String, Future<List<NomosScopeKey>>> _cache = {};
+  WrappedKeyStore(
+      {required this.bridge,
+      required this.principal,
+      required this.deviceSecret});
+
+  Future<List<NomosScopeKey>> _loadScope(String scope) {
+    return _cache.putIfAbsent(scope, () async {
+      final rows = await bridge
+          .query('wrappedKeysByRecipient', {'recipientPrincipal': principal});
+      final held = <NomosScopeKey>[];
+      for (final row in rows) {
+        final d = ((row['data'] ?? row) as Map);
+        if (d['scope']?.toString() != scope) continue;
+        final key = await bridge.cryptoUnwrapKey(
+            secret: deviceSecret,
+            hpkeEpk: d['hpkeEpk'].toString(),
+            ct: d['ct'].toString());
+        held.add(NomosScopeKey(
+            scope: scope,
+            epoch: (d['epoch'] as num?)?.toInt() ?? 0,
+            key: key));
+      }
+      held.sort((a, b) => b.epoch - a.epoch);
+      return held;
+    });
+  }
+
+  @override
+  Future<NomosScopeKey?> scopeKey(String scope) async {
+    final ks = await _loadScope(scope);
+    return ks.isEmpty ? null : ks.first;
+  }
+
+  @override
+  Future<List<NomosScopeKey>> readKeys(List<String> scopes) async {
+    final all = <NomosScopeKey>[];
+    for (final s in scopes) {
+      all.addAll(await _loadScope(s));
+    }
+    return all;
+  }
+}
+
 /// The result of [NomosBridge.offerCreates]: the new local [head] plus every aggregate the plan minted.
 class NomosOfferOutcome {
   final String head;
@@ -771,14 +861,78 @@ class NomosBridge {
           Map<String, Object?> args) async =>
       _asMap(await _call('attestationSign', {'args': args}));
 
-  /// A declared query's rows from the local projection.
+  /// A declared query's rows from the local projection. `keys` (E2E sealing) injects the reader's held
+  /// scope keys so encrypted fields AEAD-open in-wasm; absent ⇒ they stay opaque envelopes (today's
+  /// behavior). `principal` stamps the private-read gate (defaults to the connection's bound principal).
+  /// Both are OMITTED from the wire when absent, so a public un-keyed read is byte-identical to before.
   Future<List<Map<String, dynamic>>> query(String queryId,
-          [Map<String, Object?> params = const {}]) async =>
-      _asRows(await _call('query', {'queryId': queryId, 'params': params}));
+          [Map<String, Object?> params = const {},
+          List<NomosScopeKey>? keys,
+          String? principal]) async =>
+      _asRows(await _call('query', {
+        'queryId': queryId,
+        'params': params,
+        ...?_readAuthArgs(keys, principal),
+      }));
+
+  /// A single aggregate by id (the by-id read). `keys`/`principal`: see [query].
+  Future<List<Map<String, dynamic>>> queryById(String id,
+          [List<NomosScopeKey>? keys, String? principal]) async =>
+      _asRows(await _call('queryById', {
+        'id': id,
+        ...?_readAuthArgs(keys, principal),
+      }));
+
+  /// The read auth sidecar (private reads + E2E): `keys`/`principal` as top-level call args, or null when
+  /// neither is present (so the wire is byte-identical to before this existed).
+  Map<String, Object?>? _readAuthArgs(List<NomosScopeKey>? keys, String? principal) {
+    final out = <String, Object?>{};
+    if (principal != null && principal.isNotEmpty) out['principal'] = principal;
+    if (keys != null && keys.isNotEmpty) out['keys'] = keys.map((k) => k.toJson()).toList();
+    return out.isEmpty ? null : out;
+  }
 
-  /// A single aggregate by id (the by-id read).
-  Future<List<Map<String, dynamic>>> queryById(String id) async =>
-      _asRows(await _call('queryById', {'id': id}));
+  /// E2E CRYPTO OPS (operator-blind sealing) — routed to the kernel via the WebView runner. XChaCha isn't in
+  /// WebCrypto/Dart, so these drive the wasm; the scope key + device secret are INJECTED per call and never
+  /// touch the chain. Mirror of the TS holon's crypto seam (@githolon/client).
+  /// Mint an X25519 device keypair for the handshake: `{secret, public}` (base64). Secret stays on device.
+  Future<Map<String, Object?>> cryptoKeygen() async =>
+      _asMap(await _call('cryptoKeygen'));
+
+  /// AUTHOR-SIDE SEAL: encrypt `plaintext` into its on-chain ciphertext envelope, bound to the scope + #58
+  /// stable sids (rename-safe). Returns the envelope string the encrypted field value is written as.
+  Future<String> cryptoSealField(
+          {required String scopeKey,
+          required String scope,
+          required int epoch,
+          required String aggSid,
+          required String fieldSid,
+          required String plaintext}) async =>
+      (_asMap(await _call('cryptoSealField', {
+        'scopeKey': scopeKey,
+        'scope': scope,
+        'epoch': epoch,
+        'aggSid': aggSid,
+        'fieldSid': fieldSid,
+        'plaintext': plaintext,
+      }))['envelope'] ?? '')
+          .toString();
+
+  /// Wrap a scope key TO a recipient's public key (committer side): `{hpkeEpk, ct}` base64 ciphertext.
+  Future<Map<String, Object?>> cryptoWrapKey(
+          {required String recipientPub, required String scopeKey}) async =>
+      _asMap(await _call('cryptoWrapKey',
+          {'recipientPub': recipientPub, 'scopeKey': scopeKey}));
+
+  /// Unwrap an on-chain WrappedKey with this device's secret → the base64 scope key (reader side).
+  Future<String> cryptoUnwrapKey(
+          {required String secret,
+          required String hpkeEpk,
+          required String ct}) async =>
+      (_asMap(await _call('cryptoUnwrapKey',
+                  {'secret': secret, 'hpkeEpk': hpkeEpk, 'ct': ct}))['scopeKey'] ??
+              '')
+          .toString();
 
   /// THE SPATIAL READ: rows of the declared spatial index's of-type whose geometry
   /// intersects [bbox] — an R*Tree probe on the local projection, same row shape as [query].

package/dart/test/test_harness_test.dart

@@ -20,6 +20,9 @@ String get _guestbookDeployJson =>
     '${Directory.current.path}/../../examples/guestbook/build/guestbook.deploy.json';
 String get _runtimeDir =>
     '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+// The built CLI bin — drives the `githolon harness-install` SUBCOMMAND lane (the published-harness path).
+String get _cliDist =>
+    '${Directory.current.path}/../../cli/dist/cli.mjs';
 
 /// The prerequisite that isn't installable in-test (a warm runtime cache + the compiled fixture). Returns a
 /// skip reason, or null when everything the harness needs is present.
@@ -100,4 +103,43 @@ void main() {
     await expectLater(
         harness.bridge.query('entriesByAuthor', {'author': 'x'}), throwsA(anything));
   }, timeout: const Timeout(Duration(minutes: 2)));
+
+  test('OFFLINE: the `githolon harness-install` SUBCOMMAND lane installs law and drives a read', () async {
+    final skip = _missingPrereq();
+    if (skip != null) {
+      markTestSkipped(skip);
+      return;
+    }
+    if (!File(_cliDist).existsSync()) {
+      markTestSkipped('build the CLI first: cd cli && npm run build (needs dist/cli.mjs)');
+      return;
+    }
+    // FORCE the published subcommand lane via the installHelper seam: a githolon command line (here the
+    // in-repo built bin) whose `harness-install` subcommand does the offline install a published tenant gets.
+    final harness = await NomosTestHarness.ephemeral(
+      deployJsonPaths: [_guestbookDeployJson],
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      installHelper: 'node $_cliDist', // NOT an existing .mjs file ⇒ the subcommand lane
+      registerTearDown: addTearDown,
+    );
+
+    final outcome = await harness.bridge.offerCreates(
+      domain: 'guestbook',
+      directiveId: 'signGuestbook',
+      payload: {
+        'author': 'subcommand',
+        'message': 'installed via githolon harness-install',
+        'mood': 'happy',
+        'signedAt': DateTime.now().toUtc().toIso8601String(),
+      },
+    );
+    expect(outcome.created, hasLength(1));
+    final rows = await harness.bridge.query('entriesByAuthor', {'author': 'subcommand'});
+    expect(rows, hasLength(1));
+    expect((rows.first['data'] as Map)['message'], 'installed via githolon harness-install');
+    expect((rows.first['data'] as Map)['moodEmoji'], '😊'); // the law's plan ran through the subcommand-built snapshot
+
+    stdout.writeln('subcommand harness green: ws=${harness.workspace}');
+  }, timeout: const Timeout(Duration(minutes: 2)));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.48.1",
+  "version": "0.50.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",
@@ -46,7 +46,8 @@
     "dart",
     "!dart/.dart_tool",
     "!dart/build",
-    "compile_package.mjs"
+    "compile_package.mjs",
+    "check_package.mjs"
   ],
   "publishConfig": {
     "access": "public"

package/src/build_package.ts

@@ -68,6 +68,7 @@ import { emitUsd } from "./usd.js";
 import { expandCapabilityExports } from "./capability_exports.js";
 import { RelationTuple } from "./framework/relations.js";
 import { parentAttestedBirthMarker } from "./births.js";
+import { discoverUnsanctionedEnsures, sanctioningEnsureDirective } from "./secondary_ensure.js";
 
 // ─────────────────────────────────────────────────────────────────────────────────
 // composeDomainModule — the named-keys `module(...)`
@@ -185,6 +186,24 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
       if (!byId.has(a.id)) byId.set(a.id, a);
     }
   }
+  // SECONDARY-CREATE AUTO-DECLARE (secondary_ensure.ts — the id-mint-gate DX): a plan may `ensure(B, "det:id")`
+  // a SECOND aggregate at a deterministic id of a type its directive does NOT declare `.ensures()` for. The
+  // id-mint gate refuses such an id unless the certified manifest carries an `Ensure → B` declaration. Plan-
+  // probe the directives, and for every ensured type NO directive already declares, inject a NO-OP sanctioning
+  // `.ensures(B)` directive (modelled on `nomosBirthRecordEnsure`) so the manifest opens the declared-ensures
+  // lane. Best-effort + era-safe: a domain with no (unsanctioned) secondary ensure synthesizes nothing and is
+  // byte-identical; a domain that DOES could not have deployed before without the author hand-writing this.
+  const autoDeclaredEnsures: string[] = [];
+  for (const ty of discoverUnsanctionedEnsures(directives, spec.domain ?? spec.name)) {
+    const agg = byId.get(ty);
+    // Only sanction a type whose handle this domain actually carries (its schema must be present for the
+    // upsert to fold); a probe pointing at a foreign/unknown type is left to the runtime gate (no schema).
+    if (agg === undefined) continue;
+    const dir = sanctioningEnsureDirective(agg);
+    if (directives.some((d) => d.id === dir.id)) continue;
+    directives.push(dir);
+    autoDeclaredEnsures.push(ty);
+  }
   const aggregates = [...byId.values()];
   const directiveIds = new Set(directives.map((d) => d.id));
   for (const task of spec.impureCapabilities ?? []) {
@@ -330,6 +349,8 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     domain: spec.domain ?? spec.name,
     aggregates,
     directives,
+    // Diagnostic metadata for the compile summary — NOT law (not hashed). Omit-when-empty.
+    ...(autoDeclaredEnsures.length > 0 ? { autoDeclaredEnsures } : {}),
     ...(queries.length > 0 ? { queries } : {}),
     ...(counts.length > 0 ? { counts } : {}),
     ...(spatials.length > 0 ? { spatials } : {}),
@@ -878,7 +899,29 @@ export function hexUtf8(text: string): string {
  * domainHash the deploy names is sha256 over the WHOLE returned string (trailing
  * newline included) exactly as committed.
  */
-export function packageUsda(usdJson: string, javascript: string): string {
+export function packageUsda(usdJson: string, javascript: string, opts: { compact?: boolean } = {}): string {
+  // THE COMPACT ERA (opt-in, 2026-07-04): base64 blob fields (`*B64`, 1.33× text) instead of hex
+  // (2×). Requires every consumer to carry the decode arm (kernel domain_package.rs extract_blob +
+  // the JS parsers) — shipped ahead of this emit, so `compact: true` is the tenant's explicit
+  // choice once their stack is current. Hex stays the default emit until a future major; hex
+  // packages parse FOREVER (the era rule). sha256(the returned string) is the domainHash either
+  // way — a compact recompile is ONE named hash move (batched with minify + locale-strip).
+  if (opts.compact) {
+    return `#usda 1.0
+(
+    customData = {
+        string nomos:format = "${NOMOS_DOMAIN_PACKAGE_FORMAT}"
+    }
+)
+
+def "NomosDomainPackage"
+{
+    custom string nomos:usdJsonB64 = "${Buffer.from(usdJson, "utf8").toString("base64")}"
+    custom string nomos:executable:language = "javascript"
+    custom string nomos:executable:javascriptB64 = "${Buffer.from(javascript, "utf8").toString("base64")}"
+}
+`;
+  }
   return `#usda 1.0
 (
     customData = {

package/src/check_package_main.ts

@@ -0,0 +1,83 @@
+// 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 check` — the author-time gate as a standalone command
+ * (architecture/author_time_gate.md, slice 1). Loads `nomos.package.mjs`, composes each
+ * domain the SAME way `compile` does (`composeDomainModule` — the one owner of directive
+ * 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 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";
+
+interface DomainConfig {
+  key: string;
+  name?: string;
+  modules: string[];
+}
+interface PackageConfig {
+  name: string;
+  domains: DomainConfig[];
+}
+
+function fail(msg: string): never {
+  console.error(`githolon check: ${msg}`);
+  process.exit(2);
+}
+
+/**
+ * Compose the package's domain modules from `nomos.package.mjs` — the check-time subset of what
+ * `compile_package_main` does: import the config, import each domain's TS modules, and hand them to
+ * `composeDomainModule` (the shared composition primitive that discovers directives/aggregates and
+ * applies the secondary-ensure auto-declare). Returns the composed modules ready for the twins.
+ */
+export async function loadComposedModules(configArg: string): Promise<DomainModule[]> {
+  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 };
+  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[] = [];
+  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[] = [];
+    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);
+    }
+    composed.push(composeDomainModule({ name: d.name ?? d.key, domain: d.key, modules: mods }));
+  }
+  return composed;
+}
+
+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);
+
+  console.log(`githolon check: ${findings.length} finding(s)`);
+  for (const line of formatFindings(findings)) {
+    const level = line.includes("REFUSE") ? "  ✗ " : line.includes("WARN") ? "  ⚠ " : "  • ";
+    console.log(level + line);
+  }
+  if (findings.length === 0) console.log("  all clear — no static twin flagged anything");
+
+  process.exit(hasRefusal(findings) ? 1 : 0);
+}
+
+void main();

package/src/codegen_dart.ts

@@ -2985,6 +2985,14 @@ export interface DomainModule {
   domain?: string;
   aggregates: AggregateHandle[];
   directives: AnyDirective[];
+  /**
+   * SECONDARY-CREATE AUTO-DECLARE (secondary_ensure.ts) — the aggregate TYPES whose deterministic
+   * secondary `ensure(...)` `composeDomainModule` plan-probed and SANCTIONED by injecting a no-op
+   * `.ensures(Type)` directive into {@link directives}. Diagnostic metadata for the compile summary
+   * ONLY — NOT law, NOT hashed (the manifest reads named fields; this one is not among them). Absent
+   * when the domain has no unsanctioned secondary ensure (the common case).
+   */
+  autoDeclaredEnsures?: string[];
   /**
    * STABLE-ID CONTINUITY (#58 — names are labels, identity is minted). When present
    * (attached by `nomos-compile` from the PRIOR build's identity manifests), the