@githolon/dsl 0.33.0 → 0.34.1

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,6 +188,9 @@ 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)))}`]
       : []),
@@ -779,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"];
     {
@@ -820,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).
@@ -846,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)!),
@@ -861,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 } : {}),
     };
   });
 
@@ -996,8 +1051,10 @@ 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"]>();
@@ -1052,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") {
@@ -1062,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") {
@@ -1174,8 +1241,10 @@ 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);
@@ -1194,9 +1263,11 @@ 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 } : {}),

package/src/value_object.ts

@@ -411,3 +411,46 @@ export function collectValueObjectDescriptors(
   }
   return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
+
+/**
+ * ONE VO↔FIELD ATTACHMENT (the IR pointer): aggregate `aggregate`'s field `field`
+ * stores value object `vo`. Rides the additive `nomosValueObjects` USD key as
+ * `usages` so tooling (the scene projector, the explorer glyphs) can attach a VO
+ * molecule to the exact field that carries it. NEVER in the canonical
+ * manifest/domainHash — a VO field's wire schema stays a plain `jsonObject` leaf.
+ */
+export interface ValueObjectUsage {
+  readonly aggregate: string;
+  readonly field: string;
+  readonly vo: string;
+}
+
+/**
+ * Collect the sorted VO↔field usage pointers of a set of aggregates (one entry per
+ * VO-typed field; sorted by aggregate then field — byte-deterministic). Returns `[]`
+ * when no field carries a VO — the omit-when-empty input to the `usages` entry of
+ * the `nomosValueObjects` era key.
+ */
+export function collectValueObjectUsages(
+  aggregates: readonly { id: string; fields: Record<string, Field> }[],
+): ValueObjectUsage[] {
+  const usages: ValueObjectUsage[] = [];
+  for (const agg of aggregates) {
+    for (const fieldName of Object.keys(agg.fields)) {
+      const meta = agg.fields[fieldName]!.valueObject;
+      if (meta === undefined) continue;
+      usages.push({ aggregate: agg.id, field: fieldName, vo: meta.name });
+    }
+  }
+  return usages.sort((a, b) =>
+    a.aggregate !== b.aggregate
+      ? a.aggregate < b.aggregate
+        ? -1
+        : 1
+      : a.field < b.field
+        ? -1
+        : a.field > b.field
+          ? 1
+          : 0,
+  );
+}

package/src/wire_encode.ts

@@ -20,9 +20,16 @@
  * LATER coordinated migration — we target the current serde_json shape now.
  */
 import { encodeDriver } from "./drivers.js";
+import { __qualifyAggregateType } from "./framework/relations.js";
 import { __resetAuthoring, __drainAuthoring } from "./authoring.js";
 import { __resetReads, __drainReads } from "./read.js";
 import { __resetBirths, __drainBirths } from "./births.js";
+import {
+  birthMeterSubject,
+  birthMeterBornAt,
+  captureBirthMeterReads,
+  planBirthRecordOps,
+} from "./birth_meter.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { Field, EvidenceRefValue } from "./fields.js";
 import type { Directive, ReferentialMarker } from "./directive.js";
@@ -203,13 +210,33 @@ export function executeDirectiveToIntent<P>(
   __resetReads();
   __resetBirths();
   const returned = directive.plan(parsed, ctx);
-  const planned = [...__drainAuthoring(), ...returned];
-  const reads = __drainReads();
   // THE BIRTH EFFECT (G3 — birth is a declared kernel primitive): a `.births()` directive's plan records
   // the child's genesis recipe via `birth(recipe)`; it rides the intent as a DECLARED output (like a
   // captured read), drained here. Empty for every non-birth directive — OMITTED below so a birth-free
   // intent is byte-identical (the era rule).
   const births = __drainBirths();
+  // METERED BIRTH (slice A — architecture/metered_birth_and_attested_reads.md). For every PLANNED birth,
+  // the library — HERE, in the ONE plan-output assembly both lanes (client authoring + the sealed engine's
+  // `plan`) funnel through, so the halves are byte-identical by construction — does two things the tenant
+  // never writes:
+  //   A1 THE AUTO-RECORD: append the `NomosBirthRecord` field ops (deterministic id per child; Lww upsert)
+  //      to the SAME intent that carries the birth effect. The kernel's `nomosBirthRecordGate` era arm
+  //      refuses a new-era birth whose intent carries no record — this is what satisfies it.
+  //   A2 THE AUTO-CAPTURE: capture the three meter reads (records-by-subject + grant + policy — the #58
+  //      lane `.births()` auto-declares) so the synthesized birth-quota invariant judges over COMMITTED,
+  //      CAS-re-derived pre-apply state on every lane.
+  // A `.births()` dispatch that planned NO birth (e.g. birthChild without a genesis) appends/captures
+  // nothing — byte-identical to before (the era rule); pre-era bundles ship an older lump and are untouched.
+  const meterOps: PlannedOp[] = [];
+  if (births.length > 0) {
+    const payloadRecord = parsed as unknown as Record<string, unknown>;
+    const subject = birthMeterSubject(payloadRecord);
+    captureBirthMeterReads(subject);
+    const bornAt = birthMeterBornAt(payloadRecord);
+    for (const b of births) meterOps.push(...planBirthRecordOps(b, subject, bornAt));
+  }
+  const planned = [...__drainAuthoring(), ...returned, ...meterOps];
+  const reads = __drainReads();
 
   // Partition the plan output: STRIKE ops route onto the intent's `strikes` channel
   // (the kernel's strikeout / revert facet, folded by parity); FIELD ops group into
@@ -293,7 +320,11 @@ export function executeDirectiveToIntent<P>(
         aggregate,
         marker: eventMarker,
         ops: [
-          { field: "__type", op: { Set: { Str: ty } } },
+          // READ-PROJECTION NAMESPACING: the stamped TYPE is qualified by the dispatching domain iff
+          // the domain declares it non-global — so the folded row's `__type` equals the qualified
+          // schema key the SAME compile wrote (rows and read manifest agree by construction). Outside
+          // a plan dispatch (codegen probes) the type passes through bare.
+          { field: "__type", op: { Set: { Str: __qualifyAggregateType(ty) } } },
           { field: "__id", op: { Set: { Str: aggregate } } },
           ...ops,
         ],