@githolon/dsl 0.50.0 → 0.52.0

package/src/law_check.ts

@@ -25,7 +25,7 @@
  * payload that exhibited it. The runtime gate remains the arbiter; `check` never claims
  * completeness, only that what it flags is real.
  */
-import type { z } from "zod";
+import { z } from "zod";
 
 import type { AggregateHandle } from "./aggregate.js";
 import type { Directive } from "./directive.js";
@@ -39,6 +39,10 @@ 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 {
@@ -162,6 +166,164 @@ function samplePayloadText(payload: Record<string, unknown>): string {
   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
@@ -298,19 +460,254 @@ function opVsSchemaFindings(
   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.
+ * 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[]): Finding[] {
+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({
@@ -328,7 +725,12 @@ export function checkDomainModules(modules: readonly DomainModule[]): Finding[]
       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

package/src/law_source_map.ts

@@ -0,0 +1,146 @@
+// 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.
+
+/**
+ * SOURCE MAPPING for `githolon check` findings (architecture/author_time_gate.md, slice 3 — the LSP).
+ *
+ * A {@link Finding} carries `{domain, directiveId?}` but no source LOCATION — the probe knows WHICH
+ * directive/aggregate/read is at fault, not WHERE it is written. This module recovers the location by
+ * scanning the domain's own TS module source text for the DECLARATION of the named entity:
+ * `directive("<id>")`, `aggregate("<Id>", …)`, `query("<id>")`, `count("<id>")`, `sum(...)`, … — a
+ * regex on the STRING LITERAL, robust across formatting (multi-line, spacing, quote style).
+ *
+ * The id in a finding may name a directive, a read decl (query/count/sum/min/max/exists/spatial), a
+ * workspace invariant, or — for a domain-wide finding with no `directiveId` — an aggregate. We do NOT
+ * know which kind, so we scan for the id as the FIRST string argument of ANY declaration call. When
+ * nothing resolves (a domain-wide finding, an id we can't find, an exotic layout) we fall back to
+ * line 1 of the domain's FIRST module — a squiggle at the top of the file beats no squiggle.
+ *
+ * Pure + synchronous: the caller supplies the domain→module-file-paths map (the config knows it — the
+ * composed DomainModule does not retain source paths, so the check/LSP lane threads them through) and
+ * the file READS are memoized per source map instance.
+ */
+import { readFileSync } from "node:fs";
+
+/** A resolved 1-based source location (LSP-friendly: `line`/`column` are 1-based, editors 0-base them). */
+export interface SourceLocation {
+  /** Absolute path of the module file the declaration lives in. */
+  readonly file: string;
+  /** 1-based line of the declaration's id string literal (or 1 on fallback). */
+  readonly line: number;
+  /** 1-based column of the id string literal's opening quote (or 1 on fallback). */
+  readonly column: number;
+  /** True when this is the top-of-file fallback (the id could not be located precisely). */
+  readonly fallback: boolean;
+}
+
+/** The declaration VERBS whose first string argument names an entity a finding can point at. */
+const DECL_VERBS = [
+  "directive",
+  "aggregate",
+  "query",
+  "count",
+  "sum",
+  "min",
+  "max",
+  "exists",
+  "spatial",
+  "workspaceInvariant",
+  "valueObject",
+  "derived",
+  "combined",
+  "first",
+  "take",
+  "relation",
+] as const;
+
+/** Escape a string for literal use inside a RegExp. */
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Compute the 1-based {line, column} of a character offset in `text` (column = chars into the line + 1). */
+function offsetToLineCol(text: string, offset: number): { line: number; column: number } {
+  let line = 1;
+  let lineStart = 0;
+  for (let i = 0; i < offset; i++) {
+    if (text.charCodeAt(i) === 10 /* \n */) {
+      line++;
+      lineStart = i + 1;
+    }
+  }
+  return { line, column: offset - lineStart + 1 };
+}
+
+/**
+ * A source map over a single domain's module files. Reads + memoizes the source text lazily and
+ * resolves an entity id (or an aggregate/whole-domain fallback) to a {@link SourceLocation}.
+ */
+export class DomainSourceMap {
+  private readonly texts = new Map<string, string | null>();
+
+  /** `files` — the ORDERED module paths composing the domain (config order; first is the fallback anchor). */
+  constructor(private readonly files: readonly string[]) {}
+
+  private text(file: string): string | null {
+    if (!this.texts.has(file)) {
+      try {
+        this.texts.set(file, readFileSync(file, "utf8"));
+      } catch {
+        this.texts.set(file, null);
+      }
+    }
+    return this.texts.get(file) ?? null;
+  }
+
+  /** The top-of-file fallback: line 1, column 1 of the domain's first readable module. */
+  private fallbackLocation(): SourceLocation | undefined {
+    const file = this.files[0];
+    if (file === undefined) return undefined;
+    return { file, line: 1, column: 1, fallback: true };
+  }
+
+  /**
+   * Locate the declaration of `id` across the domain's modules — the first `<verb>("<id>"…)` /
+   * `<verb>('<id>'…)` / <verb>(`<id>`…) match, scanned in config module order. Falls back to the top
+   * of the first module when `id` is undefined (a domain-wide finding) or cannot be located.
+   */
+  locate(id: string | undefined): SourceLocation | undefined {
+    if (id !== undefined) {
+      const idRe = escapeRe(id);
+      // <verb> ( <optional ws> <quote> id <same quote>  — the id as the first string arg of a decl call.
+      const verbs = DECL_VERBS.join("|");
+      const re = new RegExp(`\\b(?:${verbs})\\s*\\(\\s*(["'\`])${idRe}\\1`, "g");
+      for (const file of this.files) {
+        const text = this.text(file);
+        if (text === null) continue;
+        const m = re.exec(text);
+        if (m !== null) {
+          // Column points at the opening QUOTE of the id literal (m.index is at the verb).
+          const quoteOffset = m.index + m[0].length - id.length - 1;
+          const { line, column } = offsetToLineCol(text, quoteOffset);
+          return { file, line, column, fallback: false };
+        }
+        re.lastIndex = 0;
+      }
+    }
+    return this.fallbackLocation();
+  }
+}
+
+/** A source map over a whole package — one {@link DomainSourceMap} per domain key. */
+export class LawSourceMap {
+  private readonly perDomain = new Map<string, DomainSourceMap>();
+
+  /** `domainFiles` — domain key → its ORDERED module file paths (absolute), as the config declares them. */
+  constructor(domainFiles: ReadonlyMap<string, readonly string[]>) {
+    for (const [domain, files] of domainFiles) this.perDomain.set(domain, new DomainSourceMap([...files]));
+  }
+
+  /** Resolve a finding's `{domain, directiveId?}` to a source location, or `undefined` when unmappable. */
+  locate(domain: string, id?: string): SourceLocation | undefined {
+    return this.perDomain.get(domain)?.locate(id);
+  }
+}

package/src/lsp_main.ts

@@ -0,0 +1,14 @@
+// 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` (stdio) — the language-server entry. Starts the author-time-gate server
+ * ({@link startServer}); it speaks LSP over stdin/stdout to any editor (VS Code, Neovim, …).
+ * Run under tsx (the launcher `lsp_server.mjs`) so it can import the tenant's TS domain modules
+ * in-process. See architecture/author_time_gate.md (slice 3).
+ */
+import { startServer } from "./lsp_server.js";
+
+startServer();