@githolon/dsl 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -19,6 +19,8 @@
     "./manifest": "./src/manifest.ts",
     "./compose": "./src/compose.ts",
     "./usd": "./src/usd.ts",
+    "./usd-layers": "./src/usd_layers.ts",
+    "./usd-state": "./src/usd_state.ts",
     "./engine-entry": "./src/engine_entry.ts",
     "./build-package": "./src/build_package.ts",
     "./compile-engine": "./src/compile_engine.ts",

package/src/compile_package_main.ts

@@ -64,15 +64,25 @@ import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 import type { ImpureCapabilityDecl } from "./codegen_provider_dart.js";
 import {
+  aggregatesOf,
   buildIdentity,
   buildReadManifest,
   composeDomainModule,
+  directivesOf,
   emitUsdJsonForModules,
   packageUsda,
   sha256HexUtf8,
   writeIdentity,
   type Mod,
 } from "./build_package.js";
+import { collectEngineRouting } from "./engine_entry.js";
+import {
+  emitLayeredDomain,
+  flattenLayeredUsd,
+  layeredRootUsda,
+  type LayeredModuleInput,
+} from "./usd_layers.js";
+import type { UsdLayer } from "./usd.js";
 import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
 import { generateTsProof } from "./codegen_proof.js";
 
@@ -111,6 +121,17 @@ interface PackageConfig {
    * can vendor the directory as-is, no pub deps.
    */
   readonly dart?: boolean | { readonly out?: string };
+  /**
+   * OPT-IN layered USD emission (also `--layered` on the CLI). When true, ALSO emit
+   * `build/layers/<domain>--<module>.usda` (+ `.layer.json`) — one REAL USD layer per
+   * authored MODULE — and `build/<name>.layered.usda`, a root whose subLayers stack
+   * them (USD strongest-first == Nomos module order reversed). The flattened
+   * `.package.usda` emission and the domainHash DO NOT MOVE; the compile asserts
+   * fail-closed that the layer stack flattens BYTE-IDENTICALLY to the canonical
+   * composed IR (the monoid homomorphism — see `usd_layers.ts` /
+   * `docs/usd_layered_composition.md`).
+   */
+  readonly layered?: boolean;
 }
 
 function fail(msg: string): never {
@@ -283,7 +304,9 @@ function emitDart(modules: readonly DomainModule[], dartOut: string): string[] {
 // ── main ──────────────────────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
-  const configArg = process.argv[2] ?? "nomos.package.mjs";
+  const argv = process.argv.slice(2);
+  const layeredFlag = argv.includes("--layered");
+  const configArg = argv.find((a) => !a.startsWith("--")) ?? "nomos.package.mjs";
   const configPath = path.resolve(process.cwd(), configArg);
   if (!existsSync(configPath)) fail(`config not found: ${configPath}`);
   const cfgDir = path.dirname(configPath);
@@ -304,9 +327,21 @@ async function main(): Promise<void> {
   mkdirSync(outDir, { recursive: true });
 
   // ── import + compose each domain ──
+  // LAZY PER-DOMAIN BOOT (#34): the generated entry registers each domain's modules
+  // as `() => require("…")` THUNKS — esbuild lazy-wraps every required module
+  // (`__esm` init at the require call, not at bundle top level), so a fresh
+  // per-plan sandbox boots ONLY the domain the dispatched intent touches. The
+  // routing table for type/relation-keyed dispatches is computed below by the
+  // SAME scans the engine registries run (`collectEngineRouting` — one machinery).
+  // `NOMOS_LUMP_BOOT=eager` keeps the pre-#34 whole-law top-level boot (static
+  // imports, no routing) — the equivalence baseline the #34 suite compares against.
+  const eagerLump = process.env.NOMOS_LUMP_BOOT === "eager";
   const entryImports: string[] = [];
   const entryDomains: string[] = [];
+  const routingInput: Record<string, Mod[]> = {};
   const domainModules: DomainModule[] = [];
+  const layered = layeredFlag || cfg.layered === true;
+  const layeredDomains: { key: string; inputs: LayeredModuleInput[] }[] = [];
   let importSeq = 0;
 
   for (const d of cfg.domains) {
@@ -314,17 +349,22 @@ async function main(): Promise<void> {
       fail(`each domain needs { key, modules: [path, ...] }; got ${JSON.stringify(d)}`);
     }
     const mods: Mod[] = [];
-    const varNames: string[] = [];
+    const sourceExprs: string[] = [];
     for (const rel of d.modules) {
       const abs = path.resolve(cfgDir, rel);
       if (!existsSync(abs)) fail(`domain '${d.key}': module not found: ${abs}`);
       const m = (await import(pathToFileURL(abs).href)) as Mod;
       mods.push(m);
-      const v = `m${importSeq++}`;
-      varNames.push(v);
-      entryImports.push(`import * as ${v} from ${JSON.stringify(abs)};`);
+      if (eagerLump) {
+        const v = `m${importSeq++}`;
+        sourceExprs.push(v);
+        entryImports.push(`import * as ${v} from ${JSON.stringify(abs)};`);
+      } else {
+        sourceExprs.push(`() => require(${JSON.stringify(abs)})`);
+      }
     }
-    entryDomains.push(`    ${JSON.stringify(d.key)}: [${varNames.join(", ")}],`);
+    entryDomains.push(`    ${JSON.stringify(d.key)}: [${sourceExprs.join(", ")}],`);
+    routingInput[d.key] = mods;
 
     let merged: Mod = {};
     for (const m of mods) merged = { ...merged, ...m };
@@ -375,6 +415,51 @@ async function main(): Promise<void> {
         ...(spatials.length > 0 ? { spatials } : {}),
       }),
     );
+
+    // ── opt-in: ONE USD LAYER PER MODULE (Φ applied per module, not once over the
+    //    composed fold) — the layered emission `usd_layers.ts` proves flattens back
+    //    to the EXACT canonical IR (asserted below, fail-closed). Per-module decls
+    //    are discovered the same way as above, on each module's OWN exports; config
+    //    export-names resolve on whichever module actually exports them; config
+    //    `extraAggregates` ride the FIRST (weakest) layer, prelude-style. Counts /
+    //    sums / spatials never enter the USD IR, so they have no layer placement.
+    if (layered) {
+      const usedStems = new Set<string>();
+      const inputs: LayeredModuleInput[] = mods.map((m, i) => {
+        let stem = path.basename(d.modules[i]!).replace(/\.[^.]*$/, "");
+        for (let n = 2; usedStems.has(stem); n++) stem = `${stem}-${n}`;
+        usedStems.add(stem);
+
+        const presentNames = (names: readonly string[] | undefined) =>
+          (names ?? []).filter((n) => (m as Record<string, unknown>)[n] !== undefined);
+        const layerQueries = [
+          ...discover<QueryDecl>(m, isQueryDecl),
+          ...resolveNamed<QueryDecl>(m, presentNames(d.queries), "queries"),
+        ];
+        const layerDeriveds = [
+          ...discover<DerivedDecl>(m, isDerivedDecl),
+          ...resolveNamed<DerivedDecl>(m, presentNames(d.deriveds), "deriveds"),
+        ];
+        const layerCombineds = [
+          ...discover<CombinedDecl>(m, isCombinedDecl),
+          ...resolveNamed<CombinedDecl>(m, presentNames(d.combineds), "combineds"),
+        ];
+        const byId = new Map<string, AggregateHandle>();
+        for (const a of [...aggregatesOf(m), ...(i === 0 ? extraAggregates : [])]) byId.set(a.id, a);
+
+        const module: DomainModule = {
+          name: d.name ?? d.key,
+          domain: d.key,
+          aggregates: [...byId.values()],
+          directives: directivesOf(m),
+          ...(layerQueries.length > 0 ? { queries: layerQueries } : {}),
+          ...(layerDeriveds.length > 0 ? { deriveds: layerDeriveds } : {}),
+          ...(layerCombineds.length > 0 ? { combineds: layerCombineds } : {}),
+        };
+        return { name: stem, module };
+      });
+      layeredDomains.push({ key: d.key, inputs });
+    }
   }
 
   // ── reports ──
@@ -384,14 +469,76 @@ async function main(): Promise<void> {
     if (!rel || !exportName) fail(`report '${reportId}' must be "modulePath#exportName"; got '${ref}'`);
     const abs = path.resolve(cfgDir, rel);
     if (!existsSync(abs)) fail(`report '${reportId}': module not found: ${abs}`);
-    const v = `r${importSeq++}`;
-    entryImports.push(`import * as ${v} from ${JSON.stringify(abs)};`);
-    entryReports.push(`    ${JSON.stringify(reportId)}: ${v}.${exportName},`);
+    if (eagerLump) {
+      const v = `r${importSeq++}`;
+      entryImports.push(`import * as ${v} from ${JSON.stringify(abs)};`);
+      entryReports.push(`    ${JSON.stringify(reportId)}: ${v}.${exportName},`);
+    } else {
+      // A lazy report factory: the module's `__esm` init runs on first render call.
+      entryReports.push(
+        `    ${JSON.stringify(reportId)}: (actor: string) => (require(${JSON.stringify(abs)}) as any).${exportName}(actor),`,
+      );
+    }
   }
 
   // ── 1. generate + bundle the engine entry ──
+  // The routing table is computed by the SAME duck-type scans the engine registries
+  // run, over the SAME imported modules (collectEngineRouting — one machinery, so a
+  // law whose invariant declarations are inconsistent refuses to COMPILE, and the
+  // table can never disagree with what a full force would register).
+  const routing = collectEngineRouting(routingInput);
+  // AMBIENT-SLOT SEEDING (lazy boot only): zod v4 writes
+  // `globalThis.__zod_global{Config,Registry}` at MODULE INIT. The sealed sandbox
+  // freezes globalThis after the lump's top level — an eager lump's zod init ran
+  // pre-freeze, but a lazy lump would init zod inside the dispatch, post-freeze,
+  // and the frozen global refuses the new slots. So the entry eagerly imports the
+  // TWO tiny zod core modules that own those writes (resolved to the same files
+  // the domain modules' `zod` import reaches — same esbuild module instances);
+  // the heavy classic schema graph stays deferred. The frozen-sandbox boot probe
+  // below fail-closes the compile if any OTHER module writes globals at lazy init.
+  // Namespace imports + a `seeds` call argument (NOT bare side-effect imports):
+  // zod ships `sideEffects: false`, so esbuild would tree-shake a bare import away;
+  // passing the namespaces into the registerEngine CALL forces their init at the
+  // entry's top level — pre-freeze, exactly where the eager lump ran them.
+  const zodSeedImports: string[] = [];
+  const zodSeedNames: string[] = [];
+  if (!eagerLump) {
+    const zodPkgJson = [cfgDir, DSL_DIR]
+      .map((dir) => {
+        try {
+          return createRequire(pathToFileURL(path.join(dir, "noop.js"))).resolve("zod/package.json");
+        } catch {
+          return undefined;
+        }
+      })
+      .find((p): p is string => p !== undefined);
+    const zodCoreFiles = zodPkgJson
+      ? ["core.js", "registries.js"].map((f) => path.join(path.dirname(zodPkgJson), "v4", "core", f))
+      : [];
+    const seedFiles =
+      zodCoreFiles.length > 0 && zodCoreFiles.every((f) => existsSync(f))
+        ? zodCoreFiles
+        : zodPkgJson !== undefined
+          ? // Unknown zod layout — seed by initializing the whole library at top
+            // level (loses some laziness, never correctness).
+            ["zod"]
+          : [];
+    for (const f of seedFiles) {
+      const v = `__seed${zodSeedNames.length}`;
+      zodSeedImports.push(`import * as ${v} from ${JSON.stringify(f)};`);
+      zodSeedNames.push(v);
+    }
+  }
   const entrySource = [
     `// AUTO-GENERATED by nomos-compile from ${path.basename(configPath)} — do not edit.`,
+    ...(eagerLump
+      ? []
+      : [
+          `// LAZY PER-DOMAIN BOOT (#34): each domain registers as require-thunks; esbuild`,
+          `// defers every module's init to its first dispatch touch inside the fresh sandbox.`,
+          `declare function require(id: string): Record<string, unknown>;`,
+          ...zodSeedImports,
+        ]),
     ...entryImports,
     `import { registerEngine } from "@githolon/dsl/engine-entry";`,
     ``,
@@ -400,6 +547,8 @@ async function main(): Promise<void> {
     ...entryDomains,
     `  },`,
     ...(entryReports.length > 0 ? [`  reports: {`, ...entryReports, `  },`] : []),
+    ...(eagerLump ? [] : [`  routing: ${JSON.stringify(routing)},`]),
+    ...(zodSeedNames.length > 0 ? [`  seeds: [${zodSeedNames.join(", ")}],`] : []),
     `});`,
     ``,
   ].join("\n");
@@ -436,6 +585,57 @@ async function main(): Promise<void> {
     fail(`bundled engine entry does not assign globalThis.plan — refusing to package`);
   }
 
+  // ── 1b. THE FROZEN-SANDBOX BOOT PROBE (lazy boot only, fail-closed) ──
+  // The sealed engine freezes globalThis after the lump's top level; a lazy
+  // domain's module init runs LATER, inside the dispatch. Any module that writes
+  // an ambient global at init (the zod slots are pre-seeded above; this guards
+  // everything else) would deterministically throw at FIRST DISPATCH in
+  // production. Reproduce the sandbox order here — eval the real bundle in a
+  // fresh frozen context, then force every domain — and refuse to package on any
+  // failure that is not the expected unknown-directive refusal.
+  if (!eagerLump) {
+    // A CHILD process: the probe must freeze a REAL global object (a `vm` context
+    // global refuses Object.freeze), and the lump must run STRICT (the engine
+    // evals it with the STRICT flag — sloppy mode would silently no-op the very
+    // frozen-global writes the probe exists to catch).
+    const lumpPath = path.join(outDir, ".nomos_lump.js");
+    writeFileSync(lumpPath, javascript, "utf8");
+    const probePath = path.join(outDir, ".nomos_boot_probe.cjs");
+    writeFileSync(
+      probePath,
+      [
+        `// AUTO-GENERATED by nomos-compile — the frozen-sandbox lazy-boot probe.`,
+        `const fs = require("node:fs");`,
+        `const lump = fs.readFileSync(process.argv[2], "utf8");`,
+        `const domains = JSON.parse(process.argv[3]);`,
+        `(0, eval)('"use strict";\\n' + lump); // indirect eval → real global scope, strict like the engine`,
+        `Object.freeze(globalThis);            // the sealed sandbox freezes before dispatch`,
+        `for (const key of domains) {`,
+        `  let msg;`,
+        `  try { globalThis.plan({ intent: { domain: key, directiveId: "__nomos_boot_probe__" } }); msg = "unexpected-success"; }`,
+        `  catch (e) { msg = String((e && e.message) || e); }`,
+        `  if (!/no directive registered/.test(msg)) { console.error(key + "\\u0000" + msg); process.exit(3); }`,
+        `}`,
+        ``,
+      ].join("\n"),
+      "utf8",
+    );
+    try {
+      execFileSync(process.execPath, [probePath, lumpPath, JSON.stringify(cfg.domains.map((d) => d.key))], {
+        encoding: "utf8",
+        stdio: ["ignore", "ignore", "pipe"],
+      });
+    } catch (e) {
+      const stderr = String((e as { stderr?: string }).stderr ?? "").trim();
+      const [domainKey, msg] = stderr.includes("\u0000") ? stderr.split("\u0000") : ["?", stderr];
+      fail(
+        `domain '${domainKey}' failed its frozen-sandbox lazy-boot probe — a module ` +
+          `initializer touches ambient globals after the freeze (the engine would ` +
+          `refuse its first dispatch): ${msg}`,
+      );
+    }
+  }
+
   // ── 2. USD IR + the package envelope ──
   const usdJson = emitUsdJsonForModules(domainModules);
   const text = packageUsda(usdJson, javascript);
@@ -443,6 +643,48 @@ async function main(): Promise<void> {
   writeFileSync(pkgPath, text, "utf8");
   const domainHash = sha256HexUtf8(text);
 
+  // ── 2b. opt-in LAYERED emission — additive artifacts ONLY (the flattened package
+  //        above and its domainHash are already written and do not move). The
+  //        homomorphism is ASSERTED fail-closed on every layered compile: the
+  //        per-module layer stack must flatten BYTE-IDENTICALLY to the canonical
+  //        composed IR embedded in the package, or nothing layered is emitted.
+  let layeredRootPath: string | undefined;
+  let layeredFileCount = 0;
+  if (layered) {
+    const safe = (s: string) => s.replace(/[^A-Za-z0-9._-]/g, "_");
+    const layersDir = path.join(outDir, "layers");
+    mkdirSync(layersDir, { recursive: true });
+    const allLayers: UsdLayer[] = [];
+    const relPaths: string[] = [];
+    const pendingWrites: { path: string; text: string }[] = [];
+    for (const ld of layeredDomains) {
+      for (const emitted of emitLayeredDomain(ld.key, ld.inputs)) {
+        const base = `${safe(ld.key)}--${safe(emitted.name)}`;
+        pendingWrites.push({ path: path.join(layersDir, `${base}.usda`), text: emitted.usda });
+        pendingWrites.push({
+          path: path.join(layersDir, `${base}.layer.json`),
+          text: JSON.stringify(emitted.layer) + "\n",
+        });
+        allLayers.push(emitted.layer);
+        relPaths.push(`layers/${base}.usda`);
+      }
+    }
+    const flatJson = JSON.stringify(flattenLayeredUsd(allLayers));
+    if (flatJson !== usdJson) {
+      fail(
+        `layered emission does not flatten to the canonical composed IR — the module fold and ` +
+          `the layer-stack fold DISAGREE for this package (usually a re-declared directive ` +
+          `silently dropping an omit-when-empty reads/emits boundary, or a re-declared ` +
+          `aggregate dropping a field: USD shows the weaker opinion through; the module fold ` +
+          `does not). Refusing to emit the layered artifact (the flattened package is unaffected).`,
+      );
+    }
+    for (const w of pendingWrites) writeFileSync(w.path, w.text, "utf8");
+    layeredRootPath = path.join(outDir, `${cfg.name}.layered.usda`);
+    writeFileSync(layeredRootPath, layeredRootUsda(relPaths), "utf8");
+    layeredFileCount = relPaths.length;
+  }
+
   // ── 3. the READ manifest + IDENTITY artifacts ──
   const readManifest = buildReadManifest(domainModules);
   const readPath = path.join(outDir, "domain_manifests.json");
@@ -536,6 +778,11 @@ async function main(): Promise<void> {
   console.log(`nomos-compile: ${cfg.name}`);
   console.log(`  package    ${rel(pkgPath)} (${text.length} bytes)`);
   console.log(`  domainHash ${domainHash}`);
+  if (layeredRootPath !== undefined) {
+    console.log(
+      `  layered    ${rel(layeredRootPath)} (${layeredFileCount} module layer(s) in build/layers/ — flatten-verified byte-identical to the canonical IR)`,
+    );
+  }
   console.log(`  read       ${rel(readPath)} (${Object.keys(readManifest.aggregateFieldKinds).length} aggregate(s), ${readManifest.queries.length} quer(y/ies), ${readManifest.counts.length} count(s))`);
   console.log(`  identity   ${rel(manifestsPath)} (${Object.keys(identity.manifests).length} domain(s)${identity.excluded.length ? `, ${identity.excluded.length} EXCLUDED (palette gap)` : ""})`);
   for (const [dom, h] of Object.entries(identity.hashes)) console.log(`             ${dom.padEnd(20)} ${h}`);