@githolon/dsl 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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

@@ -55,7 +55,13 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import type { AggregateHandle } from "./aggregate.js";
-import { generateDartDomain, type DomainModule } from "./codegen_dart.js";
+import {
+  generateDartDomain,
+  type DartImport,
+  type DartRefImport,
+  type DomainModule,
+  type PermissionVocabulary,
+} from "./codegen_dart.js";
 import type { AnyCount } from "./count.js";
 import type { QueryDecl } from "./query.js";
 import type { SpatialDecl } from "./spatial.js";
@@ -64,15 +70,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";
 
@@ -92,6 +108,23 @@ interface DomainConfig {
   readonly impureCapabilities?: readonly string[];
   readonly extraAggregates?: readonly string[];
   readonly readModelAggregates?: readonly string[];
+  // DART CODEGEN HINTS (#codegen_dart; NEVER law: none of these enter the USD IR,
+  // the package bytes, or the identity manifest — they shape ONLY the generated
+  // `dart/` frontend, so adding them does not move the domainHash):
+  /** LITERAL extra imports for the generated `<domain>.dart` (e.g. a sibling
+   * domain file whose types this domain's payloads reference). */
+  readonly dartImports?: readonly DartImport[];
+  /** LITERAL cross-domain read-model routing: an aggregate TYPE this domain
+   * references resolves through the named import prefix instead of a local decl. */
+  readonly dartRefImports?: readonly DartRefImport[];
+  /** EXPORT-NAME escape hatch (resolved on the merged module exports, like
+   * `impureCapabilities`): `resourceTypes` names a `readonly string[]` export and
+   * `roleCatalogue` a `Record<string, string[]>` export; together they emit the
+   * frontend permission vocabulary (PermissionRoles/PermissionCapabilities). */
+  readonly permissionVocabulary?: {
+    readonly resourceTypes: string;
+    readonly roleCatalogue: string;
+  };
 }
 
 interface PackageConfig {
@@ -111,6 +144,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 {
@@ -207,6 +251,66 @@ function discover<T>(merged: Mod, match: (v: unknown) => v is T): T[] {
   return out;
 }
 
+/** Validate the LITERAL dart-codegen import hints (config data, not module exports). */
+function checkDartImports(domainKey: string, imports: readonly DartImport[] | undefined): void {
+  for (const imp of imports ?? []) {
+    if (typeof imp?.uri !== "string" || (imp.prefix !== undefined && typeof imp.prefix !== "string")) {
+      fail(`domain '${domainKey}': each dartImports entry must be { uri, prefix? }; got ${JSON.stringify(imp)}`);
+    }
+  }
+}
+
+function checkDartRefImports(domainKey: string, imports: readonly DartRefImport[] | undefined): void {
+  for (const imp of imports ?? []) {
+    if (
+      typeof imp?.aggregateType !== "string" ||
+      typeof imp?.uri !== "string" ||
+      typeof imp?.prefix !== "string"
+    ) {
+      fail(
+        `domain '${domainKey}': each dartRefImports entry must be { aggregateType, uri, prefix }; got ${JSON.stringify(imp)}`,
+      );
+    }
+  }
+}
+
+/** Resolve the permissionVocabulary EXPORT NAMES on the merged exports, fail-closed. */
+function resolvePermissionVocabulary(
+  domainKey: string,
+  merged: Mod,
+  cfg: DomainConfig["permissionVocabulary"],
+): PermissionVocabulary | undefined {
+  if (cfg === undefined) return undefined;
+  if (typeof cfg?.resourceTypes !== "string" || typeof cfg?.roleCatalogue !== "string") {
+    fail(
+      `domain '${domainKey}': permissionVocabulary must be { resourceTypes: "<exportName>", roleCatalogue: "<exportName>" }; got ${JSON.stringify(cfg)}`,
+    );
+  }
+  const resourceTypes = merged[cfg.resourceTypes];
+  if (!Array.isArray(resourceTypes) || !resourceTypes.every((t) => typeof t === "string")) {
+    fail(
+      `domain '${domainKey}': permissionVocabulary.resourceTypes names export '${cfg.resourceTypes}', which the modules do not export as a string[]`,
+    );
+  }
+  const roleCatalogue = merged[cfg.roleCatalogue];
+  if (
+    !roleCatalogue ||
+    typeof roleCatalogue !== "object" ||
+    Array.isArray(roleCatalogue) ||
+    !Object.values(roleCatalogue).every(
+      (caps) => Array.isArray(caps) && caps.every((c) => typeof c === "string"),
+    )
+  ) {
+    fail(
+      `domain '${domainKey}': permissionVocabulary.roleCatalogue names export '${cfg.roleCatalogue}', which the modules do not export as a Record<string, string[]>`,
+    );
+  }
+  return {
+    resourceTypes: resourceTypes as string[],
+    roleCatalogue: roleCatalogue as Record<string, string[]>,
+  };
+}
+
 /** Resolve explicit EXPORT NAMES (the config escape hatch) on the merged exports. */
 function resolveNamed<T>(merged: Mod, names: readonly string[] | undefined, what: string): T[] {
   const out: T[] = [];
@@ -283,7 +387,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 +410,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 +432,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 };
@@ -357,6 +480,11 @@ async function main(): Promise<void> {
     );
     const extraAggregates = resolveNamed<AggregateHandle>(merged, d.extraAggregates, "extraAggregates");
 
+    // Dart-codegen hints (frontend-only — never law; see DomainConfig):
+    checkDartImports(d.key, d.dartImports);
+    checkDartRefImports(d.key, d.dartRefImports);
+    const permissionVocabulary = resolvePermissionVocabulary(d.key, merged, d.permissionVocabulary);
+
     domainModules.push(
       composeDomainModule({
         name: d.name ?? d.key,
@@ -373,8 +501,60 @@ async function main(): Promise<void> {
         ...(impureCapabilities.length > 0 ? { impureCapabilities } : {}),
         ...(sums.length > 0 ? { sums } : {}),
         ...(spatials.length > 0 ? { spatials } : {}),
+        ...(d.dartImports !== undefined && d.dartImports.length > 0
+          ? { dartImports: d.dartImports }
+          : {}),
+        ...(d.dartRefImports !== undefined && d.dartRefImports.length > 0
+          ? { dartRefImports: d.dartRefImports }
+          : {}),
+        ...(permissionVocabulary !== undefined ? { permissionVocabulary } : {}),
       }),
     );
+
+    // ── 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 +564,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 +642,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 +680,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 +738,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 +873,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}`);