@githolon/dsl 0.49.0 → 0.51.0

package/src/check_package_main.ts

@@ -0,0 +1,194 @@
+// 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, 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, type Finding } from "./law_check.js";
+import {
+  currentEvolveLaw,
+  evolveDiff,
+  evolveLawFromDeployJson,
+  evolveLawFromLockfile,
+  type EvolveLaw,
+  type StableIdLockfile,
+} from "./evolve_preview.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;
+}
+
+/**
+ * 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);
+  // 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 modules = await loadComposedModules(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) {
+      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) 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;
+    console.log(`githolon check: evolve preview against ${prior.source}`);
+  }
+
+  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");
+
+  // 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);
+}
+
+void main();

package/src/codegen_dart_client.ts

@@ -36,7 +36,7 @@ import type { DomainModule } from "./codegen_dart.js";
 import { cap, readModelClassName } from "./codegen_dart.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
-import { autoStampFields } from "./codegen_ts.js";
+import { autoStampFields, domainEncryptionMap, type EncDomainMap, type InterfaceAggShape } from "./codegen_ts.js";
 
 const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
 const lcFirst = (s: string) => (s.length ? s[0]!.toLowerCase() + s.slice(1) : s);
@@ -127,6 +127,33 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   const aggById = new Map<string, AggregateHandle>();
   for (const a of mod.aggregates) aggById.set(a.id, a);
 
+  // THE E2E-SEALING MAP (the sealing client) — non-null iff a field is `.encrypted()`. When null NOTHING
+  // below emits (the generated Dart client is byte-identical to a pre-sealing compile). Same map + sids as
+  // the TS client (one source of truth: `domainEncryptionMap`); requires the baked interface for the sids.
+  const encMap: EncDomainMap | null =
+    opts.interface !== undefined
+      ? domainEncryptionMap(mod, opts.interface as { aggregates?: Record<string, InterfaceAggShape> })
+      : null;
+  const encPresent = encMap !== null;
+  /** The distinct scopes a read of `typeId` must inject keys for (empty ⇒ nothing encrypted on it). */
+  const readScopesFor = (typeId: string): string[] => {
+    const r = encMap?.reads?.[typeId];
+    return r === undefined ? [] : [...new Set(Object.values(r).map((x) => x.scope))].sort();
+  };
+  const keysArg = (typeId: string): string => {
+    const scopes = readScopesFor(typeId);
+    return scopes.length ? `, await _readKeys([${scopes.map((s) => dartStr(s)).join(", ")}])` : "";
+  };
+  // The DISTINCT encryption scopes this domain defines (across encrypted reads + sealing directives) — the
+  // set the owner ceremony rotates. Empty ⇒ no `encryption` getter is emitted for this domain.
+  const domScopes: string[] = (() => {
+    if (encMap === null) return [];
+    const s = new Set<string>();
+    for (const r of Object.values(encMap.reads)) for (const f of Object.values(r)) s.add(f.scope);
+    for (const dir of Object.values(encMap.directives)) for (const f of Object.values(dir)) s.add(f.scope);
+    return [...s].sort();
+  })();
+
   const methods: string[] = [];
 
   // ── directives → typed offer ──
@@ -148,6 +175,34 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const gateDoc = gate !== undefined
       ? `  /// GATED: needs an \`actor\` (the \`${gate.relation}\` relation) — throws MissingOfferAuthority otherwise.`
       : "";
+    // E2E SEALING (the sealing client): a directive with `.encrypted()` payload fields SEALS them via the
+    // bound [keyStore] before dispatch (a missing key throws [EncryptionKeyUnavailable] — never a plaintext
+    // write). One async block covers creates + mutate + gated + stamps; `seal: false` is the escape hatch.
+    if (encMap?.directives?.[d.id] !== undefined) {
+      const isCreates = (d as { marker?: string }).marker === "creates";
+      const retType = isCreates ? "NomosOfferOutcome" : "String";
+      const offerFn = isCreates ? "offerCreates" : "offerDirective";
+      methods.push(
+        `  /// Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head.`,
+        `  /// Encrypted field(s) are SEALED via the bound [keyStore] before dispatch (pass \`seal: false\` to skip).`,
+        ...(stamps.length > 0 ? [`  /// Omitted ${stamps.map((s) => `\`${s}\``).join(" / ")} auto-stamp(s) ISO now() at offer.`] : []),
+        ...(gateDoc ? [gateDoc] : []),
+        `  Future<${retType}> ${method}(${payloadClass} payload, {bool seal = true}) async {`,
+        ...(gateGuard ? [gateGuard] : []),
+        `    final data = payload.toPayloadJson();`,
+        ...(stamps.length > 0
+          ? [
+              `    final now = DateTime.now().toUtc().toIso8601String();`,
+              ...stamps.map((s) => `    data.putIfAbsent(${dartStr(s)}, () => now);`),
+            ]
+          : []),
+        `    await _sealPayload(data, ${dartStr(d.id)}, seal);`,
+        `    return bridge.${offerFn}(domain: ${dartStr(domain)}, directiveId: ${dartStr(d.id)}, payload: data, actor: actor, domainHash: domainHash);`,
+        `  }`,
+        ``,
+      );
+      continue;
+    }
     if ((d as { marker?: string }).marker === "creates") {
       // LAW-MINTED ID RETURN: a `.creates` plan mints its aggregate id inside the sealed intent (the payload
       // carries none — callers never supply ids). The bridge's offerCreates hands the minted ids back with the
@@ -213,9 +268,9 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const argMap = `{${q.key.map((k) => `${dartStr(k)}: ${dartKeyParam(k)}`).join(", ")}}`;
     const m = safeMethod(lcFirst(camel(q.id)));
     methods.push(
-      `  /// Declared query \`${q.id}\` (indexed probe — routed by the read manifest).`,
+      `  /// Declared query \`${q.id}\` (indexed probe — routed by the read manifest).${readScopesFor(q.returns).length ? " Encrypted field(s) decrypt when the bound [keyStore] holds the scope key; else they stay opaque envelopes." : ""}`,
       `  Future<List<${model}>> ${m}({${params}}) async =>`,
-      `      (await bridge.query(${dartStr(q.id)}, ${argMap})).map((r) => ${rowToModel(model, "r")}).toList();`,
+      `      (await bridge.query(${dartStr(q.id)}, ${argMap}${keysArg(q.returns)})).map((r) => ${rowToModel(model, "r")}).toList();`,
       ``,
       `  /// Reactive \`${q.id}\` — re-emits on every local change (cancel the subscription to stop).`,
       `  Stream<List<${model}>> watch${cap(camel(q.id))}({${params}}) =>`,
@@ -267,9 +322,9 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     const lc = lcFirst(camel(agg.id));
     const Cap = cap(camel(agg.id));
     methods.push(
-      `  /// Read one ${agg.id} by aggregate id.`,
+      `  /// Read one ${agg.id} by aggregate id.${readScopesFor(agg.id).length ? " Encrypted field(s) decrypt when the bound [keyStore] holds the scope key." : ""}`,
       `  Future<List<${model}>> ${safeMethod(`${lc}ById`)}(String id) async =>`,
-      `      (await bridge.queryById(id)).map((r) => ${rowToModel(model, "r")}).toList();`,
+      `      (await bridge.queryById(id${keysArg(agg.id)})).map((r) => ${rowToModel(model, "r")}).toList();`,
       ``,
       `  /// Watch one ${agg.id} by aggregate id (local reactive read).`,
       `  Stream<List<${model}>> watch${Cap}ById(String id) =>`,
@@ -277,7 +332,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
       ``,
       `  /// Every ${agg.id} (the type-index probe — O(result), not a scan).`,
       `  Future<List<${model}>> ${safeMethod(`list${Cap}s`)}() async =>`,
-      `      (await bridge.query('aggregatesByType', {'__type': ${dartStr(agg.id)}})).map((r) => ${rowToModel(model, "r")}).toList();`,
+      `      (await bridge.query('aggregatesByType', {'__type': ${dartStr(agg.id)}}${keysArg(agg.id)})).map((r) => ${rowToModel(model, "r")}).toList();`,
       ``,
     );
   }
@@ -305,7 +360,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `// client file gives an app the whole typed surface.`,
     `export '${mod.name}.dart';`,
     ...(opts.frameworkImportUri !== undefined ? [`export '${opts.frameworkImportUri}';`] : []),
-    `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion;`,
+    `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion${encPresent ? ", NomosScopeKey, NomosKeyStore, EncryptionKeyUnavailable, WrappedKeyStore, NomosEncryption, NomosEpochResult, EncryptionMemberKeyMissing, EncryptionRosterMismatch" : ""};`,
     ``,
     `/// sha256 of the deployed \`.package.usda\` — the installed law this client offers under.`,
     `const String ${hashConst} = ${dartStr(opts.domainHash)};`,
@@ -344,8 +399,30 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     `  /// The verified principal uid every offer is authored as (sealed as \`security.actor\` by the one encoder).`,
     `  /// Null ⇒ open (un-gated) authoring; a gated directive then throws [MissingOfferAuthority].`,
     `  final String? actor;`,
-    `  ${className}(this.bridge, {this.domainHash = ${hashConst}, this.actor});`,
+    ...(encPresent
+      ? [
+          ``,
+          `  /// THE KEY CUSTODY surface (E2E sealing). When set, encrypted directive fields SEAL automatically`,
+          `  /// before dispatch and encrypted read fields DECRYPT automatically; null ⇒ ciphertext passes through`,
+          `  /// unchanged (today's behavior). See [WrappedKeyStore] for the default over the on-chain WrappedKeys.`,
+          `  final NomosKeyStore? keyStore;`,
+        ]
+      : []),
+    `  ${className}(this.bridge, {this.domainHash = ${hashConst}, this.actor${encPresent ? ", this.keyStore" : ""}});`,
     ``,
+    ...(encPresent ? dartEncClassMembers(encMap!) : []),
+    // THE OWNER CEREMONY (slice 2): grantAndWrap / revokeAndRotate / rotate — the operator-blind key-epoch
+    // handshake as one call. Bind `actor` (the owner) to author the fan-out. Only for a domain with a scope.
+    ...(domScopes.length > 0
+      ? [
+          `  /// OWNER CEREMONY (slice 2): \`grantAndWrap\` / \`revokeAndRotate\` / \`rotate\` — the operator-blind`,
+          `  /// key-epoch handshake as one call. Bind \`actor\` (the owner) to author the fan-out.`,
+          `  NomosEncryption get encryption => NomosEncryption(`,
+          `      bridge: bridge, domain: ${dartStr(domain)}, domainHash: domainHash, actor: actor,`,
+          `      scopes: const [${domScopes.map((s) => dartStr(s)).join(", ")}]);`,
+          ``,
+        ]
+      : []),
     ...(opts.interface !== undefined
       ? [
           `  /// This client's structural interface requirement (#72) as JSON — hand it to the`,
@@ -370,3 +447,42 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     ``,
   ].join("\n");
 }
+
+/** The in-class E2E-sealing members: the baked map + the seal/read private helpers. */
+function dartEncClassMembers(encMap: EncDomainMap): string[] {
+  return [
+    `  /// The baked E2E-sealing map (compile-time, from the SAME sids the law was compiled with): which`,
+    `  /// directive payload fields seal → { scope, aggSid, fieldSid }, and which read-model fields decrypt.`,
+    `  static final Map<String, dynamic> encryptionMap = (jsonDecode(${dartRawJson(encMap)}) as Map).cast<String, dynamic>();`,
+    ``,
+    `  /// Seal the mapped encrypted fields of \`data\` in place before dispatch. No keyStore / \`seal == false\``,
+    `  /// ⇒ passthrough (today's behavior); a held key seals; a missing key throws [EncryptionKeyUnavailable].`,
+    `  Future<void> _sealPayload(Map<String, dynamic> data, String directiveId, bool seal) async {`,
+    `    if (!seal || keyStore == null) return;`,
+    `    final fields = (encryptionMap['directives'] as Map)[directiveId] as Map?;`,
+    `    if (fields == null) return;`,
+    `    for (final entry in fields.entries) {`,
+    `      final field = entry.key as String;`,
+    `      final m = entry.value as Map;`,
+    `      if (data[field] == null) continue;`,
+    `      final scope = m['scope'] as String;`,
+    `      final sk = await keyStore!.scopeKey(scope);`,
+    `      if (sk == null) throw EncryptionKeyUnavailable(scope, field);`,
+    `      data[field] = await bridge.cryptoSealField(`,
+    `        scopeKey: sk.key, scope: scope, epoch: sk.epoch,`,
+    `        aggSid: m['aggSid'] as String, fieldSid: m['fieldSid'] as String,`,
+    `        plaintext: data[field].toString(),`,
+    `      );`,
+    `    }`,
+    `  }`,
+    ``,
+    `  /// The read keys to inject for \`scopes\`, or null when there is nothing to inject (no keyStore / no`,
+    `  /// held keys) — the read then behaves exactly as today (encrypted fields stay opaque envelopes).`,
+    `  Future<List<NomosScopeKey>?> _readKeys(List<String> scopes) async {`,
+    `    if (keyStore == null || scopes.isEmpty) return null;`,
+    `    final keys = await keyStore!.readKeys(scopes);`,
+    `    return keys.isEmpty ? null : keys;`,
+    `  }`,
+    ``,
+  ];
+}

package/src/codegen_proof.ts

@@ -1384,7 +1384,7 @@ export interface ChildBirthParentSetup {
 /** A stub `nomos` global (mint + sha256) so a `.births()` plan that mints / hashes a child name runs to
  *  completion at codegen. The hash is a deterministic STUB (the codegen never needs the real digest — the
  *  recipe's workspace is read at RUNTIME from the offer's `born`); mint mirrors `harvestPrincipalFlows`. */
-function withBirthProbeGlobals<T>(run: () => T): T {
+export function withBirthProbeGlobals<T>(run: () => T): T {
   const g = globalThis as unknown as { nomos?: { mint?: (t: string) => string; sha256?: (s: string) => string; read?: unknown } };
   const had = "nomos" in g;
   const prior = g.nomos;