@githolon/dsl 0.1.0

package/src/compile_engine.ts

@@ -0,0 +1,567 @@
+// 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} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * USD → engine-bundle — the EXPLICIT, SEPARATE generative stage (#138, increment 1).
+ *
+ * Jack: "I want TS → USD and then as a separate stage USD → wasm."
+ *
+ * #137 gave us TS → USD: `emitUsd(layers)` encodes `DomainModule`s into the composed
+ * OpenUSD-shaped IR document (`UsdDocument`) — the STRUCTURE / LAW / IDENTITY: which
+ * directives + aggregates exist, their target / marker / requires / scope / reads /
+ * emits contracts, flattened + hashed by `usdHash`. The USD IR carries the LAW, NOT
+ * the executable code.
+ *
+ * This module is the NEXT stage: USD → the engine module the runtime evals. Today
+ * `golden/emit_engine_golden.ts` HAND-ASSEMBLES the registry `{ "domain directiveId"
+ * -> { directive, agg } }` straight from the imported domain modules and assigns
+ * `globalThis.plan` — skipping the USD intermediate entirely. Here the SAME engine
+ * module is generated FROM the composed USD doc instead: the USD directive prims drive
+ * WHICH directives the module exposes (the law), and the supplied `plans` BIND each to
+ * its executable `.plan()`-bearing `Directive` + target `AggregateHandle` (the code).
+ *
+ * Two load-bearing properties the explicit stage buys:
+ *  1. **Identity flows TS → USD → module.** The compiled module's identity is STAMPED
+ *     `= usdHash(usdDoc, opts)` — NOT an ad-hoc bundle/registry hash. Re-deriving the
+ *     module from the same `(doc, opts)` re-stamps byte-identically; a different law
+ *     (different USD) yields a different module identity.
+ *  2. **Fail-closed on USD ↔ plan divergence.** A USD directive prim with no matching
+ *     plan, or a supplied plan with no matching USD directive prim, REFUSES the module
+ *     (`EngineCompileError`). The explicit stage certifies that the executable bundle
+ *     and the composed law are in 1:1 agreement — the inconsistency the hand path
+ *     cannot catch (it has no law artifact to check against).
+ *
+ * ADDITIVE + build-time only: imports `node:crypto` transitively via `usd.js`, reached
+ * via the `@githolon/dsl/compile-engine` subpath, NOT the runtime `index.ts` barrel. It
+ * does NOT bake/touch any pinned `*.wasm` — wiring the REAL bundle through this stage +
+ * re-baking is a later, gated step. SYNTHETIC framework units only.
+ */
+import type { Directive } from "./directive.js";
+import type { AggregateHandle, AggregateInvariantFn } from "./aggregate.js";
+import type { ComposeOptions } from "./compose.js";
+import { flattenUsd, usdHash, type UsdDocument, type UsdPrim } from "./usd.js";
+import type { DeclaredEmits } from "./emits_guard.js";
+import type {
+  WorkspaceInvariantDecl,
+  WorkspaceInvariantReads,
+  WorkspaceInvariantAssert,
+  InvariantRef,
+} from "./framework/workspace_invariant.js";
+
+/** A directive's executable binding: its `.plan()`-bearing `Directive` + target handle.
+ * This is the EXECUTABLE half the USD IR (the law) does not carry — the stage BINDS it
+ * to the law. Shape mirrors `emit_engine_golden.ts`'s hand-assembled `RegistryEntry`. */
+export interface PlanBinding {
+  /** The `.plan()`-bearing directive (the executable). `unknown` payload — the stage
+   * only routes; payload typing is the per-directive call site's concern. */
+  readonly directive: Directive<unknown>;
+  /** The directive's target `AggregateHandle` (resolves field kinds when planning). */
+  readonly agg: AggregateHandle;
+}
+
+/** The executable plans the stage binds to the USD law, keyed by directive id. */
+export type PlanMap = ReadonlyMap<string, PlanBinding>;
+
+/** One compiled registry entry: the USD law prim + its bound executable. */
+export interface EngineRegistryEntry {
+  /** The directive id (the last segment of the USD prim `path`). */
+  readonly directiveId: string;
+  /** The target aggregate TYPE id (from the USD directive prim — the LAW). */
+  readonly target: string;
+  /** The bound executable directive + its target handle (from `plans`). */
+  readonly binding: PlanBinding;
+}
+
+/**
+ * The compiled engine module: the registry the runtime dispatches against PLUS the
+ * stamped identity. `registry` is keyed by directive id (the same `{ directive, agg }`
+ * shape `emit_engine_golden.ts` assembles by hand). `identity` is `usdHash(usdDoc,
+ * opts)` — the composed-IR identity flowed straight through, the "USD → wasm as a
+ * separate stage" anchor.
+ */
+export interface EngineModule {
+  /** directiveId → its compiled registry entry (USD law prim ↔ bound plan). */
+  readonly registry: ReadonlyMap<string, EngineRegistryEntry>;
+  /** The module identity = `usdHash(usdDoc, opts)` (flows TS → USD → module). */
+  readonly identity: string;
+  /**
+   * directiveId → its DECLARED emit boundary (event type → `{ max? }`), carried
+   * STRAIGHT from the USD directive prim's `emits` (#137). A directive declaring no
+   * emits maps to `{}`. This is the data the runtime / gate reads to enforce
+   * `emitted ⊆ declared` at dispatch via {@link assertEmitsWithinDeclared} — the
+   * WIRING of that call is the later, gated flip; compiling the data onto the module
+   * is the additive step here. The emit clauses are also statically consistency-checked
+   * at compile (the `emits-malformed` rule), so what flows here is already well-formed.
+   */
+  readonly emitsByDirective: ReadonlyMap<string, DeclaredEmits>;
+  /**
+   * aggregateTypeId → its declared `invariant` body (#250). OMITTED for aggregate types
+   * that carry no invariant. The body ships in the engine bundle, NEVER the ledger —
+   * presence-only (`hasInvariant: true`) is what the manifest hashes. The map is keyed by
+   * the aggregate handle's `.id` (the wire type string, e.g. `"Roster"`).
+   */
+  readonly aggregateInvariants: ReadonlyMap<string, AggregateInvariantFn>;
+  /**
+   * The workspace-invariant declarations for this module (#266), carrying both the
+   * `reads` and `assert` executable bodies. The gate dispatches:
+   *   1. `workspaceInvariantReads` — call the matching `.reads` body to derive the ref-set.
+   *   2. `workspaceInvariant` — call the matching `.assert` body over the resolved snapshots.
+   * OMITTED (empty map) when the domain declares no workspace invariants.
+   */
+  readonly workspaceInvariants: ReadonlyMap<string, WorkspaceInvariantDecl>;
+}
+
+/** A divergence the explicit USD → module stage refuses (fail-closed). */
+export type EngineCompileRule =
+  /** A USD directive prim has no matching plan in `plans` (the law has no executable). */
+  | "plan-missing"
+  /** A supplied plan has no matching USD directive prim (executable not in the law). */
+  | "plan-extra"
+  /** A bound plan's directive/handle disagrees with the USD prim's id/target (the
+   * executable does not implement the law it is bound to). */
+  | "binding-mismatch"
+  /** A directive's DECLARED emit set is malformed: a duplicate event type within the
+   * one directive, or a non-positive / non-integer `max`. A conservative STATIC check
+   * — it does NOT consult a global event registry (the model has none yet); it only
+   * rejects a self-inconsistent declared boundary so the data carried onto the module
+   * (and later enforced) is well-formed. */
+  | "emits-malformed";
+
+/** A typed, fail-closed engine-compile failure (USD ↔ plan divergence). */
+export class EngineCompileError extends Error {
+  readonly rule: EngineCompileRule;
+  readonly directiveId: string;
+  readonly detail: string;
+  constructor(rule: EngineCompileRule, directiveId: string, detail: string) {
+    super(`engine compile ${rule} at "${directiveId}": ${detail}`);
+    this.name = "EngineCompileError";
+    this.rule = rule;
+    this.directiveId = directiveId;
+    this.detail = detail;
+  }
+}
+
+/** The directive id is the LAST `/`-segment of a USD prim path (e.g.
+ * `/Sample/createThing` → `createThing`). */
+function directiveIdOf(path: string): string {
+  const segments = path.split("/").filter((s) => s.length > 0);
+  return segments[segments.length - 1] ?? path;
+}
+
+/**
+ * Validate a USD directive prim's declared `emits` and return it as a well-formed
+ * {@link DeclaredEmits} (omitted ⇒ `{}`). CONSERVATIVE static consistency only — it
+ * does NOT cross-check against a global event registry (the model has none yet); it
+ * rejects a SELF-inconsistent declared boundary so the data flowing onto the module
+ * (and later enforced) is sound. Throws `emits-malformed` for:
+ *  - a non-integer / non-positive `max` (a `max` of 0 or negative or fractional can
+ *    never be satisfied or is meaningless as a count bound);
+ *  - a duplicate event type (two clauses for the same type). The USD prim already
+ *    carries an OBJECT (whose keys are inherently unique), so this clause guards the
+ *    invariant explicitly and is sensitive should the carrier ever become entry-based.
+ */
+function validateDeclaredEmits(
+  directiveId: string,
+  emits: Record<string, { max?: number }> | undefined,
+): DeclaredEmits {
+  if (emits === undefined) return {};
+  const out: DeclaredEmits = {};
+  for (const eventType of Object.keys(emits)) {
+    if (Object.prototype.hasOwnProperty.call(out, eventType)) {
+      throw new EngineCompileError(
+        "emits-malformed",
+        directiveId,
+        `declared emit event type "${eventType}" appears more than once.`,
+      );
+    }
+    const clause = emits[eventType]!;
+    const max = clause.max;
+    if (max !== undefined) {
+      if (!Number.isInteger(max) || max <= 0) {
+        throw new EngineCompileError(
+          "emits-malformed",
+          directiveId,
+          `declared emit "${eventType}" has an invalid max ${max} — a max must be a ` +
+            `positive integer.`,
+        );
+      }
+      out[eventType] = { max };
+    } else {
+      out[eventType] = {};
+    }
+  }
+  return out;
+}
+
+/**
+ * Compile the engine module FROM the composed USD doc (the law) + the supplied
+ * executable `plans` (the code). The SEPARATE USD → engine-bundle stage.
+ *
+ * 1. `flattenUsd(usdDoc, opts)` → the effective composed prims; the DIRECTIVE prims
+ *    are the law the engine module must expose.
+ * 2. For each directive prim, the directive id is its path's last segment; bind
+ *    `plans.get(directiveId)`. The prim's `target` (the law) is checked against the
+ *    bound directive's `aggregateId` + handle id (the executable) — a disagreement is
+ *    a `binding-mismatch`. Builds the registry entry `{ directiveId, target, binding }`.
+ * 3. Stamp `identity = usdHash(usdDoc, opts)` — identity flows TS → USD → module.
+ * 4. FAIL CLOSED on divergence: a directive prim with no plan → `plan-missing`; a plan
+ *    with no directive prim → `plan-extra`. The module is refused unless the USD law
+ *    and the executable bundle are in exact 1:1 agreement.
+ * 5. Collect aggregate invariant bodies from the bound aggregate handles (those with
+ *    `hasInvariant: true`). Collect workspace invariant declarations from `wsInvariants`
+ *    if supplied.
+ *
+ * Behaviour-preserving vs `emit_engine_golden.ts`: for the same domains, the produced
+ * registry exposes the same directive-id set, each bound to the same `{ directive, agg }`
+ * — so routing the real bundle through this stage later is a no-op on dispatch.
+ *
+ * @param wsInvariants - the domain's workspace-invariant declarations (carrying the
+ *   executable `reads`/`assert` bodies that ship in the engine bundle). Pass only the
+ *   invariants for the SAME domain the USD doc describes; `makeEngineReport` dispatches
+ *   them by id.
+ */
+export function compileEngineModule(
+  usdDoc: UsdDocument,
+  plans: PlanMap,
+  opts: ComposeOptions = {},
+  wsInvariants: readonly WorkspaceInvariantDecl[] = [],
+): EngineModule {
+  const prims = flattenUsd(usdDoc, opts);
+  const directivePrims = prims.filter(
+    (p): p is Extract<UsdPrim, { kind: "directive" }> => p.kind === "directive",
+  );
+
+  const registry = new Map<string, EngineRegistryEntry>();
+  const emitsByDirective = new Map<string, DeclaredEmits>();
+  const bound = new Set<string>();
+
+  for (const prim of directivePrims) {
+    const directiveId = directiveIdOf(prim.path);
+
+    // A directive id appearing twice across the flattened law is itself a structural
+    // inconsistency the explicit stage refuses (the registry key would collide).
+    if (registry.has(directiveId)) {
+      throw new EngineCompileError(
+        "binding-mismatch",
+        directiveId,
+        `USD directive id "${directiveId}" appears at more than one prim path ` +
+          `(latest "${prim.path}") — the engine registry key would collide.`,
+      );
+    }
+
+    const binding = plans.get(directiveId);
+    if (binding === undefined) {
+      throw new EngineCompileError(
+        "plan-missing",
+        directiveId,
+        `USD directive prim "${prim.path}" has no matching plan — the composed law ` +
+          `declares a directive the executable bundle does not implement.`,
+      );
+    }
+
+    // The executable must implement the law it is bound to: the directive's own id must
+    // match the USD prim's id, and its declared target (aggregateId / handle id) must
+    // match the USD prim's `target`. Otherwise the wrong code is wired to the law.
+    if (binding.directive.id !== directiveId) {
+      throw new EngineCompileError(
+        "binding-mismatch",
+        directiveId,
+        `bound directive id "${binding.directive.id}" does not match USD directive ` +
+          `id "${directiveId}".`,
+      );
+    }
+    if (binding.directive.aggregateId !== prim.target) {
+      throw new EngineCompileError(
+        "binding-mismatch",
+        directiveId,
+        `bound directive targets aggregate "${binding.directive.aggregateId}" but the ` +
+          `USD law's target is "${prim.target}".`,
+      );
+    }
+    if (binding.agg.id !== prim.target) {
+      throw new EngineCompileError(
+        "binding-mismatch",
+        directiveId,
+        `bound aggregate handle "${binding.agg.id}" does not match the USD law's ` +
+          `target "${prim.target}".`,
+      );
+    }
+
+    // Carry the declared emit boundary off the USD prim (the law), validating it is
+    // self-consistent (`emits-malformed`) before it flows onto the module. The set the
+    // runtime/gate will enforce `emitted ⊆ declared` against at dispatch.
+    const declaredEmits = validateDeclaredEmits(directiveId, prim.emits);
+
+    registry.set(directiveId, { directiveId, target: prim.target, binding });
+    emitsByDirective.set(directiveId, declaredEmits);
+    bound.add(directiveId);
+  }
+
+  // Fail closed on the OTHER direction: a supplied plan with NO matching USD directive
+  // prim — an executable not present in the composed law.
+  for (const directiveId of plans.keys()) {
+    if (!bound.has(directiveId)) {
+      throw new EngineCompileError(
+        "plan-extra",
+        directiveId,
+        `plan "${directiveId}" has no matching USD directive prim — an executable not ` +
+          `present in the composed law.`,
+      );
+    }
+  }
+
+  // Identity FLOWS TS → USD → module: stamp the composed-IR hash, not a bundle hash.
+  const identity = usdHash(usdDoc, opts);
+
+  // Collect aggregate invariant bodies from the bound handles (step 5).
+  // Keyed by aggregate type id (handle.id), carrying only handles that declare an invariant.
+  const aggregateInvariants = new Map<string, AggregateInvariantFn>();
+  for (const entry of registry.values()) {
+    const handle = entry.binding.agg;
+    if (handle.hasInvariant === true && handle.invariant !== undefined) {
+      aggregateInvariants.set(handle.id, handle.invariant);
+    }
+  }
+
+  // Collect workspace invariant declarations by id. The executable `reads`/`assert` bodies
+  // are carried straight through — they ship in the engine bundle, not the ledger.
+  const workspaceInvariants = new Map<string, WorkspaceInvariantDecl>();
+  for (const decl of wsInvariants) {
+    workspaceInvariants.set(decl.id, decl);
+  }
+
+  return { registry, identity, emitsByDirective, aggregateInvariants, workspaceInvariants };
+}
+
+// #250 follow-up: this module emits `globalThis.plan` only. The engine-backed AGGREGATE
+// INVARIANT oracle (nomos_admission_peer::EngineAggregateInvariant) dispatches a
+//   { intent: { aggregateInvariant: { of: "<AggType>" } }, priorState: <snapshot> }
+// job via `globalThis.planReport` (Report mode). The compiled emit should add a
+// `planReport` aggregate-invariant case the SAME way `executeDirectiveToIntent` is dispatched here:
+// look up the aggregate handle by `of`, run its declared `.invariant` body
+// (aggregate(..., { invariant }) — see dsl/src/aggregate.ts; the handle carries
+// `.invariant` + `hasInvariant`) over `priorState`, and return the EXACT verdict
+// JSON.stringify({accept:true}) | JSON.stringify({reject:"<code>"}). Until then the
+// Rust path is proven end-to-end by a per-domain shim in
+// admission-peer/tests/aggregate_invariant_e2e.rs.
+
+/**
+ * The classic-script `globalThis.plan(job)` equivalent, derived FROM a compiled
+ * `EngineModule`. Mirrors `emit_engine_golden.ts`'s `plan`: it reads the dispatch
+ * fields, looks up the directive in the USD-derived registry, runs the REAL
+ * `executeDirectiveToIntent` (validate → plan → group), and returns the kernel `WireEvent[]`. A
+ * throw (unknown directive / Zod failure) is the deterministic engine halt the host
+ * quarantines.
+ *
+ * The registry key here is the directive id (the engine module is one domain's
+ * composed law). The hand path keys by `${domain} ${directiveId}` because it spans
+ * multiple imported domain modules; a composed USD doc is already the unified law, so
+ * the directive id is the dispatch key. Provided so the production cutover can route
+ * the runtime entry through the compiled module without re-implementing dispatch.
+ *
+ * Takes the `executeDirectiveToIntent` implementation as a parameter to keep this module free of
+ * the runtime `index.ts` barrel (which would drag `node:crypto` resolution concerns);
+ * the call site passes `executeDirectiveToIntent` from `@githolon/dsl`.
+ */
+export function makeEnginePlan<Wire>(
+  module: EngineModule,
+  executeDirectiveToIntent: (
+    directive: Directive<unknown>,
+    agg: AggregateHandle,
+    payload: never,
+    ctx: never,
+  ) => { events: Wire[]; strikes: string[] },
+  portsFromHost: () => never,
+): (
+  job: { intent?: { directiveId?: string; payload?: unknown } },
+) => Wire[] | { events: Wire[]; strikes: string[] } {
+  return (job) => {
+    const directiveId = job.intent?.directiveId;
+    if (typeof directiveId !== "string") {
+      throw new Error(
+        `engine plan: job.intent must carry {directiveId}; got ${JSON.stringify(job.intent)}`,
+      );
+    }
+    const entry = module.registry.get(directiveId);
+    if (entry === undefined) {
+      throw new Error(`engine plan: no directive registered for "${directiveId}"`);
+    }
+    const ctx = portsFromHost();
+    const wire = executeDirectiveToIntent(
+      entry.binding.directive,
+      entry.binding.agg,
+      job.intent?.payload as never,
+      ctx,
+    );
+    // ADDITIVE strikeout (mirrors emit_engine_golden.ts): {events, strikes} only when a
+    // strike is present, else the bare event array — strikes-free domains are byte-stable.
+    return wire.strikes.length ? { events: wire.events, strikes: wire.strikes } : wire.events;
+  };
+}
+
+/**
+ * The `globalThis.planReport(job)` dispatcher derived FROM a compiled `EngineModule`.
+ * Mirrors `makeEnginePlan` (the plan dispatcher) but handles the THREE report-mode
+ * dispatch cases the Rust host issues via `globalThis.planReport`:
+ *
+ *  1. **`aggregateInvariant`** — `job.intent.aggregateInvariant.of` names the aggregate type;
+ *     `job.priorState` is the post-apply snapshot. Runs the handle's declared `.invariant`
+ *     body. Returns `JSON.stringify({accept:true})` | `JSON.stringify({reject:"<code>"})`.
+ *     Vacuous-pass: aggregate types with no declared invariant return `{"accept":true}`.
+ *
+ *  2. **`workspaceInvariantReads`** — `job.intent.workspaceInvariantReads` carries the
+ *     invariant id; `job.intent.payload` is the authored intent payload. Runs the
+ *     declaration's `.reads` body to derive the BOUNDED ref-set. Returns
+ *     `JSON.stringify([{name, aggregate, id}, ...])`.
+ *
+ *  3. **`workspaceInvariant`** — `job.intent.workspaceInvariant.id` names the invariant;
+ *     `job.priorState` is the named snapshot map `{ refName → aggregateSnapshot }`.
+ *     Runs the declaration's `.assert` body. Returns
+ *     `JSON.stringify({accept:true})` | `JSON.stringify({reject:"<code>"})`.
+ *
+ * Dispatch job fields match the Rust host's `build_dispatch_job` serde shape EXACTLY:
+ * `capturedPorts` (camelCase), `priorState` (camelCase, present for agg + ws assert,
+ * absent for ws reads). A throw (unknown case / missing body) is the deterministic
+ * engine halt the Rust host quarantines.
+ *
+ * The returned function is wired as `globalThis.planReport = makeEngineReport(module)`
+ * in the compiled bundle — replacing the hand-written stand-in shims the Rust tests
+ * currently use (proven end-to-end by `aggregate_invariant_e2e.rs` and
+ * `workspace_invariant_gate.rs`).
+ */
+export function makeEngineReport(
+  module: EngineModule,
+): (job: {
+  intent?: {
+    workspaceInvariantList?: unknown;
+    aggregateInvariant?: { of?: string };
+    workspaceInvariantReads?: unknown;
+    workspaceInvariant?: { id?: string };
+    payload?: Record<string, unknown>;
+  };
+  priorState?: Record<string, unknown>;
+}) => string {
+  return (job) => {
+    const intent = job.intent ?? {};
+
+    // ── CASE 0: workspaceInvariantList — DISCOVERY (#266 slice 5c) ─────────────
+    // The admitting peer asks the CERTIFIED BUNDLE which workspace invariants it declares
+    // (so the gate sources the DECLARED set from the law itself — the bundle's hash IS the
+    // domain identity — instead of a parallel manifest). Returns `[{id, on}, …]`; the gate
+    // filters by `on == directiveId`. A domain that declares none returns `[]`.
+    if (intent.workspaceInvariantList !== undefined) {
+      const list = [...module.workspaceInvariants.values()].map((d) => ({
+        id: d.id,
+        on: d.on,
+      }));
+      return JSON.stringify(list);
+    }
+
+    // ── CASE 1: aggregateInvariant ─────────────────────────────────────────────
+    if (intent.aggregateInvariant !== undefined) {
+      const aggType = intent.aggregateInvariant.of;
+      if (typeof aggType !== "string") {
+        throw new Error(
+          `planReport aggregateInvariant: job.intent.aggregateInvariant must carry ` +
+            `{of: "<AggType>"}; got ${JSON.stringify(intent.aggregateInvariant)}`,
+        );
+      }
+      const invariantFn = module.aggregateInvariants.get(aggType);
+      if (invariantFn === undefined) {
+        // Vacuous-pass: the aggregate type has no declared invariant.
+        return JSON.stringify({ accept: true });
+      }
+      const snapshot = job.priorState ?? {};
+      const verdict = invariantFn(snapshot);
+      return JSON.stringify(verdict);
+    }
+
+    // ── CASE 2: workspaceInvariantReads ───────────────────────────────────────
+    if (intent.workspaceInvariantReads !== undefined) {
+      // The invariant id is carried in the `workspaceInvariantReads` field.
+      // The field value is the invariant id (the Rust host serialises it as the id directly
+      // or as an object; the stand-in treats it as truthy → locate by the field's presence).
+      // Resolve by extracting the id from the field value: the Rust shape passes
+      //   { workspaceInvariantReads: { id: "<InvId>" }, payload: <authored> }
+      // The stand-in in the Rust test does NOT use `workspaceInvariantReads.id` — it fires
+      // on ANY truthy `workspaceInvariantReads` and reads the payload. We follow the same
+      // contract: locate the invariant by matching the `on` directive against
+      // `payload.directiveId`, OR use the id from the field when present.
+      const readsField = intent.workspaceInvariantReads;
+      let decl: WorkspaceInvariantDecl | undefined;
+      if (
+        readsField !== null &&
+        typeof readsField === "object" &&
+        typeof (readsField as { id?: unknown }).id === "string"
+      ) {
+        decl = module.workspaceInvariants.get((readsField as { id: string }).id);
+      }
+      if (decl === undefined) {
+        // Fallback: match by `on` directive if the id is not present in the field.
+        const directiveId =
+          intent.payload !== undefined
+            ? (intent.payload as { directiveId?: string }).directiveId
+            : undefined;
+        if (typeof directiveId === "string") {
+          for (const d of module.workspaceInvariants.values()) {
+            if (d.on === directiveId) {
+              decl = d;
+              break;
+            }
+          }
+        }
+      }
+      if (decl === undefined) {
+        throw new Error(
+          `planReport workspaceInvariantReads: no declared workspace invariant found ` +
+            `for reads dispatch; job.intent=${JSON.stringify(intent)}`,
+        );
+      }
+      const payload = intent.payload ?? {};
+      const refs: InvariantRef[] = decl.reads({ intent: payload });
+      return JSON.stringify(refs);
+    }
+
+    // ── CASE 3: workspaceInvariant (assert) ───────────────────────────────────
+    if (intent.workspaceInvariant !== undefined) {
+      const invId = intent.workspaceInvariant.id;
+      if (typeof invId !== "string") {
+        throw new Error(
+          `planReport workspaceInvariant: job.intent.workspaceInvariant must carry ` +
+            `{id: "<InvId>"}; got ${JSON.stringify(intent.workspaceInvariant)}`,
+        );
+      }
+      const decl = module.workspaceInvariants.get(invId);
+      if (decl === undefined) {
+        throw new Error(
+          `planReport workspaceInvariant: no declared workspace invariant with id ` +
+            `"${invId}" — cannot dispatch assert.`,
+        );
+      }
+      const snapshots = (job.priorState ?? {}) as Record<string, Record<string, unknown>>;
+      const verdict = decl.assert(snapshots);
+      return JSON.stringify(verdict);
+    }
+
+    throw new Error(
+      `planReport: unrecognised dispatch — job.intent must carry one of ` +
+        `{aggregateInvariant}, {workspaceInvariantReads}, or {workspaceInvariant}; ` +
+        `got ${JSON.stringify(intent)}`,
+    );
+  };
+}
+
+// Re-export the PURE emit-boundary primitive so a consumer reaching for the compiled
+// module's `emitsByDirective` can pair it with the enforcement call from one subpath.
+// The wiring (calling this after a plan returns its events) is the later, gated flip.
+export {
+  assertEmitsWithinDeclared,
+  EmitBoundaryError,
+  type DeclaredEmit,
+  type DeclaredEmits,
+  type EmitBoundaryRule,
+} from "./emits_guard.js";