@githolon/dsl 0.33.0 → 0.34.0

package/src/engine_entry.ts

@@ -54,8 +54,11 @@
 import { executeDirectiveToIntent } from "./wire_encode.js";
 import { expandCapabilityExports } from "./capability_exports.js";
 import { RelationTuple, __setDispatchContext } from "./framework/relations.js";
+import { namespacedAggregateIds, qualifyReadProjectionType, READ_PROJECTION_DELIMITER } from "./read_projection_namespace.js";
 import { isRelationTypeDecl } from "./relation_schema.js";
 import { synthesizePreconditionInvariants } from "./precondition.js";
+import { synthesizeBirthQuotaInvariants } from "./birth_meter.js";
+import { withBirthMeterExports } from "./birth_meter_ensure.js";
 import { generateOpenApiFragment, mergeOpenApiFragments, type OpenApiDoc } from "./codegen_openapi.js";
 import type { QueryDecl } from "./query.js";
 import type { AnyCount } from "./count.js";
@@ -243,7 +246,10 @@ function mergeModules(mods: readonly DomainModuleExports[]): DomainModuleExports
   // `capability()` bundles expand into discoverable entries here — the engine
   // plane's ONE merge point, so the registry sees the task aggregate + quartet
   // without per-piece re-exports (capability_exports.ts).
-  return expandCapabilityExports(merged);
+  // METERED BIRTH: a `.births()`-declaring domain gains the birth-meter structural exports
+  // (the sanctioning `nomosBirthRecordEnsure` + the meter aggregates) at this same seam, so
+  // the registry + `describe()` see the exact surface the composed manifest carries.
+  return withBirthMeterExports(expandCapabilityExports(merged));
 }
 
 /**
@@ -270,6 +276,13 @@ interface DomainSlice {
    * type's relations (governance/signer/read-visibility) are EXCLUDED so their bare objects stay bare.
    */
   qualifiableRelations: Set<string>;
+  /**
+   * READ-PROJECTION NAMESPACING classification: the NON-GLOBAL aggregate ids this domain declares —
+   * the set whose runtime `__type` stamp qualifies to `<domain>__<type>` (matching the qualified
+   * keys the compiler wrote into the read projection / prims / stable-ids). GLOBAL aggregates (the
+   * explicit framework allowlist / `{global:true}`) are excluded so their bare identity survives.
+   */
+  qualifiableAggregates: Set<string>;
 }
 
 /** Build one domain's slice from its merged module exports (the original scans). */
@@ -376,6 +389,13 @@ function buildDomainSlice(mod: DomainModuleExports): DomainSlice {
   for (const directive of dirs.values()) {
     for (const w of synthesizePreconditionInvariants(directive)) wsInvariants.set(w.id, w);
   }
+  // METERED BIRTH (slice A2 — mirror of composeDomainModule): synthesize THE BIRTH-QUOTA invariant's
+  // executable body for every `.births()` directive, so the SEALED ENGINE registers the same
+  // `reads`/`assert` the manifest's `nomosInvariantGate` entry names. Byte-identical for a domain
+  // with no birth directive (synthesizes none — the era rule).
+  for (const directive of dirs.values()) {
+    for (const w of synthesizeBirthQuotaInvariants(directive)) wsInvariants.set(w.id, w);
+  }
 
   // ── RELATION-NAMESPACING classification — the LOCAL non-global `(type,relation)` set (by shape) ──
   // A bare `writeTuple({object:"<type>:<id>", relation})` auto-qualifies iff `<type>#<relation>` is here.
@@ -388,7 +408,11 @@ function buildDomainSlice(mod: DomainModuleExports): DomainSlice {
     for (const rel of v.relations.keys()) qualifiableRelations.add(`${v.type}#${rel}`);
   }
 
-  return { registry, deriveds, combineds, invariants, aggInvariants, wsInvariants, qualifiableRelations };
+  // ── READ-PROJECTION NAMESPACING classification — the LOCAL non-global aggregate ids (one shared
+  //    classification with the compiler: `read_projection_namespace.ts`). ──
+  const qualifiableAggregates = namespacedAggregateIds([...aggs.values()]);
+
+  return { registry, deriveds, combineds, invariants, aggInvariants, wsInvariants, qualifiableRelations, qualifiableAggregates };
 }
 
 /**
@@ -413,9 +437,14 @@ export function collectEngineRouting(
   };
   for (const [domainName, mods] of Object.entries(domains)) {
     const slice = buildDomainSlice(mergeModules(mods));
-    for (const type of slice.deriveds.keys()) add(derivedOf, type, domainName);
-    for (const type of slice.combineds.keys()) add(combinedOf, type, domainName);
-    for (const type of slice.aggInvariants.keys()) add(aggregateInvariantOf, type, domainName);
+    // Type-keyed dispatches arrive with the ROW's type — QUALIFIED for a namespaced aggregate (the
+    // runtime `__type` stamp), bare for a global one / a pre-namespacing row. Route BOTH keys so
+    // either era resolves to the declaring domain (the slice lookup strips the qualifier back off).
+    const routeKeys = (type: string): string[] =>
+      slice.qualifiableAggregates.has(type) ? [type, qualifyReadProjectionType(domainName, type)] : [type];
+    for (const type of slice.deriveds.keys()) for (const k of routeKeys(type)) add(derivedOf, k, domainName);
+    for (const type of slice.combineds.keys()) for (const k of routeKeys(type)) add(combinedOf, k, domainName);
+    for (const type of slice.aggInvariants.keys()) for (const k of routeKeys(type)) add(aggregateInvariantOf, k, domainName);
     for (const relationId of slice.invariants.keys()) add(relationOf, relationId, domainName);
     for (const wsInvariantId of slice.wsInvariants.keys()) add(workspaceInvariantOf, wsInvariantId, domainName);
   }
@@ -509,6 +538,24 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     return domainNames;
   }
 
+  /**
+   * Resolve a TYPE-keyed registry entry for a dispatch that may carry a QUALIFIED type name
+   * (read-projection namespacing — the runtime `__type` stamp is `<domain>__<type>`): try the
+   * presented key, then the bare remainder after this domain's own qualifier. Registries stay
+   * keyed by the module's bare handle ids (the source of truth); this is the one un-qualify seam.
+   */
+  function typeKeyed<T>(map: Map<string, T> | undefined, domainName: string, type: string): T | undefined {
+    if (map === undefined) return undefined;
+    const direct = map.get(type);
+    if (direct !== undefined) return direct;
+    // Strip the domain qualifier at the LAST delimiter — bare type names never contain `.`,
+    // and the qualifier's domain half is mint-tag-safe-ENCODED (`_`→`-`), so a raw-domainName
+    // prefix compare would miss (`co2_platform` qualifies as `co2-platform.`).
+    void domainName;
+    const i = type.lastIndexOf(READ_PROJECTION_DELIMITER);
+    return i > 0 ? map.get(type.slice(i + READ_PROJECTION_DELIMITER.length)) : undefined;
+  }
+
   const REPORTS: Record<string, (actor: string) => EngineReport> = config.reports ?? {};
 
   // ── the five planReport dispatch branches (wire shapes are the host oracle's contract) ──
@@ -555,7 +602,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     // Later domain wins (the Map.set fold order of the one flat registry).
     let body: AggregateInvariantFn | undefined;
     for (const domainName of domainsFor(routing.aggregateInvariantOf, aggregateType)) {
-      const found = sliceOf(domainName)?.aggInvariants.get(aggregateType);
+      const found = typeKeyed(sliceOf(domainName)?.aggInvariants, domainName, aggregateType);
       if (found !== undefined) body = found;
     }
     // VACUOUS HOLDS: a type with NO declared invariant trivially holds — `{accept:true}`,
@@ -680,7 +727,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     // Domain declaration order, then module export order — the eager fold order.
     const fields: DerivedDecl[] = [];
     for (const domainName of domainsFor(routing.derivedOf, ofType)) {
-      fields.push(...(sliceOf(domainName)?.deriveds.get(ofType) ?? []));
+      fields.push(...(typeKeyed(sliceOf(domainName)?.deriveds, domainName, ofType) ?? []));
     }
     const prior = (job.priorState ?? {}) as Record<string, unknown>;
     const out: Record<string, unknown> = {};
@@ -705,7 +752,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     // Domain declaration order, then module export order — the eager fold order.
     const fields: CombinedDecl[] = [];
     for (const domainName of domainsFor(routing.combinedOf, ofType)) {
-      fields.push(...(sliceOf(domainName)?.combineds.get(ofType) ?? []));
+      fields.push(...(typeKeyed(sliceOf(domainName)?.combineds, domainName, ofType) ?? []));
     }
     const owner = (job.priorState ?? {}) as Record<string, unknown>;
     // Preferred: related rows keyed by combined field id (iteration-order independent);
@@ -822,7 +869,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     // token qualifies explicitly. (`module.domain` === `intent.domain`.) Synchronous plan execution ⇒
     // cleared in the `finally`.
     const slice = sliceOf(domain)!;
-    __setDispatchContext({ domain, qualifiable: slice.qualifiableRelations });
+    __setDispatchContext({ domain, qualifiable: slice.qualifiableRelations, qualifiableAggregates: slice.qualifiableAggregates });
     let wire: ReturnType<typeof executeDirectiveToIntent>;
     try {
       wire = executeDirectiveToIntent(entry.directive, entry.agg, intent.payload as never, ctx);

package/src/framework/birth_meter.ts

@@ -0,0 +1,125 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine}.  If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * framework/birth_meter — THE BIRTH-ALLOWANCE GOVERNANCE SURFACE (metered birth, slice A2/A3).
+ *
+ * The meter's STRUCTURE (record + queries + quota invariant + auto-capture) is auto-ensured on every
+ * `.births()` law — see `../birth_meter.ts`. THIS module is the part a tenant COMPOSES IN when they
+ * want to GOVERN the allowance instead of living on the conservative default:
+ *
+ *   - {@link setBirthPolicy}      — set/amend the workspace's default allowance (admin-gated).
+ *   - {@link grantBirthAllowance} — a per-subject override (admin-gated; latest grant wins).
+ *   - {@link seedBirthPolicy}     — THE GENESIS SEED (A3, ungated like `seedGenesis`): the step a
+ *       parent's birth recipe threads (`buildGenesisChain`'s `descendantPool`) so the child is BORN
+ *       BOUNDED — the pool chains to root by induction (root bounds platforms, platforms bound
+ *       homes, homes bound estates). Control-plane protected exactly like `seedGenesis`: the open
+ *       session lane structurally refuses control-plane intents, and post-genesis writes on a
+ *       warranted workspace require signed authorship.
+ *
+ * V1 BOUNDARY (deliberate, stated in `architecture/metered_birth_and_attested_reads.md`): each node
+ * enforces ITS OWN count-quota; cross-level pool CONSERVATION arithmetic (a node may not grant its
+ * children more than it holds) is v2.
+ */
+import { z } from "zod";
+import { instance } from "../aggregate.js";
+import { directive } from "../directive.js";
+import { set, type PlannedOp } from "../ops.js";
+import {
+  BirthPolicy,
+  BirthGrant,
+  BIRTH_POLICY_ID,
+  birthGrantId,
+} from "../birth_meter.js";
+
+// Re-export the whole meter core so `@githolon/dsl` framework consumers get one import site.
+export {
+  NomosBirthRecord,
+  BirthPolicy,
+  BirthGrant,
+  BIRTH_POLICY_ID,
+  NOMOS_BIRTH_RECORD_PREFIX,
+  birthRecordId,
+  birthGrantId,
+  birthRecordsByPrincipal,
+  birthPolicy,
+  birthGrantByPrincipal,
+  DEFAULT_MAX_BIRTHS_PER_PRINCIPAL,
+  birthQuotaVerdict,
+  birthQuotaInvariantId,
+} from "../birth_meter.js";
+
+/** The BirthPolicy singleton upsert ops (shared by the governed set and the genesis seed). */
+function birthPolicyOps(p: { maxBirthsPerPrincipal: number; setBy: string; setAt: string }): PlannedOp[] {
+  const pol = instance(BirthPolicy, BIRTH_POLICY_ID);
+  return [
+    set(pol, "scope", "workspace"),
+    set(pol, "maxBirthsPerPrincipal", p.maxBirthsPerPrincipal),
+    set(pol, "setBy", p.setBy),
+    set(pol, "setAt", p.setAt),
+  ];
+}
+
+/**
+ * setBirthPolicy — set (or amend) THE WORKSPACE'S BIRTH ALLOWANCE DEFAULT. An Ensure on the
+ * law-state singleton (deterministic id — the `setCloudPolicy` shape), gated on the workspace's
+ * admin relation (the existing relation-gate idiom).
+ */
+export const setBirthPolicy = directive("setBirthPolicy")
+  .ensures(BirthPolicy)
+  .payload(
+    z.object({
+      maxBirthsPerPrincipal: z.number().int().positive(),
+      setBy: z.string().min(1),
+      /** Caller-stamped (the timestamp doctrine). */
+      setAt: z.string().min(1),
+    }),
+  )
+  .plan((p) => birthPolicyOps(p))
+  .requires("admin");
+
+/**
+ * seedBirthPolicy — THE GENESIS SEED (A3). Identical ops to {@link setBirthPolicy} but UNGATED,
+ * because it runs INSIDE a child's genesis recipe (before any admin relation exists) — exactly the
+ * `seedGenesis` idiom: a birth-door control-plane write the open session lane structurally refuses,
+ * and which post-genesis signed-authorship protects on every warranted workspace.
+ */
+export const seedBirthPolicy = directive("seedBirthPolicy")
+  .ensures(BirthPolicy)
+  .payload(
+    z.object({
+      maxBirthsPerPrincipal: z.number().int().positive(),
+      setBy: z.string().min(1),
+      setAt: z.string().min(1),
+    }),
+  )
+  .plan((p) => birthPolicyOps(p));
+
+/**
+ * grantBirthAllowance — a PER-SUBJECT allowance override (the `grantQuota` shape): the LATEST grant
+ * (max `grantedAt`) for a subject is the allowance in force, overriding the BirthPolicy default.
+ * Admin-gated via the existing relation-gate idiom.
+ */
+export const grantBirthAllowance = directive("grantBirthAllowance")
+  .ensures(BirthGrant)
+  .payload(
+    z.object({
+      principal: z.string().min(1),
+      maxBirths: z.number().int().positive(),
+      grantedBy: z.string().min(1),
+      /** epoch-ms — the recency tiebreak (latest grant wins), caller-stamped. */
+      grantedAt: z.number().int().nonnegative(),
+    }),
+  )
+  .plan((p) => {
+    const g = instance(BirthGrant, birthGrantId(p.principal));
+    return [
+      set(g, "principal", p.principal),
+      set(g, "maxBirths", p.maxBirths),
+      set(g, "grantedBy", p.grantedBy),
+      set(g, "grantedAt", p.grantedAt),
+    ];
+  })
+  .requires("admin");

package/src/framework/impure_capability.ts

@@ -165,7 +165,10 @@ export function impureCapabilityAggregate<
   const Id extends string,
   P extends Record<string, Field>,
 >(id: Id, params: P): AggregateHandle<Id, typeof IMPURE_CAPABILITY_ENVELOPE & P> {
-  return aggregate(id, { ...IMPURE_CAPABILITY_ENVELOPE, ...params });
+  // GLOBAL (read-projection namespacing opt-out): the capability lane addresses the envelope
+  // by its BARE declared id (`nomosCapabilities.aggregateId` → the obligation rows the holon
+  // surfaces), so the envelope's type name must not be domain-qualified.
+  return aggregate(id, { ...IMPURE_CAPABILITY_ENVELOPE, ...params }, { global: true });
 }
 
 /**
@@ -235,7 +238,7 @@ const deadLetterSchema = z.object({
  * handle; the envelope handle just types the envelope subset for `set()`).
  */
 function envelopeInstance(aggregateId: string, requestId: string) {
-  const envelopeHandle = aggregate(aggregateId, IMPURE_CAPABILITY_ENVELOPE);
+  const envelopeHandle = aggregate(aggregateId, IMPURE_CAPABILITY_ENVELOPE, { global: true });
   return instance(envelopeHandle, impureCapabilityInstanceId(requestId));
 }
 

package/src/framework/platform_admin.ts

@@ -188,7 +188,10 @@ export function seedPlatformAdmin(opts: SeedPlatformAdminOptions): PlatformAdmin
     relation: t.string().merge(Lww),
     /** ISO-8601, caller-stamped (determinism — no clock in the plan). */
     seededAt: t.string().merge(Lww),
-  });
+    // GLOBAL (read-projection namespacing opt-out): a dynamically-named framework aggregate —
+    // platform governance law deploys under differing domain keys (root vs each platform), and the
+    // founder singleton's bare identity must stay stable across them.
+  }, { global: true });
 
   /**
    * GENESIS SEED 1 — stamp the founder singleton at the fixed id. Authored by the platform's birth/genesis

package/src/framework/relations.ts

@@ -48,6 +48,7 @@ import { set, setEntry, withMarker, type PlannedOp } from "../ops.js";
 import { query } from "../query.js";
 import { endorsementOf, type AttributionPrincipal, type EndorsedAuthority } from "../principal_evidence.js";
 import { isRelationObjectToken, qualifyRelationType, type RelationObjectToken } from "../relation_schema.js";
+import { qualifyReadProjectionType } from "../read_projection_namespace.js";
 
 // ─────────────────────────────── the dispatch context (relation-namespacing) ───────────────────────────────
 //
@@ -71,6 +72,12 @@ interface DispatchContext {
   readonly domain: string;
   /** `<type>#<relation>` for every LOCAL non-global authored relation of this domain — the qualify set. */
   readonly qualifiable: ReadonlySet<string>;
+  /**
+   * READ-PROJECTION NAMESPACING: the NON-GLOBAL aggregate ids of the dispatching domain — the set
+   * whose event `__type` stamp qualifies to `<domain>__<type>` (matching the compiler's qualified
+   * read-projection / prim / stable-id keys). Absent (probe lanes) ⇒ no aggregate qualification.
+   */
+  readonly qualifiableAggregates?: ReadonlySet<string>;
 }
 
 const EMPTY_QUALIFIABLE: ReadonlySet<string> = new Set<string>();
@@ -90,6 +97,18 @@ export function __setDispatchDomain(domain: string | undefined): void {
   _ctx = domain === undefined ? undefined : { domain, qualifiable: EMPTY_QUALIFIABLE };
 }
 
+/**
+ * READ-PROJECTION NAMESPACING (the aggregate-type mirror of `resolveTupleObject`): qualify an event's
+ * aggregate TYPE by the dispatching domain IFF the domain declares it as a NON-GLOBAL aggregate — so the
+ * `__type` a plan's ops stamp equals the qualified schema key the compiler wrote (`usd.ts`). A global /
+ * foreign / unknown type, or a dispatch outside a plan (codegen probes), passes through BARE. Called by
+ * `wire_encode.ts::executeDirectiveToIntent` at the one event-emission point.
+ */
+export function __qualifyAggregateType(type: string): string {
+  if (_ctx === undefined || _ctx.qualifiableAggregates === undefined) return type;
+  return _ctx.qualifiableAggregates.has(type) ? qualifyReadProjectionType(_ctx.domain, type) : type;
+}
+
 /** Resolve a `writeTuple`/`removeTuple` object for a given relation (token → qualify; string → classify). */
 function resolveTupleObject(object: string | RelationObjectToken, relation: string): string {
   // A TOKEN is explicit sugar — always qualify its type by the dispatching domain.

package/src/framework/workspaces.ts

@@ -482,6 +482,13 @@ export function buildGenesisChain(p: {
    * chains arm the signature requirement.
    */
   requiresWarrant?: boolean;
+  /**
+   * METERED BIRTH (slice A3 — the descendant budget). When present, the child's genesis includes a
+   * `seedBirthPolicy` step so it is BORN BOUNDED (its own default birth allowance per subject).
+   * OPT-IN: thread it only when the `lawHash` the order names carries `seedBirthPolicy` (a governance
+   * package compiled under the metered-birth DSL) — see the poolSteps note below.
+   */
+  descendantPool?: number;
 }): string {
   const founder = "user:" + p.principal;
   // THE ORDER-DECLARED LAW INSTALL (G3): the child installs the EXACT law the order names — bytes are NOT in
@@ -508,8 +515,29 @@ export function buildGenesisChain(p: {
     authorizationHash: "",
     parentHead: "",
   });
+  // METERED BIRTH (slice A3 — THE POOL CHAINS TO ROOT): when the order carries a `descendantPool`, the
+  // child is BORN BOUNDED — a `seedBirthPolicy` genesis step writes the child's own BirthPolicy singleton
+  // (its default birth allowance) BEFORE the warrant lands, exactly like every other genesis seed (the
+  // still-warrant-free prefix runs unsigned). Root bounds platforms (this pool), platforms bound homes,
+  // homes bound estates — the tree meters by induction, with zero cross-workspace reads on any gate.
+  // OPT-IN (deliberate): the step folds through the CHILD'S OWN gate under the law hash the order names,
+  // so it may only be threaded when that law carries `seedBirthPolicy` (a law compiled under this DSL) —
+  // an unconditional default would refuse the genesis of every birth pinning an OLDER law hash. V1
+  // BOUNDARY: each node enforces its own count-quota; cross-level pool CONSERVATION arithmetic is v2.
+  const poolSteps =
+    p.descendantPool !== undefined
+      ? [
+          {
+            domain: "workspaces",
+            directiveId: "seedBirthPolicy",
+            actor: founder,
+            payload: { maxBirthsPerPrincipal: p.descendantPool, setBy: p.principal, setAt: p.bornAt },
+          },
+        ]
+      : [];
   return JSON.stringify([
     ...installSteps,
+    ...poolSteps,
     // THE WARRANT-FLIP (THE GOVERNANCE DEFAULT): a governance birth is born WARRANTED by default — a REAL
     // self-id (the workspace name) so signed control-plane authorship is enforced on every lane. The ONLY
     // way to stay on the legacy host-stamped lane ("" self-id, byte-identical to a pre-VA chain) is an
@@ -926,6 +954,11 @@ export const birthChild = directive("birthChild")
          *  is born WARRANTED (signed authorship enforced on every lane). Absent/false ⇒ the legacy
          *  host-stamped lane (byte-identical to a pre-VA birth). Only meaningful with a genesis. */
         requiresWarrant: z.boolean().optional(),
+        /** METERED BIRTH (slice A3): the child's own descendant budget — when present, the genesis
+         *  recipe seeds the child's BirthPolicy (`seedBirthPolicy`) so it is BORN BOUNDED. OPT-IN:
+         *  only pass it when the `lawHash` the order names carries `seedBirthPolicy` (a governance
+         *  package compiled under the metered-birth DSL). Only meaningful with a genesis. */
+        descendantPool: z.number().int().positive().optional(),
       })
       // A genesis birth (a platform) must carry a principal AND a bornAt — it owns a subtree, a lineage
       // anchor, and a law-authored genesis chain whose warrant is stamped at bornAt.
@@ -946,7 +979,7 @@ export const birthChild = directive("birthChild")
       // EXPLICITLY opts out (`requiresWarrant === false`). Thread the flag through ONLY when the request set
       // it — undefined falls to buildGenesisChain's warranted default; an explicit `false` rides the compat
       // hatch (an era-safe legacy re-build).
-      const genesisChain = buildGenesisChain({ name: p.name, principal: p.principal, parent: p.parent, tier: p.tier, foundingAdminHash: p.foundingAdminHash, bornAt: p.bornAt as string, requestedAt: p.requestedAt, ...(p.frameworkHash ? { frameworkHash: p.frameworkHash } : {}), ...(p.lawHash ? { lawHash: p.lawHash } : {}), ...(p.requiresWarrant !== undefined ? { requiresWarrant: p.requiresWarrant } : {}) });
+      const genesisChain = buildGenesisChain({ name: p.name, principal: p.principal, parent: p.parent, tier: p.tier, foundingAdminHash: p.foundingAdminHash, bornAt: p.bornAt as string, requestedAt: p.requestedAt, ...(p.frameworkHash ? { frameworkHash: p.frameworkHash } : {}), ...(p.lawHash ? { lawHash: p.lawHash } : {}), ...(p.requiresWarrant !== undefined ? { requiresWarrant: p.requiresWarrant } : {}), ...(p.descendantPool !== undefined ? { descendantPool: p.descendantPool } : {}) });
       // THE GENESIS RECIPE IS ALSO A LINEAGE/AUDIT FACT on the parent's chain (the parent records what it
       // ORDERED — law naming law, legitimate). The kernel does NOT read this field to detect the birth.
       rec.set("genesisChain", genesisChain);
@@ -1645,3 +1678,11 @@ export const workspaceQuotaBirth = workspaceInvariant("WorkspaceQuotaBirth")
   .assert((_snapshots, ctx) =>
     quotaVerdict(ctx?.reads ?? [], String((ctx?.intent ?? {}).principal ?? "")),
   );
+
+// ── METERED BIRTH (slice A — the allowance governance in the workspaces domain) ─────────────────────
+// Re-exported here so any governance package composed from THIS module carries the birth-allowance
+// surface: `setBirthPolicy`/`grantBirthAllowance` (admin-gated) and `seedBirthPolicy` — the A3 genesis
+// seed `buildGenesisChain`'s `descendantPool` step dispatches as `workspaces/seedBirthPolicy` (it must
+// live in the SAME domain key the genesis recipe names). The meter's structural half (record + quota)
+// is auto-ensured by `.births()` — see `../birth_meter.ts`.
+export { setBirthPolicy, seedBirthPolicy, grantBirthAllowance, BirthPolicy, BirthGrant, NomosBirthRecord, birthRecordsByPrincipal, birthPolicy, birthGrantByPrincipal } from "./birth_meter.js";

package/src/index.ts

@@ -58,6 +58,7 @@ export {
   type GeoPointValue,
   type GeoLineStringValue,
   type GeoPolygonValue,
+  type ValueObjectUsage,
 } from "./value_object.js";
 export {
   type PrincipalEvidence,
@@ -331,6 +332,28 @@ export {
   birthAttestation,
   parentAttestedBirth,
 } from "./framework/home.js";
+// METERED BIRTH (slice A — architecture/metered_birth_and_attested_reads.md): the structural birth
+// record + the parent-local birth quota + the allowance governance surface. The record/quota STRUCTURE
+// is auto-ensured on every `.births()` law (zero tenant code); these exports are the GOVERNANCE half a
+// tenant composes in to set/override allowances, plus the constants/predicates tests and tools read.
+export {
+  NomosBirthRecord,
+  BirthPolicy,
+  BirthGrant,
+  BIRTH_POLICY_ID,
+  NOMOS_BIRTH_RECORD_PREFIX,
+  birthRecordId,
+  birthGrantId,
+  birthRecordsByPrincipal,
+  birthPolicy,
+  birthGrantByPrincipal,
+  DEFAULT_MAX_BIRTHS_PER_PRINCIPAL,
+  birthQuotaVerdict,
+  birthQuotaInvariantId,
+  setBirthPolicy,
+  seedBirthPolicy,
+  grantBirthAllowance,
+} from "./framework/birth_meter.js";
 // THE PLATFORM FOUNDING-ADMIN BOOTSTRAP (the platform analog of seedHomeCreator) — a tenant-importable
 // factory that seats a tenant-named governance relation for a write-once, author-bound founder at genesis.
 export {
@@ -457,6 +480,17 @@ export {
   type AllowedSubject,
   type RelationCaps,
 } from "./relation_schema.js";
+
+// READ-PROJECTION (aggregate-type) NAMESPACING — the read-layer mirror of the relation namespacing:
+// the qualifier, the deliberate framework GLOBAL allowlist, and the classification the compiler +
+// sealed engine share (`aggregate(id, fields, { global: true })` is the dynamic opt-out).
+export {
+  READ_PROJECTION_DELIMITER,
+  GLOBAL_READ_PROJECTION_AGGREGATE_IDS,
+  qualifyReadProjectionType,
+  isNamespacedAggregate,
+  namespacedAggregateIds,
+} from "./read_projection_namespace.js";
 // SECURE-BY-DEFAULT SUGAR over the relation schema — plain-English combinators, audiences, presets.
 // Pure sugar: every export here BUILDS the existing Rewrite/RelationTypeDecl AST (no new wire shape).
 export {

package/src/read.ts

@@ -74,6 +74,28 @@ export function read<T = unknown>(query: QueryDecl, args: Record<string, string>
   return result;
 }
 
+/**
+ * THE BIRTH-METER CAPTURE (metered birth, slice A2 — library-internal). Identical semantics to
+ * {@link read} — serve the declared query live off `nomos.read` + record `{queryId, args, result}`
+ * into the SAME per-dispatch footprint — but with a DISTINCT refusal string, deliberately NOT the
+ * {@link CAPTURED_READ_LUMP_MARKER}: the marker greps for TENANT-authored `read()` calls that lack a
+ * declaration, whereas this door is only ever invoked by the `.births()` lane (which auto-DECLARES
+ * its three queries on the directive), so a lump that merely bundles it must not trip the read-free
+ * compile gate. A `.births()` dispatch on a host with no `nomos.read` still halts NAMED (fail-closed).
+ */
+export function __captureBirthMeterRead(query: QueryDecl, args: Record<string, string>): void {
+  const h = host() as { read?: unknown } | undefined;
+  if (typeof h?.read !== "function") {
+    throw new Error(
+      `birth-meter read('${query.id}'): this host provides no nomos.read port — a .births() ` +
+        `dispatch captures its quota reads through the engine/client runtime (tests: stub ` +
+        `globalThis.nomos.read).`,
+    );
+  }
+  const result = host().read(query.id, args);
+  footprint.push({ queryId: query.id, args, result });
+}
+
 /**
  * The compile gate's lump sentinel — the EXACT substring of the refusal `read()` throws above.
  * It exists in a bundled engine lump iff `read` itself survived tree-shaking, i.e. iff some

package/src/read_projection_composition.ts

@@ -0,0 +1,117 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · SQLite projection · embedded QuickJS engine}.
+//
+// COMPILE-TIME DIVERGENCE GUARD for SHARED read-projection keys — the read-layer
+// 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,
+// `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.
+//
+// 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
+// shape. Validation only — a conflict-free package is returned untouched (era rule).
+
+import type { UsdLayer } from "./usd.js";
+import { domainOfLayerPath } from "./relation_composition.js";
+
+/** One shared-key divergence, gathered for the scalpel message. */
+interface ReadProjectionConflict {
+  /** The accumulator section (`aggregateFieldKinds`, `queries`, …). */
+  readonly section: string;
+  /** The colliding accumulator key (the kernel's exact key). */
+  readonly key: string;
+  /** Each contributing domain's declaration, in package (weak→strong) order. */
+  readonly opinions: { readonly domain: string; readonly shape: string }[];
+}
+
+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.`,
+    ``,
+  ];
+  for (const c of conflicts) {
+    lines.push(
+      `  read projection "${c.section}" key "${c.key.replace("\0", " · ")}" — ${c.opinions.length} divergent declarations:`,
+    );
+    const w = Math.max(...c.opinions.map((o) => o.domain.length));
+    for (const o of c.opinions) lines.push(`      · ${o.domain.padEnd(w)}  ${o.shape}`);
+  }
+  lines.push(
+    ``,
+    `Fix: give the shared key ONE canonical declaration (the domains must agree, byte-for-byte — ` +
+      `for a framework aggregate that means the SAME framework version in every domain), or make ` +
+      `the declarations DISTINCT (a non-global aggregate auto-qualifies by its owning domain; a ` +
+      `declared read can simply take a different id).`,
+  );
+  return lines.join("\n");
+}
+
+type Fragment = NonNullable<UsdLayer["nomosReadProjection"]>;
+
+/** The accumulator sections keyed by declared `id` (mirrors `merge_projection_array_by_id`). */
+const BY_ID_SECTIONS = ["queries", "counts", "spatials", "sums", "mins", "maxes", "orderedReads"] as const;
+/** The sections keyed by `"<of>\0<id>"` (mirrors `merge_projection_array_by_type_and_id`). */
+const BY_TYPE_AND_ID_SECTIONS = ["deriveds", "combineds"] as const;
+
+/**
+ * Guard the package's layers against a shared-read-projection-key divergence — the EXACT key
+ * semantics the kernel accumulator merges by. Identical shared declarations pass (dedupe);
+ * divergent ones throw the scalpel. Deterministic (sorted keys/sections). Returns the layers
+ * UNTOUCHED (validation only).
+ *
+ * @throws a scalpel `Error` naming the section, key, and each domain's declaration on divergence.
+ */
+export function guardSharedReadProjectionKeys(layers: readonly UsdLayer[]): readonly UsdLayer[] {
+  // section → key → the contributing {domain, canonical JSON} opinions, in package order.
+  const seen = new Map<string, Map<string, { domain: string; shape: string }[]>>();
+  const note = (section: string, key: string, domain: string, value: unknown): void => {
+    const bySection = seen.get(section) ?? new Map<string, { domain: string; shape: string }[]>();
+    seen.set(section, bySection);
+    const arr = bySection.get(key) ?? [];
+    arr.push({ domain, shape: JSON.stringify(value) });
+    bySection.set(key, arr);
+  };
+
+  for (const layer of layers) {
+    const frag: Fragment | undefined = layer.nomosReadProjection;
+    if (frag === undefined) continue;
+    const domain = domainOfLayerPath(layer.path);
+    for (const [ty, schema] of Object.entries(frag.aggregateFieldKinds ?? {})) {
+      note("aggregateFieldKinds", ty, domain, schema);
+    }
+    const bag = frag as unknown as Record<string, readonly { id: string; of?: string }[] | undefined>;
+    for (const section of BY_ID_SECTIONS) {
+      for (const item of bag[section] ?? []) note(section, item.id, domain, item);
+    }
+    for (const section of BY_TYPE_AND_ID_SECTIONS) {
+      for (const item of bag[section] ?? []) note(section, `${item.of}\0${item.id}`, domain, item);
+    }
+  }
+
+  const conflicts: ReadProjectionConflict[] = [];
+  for (const section of [...seen.keys()].sort()) {
+    const bySection = seen.get(section)!;
+    for (const key of [...bySection.keys()].sort()) {
+      const opinions = bySection.get(key)!;
+      if (opinions.length < 2) continue;
+      const distinct = new Set(opinions.map((o) => o.shape));
+      if (distinct.size > 1) conflicts.push({ section, key, opinions });
+    }
+  }
+  if (conflicts.length > 0) throw new Error(scalpelMessage(conflicts));
+  return layers;
+}