@githolon/dsl 0.16.3 → 0.18.0

package/src/engine_entry.ts

@@ -54,6 +54,13 @@
 import { executeDirectiveToIntent } from "./wire_encode.js";
 import { expandCapabilityExports } from "./capability_exports.js";
 import { RelationTuple } from "./framework/relations.js";
+import { generateOpenApiFragment, mergeOpenApiFragments, type OpenApiDoc } from "./codegen_openapi.js";
+import type { QueryDecl } from "./query.js";
+import type { AnyCount } from "./count.js";
+import type { AnySum } from "./sum.js";
+import type { AnyExtremum } from "./extremum.js";
+import type { SpatialDecl } from "./spatial.js";
+import type { DomainModule } from "./codegen_dart.js";
 import type { Directive } from "./directive.js";
 import type { AggregateHandle, AggregateInvariantFn, AggregateInvariantVerdict } from "./aggregate.js";
 import type { Ports } from "./ctx.js";
@@ -120,6 +127,34 @@ export interface EngineEntryConfig {
    * `sideEffects: false` (a bare side-effect import would be tree-shaken away).
    */
   readonly seeds?: readonly unknown[];
+  /**
+   * THE SELF-DESCRIBE INPUT (G1 — openapi residue removal): the per-domain read/maintenance
+   * decls the OpenAPI fragment needs that are NOT discoverable by shape from the live module
+   * exports alone (queries/counts/sums/mins/maxes/spatials/workspaceInvariants — the compiler
+   * already auto-discovered + named-resolved them when it composed each DomainModule). The
+   * directives + aggregates ARE discovered from the modules; these ride alongside so the
+   * lump's `globalThis.describe` reproduces the EXACT `<name>.openapi.json` the compiler wrote
+   * (byte-identity, no Rust re-implementation, no drift). Keyed by domain dispatch key, in the
+   * same declaration order as `domains`. Omitted ⇒ describe still emits offers from directives.
+   */
+  readonly openapiDecls?: Record<string, OpenApiDomainDecls>;
+  /**
+   * The package's OpenAPI document title (the compiler's `"<name> (nomos package)"`). Baked into
+   * the lump so `describe` reproduces the compiler's `<name>.openapi.json` byte-for-byte without
+   * the kernel knowing the package name. The kernel MAY override it (the workspace-level title).
+   */
+  readonly packageTitle?: string;
+}
+
+/** The openapi-relevant decls one domain contributes beyond its directives/aggregates. */
+export interface OpenApiDomainDecls {
+  readonly queries?: readonly QueryDecl[];
+  readonly counts?: readonly AnyCount[];
+  readonly sums?: readonly AnySum[];
+  readonly mins?: readonly AnyExtremum[];
+  readonly maxes?: readonly AnyExtremum[];
+  readonly spatials?: readonly SpatialDecl[];
+  readonly workspaceInvariants?: readonly WorkspaceInvariantDecl[];
 }
 
 interface RegistryEntry {
@@ -395,6 +430,8 @@ function portsFromHost(principalRaw = ""): Ports {
 export interface RegisteredEngine {
   plan(job: unknown): WireEvent[] | { events: WireEvent[]; strikes?: string[]; endorse?: { sink: string; facet: string; reason: string | null }[] };
   planReport(job: unknown): string;
+  /** The G1 self-describe verb: the lump's own merged OpenAPI, derived from its modules. */
+  describe(opts?: { lawHash?: string; title?: string }): OpenApiDoc;
 }
 
 /**
@@ -543,7 +580,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
   /** `{workspaceInvariantReads:{id}, payload}` → the bounded ref-set `[{name,aggregate,id},…]`. */
   function planWorkspaceInvariantReads(job: {
     intent?: { workspaceInvariantReads?: { id?: string }; payload?: unknown };
-    capturedPorts?: { principal?: string };
+    capturedPorts?: { principal?: string; principal_verified?: boolean };
   }): string {
     const id = job.intent?.workspaceInvariantReads?.id;
     if (typeof id !== "string") {
@@ -559,14 +596,17 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     // LAW-GATED AUTHZ: the captured author identity (a top-level sibling of `intent`, set by the wasm
     // author leg + replayed verbatim) — the governance invariant reads it to gate by the AUTHOR.
     const principal = (job.capturedPorts?.principal ?? "") as string;
-    return JSON.stringify(decl.reads({ intent, principal }));
+    // VA-core (Phase 3): the kernel-DERIVED author-verified flag (`captured_ports.principal_verified`),
+    // threaded the same way as `principal`, so an invariant may gate on a VERIFIED author (e.g. enrollSignerSelf).
+    const principalVerified = job.capturedPorts?.principal_verified === true;
+    return JSON.stringify(decl.reads({ intent, principal, principalVerified }));
   }
 
   /** `{workspaceInvariant:{id,on}, payload?}` + priorState (named snapshots) → {accept}|{reject}. */
   function planWorkspaceInvariantAssert(job: {
     intent?: { workspaceInvariant?: { id?: string }; payload?: unknown };
     priorState?: Record<string, unknown>;
-    capturedPorts?: { principal?: string };
+    capturedPorts?: { principal?: string; principal_verified?: boolean };
   }): string {
     const id = job.intent?.workspaceInvariant?.id;
     if (typeof id !== "string") {
@@ -581,7 +621,9 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     const snapshots = (job.priorState ?? {}) as Record<string, Record<string, unknown>>;
     const intent = (job.intent?.payload ?? {}) as Record<string, unknown>;
     const principal = (job.capturedPorts?.principal ?? "") as string;
-    return JSON.stringify(decl.assert(snapshots, { intent, principal }));
+    // VA-core (Phase 3): the kernel-DERIVED author-verified flag — threaded like `principal`.
+    const principalVerified = job.capturedPorts?.principal_verified === true;
+    return JSON.stringify(decl.assert(snapshots, { intent, principal, principalVerified }));
   }
 
   function planDerive(job: {
@@ -717,7 +759,7 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
   function plan(job: {
     intent?: { domain?: string; directiveId?: string; payload?: unknown };
     capturedPorts?: { principal?: string };
-  }): WireEvent[] | { events: WireEvent[]; strikes?: string[]; endorse?: { sink: string; facet: string; reason: string | null }[] } {
+  }): WireEvent[] | { events: WireEvent[]; strikes?: string[]; endorse?: { sink: string; facet: string; reason: string | null }[]; births?: { workspace: string; genesisChain: unknown }[] } {
     const intent = job.intent ?? {};
     const domain = intent.domain;
     const directiveId = intent.directiveId;
@@ -739,18 +781,77 @@ export function registerEngine(config: EngineEntryConfig): RegisteredEngine {
     // it to check the law's nomosFlowGate.endorse; decode_plan_output ignores it for the byte-compare),
     // so a principal-free intent still emits the bare array, byte-identical.
     const endorse = wire.endorse;
-    if (!wire.strikes.length && !(endorse && endorse.length)) return wire.events;
+    // THE BIRTH EFFECT (G3): a `.births()` directive's plan recorded the child's genesis recipe; it rides the
+    // plan-output object as a TRANSIENT verify-input (like `endorse` — the kernel reads it onto the intent's
+    // `captured_ports.births` and folds it after admit; decode_plan_output ignores it for the byte-compare),
+    // so a birth-free intent still emits the bare event array, byte-identical (the era rule).
+    const births = wire.births;
+    if (!wire.strikes.length && !(endorse && endorse.length) && !(births && births.length)) return wire.events;
     return {
       events: wire.events,
       ...(wire.strikes.length ? { strikes: wire.strikes } : {}),
       ...(endorse && endorse.length ? { endorse } : {}),
+      ...(births && births.length ? { births } : {}),
     };
   }
 
+  /**
+   * 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.
+   * `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)"`.
+   */
+  function describe(opts?: { lawHash?: string; title?: string }): OpenApiDoc {
+    const lawHash = opts?.lawHash;
+    const fragments: OpenApiDoc[] = [];
+    for (const domainName of domainNames) {
+      const sources = config.domains[domainName];
+      if (sources === undefined) continue;
+      const merged = mergeModules(sources.map((m) => (typeof m === "function" ? m() : m)));
+      // Aggregates dedup by wire id + RelationTuple auto-ensure (the compose contract) — openapi
+      // reads aggregates only for the hasMany inverse indexes, so this matches composeDomainModule.
+      const byId = aggregatesOf(merged);
+      const directives = [...directivesOf(merged).values()];
+      if (!byId.has(RelationTuple.id) && directives.some((d) => d.aggregateId === RelationTuple.id)) {
+        byId.set(RelationTuple.id, RelationTuple);
+      }
+      const decls = config.openapiDecls?.[domainName] ?? {};
+      const module = {
+        name: domainName,
+        domain: domainName,
+        aggregates: [...byId.values()],
+        directives,
+        ...(decls.queries && decls.queries.length > 0 ? { queries: [...decls.queries] } : {}),
+        ...(decls.counts && decls.counts.length > 0 ? { counts: [...decls.counts] } : {}),
+        ...(decls.sums && decls.sums.length > 0 ? { sums: [...decls.sums] } : {}),
+        ...(decls.mins && decls.mins.length > 0 ? { mins: [...decls.mins] } : {}),
+        ...(decls.maxes && decls.maxes.length > 0 ? { maxes: [...decls.maxes] } : {}),
+        ...(decls.spatials && decls.spatials.length > 0 ? { spatials: [...decls.spatials] } : {}),
+        ...(decls.workspaceInvariants && decls.workspaceInvariants.length > 0
+          ? { workspaceInvariants: [...decls.workspaceInvariants] }
+          : {}),
+      } as unknown as DomainModule;
+      fragments.push(generateOpenApiFragment(module, lawHash !== undefined ? { lawHash } : {}));
+    }
+    const title = opts?.title ?? config.packageTitle;
+    return mergeOpenApiFragments(fragments, {
+      ...(title !== undefined ? { title } : {}),
+      ...(lawHash !== undefined ? { lawHash } : {}),
+    });
+  }
+
   // The engine evals the bundle as a classic script and FREEZES globalThis before
-  // dispatch — assign both entries NOW, at top-level eval.
+  // dispatch — assign all entries NOW, at top-level eval. `describe` is the G1 self-
+  // describe verb (the kernel `describe` run mode evals `globalThis.describe(opts)`).
   (globalThis as { plan?: unknown }).plan = plan;
   (globalThis as { planReport?: unknown }).planReport = planReport;
+  (globalThis as { describe?: unknown }).describe = describe;
 
-  return { plan, planReport } as RegisteredEngine;
+  return { plan, planReport, describe } as RegisteredEngine;
 }

package/src/framework/home.ts

@@ -32,8 +32,11 @@ import { directive } from "../directive.js";
 import { create } from "../authoring.js";
 import { set, type PlannedOp } from "../ops.js";
 import { query } from "../query.js";
+import { birth } from "../births.js";
 import { workspaceInvariant, refAs } from "./workspace_invariant.js";
 import { identityRelations } from "./signing_identity.js";
+import { requireParentAttestedBirth } from "../births.js";
+import { GenesisWarrant, seedGenesis } from "./genesis.js";
 
 // `nomos.sha256` — the TRUSTLESS, pure hash computed IN the githolon (Rust sha2 bound in the sealed engine;
 // see deterministic-rquickjs). Available as a global to plans + invariant predicates (like `nomos.mint`); it
@@ -44,6 +47,12 @@ declare const nomos: { sha256(input: string): string };
  *  identity's public device keys, enrolled via `enrollSigner`, checked by the gate). */
 export { identityRelations };
 
+/** THE GENESIS WARRANT primitives — re-exported so a HOME law carries them in the `home` domain key. The
+ *  birthHome genesis chain runs `home/seedGenesis` to record the home's unique self-id (== homeName), so
+ *  `workspace_self_id` resolves on the home and BOTH the signed-author regime + the parent-attested-birth
+ *  cert door FIRE on every home (BREAK 1). Without this the home is unwarranted and both doors are inert. */
+export { GenesisWarrant, seedGenesis };
+
 /**
  * THE HOME OWNER (home_holons §5 — the owner stamp). A home holon is born UNWARRANTED (the subject may
  * never have logged in — a share can be delivered to a stranger's lazily-born home, before they hold any
@@ -105,6 +114,94 @@ export const homeNameBindsOwner = workspaceInvariant("HomeNameBindsOwner")
       : { reject: "a home's name must hash its owner (home-<sha256(principal)>) — refusing a squatted home" };
   });
 
+/** Re-derive a subject's home slot name IN-LAW (`home-<sha256(subject)>`) — the SAME formula the client's
+ *  `homeNameOf` and the {@link homeNameBindsOwner} invariant use. `nomos.sha256` is the trustless pure hash
+ *  bound in the sealed engine, so every replaying peer derives the identical name. */
+export function homeNameOf(subject: string): string {
+  return HOME_NAME_PREFIX + nomos.sha256(String(subject)).slice(0, HOME_NAME_HASH_LEN);
+}
+
+/**
+ * `birthHome` — THE FRAMEWORK BIRTH PRIMITIVE for a home holon. This is the MECHANICS (OURS) so a tenant
+ * never hand-builds a home genesis: the parent (the cloud/platform whose governance includes this directive)
+ * ORDERS the birth of an identity's home holon, and the kernel's offer-effect spawns it + self-validates it
+ * through the child's OWN gate from intent 0 (the `.births()` declared consequence; `architecture/
+ * home_holons_and_cross_custody.md` + `sovereign_adapter.md` "birth is a kernel offer-effect").
+ *
+ * SELF-BOUND — squatting is structurally impossible (no separate grant needed; the policy gate is the
+ * tenant's `setAuthProvider` auth scoping, which decides whether the offering principal is verified at all):
+ *   1. The home OWNER rides the payload (`owner`, a `user:<uid>` subject). `ctx.principal()` is opaque
+ *      PrincipalEvidence — it CANNOT be read as a raw string in-plan to compute the slot name — so the owner
+ *      is payload-carried, but the binding below makes it sound.
+ *   2. The workspace name + the seeded `homeName` are BOTH derived from THE SAME payload `owner` via
+ *      {@link homeNameOf} — they cannot diverge in this plan.
+ *   3. The child's genesis includes `seedHomeOwner(owner, homeNameOf(owner), bornAt)`, and the home law's
+ *      {@link homeNameBindsOwner} invariant RE-DERIVES `home-<sha256(owner)>` at the child's gate (author AND
+ *      verify_chain). So a chain that claims `home-<hash(alice)>` but seeds owner `bob` FAILS the child's own
+ *      law — refused in the githolon, by the law, never by a host. A verified principal is required upstream
+ *      (no anonymous home birth); the offer principal IS the auth boundary (the tenant's setAuthProvider).
+ *
+ * The genesis chain it authors (reusing the order-declares-the-law install shape — bytes resolved by hash
+ * from the parent's custody, `domainPackageB64: ""`):
+ *   [ bootstrap/installDomain(frameworkHash), nomos/home installDomain(lawHash), seedHomeOwner(owner, …) ]
+ * `frameworkHash` (the bootstrap controller hash) + `lawHash` (the HOME law package domainHash) are
+ * tenant-PINNED at their governance compile (mirroring `birthChild`) — the end-user app supplies neither;
+ * the tenant's HomeBirth.viaCoordinator buildBody / their governance fills them. `seedHomeOwner` is INCLUDED
+ * so HomeOwner is seeded and `homeNameBindsOwner` passes (a birth without it would be an invalid, un-owned
+ * home).
+ */
+const HOME_LAW_DOMAIN = "home";
+export const birthHome = directive("birthHome")
+  .creates(HomeOwner) // the birth's law-declared touched type — the child's HomeOwner is what this offer seeds
+  .payload(
+    z.object({
+      /** The identity this home belongs to (a `user:<uid>` subject). The workspace name + seeded homeName are
+       *  both `home-<sha256(owner)>` — self-bound, so you can only birth YOUR OWN home slot. */
+      owner: z.string().min(1),
+      /** The bootstrap framework controller content hash — tenant-pinned at governance compile (the child
+       *  installs it IN-CHAIN as intent 0; the kernel resolves the bytes by hash from the parent's custody). */
+      frameworkHash: z.string().min(1),
+      /** The HOME law package domainHash — tenant-pinned at governance compile (the child's second install). */
+      lawHash: z.string().min(1),
+      /** ISO-8601 birth time, caller-stamped (the timestamp doctrine — the plan reads no clock). */
+      bornAt: z.string().min(1),
+      /** THE DEVICE-SIGNED HOME CERT (JSON `executor::birth_cert::BirthCert`), signed CLIENT-SIDE by the
+       *  owner's device key `S_U` (the SAME key the `signer` relation enrolls). The kernel's birth offer-
+       *  effect VERIFIES this cert's signature against U's enrolled signer pubkey `P_U` AND that its
+       *  `founder == ctx.principal()` (the gate verdict, CAS-as-law) BEFORE accepting it as `links[0]` of
+       *  the travelling chain — the kernel signs nothing (it holds no secret; it only verifies). Optional:
+       *  absent ⇒ the era stays inert for this birth (no warranted home cert is seeded; pre-feature lane). */
+      homeCert: z.string().optional(),
+    }),
+  )
+  .plan((p) => {
+    const founder = p.owner; // the actor for the child's own genesis steps (its self-bound owner subject)
+    const homeName = homeNameOf(p.owner); // workspace name == seeded homeName — derived from the SAME owner
+    const genesisChain = [
+      // THE ORDER-DECLARED LAW INSTALL: two layers, bytes-by-hash (empty package — the kernel resolves them
+      // from the parent's custody when it folds the birth; never the host). Matches buildGenesisChain's shape.
+      { 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: "" },
+      // SEED THE OWNER — the home is born OWNED; the homeNameBindsOwner invariant in the child's law proves
+      // homeName == home-<sha256(owner)> at the child's own gate, so the slot can ONLY be its rightful owner's.
+      // THE GENESIS ORDER IS THE CONTRACT (BREAK 1): the parent's offer-effect APPENDS `seedBirthAttestation`
+      // (the travelling cert) and THEN `seedGenesis` (the WARRANT) after this step — so the warrant lands LAST,
+      // exactly like `enrollSigner → seedGenesis → grantAdmin(SIGNED)`: every genesis seed runs UNSIGNED on a
+      // still-warrant-free prefix (door + signed-author both inert), the warrant lands at the very end, and
+      // ALL post-genesis writes are then signed AND cert-gated. The home is born WARRANTED (its self-id ==
+      // homeName), so `workspace_self_id` resolves and the parent-attested-birth cert door FIRES on every
+      // post-genesis write (without a warrant the door was inert for every home it protects). ERA-SAFE: a
+      // non-AuthProvider / legacy chain never born under THIS recipe carries no warrant + replays byte-identical.
+      { domain: HOME_LAW_DOMAIN, directiveId: "seedHomeOwner", actor: founder, payload: { principal: p.owner, homeName, bornAt: p.bornAt } },
+    ];
+    // THE DECLARED BIRTH EFFECT (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 — takes
+    // the recipe and spawns + self-validates the child through the child's OWN gate (each step self-verifies).
+    birth({ workspace: homeName, genesisChain });
+    return [];
+  })
+  .births(); // BIRTH IS A DECLARED KERNEL PRIMITIVE — emits the `nomosBirthGate` era key; the kernel folds the recipe
+
 /**
  * THE SHARED-WITH-ME INDEX (§5) — one record per cross-custody attestation delivered to this home holon:
  * a signed edge `<asserterWorkspace> : <object> # <relation> @ this-identity`, indexed LOCALLY so the
@@ -181,3 +278,85 @@ export const pruneShare = directive("pruneShare")
 
 /** "Show me everything <asserter> shared with me" — an indexed probe over the local access list. */
 export const sharedByWorkspace = query("sharedByWorkspace").key("asserterWorkspace").returns(SharedWithMe);
+
+// ─────────────────── THE PEER-SOVEREIGN ROOT-OF-TRUST (the BirthAttestation cert chain) ───────────────────
+
+/**
+ * THE BIRTH ATTESTATION (the cert, on-chain for AUDIT). When a parent P births this home via the offer-
+ * effect, the kernel seeds a SIGNED [executor::birth_cert::BirthCert] {child, founder, verified, parentKey,
+ * parentId, epoch} into the home's genesis (it travels with the home's `GenesisWarrant.bornUnder` so a peer
+ * verifies it OFFLINE), AND folds this singleton record so the home's projection surfaces "who attested my
+ * birth, and was my founder verified". `verified` + `founder` are the parent's GATE verdict (captured-port,
+ * CAS-as-law), never the offer payload. A peer's TRUST decision uses the travelling signed chain (the kernel
+ * verify doors); this aggregate is the human-readable mirror.
+ */
+export const BIRTH_ATTESTATION_ID = "birth-attestation:self";
+export const BirthAttestation = aggregate("BirthAttestation", {
+  /** This home's self-id (`home-<sha256(founder)>`) — the cert's `child`. */
+  child: t.string().merge(Lww),
+  /** The founding principal the parent attested (== {@link HomeOwner} `principal`). */
+  founder: t.string().merge(Lww),
+  /** THE PARENT'S GATE VERDICT: was `founder` VERIFIED at the parent's offer gate (an IdP vouched)? */
+  verified: t.string().merge(Lww), // "true"/"false" (string for the Lww scalar projection)
+  /** The parent's workspace self-id (lineage). */
+  parentId: t.string().merge(Lww),
+  /** The parent's enrolled signer PUBLIC KEY (base64) — `K_P`, the cert's signer. */
+  parentKey: t.string().merge(Lww),
+  /** The parent's SignerEpoch at the attestation (informational; the cert is judged at birth-time validity). */
+  epoch: t.int().merge(Lww),
+  /** THE TRAVELLING SIGNED CERT CHAIN (JSON: `executor::birth_cert::BirthCertChain`) — the home's own
+   *  P-signed cert FIRST, then each ancestor's birth-cert up to root. The kernel verify doors parse THIS,
+   *  verify the signature chain to the pinned `K_root` OFFLINE (no cross-ws read), and assert it binds this
+   *  home (`child`==self-id, `founder`==HomeOwner.principal, `verified`). It travels because it folds into
+   *  the home's own genesis (seeded by the parent's offer-effect), so a peer holding only the home has it. */
+  certChain: t.string().merge(Lww),
+});
+
+/** Audit read: this home's birth attestation (who attested it + the verified verdict). */
+export const birthAttestation = query("birthAttestation").key("child").returns(BirthAttestation);
+
+/**
+ * `seedBirthAttestation` — THE GENESIS-DOOR step the parent's offer-effect INJECTS into the home's genesis
+ * chain (the kernel appends it in `run_birth_effect` carrying the assembled + signed cert chain). It folds
+ * the [`BirthAttestation`] singleton so the home's own state carries its travelling cert. A CONTROL-PLANE
+ * write seeded once at birth (the open session lane structurally refuses it by directive id). The values
+ * are the parent's GATE VERDICT (`founder`/`verified` lowered from the captured port — CAS-as-law, never
+ * the offer payload) + the signed chain bytes; the home's verify doors re-derive trust from the chain.
+ */
+export const seedBirthAttestation = directive("seedBirthAttestation")
+  .ensures(BirthAttestation)
+  .payload(
+    z.object({
+      child: z.string().min(1),
+      founder: z.string().min(1),
+      verified: z.string().min(1), // "true"/"false"
+      /** The parent's workspace self-id (lineage). EMPTY for a root-DIRECT birth (root carries no self-id
+       *  binding in the unwarranted lane) — the cert's terminal link is then signed by K_root directly. */
+      parentId: z.string(),
+      parentKey: z.string().min(1), // base64 K_P
+      epoch: z.number().int().nonnegative(),
+      certChain: z.string().min(1), // JSON BirthCertChain
+    }),
+  )
+  .plan((p) => {
+    const h = instance(BirthAttestation, BIRTH_ATTESTATION_ID);
+    return [
+      set(h, "child", p.child),
+      set(h, "founder", p.founder),
+      set(h, "verified", p.verified),
+      set(h, "parentId", p.parentId),
+      set(h, "parentKey", p.parentKey),
+      set(h, "epoch", p.epoch),
+      set(h, "certChain", p.certChain),
+    ];
+  });
+
+/**
+ * THE ERA DECLARATION (the `nomosParentAttestedBirth` USD key). Exporting this sentinel from the home law
+ * tells the kernel's verify doors to VERIFY THE TRAVELLING CERT CHAIN to the pinned `K_root` on every lane
+ * (author / receive / verify_chain) — so a warranted home that self-asserts a verified founder WITHOUT a
+ * parent-signed chain rooting at root is refused (`ParentDidNotAttest` / `CertChainBroken` /
+ * `NotRootedAtRoot`). Era-ruled: a home law that does NOT export this carries no key and replays byte-
+ * identical (the squat-only `homeNameBindsOwner` check still runs; the cert check is simply inert).
+ */
+export const parentAttestedBirth = requireParentAttestedBirth;

package/src/framework/impure_capability.ts

@@ -101,9 +101,13 @@ export type ImpureCapabilityStatus = (typeof IMPURE_CAPABILITY_STATUSES)[number]
  *  - requestedBy    Lww — who obligated the task (provenance). Immutable-after-create.
  *  - requestedAt    Int — epoch-ms the obligation was authored. Immutable-after-create.
  *  - status         Lww enum — `requested` → the reactor flips to a terminal status.
- *  - resultRef      Lww json (OPTIONAL) — the content-addressed RESULT the reactor
- *                   records on completion (a blob ref / download url JSON leaf). Absent
- *                   on a fresh request; absent on failure.
+ *  - resultRef      Lww string (OPTIONAL) — the content-addressed RESULT the reactor
+ *                   records on completion: a blob ref / download url. The receipt-field
+ *                   mechanism (capability.ts) TRANSPORTS typed values through this string
+ *                   (JSON.stringify → JSON.parse into separate typed fields), so the ref
+ *                   itself is honestly a STRING — NOT a `t.json()` leaf (which is now the
+ *                   first-class `Value::Json`, reserved for genuinely-structured fields).
+ *                   Absent on a fresh request; absent on failure.
  *  - failureReason  Lww (OPTIONAL) — set only when the reactor flips to `failed`.
  *  - completedAt    Int (OPTIONAL) — epoch-ms the task reached its terminal state
  *                   (completed OR failed). Absent while `requested`.
@@ -125,7 +129,7 @@ export const IMPURE_CAPABILITY_ENVELOPE = {
   scheduledAt: t.int().merge(Lww),
   deadlineAt: t.int().merge(Lww),
   status: t.enum(IMPURE_CAPABILITY_STATUSES).merge(Lww),
-  resultRef: t.json().merge(Lww).optional(),
+  resultRef: t.string().merge(Lww).optional(),
   failureReason: t.string().merge(Lww).optional(),
   completedAt: t.int().merge(Lww).optional(),
   blockedReason: t.string().merge(Lww).optional(),

package/src/framework/relations.ts

@@ -115,6 +115,20 @@ export interface RelationSubjectLeaf {
   grantedAt: string;
   revokedBy?: string;
   revokedAt?: string;
+  /**
+   * VA-core (signer-provenance) — the SignerEpoch this leaf was authored under. OMITTED when absent so
+   * every pre-VA chain (and every non-signer relation) stays byte-identical: `compact()` strips an
+   * `undefined`. A revoke (`unrelateSubject`) backdates by bumping the SignerEpoch; a key whose
+   * `validFromEpoch` predates the current epoch is stale (the full backdate gate is phase 4).
+   */
+  validFromEpoch?: number;
+  /**
+   * VA-core (signer-provenance) — the IdP/issuer that VOUCHED for the enrolling principal at enroll time
+   * (e.g. the `AuthProvider.issuer`). The kernel's `verify_captured_principal` DERIVES `principal_verified`
+   * from THIS leaf field (provenance, not the wire): an enrollment vouched by a real IdP reads verified on
+   * every lane. OMITTED when absent (legacy / unverified enrollment) so existing chains stay byte-identical.
+   */
+  verifiedVia?: string;
 }
 
 /** Strip undefined keys so the JSON leaf is byte-stable (no dropped-slot `"k":undefined`). */
@@ -137,6 +151,10 @@ interface WriteTupleInput {
   /** ATTRIBUTION (free): who recorded the grant. A plain string OR `ctx.principal().asAttribution()`. */
   grantedBy: string | AttributionPrincipal;
   grantedAt: string;
+  /** VA-core: the SignerEpoch this tuple is authored under (signer relations only; omitted otherwise). */
+  validFromEpoch?: number;
+  /** VA-core: the IdP/issuer that vouched for the enrolling principal (signer relations only; omitted otherwise). */
+  verifiedVia?: string;
 }
 
 /** Lower a tuple write to plan ops. The first op MATERIALIZES the (object, relation)
@@ -165,6 +183,10 @@ function lowerTuple(
     grantedAt: p.grantedAt,
     revokedBy: p.revokedBy,
     revokedAt: p.revokedAt,
+    // VA-core signer-provenance leaf fields — `compact` strips an `undefined`, so a non-signer relation
+    // (these never set) stays byte-identical to a pre-VA leaf (the era rule on the wire shape).
+    validFromEpoch: p.validFromEpoch,
+    verifiedVia: p.verifiedVia,
   });
   const subjectEntry = setEntry(rt, "subjects", subjectRaw, JSON.stringify(leaf));
   return [