@githolon/dsl 0.49.0 → 0.50.0

package/src/law_check.ts

@@ -0,0 +1,375 @@
+// 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 type { 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";
+
+/** 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;
+}
+
+// ── 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;
+}
+
+/**
+ * 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.
+ */
+export function checkDomainModules(modules: readonly DomainModule[]): Finding[] {
+  const findings: Finding[] = [];
+
+  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);
+
+    // 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));
+    }
+  }
+
+  // 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);
+}