@githolon/dsl 0.17.0 → 0.18.0

package/src/framework/workspaces.ts

@@ -67,6 +67,7 @@ export const GOVERNANCE_REVISION = "2026-06-12-capability-bindings"; // hash-bea
 import { z } from "zod";
 import { aggregate, instance } from "../aggregate.js";
 import { create, ensure } from "../authoring.js";
+import { birth } from "../births.js";
 import { directive } from "../directive.js";
 import { Lww } from "../drivers.js";
 import { t } from "../fields.js";
@@ -262,6 +263,18 @@ export const CloudWorkspace = aggregate("CloudWorkspace", {
    * the genesis directives HERE is law naming law (legitimate); the prohibition binds only the host.
    */
   genesisChain: t.json().merge(Lww).optional(),
+  /**
+   * THE LINEAGE-AUTHORIZATION BINDING (proof-friendly — architecture/sovereign_adapter.md "birth is a kernel
+   * offer-effect"). The child's genesis SELF-ATTESTS who authorized it: a JSON commitment
+   * `{parent, principal, authorizedAt}` — the law-available lineage anchor — that the child's OWN chain
+   * carries, so a verifier of the child alone sees its claimed parentage, cross-checkable against the
+   * parent's chain (which holds the child's CloudWorkspace + the gated `birthChild` that minted it). It is
+   * the clean public-input shape a future recursive-proof circuit (Nova / zkWASM) would expose; the
+   * kernel-structural commitments (the parent chain head + the `birthChild` intent hash + the law hash) join
+   * it when the KERNEL produces the genesis (B's later slice — until then those ride as `""`). `t.string`
+   * (JSON), never `t.json`: it rides verbatim as a scalar (the kernel `Value` has no JSON variant — the same
+   * reasoning as the auth keys). Absent on root (the base of the world tree, born under nothing). */
+  bornUnder: t.string().merge(Lww).optional(),
 });
 
 // AdminGrant / CreationGrant aggregates: DELETED (full-native Zanzibar). Admin/creation authority is
@@ -431,17 +444,63 @@ function planBirthRecord(
 export function buildGenesisChain(p: {
   name: string;
   principal: string;
+  parent: string;
   tier: (typeof WORKSPACE_TIERS)[number];
   foundingAdminHash: string;
   bornAt: string;
   requestedAt: number;
+  /** THE ORDER DECLARES THE LAW (G3 — no inheritance, no `_parentLawHash`): the content hashes of the
+   *  bootstrap framework controller + the governance law package the child installs IN-CHAIN as its first
+   *  intents. Frozen facts on the birth order (the parent captured them at `birthChild` time). When present,
+   *  the recipe PREPENDS `bootstrap/installDomain(framework)` + `nomos/installDomain(law)` — the two-layer
+   *  install the genesis bootstrap does — so the child installs ITS OWN law as intent 0 and self-validates
+   *  from there. Absent ⇒ the recipe resolves an already-installed law by shape (pre-G3 / test lanes). */
+  frameworkHash?: string;
+  lawHash?: string;
+  /**
+   * THE WARRANT-FLIP (VA-1, architecture/identity_keys.md). When TRUE — set iff the genesis recipe
+   * declares an AuthProvider (an IdP vouches for this subtree's principals) — `seedGenesis` records a
+   * REAL `workspaceId` (the workspace name as the unique self-id), so the chain is born WARRANTED:
+   * `verify_captured_principal` enforces signed authorship on all lanes (author / receive / verify_chain).
+   * FALSE (the default, the legacy lane) keeps `workspaceId: ""` so the workspace stays unwarranted
+   * (host-stamped authorship, like root) — pre-VA / non-AuthProvider births replay byte-identically.
+   * NO flag-day: the era is per-workspace, decided at genesis by whether the recipe carries an AuthProvider.
+   */
+  requiresWarrant?: boolean;
 }): 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
+  // the recipe (the kernel resolves them by hash from its own custody when it folds the birth, never the
+  // host). `domainHash` names the law; `domainPackageB64` stays empty here (the kernel supplies bytes-by-hash
+  // for the in-chain install). Two layers, matching the genesis bootstrap: bootstrap controller, then law.
+  const installSteps =
+    p.frameworkHash && p.lawHash
+      ? [
+          { domain: "bootstrap", directiveId: "installDomain", actor: founder, payload: { domainHash: p.frameworkHash }, domainHash: p.frameworkHash, domainPackageB64: "" },
+          { domain: "nomos", directiveId: "installDomain", actor: founder, payload: { domainHash: p.lawHash }, domainHash: p.lawHash, domainPackageB64: "" },
+        ]
+      : [];
+  // THE LINEAGE-AUTHORIZATION BINDING (proof-friendly): the child's birthCloud records who authorized it, so
+  // the child's OWN chain self-attests its parentage — cross-checkable against the parent's chain. The
+  // law-available anchor now; the kernel-structural commitments (parent chain head + birthChild intent hash
+  // + law hash) join as `""` placeholders until the kernel produces the genesis (B's later slice). The
+  // ordering of keys is fixed so the commitment is a stable, content-addressed shape (proof public inputs).
+  const bornUnder = JSON.stringify({
+    parent: p.parent,
+    principal: p.principal,
+    authorizedAt: p.requestedAt,
+    lawHash: "",
+    authorizationHash: "",
+    parentHead: "",
+  });
   return JSON.stringify([
-    { domain: "workspaces", directiveId: "seedGenesis", actor: founder, payload: { principal: founder, workspaceId: "", bornAt: p.bornAt } },
+    ...installSteps,
+    // THE WARRANT-FLIP (VA-1): a REAL self-id iff the recipe declares an AuthProvider (born warranted ⇒
+    // signed authorship enforced on every lane); "" keeps the legacy host-stamped lane (byte-identical).
+    { domain: "workspaces", directiveId: "seedGenesis", actor: founder, payload: { principal: founder, workspaceId: p.requiresWarrant ? p.name : "", bornAt: p.bornAt } },
     { domain: "workspaces", directiveId: "grantAdmin", actor: founder, payload: { keyHash: p.foundingAdminHash, label: `founding admin (born for ${p.principal})`, grantedBy: p.principal, grantedAt: p.requestedAt } },
     // No `role` — it was a vestigial node-class label (collapsed with `kind`); birthCloud ignores it now.
-    { domain: "workspaces", directiveId: "birthCloud", actor: "", payload: { principal: p.principal, name: p.name, tier: p.tier, bornAt: p.requestedAt } },
+    { domain: "workspaces", directiveId: "birthCloud", actor: "", payload: { principal: p.principal, name: p.name, tier: p.tier, bornAt: p.requestedAt, bornUnder } },
   ]);
 }
 
@@ -498,10 +557,14 @@ export const birthCloud = directive("birthCloud")
       role: z.enum(WORKSPACE_ROLES).optional(),
       tier: z.enum(WORKSPACE_TIERS).default("edge"),
       bornAt: epochMs,
+      /** THE LINEAGE-AUTHORIZATION BINDING (proof-friendly): the JSON commitment to who authorized this
+       *  birth, recorded onto the child's self-record so its OWN chain self-attests its parentage. Absent on
+       *  root (born under nothing). Authored by {@link buildGenesisChain} for a child birth. */
+      bornUnder: z.string().optional(),
     }),
   )
   .plan((p) => {
-    create(CloudWorkspace)
+    const rec = create(CloudWorkspace)
       .set("name", p.name)
       .set("parent", "") // the root of the world tree
       .set("principal", p.principal)
@@ -511,6 +574,8 @@ export const birthCloud = directive("birthCloud")
       .set("createdBy", p.principal)
       .set("createdAt", p.bornAt)
       .set("provisionedAt", p.bornAt);
+    // The child's chain self-attests its lineage authorization (the proof-friendly binding); root omits it.
+    if (p.bornUnder) rec.set("bornUnder", p.bornUnder);
     // The self-identity singleton at the CONSTANT id (ungated — birthCloud is not admin-mutating), so the
     // gate's self-record exists before any admin write. ensure() = deterministic-id sibling birth. `name` is
     // the born marker; `role` is no longer written (vestigial node-class — see WorkspaceSelf).
@@ -609,18 +674,18 @@ export const retireWorkspace = directive("retireWorkspace")
 /**
  * reclaimWorkspace — THE LAWFUL CUSTODY DISCARD. Where {@link retireWorkspace}
  * withdraws the law (a status, the bytes untouched), reclaim is the law AUTHORIZING
- * the host to drop the custody: the worker bailiff, on seeing THIS fact folded,
- * `ARTIFACTS.delete`s the workspace's git ledger and `deleteAll`s its DO storage.
+ * the bailiff to drop the custody: on seeing THIS fact folded, the bailiff drops the
+ * workspace's git ledger + DO storage (operator-gated soft-mark while pre-release).
  *
- * THE TWO-PHASE RULE (enforced worker-side, since a plan cannot read prior state):
- * only a `retired` workspace may be reclaimed — retire withdraws, reclaim discards.
+ * THE TWO-PHASE RULE is LAW (see {@link reclaimRequiresRetired}): only a `retired`
+ * workspace may be reclaimed — the invariant reads the pre-apply status at the one gate.
  *
- * THE FIXED POINT: this is authored for CHILDREN only. The worker refuses to reclaim
- * ROOT — the genesis workspace is the seat of the law that authorizes reclaim, so the
- * law can reap everything it governs EXCEPT itself. Dropping root is the one act Nomos
- * cannot perform in-law; the custodian does it through Cloudflare directly. The
- * custody-reclaimed fact (this status flip) is append-only and outlives the bytes:
- * Nomos never erases the FACT that a workspace existed and was reclaimed.
+ * THE FIXED POINT: this is authored for CHILDREN only. The law refuses to reclaim ROOT —
+ * the genesis workspace is the seat of the law that authorizes reclaim, so the law can
+ * reap everything it governs EXCEPT itself. Dropping root is the one act Nomos cannot
+ * perform in-law; the custodian does it through Cloudflare directly. The custody-reclaimed
+ * fact (this status flip) is append-only and outlives the bytes: Nomos never erases the
+ * FACT that a workspace existed and was reclaimed.
  */
 export const reclaimWorkspace = directive("reclaimWorkspace")
   .mutates(CloudWorkspace)
@@ -684,6 +749,17 @@ export const birthChild = directive("birthChild")
         /** GENESIS birth time as an ISO string (caller-stamped — the timestamp doctrine). Arms the warrant
          *  in the law-authored genesis chain; required for (and only used by) a genesis birth. */
         bornAt: z.string().optional(),
+        /** THE ORDER DECLARES THE LAW (G3 — no inheritance): the content hashes of the bootstrap framework
+         *  controller + the governance law package the child installs IN-CHAIN as its genesis intent 0. Frozen
+         *  facts the requester presents (the parent's current law, captured at birth time). When present, the
+         *  genesis recipe prepends the two-layer installDomain; the kernel resolves the BYTES by hash from its
+         *  own custody (never the host). Absent ⇒ the recipe resolves an already-installed law by shape. */
+        frameworkHash: sha256Hex.optional(),
+        lawHash: sha256Hex.optional(),
+        /** THE WARRANT-FLIP (VA-1): TRUE iff the child's genesis recipe declares an AuthProvider — the child
+         *  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(),
       })
       // 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.
@@ -694,13 +770,23 @@ export const birthChild = directive("birthChild")
   )
   .plan((p) => {
     const rec = planBirthRecord(p, p.foundingAdminHash ? { foundingAdminHash: p.foundingAdminHash, pool: p.pool } : undefined);
-    // LAW AUTHORS THE GENESIS RECIPE (P1): a genesis birth carries its child's seedGenesis→grantAdmin→
-    // birthCloud chain as data; the provider replays it opaquely. (refine guarantees principal + bornAt here.)
+    // LAW AUTHORS THE GENESIS RECIPE (P1): a genesis birth carries its child's [installDomain×2 →]
+    // seedGenesis→grantAdmin→birthCloud chain. (refine guarantees principal + bornAt here.)
     if (p.foundingAdminHash) {
-      rec.set("genesisChain", buildGenesisChain({ name: p.name, principal: p.principal, tier: p.tier, foundingAdminHash: p.foundingAdminHash, bornAt: p.bornAt as string, requestedAt: p.requestedAt }));
+      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 ? { requiresWarrant: true } : {}) });
+      // 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);
+      // THE DECLARED BIRTH EFFECT (G3 — the unix model): the recipe rides the committed intent as a declared
+      // output (`captured_ports.births`). The kernel — reading the `.births` DECLARATION off the law manifest
+      // (the `nomosBirthGate` era key, NEVER this CloudWorkspace aggregate) — takes the recipe off the intent
+      // after admit and spawns + self-validates the child through the child's OWN gate. So birth is an
+      // EXPLICIT, declared consequence of the offer, not a side-effect inferred by scanning domain state.
+      birth({ workspace: p.name, genesisChain: JSON.parse(genesisChain) });
     }
     return [];
   })
+  .births() // BIRTH IS A DECLARED KERNEL PRIMITIVE (G3): emits the `nomosBirthGate` era key; the kernel folds the carried recipe
   .requires("creator"); // THE ONE birth authority — a #creator may birth a leaf OR a platform (tier collapsed)
 
 /** workspacesByStatus — the birth provider drains `requested` CloudWorkspaces that CARRY A foundingAdminHash
@@ -745,13 +831,31 @@ export const AuthProvider = aggregate("AuthProvider", {
   scope: t.string().merge(Lww),
   /** The token issuer (the `iss` claim tokens must carry). */
   issuer: t.string().merge(Lww),
-  /** The provider's public JWKS endpoint (asymmetric verification keys). */
+  /** The provider's public JWKS endpoint (asymmetric verification keys). The KERNEL never fetches — it's a
+   *  reference for the rotation capability that re-fetches + re-sets {@link keys}. */
   jwksUrl: t.string().merge(Lww),
+  /** THE VERIFYING KEYS — the JWKS JSON (`{keys:[{kid,kty,alg,crv,x,y,n,e,...}]}`) as an OPAQUE STRING the
+   *  KERNEL parses + verifies a presented token against (sovereign-auth arc — see
+   *  architecture/sovereign_adapter.md). `t.string` (NOT `t.json`): the kernel `Value` has no JSON variant,
+   *  so the raw JWKS text must ride verbatim as a scalar — the kernel does `serde_json` on it, no projection
+   *  parse, no double-encoding. LAW-STATE: set by {@link setAuthProvider} (gated), refreshed by the
+   *  JWKS-fetch rotation capability (the host FETCHES — impure — but the law OWNS the keys + the kernel does
+   *  the verification). Absent ⇒ no in-kernel verify for this workspace (shell-issuer fallback, transitional). */
+  keys: t.string().merge(Lww).optional(),
   /** OPTIONAL expected `aud` claim. When the platform sets it, a token's `aud` MUST carry this value
    *  (defense-in-depth beyond the issuer match — e.g. a Firebase project id, an Auth0 API audience).
    *  Absent ⇒ issuer match alone. This is LAW-STATE the PLATFORM owns; the host merely enforces it as a
    *  capability (it never chooses the audience). */
   audience: t.string().merge(Lww),
+  /** OPTIONAL — the JWT claim that carries the PRINCIPAL (default `"sub"` when absent). Azure AD's stable
+   *  user id is `oid` (its `sub` is pairwise-per-app, useless as identity); some setups key on a custom
+   *  claim. The KERNEL extracts THIS claim as the principal — never hardcoded to `sub`. */
+  principalClaim: t.string().merge(Lww).optional(),
+  /** OPTIONAL — the PINNED CA ROOT (base64 DER) for TRUSTLESS key rotation. When set, {@link rotateKeys}
+   *  accepts a new JWKS IFF each key's `x5c` chain validates to THIS root IN THE KERNEL (RFC 5280, the IdP's
+   *  CA vouches) and each key matches its leaf cert — no host trust, no admin. Pinned once via the
+   *  admin-gated {@link setAuthProvider}. Absent ⇒ no trustless rotation (rotate via setAuthProvider). */
+  rootCert: t.string().merge(Lww).optional(),
   /** Human label for audit ("acme supabase", ...). */
   label: t.string().merge(Lww),
   /** Who set it (attribution). */
@@ -773,6 +877,13 @@ export const setAuthProvider = directive("setAuthProvider")
       issuer: z.string().regex(/^https?:\/\/\S+$/, "expected an http(s) URL"),
       jwksUrl: z.string().regex(/^https?:\/\/\S+$/, "expected an http(s) URL"),
       audience: z.string().min(1).optional(),
+      /** The JWKS JSON (the public verifying keys) the KERNEL checks tokens against. Optional so the
+       *  rotation capability can re-set just the keys; absent keeps the prior keys (Lww). */
+      keys: z.string().min(1).optional(),
+      /** OPTIONAL — the claim carrying the principal (default "sub"; e.g. "oid" for Azure AD). */
+      principalClaim: z.string().min(1).optional(),
+      /** OPTIONAL — the pinned CA root (base64 DER) enabling trustless {@link rotateKeys}. */
+      rootCert: z.string().min(1).optional(),
       label: z.string().min(1),
       setBy: z.string().min(1),
       setAt: epochMs,
@@ -785,6 +896,9 @@ export const setAuthProvider = directive("setAuthProvider")
       set(ap, "issuer", p.issuer),
       set(ap, "jwksUrl", p.jwksUrl),
       ...(p.audience ? [set(ap, "audience", p.audience)] : []),
+      ...(p.keys ? [set(ap, "keys", p.keys)] : []),
+      ...(p.principalClaim ? [set(ap, "principalClaim", p.principalClaim)] : []),
+      ...(p.rootCert ? [set(ap, "rootCert", p.rootCert)] : []),
       set(ap, "label", p.label),
       set(ap, "setBy", p.setBy),
       set(ap, "setAt", p.setAt),
@@ -792,6 +906,30 @@ export const setAuthProvider = directive("setAuthProvider")
   })
   .requires("admin");
 
+/**
+ * rotateKeys — TRUSTLESS key rotation. Replace {@link AuthProvider.keys} with a new JWKS whose every key
+ * carries an `x5c` cert chain. DELIBERATELY UNGATED at the relation level — the KERNEL is the authority: it
+ * admits this ONLY if each key's x5c chain validates (RFC 5280) to the law-pinned {@link AuthProvider.rootCert}
+ * and each key matches its CA-vouched leaf cert (the bind). So a bailiff (host on a cron, or anyone) may
+ * FETCH the IdP's rotated JWKS and offer it, but cannot forge keys — forged keys wouldn't chain to the root.
+ * No host trust, no admin: the IdP's CA vouches. Workspaces with no pinned root rotate via setAuthProvider.
+ */
+export const rotateKeys = directive("rotateKeys")
+  .ensures(AuthProvider)
+  .payload(
+    z.object({
+      /** The new JWKS JSON; EACH key MUST carry an `x5c` the kernel validates to {@link AuthProvider.rootCert}. */
+      keys: z.string().min(1),
+      rotatedAt: epochMs,
+    }),
+  )
+  .plan((p) => {
+    const ap = instance(AuthProvider, "auth-provider:platform");
+    // The kernel's x5c admission gate authorizes this (validate_rotate_keys); the plan just stores the
+    // CA-vouched JWKS. The `ensures` marker upserts onto the existing AuthProvider singleton.
+    return [withMarker(set(ap, "keys", p.keys), "ensures"), set(ap, "setAt", p.rotatedAt)];
+  });
+
 /**
  * HostnameClaim — a CUSTOM HOSTNAME bound to a platform: `api.acme.com` serving
  * acme's subtree. A root-custody fact (the hostname is the HOST's edge resource —
@@ -1006,14 +1144,21 @@ export const setWorkspaceByteCap = directive("setWorkspaceByteCap")
 export const grantAdmin = directive("grantAdmin")
   .ensures(RelationTuple)
   .payload(
-    z.object({
-      keyHash: sha256Hex,
-      label: z.string().min(1),
-      grantedBy: z.string().min(1),
-      grantedAt: epochMs,
-    }),
+    z
+      .object({
+        // `principal` (a `user:<uid>` subject) is the PRINCIPAL-CENTRIC grant — authority lives on the
+        // identity, so it survives device-key ROTATION (the signer indirection's whole point) and matches
+        // the subject a SIGNED author resolves to. `keyHash` (a `key:<hash>` subject) is the legacy
+        // key-centric grant (the bearer-secret lane). Exactly one — mirrors grantCreation.
+        keyHash: sha256Hex.optional(),
+        principal: z.string().min(1).optional(),
+        label: z.string().min(1),
+        grantedBy: z.string().min(1),
+        grantedAt: epochMs,
+      })
+      .refine((d) => !!d.keyHash !== !!d.principal, { message: "grantAdmin needs exactly one of keyHash (a key: subject) or principal (a user: subject)", path: ["keyHash"] }),
   )
-  .plan((p) => writeTuple({ object: SELF_ADMIN_OBJECT, relation: "admin", subject: "key:" + p.keyHash, grantedBy: p.grantedBy, grantedAt: String(p.grantedAt) }))
+  .plan((p) => writeTuple({ object: SELF_ADMIN_OBJECT, relation: "admin", subject: p.principal ? "user:" + p.principal : "key:" + p.keyHash, grantedBy: p.grantedBy, grantedAt: String(p.grantedAt) }))
   .requires("admin"); // only an admin grants admin (pre-apply roster ⇒ no self-grant)
 
 /**
@@ -1027,13 +1172,16 @@ export const grantAdmin = directive("grantAdmin")
 export const revokeAdmin = directive("revokeAdmin")
   .ensures(RelationTuple)
   .payload(
-    z.object({
-      keyHash: sha256Hex,
-      revokedBy: z.string().min(1),
-      revokedAt: epochMs,
-    }),
+    z
+      .object({
+        keyHash: sha256Hex.optional(),
+        principal: z.string().min(1).optional(),
+        revokedBy: z.string().min(1),
+        revokedAt: epochMs,
+      })
+      .refine((d) => !!d.keyHash !== !!d.principal, { message: "revokeAdmin needs exactly one of keyHash or principal", path: ["keyHash"] }),
   )
-  .plan((p) => removeTuple({ object: SELF_ADMIN_OBJECT, relation: "admin", subject: "key:" + p.keyHash, grantedBy: p.revokedBy, grantedAt: String(p.revokedAt), revokedBy: p.revokedBy, revokedAt: String(p.revokedAt) }))
+  .plan((p) => removeTuple({ object: SELF_ADMIN_OBJECT, relation: "admin", subject: p.principal ? "user:" + p.principal : "key:" + p.keyHash, grantedBy: p.revokedBy, grantedAt: String(p.revokedAt), revokedBy: p.revokedBy, revokedAt: String(p.revokedAt) }))
   .requires("admin");
 
 /**
@@ -1253,3 +1401,18 @@ export const provisionReceiptGuard = workspaceInvariant("ProvisionReceiptGuard")
       return { reject: "provision-founding-hash-mismatch" };
     return { accept: true };
   });
+
+/** reclaimWorkspace: THE RETIRED→RECLAIMED TWO-PHASE INTERLOCK, AS LAW (#41/#58). Reclaim authorizes the
+ *  irreversible custody discard, so only a `retired` workspace may be reclaimed — retire WITHDRAWS (a status,
+ *  reversible), reclaim DISCARDS. The invariant reads the pre-apply status of the record being reclaimed (same
+ *  shape as ProvisionReceiptGuard) and refuses unless it is exactly `retired`. Fires at the ONE wasm gate on
+ *  every peer — author, edge admission, AND verify_chain — so the interlock is identical on cloud + client +
+ *  replay; the bailiff's drop merely executes the lawful `reclaimed` fact. (Root never reaches here: the law
+ *  refuses reclaiming itself; this guards children.) */
+export const reclaimRequiresRetired = workspaceInvariant("ReclaimRequiresRetired")
+  .on("reclaimWorkspace")
+  .reads((ctx) => [refAs("ws", "CloudWorkspace", "pre:" + String((ctx.intent ?? {}).workspaceId ?? ""))])
+  .assert(({ ws }) => {
+    const rec = ws as { status?: string } | undefined;
+    return rec?.status === "retired" ? { accept: true } : { reject: "reclaim-requires-retired" };
+  });

package/src/index.ts

@@ -94,6 +94,18 @@ export { create, existing, ensure, type AggregateRef } from "./authoring.js";
 // `nomos-compile` REFUSES law that references read() (a named compile error, never a runtime halt).
 // The captured-reads wave (task #58) wires the capability in and lifts the refusal.
 export { read } from "./read.js";
+// THE BIRTH EFFECT (G3 — birth is a declared kernel primitive): a `.births()` directive's plan records the
+// child's genesis recipe via `birth(recipe)` (reuse `buildGenesisChain`); it rides the committed intent as a
+// declared output, and the kernel — reading the `.births` declaration off the law manifest (the
+// `nomosBirthGate` era key, never domain state) — spawns + self-validates the child after the offer admits.
+export { birth, type BirthRecipe } from "./births.js";
+// THE PEER-SOVEREIGN ROOT-OF-TRUST (the BirthAttestation cert chain): a home/child law exports
+// `requireParentAttestedBirth` to declare it requires a parent-attested-birth cert chain (the
+// `nomosParentAttestedBirth` era key); the kernel verify doors then verify the travelling chain to K_root.
+export {
+  requireParentAttestedBirth,
+  type ParentAttestedBirthMarker,
+} from "./births.js";
 export {
   query,
   hasManyIndexes,
@@ -247,6 +259,28 @@ export {
   signerObject,
   SIGNER_RELATION,
   enrollSigner,
+  // VA-core — SignerEpoch + self-bind enroll/revoke + the strict-increment & verified-enroll gates.
+  SignerEpoch,
+  SIGNER_EPOCH_ID,
+  signerEpochCurrent,
+  advanceSignerEpoch,
+  signerEpochStrictlyIncreases,
+  enrollSignerSelf,
+  enrollSignerSelfRequiresVerified,
+  revokeSigner,
+  revokeSignerEpochStrictlyIncreases,
+  signerTuplesByObject,
+  signerTupleInstanceId,
+  // THE ENROLL-ONCE DELEGATION (the peer-sovereign root-of-trust) — the per-user tenant-signed cert the
+  // kernel reads to assemble U's home cert chain at birth.
+  SignerDelegation,
+  SIGNER_DELEGATION_PREFIX,
+  signerDelegationInstanceId,
+  enrollDelegation,
+  signerDelegationByUser,
+  type SignerDelegationHandle,
+  type SignerEpochHandle,
+  type SignerAuthority,
 } from "./framework/signing_identity.js";
 // THE HOME HOLON (home_holons_and_cross_custody.md §4) — the identity-role law: the shared-with-me access
 // index + the owner lane to maintain it (the key directory is the `signer` relation above).
@@ -262,6 +296,14 @@ export {
   seedHomeOwner,
   writeHomeOwner,
   homeNameBindsOwner,
+  homeNameOf,
+  birthHome,
+  // THE PEER-SOVEREIGN ROOT-OF-TRUST (the BirthAttestation cert chain).
+  BirthAttestation,
+  BIRTH_ATTESTATION_ID,
+  seedBirthAttestation,
+  birthAttestation,
+  parentAttestedBirth,
 } from "./framework/home.js";
 // THE GENESIS WARRANT (identity_keys.md step 0) — the in-history birth fact that lets
 // the gate's genesis clause admit a founding control-plane grant on a virgin chain.

package/src/usd.ts

@@ -285,6 +285,33 @@ export interface UsdLayer {
       }
     >;
   };
+  /**
+   * THE BIRTH GATE DECLARATION (G3 — birth is a declared kernel primitive, the unix model). Present IFF ≥1
+   * directive declares `.births()`: the SORTED set of their ids. A directive named here BIRTHS a child
+   * workspace as the defined CONSEQUENCE of its offer — after the offer admits, the kernel reads THIS
+   * declaration (the SAME way it reads `nomosReadGate`/`nomosInvariantGate` — never a domain aggregate),
+   * takes the genesis recipe the intent carried (its `captured_ports.births`), spawns the child's custody,
+   * and self-validates the child's whole genesis through the child's OWN gate (the `materialize_genesis`
+   * keystone). The kernel reads NO domain schema; it reads its own manifest declaration + the carried
+   * recipe. OMITTED for law with no birth directive (the era rule — byte-identical hash; every pre-feature
+   * chain replays green, the birth effect inert). SORTED keys for byte-determinism.
+   */
+  readonly nomosBirthGate?: {
+    readonly v: 1;
+    /** The directive ids declared `.births()` — SORTED. */
+    readonly directives: string[];
+  };
+  /**
+   * THE PEER-SOVEREIGN ROOT-OF-TRUST (the BirthAttestation cert chain). Present IFF the law declares
+   * `requireParentAttestedBirth`: a warranted workspace running this law MUST travel with a SIGNED cert
+   * chain proving its founder was VERIFIED by its parent at birth, rooting at the pinned `K_root`. The
+   * kernel's verify doors (author / receive / verify_chain) verify the travelling chain OFFLINE — no
+   * cross-ws read. OMITTED for law that doesn't declare it (the era rule — byte-identical hash; every
+   * pre-feature + legacy/non-warranted chain replays green, the check inert).
+   */
+  readonly nomosParentAttestedBirth?: {
+    readonly v: 1;
+  };
   /**
    * STABLE IDENTIFIERS (#58 — names are labels, identity is minted). The layer's
    * domain/aggregate/field sids + label lineages, carried verbatim from the canonical
@@ -721,6 +748,21 @@ export function emitUsd(
       }
       const nomosAttestationGate =
         Object.keys(attestationReq).length > 0 ? { v: 1 as const, directives: attestationReq } : undefined;
+      // THE BIRTH GATE (G3 — birth is a declared kernel primitive): the SORTED set of directive ids
+      // declaring `.births()`. The kernel reads this off the manifest (never a domain aggregate) to know an
+      // admitted directive births, then folds the recipe the intent carried. Omit-when-empty (era rule —
+      // a birth-free layer is byte-identical apart from the always-on stableIds key).
+      const birthDirectives = [...l.module.directives]
+        .filter((d) => (d as { birthsChild?: boolean }).birthsChild === true)
+        .map((d) => d.id)
+        .sort();
+      const nomosBirthGate =
+        birthDirectives.length > 0 ? { v: 1 as const, directives: birthDirectives } : undefined;
+      // THE PEER-SOVEREIGN ROOT-OF-TRUST: the home/child law declared it requires a parent-attested-birth
+      // cert chain (the `requireParentAttestedBirth` sentinel, discovered by composeDomainModule). Emit the
+      // era key iff true; omit otherwise (a law that doesn't require it is byte-identical — the era rule).
+      const nomosParentAttestedBirth =
+        (l.module as { parentAttestedBirth?: boolean }).parentAttestedBirth === true ? { v: 1 as const } : undefined;
       // THE CAPTURED-READ GATE DECLARATION (#58): collected from the canonical
       // manifest's per-directive `capturedReads` (omit-when-empty — read-free law's
       // USD is byte-identical apart from the always-on stableIds key).
@@ -850,6 +892,8 @@ export function emitUsd(
         ...(nomosRelations !== undefined ? { nomosRelations } : {}),
         ...(nomosRelationGate !== undefined ? { nomosRelationGate } : {}),
         ...(nomosAttestationGate !== undefined ? { nomosAttestationGate } : {}),
+        ...(nomosBirthGate !== undefined ? { nomosBirthGate } : {}),
+        ...(nomosParentAttestedBirth !== undefined ? { nomosParentAttestedBirth } : {}),
         ...(Object.keys(visAggregates).length > 0
           ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }
           : {}),

package/src/usd_layers.ts

@@ -177,6 +177,12 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosAttestationGate !== undefined
       ? [`${indent}custom string nomos:attestationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttestationGate)))}`]
       : []),
+    ...(layer.nomosBirthGate !== undefined
+      ? [`${indent}custom string nomos:birthGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosBirthGate)))}`]
+      : []),
+    ...(layer.nomosParentAttestedBirth !== undefined
+      ? [`${indent}custom string nomos:parentAttestedBirthHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosParentAttestedBirth)))}`]
+      : []),
   ];
 }
 
@@ -765,6 +771,23 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         attestationGate = { v: 1, directives: rec };
       }
     }
+    // THE BIRTH GATE (G3): the SORTED union of every layer's `.births()` directive ids. Omit-when-empty
+    // (era rule). The set is the contract; order is incidental (sorted for byte-determinism).
+    let birthGate: UsdLayer["nomosBirthGate"];
+    {
+      const b = new Set<string>();
+      for (const l of stack) {
+        if (l.nomosBirthGate === undefined) continue;
+        for (const id of l.nomosBirthGate.directives) b.add(id);
+      }
+      if (b.size > 0) birthGate = { v: 1, directives: [...b].sort() };
+    }
+    // THE PEER-SOVEREIGN ROOT-OF-TRUST: the era key is present iff ANY layer in the stack declares it
+    // (a boolean union — once required, required). Omit-when-absent (era rule).
+    let parentAttestedBirth: UsdLayer["nomosParentAttestedBirth"];
+    if (stack.some((l) => l.nomosParentAttestedBirth !== undefined)) {
+      parentAttestedBirth = { v: 1 };
+    }
     return {
       path,
       prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
@@ -781,6 +804,8 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       ...(relations !== undefined ? { nomosRelations: relations } : {}),
       ...(relationGate !== undefined ? { nomosRelationGate: relationGate } : {}),
       ...(attestationGate !== undefined ? { nomosAttestationGate: attestationGate } : {}),
+      ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
+      ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
     };
   });
 
@@ -908,6 +933,8 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const relationsByDomain = new Map<string, UsdLayer["nomosRelations"]>();
   const relationGateByDomain = new Map<string, UsdLayer["nomosRelationGate"]>();
   const attestationGateByDomain = new Map<string, UsdLayer["nomosAttestationGate"]>();
+  const birthGateByDomain = new Map<string, UsdLayer["nomosBirthGate"]>();
+  const parentAttestedBirthByDomain = new Map<string, UsdLayer["nomosParentAttestedBirth"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
@@ -959,6 +986,16 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof attGateHex === "string") {
         attestationGateByDomain.set(domain, JSON.parse(unhexUtf8(attGateHex)) as UsdLayer["nomosAttestationGate"]);
       }
+      // THE BIRTH GATE (G3): the hex-carried `.births()` directive set.
+      const birthGateHex = p.attrs.get("nomos:birthGateHex");
+      if (typeof birthGateHex === "string") {
+        birthGateByDomain.set(domain, JSON.parse(unhexUtf8(birthGateHex)) as UsdLayer["nomosBirthGate"]);
+      }
+      // THE PEER-SOVEREIGN ROOT-OF-TRUST: the hex-carried parent-attested-birth era marker.
+      const pabHex = p.attrs.get("nomos:parentAttestedBirthHex");
+      if (typeof pabHex === "string") {
+        parentAttestedBirthByDomain.set(domain, JSON.parse(unhexUtf8(pabHex)) as UsdLayer["nomosParentAttestedBirth"]);
+      }
     }
   }
 
@@ -1056,6 +1093,8 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const rel = relationsByDomain.get(domain);
       const relGate = relationGateByDomain.get(domain);
       const attGate = attestationGateByDomain.get(domain);
+      const birthGate = birthGateByDomain.get(domain);
+      const parentAttestedBirth = parentAttestedBirthByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
@@ -1072,6 +1111,8 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(rel !== undefined ? { nomosRelations: rel } : {}),
         ...(relGate !== undefined ? { nomosRelationGate: relGate } : {}),
         ...(attGate !== undefined ? { nomosAttestationGate: attGate } : {}),
+        ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
+        ...(parentAttestedBirth !== undefined ? { nomosParentAttestedBirth: parentAttestedBirth } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));

package/src/wire.ts

@@ -40,6 +40,10 @@ export type WireValue =
   | { Set: string[] }
   | { Map: Record<string, WireField> }
   | { Evidence: WireEvidenceRef }
+  // First-class canonical JSON (RFC 8785 / JCS) — the committed form of a `t.json()` leaf. The
+  // value rides INLINE (`{Json: <any json>}`), not as a string-of-JSON; the kernel canonicalises
+  // it at the boundary (`canonical_json.rs`) and decodes the variant directly into structured JSON.
+  | { Json: unknown }
   // ── STRUCTURAL CRDT state values (only seen when reading RAW folded state back; the read MODEL
   //    collapses them via the kernel `observed_value` to Int/Str/Set, so typed reads stay scalar) ──
   | { Counter: Record<string, { pos: number; neg: number }> }
@@ -135,6 +139,15 @@ export interface WireIntent {
    * empty so a principal-free intent is byte-identical.
    */
   endorse?: { sink: string; facet: string; reason: string | null }[];
+  /**
+   * THE BIRTH EFFECT (G3 — birth is a declared kernel primitive, the unix model): the genesis recipe(s) a
+   * `.births()` directive's plan produced (`birth(recipe)`). It rides the intent as a DECLARED OUTPUT — the
+   * kernel reads the `.births` DECLARATION off the law manifest (the `nomosBirthGate` era key, NOT domain
+   * state), then takes this recipe off the admitted intent and spawns + self-validates the child through the
+   * child's OWN gate. A verify-input WITNESS (rides the carried `captured_ports`, never the events nor the
+   * OID). OMITTED when empty so a birth-free intent is byte-identical to before this existed (the era rule).
+   */
+  births?: { workspace: string; genesisChain: unknown }[];
 }
 
 /**

package/src/wire_encode.ts

@@ -22,6 +22,7 @@
 import { encodeDriver } from "./drivers.js";
 import { __resetAuthoring, __drainAuthoring } from "./authoring.js";
 import { __resetReads, __drainReads } from "./read.js";
+import { __resetBirths, __drainBirths } from "./births.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { Field, EvidenceRefValue } from "./fields.js";
 import type { Directive, ReferentialMarker } from "./directive.js";
@@ -86,14 +87,18 @@ function encodeKernelValue(field: Field | undefined, value: unknown): WireValue
       },
     };
   }
+  // A `t.json()` leaf lowers to the FIRST-CLASS kernel `Value::Json` (RFC 8785 / JCS), NOT a
+  // `Value::Str` holding JSON-shaped text. Checked BEFORE the scalar fallthroughs so EVERY json
+  // value — object, array, string, number, boolean, null — commits as one consistent value kind
+  // (the kernel canonicalises it at the boundary). This is the new-era encoding; a package compiled
+  // before this change froze the old `{ Str: JSON.stringify(value) }` lump and replays unchanged.
+  if (field?.kind === "json") return { Json: value };
   // For scalar Set/SetEntry the kernel expects Str or Int. Maps store leaves;
   // a map's entry value is a leaf scalar.
   if (typeof value === "number" && Number.isInteger(value)) return { Int: value };
   if (typeof value === "string") return { Str: value };
   if (typeof value === "boolean") return { Str: String(value) };
   // Enum values are strings; refs are id strings — both handled above.
-  // Anything else (object/array as a scalar) is JSON-encoded into a Str leaf.
-  if (field?.kind === "json") return { Str: JSON.stringify(value) };
   throw new Error(
     `Cannot encode value ${JSON.stringify(value)} for field '${field?.kind ?? "?"}': ` +
       `kernel scalars are Str | Int only.`,
@@ -196,9 +201,15 @@ export function executeDirectiveToIntent<P>(
   // The plan may also READ (O(1) DSL queries via `read(...)`) — captured into the footprint below.
   __resetAuthoring();
   __resetReads();
+  __resetBirths();
   const returned = directive.plan(parsed, ctx);
   const planned = [...__drainAuthoring(), ...returned];
   const reads = __drainReads();
+  // THE BIRTH EFFECT (G3 — birth is a declared kernel primitive): a `.births()` directive's plan records
+  // the child's genesis recipe via `birth(recipe)`; it rides the intent as a DECLARED output (like a
+  // captured read), drained here. Empty for every non-birth directive — OMITTED below so a birth-free
+  // intent is byte-identical (the era rule).
+  const births = __drainBirths();
 
   // Partition the plan output: STRIKE ops route onto the intent's `strikes` channel
   // (the kernel's strikeout / revert facet, folded by parity); FIELD ops group into
@@ -302,6 +313,7 @@ export function executeDirectiveToIntent<P>(
     events,
     ...(reads.length ? { reads } : {}),
     ...(endorse.length ? { endorse } : {}),
+    ...(births.length ? { births } : {}),
   };
 }