@githolon/dsl 0.45.0 → 0.47.0

package/src/compile_package_main.ts

@@ -108,7 +108,7 @@ import {
   layeredRootUsda,
   type LayeredModuleInput,
 } from "./usd_layers.js";
-import { domainManifest } from "./manifest.js";
+import { domainManifest, canonicalJson } from "./manifest.js";
 import type { WireSchema } from "./wire.js";
 import {
   deriveStableIdContinuity,
@@ -121,6 +121,7 @@ import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
 import { generateOpenApiFragment, mergeOpenApiFragments } from "./codegen_openapi.js";
 import { domainInterface, type DomainInterface } from "./shape_compat.js";
 import { generateTsProof, proofLegsIndex } from "./codegen_proof.js";
+import type { NomosCompat } from "./compat_manifest.js";
 
 const DSL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -187,7 +188,19 @@ interface PackageConfig {
    * `package:nomos_client/...` import is rewritten to a relative one) — so a Flutter app
    * can vendor the directory as-is, no pub deps.
    */
-  readonly dart?: boolean | { readonly out?: string; readonly support?: DartSupportImport };
+  readonly dart?:
+    | boolean
+    | {
+        readonly out?: string;
+        readonly support?: DartSupportImport;
+        /**
+         * Basename (no `.dart`) of the generated PACKAGE BARREL — the stable public facade emitted at
+         * `<out>/<barrel>.dart` over the `src/generated/` files. Set it to the pub package name (so
+         * `package:co2_nomos_domains/co2_nomos_domains.dart` resolves); defaults to the snake_cased
+         * config `name`.
+         */
+        readonly barrel?: 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
@@ -372,9 +385,22 @@ const DART_SUPPORT_SRC = [
  *  (a real `nomos_client` pub dep) keeps the full barrel. */
 const VENDORED_BARREL_EXCLUDES = ["src/schema_validation.dart", "src/home.dart"] as const;
 
-function removeVendoredDartSupport(dartOut: string): void {
+/** The generated-owned subdirectory, relative to `dartOut` (the pub package's `lib/`). WIPED and
+ *  rewritten on every compile — nothing hand-written may live in it. The stable facade (the package
+ *  barrel) stays at `dartOut/<barrel>.dart`, so a prune/regenerate can never orphan app imports. */
+const DART_GENERATED_SUBDIR = path.join("src", "generated");
+
+/** Remove the PRE-barrel flat layout's generated files from `dartOut` root (they now live under
+ *  `src/generated/`): the vendored support set + the per-domain files. Targeted by exact known
+ *  name — `dartOut` is typically the tenant package's `lib/`, so never sweep directories. */
+function removeLegacyFlatDartLayout(dartOut: string, moduleNames: readonly string[]): void {
   rmSync(path.join(dartOut, "nomos_client.dart"), { force: true });
-  rmSync(path.join(dartOut, "src"), { recursive: true, force: true });
+  rmSync(path.join(dartOut, "nomos_framework.dart"), { force: true });
+  for (const f of DART_SUPPORT_SRC) rmSync(path.join(dartOut, "src", f), { force: true });
+  for (const name of moduleNames) {
+    rmSync(path.join(dartOut, `${name}.dart`), { force: true });
+    rmSync(path.join(dartOut, `${name}.client.dart`), { force: true });
+  }
 }
 
 /**
@@ -382,6 +408,10 @@ function removeVendoredDartSupport(dartOut: string): void {
  * `<name>.dart` per domain (the SAME `generateDartDomain` path the co2 tenant's
  * `emit_dart.ts` drives) + the vendored `nomos_client.dart` barrel and its `src/`
  * support files, with the generated files' `package:` import rewritten relative.
+ * Everything lands under `dartOut/src/generated/` (generated-owned, wiped per
+ * compile) behind ONE generated package barrel `dartOut/<barrelName>.dart` — the
+ * analyzer-clean plug-and-play entrypoint (zero `show`/`hide`; framework-shared
+ * symbols dedup into `nomos_framework.dart`, so no export is ambiguous).
  */
 function emitDart(
   modules: readonly DomainModule[],
@@ -389,25 +419,29 @@ function emitDart(
   domainHash: string,
   packageInterface: Record<string, DomainInterface> = {},
   supportImport: DartSupportImport = "vendored",
+  barrelName = "nomos_domains",
+  compat?: NomosCompat,
 ): string[] {
-  mkdirSync(dartOut, { recursive: true });
+  const genDir = path.join(dartOut, DART_GENERATED_SUBDIR);
+  removeLegacyFlatDartLayout(dartOut, modules.map((m) => m.name));
+  rmSync(genDir, { recursive: true, force: true });
+  mkdirSync(genDir, { recursive: true });
 
   // 1. optional vendored framework support (barrel + src/), copied byte-for-byte except
   //    the barrel's schema_validation export (see DART_SUPPORT_SRC).
   if (supportImport === "vendored") {
-    mkdirSync(path.join(dartOut, "src"), { recursive: true });
+    mkdirSync(path.join(genDir, "src"), { recursive: true });
     const libDir = path.join(DSL_DIR, "dart", "lib");
     const barrel = readFileSync(path.join(libDir, "nomos_client.dart"), "utf8")
       .split("\n")
       .filter((line) => !VENDORED_BARREL_EXCLUDES.some((x) => line.includes(x)))
       .join("\n");
-    writeFileSync(path.join(dartOut, "nomos_client.dart"), barrel, "utf8");
+    writeFileSync(path.join(genDir, "nomos_client.dart"), barrel, "utf8");
     for (const f of DART_SUPPORT_SRC) {
-      copyFileSync(path.join(libDir, "src", f), path.join(dartOut, "src", f));
+      copyFileSync(path.join(libDir, "src", f), path.join(genDir, "src", f));
     }
-  } else {
-    removeVendoredDartSupport(dartOut);
   }
+  // (package-support mode vendors nothing — the genDir wipe above already cleared any prior set)
 
   // 2. FRAMEWORK-SHARED symbol dedup (Dart-codegen hygiene). Framework-owned symbols fold into MANY
   //    domains, so their generated Dart would be DEFINED once per domain — a package barrel re-exporting
@@ -468,7 +502,7 @@ function emitDart(
         `generated Dart for '${fileBase}' does not carry the expected support import (${DART_PACKAGE_IMPORT}) — codegen_dart header drifted; fix the rewrite in compile_package_main.ts`,
       );
     }
-    const p = path.join(dartOut, `${fileBase}.dart`);
+    const p = path.join(genDir, `${fileBase}.dart`);
     writeFileSync(
       p,
       supportImport === "vendored" ? src.replace(DART_PACKAGE_IMPORT, DART_RELATIVE_IMPORT) : src,
@@ -533,13 +567,39 @@ function emitDart(
     const clientSrc = generateDartBridgeClient(modForDart, {
       domainHash,
       interface: packageInterface[modForDart.domain ?? modForDart.name],
+      ...(compat !== undefined ? { compat } : {}),
       supportImport,
       ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
     });
-    const cp = path.join(dartOut, `${mod.name}.client.dart`);
+    const cp = path.join(genDir, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");
     written.push(cp);
   }
+
+  // 3. THE PACKAGE BARREL — the stable public facade (`dartOut/<barrelName>.dart`), generated-owned
+  //    and overwritten every compile. ONE import gives an app the support runtime + the shared
+  //    framework surface + every domain's types and client, with ZERO `show`/`hide` (the framework
+  //    dedup above makes the exports collision-free by construction; re-exporting the same library
+  //    through two paths — e.g. a client's own `nomos_framework.dart` re-export — is not ambiguous).
+  const genRel = DART_GENERATED_SUBDIR.split(path.sep).join("/");
+  const barrelLines = [
+    "// GENERATED by nomos-compile — the package's public entrypoint. DO NOT EDIT.",
+    "// Regenerated on every compile; generated implementation lives under src/generated/.",
+    "library;",
+    "",
+    supportImport === "vendored"
+      ? `export '${genRel}/nomos_client.dart';`
+      : `export 'package:nomos_client/nomos_client.dart';`,
+    ...(hasFrameworkSymbols ? [`export '${genRel}/${FRAMEWORK_FILE}.dart';`] : []),
+    ...modules.flatMap((m) => [
+      `export '${genRel}/${m.name}.dart';`,
+      `export '${genRel}/${m.name}.client.dart';`,
+    ]),
+    "",
+  ];
+  const barrelPath = path.join(dartOut, `${barrelName}.dart`);
+  writeFileSync(barrelPath, barrelLines.join("\n"), "utf8");
+  written.push(barrelPath);
   return written;
 }
 
@@ -548,6 +608,9 @@ function emitDart(
 async function main(): Promise<void> {
   const argv = process.argv.slice(2);
   const layeredFlag = argv.includes("--layered");
+  // §"Shipped (1–4)" follow-up: `githolon compile --analyze` (or NOMOS_ANALYZE=1) runs
+  // `dart analyze` on the generated Dart package after emission and fails the compile on red.
+  const analyzeFlag = argv.includes("--analyze") || process.env.NOMOS_ANALYZE === "1";
   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}`);
@@ -1480,6 +1543,34 @@ async function main(): Promise<void> {
   // compute the identity to surface its per-domain hash in the summary below.
   const identity = buildIdentity(domainModules);
 
+  // ── 3a. the CLIENT/LAW COMPATIBILITY MANIFEST (§5, architecture/plug_and_play_dx.md).
+  // A DIAGNOSIS surface, NEVER a gate: the shape-compat arc (#72) established that clients
+  // fit workspaces by STRUCTURAL INTERFACE (stable-id subtyping), not by law-hash pin. This
+  // block is baked into both generated clients (TS + Dart) and mirrored into the deploy JSON
+  // so a connect() can classify silent / shape-compat / incompatible. FRONTEND-ONLY: it is
+  // emitted like the dart codegen hints — it does NOT enter the USD IR / package bytes /
+  // domainHash (the package `text` above is already hashed and does not move).
+  const dslVersion = ((): string => {
+    try {
+      return JSON.parse(readFileSync(path.join(DSL_DIR, "package.json"), "utf8")).version ?? "unknown";
+    } catch {
+      return "unknown";
+    }
+  })();
+  const compatDomains: NomosCompat["domains"] = {};
+  for (const m of domainModules) {
+    const key = m.domain ?? m.name;
+    const identityHash = identity.hashes[key];
+    compatDomains[key] = identityHash === undefined ? {} : { identityHash };
+  }
+  const nomosCompat: NomosCompat = {
+    packageName: cfg.name,
+    lawHash: domainHash,
+    interfaceHash: sha256HexUtf8(canonicalJson(packageInterface)),
+    domains: compatDomains,
+    generator: { dsl: dslVersion, schema: 1 },
+  };
+
   // ── 3b. the OpenAPI spec — THE PACKAGE'S SELF-DESCRIPTION (the host's runtime routing table;
   // architecture/githolon_host_contract.md "The Self-Describing API"). Each domain emits its fragment
   // from its OWN zod (z.toJSONSchema); the package's spec is the law-blind merge. Deploy STAGES it like
@@ -1524,6 +1615,9 @@ async function main(): Promise<void> {
     // THE SELF-DESCRIBING API: this package's OpenAPI spec (law-derived). The worker stages it on the
     // manifest overlay; a read serves the workspace's merged spec; the host builds its router from it.
     openapi,
+    // THE CLIENT/LAW COMPAT MANIFEST (§5): a DIAGNOSIS surface (law hash + interface hash + generator
+    // provenance) the connect-time classifier reads. Frontend-only — the package bytes above ignore it.
+    nomosCompat,
   };
   const deployPath = path.join(outDir, `${cfg.name}.deploy.json`);
   writeFileSync(deployPath, JSON.stringify(deployBody) + "\n", "utf8");
@@ -1535,6 +1629,7 @@ async function main(): Promise<void> {
   let proofPath: string | undefined;
   let proofSkip: string | undefined;
   let proofDomains: string[] = [];
+  let birthWarnings: string[] = [];
   try {
     const proofSrc = generateTsProof(domainModules, { packageName: cfg.name, domainHash });
     proofPath = path.join(outDir, `${cfg.name}.proof.mts`);
@@ -1547,10 +1642,20 @@ async function main(): Promise<void> {
     if (legsIndex !== null) {
       writeFileSync(path.join(outDir, `${cfg.name}.proof-legs.json`), JSON.stringify(legsIndex, null, 2) + "\n", "utf8");
       proofDomains = Object.keys(legsIndex.domains);
+      birthWarnings = Object.values(legsIndex.domains).flatMap((l) => l.birthDiagnostics ?? []);
     }
   } catch (e) {
     proofSkip = (e as Error).message;
   }
+  // BIRTHS DX: a `.births()` directive that can't be (or can only shakily be) proven says WHY here —
+  // never a silent skip, never an opaque runtime `born=[]` first contact. When the .mts generation
+  // itself failed, still derive the per-domain diagnostics (best-effort).
+  if (proofSkip !== undefined && birthWarnings.length === 0) {
+    try {
+      const idx = proofLegsIndex(domainModules);
+      if (idx !== null) birthWarnings = Object.values(idx.domains).flatMap((l) => l.birthDiagnostics ?? []);
+    } catch { /* diagnostics are best-effort */ }
+  }
 
   const summaryTxt = [
     `${cfg.name} — compiled Nomos domain package`,
@@ -1573,7 +1678,7 @@ async function main(): Promise<void> {
   // ── 5. the typed TS client (#10 — the web sibling of codegen_dart), with the
   //       deployed law's content hash baked in (emitted AFTER the package is hashed) ──
   const clientPath = path.join(outDir, `${cfg.name}.client.ts`);
-  writeFileSync(clientPath, generateTsClient(domainModules, { packageName: cfg.name, domainHash, interface: packageInterface }), "utf8");
+  writeFileSync(clientPath, generateTsClient(domainModules, { packageName: cfg.name, domainHash, interface: packageInterface, compat: nomosCompat }), "utf8");
 
   // ── 6. the typed Dart frontend (opt-in; the Flutter sibling of step 5, emitted
   //       after the package hash like the TS client) ──
@@ -1584,10 +1689,11 @@ async function main(): Promise<void> {
     (typeof dartCfg !== "object" ||
       dartCfg === null ||
       (dartCfg.out !== undefined && typeof dartCfg.out !== "string") ||
-      (dartCfg.support !== undefined && dartCfg.support !== "vendored" && dartCfg.support !== "package"))
+      (dartCfg.support !== undefined && dartCfg.support !== "vendored" && dartCfg.support !== "package") ||
+      (dartCfg.barrel !== undefined && !/^[a-z][a-z0-9_]*$/.test(String(dartCfg.barrel))))
   ) {
     fail(
-      `config key 'dart' must be false, true, or { out?: "relative/dir", support?: "vendored" | "package" }; got ${JSON.stringify(dartCfg)}`,
+      `config key 'dart' must be false, true, or { out?: "relative/dir", support?: "vendored" | "package", barrel?: "snake_case_name" }; got ${JSON.stringify(dartCfg)}`,
     );
   }
   const dartSupportImport: DartSupportImport =
@@ -1599,7 +1705,16 @@ async function main(): Promise<void> {
       cfgDir,
       typeof dartCfg === "object" && dartCfg.out !== undefined ? dartCfg.out : path.join(outDir, "dart"),
     );
-    dartFiles = emitDart(domainModules, dartOut, domainHash, packageInterface, dartSupportImport);
+    // The barrel basename: configured, else the snake_cased package name (a valid Dart library
+    // file name — pub packages import `package:<name>/<name>.dart`).
+    const defaultBarrel = cfg.name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "_")
+      .replace(/^_+|_+$/g, "")
+      .replace(/^(?=[0-9])/, "n");
+    const dartBarrel =
+      typeof dartCfg === "object" && dartCfg.barrel !== undefined ? dartCfg.barrel : defaultBarrel;
+    dartFiles = emitDart(domainModules, dartOut, domainHash, packageInterface, dartSupportImport, dartBarrel, nomosCompat);
   }
 
   // ── summary ──
@@ -1645,6 +1760,9 @@ async function main(): Promise<void> {
   } else {
     console.log(`  proof      SKIPPED — ${proofSkip}`);
   }
+  for (const w of birthWarnings) {
+    console.log(`  ⚠ births   ${w}`);
+  }
   if (dartOut !== undefined) {
     const supportText =
       dartSupportImport === "vendored" ? "vendored nomos_client support" : "package nomos_client imports";
@@ -1666,6 +1784,46 @@ async function main(): Promise<void> {
   } else {
     console.log(`prove it: npm run e2e   # offline write -> sync -> admission -> cloud query, live`);
   }
+
+  if (analyzeFlag) runDartAnalyze(dartOut);
+}
+
+/**
+ * `--analyze` (or NOMOS_ANALYZE=1): run `dart analyze` on the generated Dart package so a red
+ * analyze fails the compile loudly. NEVER changes any emitted bytes — a pure post-emission check.
+ * - No Dart out (dart config off) or no `pubspec.yaml` at the out dir / one level up → warn + skip
+ *   (the generated sources need a pub package around them to analyze).
+ * - `dart` missing from PATH → warn + skip.
+ * - Analyzer red → print its output and exit non-zero.
+ */
+function runDartAnalyze(dartOut: string | undefined): void {
+  if (dartOut === undefined) {
+    console.warn(`  ⚠ analyze  skipped — no Dart output (set 'dart' in the config to emit + analyze)`);
+    return;
+  }
+  // The pub package root: the out dir, else one level up (a common layout is
+  // `<pkg>/lib/generated` with the pubspec at `<pkg>/`, but out is usually `<pkg>` itself).
+  const pkgRoot = [dartOut, path.dirname(dartOut)].find((d) => existsSync(path.join(d, "pubspec.yaml")));
+  if (pkgRoot === undefined) {
+    console.warn(
+      `  ⚠ analyze  skipped — no pubspec.yaml at ${path.relative(process.cwd(), dartOut)} or its parent; ` +
+        `\`dart analyze\` needs a pub package (add a pubspec.yaml around the generated Dart)`,
+    );
+    return;
+  }
+  try {
+    execFileSync("dart", ["analyze", pkgRoot], { stdio: "inherit" });
+    console.log(`  analyze    dart analyze GREEN (${path.relative(process.cwd(), pkgRoot)})`);
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      console.warn(`  ⚠ analyze  skipped — \`dart\` is not on PATH (install the Dart SDK to analyze)`);
+      return;
+    }
+    // A non-zero exit is analyzer RED — execFileSync already streamed the output (stdio: inherit).
+    console.error(`  ✗ analyze  dart analyze FAILED (${path.relative(process.cwd(), pkgRoot)}) — see output above`);
+    process.exit(1);
+  }
 }
 
 await main();

package/src/framework/framework_aggregates.ts

@@ -32,6 +32,9 @@
 import type { AggregateHandle } from "../aggregate.js";
 import type { Directive } from "../directive.js";
 import type { QueryDecl } from "../query.js";
+import { nomosSourceFrontierEnsure } from "../attested.js";
+import * as birthMeter from "../birth_meter.js";
+import * as birthMeterEnsure from "../birth_meter_ensure.js";
 import * as disclosure from "./disclosure.js";
 import * as domainLifecycle from "./domain_lifecycle.js";
 import * as encryptionIdentity from "./encryption_identity.js";
@@ -47,6 +50,12 @@ import * as workspaces from "./workspaces.js";
 // Every framework module that DECLARES aggregate / directive / query singletons. Namespace imports so
 // the registry is derived from the real exports (no hand-kept id list to drift).
 const FRAMEWORK_NAMESPACES: ReadonlyArray<Record<string, unknown>> = [
+  // MERGE-SEAM-INJECTED singletons (`composeDomainModule` folds these into every `.births()`
+  // domain WITHOUT a tenant re-export — `withBirthMeterExports` + BIRTH_METER_AGGREGATES/QUERIES).
+  // Unbranded, a 2-birthing-domain package defined `NomosBirthRecordEnsurePayload` (+ the meter
+  // read models/accessors) once PER domain — the exact ambiguous_export co2 hit on its barrel.
+  birthMeter,
+  birthMeterEnsure,
   disclosure,
   domainLifecycle,
   encryptionIdentity,
@@ -114,6 +123,15 @@ for (const ns of FRAMEWORK_NAMESPACES) {
   }
 }
 
+// THE ATTESTED-READS INJECTED DIRECTIVE — branded INDIVIDUALLY, not via its namespace: its payload
+// class (`NomosSourceFrontierEnsurePayload`, zero-field) is domain-agnostic and must dedup like the
+// birth-meter's, but the `NomosSourceFrontier` AGGREGATE stays UNBRANDED deliberately — it is
+// NAMESPACED per owning domain at law (it is NOT in `GLOBAL_READ_PROJECTION_AGGREGATE_IDS`), so its
+// per-domain Dart read surface is domain-specific and must stay in each domain's file. Branding the
+// whole namespace would have flipped its law-plane namespacing via the drift-guard pin.
+(nomosSourceFrontierEnsure as { framework?: true }).framework = true;
+directiveIds.add(nomosSourceFrontierEnsure.id);
+
 export const FRAMEWORK_AGGREGATE_IDS: ReadonlySet<string> = aggregateIds;
 export const FRAMEWORK_DIRECTIVE_IDS: ReadonlySet<string> = directiveIds;
 export const FRAMEWORK_QUERY_IDS: ReadonlySet<string> = queryIds;

package/src/read_projection_composition.ts

@@ -6,20 +6,20 @@
 // sibling of `relation_composition.ts` (the scalpel).
 //
 // THE MODEL. The kernel's installed-read-manifest accumulator
-// (`wasm_git_holon.rs::ReadProjectionAccumulator`) UNIONS every active install's
-// `nomosReadProjection` fragment BY KEY — `aggregateFieldKinds` by aggregate TYPE,
+// (`wasm_git_holon.rs::ReadProjectionAccumulator`) UNIONS the CURRENT installed
+// `nomosReadProjection` fragments BY KEY — `aggregateFieldKinds` by aggregate TYPE,
 // `queries`/`counts`/`spatials`/`sums`/`mins`/`maxes`/`orderedReads` by declared `id`,
 // `deriveds`/`combineds` by `"<of>\0<id>"` — and (correctly, fail-closed) REFUSES a
-// key declared twice with DIVERGENT shapes: "divergent read projection declaration
-// for key <k>". At RUNTIME that refusal WEDGES the workspace's read plane.
+// CURRENT key declared twice with DIVERGENT shapes: "divergent read projection
+// declaration for key <k>". Superseded eras never feed the current read manifest.
 //
 // Read-projection NAMESPACING (`read_projection_namespace.ts`) makes a NON-GLOBAL
 // aggregate's keys domain-qualified, so tenant domains never share a key. What CAN
 // still share a key inside one package: GLOBAL framework aggregates declared by ≥2
 // domains (byte-identical by construction — same framework version — but a version
 // skew diverges), and same-named declared reads across domains. This guard turns the
-// runtime wedge into a precise COMPILE refusal: identical shared declarations PASS
-// (the kernel dedupes them), divergent ones REFUSE with the key and each domain's
+// current-runtime conflict into a precise COMPILE refusal: identical shared declarations
+// PASS (the kernel dedupes them), divergent ones REFUSE with the key and each domain's
 // shape. Validation only — a conflict-free package is returned untouched (era rule).
 
 import type { UsdLayer } from "./usd.js";
@@ -38,9 +38,9 @@ interface ReadProjectionConflict {
 function scalpelMessage(conflicts: readonly ReadProjectionConflict[]): string {
   const lines: string[] = [
     `Refusing to compose the package: shared read-projection key(s) carry DIVERGENT declarations ` +
-      `across domains — the kernel's installed-read-manifest accumulator refuses exactly this at ` +
-      `SERVE time ("divergent read projection declaration for key …"), wedging the workspace's ` +
-      `read plane. Fail-closed compile refusal, not a runtime wedge.`,
+      `across domains — the current installed-read-manifest accumulator refuses exactly this at ` +
+      `SERVE time ("divergent read projection declaration for key …"). Superseded eras are ignored, ` +
+      `but genuinely current law must have one coherent read shape. Fail-closed compile refusal.`,
     ``,
   ];
   for (const c of conflicts) {

package/src/read_projection_namespace.ts

@@ -6,11 +6,10 @@
 // relation-type namespacing (`relation_schema.ts::qualifyRelationType`).
 //
 // THE DISEASE. The kernel's installed-read-manifest accumulator
-// (`wasm_git_holon.rs::insert_read_projection_value`) unions every ACTIVE install's
-// `nomosReadProjection` fragment and — correctly, fail-closed — REFUSES when two
-// installs declare the SAME key with DIVERGENT shapes ("divergent read projection
-// declaration for key AuthProvider"). Two different domain keys that each declare a
-// same-named aggregate therefore WEDGE the workspace's read plane at serve time.
+// (`wasm_git_holon.rs::insert_read_projection_value`) merges every current install's
+// `nomosReadProjection` fragment by key. Superseded eras are ignored, so old read
+// declarations cannot wedge a workspace, but two independent current domain keys that
+// each declare a same-named aggregate are still an ambiguous read surface.
 //
 // THE CURE (the maintainer's rule: "Namespaces are a good idea. Use them."): a
 // NON-GLOBAL aggregate's TYPE NAME is QUALIFIED by its owning domain key at compile —

package/src/usd.ts

@@ -288,9 +288,9 @@ export interface UsdLayer {
    * THE READ-PROJECTION NAMESPACE ERA KEY (read-projection namespacing — the read-layer mirror of
    * `nomosRelationNamespace`). Present IFF this layer qualified ≥1 (non-global) AGGREGATE TYPE by its
    * owning domain key (`Entry` → `guestbook__Entry`), so two domains / two installs that each declare
-   * the same bare aggregate name no longer collide at the kernel's installed-read-manifest accumulator
-   * ("divergent read projection declaration for key …" — the fail-closed union stays the trust
-   * boundary; a qualified key is simply a NEW name to it). `types` is the SORTED set of qualified type
+   * the same bare aggregate name no longer collide at the kernel's installed-read-manifest accumulator.
+   * Runtime evolution ignores superseded eras; qualification keeps independent domains distinct.
+   * `types` is the SORTED set of qualified type
    * names this layer produced; `delimiter` is the same ratified colon-free `"__"`. OMITTED for a layer
    * whose aggregates are all GLOBAL (the explicit framework allowlist / `{global:true}`) — the marker
    * is a witness; the qualification itself is baked into the layer's keys.

package/src/value_object.ts

@@ -349,6 +349,7 @@ function sampleOfDescriptorField(
   f: ValueObjectFieldDescriptor,
   fieldName: string,
   byName: Map<string, ValueObjectDescriptor>,
+  includeOptional = false,
 ): unknown {
   switch (f.type) {
     case "string": return `sample-${fieldName}`;
@@ -356,17 +357,17 @@ function sampleOfDescriptorField(
     case "literal": return f.value;
     case "boolean": return true;
     case "enum": return f.values[0];
-    case "array": return [sampleOfDescriptorField(f.items, fieldName, byName)];
+    case "array": return [sampleOfDescriptorField(f.items, fieldName, byName, includeOptional)];
     case "geometry": return GEOMETRY_SAMPLES[f.geometry];
     case "object": {
       const dep = byName.get(f.ref);
       if (dep === undefined) throw new Error(`voSample: nested value object '${f.ref}' has no descriptor`);
-      return sampleOfDescriptor(dep, byName);
+      return sampleOfDescriptor(dep, byName, includeOptional);
     }
   }
 }
 
-function sampleOfDescriptor(d: ValueObjectDescriptor, byName: Map<string, ValueObjectDescriptor>): unknown {
+function sampleOfDescriptor(d: ValueObjectDescriptor, byName: Map<string, ValueObjectDescriptor>, includeOptional = false): unknown {
   if (d.geometry !== undefined) return GEOMETRY_SAMPLES[d.geometry];
   if (d.union !== undefined) {
     // FIRST declared arm (keys are sorted — deterministic); `example:` overrides upstream.
@@ -378,15 +379,15 @@ function sampleOfDescriptor(d: ValueObjectDescriptor, byName: Map<string, ValueO
     }
     const out: Record<string, unknown> = { type: key };
     for (const [k, f] of Object.entries(arm.fields)) {
-      if (f.optional === true) continue;
-      out[k] = sampleOfDescriptorField(f, k, byName);
+      if (f.optional === true && !includeOptional) continue;
+      out[k] = sampleOfDescriptorField(f, k, byName, includeOptional);
     }
     return out;
   }
   const out: Record<string, unknown> = {};
   for (const [k, f] of Object.entries(d.fields ?? {})) {
-    if (f.optional === true) continue; // optional → omitted (mirrors payload synthesis)
-    out[k] = sampleOfDescriptorField(f, k, byName);
+    if (f.optional === true && !includeOptional) continue; // optional → omitted (mirrors payload synthesis)
+    out[k] = sampleOfDescriptorField(f, k, byName, includeOptional);
   }
   return out;
 }
@@ -397,12 +398,12 @@ function sampleOfDescriptor(d: ValueObjectDescriptor, byName: Map<string, ValueO
  * VOs). Proof synthesis calls this instead of guessing at the raw zod — which is exactly the
  * lane that refused its own sample on constrained shapes (geo min-2 coordinates).
  */
-export function voSample(meta: ValueObjectFieldMeta): unknown {
+export function voSample(meta: ValueObjectFieldMeta, opts?: { includeOptional?: boolean }): unknown {
   if (meta.example !== undefined) return meta.example;
   const byName = new Map<string, ValueObjectDescriptor>();
   for (const d of meta.dependencies) byName.set(d.name, d);
   byName.set(meta.descriptor.name, meta.descriptor);
-  return sampleOfDescriptor(meta.descriptor, byName);
+  return sampleOfDescriptor(meta.descriptor, byName, opts?.includeOptional === true);
 }
 
 function makeValueObject<T>(