@githolon/dsl 0.32.0 → 0.34.0

package/src/compile_package_main.ts

@@ -84,6 +84,8 @@ import {
   type Mod,
 } from "./build_package.js";
 import { synthesizePreconditionInvariants } from "./precondition.js";
+import { BIRTH_METER_QUERIES, synthesizeBirthQuotaInvariants } from "./birth_meter.js";
+import { withBirthMeterExports } from "./birth_meter_ensure.js";
 import { collectEngineRouting } from "./engine_entry.js";
 import {
   discover,
@@ -422,8 +424,25 @@ function emitDart(
   const frameworkAggIds: ReadonlySet<string> = new Set(frameworkAggById.keys());
   const frameworkDirIds: ReadonlySet<string> = new Set(frameworkDirById.keys());
   const frameworkQueryIds: ReadonlySet<string> = new Set(frameworkQueryById.keys());
+  // VALUE OBJECTS shared by ≥2 domains: their generated Dart class emits ONCE in the shared
+  // `nomos_framework.dart` (the same collision rule as framework symbols — a barrel re-exporting
+  // two domains must not define one VO class twice). A single-domain VO stays in its domain file.
+  const voDomainsByName = new Map<string, number>();
+  const voDescriptorByName = new Map<string, NonNullable<DomainModule["valueObjects"]>[number]>();
+  for (const mod of modules) {
+    for (const d of mod.valueObjects ?? []) {
+      voDomainsByName.set(d.name, (voDomainsByName.get(d.name) ?? 0) + 1);
+      voDescriptorByName.set(d.name, d);
+    }
+  }
+  const sharedVoNames: ReadonlySet<string> = new Set(
+    [...voDomainsByName.entries()].filter(([, n]) => n > 1).map(([name]) => name),
+  );
+  const sharedVos = [...sharedVoNames]
+    .sort()
+    .map((name) => voDescriptorByName.get(name)!);
   const hasFrameworkSymbols =
-    frameworkAggs.length > 0 || frameworkDirs.length > 0 || frameworkQueries.length > 0;
+    frameworkAggs.length > 0 || frameworkDirs.length > 0 || frameworkQueries.length > 0 || sharedVos.length > 0;
   const FRAMEWORK_FILE = "nomos_framework";
   const frameworkImportUri = hasFrameworkSymbols ? `${FRAMEWORK_FILE}.dart` : undefined;
 
@@ -455,6 +474,8 @@ function emitDart(
       directives: frameworkDirs,
       readModelAggregates: frameworkAggs.map((a) => a.id),
       ...(frameworkQueries.length > 0 ? { queries: frameworkQueries } : {}),
+      // Package-SHARED value objects (used by ≥2 domains) — their class emits here, once.
+      ...(sharedVos.length > 0 ? { valueObjects: sharedVos } : {}),
     };
     writeGenerated(FRAMEWORK_FILE, generateDartDomain(frameworkMod));
   }
@@ -480,12 +501,17 @@ function emitDart(
     const domainFwQueryIds = new Set(
       (modForDart.queries ?? []).filter((q) => frameworkQueryIds.has(q.id)).map((q) => q.id),
     );
-    const foldsFramework = domainFwAggIds.size > 0 || domainFwDirIds.size > 0 || domainFwQueryIds.size > 0;
+    const domainSharedVoNames = new Set(
+      (modForDart.valueObjects ?? []).filter((d) => sharedVoNames.has(d.name)).map((d) => d.name),
+    );
+    const foldsFramework =
+      domainFwAggIds.size > 0 || domainFwDirIds.size > 0 || domainFwQueryIds.size > 0 || domainSharedVoNames.size > 0;
     const domainFrameworkImport = foldsFramework ? frameworkImportUri : undefined;
     const src = generateDartDomain(modForDart, {
       skipAggregateIds: domainFwAggIds,
       skipDirectiveIds: domainFwDirIds,
       skipQueryIds: domainFwQueryIds,
+      skipValueObjectNames: domainSharedVoNames,
       ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
     });
     writeGenerated(mod.name, src);
@@ -596,6 +622,8 @@ async function main(): Promise<void> {
     // `capability()` bundles expand into discoverable entries (the CLI plane's
     // merge point) — queries/sums/sid-minting/manifests all see the pieces.
     merged = expandCapabilityExports(merged);
+    // METERED BIRTH: the same injection composeDomainModule/mergeModules apply — one seam, no drift.
+    merged = withBirthMeterExports(merged);
     let shardingSums: AnySum[] = [];
     let shardingMins: AnyExtremum[] = [];
     let shardingMaxes: AnyExtremum[] = [];
@@ -736,6 +764,15 @@ async function main(): Promise<void> {
       ...discover<QueryDecl>(merged, isQueryDecl),
       ...resolveNamed<QueryDecl>(merged, d.queries, "queries"),
     ];
+    // METERED BIRTH (slice A): a domain declaring ≥1 `.births()` directive gets the meter's declared
+    // queries appended (dedup by id) so the openapi self-describe decls + read routing carry them —
+    // the same auto-ensure `composeDomainModule` applies to the manifest half.
+    if (directivesOf(merged).some((dir) => (dir as { birthsChild?: boolean }).birthsChild === true)) {
+      const haveQuery = new Set(queries.map((q) => q.id));
+      for (const q of BIRTH_METER_QUERIES) {
+        if (!haveQuery.has(q.id)) queries.push(q);
+      }
+    }
     const counts = [
       ...discover<AnyCount>(merged, isCountDecl),
       ...resolveNamed<AnyCount>(merged, d.counts, "counts"),
@@ -763,6 +800,9 @@ async function main(): Promise<void> {
     const workspaceInvariantsForDecls = [
       ...workspaceInvariants,
       ...directivesOf(merged).flatMap((dir) => synthesizePreconditionInvariants(dir)),
+      // METERED BIRTH (slice A2): the synthesized birth-quota invariants (also synthesized inside
+      // `composeDomainModule`) — recomposed here purely for the openapi self-describe decls.
+      ...directivesOf(merged).flatMap((dir) => synthesizeBirthQuotaInvariants(dir)),
     ];
     // Native Zanzibar relation schema (P1) — auto-discovered by brand, like workspaceInvariants.
     const relationTypes = [

package/src/directive.ts

@@ -23,6 +23,7 @@ import type { Ports } from "./ctx.js";
 import type { CertifiedReadDecl } from "./certified_read.js";
 import type { RelationDecl } from "./relation.js";
 import type { QueryDecl } from "./query.js";
+import { BIRTH_METER_QUERIES } from "./birth_meter.js";
 
 export type ReferentialMarker = "creates" | "mutates" | "ensures" | "archives";
 
@@ -685,7 +686,15 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       // BIRTH AS A DECLARED KERNEL PRIMITIVE (G3): mark this directive a birth — its plan's `birth(recipe)`
       // rides the intent, and the kernel (reading the `nomosBirthGate` era key, not domain state) executes
       // the birth after admit. Era-ruled: a non-birthing directive omits the flag and is byte-identical.
-      return makeRequirable({ ...base, birthsChild: true });
+      // METERED BIRTH (slice A): `.births()` ALSO auto-declares the three birth-meter captured reads
+      // (`birthRecordsByPrincipal`/`birthGrantByPrincipal`/`birthPolicy` — the #58 lane), so the
+      // `nomosReadGate` era key carries them by construction and the meter reads the `.births()` dispatch
+      // auto-captures (see `executeDirectiveToIntent`) CAS-verify on every lane. The era is the bundle:
+      // recompiling under this DSL is what arms the meter (every pre-era bundle replays byte-green).
+      const byId = new Map<string, QueryDecl>((base.declaredQueryReads ?? []).map((q) => [q.id, q]));
+      for (const q of BIRTH_METER_QUERIES) byId.set(q.id, q);
+      const mergedQueries = [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+      return makeRequirable({ ...base, birthsChild: true, declaredQueryReads: mergedQueries });
     },
     grants(relation: string): RequirableDirective<P> {
       // PROOF-TOOLING PRODUCER MARKER (symmetric to `.requires`): record that this directive establishes

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/fields.ts

@@ -72,6 +72,62 @@ export const evidenceRefSchema: z.ZodType<EvidenceRefValue> = z.object({
   storageClass: z.enum(["git", "external"]),
 });
 
+// ── VALUE OBJECTS (composable value objects — `value_object.ts`) ─────────────────────
+// The descriptor types live HERE (dependency-free) so `Field` can carry the metadata
+// without a `fields.ts → value_object.ts` cycle; `value_object.ts` re-exports them.
+
+/** The RFC 7946 geometry kinds a `geo.*` value object can declare (Point is the
+ *  spatial-index-blessed one; see `spatial.ts`). */
+export type GeometryKind = "Point" | "LineString" | "Polygon";
+
+/**
+ * One field of a value-object DESCRIPTOR — the canonical, JSON-schema-ish shape that
+ * rides the package IR (`nomosValueObjects`) and drives TS/Dart codegen. `optional`
+ * is PRESENT only when true (omit-when-false — descriptor bytes are deterministic).
+ * `array.items` is a nested descriptor WITHOUT `optional` (an array of optionals is
+ * not expressible — the v1 constrained set).
+ */
+export type ValueObjectFieldDescriptor =
+  | { readonly type: "string"; readonly optional?: true }
+  | { readonly type: "number"; readonly optional?: true }
+  | { readonly type: "boolean"; readonly optional?: true }
+  | { readonly type: "enum"; readonly values: readonly string[]; readonly optional?: true }
+  | { readonly type: "array"; readonly items: ValueObjectFieldDescriptor; readonly optional?: true }
+  /** A nested value object, referenced BY NAME (its own descriptor rides alongside). */
+  | { readonly type: "object"; readonly ref: string; readonly optional?: true }
+  /** A nested GEO value object (RFC 7946 geometry), referenced by name. */
+  | { readonly type: "geometry"; readonly ref: string; readonly geometry: GeometryKind; readonly optional?: true };
+
+/**
+ * The canonical descriptor of ONE named value object. A structural VO carries
+ * `fields` (keys SORTED — byte-determinism); a `geo.*` VO carries `geometry`
+ * instead (its shape is fixed by RFC 7946, not authored).
+ */
+export interface ValueObjectDescriptor {
+  readonly name: string;
+  readonly fields?: Readonly<Record<string, ValueObjectFieldDescriptor>>;
+  readonly geometry?: GeometryKind;
+}
+
+/**
+ * The value-object metadata a VO-typed `Field` carries (`ValueObject.field()` sets it).
+ * FRONTEND/IR-ONLY: it never enters the kernel wire `Schema` (driver-only — see
+ * `encodeKernelSchema`) nor the canonical manifest, so a VO field's domainHash is
+ * IDENTICAL to a hand-rolled `t.jsonObject()` field. The additive `nomosValueObjects`
+ * USD key (built by `composeDomainModule`/`usd.ts` FROM this metadata) is what makes
+ * the structure visible to tooling.
+ */
+export interface ValueObjectFieldMeta {
+  /** The VO's declared name (the generated TS interface / Dart class name). */
+  readonly name: string;
+  /** This VO's own canonical descriptor. */
+  readonly descriptor: ValueObjectDescriptor;
+  /** Every TRANSITIVELY nested VO's descriptor (self excluded), sorted by name. */
+  readonly dependencies: readonly ValueObjectDescriptor[];
+  /** Present iff this VO is a `geo.*` geometry (the spatial-index pairing check). */
+  readonly geometry?: GeometryKind;
+}
+
 export interface Field<T = unknown, K extends FieldKind = FieldKind> {
   /** The kind tag. `K` is the LITERAL kind so the query DSL can constrain `.ref`
    * to ONLY `kind:'ref'` fields at compile time (`t.ref` → `Field<string,'ref'>`).
@@ -113,6 +169,15 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * `encodeKernelSchema`) — so it changes NO hash (identical to `mapValueKind`/`isOptional`).
    */
   readonly jsonShape?: "object";
+  /**
+   * For a `json`-kind field lowered from a NAMED VALUE OBJECT (`ValueObject.field()`):
+   * the VO metadata (name + canonical descriptor + nested-VO dependencies). Drives the
+   * generated TS interface / Dart class and the additive `nomosValueObjects` USD key.
+   * FRONTEND/IR-ONLY — never in the kernel wire `Schema` (driver-only), so the field's
+   * canonical-manifest bytes are identical to a plain `t.jsonObject()` (see
+   * {@link ValueObjectFieldMeta}). `undefined` for every non-VO field.
+   */
+  readonly valueObject?: ValueObjectFieldMeta;
   /**
    * Whether a folded aggregate may LACK this field. A SCALAR field
    * (`string`/`int`/`enum`/`ref`/`json`) that a `.creates` directive does not
@@ -184,6 +249,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     isOptional?: boolean;
     mapValueKind?: FieldKind;
     jsonShape?: "object";
+    valueObject?: ValueObjectFieldMeta;
     encrypted?: true;
     meta?: true;
     facet?: FieldFacet;
@@ -201,6 +267,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.viaField !== undefined ? { viaField: extra.viaField } : {}),
     ...(extra.mapValueKind !== undefined ? { mapValueKind: extra.mapValueKind } : {}),
     ...(extra.jsonShape !== undefined ? { jsonShape: extra.jsonShape } : {}),
+    ...(extra.valueObject !== undefined ? { valueObject: extra.valueObject } : {}),
     ...(extra.encrypted ? { isEncrypted: true as const } : {}),
     ...(extra.meta ? { isMeta: true as const } : {}),
     merge(d: Driver) {
@@ -401,3 +468,20 @@ function refImpl(
   }
   return makeField<string, "ref">("ref", z.string(), Conflict, { refAggregateId: a.id });
 }
+
+/**
+ * INTERNAL (`value_object.ts` — `ValueObject.field()`): construct the JSON-OBJECT value
+ * leaf a named value object lowers to. Storage/merge-identical to `t.jsonObject()`
+ * (kind `"json"`, `jsonShape:"object"`, driver Lww — the whole VO replaces WHOLESALE;
+ * per-subfield merge is what aggregates/maps are for), PLUS the {@link
+ * ValueObjectFieldMeta} that names the VO for codegen + the `nomosValueObjects` IR key.
+ * The zod is the VO's TYPED object schema, so `set(handle, field, value)` and payload
+ * embedding validate the real structure. Not part of `t.*` — reach it via
+ * `valueObject(...)`/`geo.*`'s `.field()`.
+ */
+export function valueObjectField<T>(
+  zod: z.ZodType<T>,
+  valueObject: ValueObjectFieldMeta,
+): Field<T, "json"> {
+  return makeField<T, "json">("json", zod, Lww, { jsonShape: "object", valueObject });
+}

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.