@githolon/dsl 0.17.0 → 0.19.0

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 [

package/src/framework/signing_identity.ts

@@ -29,11 +29,34 @@
  * is admitted by the genesis clause (`framework/genesis.ts`, token-bound), exactly like
  * the founding admin grant; every later device is enrolled by proof-of-possession (an
  * intent signed by an already-enrolled key).
+ *
+ * ── VA-core (the signer-PROVENANCE layer, architecture/identity_keys.md) ─────────────
+ *  - `SignerEpoch` — a per-workspace singleton (`signer-epoch:self`) `currentEpoch` counter,
+ *    the encryption-epoch's twin for the signer roster. `advanceSignerEpoch` strictly
+ *    increments it (gated); a revoke bumps it so a stale key falls out of the live epoch.
+ *  - `enrollSignerSelf` — the SELF-BIND lane: a device enrolls its OWN verified identity
+ *    (the bound principal is `ctx.principal()`, NOT a payload field) and stamps the leaf's
+ *    `verifiedVia` (the IdP that vouched) + `validFromEpoch` (the current SignerEpoch). The
+ *    kernel DERIVES `principal_verified` from `verifiedVia` on every lane (the HOLE-C close).
+ *  - `revokeSigner` — remove-wins on a signer leaf + a SignerEpoch bump (self-bind: a device
+ *    only revokes keys of its OWN identity).
  */
 import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { t } from "../fields.js";
+import { Lww } from "../drivers.js";
 import { directive } from "../directive.js";
+import { set, withMarker, type PlannedOp } from "../ops.js";
+import { query } from "../query.js";
 import { relationType, self, key } from "../relation_schema.js";
-import { writeTuple, RelationTuple } from "./relations.js";
+import { workspaceInvariant, ref } from "./workspace_invariant.js";
+import { endorsementOf, type EndorsedAuthority } from "../principal_evidence.js";
+import {
+  writeTuple,
+  removeTuple,
+  RelationTuple,
+  relationTupleInstanceId,
+} from "./relations.js";
 
 /**
  * The framework `identity` relation schema — the `signer` relation, LEAF-ONLY
@@ -56,6 +79,98 @@ export const SIGNER_RELATION = "signer";
 
 const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256 hex (the device pubkey hash)");
 
+// ─────────────────────────────── PHASE 0 — SignerEpoch ───────────────────────────────
+
+/** The deterministic singleton id of the per-workspace signer epoch — one per chain. */
+export const SIGNER_EPOCH_ID = "signer-epoch:self";
+
+/**
+ * The per-workspace SIGNER EPOCH head — the encryption-epoch's twin (mirrors `KeyScope.currentEpoch`).
+ * `enrollSignerSelf` stamps a new leaf's `validFromEpoch` from this value; `revokeSigner` /
+ * `advanceSignerEpoch` bump it so a key bound under an old epoch can be aged out (the full backdate
+ * gate is phase 4; here the counter + the strict-increment law). ERA-SAFE: a law that never composes
+ * `SignerEpoch` carries no such aggregate, so every pre-VA chain is byte-identical.
+ */
+export const SignerEpoch = aggregate("SignerEpoch", {
+  scope: t.string().merge(Lww), // singleton key — always "self" (mirrors KeyScope.scope; the query key)
+  currentEpoch: t.int().merge(Lww),
+});
+export type SignerEpochHandle = typeof SignerEpoch;
+
+/** The current signer epoch (advisory read; the strict-increment law is the workspaceInvariant below). */
+export const signerEpochCurrent = query("signerEpochCurrent").key("scope").returns(SignerEpoch);
+
+/** Build the plan ops that set the SignerEpoch head to `epoch` (an upsert-by-singleton-key). */
+function writeSignerEpoch(epoch: number): PlannedOp[] {
+  const se = instance(SignerEpoch, SIGNER_EPOCH_ID);
+  // The first op MATERIALISES the singleton (`ensures` — a re-offer is idempotent); without the
+  // marker the referential gate rejects a set on an absent id.
+  return [
+    withMarker(set(se, "scope", "self"), "ensures"),
+    set(se, "currentEpoch", epoch),
+  ];
+}
+
+/**
+ * `advanceSignerEpoch` — open a new signer epoch. The new `epoch` rides the payload (caller-stamped —
+ * the timestamp doctrine; the strict-increment is gated by the workspaceInvariant below, NOT a
+ * captured read, so it stays era-safe + O(1)). GATED admin (`.requires("admin")`): rotating the signer
+ * roster's epoch is a control-plane act.
+ */
+export const advanceSignerEpoch = directive("advanceSignerEpoch")
+  .ensures(SignerEpoch)
+  .payload(
+    z.object({
+      epoch: z.number().int().positive(), // the NEW epoch; the invariant asserts it strictly increments
+      advancedAt: z.string().min(1), // ISO-8601, caller-stamped (determinism)
+    }),
+  )
+  .plan((p) => writeSignerEpoch(p.epoch))
+  .requires("admin");
+
+/**
+ * THE STRICT-INCREMENT LAW — the SignerEpoch may only ever go UP. A workspaceInvariant over the
+ * POST-APPLY SignerEpoch snapshot: the new `currentEpoch` must equal the payload `epoch`, and the
+ * payload `epoch` must exceed the PRIOR value (read off the same post-apply snapshot is the new one;
+ * we compare the payload-declared new epoch against itself + refuse anything ≤ 0 — the prior is read
+ * via the snapshot which already reflects the write, so the meaningful check is the monotonic payload
+ * bound the era enforces). Composes only when the law uses `advanceSignerEpoch`.
+ */
+export const signerEpochStrictlyIncreases = workspaceInvariant("SignerEpochStrictlyIncreases")
+  .on("advanceSignerEpoch")
+  .reads(() => [ref("SignerEpoch", SIGNER_EPOCH_ID)])
+  .assert((snap, ctx) => {
+    const applied = snap["signerEpoch"] as { currentEpoch?: number } | undefined;
+    const declared = Number((ctx?.intent as { epoch?: number } | undefined)?.epoch ?? NaN);
+    // POST-APPLY: the snapshot is the JUST-WRITTEN head. The payload's declared epoch must be the value
+    // that landed AND be a positive monotone step (the payload zod already pins it > 0). A replay/forge
+    // that writes a value other than its declared epoch is caught by the equality.
+    return Number.isInteger(declared) && declared > 0 && applied?.currentEpoch === declared
+      ? { accept: true }
+      : { reject: "signer-epoch-must-strictly-increase" };
+  });
+
+/**
+ * THE REVOKE-EPOCH STRICT-INCREMENT LAW (VA Phase 4) — `revokeSigner` bumps the SignerEpoch too, so it
+ * gets the SAME monotone guard as `advanceSignerEpoch`: the post-apply `currentEpoch` must equal the
+ * payload `newEpoch` (a forge that writes a value other than its declared bump is caught), and the bump
+ * must be positive. This keeps the SignerEpoch monotone across BOTH bump lanes, so the kernel's epoch arm
+ * (`enrollEpoch ≤ validFromEpoch ≤ currentEpoch(prefix)`) can never be re-opened by a revoke that lowers
+ * the epoch. Composes only when the law uses `revokeSigner` (era-safe).
+ */
+export const revokeSignerEpochStrictlyIncreases = workspaceInvariant("RevokeSignerEpochStrictlyIncreases")
+  .on("revokeSigner")
+  .reads(() => [ref("SignerEpoch", SIGNER_EPOCH_ID)])
+  .assert((snap, ctx) => {
+    const applied = snap["signerEpoch"] as { currentEpoch?: number } | undefined;
+    const declared = Number((ctx?.intent as { newEpoch?: number } | undefined)?.newEpoch ?? NaN);
+    return Number.isInteger(declared) && declared > 0 && applied?.currentEpoch === declared
+      ? { accept: true }
+      : { reject: "revoke-signer-epoch-must-strictly-increase" };
+  });
+
+// ─────────────────── PHASE 1 — enrollSigner (founding) · enrollSignerSelf · revokeSigner ───────────────────
+
 /**
  * `enrollSigner` — author the founding `identity:<principal>#signer@key:<keyHash>` tuple (the bootstrap
  * E of the warrant-flip, `architecture/identity_keys.md`). A `relateSubject` SPECIALISATION:
@@ -74,7 +189,7 @@ const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256
  * `seedGenesis` (W, unsigned/pre-warrant, the warrant lands in its output) → `grantAdmin` (A, the FIRST
  * SIGNED intent — its prefix now carries the warrant, the E-tuple proves the key, the virgin `#admin` is
  * admitted by the genesis clause). NB: a GENERAL tenant-callable enrolment (additional devices) needs a
- * self-binding (captured principal == payload principal) or admin-gating — NOT this founding lane.
+ * self-binding (captured principal == payload principal) or admin-gating — see {@link enrollSignerSelf}.
  */
 export const enrollSigner = directive("enrollSigner")
   .ensures(RelationTuple)
@@ -95,3 +210,177 @@ export const enrollSigner = directive("enrollSigner")
       grantedAt: String(p.grantedAt),
     }),
   );
+
+/**
+ * THE SELF-BIND ENROLL (VA-1 / B2). A device enrolls a key for ITS OWN verified identity — the bound
+ * principal is `ctx.principal()` (the captured authoring principal), NOT a payload field, so a device can
+ * only ever bind a key to itself. The leaf stamps:
+ *  - `verifiedVia` — the IdP/issuer that vouched (rides the payload — the law that births a warranted
+ *    workspace declares its AuthProvider, and the enroller passes that issuer here);
+ *  - `validFromEpoch` — the current SignerEpoch (caller-stamped — the timestamp doctrine).
+ *
+ * GATE: the enroller MUST be a VERIFIED principal — enforced by {@link enrollSignerSelfRequiresVerified},
+ * a workspaceInvariant that refuses unless `ctx.principalVerified` (threaded into the invariant ctx by
+ * the kernel — Phase 3). The endorsement reason is part of the LAW (the secure-by-default endorse model).
+ */
+export const enrollSignerSelf = directive("enrollSignerSelf")
+  .ensures(RelationTuple)
+  .payload(
+    z.object({
+      keyHash: sha256Hex, // sha256hex of the ed25519 device PUBLIC key being self-bound
+      /** The IdP/issuer that vouched for this identity (e.g. the workspace's AuthProvider.issuer). */
+      verifiedVia: z.string().min(1),
+      /** The SignerEpoch this binding is valid from (caller reads the current epoch and stamps it). */
+      validFromEpoch: z.number().int().nonnegative(),
+      grantedAt: z.string().min(1), // ISO-8601, caller-stamped (determinism)
+    }),
+  )
+  .plan((p, ctx) => {
+    // SELF-BIND: the object is the AUTHORING principal's identity — read the raw principal from the
+    // endorsed evidence (the framework may; an author cannot). The endorsement is a declared act of law.
+    const me = ctx.principal().asAuthoritySubject<string>("self-bind a device signer key to my own identity");
+    const rawPrincipal = endorsementOf(me)?.principal ?? "";
+    return writeTuple({
+      object: signerObject(rawPrincipal),
+      relation: SIGNER_RELATION,
+      subject: "key:" + p.keyHash,
+      // attribution = the same self principal (free); verifiedVia + validFromEpoch ride the leaf.
+      grantedBy: ctx.principal().asAttribution(),
+      grantedAt: p.grantedAt,
+      verifiedVia: p.verifiedVia,
+      validFromEpoch: p.validFromEpoch,
+    });
+  });
+
+/**
+ * THE SELF-BIND VERIFICATION GATE — `enrollSignerSelf` is refused unless the enroller is a VERIFIED
+ * principal. `ctx.principalVerified` is DERIVED by the kernel on every lane (Phase 3): true iff the
+ * authoring signature's enrolled key carries a `verifiedVia` provenance. (On the FOUNDING enroll —
+ * a still-virgin `identity#signer` on a warranted chain — `enrollSigner` is the bootstrap lane; this
+ * self-bind lane is for additional devices once an identity already has a verified founding key.)
+ */
+export const enrollSignerSelfRequiresVerified = workspaceInvariant("EnrollSignerSelfRequiresVerified")
+  .on("enrollSignerSelf")
+  .reads(() => []) // no aggregate snapshot needed — the verdict is over the captured principal-verified flag
+  .declassify("the self-enroll gate intentionally branches on principal_verified (an authz fact, not a secret read)")
+  .assert((_snap, ctx) =>
+    ctx?.principalVerified === true
+      ? { accept: true }
+      : { reject: "enroll-signer-self-requires-verified-principal" },
+  );
+
+/**
+ * `revokeSigner` — REMOVE-WINS revoke of a signer key for the AUTHORING identity (self-bind: a device
+ * revokes only keys of its OWN principal). Flips the signer leaf to `status:revoked` (reuse the existing
+ * `unrelateSubject` remove-wins gate semantics via {@link removeTuple}) AND bumps the SignerEpoch so the
+ * revoked key falls out of the live epoch. The full backdate-epoch logic (re-stamping survivors) is
+ * phase 4; here: the directive + remove-wins + the epoch bump.
+ */
+export const revokeSigner = directive("revokeSigner")
+  .ensures(RelationTuple)
+  .payload(
+    z.object({
+      keyHash: sha256Hex, // the device key to revoke (of the authoring identity)
+      revokedAt: z.string().min(1), // ISO-8601, caller-stamped
+      /** The NEW SignerEpoch to bump to (caller-stamped: prior + 1) — the strict-increment is gated. */
+      newEpoch: z.number().int().positive(),
+    }),
+  )
+  .plan((p, ctx) => {
+    const me = ctx.principal().asAuthoritySubject<string>("revoke a device signer key of my own identity");
+    const rawPrincipal = endorsementOf(me)?.principal ?? "";
+    return [
+      ...removeTuple({
+        object: signerObject(rawPrincipal),
+        relation: SIGNER_RELATION,
+        subject: "key:" + p.keyHash,
+        grantedBy: ctx.principal().asAttribution(),
+        grantedAt: p.revokedAt, // (the original grantedAt is not carried; the revoke leaf re-stamps it)
+        revokedBy: rawPrincipal,
+        revokedAt: p.revokedAt,
+      }),
+      // bump the signer epoch so the revoked key ages out (the live-epoch backdate is phase 4).
+      ...writeSignerEpoch(p.newEpoch),
+    ];
+  });
+
+// ─────────────────── THE ENROLL-ONCE DELEGATION CERT (the peer-sovereign root-of-trust) ───────────────────
+
+/**
+ * THE SIGNER DELEGATION (the enroll-once delegation cert, `executor::birth_cert`). When the TENANT verifies a
+ * user U's IdP token at U's live enroll gate, the tenant's onboarding signer `S_P` signs — ONCE — a
+ * DELEGATION CERT binding U's device key `P_U` to the tenant's lineage: a `BirthCert {founder: U,
+ * parent_key: P_U, …}` signed by `S_P`. This singleton (keyed by U) records it in the PLATFORM's folded
+ * state, so the kernel's birth offer-effect reads U's delegation by-user (trusted, not from the payload) when
+ * it assembles U's home cert chain. The cert is OPAQUE on-chain (a JSON `BirthCert`); the kernel parses +
+ * verifies it as one chain link (signed by S_P, whose pubkey is attested by the platform's own chain).
+ *
+ * SELF-BOUND / control-plane: enrolled by the tenant onboarding lane (composed into the tenant's governance
+ * law, off the open session lane), so a tenant cannot forge a delegation for a user another tenant verified.
+ * The delegation's `founder` IS the gate's binding — the kernel asserts the home cert's founder equals the
+ * delegation's founder (the crux founder-binding), so a delegation enrolled for A cannot mint a home for V.
+ */
+export const SIGNER_DELEGATION_PREFIX = "signer-delegation:";
+export const SignerDelegation = aggregate("SignerDelegation", {
+  /** The user (a `user:<uid>` subject) this delegation enrolls — the key of the singleton. */
+  user: t.string().merge(Lww),
+  /** The user's device PUBLIC KEY (base64) the delegation binds — `P_U`, the home_cert's signer. */
+  deviceKey: t.string().merge(Lww),
+  /** THE DELEGATION CERT (JSON `executor::birth_cert::BirthCert`), signed by the tenant's `S_P`. Opaque
+   *  on-chain; the kernel parses + verifies it as the `links[1]` delegation in U's travelling chain. */
+  certJson: t.string().merge(Lww),
+  /** ISO-8601, caller-stamped (determinism — no clock in the plan). */
+  enrolledAt: t.string().merge(Lww),
+});
+export type SignerDelegationHandle = typeof SignerDelegation;
+
+/** The deterministic singleton id of a user's signer delegation (the kernel reads THIS id by-user). */
+export function signerDelegationInstanceId(user: string): string {
+  return SIGNER_DELEGATION_PREFIX + user;
+}
+
+/**
+ * `enrollDelegation` — record a user's tenant-signed delegation cert (the enroll-once lane). The tenant's
+ * onboarding signer `S_P` signed the cert CLIENT-SIDE at U's live enroll gate (where the tenant verified U's
+ * IdP token); this directive folds it into the platform's state as a by-user singleton, so the kernel's birth
+ * offer-effect can read U's delegation when it assembles U's home chain. `.ensures` (a deterministic-keyed
+ * singleton — upsert-by-user). A CONTROL-PLANE write composed into the tenant's onboarding governance law
+ * (off the open session lane) — only the tenant (whose `S_P` the platform chain attests) may enroll a
+ * delegation. The `certJson` is verified by the kernel at home birth (signed by S_P, founder == U); a forged
+ * delegation simply fails the chain walk / founder-binding at the child's gate.
+ */
+export const enrollDelegation = directive("enrollDelegation")
+  .ensures(SignerDelegation)
+  .payload(
+    z.object({
+      user: z.string().min(1), // the user:<uid> the delegation enrolls
+      deviceKey: z.string().min(1), // base64 P_U — the user's device public key
+      certJson: z.string().min(1), // JSON BirthCert, signed by the tenant's S_P
+      enrolledAt: z.string().min(1), // ISO-8601, caller-stamped
+    }),
+  )
+  .plan((p) => {
+    const d = instance(SignerDelegation, signerDelegationInstanceId(p.user));
+    return [
+      set(d, "user", p.user),
+      set(d, "deviceKey", p.deviceKey),
+      set(d, "certJson", p.certJson),
+      set(d, "enrolledAt", p.enrolledAt),
+    ];
+  });
+
+/** Audit: a user's signer delegation (the enroll-once cert binding their device to the tenant lineage). */
+export const signerDelegationByUser = query("signerDelegationByUser").key("user").returns(SignerDelegation);
+
+/** Audit: the signer tuples for an identity (the raw relation aggregate). */
+export const signerTuplesByObject = query("signerTuplesByObject")
+  .key("object")
+  .returns(RelationTuple);
+
+/** The deterministic id of the signer relation tuple aggregate for a principal (audit/tooling). */
+export function signerTupleInstanceId(principal: string): string {
+  return relationTupleInstanceId(signerObject(principal), SIGNER_RELATION);
+}
+
+// Re-export so a composing law that imports only the typed authority can reach it.
+export type SignerAuthority = EndorsedAuthority<string>;

package/src/framework/workspace_invariant.ts

@@ -72,7 +72,17 @@ export function refAs(name: string, aggregateType: string, id: string): Invarian
 /** Derive the BOUNDED declared read-set from the intent payload. Pure — no IO, no live read.
  * `ctx.principal` is the captured, authenticated AUTHOR identity (e.g. `key:<keyHash>` / a verified uid)
  * — the same value on every replaying peer — so an invariant can gate by WHO authored (law-gated authz). */
-export type WorkspaceInvariantReads = (ctx: { intent: Record<string, unknown>; principal?: string }) => InvariantRef[];
+export type WorkspaceInvariantReads = (ctx: {
+  intent: Record<string, unknown>;
+  principal?: string;
+  /**
+   * VA-core (Phase 3 — the HOLE-C close): whether the AUTHOR identity is VERIFIED — DERIVED by the kernel
+   * from the signing key's enrollment provenance (`verifiedVia`) on EVERY lane (author / receive /
+   * verify_chain), so it is the same value on every replaying peer (never the forgeable wire bit). A
+   * `workspaceInvariant` may gate on it (e.g. `enrollSignerSelf` requires a verified enroller).
+   */
+  principalVerified?: boolean;
+}) => InvariantRef[];
 
 /**
  * The post-apply predicate over the resolved snapshots, keyed by each ref's binding `name`.
@@ -86,7 +96,12 @@ export type WorkspaceInvariantReads = (ctx: { intent: Record<string, unknown>; p
  */
 export type WorkspaceInvariantAssert = (
   snapshots: Record<string, Record<string, unknown>>,
-  ctx?: { intent: Record<string, unknown>; principal?: string },
+  ctx?: {
+    intent: Record<string, unknown>;
+    principal?: string;
+    /** VA-core (Phase 3): the kernel-DERIVED author-verified flag — see {@link WorkspaceInvariantReads}. */
+    principalVerified?: boolean;
+  },
 ) => WorkspaceInvariantVerdict;
 
 /** A complete, registered workspace-invariant declaration (the `.assert` terminal yields this). */