@githolon/dsl 0.49.0 → 0.51.0

package/src/law_check.ts

@@ -0,0 +1,777 @@
+// 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 AUTHOR-TIME GATE — `githolon check` (architecture/author_time_gate.md, slice 1).
+ *
+ * Every DX bug the tenant teams reported was the same disease: the kernel gate refused
+ * something at RUNTIME that was STATICALLY VISIBLE at compile. The cure is to pre-fire
+ * the refusal at author time, with the FIX inside the message. This module is the
+ * unified surface: it runs the STATIC TWINS of the gate's refusal vocabulary over the
+ * composed domain modules and returns typed {@link Finding}s.
+ *
+ * Three verdict levels:
+ *   - **refuse** — the fault is PAYLOAD-INDEPENDENT (return shape, schema/driver mismatch),
+ *     so the runtime gate WILL refuse it. `githolon check` exits non-zero; `compile` refuses.
+ *   - **warn** — the probe SAW something suspicious but can't PROVE it (a plan that threw on
+ *     the one synthesized sample — a conditional/payload-dependent path). Names the payload.
+ *   - **note** — an auto-repair was applied (e.g. the auto-declared secondary ensure).
+ *
+ * FALSE-POSITIVE DISCIPLINE (the hard rule, from the design doc): the probe runs ONE
+ * synthesized payload — a conditional branch it doesn't take proves nothing. A twin may
+ * REFUSE only when the fault is payload-independent; everything else is a WARN naming the
+ * payload that exhibited it. The runtime gate remains the arbiter; `check` never claims
+ * completeness, only that what it flags is real.
+ */
+import { z } from "zod";
+
+import type { AggregateHandle } from "./aggregate.js";
+import type { Directive } from "./directive.js";
+import type { DomainModule } from "./codegen_dart.js";
+import type { Field } from "./fields.js";
+import type { FieldOp, PlannedOp } from "./ops.js";
+import { deterministicPorts } from "./ctx.js";
+import { synthesizePayload, withBirthProbeGlobals, type SynthesizedPayload } from "./codegen_proof.js";
+import { __drainAuthoring, __resetAuthoring } from "./authoring.js";
+import { __drainReads, __resetReads } from "./read.js";
+import { __drainBirths, __resetBirths } from "./births.js";
+import { proofLegsIndex } from "./codegen_proof.js";
+import { autoStampFields, zodKind, zodObjectShape } from "./codegen_ts.js";
+import { finishCount } from "./count.js";
+import { finishSum } from "./sum.js";
+import { finishExtremum } from "./extremum.js";
+import { finishExists } from "./exists.js";
+
+/** One author-time finding — the gate refusal pre-fired at compile, or a courtesy note. */
+export interface Finding {
+  /** The domain key the directive lives in. */
+  readonly domain: string;
+  /** The directive the finding is about (absent for a domain-wide note). */
+  readonly directiveId?: string;
+  /** `refuse` — provably refuses at the gate · `warn` — suspicious, can't prove · `note` — auto-repair. */
+  readonly level: "refuse" | "warn" | "note";
+  /** What is wrong (or, for a note, what was auto-repaired). */
+  readonly what: string;
+  /** How to fix it (or, for a note, how the repair keeps the law valid). */
+  readonly fix: string;
+}
+
+/** Payload field names the FRAMEWORK consumes off the intent (never the plan) — excluded from the
+ *  unread-payload-field warn so a birth/timestamp convention field is never falsely flagged as dead.
+ *  Sources: `autoStampFields` (the `…At` clock convention) + `birthMeterSubject`/`birthMeterBornAt`. */
+const FRAMEWORK_CONSUMED_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
+  "principal",
+  "owner",
+  "ownerSubject",
+  "bornAt",
+  "requestedAt",
+]);
+
+/** The outcome of running one directive's plan on its synthesized sample under the probe globals. */
+interface ProbeResult {
+  readonly synth: SynthesizedPayload;
+  /** The stamped-and-filled sample the plan was run with (what a WARN names). */
+  readonly probePayload: Record<string, unknown>;
+  /** The plan's RETURN value (whatever it was — checked for array-ness by the return twin). */
+  readonly returned: unknown;
+  /** True when the plan THREW on the sample (payload-dependent — everything degrades to a WARN). */
+  readonly threw: boolean;
+  readonly error?: unknown;
+  /** The FIELD ops the plan emitted (authoring sink + returned ops), when it didn't throw. */
+  readonly ops: FieldOp[];
+  /** The top-level payload keys the plan actually READ (via the tracking proxy). */
+  readonly readFields: ReadonlySet<string>;
+}
+
+/** Run a directive's plan ONCE on a tracking-proxy sample under the birth-probe globals, capturing the
+ *  return value, whether it threw, the emitted field ops, and which payload fields it read. `undefined`
+ *  ⇒ the payload is unsynthesizable (an exotic zod shape) — the directive can't be probed at all. */
+function probeDirective(dir: Directive<unknown>, where: string): ProbeResult | undefined {
+  let synth: SynthesizedPayload;
+  try {
+    synth = synthesizePayload(dir.payloadSchema as z.ZodTypeAny, where);
+  } catch {
+    return undefined;
+  }
+  // Build the sample: required non-stamped fields from the synth, plus the auto-stamped `…At` fields
+  // filled with a fixed ISO stamp (the client stamps them at dispatch; the plan may read them here).
+  const probePayload: Record<string, unknown> = { ...synth.value };
+  for (const f of synth.autoStamped) probePayload[f] = "2026-01-01T00:00:00Z";
+
+  const shapeKeys = new Set(Object.keys(safeShape(dir.payloadSchema as z.ZodTypeAny)));
+  const readFields = new Set<string>();
+  const tracked = new Proxy(probePayload, {
+    get(target, prop, recv) {
+      if (typeof prop === "string" && shapeKeys.has(prop)) readFields.add(prop);
+      return Reflect.get(target, prop, recv);
+    },
+  });
+
+  let returned: unknown;
+  let threw = false;
+  let error: unknown;
+  let ops: FieldOp[] = [];
+  withBirthProbeGlobals(() => {
+    __resetAuthoring();
+    __resetReads();
+    __resetBirths();
+    try {
+      returned = dir.plan(tracked as never, deterministicPorts({ physical: 1, replica: 1, principal: "principal:probe" }));
+      const drained: PlannedOp[] = [...__drainAuthoring(), ...(Array.isArray(returned) ? returned : [])];
+      ops = drained.filter((o): o is FieldOp => (o as { kind?: string }).kind !== "strike");
+    } catch (e) {
+      threw = true;
+      error = e;
+    } finally {
+      // Drain the sinks on every path so a throwing probe never leaks state into the next.
+      try { __drainAuthoring(); } catch { /* drained */ }
+      try { __drainReads(); } catch { /* drained */ }
+      try { __drainBirths(); } catch { /* drained */ }
+    }
+  });
+  return { synth, probePayload, returned, threw, error, ops, readFields };
+}
+
+/** `zodObjectShape` with a swallow — a non-object payload yields `{}` (the return twin handles it). */
+function safeShape(schema: z.ZodTypeAny): Record<string, z.ZodTypeAny> {
+  try {
+    if (zodKind(schema) !== "object") return {};
+    return zodObjectShape(schema);
+  } catch {
+    return {};
+  }
+}
+
+/** The REQUIRED top-level payload fields (optional/defaulted omitted — an unread optional proves nothing). */
+function requiredPayloadFields(schema: z.ZodTypeAny): string[] {
+  const out: string[] = [];
+  for (const [name, f] of Object.entries(safeShape(schema))) {
+    const k = zodKind(f);
+    if (k === "optional" || k === "default") continue;
+    out.push(name);
+  }
+  return out;
+}
+
+/** A short, safe render of the sample payload a WARN names (bounded so a huge payload doesn't flood). */
+function samplePayloadText(payload: Record<string, unknown>): string {
+  let s: string;
+  try {
+    s = JSON.stringify(payload);
+  } catch {
+    s = "<unserializable>";
+  }
+  return s.length > 200 ? `${s.slice(0, 197)}…` : s;
+}
+
+// ── SLICE 2 — the DELETED-AMBIENT twin (crypto/fetch/setTimeout/… → refuse) ────────
+// The sealed sandbox HARDENs `globalThis` by ALLOWLIST-DELETE (deterministic-rquickjs/src/lib.rs
+// `HARDEN`): it keeps ONLY the pure ECMAScript surface + `__ports`, and DELETES everything else.
+// A plan that references one of those deleted ambients runs fine in NODE (where the probe lives —
+// `crypto`/`fetch`/`setTimeout`/… all exist), so the ordinary probe never sees it, but throws
+// "'<X>' is not defined" at the FIRST dispatch on every peer. So we run the plan a SECOND time with
+// those globals shadowed by THROWING stubs and catch the marker — a reference UNCONDITIONAL on the
+// sample path is payload-independent ⇒ REFUSE (a branch the sample doesn't take never fires the
+// stub ⇒ no finding, the hard rule). Date/Math stay REAL: `Date.now()`/`new Date()`/`Math.random()`
+// are LEGAL (shimmed to the captured ports — deterministic by design), NOT deleted.
+//
+// The list is DERIVED from HARDEN's excluded-by-omission set (the `HARDEN` doc-comment enumerates
+// it), restricted to the names that (a) EXIST in Node — so the ordinary probe can't catch them —
+// and (b) a plan could plausibly reach for. `console` is deliberately EXCLUDED: internal DSL/probe
+// code may log, which would be a false REFUSE, and the doc's list doesn't name it. So are the names
+// Node/undici touch INTERNALLY (`queueMicrotask`/`setImmediate`/`Intl`/`structuredClone`/`Text*`) —
+// stubbing them risks perturbing Node's own machinery. QuickJS-only globals (`os`/`std`/`print`/
+// `scriptArgs`) are absent in Node too, so a plan using them already throws in the ordinary probe
+// (twin A WARNs it) — no stub needed.
+const DELETED_AMBIENT_ALTERNATIVE: Readonly<Record<string, string>> = {
+  crypto:
+    "randomness rides the captured ports — `Math.random()` is shimmed to the deterministic captured draws; a random id comes from Nomos minting it (`create(Agg)` mints)",
+  performance:
+    "time rides the captured ports — `Date.now()` / `new Date()` are shimmed to the deterministic captured clock; use those, or carry an ISO timestamp IN the payload",
+  fetch:
+    "network never happens in a plan (it must be a pure function of (payload, ports)) — carry the data IN the payload, or read it via a declared read() (`.reads(theQuery)`)",
+  XMLHttpRequest:
+    "network never happens in a plan — carry the data IN the payload, or read it via a declared read() (`.reads(theQuery)`)",
+  WebSocket:
+    "network never happens in a plan — carry the data IN the payload, or read it via a declared read() (`.reads(theQuery)`)",
+  setTimeout: "a plan is synchronous + deterministic — there are no timers; compute the value inline",
+  clearTimeout: "a plan is synchronous + deterministic — there are no timers; compute the value inline",
+  setInterval: "a plan is synchronous + deterministic — there are no timers; compute the value inline",
+  clearInterval: "a plan is synchronous + deterministic — there are no timers; compute the value inline",
+  process: "there is no host/OS ambient in the sandbox — carry any config IN the payload",
+  require: "there are no modules in the sandbox — the plan is a self-contained pure function",
+};
+const DELETED_AMBIENTS: readonly string[] = Object.keys(DELETED_AMBIENT_ALTERNATIVE);
+
+/** The marker a shadowed ambient throws when the plan USES it — carries the name so the twin can name
+ *  it (and its captured alternative). */
+function deletedAmbientMarker(name: string): Error {
+  return Object.assign(new Error(`the sealed sandbox removes '${name}'`), { nomosDeletedAmbient: name });
+}
+
+/** A stub VALUE for a deleted ambient: a Proxy that is INERT when merely held or read as a binding
+ *  (so Node/DSL internals that pass the reference around stay functional) but throws its marker the
+ *  instant a PLAN actually USES it — a property access (`crypto.randomUUID`, `performance.now`,
+ *  `process.env`), a call (`fetch(...)`, `setTimeout(...)`, `require(...)`), or a construct
+ *  (`new WebSocket(...)`). This is the whole realistic surface by which a plan reaches an ambient;
+ *  a bare unused `const c = crypto` is under-detected on purpose (the runtime gate stays the arbiter),
+ *  the safe trade for never poisoning Node internals. Symbol reads return `undefined` so util.inspect /
+ *  thenable probing can't trip it. */
+function deletedAmbientStub(name: string): unknown {
+  const target = function () {} as unknown as object;
+  return new Proxy(target, {
+    get(_t, prop) {
+      if (typeof prop === "symbol") return undefined;
+      throw deletedAmbientMarker(name);
+    },
+    apply() {
+      throw deletedAmbientMarker(name);
+    },
+    construct() {
+      throw deletedAmbientMarker(name);
+    },
+  });
+}
+
+/** Run `run()` (the SYNCHRONOUS plan call only) with every {@link DELETED_AMBIENTS} name shadowed by a
+ *  {@link deletedAmbientStub} data-property on `globalThis`, restored in a `finally` on the SAME tick —
+ *  never across an await/module-load boundary (the teammate's bug: a stub visible during Node's lazy
+ *  undici load). Because the stub is inert unless USED, and this window is one synchronous plan call,
+ *  Node internals never trip it. Restores the exact prior descriptors on every path. */
+function withDeletedAmbientStubs<T>(run: () => T): T {
+  const g = globalThis as unknown as Record<string, unknown>;
+  // PRE-MATERIALIZE (with NO stub installed yet — so nothing here can throw a marker). Node defines
+  // `fetch`/`performance`/`crypto` as LAZY globals that materialize — and pull in undici, which reads
+  // `performance` — on first access, AND (Node 25) even on a `getOwnPropertyDescriptor` query. Forcing
+  // each to a concrete value NOW, before any shadow, means the descriptor-capture + the sync plan run
+  // below never trigger a lazy load: the stub window stays synchronous and load-free (the teammate's
+  // bug was a stub visible during that undici load — this keeps the load strictly before the window).
+  for (const name of DELETED_AMBIENTS) {
+    try {
+      void g[name];
+    } catch {
+      /* a global that throws on plain read — nothing to pre-materialize */
+    }
+  }
+  const prior = new Map<string, PropertyDescriptor | undefined>();
+  for (const name of DELETED_AMBIENTS) {
+    prior.set(name, Object.getOwnPropertyDescriptor(g, name));
+    try {
+      Object.defineProperty(g, name, { configurable: true, writable: true, value: deletedAmbientStub(name) });
+    } catch {
+      // A non-configurable global can't be shadowed — leave it (the ordinary probe still runs).
+      prior.delete(name);
+    }
+  }
+  try {
+    return run();
+  } finally {
+    for (const [name, desc] of prior) {
+      try {
+        if (desc === undefined) delete g[name];
+        else Object.defineProperty(g, name, desc);
+      } catch {
+        /* best-effort restore */
+      }
+    }
+  }
+}
+
+/** Re-run the directive's plan on its synthesized sample with the deleted ambients shadowed; return the
+ *  ambient name the plan READ on the sample path, or `undefined`. Inconclusive when the ordinary probe
+ *  already threw (a broken sample path proves nothing about the ambient reference). */
+function probeDeletedAmbient(dir: Directive<unknown>, probe: ProbeResult): string | undefined {
+  if (probe.threw) return undefined;
+  let hit: string | undefined;
+  withBirthProbeGlobals(() => {
+    withDeletedAmbientStubs(() => {
+      __resetAuthoring();
+      __resetReads();
+      __resetBirths();
+      try {
+        dir.plan(
+          probe.probePayload as never,
+          deterministicPorts({ physical: 1, replica: 1, principal: "principal:probe" }),
+        );
+      } catch (e) {
+        const name = (e as { nomosDeletedAmbient?: unknown } | null)?.nomosDeletedAmbient;
+        if (typeof name === "string") hit = name;
+        // A non-marker throw is a payload-dependent branch (twin A already WARNs it) — ignore.
+      } finally {
+        try { __drainAuthoring(); } catch { /* drained */ }
+        try { __drainReads(); } catch { /* drained */ }
+        try { __drainBirths(); } catch { /* drained */ }
+      }
+    });
+  });
+  return hit;
+}
+
+// ── TWIN 1 (slice 2) — the DELETED-AMBIENT refusal ────────────────────────────────
+function deletedAmbientFindings(domain: string, dir: Directive<unknown>, probe: ProbeResult): Finding[] {
+  const name = probeDeletedAmbient(dir, probe);
+  if (name === undefined) return [];
+  return [
+    {
+      domain,
+      directiveId: dir.id,
+      level: "refuse",
+      what: `the plan references '${name}', which the sealed sandbox REMOVES (HARDEN allowlist-delete) — it would throw "'${name}' is not defined" at the first dispatch on every peer`,
+      fix: DELETED_AMBIENT_ALTERNATIVE[name] ?? "the sandbox keeps only the pure ECMAScript surface + the captured ports — carry data IN the payload or via declared reads",
+    },
+  ];
+}
+
+// ── TWIN A — the UNIVERSAL plan-return probe ──────────────────────────────────────
+// The engine assembles a plan's output with `[...returned]` (wire_encode.ts). A plan whose
+// `plan` returns a NON-ITERABLE (undefined — a forgotten `return`; a builder — a forgotten
+// `return []` after `create(...).set(...)`; a plain object) throws "not iterable" at the FIRST
+// dispatch on every peer. This is payload-INDEPENDENT (the return TYPE is fixed) ⇒ REFUSE.
+// A plan that THREW on the sample is payload-DEPENDENT (can't prove) ⇒ WARN naming the sample.
+function planReturnFindings(domain: string, dir: Directive<unknown>, probe: ProbeResult): Finding[] {
+  if (probe.threw) {
+    return [
+      {
+        domain,
+        directiveId: dir.id,
+        level: "warn",
+        what: `the plan THREW on the synthesized sample (${(probe.error as Error)?.message ?? String(probe.error)}) — can't prove the return shape`,
+        fix: `run it on the sample ${samplePayloadText(probe.probePayload)} — if the throw is real, the runtime gate refuses; if it's a payload-dependent branch, ignore`,
+      },
+    ];
+  }
+  if (!Array.isArray(probe.returned)) {
+    const got =
+      probe.returned === undefined
+        ? "undefined (a missing `return`)"
+        : typeof probe.returned === "object" && probe.returned !== null
+          ? "an object/builder (a forgotten `return []`)"
+          : `a ${typeof probe.returned}`;
+    return [
+      {
+        domain,
+        directiveId: dir.id,
+        level: "refuse",
+        what: `the plan returns ${got}, not an array of ops — the engine assembles plan output with [...returned] and would throw "not iterable" at the first dispatch`,
+        fix: `return an array of ops — the fluent surface (create/set/add) records ops as a side-effect, so end the plan with \`return [];\` (or return the typed ops directly)`,
+      },
+    ];
+  }
+  return [];
+}
+
+// ── TWIN B — the UNREAD-PAYLOAD-FIELD warn ────────────────────────────────────────
+// A REQUIRED payload field the plan never reads on the sample path is usually a bug (dead field
+// or missing logic). WARN only (a conditional read the sample didn't reach proves nothing), and
+// only for a plan that ran cleanly (a throwing plan read nothing — twin A already flagged it).
+// Framework-consumed convention fields (auto-stamped `…At`, birth subject/time) are excluded.
+function unreadPayloadFindings(domain: string, dir: Directive<unknown>, probe: ProbeResult): Finding[] {
+  if (probe.threw) return [];
+  const stamped = new Set(autoStampFields(dir.payloadSchema as z.ZodTypeAny));
+  // The GATE reads some payload fields the PLAN never does: `.requires(rel, { objectFrom })` derives
+  // the gate object from a named payload id field (per-record authz). Excluding it keeps a real
+  // gate-consumed field from being flagged dead (the todo-pro `shareTodo.listId` case).
+  const gateConsumed = new Set<string>();
+  const objectFromField = (dir as { requiresRelationGate?: { objectFrom?: { idField?: string } } })
+    .requiresRelationGate?.objectFrom?.idField;
+  if (typeof objectFromField === "string") gateConsumed.add(objectFromField);
+  const out: Finding[] = [];
+  for (const f of requiredPayloadFields(dir.payloadSchema as z.ZodTypeAny)) {
+    if (probe.readFields.has(f)) continue;
+    if (stamped.has(f)) continue; // the client stamps it; the plan needn't read it
+    if (FRAMEWORK_CONSUMED_PAYLOAD_FIELDS.has(f)) continue; // the meter reads it off the intent
+    if (gateConsumed.has(f)) continue; // the authz gate derives its object from it
+    out.push({
+      domain,
+      directiveId: dir.id,
+      level: "warn",
+      what: `payload field '${f}' is never read by the plan (on the sampled path) — dead field or missing logic?`,
+      fix: `read it in the plan (e.g. \`.set("${f}", p.${f})\`), make it \`.optional()\` if it is genuinely optional, or drop it from the payload`,
+    });
+  }
+  return out;
+}
+
+// ── TWIN C — the OP-VS-SCHEMA / driver twin ───────────────────────────────────────
+// Walk the probed ops against the target aggregate's schema. An op on a field the aggregate
+// does NOT declare is a hard mismatch (REFUSE, naming the real fields). A `set` on an additive
+// set (AddWins/RemoveWins) OVERWRITES the CRDT instead of merging — REFUSE naming addToSet/
+// removeFromSet. A `setEntry` on a non-map field is likewise a driver mismatch. Conservative:
+// only ops targeting an aggregate THIS domain declares are judged (a foreign/framework tuple is
+// left to the runtime gate); every refusal here is a combination the engine provably rejects.
+function opVsSchemaFindings(
+  domain: string,
+  dir: Directive<unknown>,
+  probe: ProbeResult,
+  aggById: ReadonlyMap<string, AggregateHandle>,
+): Finding[] {
+  if (probe.threw) return [];
+  const out: Finding[] = [];
+  const seen = new Set<string>(); // dedupe identical (agg, field, kind) findings
+  for (const op of probe.ops) {
+    const aggId = op.aggregateType;
+    if (typeof aggId !== "string") continue;
+    const agg = aggById.get(aggId);
+    if (agg === undefined) continue; // foreign / framework aggregate — the runtime gate arbitrates
+    const key = `${aggId}.${op.field}.${op.kind}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const field = agg.fields[op.field] as Field | undefined;
+    if (field === undefined) {
+      const real = Object.keys(agg.fields).sort();
+      out.push({
+        domain,
+        directiveId: dir.id,
+        level: "refuse",
+        what: `the plan writes '${op.field}' on '${aggId}', which is not a declared field of that aggregate`,
+        fix: `write one of ${aggId}'s fields — ${real.length ? real.join(", ") : "(none)"} — or add '${op.field}' to the aggregate`,
+      });
+      continue;
+    }
+    const driverKind = (field.driver as { kind?: string }).kind;
+    if (op.kind === "set" && driverKind === "AddWins") {
+      out.push({
+        domain,
+        directiveId: dir.id,
+        level: "refuse",
+        what: `the plan \`set\`s '${op.field}' on '${aggId}', an AddWins set — set() OVERWRITES the merge (concurrent adds would be lost)`,
+        fix: `use \`addToSet(instance(${aggId}, id), "${op.field}", values)\` — the additive write that commutes`,
+      });
+    } else if (op.kind === "set" && driverKind === "RemoveWins") {
+      out.push({
+        domain,
+        directiveId: dir.id,
+        level: "refuse",
+        what: `the plan \`set\`s '${op.field}' on '${aggId}', a RemoveWins set — set() OVERWRITES the 2P-set CRDT`,
+        fix: `use \`addToSet(...)\` / \`removeFromSet(instance(${aggId}, id), "${op.field}", values)\` — the additive/tombstone writes`,
+      });
+    } else if (op.kind === "setEntry" && field.kind !== "map") {
+      out.push({
+        domain,
+        directiveId: dir.id,
+        level: "refuse",
+        what: `the plan \`setEntry\`s '${op.field}' on '${aggId}', a '${field.kind}' field — setEntry targets a map (MapOf) field only`,
+        fix: `write a t.map(...) field with setEntry, or use \`set(...)\` for the '${field.kind}' field '${op.field}'`,
+      });
+    }
+  }
+  return out;
+}
+
+// ── TWIN 4 (sealing slice 3) — GROUP/KEY BY an .encrypted() field REFUSES ──────────
+// An `.encrypted()` field is a ciphertext envelope on the wire; grouping or keying a read BY it
+// makes the PLAINTEXT public (the group key / index value leaks the very thing you sealed —
+// e2e_encryption.md's "METADATA IS PUBLIC" footgun). Every read decl that GROUPS or KEYS by a
+// field is checked against the target aggregate's `encryptedFields`: a hit is payload-independent
+// (a static declaration) ⇒ REFUSE. (Twin 4b — an `.encrypted()` field on a non-`requires()`
+// aggregate — is REFUSED earlier by `aggregate()` itself, before compose; a defensive re-check is
+// folded in below so the unified report names it too if the state is ever reached.)
+function encryptionGroupingFindings(mod: DomainModule, aggById: ReadonlyMap<string, AggregateHandle>): Finding[] {
+  const domain = mod.domain ?? mod.name;
+  const out: Finding[] = [];
+  const seen = new Set<string>();
+  const encryptedOf = (aggId: string): ReadonlySet<string> =>
+    new Set(aggById.get(aggId)?.encryptedFields ?? []);
+  const flag = (readKind: string, readId: string, aggId: string, field: string, verb: string): void => {
+    if (!encryptedOf(aggId).has(field)) return;
+    const key = `${readKind}:${readId}:${aggId}.${field}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({
+      domain,
+      directiveId: readId,
+      level: "refuse",
+      what: `the ${readKind} '${readId}' ${verb} by '${field}' on '${aggId}', an .encrypted() field — ${verb === "keys" ? "keying" : "grouping"} by a sealed field makes its plaintext PUBLIC (the ${verb === "keys" ? "index key" : "group key"} leaks what you encrypted)`,
+      fix: `${verb} by a PLAINTEXT field instead, or drop .encrypted() from '${field}' — you can't both seal a value and expose it as a ${verb === "keys" ? "read key" : "group"}`,
+    });
+  };
+
+  for (const q of mod.queries ?? []) for (const k of q.key) flag("query", q.id, q.returns, k, "keys");
+  for (const c of mod.counts ?? []) {
+    const d = finishCount(c);
+    if (d.by !== undefined) flag("count", d.id, d.of, d.by, "groups");
+  }
+  for (const s of mod.sums ?? []) {
+    const d = finishSum(s);
+    if (d.by !== undefined) flag("sum", d.id, d.of, d.by, "groups");
+  }
+  for (const m of mod.mins ?? []) {
+    const d = finishExtremum(m);
+    if (d.by !== undefined) flag("min", d.id, d.of, d.by, "groups");
+  }
+  for (const m of mod.maxes ?? []) {
+    const d = finishExtremum(m);
+    if (d.by !== undefined) flag("max", d.id, d.of, d.by, "groups");
+  }
+  for (const e of mod.exists_ ?? []) {
+    const d = finishExists(e);
+    if (d.by !== undefined) flag("exists", d.id, d.of, d.by, "groups");
+  }
+  for (const sp of mod.spatials ?? []) flag("spatial", sp.id, sp.of, sp.on, "keys");
+
+  // Twin 4b (defensive unify — normally pre-empted by aggregate()'s throw): an encrypted field on a
+  // non-private aggregate. Unreachable in practice (the aggregate never composes), kept for completeness.
+  for (const agg of mod.aggregates) {
+    if ((agg.encryptedFields?.length ?? 0) > 0 && agg.visibility === undefined) {
+      out.push({
+        domain,
+        level: "refuse",
+        what: `aggregate '${agg.id}' has .encrypted() field(s) ${(agg.encryptedFields ?? []).join(", ")} but is not private — the encryption scope IS the read scope`,
+        fix: `add { visibility: requires("<cap>") } to '${agg.id}' (or drop .encrypted())`,
+      });
+    }
+  }
+  return out;
+}
+
+// ── TWIN 3 (slice 2) — INVARIANT SAMPLE-PROBE (aggregate + workspace invariants) ────
+// An aggregate invariant (`aggregate(id, fields, { invariant })`) runs on every touching event; a
+// workspaceInvariant(id).on(dir).reads(...).assert(...) runs at the gate. We probe each like a plan:
+// synthesize a sample (the aggregate's fields for an aggregate invariant; the `on`-directive's payload
+// + a synthesized snapshot per declared ref for a workspace invariant) and run the predicate. A THROW
+// (not a `reject` verdict — a reject is legitimate law) is a predicate BUG ⇒ WARN naming the exact
+// sample serialized. NEVER a REFUSE (sample-dependent — a different input may not throw, the hard rule).
+
+/** Synthesize a plausible folded-snapshot for an aggregate from its stored fields' zod schemas.
+ *  `undefined` when the shape is unsynthesizable (an exotic field) — the predicate can't be probed. */
+function synthesizeSnapshot(agg: AggregateHandle, where: string): Record<string, unknown> | undefined {
+  try {
+    const shape: Record<string, z.ZodTypeAny> = {};
+    for (const [name, f] of Object.entries(agg.fields)) shape[name] = (f as Field).zod as z.ZodTypeAny;
+    return synthesizePayload(z.object(shape), where).value as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+function invariantFindings(mod: DomainModule, aggById: ReadonlyMap<string, AggregateHandle>): Finding[] {
+  const domain = mod.domain ?? mod.name;
+  const out: Finding[] = [];
+
+  // Aggregate invariants — probe the composed `invariant` fn on a synthesized snapshot.
+  for (const agg of mod.aggregates) {
+    if (typeof agg.invariant !== "function") continue;
+    const snap = synthesizeSnapshot(agg, `${domain}/${agg.id}#invariant`);
+    if (snap === undefined) continue; // unsynthesizable — proven by hand, not by check
+    try {
+      withBirthProbeGlobals(() => agg.invariant!(snap));
+    } catch (e) {
+      out.push({
+        domain,
+        level: "warn",
+        what: `aggregate '${agg.id}' invariant THREW on the synthesized snapshot (${(e as Error)?.message ?? String(e)}) — a predicate bug, or a payload-dependent path the sample happened to hit`,
+        fix: `run the invariant on the snapshot ${samplePayloadText(snap)} — if the throw is real, every touching event refuses; if it's a shape the real data never has, guard the predicate`,
+      });
+    }
+  }
+
+  // Workspace invariants — resolve the ref-set from a synthesized intent, synth a snapshot per ref,
+  // then run the predicate. A throw at either step (reads() or assert()) → WARN naming the input.
+  const dirById = new Map<string, Directive<unknown>>();
+  for (const d of mod.directives as Directive<unknown>[]) dirById.set(d.id, d);
+  for (const wi of mod.workspaceInvariants ?? []) {
+    // The `on` may be `<domain>.<Directive>` or a bare id — match the suffix.
+    const onId = wi.on.includes(".") ? wi.on.slice(wi.on.lastIndexOf(".") + 1) : wi.on;
+    const dir = dirById.get(wi.on) ?? dirById.get(onId);
+    let intent: Record<string, unknown> = {};
+    if (dir !== undefined) {
+      const probe = probeDirective(dir, `${domain}/${wi.id}#intent`);
+      if (probe !== undefined) intent = probe.probePayload;
+    }
+    const ctx = { intent, principal: "principal:probe", principalVerified: true } as const;
+    let threwAt: "reads" | "assert" | undefined;
+    let err: unknown;
+    let snapshots: Record<string, Record<string, unknown>> = {};
+    withBirthProbeGlobals(() => {
+      try {
+        const refs = wi.reads(ctx);
+        for (const r of refs) {
+          const targetAgg = aggById.get(r.aggregate);
+          const snap = targetAgg !== undefined ? synthesizeSnapshot(targetAgg, `${domain}/${wi.id}#${r.name}`) : undefined;
+          snapshots[r.name] = snap ?? {};
+        }
+      } catch (e) {
+        threwAt = "reads";
+        err = e;
+      }
+      if (threwAt === undefined) {
+        try {
+          wi.assert(snapshots, { ...ctx, reads: [] });
+        } catch (e) {
+          threwAt = "assert";
+          err = e;
+        }
+      }
+    });
+    if (threwAt !== undefined) {
+      out.push({
+        domain,
+        directiveId: wi.on,
+        level: "warn",
+        what: `workspace invariant '${wi.id}' ${threwAt === "reads" ? "reads()" : "assert()"} THREW on the synthesized sample (${(err as Error)?.message ?? String(err)}) — a predicate bug, or a payload-dependent path the sample hit`,
+        fix: `run it on intent=${samplePayloadText(intent)} snapshots=${samplePayloadText(snapshots)} — if the throw is real, the gate refuses on '${wi.on}'; if the sample's shape never occurs, guard the predicate`,
+      });
+    }
+  }
+  return out;
+}
+
+// ── TWIN 2 (slice 2) — TOP-LEVEL PORT-READ pool-eligibility WARN ───────────────────
+// A tenant MODULE whose TOP LEVEL reads the captured ports (`Date.now()`/`new Date()`/`Math.random()`
+// at module scope, not inside a plan) makes the built engine lump PRISTINE-POOL-INELIGIBLE
+// (deterministic-rquickjs's "boot-reads hole"): the resident-sandbox pool can't reuse it, so EVERY
+// dispatch pays a full boot. The tenant modules are imported at compose time — their top level runs
+// in Node BEFORE any probe — so this is caught by INSTRUMENTING the import: {@link recordTopLevelPortReads}
+// shims those three ambients to set a flag during the import and reports which module top levels read
+// them (the honest, reliable mechanism — a cache-busted re-eval or a built-lump scan would be heavier
+// and less faithful). `check_package_main` / `compile` wrap each tenant `import()` in it and pass the
+// offending DOMAIN keys here; the DomainModule itself carries no source, so absent that wiring (unit
+// tests) the twin is simply silent. WARN only — a boot cost, never a correctness fault.
+
+/** True iff `run()` (a tenant-module import) READS the captured ports at top level. Shims `Date.now`/
+ *  the no-arg `Date` ctor / `Math.random` to set a flag, then restores them. Call it AROUND each tenant
+ *  `await import(...)` in the check/compile lane; map a true result to the domain key and feed it to
+ *  {@link checkDomainModules}'s `portReadingDomains`. (Exported so the module-load lane can wrap it with
+ *  ONE additive call — no restructuring of the loader.) */
+export async function recordTopLevelPortReads<T>(run: () => Promise<T>): Promise<{ value: T; read: boolean }> {
+  let read = false;
+  const realNow = Date.now;
+  const realRandom = Math.random;
+  const RealDate = Date;
+  const ShimDate = function (this: unknown, ...args: unknown[]): unknown {
+    if (args.length === 0) read = true; // no-arg `new Date()` reads the wall clock == a port read
+    // Delegate to the real Date so the module still evaluates correctly.
+    return new (RealDate as unknown as new (...a: unknown[]) => object)(...args);
+  } as unknown as DateConstructor;
+  ShimDate.now = () => {
+    read = true;
+    return realNow.call(Date);
+  };
+  ShimDate.parse = RealDate.parse;
+  ShimDate.UTC = RealDate.UTC;
+  // `new ShimDate(...)` delegates to RealDate, so instances already carry RealDate.prototype; no
+  // need to reassign the (read-only) `prototype` slot on the function object.
+  try {
+    // eslint-disable-next-line no-global-assign
+    (globalThis as { Date: DateConstructor }).Date = ShimDate;
+    Date.now = () => {
+      read = true;
+      return realNow.call(RealDate);
+    };
+    Math.random = () => {
+      read = true;
+      return realRandom.call(Math);
+    };
+    const value = await run();
+    return { value, read };
+  } finally {
+    (globalThis as { Date: DateConstructor }).Date = RealDate;
+    Date.now = realNow;
+    Math.random = realRandom;
+  }
+}
+
+function topLevelPortReadFindings(mod: DomainModule, portReadingDomains: ReadonlySet<string>): Finding[] {
+  const domain = mod.domain ?? mod.name;
+  if (!portReadingDomains.has(domain) && !portReadingDomains.has(mod.name)) return [];
+  return [
+    {
+      domain,
+      level: "warn",
+      what: `this module's TOP LEVEL reads the captured ports (Date.now()/new Date()/Math.random() at module scope) — the built law loses sandbox POOLING (the pristine-pool "boot-reads hole"), so every write pays a full boot`,
+      fix: `move the read INSIDE the plan (a plan is where the captured ports belong); a module-level constant must not read the clock/rng`,
+    },
+  ];
+}
+
+/**
+ * Run every author-time twin over the composed domain modules and return the findings, ordered
+ * refuse → warn → note (stable within a level, by domain/directive appearance). This is the ONE
+ * entry `githolon check` and `compile`'s summary both call. `opts.portReadingDomains` (optional) is
+ * the set of domain keys whose module top level read the captured ports at import — collected by the
+ * module-load lane via {@link recordTopLevelPortReads}; absent ⇒ the top-level-port-read twin is silent.
+ */
+export function checkDomainModules(
+  modules: readonly DomainModule[],
+  opts?: { portReadingDomains?: ReadonlySet<string> },
+): Finding[] {
+  const findings: Finding[] = [];
+  const portReadingDomains = opts?.portReadingDomains ?? new Set<string>();
+
+  for (const mod of modules) {
+    const domain = mod.domain ?? mod.name;
+    const aggById = new Map<string, AggregateHandle>();
+    for (const a of mod.aggregates) aggById.set(a.id, a);
+
+    // Slice-2 twin: the module top level read the captured ports (pristine-pool ineligibility).
+    findings.push(...topLevelPortReadFindings(mod, portReadingDomains));
+
+    // The NOTE twin (unify): the auto-declared secondary ensures composeDomainModule injected.
+    for (const ty of mod.autoDeclaredEnsures ?? []) {
+      findings.push({
+        domain,
+        level: "note",
+        what: `auto-declared Ensure→${ty} from a plan's secondary ensure(...) — the id-mint gate was opened for it`,
+        fix: `no action needed; to make it explicit, export a directive that \`.ensures(${ty})\``,
+      });
+    }
+
+    for (const dir of mod.directives as Directive<unknown>[]) {
+      const where = `${domain}/${dir.id}`;
+      const probe = probeDirective(dir, where);
+      if (probe === undefined) continue; // unsynthesizable payload — proven by hand, not by check
+      findings.push(...planReturnFindings(domain, dir, probe));
+      findings.push(...unreadPayloadFindings(domain, dir, probe));
+      findings.push(...opVsSchemaFindings(domain, dir, probe, aggById));
+      findings.push(...deletedAmbientFindings(domain, dir, probe));
+    }
+
+    // Slice-2/slice-3 twins over the whole module: invariant sample-probes + encryption grouping.
+    findings.push(...invariantFindings(mod, aggById));
+    findings.push(...encryptionGroupingFindings(mod, aggById));
+  }
+
+  // The BIRTH-RECIPE twin (unify): fold the scattered `.births()` recipe diagnostics into the
+  // one report as WARNs (a discoverable-but-suspect recipe — missing seed, uncomposed child domain).
+  try {
+    const idx = proofLegsIndex(modules as DomainModule[]);
+    if (idx !== null) {
+      for (const [domain, legs] of Object.entries(idx.domains)) {
+        for (const diag of legs.birthDiagnostics ?? []) {
+          findings.push({
+            domain,
+            level: "warn",
+            what: `birth recipe: ${diag}`,
+            fix: `see architecture/g3_kernel_fulfils_birth.md / the births DX — the recipe must install both framework + child law and seed genesis`,
+          });
+        }
+      }
+    }
+  } catch {
+    /* birth discovery is best-effort — its absence never blocks the check */
+  }
+
+  const rank = { refuse: 0, warn: 1, note: 2 } as const;
+  return findings
+    .map((f, i) => ({ f, i }))
+    .sort((a, b) => rank[a.f.level] - rank[b.f.level] || a.i - b.i)
+    .map(({ f }) => f);
+}
+
+/** Does the finding set carry a hard refusal (⇒ `githolon check` exits non-zero, `compile` refuses)? */
+export function hasRefusal(findings: readonly Finding[]): boolean {
+  return findings.some((f) => f.level === "refuse");
+}
+
+/** Format one finding as the unified report line: `<domain>/<directive>: <LEVEL> — <what> — fix: <fix>`. */
+export function formatFinding(f: Finding): string {
+  const subject = f.directiveId !== undefined ? `${f.domain}/${f.directiveId}` : f.domain;
+  return `${subject}: ${f.level.toUpperCase()} — ${f.what} — fix: ${f.fix}`;
+}
+
+/** The full `check` report body (one line per finding), ordered refuse → warn → note. */
+export function formatFindings(findings: readonly Finding[]): string[] {
+  return findings.map(formatFinding);
+}