@githolon/dsl 0.100.2 → 0.100.4

package/dart/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.62.1
+
+- Align the public Dart documentation with the one Flutter application entry point: identity comes from the
+  token passed to `NomosScope.home(application:, authToken:)`; application code no longer supplies a subject
+  or device-token callback.
+
 ## 0.62.0
 
 - Generated business clients expose one `birth(payload)` method. The bound session supplies its verified

package/dart/lib/src/home.dart

@@ -10,7 +10,7 @@ import 'package:crypto/crypto.dart';
 /// every peer and on the cloud. Use it directly as the `workspace`:
 ///
 /// ```dart
-/// NomosScope(workspace: homeNameOf('user:$firebaseUid'), ...)
+/// NomosScope.home(application: 'my-app', authToken: idToken, ...)
 /// ```
 ///
 /// Formula: `home-` + the first 40 hex chars of `sha256(utf8(subject))`.

package/dart/lib/src/webview_bridge.dart

@@ -1895,8 +1895,7 @@ class NomosBridge {
 
   /// Derive the device key's base64 PUBLIC half from its base64 SECRET seed, inside the LOCAL kernel
   /// (the secret never leaves the device). The recovery lanes use this when only the secret was
-  /// persisted (the device-key store keeps just the seed) — e.g. to mint a device-BOUND IdP token
-  /// (`authTokenForDevice(publicKey)`) for the keyless re-enroll lane.
+  /// persisted (the device-key store keeps just the seed), including low-level device-bound enrollment.
   Future<String> devicePublicOf(String secret) async =>
       (_asMap(await _call('devicePublicOf', {'secret': secret}))['public'] ?? '')
           .toString();

package/dart/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.62.0
+version: 0.62.1
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.100.2",
+  "version": "0.100.4",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/birth_meter.ts

@@ -57,12 +57,18 @@ import type { BirthRecipe } from "./births.js";
  *  a re-birth of the same name updates the SAME record, Lww). The kernel's `nomosBirthRecordGate`
  *  era key carries this prefix so the wasm arm reads it from LAW, never hardcodes it. */
 export const NOMOS_BIRTH_RECORD_PREFIX = "nomos-birth-record:";
+export const NOMOS_CHILD_LIFECYCLE_PREFIX = "nomos-child-lifecycle:";
 
 /** The birth record's deterministic aggregate instance id for a child workspace name. */
 export function birthRecordId(child: string): string {
   return NOMOS_BIRTH_RECORD_PREFIX + child;
 }
 
+/** The additive lifecycle record beside the immutable historical birth witness. */
+export function childLifecycleId(child: string): string {
+  return NOMOS_CHILD_LIFECYCLE_PREFIX + child;
+}
+
 /**
  * NomosBirthRecord — THE STRUCTURAL BIRTH RECORD (A1). One row per child this workspace has
  * birthed, written AUTOMATICALLY in the same intent as the birth effect (the `.births()` lane).
@@ -79,6 +85,21 @@ export const NomosBirthRecord = aggregate("NomosBirthRecord", {
   bornAt: t.string().merge(Lww),
 });
 
+/**
+ * NomosChildLifecycle — additive lifecycle for a child witnessed by NomosBirthRecord. It is deliberately
+ * a separate aggregate: a framework upgrade must never reinterpret the projection schema of historical
+ * birth rows. No lifecycle row means active; reclaimed is terminal.
+ */
+export const NomosChildLifecycle = aggregate("NomosChildLifecycle", {
+  child: t.string().merge(Lww),
+  principal: t.string().merge(Lww),
+  status: t.string().merge(Lww),
+  retiredBy: t.string().merge(Lww),
+  retiredAt: t.int().merge(Lww),
+  reclaimedBy: t.string().merge(Lww),
+  reclaimedAt: t.int().merge(Lww),
+});
+
 /** BirthPolicy — the workspace's birth-allowance singleton (id `birth-policy:workspace`), the
  *  `CloudPolicy` shape one level down: the default max live births per subject in THIS workspace. */
 export const BIRTH_POLICY_ID = "birth-policy:workspace";
@@ -111,6 +132,16 @@ export const birthRecordsByPrincipal = query("birthRecordsByPrincipal")
   .key("principal")
   .returns(NomosBirthRecord);
 
+/** Lifecycle rows for quota accounting; no row means the historical child remains active. */
+export const childLifecyclesByPrincipal = query("childLifecyclesByPrincipal")
+  .key("principal")
+  .returns(NomosChildLifecycle);
+
+/** Terminal lifecycle facts for the custody bailiff. */
+export const childLifecyclesByStatus = query("childLifecyclesByStatus")
+  .key("status")
+  .returns(NomosChildLifecycle);
+
 /** The workspace's birth-policy singleton (`scope: "workspace"`). */
 export const birthPolicy = query("birthPolicy").key("scope").returns(BirthPolicy);
 
@@ -119,13 +150,20 @@ export const birthGrantByPrincipal = query("birthGrantByPrincipal")
   .key("principal")
   .returns(BirthGrant);
 
-/** The three meter reads every `.births()` directive auto-declares (`nomosReadGate`). */
+/** The framework reads every `.births()` directive auto-declares (`nomosReadGate`). */
 export const BIRTH_METER_QUERIES: readonly QueryDecl[] = [
   birthRecordsByPrincipal,
+  childLifecyclesByPrincipal,
   birthPolicy,
   birthGrantByPrincipal,
 ];
 
+/** Every query a birth-capable law carries, including the custody bailiff's terminal-child index. */
+export const BIRTH_FRAMEWORK_QUERIES: readonly QueryDecl[] = [
+  ...BIRTH_METER_QUERIES,
+  childLifecyclesByStatus,
+];
+
 /**
  * THE DEFAULT BIRTH ALLOWANCE when a workspace carries neither a BirthPolicy singleton nor a grant
  * for the subject: a CONSERVATIVE floor for non-root workspaces (a home births a handful of estate
@@ -173,13 +211,14 @@ function sha256(text: string): string {
 }
 
 /**
- * CAPTURE the three meter reads on the write path (A2 — the plan side of the birth-quota gate; the
+ * CAPTURE the meter reads on the write path (A2 — the plan side of the birth-quota gate; the
  * exact `countQuotaReads` shape). Called by `executeDirectiveToIntent` for every `.births()` dispatch
  * that planned ≥1 birth — the values ride `captured_ports.reads`, CAS-re-derived + byte-compared at
  * the pre-apply position on every lane; the verdict is the synthesized invariant's.
  */
 export function captureBirthMeterReads(subject: string): void {
   __captureBirthMeterRead(birthRecordsByPrincipal, { principal: subject });
+  __captureBirthMeterRead(childLifecyclesByPrincipal, { principal: subject });
   __captureBirthMeterRead(birthGrantByPrincipal, { principal: subject });
   __captureBirthMeterRead(birthPolicy, { scope: "workspace" });
 }
@@ -231,7 +270,13 @@ export function birthQuotaVerdict(
     const hit = reads.find((r) => r.queryId === queryId && r.args[argKey] === argValue);
     return Array.isArray(hit?.result) ? (hit!.result as MeterRow[]) : [];
   };
-  const count = rowsOf(birthRecordsByPrincipal.id, "principal", subject).length;
+  // Terminal children no longer consume the parent's live-child allowance. Lifecycle is kept in an additive
+  // aggregate beside the historical birth witness, so an old row with no lifecycle remains active.
+  const born = rowsOf(birthRecordsByPrincipal.id, "principal", subject).length;
+  const terminal = rowsOf(childLifecyclesByPrincipal.id, "principal", subject)
+    .filter((r) => r.data?.status === "retired" || r.data?.status === "reclaimed")
+    .length;
+  const count = Math.max(0, born - terminal);
   // ALLOWANCE: the LATEST BirthGrant (max grantedAt) wins; else the BirthPolicy singleton; else the floor.
   let allowance: number | undefined;
   let latestGrantedAt = -Infinity;
@@ -295,6 +340,7 @@ export function synthesizeBirthQuotaInvariants(directive: {
 /** The meter aggregates every `.births()`-declaring domain auto-ensures (the RelationTuple courtesy). */
 export const BIRTH_METER_AGGREGATES: readonly AggregateHandle[] = [
   NomosBirthRecord,
+  NomosChildLifecycle,
   BirthPolicy,
   BirthGrant,
 ] as unknown as readonly AggregateHandle[];

package/src/birth_meter_ensure.ts

@@ -26,9 +26,17 @@ import { directive } from "./directive.js";
 import type { Directive } from "./directive.js";
 import {
   NomosBirthRecord,
+  NomosChildLifecycle,
   BirthPolicy,
   BirthGrant,
 } from "./birth_meter.js";
+import {
+  reclaimChild,
+  reclaimChildRequiresRetired,
+  retireChild,
+  retireChildRequiresBirth,
+  retireChildNotReclaimed,
+} from "./framework/birth_meter.js";
 
 /**
  * The sanctioning declaration — an `ensures(NomosBirthRecord)` directive whose plan emits ZERO ops.
@@ -59,9 +67,23 @@ export function withBirthMeterExports<M extends Record<string, unknown>>(mod: M)
   );
   if (!declaresBirth) return mod;
   const out: Record<string, unknown> = { ...mod };
-  if (!("nomosBirthRecordEnsure" in out)) out["nomosBirthRecordEnsure"] = nomosBirthRecordEnsure;
-  if (!("NomosBirthRecord" in out)) out["NomosBirthRecord"] = NomosBirthRecord;
-  if (!("BirthPolicy" in out)) out["BirthPolicy"] = BirthPolicy;
-  if (!("BirthGrant" in out)) out["BirthGrant"] = BirthGrant;
+  // Business birth hides framework maintenance declarations from the generated application facade while
+  // retaining them in certified law for the operator's structural offer discovery. A non-business
+  // `.births()` law keeps its existing explicit generated surface.
+  const businessInternal = Object.values(mod).some(
+    (v) => v !== null && typeof v === "object" && (v as { businessBirth?: unknown }).businessBirth !== undefined,
+  );
+  const presented = <T extends object>(v: T): T =>
+    businessInternal ? ({ ...v, businessBirthInternal: true } as T) : v;
+  if (!("nomosBirthRecordEnsure" in out)) out["nomosBirthRecordEnsure"] = presented(nomosBirthRecordEnsure);
+  if (!("NomosBirthRecord" in out)) out["NomosBirthRecord"] = presented(NomosBirthRecord);
+  if (!("NomosChildLifecycle" in out)) out["NomosChildLifecycle"] = presented(NomosChildLifecycle);
+  if (!("BirthPolicy" in out)) out["BirthPolicy"] = presented(BirthPolicy);
+  if (!("BirthGrant" in out)) out["BirthGrant"] = presented(BirthGrant);
+  if (!("retireChild" in out)) out["retireChild"] = presented(retireChild);
+  if (!("reclaimChild" in out)) out["reclaimChild"] = presented(reclaimChild);
+  if (!("reclaimChildRequiresRetired" in out)) out["reclaimChildRequiresRetired"] = reclaimChildRequiresRetired;
+  if (!("retireChildRequiresBirth" in out)) out["retireChildRequiresBirth"] = retireChildRequiresBirth;
+  if (!("retireChildNotReclaimed" in out)) out["retireChildNotReclaimed"] = retireChildNotReclaimed;
   return out as M;
 }

package/src/build_package.ts

@@ -56,7 +56,7 @@ import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js"
 import { synthesizePreconditionInvariants } from "./precondition.js";
 import {
   BIRTH_METER_AGGREGATES,
-  BIRTH_METER_QUERIES,
+  BIRTH_FRAMEWORK_QUERIES,
   synthesizeBirthQuotaInvariants,
 } from "./birth_meter.js";
 import { withBirthMeterExports } from "./birth_meter_ensure.js";
@@ -81,6 +81,11 @@ import { discoverUnsanctionedEnsures, sanctioningEnsureDirective } from "./secon
 import { assertIdOfLint } from "./idof_lint.js";
 import { assertSurfacedResolvers } from "./surfaced_lint.js";
 import { expandBusinessBirthExports } from "./business_birth.js";
+import {
+  reclaimChildRequiresRetired,
+  retireChildNotReclaimed,
+  retireChildRequiresBirth,
+} from "./framework/birth_meter.js";
 
 // ─────────────────────────────────────────────────────────────────────────────────
 // composeDomainModule — the named-keys `module(...)`
@@ -309,6 +314,12 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   const maxes = [...(spec.maxes ?? [])];
   const workspaceTypes = [...(spec.workspaceTypes ?? [])];
   const workspaceInvariants = [...(spec.workspaceInvariants ?? [])];
+  if (declaresBirth) {
+    const haveInvariant = new Set(workspaceInvariants.map((w) => w.id));
+    for (const lifecycle of [reclaimChildRequiresRetired, retireChildNotReclaimed, retireChildRequiresBirth]) {
+      if (!haveInvariant.has(lifecycle.id)) workspaceInvariants.push(lifecycle);
+    }
+  }
   // DESUGAR the write-path precondition primitives (`.requiresExisting`/`.creates(Agg,idFn)`/`.where`):
   // each directive's descriptors synthesize workspace invariants (LANE B) appended to the SAME list a
   // hand-authored `workspaceInvariant(...)` occupies — so downstream treats them identically. Era-safe:
@@ -321,7 +332,7 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   // The meter's declared queries route like any exported query (read manifest + captured-read re-derive).
   if (declaresBirth) {
     const haveQuery = new Set(queries.map((q) => q.id));
-    for (const q of BIRTH_METER_QUERIES) {
+    for (const q of BIRTH_FRAMEWORK_QUERIES) {
       if (!haveQuery.has(q.id)) queries.push(q);
     }
     // The inheritance read (`.reads("authProvider")` on birthHome) routes like any declared query.

package/src/business_birth.ts

@@ -15,10 +15,13 @@ import { AuthProvider, authProvider, setAuthProvider } from "./framework/auth_pr
 import {
   BirthGrant,
   BirthPolicy,
+  NomosChildLifecycle,
   NomosBirthRecord,
   birthGrantByPrincipal,
   birthPolicy,
   birthRecordsByPrincipal,
+  childLifecyclesByPrincipal,
+  childLifecyclesByStatus,
 } from "./birth_meter.js";
 import { nomosBirthRecordEnsure } from "./birth_meter_ensure.js";
 import { GENESIS_WARRANT_ID, GenesisWarrant, seedGenesis } from "./framework/genesis.js";
@@ -238,10 +241,13 @@ function lowerOne(decl: BusinessBirthDecl, domain: string): Record<string, unkno
     // Exact export keys prevent the generic `.births()` auto-compose seam from inserting a second,
     // unmarked copy. The values are still the canonical framework declarations.
     NomosBirthRecord: internalSurface(NomosBirthRecord),
+    NomosChildLifecycle: internalSurface(NomosChildLifecycle),
     BirthPolicy: internalSurface(BirthPolicy),
     BirthGrant: internalSurface(BirthGrant),
     nomosBirthRecordEnsure: internalDirective(nomosBirthRecordEnsure),
     __nomos_birthRecordsByPrincipal: internalSurface(birthRecordsByPrincipal),
+    __nomos_childLifecyclesByPrincipal: internalSurface(childLifecyclesByPrincipal),
+    __nomos_childLifecyclesByStatus: internalSurface(childLifecyclesByStatus),
     __nomos_birthPolicy: internalSurface(birthPolicy),
     __nomos_birthGrantByPrincipal: internalSurface(birthGrantByPrincipal),
     __nomos_parentAttestedBirth: businessParentAttestedBirth,

package/src/codegen_openapi.ts

@@ -50,11 +50,18 @@ export interface OpenApiDoc {
   openapi: "3.1.0";
   info: Record<string, unknown>;
   paths: Record<string, Record<string, unknown>>;
+  /**
+   * Law-derived routes needed by Nomos itself (device seating, provenance, recovery, ...).
+   * The host consumes this only on its internal describe path and strips it from public OpenAPI.
+   */
+  "x-nomos-framework-routes"?: { paths: Record<string, Record<string, unknown>> };
 }
 
 export interface OpenApiFragmentOptions {
   /** The content hash of the installed law (the spec's version + ingest cache key). */
   lawHash?: string;
+  /** Include the private framework router manifest used by the Nomos host. Public codegen omits it. */
+  includeFrameworkRoutes?: boolean;
 }
 
 /** Lower a directive's payload zod to JSON Schema; a non-representable schema falls back to a
@@ -95,22 +102,10 @@ function domainKey(module: DomainModule): string {
  * the merge namespaces any cross-domain collision. The offer/query distinction rides on the HTTP
  * method (POST/GET) AND the authoritative `x-nomos.kind` — the host reads the latter, never the name.
  */
-export function generateOpenApiFragment(
+function generateOpenApiSurface(
   module: DomainModule,
   opts: OpenApiFragmentOptions = {},
 ): OpenApiDoc {
-  module = {
-    ...module,
-    aggregates: module.aggregates.filter(
-      (a) => (a as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
-    ),
-    directives: module.directives.filter(
-      (d) => (d as { businessBirthInternal?: unknown }).businessBirthInternal !== true,
-    ),
-    ...(module.queries === undefined
-      ? {}
-      : { queries: module.queries.filter((q) => (q as { businessBirthInternal?: unknown }).businessBirthInternal !== true) }),
-  };
   const domain = domainKey(module);
   const paths: Record<string, Record<string, unknown>> = {};
 
@@ -123,7 +118,6 @@ export function generateOpenApiFragment(
 
   // OFFERABLE INTENTS → POST offers. The payload JSON Schema is the intent's own zod, lowered.
   for (const dir of module.directives as AnyDirective[]) {
-    if ((dir as { businessBirthInternal?: unknown }).businessBirthInternal === true) continue;
     const businessBirth = (dir as {
       businessBirth?: { aggregateId: string; publicPayloadSchema: unknown };
     }).businessBirth;
@@ -247,11 +241,79 @@ export function generateOpenApiFragment(
   };
 }
 
+/**
+ * Generate the developer-facing OpenAPI plus, only when requested by the runtime, a separate
+ * framework routing manifest. The split is deliberate: filtering framework declarations out of
+ * `paths` is presentation; it must never make Nomos's own law declarations unroutable.
+ */
+export function generateOpenApiFragment(
+  module: DomainModule,
+  opts: OpenApiFragmentOptions = {},
+): OpenApiDoc {
+  const isInternal = (value: unknown) =>
+    !!value && typeof value === "object"
+      && (value as { businessBirthInternal?: unknown }).businessBirthInternal === true;
+  const publicModule: DomainModule = {
+    ...module,
+    aggregates: module.aggregates.filter((a) => !isInternal(a)),
+    directives: module.directives.filter((d) => !isInternal(d)),
+    ...(module.queries === undefined ? {} : { queries: module.queries.filter((q) => !isInternal(q)) }),
+  };
+  const publicDoc = generateOpenApiSurface(publicModule, opts);
+  if (opts.includeFrameworkRoutes !== true) return publicDoc;
+
+  const frameworkModule: DomainModule = {
+    ...module,
+    aggregates: module.aggregates.filter(isInternal),
+    directives: module.directives.filter(isInternal),
+    ...(module.queries === undefined ? {} : { queries: module.queries.filter(isInternal) }),
+    // Framework routing is for declared internal offers/queries. Business maintained reads remain
+    // on the public module; do not duplicate them into the private table.
+    counts: [],
+    sums: [],
+    mins: [],
+    maxes: [],
+    spatials: [],
+  };
+  const frameworkDoc = generateOpenApiSurface(frameworkModule, opts);
+  if (Object.keys(frameworkDoc.paths).length === 0) return publicDoc;
+  return {
+    ...publicDoc,
+    "x-nomos-framework-routes": { paths: frameworkDoc.paths },
+  };
+}
+
 /** Stable JSON of an operation, to detect a genuine duplicate vs a real collision in the merge. */
 function operationKey(op: unknown): string {
   return JSON.stringify(op);
 }
 
+function mergePathsInto(
+  paths: Record<string, Record<string, unknown>>,
+  incoming: Record<string, Record<string, unknown>>,
+): void {
+  for (const [path, methods] of Object.entries(incoming)) {
+    for (const [method, op] of Object.entries(methods)) {
+      const existing = paths[path]?.[method];
+      if (existing === undefined) {
+        (paths[path] ??= {})[method] = op;
+      } else if (operationKey(existing) === operationKey(op)) {
+        // identical (a framework operation shared by many domains) — keep the one entry.
+      } else {
+        // genuine collision: two domains, same path+method, different operations. Namespace BOTH
+        // under their domain so neither wins silently.
+        const domOf = (o: unknown): string =>
+          String((o as { "x-nomos"?: { domain?: string } })?.["x-nomos"]?.domain ?? "domain");
+        const bucket = paths[path]!;
+        (paths[`/${domOf(existing)}${path}`] ??= {})[method] = existing;
+        (paths[`/${domOf(op)}${path}`] ??= {})[method] = op;
+        delete bucket[method];
+        if (Object.keys(bucket).length === 0) delete paths[path];
+      }
+    }
+  }
+}
+
 /**
  * mergeOpenApiFragments — the WORKSPACE spec = the union of its installed domains' fragments. The
  * runtime step (driven by `currentLaw`), kept here as a pure, law-blind function:
@@ -266,27 +328,10 @@ export function mergeOpenApiFragments(
   opts: { title?: string; lawHash?: string } = {},
 ): OpenApiDoc {
   const paths: Record<string, Record<string, unknown>> = {};
+  const frameworkPaths: Record<string, Record<string, unknown>> = {};
   for (const frag of fragments) {
-    for (const [path, methods] of Object.entries(frag.paths)) {
-      for (const [method, op] of Object.entries(methods)) {
-        const existing = paths[path]?.[method];
-        if (existing === undefined) {
-          (paths[path] ??= {})[method] = op;
-        } else if (operationKey(existing) === operationKey(op)) {
-          // identical (a framework operation shared by many domains) — keep the one entry.
-        } else {
-          // genuine collision: two domains, same path+method, different operations. Namespace BOTH
-          // under their domain so neither wins silently.
-          const domOf = (o: unknown): string =>
-            String((o as { "x-nomos"?: { domain?: string } })?.["x-nomos"]?.domain ?? "domain");
-          const bucket = paths[path]!;
-          (paths[`/${domOf(existing)}${path}`] ??= {})[method] = existing;
-          (paths[`/${domOf(op)}${path}`] ??= {})[method] = op;
-          delete bucket[method];
-          if (Object.keys(bucket).length === 0) delete paths[path];
-        }
-      }
-    }
+    mergePathsInto(paths, frag.paths);
+    mergePathsInto(frameworkPaths, frag["x-nomos-framework-routes"]?.paths ?? {});
   }
   return {
     openapi: "3.1.0",
@@ -296,5 +341,8 @@ export function mergeOpenApiFragments(
       ...(opts.lawHash ? { "x-nomos-law-hash": opts.lawHash } : {}),
     },
     paths,
+    ...(Object.keys(frameworkPaths).length > 0
+      ? { "x-nomos-framework-routes": { paths: frameworkPaths } }
+      : {}),
   };
 }

package/src/compile_package_main.ts

@@ -91,7 +91,7 @@ import {
   type Mod,
 } from "./build_package.js";
 import { synthesizePreconditionInvariants } from "./precondition.js";
-import { BIRTH_METER_QUERIES, synthesizeBirthQuotaInvariants } from "./birth_meter.js";
+import { BIRTH_FRAMEWORK_QUERIES, synthesizeBirthQuotaInvariants } from "./birth_meter.js";
 import { withBirthMeterExports } from "./birth_meter_ensure.js";
 import { expandBusinessBirthExports } from "./business_birth.js";
 import { expandRoleExports, rolesOf } from "./role.js";
@@ -1772,7 +1772,7 @@ async function main(): Promise<void> {
     // 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) {
+      for (const q of BIRTH_FRAMEWORK_QUERIES) {
         if (!haveQuery.has(q.id)) queries.push(q);
       }
     }

package/src/directive.ts

@@ -958,8 +958,8 @@ 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.
-      // METERED BIRTH (slice A): `.births()` ALSO auto-declares the three birth-meter captured reads
-      // (`birthRecordsByPrincipal`/`birthGrantByPrincipal`/`birthPolicy` — the #58 lane), so the
+      // METERED BIRTH (slice A): `.births()` ALSO auto-declares the birth-meter reads
+      // (`birthRecordsByPrincipal`/`childLifecyclesByPrincipal`/`birthGrantByPrincipal`/`birthPolicy`), 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).

package/src/engine_entry.ts

@@ -931,11 +931,9 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
    * THE SELF-DESCRIBE VERB (G1) — the lump's OWN OpenAPI, derived from the SAME modules it
    * dispatches. The kernel runs this over the FOLDED law (the lump IS `nomos:executable:
    * javascriptHex` in the package USDA in custody), so the workspace's API surface is a pure,
-   * deterministic function of installed law — NOT a host-staged blob. It reproduces, byte for
-   * byte, the `<name>.openapi.json` the compiler wrote: per domain (declaration order) build the
-   * openapi-relevant DomainModule (directives + aggregates from the live exports; queries/counts/
-   * sums/mins/maxes/spatials/workspaceInvariants from `config.openapiDecls`), `generateOpenApi
-   * Fragment`, then `mergeOpenApiFragments` — the EXACT calls compile_package_main makes.
+   * deterministic function of installed law — NOT a host-staged blob. Its public `paths` reproduce
+   * the `<name>.openapi.json` the compiler wrote; describe also carries a private, law-derived
+   * framework routing manifest which the host consumes internally and never publishes.
    * `opts.lawHash`/`opts.title` are injected by the kernel at describe-time (the version stamp +
    * package title), matching the compiler's `domainHash`/`"<name> (nomos package)"`.
    */
@@ -969,7 +967,10 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
           ? { workspaceInvariants: [...decls.workspaceInvariants] }
           : {}),
       } as unknown as DomainModule;
-      fragments.push(generateOpenApiFragment(module, lawHash !== undefined ? { lawHash } : {}));
+      fragments.push(generateOpenApiFragment(module, {
+        ...(lawHash !== undefined ? { lawHash } : {}),
+        includeFrameworkRoutes: true,
+      }));
     }
     const title = opts?.title ?? config.packageTitle;
     return mergeOpenApiFragments(fragments, {

package/src/framework/birth_meter.ts

@@ -27,23 +27,33 @@ import { z } from "zod";
 import { instance } from "../aggregate.js";
 import { directive } from "../directive.js";
 import { set, type PlannedOp } from "../ops.js";
+import { refAs, workspaceInvariant } from "./workspace_invariant.js";
 import {
   BirthPolicy,
   BirthGrant,
+  NomosChildLifecycle,
+  NomosBirthRecord,
   BIRTH_POLICY_ID,
+  birthRecordId,
+  childLifecycleId,
   birthGrantId,
 } from "../birth_meter.js";
 
 // Re-export the whole meter core so `@githolon/dsl` framework consumers get one import site.
 export {
   NomosBirthRecord,
+  NomosChildLifecycle,
   BirthPolicy,
   BirthGrant,
   BIRTH_POLICY_ID,
   NOMOS_BIRTH_RECORD_PREFIX,
+  NOMOS_CHILD_LIFECYCLE_PREFIX,
   birthRecordId,
+  childLifecycleId,
   birthGrantId,
   birthRecordsByPrincipal,
+  childLifecyclesByPrincipal,
+  childLifecyclesByStatus,
   birthPolicy,
   birthGrantByPrincipal,
   DEFAULT_MAX_BIRTHS_PER_PRINCIPAL,
@@ -51,6 +61,93 @@ export {
   birthQuotaInvariantId,
 } from "../birth_meter.js";
 
+/**
+ * retireChild / reclaimChild are the lifecycle of the SAME child born by `.births()`. They are operator
+ * maintenance beneath the application API, not alternative creation lanes. The durable parent-side
+ * NomosBirthRecord remains the immutable birth witness; an additive NomosChildLifecycle is the authority
+ * for withdrawal/disposal, so a framework upgrade never changes the schema of historical birth rows.
+ */
+export const retireChild = directive("retireChild")
+  .ensures(NomosChildLifecycle)
+  .payload(z.object({
+    child: z.string().min(1),
+    principal: z.string().min(1),
+    retiredBy: z.string().min(1),
+    retiredAt: z.number().int().nonnegative(),
+  }))
+  .plan((p) => {
+    const rec = instance(NomosChildLifecycle, childLifecycleId(p.child));
+    return [
+      set(rec, "child", p.child),
+      set(rec, "principal", p.principal),
+      set(rec, "status", "retired"),
+      set(rec, "retiredBy", p.retiredBy),
+      set(rec, "retiredAt", p.retiredAt),
+    ];
+  });
+
+export const reclaimChild = directive("reclaimChild")
+  .ensures(NomosChildLifecycle)
+  .payload(z.object({
+    child: z.string().min(1),
+    reclaimedBy: z.string().min(1),
+    reclaimedAt: z.number().int().nonnegative(),
+  }))
+  .plan((p) => {
+    const rec = instance(NomosChildLifecycle, childLifecycleId(p.child));
+    return [
+      set(rec, "status", "reclaimed"),
+      set(rec, "reclaimedBy", p.reclaimedBy),
+      set(rec, "reclaimedAt", p.reclaimedAt),
+    ];
+  });
+
+/** Reclaim is two-phase; a child must first be explicitly withdrawn. */
+export const reclaimChildRequiresRetired = workspaceInvariant("ReclaimChildRequiresRetired")
+  .on("reclaimChild")
+  .reads((ctx) => [
+    refAs("record", "NomosChildLifecycle", "pre:" + childLifecycleId(String(ctx.intent.child ?? ""))),
+  ])
+  .assert(({ record }, ctx) =>
+    (record as { status?: string; principal?: string } | undefined)?.status === "retired"
+      && sameLifecyclePrincipal((record as { principal?: string }).principal, ctx?.principal)
+      ? { accept: true }
+      : { reject: "reclaim-child-requires-retired" },
+  );
+
+/** Reclaimed is permanent: retirement cannot move a child back out of the terminal state. */
+export const retireChildNotReclaimed = workspaceInvariant("RetireChildNotReclaimed")
+  .on("retireChild")
+  .reads((ctx) => [
+    refAs("record", "NomosChildLifecycle", "pre:" + childLifecycleId(String(ctx.intent.child ?? ""))),
+  ])
+  .assert(({ record }) =>
+    (record as { status?: string } | undefined)?.status === "reclaimed"
+      ? { reject: "reclaimed-child-is-terminal" }
+      : { accept: true },
+  );
+
+/** A lifecycle cannot mint authority for arbitrary custody: retirement must name its exact birth witness. */
+export const retireChildRequiresBirth = workspaceInvariant("RetireChildRequiresBirth")
+  .on("retireChild")
+  .reads((ctx) => [
+    refAs("birth", "NomosBirthRecord", "pre:" + birthRecordId(String(ctx.intent.child ?? ""))),
+  ])
+  .assert(({ birth }, ctx) => {
+    const record = birth as { child?: string; principal?: string } | undefined;
+    const intent = ctx?.intent as { child?: string; principal?: string } | undefined;
+    return record?.child === intent?.child
+      && record?.principal === intent?.principal
+      && sameLifecyclePrincipal(record?.principal, ctx?.principal)
+      ? { accept: true }
+      : { reject: "retire-child-requires-exact-birth-record" };
+  });
+
+function sameLifecyclePrincipal(recorded: string | undefined, author: string | undefined): boolean {
+  const normalize = (s: string | undefined): string => s?.startsWith("user:") ? s.slice(5) : (s ?? "");
+  return normalize(recorded) !== "" && normalize(recorded) === normalize(author);
+}
+
 /** 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);

package/src/framework/framework_aggregates.ts

@@ -35,6 +35,7 @@ import type { QueryDecl } from "../query.js";
 import { nomosSourceFrontierEnsure } from "../attested.js";
 import * as birthMeter from "../birth_meter.js";
 import * as birthMeterEnsure from "../birth_meter_ensure.js";
+import * as birthMeterFramework from "./birth_meter.js";
 import * as disclosure from "./disclosure.js";
 import * as domainLifecycle from "./domain_lifecycle.js";
 import * as encryptionIdentity from "./encryption_identity.js";
@@ -56,6 +57,7 @@ const FRAMEWORK_NAMESPACES: ReadonlyArray<Record<string, unknown>> = [
   // read models/accessors) once PER domain — the exact ambiguous_export co2 hit on its barrel.
   birthMeter,
   birthMeterEnsure,
+  birthMeterFramework,
   disclosure,
   domainLifecycle,
   encryptionIdentity,

package/src/index.ts

@@ -456,13 +456,18 @@ export {
 // tenant composes in to set/override allowances, plus the constants/predicates tests and tools read.
 export {
   NomosBirthRecord,
+  NomosChildLifecycle,
   BirthPolicy,
   BirthGrant,
   BIRTH_POLICY_ID,
   NOMOS_BIRTH_RECORD_PREFIX,
+  NOMOS_CHILD_LIFECYCLE_PREFIX,
   birthRecordId,
+  childLifecycleId,
   birthGrantId,
   birthRecordsByPrincipal,
+  childLifecyclesByPrincipal,
+  childLifecyclesByStatus,
   birthPolicy,
   birthGrantByPrincipal,
   DEFAULT_MAX_BIRTHS_PER_PRINCIPAL,
@@ -471,6 +476,11 @@ export {
   setBirthPolicy,
   seedBirthPolicy,
   grantBirthAllowance,
+  retireChild,
+  reclaimChild,
+  reclaimChildRequiresRetired,
+  retireChildRequiresBirth,
+  retireChildNotReclaimed,
 } 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.

package/src/read_projection_namespace.ts

@@ -81,6 +81,7 @@ export const GLOBAL_READ_PROJECTION_AGGREGATE_IDS: ReadonlySet<string> = new Set
   // 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",
+  "NomosChildLifecycle",
   "BirthPolicy",
   "BirthGrant",
   // home holons

package/src/wire_encode.ts

@@ -306,7 +306,7 @@ export function executeDirectiveToIntent<P>(
   //   A1 THE AUTO-RECORD: append the `NomosBirthRecord` field ops (deterministic id per child; Lww upsert)
   //      to the SAME intent that carries the birth effect. The kernel's `nomosBirthRecordGate` era arm
   //      refuses a new-era birth whose intent carries no record — this is what satisfies it.
-  //   A2 THE AUTO-CAPTURE: capture the three meter reads (records-by-subject + grant + policy — the #58
+  //   A2 THE AUTO-CAPTURE: capture the meter reads (births + terminal lifecycle + grant + policy — the #58
   //      lane `.births()` auto-declares) so the synthesized birth-quota invariant judges over COMMITTED,
   //      CAS-re-derived pre-apply state on every lane.
   // A `.births()` dispatch that planned NO birth (e.g. birthChild without a genesis) appends/captures