@githolon/dsl 0.2.0 → 0.2.2

package/src/engine_entry.ts

@@ -29,6 +29,22 @@
  * `identity = {...identityCore, ...co2_identity}` pattern), so a tenant can compose
  * framework + tenant modules under one dispatch key.
  *
+ * LAZY PER-DOMAIN BOOT (task #34 — hot-path boot): a domain's module may also be a
+ * THUNK `() => moduleExports`. `nomos-compile` emits thunks (`() => require("…")`),
+ * which esbuild lazy-wraps (`__esm` init runs at the require call, not at bundle
+ * top level) — so the lump's TOP-LEVEL boot no longer executes every domain's zod
+ * schema graph + directive construction. Each fresh per-plan sandbox forces ONLY
+ * the domain(s) the dispatched intent touches: per-plan boot is O(directives of
+ * the touched domain), not O(whole law). Dispatches that are keyed by AGGREGATE
+ * TYPE or RELATION (derive / combine / aggregateInvariant / invariant) cannot know
+ * which domain to force, so a thunked entry REQUIRES the compiler-emitted
+ * `routing` table (built by `collectEngineRouting` over the SAME duck-type scans —
+ * one machinery, never a parallel list) mapping each type/relation to the domain
+ * keys that declare it. Fail-closed: thunks without routing refuse at top level.
+ * The EAGER shape (plain module objects, no routing) keeps the exact pre-#34
+ * behaviour — old generated entries remain valid inputs, and old compiled lumps in
+ * deployed chains re-verify untouched (they carry their own machinery).
+ *
  * ENGINE-BUNDLE-SAFE: this file (and everything it reaches) imports NO node builtin —
  * it must bundle under esbuild `--platform=neutral` into the sealed QuickJS lump.
  * The contracts mirrored here (wire shapes, vacuous-holds, strikes-conditional
@@ -48,20 +64,56 @@ import type { QueryRow } from "./report.js";
 /** One bundled domain module: a bag of named exports the entry scans by SHAPE. */
 export type DomainModuleExports = Record<string, unknown>;
 
+/**
+ * A domain module SOURCE: the exports bag itself (eager — the pre-#34 shape), or a
+ * thunk producing it (lazy — forced on first dispatch touch inside the fresh
+ * sandbox; `nomos-compile` emits `() => require("…")`, which esbuild defers).
+ */
+export type DomainModuleSource = DomainModuleExports | (() => DomainModuleExports);
+
 /** A report: declarative query + render; the host feeds rows, the engine renders. */
 export interface EngineReport {
   render(rows: QueryRow[]): string;
 }
 
+/**
+ * THE ROUTING TABLE (lazy boot only): aggregate type / relation id → the domain
+ * keys (in `domains` declaration order) whose modules declare it. Emitted by the
+ * compiler via {@link collectEngineRouting} — the SAME scans that build the live
+ * registries, run once at compile over the same merged modules, so the table
+ * cannot drift from what a full force would register. Used by the dispatches that
+ * are NOT keyed by domain (derive / combine / aggregateInvariant / invariant) to
+ * force only the declaring domain(s). A type/relation ABSENT from its map is one
+ * NO domain declares — exactly the eager scan-everything outcome.
+ */
+export interface EngineRouting {
+  readonly derivedOf?: Record<string, readonly string[]>;
+  readonly combinedOf?: Record<string, readonly string[]>;
+  readonly aggregateInvariantOf?: Record<string, readonly string[]>;
+  readonly relationOf?: Record<string, readonly string[]>;
+}
+
 /** The one declarative input: dispatch key → ORDERED module list (later wins). */
 export interface EngineEntryConfig {
   /**
    * Domain dispatch key → the modules composing it, spread-merged IN ORDER
    * (later overrides earlier on a name collision — the `identity` union pattern).
+   * Values may be thunks (lazy boot — see the module header).
    */
-  readonly domains: Record<string, readonly DomainModuleExports[]>;
+  readonly domains: Record<string, readonly DomainModuleSource[]>;
   /** Optional report registry: `reportId` → a factory `(actor) => Report`. */
   readonly reports?: Record<string, (actor: string) => EngineReport>;
+  /** REQUIRED when any domain module is a thunk; ignored otherwise. */
+  readonly routing?: EngineRouting;
+  /**
+   * AMBIENT-SLOT SEEDS (lazy boot): values imported at the entry's TOP LEVEL purely
+   * so their modules' init runs PRE-FREEZE (zod v4 writes
+   * `globalThis.__zod_global{Config,Registry}` at module init; the frozen sandbox
+   * refuses new globals at lazy-init time). The values are never read — passing
+   * them as call arguments is what keeps the imports live under a library's
+   * `sideEffects: false` (a bare side-effect import would be tree-shaken away).
+   */
+  readonly seeds?: readonly unknown[];
 }
 
 interface RegistryEntry {
@@ -148,6 +200,126 @@ function mergeModules(mods: readonly DomainModuleExports[]): DomainModuleExports
   return merged;
 }
 
+/**
+ * ONE DOMAIN's registries — everything its merged module exports register. Built by
+ * the ONE `buildDomainSlice` whether the boot is eager (all domains at top level)
+ * or lazy (the touched domain inside the dispatch) — factored, never forked.
+ */
+interface DomainSlice {
+  /** directiveId → {directive, agg}. */
+  registry: Map<string, RegistryEntry>;
+  /** aggregate type → its DerivedDecls (module export order). */
+  deriveds: Map<string, DerivedDecl[]>;
+  /** aggregate type → its CombinedDecls (module export order). */
+  combineds: Map<string, CombinedDecl[]>;
+  /** relation id → invariant body (off the registered directives' declaredRelations). */
+  invariants: Map<string, InvariantBody>;
+  /** aggregate type → aggregate-invariant body. */
+  aggInvariants: Map<string, AggregateInvariantFn>;
+}
+
+/** Build one domain's slice from its merged module exports (the original scans). */
+function buildDomainSlice(mod: DomainModuleExports): DomainSlice {
+  // ── directiveId → {directive, agg} ────────────────────────────────────────────
+  const registry = new Map<string, RegistryEntry>();
+  const aggs = aggregatesOf(mod);
+  const dirs = directivesOf(mod);
+  for (const [dirId, directive] of dirs) {
+    const agg = aggs.get(directive.aggregateId);
+    if (agg === undefined) {
+      // A directive targeting an aggregate not exported by its module is an
+      // authoring bug; surface it lazily (only if that directive is invoked).
+      continue;
+    }
+    registry.set(dirId, { directive, agg });
+  }
+
+  // ── aggregate type → derived / combined decls (fn bodies ship HERE, never the ledger) ──
+  const deriveds = new Map<string, DerivedDecl[]>();
+  const combineds = new Map<string, CombinedDecl[]>();
+  for (const d of derivedsOf(mod)) {
+    const list = deriveds.get(d.of) ?? [];
+    list.push(d);
+    deriveds.set(d.of, list);
+  }
+  for (const c of combinedsOf(mod)) {
+    const list = combineds.get(c.of) ?? [];
+    list.push(c);
+    combineds.set(c.of, list);
+  }
+
+  // ── relation id → cross-workspace invariant body (off the directives' declaredRelations) ──
+  const invariants = new Map<string, InvariantBody>();
+  for (const { directive } of registry.values()) {
+    const relations = (directive as { declaredRelations?: unknown }).declaredRelations;
+    if (!Array.isArray(relations)) continue;
+    for (const rel of relations) {
+      const r = rel as { id?: unknown; hasInvariant?: unknown; invariant?: unknown };
+      if (typeof r.id !== "string" || r.hasInvariant !== true) continue;
+      if (typeof r.invariant !== "function") {
+        // A relation declaring `hasInvariant` MUST ship an executable body — fail-closed.
+        throw new Error(
+          `engine bundle: relation "${r.id}" declares hasInvariant but ships no executable ` +
+            `invariant body — the gate would have nothing to evaluate (cross_workspace.md §2.1).`,
+        );
+      }
+      invariants.set(r.id, r.invariant as InvariantBody);
+    }
+  }
+
+  // ── aggregate type → aggregate-invariant body — from the SAME exports (no second list) ──
+  const aggInvariants = new Map<string, AggregateInvariantFn>();
+  for (const v of Object.values(mod)) {
+    if (
+      v &&
+      typeof v === "object" &&
+      (v as { __isAggregateHandle?: boolean }).__isAggregateHandle === true &&
+      (v as { hasInvariant?: boolean }).hasInvariant === true
+    ) {
+      const h = v as AggregateHandle & { invariant?: AggregateInvariantFn };
+      if (typeof h.invariant !== "function") {
+        // A handle declaring `hasInvariant` MUST ship an executable body — fail-closed.
+        throw new Error(
+          `engine bundle: aggregate "${h.id}" declares hasInvariant but ships no executable ` +
+            `invariant body — the gate would have nothing to evaluate (#250).`,
+        );
+      }
+      aggInvariants.set(h.id, h.invariant);
+    }
+  }
+
+  return { registry, deriveds, combineds, invariants, aggInvariants };
+}
+
+/**
+ * COMPILE-TIME companion (build lane; also bundle-safe): run the SAME scans the live
+ * registries run, over the SAME merged modules, and return the routing table a lazy
+ * entry needs. `nomos-compile` calls this with every domain's merged exports and
+ * embeds the result as `config.routing` — so the table and the registries can never
+ * disagree (one machinery). Throws the same fail-closed errors `buildDomainSlice`
+ * throws (a law whose invariant declarations are inconsistent refuses to COMPILE).
+ */
+export function collectEngineRouting(
+  domains: Record<string, readonly DomainModuleExports[]>,
+): EngineRouting {
+  const derivedOf: Record<string, string[]> = {};
+  const combinedOf: Record<string, string[]> = {};
+  const aggregateInvariantOf: Record<string, string[]> = {};
+  const relationOf: Record<string, string[]> = {};
+  const add = (map: Record<string, string[]>, key: string, domainName: string) => {
+    const list = map[key] ?? (map[key] = []);
+    if (!list.includes(domainName)) list.push(domainName);
+  };
+  for (const [domainName, mods] of Object.entries(domains)) {
+    const slice = buildDomainSlice(mergeModules(mods));
+    for (const type of slice.deriveds.keys()) add(derivedOf, type, domainName);
+    for (const type of slice.combineds.keys()) add(combinedOf, type, domainName);
+    for (const type of slice.aggInvariants.keys()) add(aggregateInvariantOf, type, domainName);
+    for (const relationId of slice.invariants.keys()) add(relationOf, relationId, domainName);
+  }
+  return { derivedOf, combinedOf, aggregateInvariantOf, relationOf };
+}
+
 /**
  * Build a DSL `ctx` (Ports) from the host-injected `__ports` scalars. `clock()`
  * synthesises a `WireHlc` from the scalar (the engine leg DISCARDS the produced
@@ -180,89 +352,51 @@ export interface RegisteredEngine {
 }
 
 /**
- * Build ALL registries from the one `domains` map, wire the five dispatch paths, and
- * assign `globalThis.plan` + `globalThis.planReport` (the lump is eval'd as a classic
- * script and `globalThis` is FROZEN before dispatch — registration must happen at
- * top-level eval, which calling this at module top level does).
+ * Build the registries from the one `domains` map (eagerly for plain module objects,
+ * on first dispatch touch for thunks), wire the five dispatch paths, and assign
+ * `globalThis.plan` + `globalThis.planReport` (the lump is eval'd as a classic
+ * script and `globalThis` is FROZEN before dispatch — the ASSIGNMENT must happen at
+ * top-level eval, which calling this at module top level does; the lazy forcing
+ * happens inside the dispatch call and writes no globals).
  */
 export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
-  const mergedByDomain = new Map<string, DomainModuleExports>();
-  for (const [domainName, mods] of Object.entries(config.domains)) {
-    mergedByDomain.set(domainName, mergeModules(mods));
+  const domainNames = Object.keys(config.domains);
+  const lazy = Object.values(config.domains).some((mods) =>
+    mods.some((m) => typeof m === "function"),
+  );
+  // FAIL-CLOSED: a thunked (lazy) entry cannot resolve type/relation-keyed
+  // dispatches without the compiler-emitted routing table. Refuse at top level —
+  // at lump-build/install time, never silently at dispatch.
+  if (lazy && config.routing === undefined) {
+    throw new Error(
+      "engine bundle: lazy domain thunks require the compiler-emitted routing table " +
+        "(registerEngine config.routing) — recompile with nomos-compile.",
+    );
   }
+  const routing: EngineRouting = config.routing ?? {};
 
-  // ── (domain, directiveId) → {directive, agg} ──────────────────────────────────
-  const REGISTRY = new Map<string, RegistryEntry>();
-  for (const [domainName, mod] of mergedByDomain) {
-    const aggs = aggregatesOf(mod);
-    const dirs = directivesOf(mod);
-    for (const [dirId, directive] of dirs) {
-      const agg = aggs.get(directive.aggregateId);
-      if (agg === undefined) {
-        // A directive targeting an aggregate not exported by its module is an
-        // authoring bug; surface it lazily (only if that directive is invoked).
-        continue;
-      }
-      REGISTRY.set(`${domainName}\u0000${dirId}`, { directive, agg });
-    }
+  // ── domain key → its slice (forced once per sandbox; eager boot forces ALL now) ──
+  const sliceCache = new Map<string, DomainSlice>();
+  function sliceOf(domainName: string): DomainSlice | undefined {
+    const cached = sliceCache.get(domainName);
+    if (cached !== undefined) return cached;
+    const sources = config.domains[domainName];
+    if (sources === undefined) return undefined;
+    const forced = sources.map((m) => (typeof m === "function" ? m() : m));
+    const slice = buildDomainSlice(mergeModules(forced));
+    sliceCache.set(domainName, slice);
+    return slice;
   }
+  if (!lazy) for (const domainName of domainNames) sliceOf(domainName);
 
-  // ── aggregate type → derived / combined decls (fn bodies ship HERE, never the ledger) ──
-  const DERIVED_REGISTRY = new Map<string, DerivedDecl[]>();
-  const COMBINED_REGISTRY = new Map<string, CombinedDecl[]>();
-  for (const mod of mergedByDomain.values()) {
-    for (const d of derivedsOf(mod)) {
-      const list = DERIVED_REGISTRY.get(d.of) ?? [];
-      list.push(d);
-      DERIVED_REGISTRY.set(d.of, list);
-    }
-    for (const c of combinedsOf(mod)) {
-      const list = COMBINED_REGISTRY.get(c.of) ?? [];
-      list.push(c);
-      COMBINED_REGISTRY.set(c.of, list);
-    }
-  }
-
-  // ── relation id → cross-workspace invariant body (off the directives' declaredRelations) ──
-  const INVARIANT_REGISTRY = new Map<string, InvariantBody>();
-  for (const { directive } of REGISTRY.values()) {
-    const relations = (directive as { declaredRelations?: unknown }).declaredRelations;
-    if (!Array.isArray(relations)) continue;
-    for (const rel of relations) {
-      const r = rel as { id?: unknown; hasInvariant?: unknown; invariant?: unknown };
-      if (typeof r.id !== "string" || r.hasInvariant !== true) continue;
-      if (typeof r.invariant !== "function") {
-        // A relation declaring `hasInvariant` MUST ship an executable body — fail-closed.
-        throw new Error(
-          `engine bundle: relation "${r.id}" declares hasInvariant but ships no executable ` +
-            `invariant body — the gate would have nothing to evaluate (cross_workspace.md §2.1).`,
-        );
-      }
-      INVARIANT_REGISTRY.set(r.id, r.invariant as InvariantBody);
-    }
-  }
-
-  // ── aggregate type → aggregate-invariant body — from the SAME map (no second list) ──
-  const AGG_INVARIANT_REGISTRY = new Map<string, AggregateInvariantFn>();
-  for (const mod of mergedByDomain.values()) {
-    for (const v of Object.values(mod)) {
-      if (
-        v &&
-        typeof v === "object" &&
-        (v as { __isAggregateHandle?: boolean }).__isAggregateHandle === true &&
-        (v as { hasInvariant?: boolean }).hasInvariant === true
-      ) {
-        const h = v as AggregateHandle & { invariant?: AggregateInvariantFn };
-        if (typeof h.invariant !== "function") {
-          // A handle declaring `hasInvariant` MUST ship an executable body — fail-closed.
-          throw new Error(
-            `engine bundle: aggregate "${h.id}" declares hasInvariant but ships no executable ` +
-              `invariant body — the gate would have nothing to evaluate (#250).`,
-          );
-        }
-        AGG_INVARIANT_REGISTRY.set(h.id, h.invariant);
-      }
-    }
+  /**
+   * The domain keys a type/relation-keyed dispatch consults, IN DECLARATION ORDER
+   * (the fold order the eager registries had): the routed list when a routing map
+   * is present (lazy — force only the declaring domains), else every domain (eager).
+   */
+  function domainsFor(map: Record<string, readonly string[]> | undefined, key: string): readonly string[] {
+    if (map !== undefined) return map[key] ?? [];
+    return domainNames;
   }
 
   const REPORTS: Record<string, (actor: string) => EngineReport> = config.reports ?? {};
@@ -278,7 +412,12 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
         `engine invariant: job.intent.invariant must carry {relation}; got ${JSON.stringify(job.intent)}`,
       );
     }
-    const body = INVARIANT_REGISTRY.get(relationId);
+    // Later domain wins (the Map.set fold order of the one flat registry).
+    let body: InvariantBody | undefined;
+    for (const domainName of domainsFor(routing.relationOf, relationId)) {
+      const found = sliceOf(domainName)?.invariants.get(relationId);
+      if (found !== undefined) body = found;
+    }
     if (body === undefined) {
       throw new Error(`engine invariant: no invariant registered for relation "${relationId}"`);
     }
@@ -303,7 +442,12 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
         `engine aggregateInvariant: job.intent.aggregateInvariant must carry {of}; got ${JSON.stringify(job.intent)}`,
       );
     }
-    const body = AGG_INVARIANT_REGISTRY.get(aggregateType);
+    // Later domain wins (the Map.set fold order of the one flat registry).
+    let body: AggregateInvariantFn | undefined;
+    for (const domainName of domainsFor(routing.aggregateInvariantOf, aggregateType)) {
+      const found = sliceOf(domainName)?.aggInvariants.get(aggregateType);
+      if (found !== undefined) body = found;
+    }
     // VACUOUS HOLDS: a type with NO declared invariant trivially holds — `{accept:true}`,
     // NOT a throw (the oracle fails CLOSED on a throw, wrongly rejecting every create).
     if (body === undefined) {
@@ -324,7 +468,11 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
         `engine derive: job.intent.derive must carry {of}; got ${JSON.stringify(job.intent)}`,
       );
     }
-    const fields = DERIVED_REGISTRY.get(ofType) ?? [];
+    // Domain declaration order, then module export order — the eager fold order.
+    const fields: DerivedDecl[] = [];
+    for (const domainName of domainsFor(routing.derivedOf, ofType)) {
+      fields.push(...(sliceOf(domainName)?.deriveds.get(ofType) ?? []));
+    }
     const prior = (job.priorState ?? {}) as Record<string, unknown>;
     const out: Record<string, unknown> = {};
     for (const d of fields) {
@@ -345,7 +493,11 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
         `engine combine: job.intent.combine must carry {of}; got ${JSON.stringify(job.intent)}`,
       );
     }
-    const fields = COMBINED_REGISTRY.get(ofType) ?? [];
+    // Domain declaration order, then module export order — the eager fold order.
+    const fields: CombinedDecl[] = [];
+    for (const domainName of domainsFor(routing.combinedOf, ofType)) {
+      fields.push(...(sliceOf(domainName)?.combineds.get(ofType) ?? []));
+    }
     const owner = (job.priorState ?? {}) as Record<string, unknown>;
     // Preferred: related rows keyed by combined field id (iteration-order independent);
     // the array path remains for older callers (declaration order).
@@ -429,7 +581,8 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
         `engine plan: job.intent must carry {domain, directiveId}; got ${JSON.stringify(intent)}`,
       );
     }
-    const entry = REGISTRY.get(`${domain}\u0000${directiveId}`);
+    // The plan dispatch IS domain-keyed: force only the dispatched domain.
+    const entry = sliceOf(domain)?.registry.get(directiveId);
     if (entry === undefined) {
       throw new Error(`engine plan: no directive registered for (${domain}, ${directiveId})`);
     }