@githolon/dsl 0.32.0 → 0.34.0

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

@@ -40,6 +40,26 @@ export {
   secretField,
   publicField,
 } from "./fields.js";
+// FIRST-CLASS COMPOSABLE VALUE OBJECTS (`value_object.ts`): named, reusable, nestable
+// structured values — ONE definition yields the zod (payload validation), the TS type,
+// the generated Dart class, and the `nomosValueObjects` IR descriptor. A VO lowers to a
+// single Lww-class json-object leaf (wholesale-replace merge — no per-subfield merge).
+// `geo.*` are the RFC 7946 geometry VOs (pair `geo.point()` with `spatial(...)`).
+export {
+  valueObject,
+  geo,
+  type ValueObject,
+  type ValueObjectValue,
+  type OptionalValueObject,
+  type ValueObjectShapeEntry,
+  type ValueObjectDescriptor,
+  type ValueObjectFieldDescriptor,
+  type GeometryKind,
+  type GeoPointValue,
+  type GeoLineStringValue,
+  type GeoPolygonValue,
+  type ValueObjectUsage,
+} from "./value_object.js";
 export {
   type PrincipalEvidence,
   type AttributionPrincipal,
@@ -312,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 {
@@ -438,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;
+}

package/src/read_projection_manifest.ts

@@ -0,0 +1,94 @@
+// 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}.
+//
+// READ-PROJECTION NAMESPACING — the CANONICAL-MANIFEST label transform (the compile-side
+// rename). BUILD-TIME ONLY, split out of `read_projection_namespace.ts` deliberately: this
+// file types against `manifest.ts` (which imports `node:crypto`/`Buffer` for the domain
+// hash), and the classification/qualifier half is imported by PLATFORM-NEUTRAL engine
+// files (`engine_entry.ts`, `wire_encode.ts`, `framework/relations.ts`) that tenant
+// scaffolds typecheck WITHOUT `@types/node`. Keeping the manifest edge here (reached only
+// via `usd.ts`, the build lane) keeps the neutral type graph node-free — the same
+// build/runtime split `stable_ids.ts` vs `stable_ids_types.ts` ratified.
+
+import type { CanonicalManifest } from "./manifest.js";
+import type { StableIds, StableAggregateId } from "./stable_ids_types.js";
+import { qualifyReadProjectionType } from "./read_projection_namespace.js";
+
+/**
+ * Qualify EVERY aggregate-type label a domain's canonical manifest carries — exactly as
+ * if the author had renamed `Entry` → `<domainKey>__Entry` in source, which is the #58
+ * rename the whole system already supports (sid identity unmoved; the projection folds
+ * old-label rows onto the new label via the `was` lineage). Touches: aggregate ids,
+ * directive targets, `queries[].returns`, every maintained read's `of` (counts / sums /
+ * mins / maxes / spatials / deriveds / combineds / orderedReads), `combineds[].reads`
+ * (a related aggregate TYPE — the cross-aggregate invalidation key), and the stable-ids
+ * labels (the BARE name is APPENDED to the sid's `was` lineage so pre-namespacing rows
+ * normalize onto the qualified label). Fields keep their bare labels (field names never
+ * collide across types — the accumulator keys them under the type). Pure + deterministic;
+ * with an empty `namespaced` set the manifest is returned UNTOUCHED (the era rule).
+ */
+export function qualifyManifestAggregateLabels(
+  manifest: CanonicalManifest,
+  domainKey: string,
+  namespaced: ReadonlySet<string>,
+): CanonicalManifest {
+  if (namespaced.size === 0) return manifest;
+  const qa = (n: string): string => (namespaced.has(n) ? qualifyReadProjectionType(domainKey, n) : n);
+
+  const stableIds: StableIds | undefined =
+    manifest.stableIds === undefined
+      ? undefined
+      : {
+          ...manifest.stableIds,
+          aggregates: Object.fromEntries(
+            Object.entries(manifest.stableIds.aggregates).map(([name, rec]): [string, StableAggregateId] => {
+              if (!namespaced.has(name)) return [name, rec];
+              // The bare labels this sid's rows may carry: every prior bare label + the current
+              // bare name (pre-namespacing rows; the runtime stamp is qualified going forward).
+              const was = [...new Set([...(rec.was ?? []), name])];
+              return [qa(name), { ...rec, was }];
+            }),
+          ),
+        };
+
+  return {
+    ...manifest,
+    aggregates: manifest.aggregates.map((a) => (namespaced.has(a.id) ? { ...a, id: qa(a.id) } : a)),
+    directives: manifest.directives.map((d) => (namespaced.has(d.target) ? { ...d, target: qa(d.target) } : d)),
+    ...(stableIds !== undefined ? { stableIds } : {}),
+    ...(manifest.queries !== undefined
+      ? { queries: manifest.queries.map((q) => (namespaced.has(q.returns) ? { ...q, returns: qa(q.returns) } : q)) }
+      : {}),
+    ...(manifest.counts !== undefined
+      ? { counts: manifest.counts.map((c) => (namespaced.has(c.of) ? { ...c, of: qa(c.of) } : c)) }
+      : {}),
+    ...(manifest.sums !== undefined
+      ? { sums: manifest.sums.map((s) => (namespaced.has(s.of) ? { ...s, of: qa(s.of) } : s)) }
+      : {}),
+    ...(manifest.mins !== undefined
+      ? { mins: manifest.mins.map((e) => (namespaced.has(e.of) ? { ...e, of: qa(e.of) } : e)) }
+      : {}),
+    ...(manifest.maxes !== undefined
+      ? { maxes: manifest.maxes.map((e) => (namespaced.has(e.of) ? { ...e, of: qa(e.of) } : e)) }
+      : {}),
+    ...(manifest.spatials !== undefined
+      ? { spatials: manifest.spatials.map((s) => (namespaced.has(s.of) ? { ...s, of: qa(s.of) } : s)) }
+      : {}),
+    ...(manifest.deriveds !== undefined
+      ? { deriveds: manifest.deriveds.map((d) => (namespaced.has(d.of) ? { ...d, of: qa(d.of) } : d)) }
+      : {}),
+    ...(manifest.combineds !== undefined
+      ? {
+          combineds: manifest.combineds.map((c) => ({
+            ...c,
+            ...(namespaced.has(c.of) ? { of: qa(c.of) } : {}),
+            ...(namespaced.has(c.reads) ? { reads: qa(c.reads) } : {}),
+          })),
+        }
+      : {}),
+    ...(manifest.orderedReads !== undefined
+      ? { orderedReads: manifest.orderedReads.map((r) => (namespaced.has(r.of) ? { ...r, of: qa(r.of) } : r)) }
+      : {}),
+  };
+}

package/src/read_projection_namespace.ts

@@ -0,0 +1,152 @@
+// 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}.
+//
+// READ-PROJECTION (aggregate-type) NAMESPACING — the read-layer mirror of the shipped
+// relation-type namespacing (`relation_schema.ts::qualifyRelationType`).
+//
+// THE DISEASE. The kernel's installed-read-manifest accumulator
+// (`wasm_git_holon.rs::insert_read_projection_value`) unions every ACTIVE install's
+// `nomosReadProjection` fragment and — correctly, fail-closed — REFUSES when two
+// installs declare the SAME key with DIVERGENT shapes ("divergent read projection
+// declaration for key AuthProvider"). Two different domain keys that each declare a
+// same-named aggregate therefore WEDGE the workspace's read plane at serve time.
+//
+// THE CURE (the maintainer's rule: "Namespaces are a good idea. Use them."): a
+// NON-GLOBAL aggregate's TYPE NAME is QUALIFIED by its owning domain key at compile —
+// `Entry` in domain `guestbook` becomes `guestbook.Entry` — so two domains that each
+// declare the same bare name NEVER share an accumulator key. The delimiter is `.`
+// (NOT relations' `__`: the id-mint gate splits a minted id's type tag on the first
+// `_`, and the type must also stay colon-free — see READ_PROJECTION_DELIMITER). The engine stamps the SAME qualified name onto every event's
+// `__type` at plan runtime (see `wire_encode.ts`), so the projected row's type and the
+// installed schema key agree by construction; the BARE name rides the aggregate's
+// stable-id `was` lineage so pre-namespacing rows normalize onto the qualified label
+// (the #58 rename machinery — a qualification IS a rename).
+//
+// GLOBAL (un-namespaced) aggregates — the opt-out. Framework aggregates the KERNEL
+// reads by bare name / bare instance-id convention (AuthProvider for in-kernel JWT
+// verification, RelationTuple for the native authz fold, the domain-lifecycle law
+// records, …) MUST keep their bare identity. They are enumerated DELIBERATELY in the
+// explicit allowlist below (never a heuristic); a drift test pins the list to the
+// real framework exports. A dynamically-named framework aggregate (a factory product,
+// e.g. `platformAdmin()`'s founder aggregate) opts out via `aggregate(id, fields,
+// { global: true })` instead — the flag rides the handle into BOTH the compiler and
+// the sealed engine, so the two classifications can never disagree.
+//
+// ERA RULE (the law is the era): qualification happens at COMPILE — already-deployed
+// packages are byte-identical untouched, and a qualified key is just a NEW name to the
+// kernel accumulator (no kernel change). The `nomosReadProjectionNamespace` era key is
+// emitted IFF a layer qualified ≥1 aggregate — the marker that this bundle's read keys
+// are domain-qualified (mirrors `nomosRelationNamespace`).
+
+/**
+ * The read-projection (aggregate-type) qualifier delimiter. NOT the relation namespacing's
+ * `__`, deliberately: an aggregate type is also the kernel id-mint TYPE TAG
+ * (`id-mint/src/lib.rs::type_tag_of` splits a minted id on the FIRST `_`), so an
+ * underscore-bearing type can never mint — `guestbook__Entry_uuid` parses as tag
+ * `guestbook` and refuses at the id-mint gate. And it must stay colon-free (`ObjectRef::
+ * parse` splits addresses on the first `:`). `.` satisfies both parsers. The ONE surface
+ * where `.` is illegal — a real-USD PRIM NAME (identifiers only) — is already covered by the
+ * `.usda` text lane's `primName()` sanitizer (`usd_layers.ts`), which round-trips the raw id
+ * via `nomos:id`; the TYPE STRING everywhere (prim `type` attr, directive `target`,
+ * read-projection keys, the runtime `__type` stamp, stable-id labels, the mint tag) is dotted.
+ */
+export const READ_PROJECTION_DELIMITER = ".";
+
+
+/**
+ * THE EXPLICIT GLOBAL ALLOWLIST — every STATICALLY-NAMED framework aggregate. These
+ * stay BARE on every surface (read projection, prims, stable-ids, runtime `__type`)
+ * because the kernel and the framework machinery address them by bare name /
+ * bare-name-derived instance ids (`auth-provider:platform`, the relation fold, the
+ * policy/lifecycle law records, the signer spine, the key-fanout gate, …).
+ *
+ * DELIBERATE ENUMERATION, not a heuristic: `read_projection_namespace.test.ts` pins
+ * this set to the real `FRAMEWORK_AGGREGATE_IDS` registry so it can never drift.
+ * (A tenant aggregate that merely REUSES one of these names also stays bare — that
+ * matches the kernel-couples-by-name reality and is exactly the shared-key case the
+ * compile-time divergence guard `read_projection_composition.ts` polices.)
+ */
+export const GLOBAL_READ_PROJECTION_AGGREGATE_IDS: ReadonlySet<string> = new Set([
+  // disclosure
+  "Disclosure",
+  // domain lifecycle (the law records themselves)
+  "PolicyBundle",
+  "DomainInstallation",
+  // encryption identity + scope (the operator-blind key machinery)
+  "EncKey",
+  "KeyScope",
+  "WrappedKey",
+  // genesis / births
+  "GenesisWarrant",
+  // metered birth (slice A) — NomosBirthRecord is kernel-read by the birth-record
+  // gate (the `nomos-birth-record:` prefix); the policy/grant singletons ride with it
+  "NomosBirthRecord",
+  "BirthPolicy",
+  "BirthGrant",
+  // home holons
+  "HomeOwner",
+  "SharedWithMe",
+  "BirthAttestation",
+  // identity
+  "Actor",
+  "User",
+  "DeviceKey",
+  "Organization",
+  "PublicUser",
+  // native relations (the one authz spine)
+  "RelationTuple",
+  // repair
+  "RepairRecord",
+  // signer spine
+  "SignerEpoch",
+  "SignerDelegation",
+  // governance / workspaces
+  "WorkspaceSelf",
+  "CloudWorkspace",
+  "CloudPolicy",
+  "QuotaGrant",
+  "PlatformGrant",
+  "CapabilityBinding",
+  "AuthProvider",
+  "HostnameClaim",
+]);
+
+/** The minimal handle shape the classification reads (compiler AND engine — one function). */
+export interface NamespaceClassifiable {
+  readonly id: string;
+  /** The `aggregate(id, fields, { global: true })` opt-out — kernel-coupled dynamic framework aggregates. */
+  readonly global?: boolean;
+}
+
+/**
+ * TRUE iff this aggregate's type name is NAMESPACED (qualified by its owning domain).
+ * FALSE for the explicit framework allowlist and for `{ global: true }` handles.
+ * ONE classification, consumed by the compiler (USD lowering) and the sealed engine
+ * (the runtime `__type` stamp) — they can never disagree.
+ */
+export function isNamespacedAggregate(agg: NamespaceClassifiable): boolean {
+  return agg.global !== true && !GLOBAL_READ_PROJECTION_AGGREGATE_IDS.has(agg.id);
+}
+
+/**
+ * Qualify a bare aggregate type by its owning domain key: `("guestbook","Entry") → "guestbook.Entry"`.
+ * The domain-key half is MINT-TAG-SAFE-encoded (`_` → `-`): the qualified type is also the kernel
+ * id-mint TYPE TAG, and `type_tag_of` splits a minted id on the FIRST `_` — so NO underscore may
+ * appear anywhere in the tag (`co2_platform.X` would parse as tag `co2`). Deterministic; the era
+ * key witnesses the encoded form.
+ */
+export function qualifyReadProjectionType(domainKey: string, type: string): string {
+  return `${domainKey.replace(/_/g, "-")}${READ_PROJECTION_DELIMITER}${type}`;
+}
+
+/**
+ * The NAMESPACED (non-global) aggregate ids a module declares — the set whose type
+ * names qualify. Derived from the live handles (the `global` flag rides the handle),
+ * shared by `usd.ts` (compile) and `engine_entry.ts` (the dispatch context).
+ */
+export function namespacedAggregateIds(aggregates: readonly NamespaceClassifiable[]): Set<string> {
+  const out = new Set<string>();
+  for (const a of aggregates) if (isNamespacedAggregate(a)) out.add(a.id);
+  return out;
+}