@githolon/dsl 0.32.0 → 0.34.0

package/src/usd.ts

@@ -45,6 +45,14 @@ import { domainInterface } from "./shape_compat.js";
 import { relationType, user, key, anyUser, qualifiedTypeId, qualifyRelationType } from "./relation_schema.js";
 import { harvestPrincipalFlows } from "./wire_encode.js";
 import { composeSharedRelationTypes } from "./relation_composition.js";
+import { collectValueObjectUsages } from "./value_object.js";
+import {
+  namespacedAggregateIds,
+  qualifyReadProjectionType,
+  READ_PROJECTION_DELIMITER,
+} from "./read_projection_namespace.js";
+import { qualifyManifestAggregateLabels } from "./read_projection_manifest.js";
+import { guardSharedReadProjectionKeys } from "./read_projection_composition.js";
 
 /** The referential marker of a directive prim (kernel `RefMode` wire string). */
 export type RefMode = WireRefMode;
@@ -276,6 +284,22 @@ export interface UsdLayer {
     readonly delimiter: string;
     readonly types: readonly string[];
   };
+  /**
+   * 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
+   * 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.
+   */
+  readonly nomosReadProjectionNamespace?: {
+    readonly v: 1;
+    readonly delimiter: string;
+    readonly types: readonly string[];
+  };
   /**
    * THE CROSS-CUSTODY ATTESTATION GATE (home_holons §3/§5). Present IFF ≥1 directive declares
    * `.attestationAuthorized()`: the SORTED set of their ids. A directive named here is authorized by a
@@ -339,6 +363,25 @@ export interface UsdLayer {
     /** The directive ids declared `.births()` — SORTED. */
     readonly directives: string[];
   };
+  /**
+   * THE BIRTH-RECORD GATE (metered birth, slice A1 — `architecture/metered_birth_and_attested_reads.md`).
+   * Present IFF the layer declares ≥1 `.births()` directive AND was compiled under the metered-birth
+   * compiler: the law's EXPLICIT declaration that every birth it performs ALSO writes a structural
+   * `NomosBirthRecord` event (deterministic id `<prefix><child>`) in the SAME intent as the birth
+   * effect — the `.births()` lane appends it automatically, so the declaration is self-fulfilling for
+   * honestly-compiled law and the kernel arm only ever bites a forged/hand-built lump. The kernel's
+   * `verify_births_witness` reads THIS declaration (the SAME way it reads `nomosBirthGate` — the
+   * bundle declares, the kernel honors; NO kernel version-if) and refuses a new-era birth whose
+   * re-derived events carry no record (`birth-record-missing`). OMITTED for pre-feature law — the
+   * era rule: every chain sealed before this key replays byte-identical, births exactly as today.
+   */
+  readonly nomosBirthRecordGate?: {
+    readonly v: 1;
+    /** The record aggregate TYPE name (the framework's `NomosBirthRecord`). */
+    readonly aggregate: string;
+    /** The deterministic instance-id prefix — the record for child `w` lives at `<prefix><w>`. */
+    readonly prefix: string;
+  };
   /**
    * THE PEER-SOVEREIGN ROOT-OF-TRUST (the BirthAttestation cert chain). Present IFF the law declares
    * `requireParentAttestedBirth`: a warranted workspace running this law MUST travel with a SIGNED cert
@@ -464,6 +507,27 @@ export interface UsdLayer {
       readonly reason: string | null;
     }[];
   };
+  /**
+   * FIRST-CLASS VALUE OBJECTS (`value_object.ts`) — the canonical descriptors of every
+   * named value object this layer's aggregates carry (deduped, SORTED by name, nested
+   * VOs included), so tooling/visualizers SEE the structure a VO field stores. PURELY
+   * DESCRIPTIVE: the kernel reads no gate off it (a VO field folds exactly like a
+   * `t.jsonObject()` leaf — one wholesale-replace json value). OMITTED for VO-free law
+   * (byte-identical hash — the era rule); declaring a VO moves the PACKAGE hash only
+   * (the canonical manifest/domainHash is untouched — the VO is not wire law).
+   */
+  readonly nomosValueObjects?: {
+    readonly v: 1;
+    readonly valueObjects: readonly import("./fields.js").ValueObjectDescriptor[];
+    /**
+     * THE VO↔FIELD ATTACHMENT (additive, hash-inert): which aggregate FIELD carries
+     * which VO — `{aggregate, field, vo}` sorted by aggregate then field. Rides THIS
+     * key (never the aggregate prim's wire schema) so the canonical manifest/domainHash
+     * of a VO field stays byte-equal to a plain `t.jsonObject()` field. Optional for
+     * era tolerance: a 0.33.0-compiled package's key parses unchanged without it.
+     */
+    readonly usages?: readonly import("./value_object.js").ValueObjectUsage[];
+  };
 }
 
 /** The reserved variant name declaring a set's DEFAULT (USD has a default variant). */
@@ -486,13 +550,15 @@ function sortPrims(prims: UsdPrim[]): UsdPrim[] {
  * encoded schema; directive prims map `requiresCapability` → `requires: [cap]`, leave
  * `scope`/`payloadRef` `undefined` (no static scope today; payload is stage 2).
  */
-function encodeModuleToPrims(layerPath: string, mod: DomainModule): UsdPrim[] {
-  const manifest = domainManifest(mod);
+function encodeModuleToPrims(layerPath: string, manifest: CanonicalManifest): UsdPrim[] {
   const prims: UsdPrim[] = [];
 
   for (const agg of manifest.aggregates) {
     prims.push({
       kind: "aggregate",
+      // The IR prim path carries the (possibly dotted-qualified) type verbatim; the `.usda`
+      // TEXT lane sanitizes the prim NAME (`usd_layers.ts::primName`) and round-trips the raw
+      // id via `nomos:id`, so real-USD identifier rules are already satisfied downstream.
       path: `${layerPath}/${agg.id}`,
       type: agg.id,
       schema: agg.schema,
@@ -525,6 +591,7 @@ function encodeModuleToPrims(layerPath: string, mod: DomainModule): UsdPrim[] {
 
 function aggregateFieldKindsForModule(
   mod: DomainModule,
+  qa: (type: string) => string = (n) => n,
 ): Record<string, Record<string, UsdFieldKindDescriptor>> {
   const out: Record<string, Record<string, UsdFieldKindDescriptor>> = {};
   for (const agg of [...(mod.aggregates as AggregateHandle[])].sort((a, b) =>
@@ -538,7 +605,7 @@ function aggregateFieldKindsForModule(
         ...(field.mapValueKind !== undefined ? { mapValueKind: field.mapValueKind } : {}),
       };
     }
-    out[agg.id] = fields;
+    out[qa(agg.id)] = fields;
   }
   return out;
 }
@@ -565,8 +632,12 @@ function readKeyFieldKind(
   return descriptor.kind;
 }
 
-function readProjectionForModule(mod: DomainModule, manifest: CanonicalManifest): UsdReadProjection {
-  const aggregateFieldKinds = aggregateFieldKindsForModule(mod);
+function readProjectionForModule(
+  mod: DomainModule,
+  manifest: CanonicalManifest,
+  qa: (type: string) => string = (n) => n,
+): UsdReadProjection {
+  const aggregateFieldKinds = aggregateFieldKindsForModule(mod, qa);
   return {
     aggregateFieldKinds,
     queries: (manifest.queries ?? []).map((q) => ({
@@ -730,13 +801,35 @@ export function emitUsd(
       // Carry the domain's declared queries straight from the canonical manifest,
       // which already applies omit-when-empty: `queries` is present here ONLY when the
       // module declared them, so a query-free layer is byte-identical to before.
-      const manifest = domainManifest(l.module);
+      const bareManifest = domainManifest(l.module);
+      // READ-PROJECTION NAMESPACING: every NON-GLOBAL aggregate's type name is qualified by the
+      // owning domain key — on the prims, the identity manifest, the stable-ids labels (bare name
+      // appended to `was` — the rename lineage), the read projection, and every `of`/`returns`
+      // reference — so two domains / two installs that each declare the same bare name never share
+      // an installed-read-manifest accumulator key. GLOBAL (framework allowlist / `{global:true}`)
+      // aggregates stay bare (the kernel addresses them by bare name). The engine stamps the SAME
+      // qualified name at plan runtime (`wire_encode.ts` via the dispatch context), so rows and
+      // schema keys agree by construction. `module.domain ?? module.name` — the SAME qualifier key
+      // relation namespacing uses (=== `intent.domain` at plan runtime).
+      const rpDomainKey = l.module.domain ?? l.module.name;
+      const namespacedAggs = namespacedAggregateIds(
+        l.module.aggregates as unknown as readonly { id: string; global?: boolean }[],
+      );
+      const qaType = (n: string): string =>
+        namespacedAggs.has(n) ? qualifyReadProjectionType(rpDomainKey, n) : n;
+      const manifest = qualifyManifestAggregateLabels(bareManifest, rpDomainKey, namespacedAggs);
+      // THE READ-PROJECTION NAMESPACE ERA KEY: present iff ≥1 aggregate was qualified (the witness
+      // marker — mirrors `nomosRelationNamespace`; the qualification itself is baked into the keys).
+      const nomosReadProjectionNamespace =
+        namespacedAggs.size > 0
+          ? { v: 1 as const, delimiter: READ_PROJECTION_DELIMITER, types: [...namespacedAggs].map(qaType).sort() }
+          : undefined;
       // THE INVARIANT-GATE DECLARATION (#41): presence-only, derived from the SAME module
       // the lump's executable bodies come from — sorted, omit-when-empty (hash-stable for
       // invariant-free law; see the `UsdLayer.nomosInvariantGate` banner for the era rule).
       const invariantAggregates = l.module.aggregates
         .filter((a) => a.hasInvariant === true)
-        .map((a) => a.id)
+        .map((a) => qaType(a.id))
         .sort();
       const wsInvariants = [...(l.module.workspaceInvariants ?? [])]
         .map((w) => ({ id: w.id, on: w.on }))
@@ -869,6 +962,17 @@ export function emitUsd(
         .sort();
       const nomosBirthGate =
         birthDirectives.length > 0 ? { v: 1 as const, directives: birthDirectives } : undefined;
+      // THE BIRTH-RECORD GATE (metered birth, slice A1 — the framework's new era key). Present IFF
+      // this layer declares ≥1 `.births()` directive AND was compiled under this compiler: the law's
+      // EXPLICIT declaration that every birth it performs ALSO writes a structural NomosBirthRecord
+      // in the SAME intent (the `.births()` lane appends it automatically). The kernel's
+      // `verify_births_witness` reads THIS key (never a version-if): a carried birth whose re-derived
+      // events contain no `<prefix><child>` record event is a typed refusal (`birth-record-missing`).
+      // Omit-when-empty (the era rule): every pre-feature bundle lacks the key and births as today.
+      const nomosBirthRecordGate =
+        birthDirectives.length > 0
+          ? { v: 1 as const, aggregate: "NomosBirthRecord", prefix: "nomos-birth-record:" }
+          : undefined;
       // THE PEER-SOVEREIGN ROOT-OF-TRUST: the home/child law declared it requires a parent-attested-birth
       // cert chain (the `requireParentAttestedBirth` sentinel). Emit the era key with the LAW-DECLARED owner +
       // cert locators (so the kernel reads them, names neither); a bare marker (no locators) falls back to the
@@ -995,6 +1099,22 @@ export function emitUsd(
       // conversion's declared flow {directiveId, sink, facet, reason}. Hashed into nomosFlowGate +
       // witnessed fail-closed at runtime (Slice B). Omit-when-empty (a principal-free domain is
       // byte-identical). SORTED for determinism.
+      // FIRST-CLASS VALUE OBJECTS: the module's collected descriptors (composeDomainModule
+      // dedupes + sorts them). Omit-when-empty (era rule — VO-free law is byte-identical).
+      const moduleValueObjects = (l.module as { valueObjects?: readonly import("./fields.js").ValueObjectDescriptor[] }).valueObjects;
+      // THE VO↔FIELD ATTACHMENT: the usage pointers ride the SAME additive key (see
+      // the UsdLayer type) — computed from the live Field metas, sorted, omit-when-empty.
+      const voUsages = collectValueObjectUsages(
+        l.module.aggregates as unknown as readonly { id: string; fields: Record<string, import("./fields.js").Field> }[],
+      );
+      const nomosValueObjects =
+        moduleValueObjects !== undefined && moduleValueObjects.length > 0
+          ? {
+              v: 1 as const,
+              valueObjects: [...moduleValueObjects],
+              ...(voUsages.length > 0 ? { usages: voUsages } : {}),
+            }
+          : undefined;
       const flowEndorse = [...l.module.directives]
         .flatMap((d) => harvestPrincipalFlows(d as never).map((f) => ({ directiveId: d.id, sink: f.sink, facet: f.facet, reason: f.reason })))
         .sort((a, b) =>
@@ -1004,9 +1124,9 @@ export function emitUsd(
         );
       return {
         path: l.path,
-        prims: encodeModuleToPrims(l.path, l.module),
+        prims: encodeModuleToPrims(l.path, manifest),
         nomosIdentityManifest: manifest,
-        nomosReadProjection: readProjectionForModule(l.module, manifest),
+        nomosReadProjection: readProjectionForModule(l.module, manifest, qaType),
         ...(manifest.queries !== undefined ? { queries: manifest.queries } : {}),
         ...(manifest.deriveds !== undefined ? { deriveds: manifest.deriveds } : {}),
         ...(manifest.combineds !== undefined ? { combineds: manifest.combineds } : {}),
@@ -1014,7 +1134,9 @@ export function emitUsd(
         ...(manifest.stableIds !== undefined ? { nomosStableIds: manifest.stableIds } : {}),
         // THE STRUCTURAL INTERFACE (#72): the on-ledger OFFER — a client negotiates shape-
         // compatibility against this, reactively, straight from the folded `policy:{hash}.bundle`.
-        nomosInterface: domainInterface(l.module, manifest.stableIds),
+        // The client-facing structural offer stays BARE-labelled (labels are cosmetic there;
+        // shape-compat negotiates by sid) — pass the pre-namespacing stable-ids.
+        nomosInterface: domainInterface(l.module, bareManifest.stableIds),
         ...(Object.keys(readGateDirectives).length > 0
           ? {
               nomosReadGate: {
@@ -1035,11 +1157,14 @@ export function emitUsd(
           : {}),
         ...(nomosRelations !== undefined ? { nomosRelations } : {}),
         ...(nomosRelationNamespace !== undefined ? { nomosRelationNamespace } : {}),
+        ...(nomosReadProjectionNamespace !== undefined ? { nomosReadProjectionNamespace } : {}),
         ...(nomosRelationGate !== undefined ? { nomosRelationGate } : {}),
         ...(nomosAttestationGate !== undefined ? { nomosAttestationGate } : {}),
         ...(nomosBirthGate !== undefined ? { nomosBirthGate } : {}),
+        ...(nomosBirthRecordGate !== undefined ? { nomosBirthRecordGate } : {}),
         ...(nomosParentAttestedBirth !== undefined ? { nomosParentAttestedBirth } : {}),
         ...(nomosVerifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll } : {}),
+        ...(nomosValueObjects !== undefined ? { nomosValueObjects } : {}),
         ...(Object.keys(visAggregates).length > 0
           ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }
           : {}),
@@ -1065,6 +1190,12 @@ export function emitUsd(
   // package's per-domain layers: UNION every domain's relations on a shared bare-id type (so nothing
   // is silently dropped) and REFUSE on a divergent shared rewrite (the scalpel). Non-shared /
   // auto-qualified types are untouched → a package with no shared global type is byte-identical.
+  // THE READ-PROJECTION DIVERGENCE GUARD (the scalpel, extended to the read layer): for keys that
+  // remain SHARED across this package's domains (GLOBAL framework aggregates / same-named declared
+  // reads), identical declarations dedupe at the kernel accumulator; a DIVERGENT shared key would
+  // wedge the workspace at serve time — refuse it AT COMPILE instead, naming the key and each
+  // domain's shape. Validation only (never transforms), so a conflict-free package is untouched.
+  guardSharedReadProjectionKeys(out);
   return { layers: composeSharedRelationTypes(out) };
 }
 

package/src/usd_layers.ts

@@ -58,6 +58,7 @@
  * the runtime barrel.
  */
 import type { AggregateHandle } from "./aggregate.js";
+import { READ_PROJECTION_DELIMITER } from "./read_projection_namespace.js";
 import type { Field } from "./fields.js";
 import type { DomainModule } from "./codegen_dart.js";
 import type { WireDriver, WireRefMode, WireSchema } from "./wire.js";
@@ -175,6 +176,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosRelationNamespace !== undefined
       ? [`${indent}custom string nomos:relationNamespaceHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelationNamespace)))}`]
       : []),
+    ...(layer.nomosReadProjectionNamespace !== undefined
+      ? [`${indent}custom string nomos:readProjectionNamespaceHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosReadProjectionNamespace)))}`]
+      : []),
     ...(layer.nomosRelationGate !== undefined
       ? [`${indent}custom string nomos:relationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelationGate)))}`]
       : []),
@@ -184,12 +188,18 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosBirthGate !== undefined
       ? [`${indent}custom string nomos:birthGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosBirthGate)))}`]
       : []),
+    ...(layer.nomosBirthRecordGate !== undefined
+      ? [`${indent}custom string nomos:birthRecordGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosBirthRecordGate)))}`]
+      : []),
     ...(layer.nomosParentAttestedBirth !== undefined
       ? [`${indent}custom string nomos:parentAttestedBirthHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosParentAttestedBirth)))}`]
       : []),
     ...(layer.nomosVerifiedFirstEnroll !== undefined
       ? [`${indent}custom string nomos:verifiedFirstEnrollHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosVerifiedFirstEnroll)))}`]
       : []),
+    ...(layer.nomosValueObjects !== undefined
+      ? [`${indent}custom string nomos:valueObjectsHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosValueObjects)))}`]
+      : []),
   ];
 }
 
@@ -776,6 +786,18 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       }
       if (ns.size > 0) relationNamespace = { v: 1, delimiter: "__", types: [...ns].sort() };
     }
+    // THE READ-PROJECTION NAMESPACE ERA KEY (read-projection namespacing): the SORTED union of every
+    // layer's qualified aggregate type names. Present iff ANY layer namespaced >=1 aggregate;
+    // omit-when-empty (byte-identical for global-only packages). Delimiter is the ratified "__".
+    let readProjectionNamespace: UsdLayer["nomosReadProjectionNamespace"];
+    {
+      const ns = new Set<string>();
+      for (const l of stack) {
+        if (l.nomosReadProjectionNamespace === undefined) continue;
+        for (const id of l.nomosReadProjectionNamespace.types) ns.add(id);
+      }
+      if (ns.size > 0) readProjectionNamespace = { v: 1, delimiter: READ_PROJECTION_DELIMITER, types: [...ns].sort() };
+    }
     // THE RELATION GATE (P4): directiveId → {relation, object} merged later-wins, SORTED. Omit-when-empty.
     let relationGate: UsdLayer["nomosRelationGate"];
     {
@@ -817,6 +839,16 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       }
       if (b.size > 0) birthGate = { v: 1, directives: [...b].sort() };
     }
+    // THE BIRTH-RECORD GATE (metered birth, A1): present iff ANY layer declares it (once declared,
+    // declared). Carry the FIRST layer's aggregate/prefix verbatim (the framework constants — do NOT
+    // reconstruct). Omit-when-absent (era rule).
+    let birthRecordGate: UsdLayer["nomosBirthRecordGate"];
+    for (const l of stack) {
+      if (l.nomosBirthRecordGate !== undefined) {
+        birthRecordGate = l.nomosBirthRecordGate;
+        break;
+      }
+    }
     // THE PEER-SOVEREIGN ROOT-OF-TRUST: the era key is present iff ANY layer declares it (once required,
     // required). Carry the FIRST layer's declared owner/cert locators verbatim (preserve them — do NOT
     // reconstruct {v:1}, which would drop the locators the kernel reads). Omit-when-absent (era rule).
@@ -843,6 +875,29 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         verifiedFirstEnroll = { v: 1, directives: rec };
       }
     }
+    // FIRST-CLASS VALUE OBJECTS (+ the VO↔field usage pointers): descriptors merged
+    // later-wins per NAME, usages later-wins per (aggregate, field), both SORTED —
+    // so the layered fold stays byte-homomorphic with `emitUsd`'s composed emission.
+    // Omit-when-empty (the era rule); `usages` omitted when none (0.33.0 tolerance).
+    let valueObjects: UsdLayer["nomosValueObjects"];
+    {
+      type VoDesc = NonNullable<UsdLayer["nomosValueObjects"]>["valueObjects"][number];
+      type VoUse = NonNullable<NonNullable<UsdLayer["nomosValueObjects"]>["usages"]>[number];
+      const byName = new Map<string, VoDesc>();
+      const byField = new Map<string, VoUse>();
+      for (const l of stack) {
+        if (l.nomosValueObjects === undefined) continue;
+        for (const d of l.nomosValueObjects.valueObjects) byName.set(d.name, d);
+        for (const u of l.nomosValueObjects.usages ?? []) byField.set(`${u.aggregate}\u0000${u.field}`, u);
+      }
+      if (byName.size > 0) {
+        const descs = [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        const uses = [...byField.values()].sort((a, b) =>
+          a.aggregate !== b.aggregate ? (a.aggregate < b.aggregate ? -1 : 1) : a.field < b.field ? -1 : a.field > b.field ? 1 : 0,
+        );
+        valueObjects = { v: 1, valueObjects: descs, ...(uses.length > 0 ? { usages: uses } : {}) };
+      }
+    }
     return {
       path,
       prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
@@ -858,11 +913,14 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       ...(encryption !== undefined ? { nomosEncryption: encryption } : {}),
       ...(relations !== undefined ? { nomosRelations: relations } : {}),
       ...(relationNamespace !== undefined ? { nomosRelationNamespace: relationNamespace } : {}),
+      ...(readProjectionNamespace !== undefined ? { nomosReadProjectionNamespace: readProjectionNamespace } : {}),
       ...(relationGate !== undefined ? { nomosRelationGate: relationGate } : {}),
       ...(attestationGate !== undefined ? { nomosAttestationGate: attestationGate } : {}),
       ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
+      ...(birthRecordGate !== undefined ? { nomosBirthRecordGate: birthRecordGate } : {}),
       ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
       ...(verifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll: verifiedFirstEnroll } : {}),
+      ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
     };
   });
 
@@ -993,10 +1051,13 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const relationsByDomain = new Map<string, UsdLayer["nomosRelations"]>();
   const relationGateByDomain = new Map<string, UsdLayer["nomosRelationGate"]>();
   const relationNamespaceByDomain = new Map<string, UsdLayer["nomosRelationNamespace"]>();
+  const readProjectionNamespaceByDomain = new Map<string, UsdLayer["nomosReadProjectionNamespace"]>();
   const attestationGateByDomain = new Map<string, UsdLayer["nomosAttestationGate"]>();
   const birthGateByDomain = new Map<string, UsdLayer["nomosBirthGate"]>();
+  const birthRecordGateByDomain = new Map<string, UsdLayer["nomosBirthRecordGate"]>();
   const parentAttestedBirthByDomain = new Map<string, UsdLayer["nomosParentAttestedBirth"]>();
   const verifiedFirstEnrollByDomain = new Map<string, UsdLayer["nomosVerifiedFirstEnroll"]>();
+  const valueObjectsByDomain = new Map<string, UsdLayer["nomosValueObjects"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
@@ -1048,6 +1109,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof relNsHex === "string") {
         relationNamespaceByDomain.set(domain, JSON.parse(unhexUtf8(relNsHex)) as UsdLayer["nomosRelationNamespace"]);
       }
+      // THE READ-PROJECTION-NAMESPACE ERA KEY: the hex-carried qualified-aggregate witness.
+      const rpNsHex = p.attrs.get("nomos:readProjectionNamespaceHex");
+      if (typeof rpNsHex === "string") {
+        readProjectionNamespaceByDomain.set(domain, JSON.parse(unhexUtf8(rpNsHex)) as UsdLayer["nomosReadProjectionNamespace"]);
+      }
       // THE ATTESTATION GATE (home_holons §3/§5): the hex-carried attestation-authorized directive set.
       const attGateHex = p.attrs.get("nomos:attestationGateHex");
       if (typeof attGateHex === "string") {
@@ -1058,6 +1124,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof birthGateHex === "string") {
         birthGateByDomain.set(domain, JSON.parse(unhexUtf8(birthGateHex)) as UsdLayer["nomosBirthGate"]);
       }
+      // THE BIRTH-RECORD GATE (metered birth, A1): the hex-carried record declaration.
+      const birthRecordGateHex = p.attrs.get("nomos:birthRecordGateHex");
+      if (typeof birthRecordGateHex === "string") {
+        birthRecordGateByDomain.set(domain, JSON.parse(unhexUtf8(birthRecordGateHex)) as UsdLayer["nomosBirthRecordGate"]);
+      }
       // THE PEER-SOVEREIGN ROOT-OF-TRUST: the hex-carried parent-attested-birth era marker.
       const pabHex = p.attrs.get("nomos:parentAttestedBirthHex");
       if (typeof pabHex === "string") {
@@ -1068,6 +1139,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof vfeHex === "string") {
         verifiedFirstEnrollByDomain.set(domain, JSON.parse(unhexUtf8(vfeHex)) as UsdLayer["nomosVerifiedFirstEnroll"]);
       }
+      // FIRST-CLASS VALUE OBJECTS: the hex-carried descriptor set (descriptive, not a gate).
+      const voHex = p.attrs.get("nomos:valueObjectsHex");
+      if (typeof voHex === "string") {
+        valueObjectsByDomain.set(domain, JSON.parse(unhexUtf8(voHex)) as UsdLayer["nomosValueObjects"]);
+      }
     }
   }
 
@@ -1165,10 +1241,13 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const rel = relationsByDomain.get(domain);
       const relGate = relationGateByDomain.get(domain);
       const relNs = relationNamespaceByDomain.get(domain);
+      const rpNs = readProjectionNamespaceByDomain.get(domain);
       const attGate = attestationGateByDomain.get(domain);
       const birthGate = birthGateByDomain.get(domain);
+      const birthRecordGate = birthRecordGateByDomain.get(domain);
       const parentAttestedBirth = parentAttestedBirthByDomain.get(domain);
       const verifiedFirstEnroll = verifiedFirstEnrollByDomain.get(domain);
+      const valueObjects = valueObjectsByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
@@ -1184,11 +1263,14 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(enc !== undefined ? { nomosEncryption: enc } : {}),
         ...(rel !== undefined ? { nomosRelations: rel } : {}),
         ...(relNs !== undefined ? { nomosRelationNamespace: relNs } : {}),
+        ...(rpNs !== undefined ? { nomosReadProjectionNamespace: rpNs } : {}),
         ...(relGate !== undefined ? { nomosRelationGate: relGate } : {}),
         ...(attGate !== undefined ? { nomosAttestationGate: attGate } : {}),
         ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
+        ...(birthRecordGate !== undefined ? { nomosBirthRecordGate: birthRecordGate } : {}),
         ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
         ...(verifiedFirstEnroll !== undefined ? { nomosVerifiedFirstEnroll: verifiedFirstEnroll } : {}),
+        ...(valueObjects !== undefined ? { nomosValueObjects: valueObjects } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));