@cotal-ai/auth 0.12.0 → 0.13.0

package/dist/credential-ledger.js

@@ -0,0 +1,732 @@
+import { EpEnvelopeError, assertLifecycleToken, endpointToken, parsePrincipalKey, isPrincipalOwnerToken, isCasLoss as isRawCasLoss, } from "@cotal-ai/core";
+import { registryStores, registryScanner, readLifecycleHeadForOperation, readUidReservation, observeGate, freezeGate, reopenGate, advanceEpochWithinTakeover, } from "./lifecycle-registry.js";
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+const isRec = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const uint = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+// ---- key grammar ------------------------------------------------------------------------------
+/** One KV key segment: no dots (a segment separator), no wildcards, KV-safe. */
+const KEY_SEGMENT = /^[A-Za-z0-9_-]+$/;
+function assertKeySegment(v, what) {
+    if (typeof v !== "string" || !KEY_SEGMENT.test(v))
+        throw new EpEnvelopeError("failed-precondition", `${what} ${JSON.stringify(v)} is not a KV-safe key segment (SPEC 13.1)`);
+    return v;
+}
+/** A credential id: one or more KV-safe segments (dots allowed BETWEEN segments — the session
+ *  families use `<sessionId>.c` / `<sessionId>.s` — but never wildcards or empty segments). */
+function assertCredentialIdTail(v, what) {
+    if (typeof v !== "string" || v.length === 0 || v.length > 256 || !v.split(".").every((s) => KEY_SEGMENT.test(s)))
+        throw new EpEnvelopeError("failed-precondition", `${what} ${JSON.stringify(v)} is not a bounded dotted credential id (SPEC 13.1)`);
+    return v;
+}
+/** A holder principal `<owner>.<actor>` with a REAL owner (derived `u_…` or the dev owner) —
+ *  eviction is BY PRINCIPAL, so a row that cannot name an evictable principal never ledgers. */
+function assertHolderPrincipal(v, what) {
+    const p = typeof v === "string" ? parsePrincipalKey(v) : null;
+    if (!p || !isPrincipalOwnerToken(p.owner))
+        throw new EpEnvelopeError("failed-precondition", `${what} ${JSON.stringify(v)} is not a principal dot-form the barrier can evict (SPEC 13.1)`);
+    return v;
+}
+export const SOURCE_ROOT = "root";
+/** Validate ONE sourceChain member — `root`, `handle.<issuerKeyId>.<id>`, or
+ *  `session.<sessionId>` (SPEC 13.1) — and return its parsed shape. */
+export function parseSourceMember(member) {
+    if (member === SOURCE_ROOT)
+        return { kind: "root" };
+    if (typeof member === "string" && member.startsWith("handle.")) {
+        const rest = member.slice("handle.".length).split(".");
+        if (rest.length === 2 && KEY_SEGMENT.test(rest[0]) && KEY_SEGMENT.test(rest[1]))
+            return { kind: "handle", issuerKeyId: rest[0], id: rest[1] };
+    }
+    if (typeof member === "string" && member.startsWith("session.")) {
+        const sid = member.slice("session.".length);
+        if (KEY_SEGMENT.test(sid))
+            return { kind: "session", sessionId: sid };
+    }
+    throw new EpEnvelopeError("failed-precondition", `sourceChain member ${JSON.stringify(member)} is not root | handle.<issuerKeyId>.<id> | session.<sessionId> (SPEC 13.1)`);
+}
+function assertSourceChain(v, what) {
+    if (!Array.isArray(v) || v.length === 0)
+        throw new EpEnvelopeError("failed-precondition", `${what} must be a non-empty sourceChain (SPEC 13.1: the FULL verified lineage, never absent)`);
+    for (const m of v)
+        parseSourceMember(m);
+    return v;
+}
+/** The agent-family ledger key `cred.<lifecycleUid>.<credentialId>`. */
+export function credRowKey(lifecycleUid, credentialId) {
+    return `cred.${assertLifecycleToken(lifecycleUid)}.${assertCredentialIdTail(credentialId, "credentialId")}`;
+}
+/** The endpoint-family ledger key `epcred.<endpoint>.<instanceId>.<credentialId>` (disjoint by
+ *  explicit prefix, never arity, SPEC 13.1). */
+export function epcredRowKey(endpoint, instanceId, credentialId) {
+    return `epcred.${endpointToken(endpoint)}.${assertLifecycleToken(instanceId, "instanceId")}.${assertCredentialIdTail(credentialId, "credentialId")}`;
+}
+/** The per-ancestor lineage index key `bysrc.<issuerKeyId>.<id>.<lifecycleUid>.<credentialId>`. */
+export function bysrcKey(issuerKeyId, id, lifecycleUid, credentialId) {
+    return `bysrc.${assertKeySegment(issuerKeyId, "issuerKeyId")}.${assertKeySegment(id, "handle id")}.${assertLifecycleToken(lifecycleUid)}.${assertCredentialIdTail(credentialId, "credentialId")}`;
+}
+/** The per-handle source gate key `srcgate.<issuerKeyId>.<id>`. */
+export function srcgateKey(issuerKeyId, id) {
+    return `srcgate.${assertKeySegment(issuerKeyId, "issuerKeyId")}.${assertKeySegment(id, "handle id")}`;
+}
+/** A takeover/registration operation's durable intent key `stage.<opId>` (the `stage.<opId>.`
+ *  staging family root — NEVER under a ledger prefix a barrier enumerates, SPEC 13.1). */
+export function stageIntentKey(opId) {
+    return `stage.${assertLifecycleToken(opId)}`;
+}
+/** Parse + validate a ledger row at its consuming boundary — closed schema, and the embedded
+ *  identity MUST rebuild the row's own key, so a key-mismatched or family-swapped poison row
+ *  never authorizes (SPEC 13.1/13.3). */
+export function parseLedgerRow(raw, key) {
+    let o;
+    try {
+        o = JSON.parse(dec.decode(raw));
+    }
+    catch {
+        throw new EpEnvelopeError("internal", `the credential-ledger row ${key} is not JSON; garbled trusted-path state never authorizes (SPEC 13.1)`);
+    }
+    if (!isRec(o))
+        throw new EpEnvelopeError("internal", `the credential-ledger row ${key} is not an object`);
+    const allowed = new Set(["credentialId", "holderPrincipal", "lifecycleUid", "endpoint", "sourceChain", "state", "exp"]);
+    for (const k of Object.keys(o))
+        if (!allowed.has(k))
+            throw new EpEnvelopeError("internal", `the credential-ledger row ${key} carries the unknown field "${k}" (closed schema, SPEC 13.1)`);
+    if (typeof o.credentialId !== "string" || typeof o.holderPrincipal !== "string" || typeof o.lifecycleUid !== "string" ||
+        (o.state !== "active" && o.state !== "revoked") || !uint(o.exp))
+        throw new EpEnvelopeError("internal", `the credential-ledger row ${key} does not validate (id/holder/uid/state/exp); a garbled row never authorizes (SPEC 13.1)`);
+    try {
+        assertSourceChain(o.sourceChain, `row ${key} sourceChain`);
+        assertCredentialIdTail(o.credentialId, `row ${key} credentialId`);
+        // holderPrincipal is ALWAYS a CONNZ-attributable principal, in BOTH families (the barrier
+        // KICKs it; the endpoint name is NOT attributable and never sits here).
+        assertHolderPrincipal(o.holderPrincipal, `row ${key} holderPrincipal`);
+    }
+    catch (e) {
+        throw new EpEnvelopeError("internal", `the credential-ledger row ${key} carries a malformed lineage/id/holder: ${e.message}`);
+    }
+    // KEY BINDING, per family: the row's own identity must rebuild its key exactly. The endpoint
+    // family keys on its own `endpoint` field (NOT holderPrincipal), so the key identity and the
+    // eviction target stay disjoint.
+    let expected;
+    if (key.startsWith("cred.")) {
+        if (o.endpoint !== undefined)
+            throw new EpEnvelopeError("internal", `the agent-family row ${key} carries an endpoint field (that belongs to the epcred family, SPEC 13.1)`);
+        expected = credRowKey(o.lifecycleUid, o.credentialId);
+    }
+    else if (key.startsWith("epcred.")) {
+        if (typeof o.endpoint !== "string" || o.endpoint.length === 0)
+            throw new EpEnvelopeError("internal", `the endpoint-family row ${key} is missing its endpoint field (it forms the key, SPEC 13.1)`);
+        try {
+            expected = epcredRowKey(o.endpoint, o.lifecycleUid, o.credentialId);
+        }
+        catch (e) {
+            throw new EpEnvelopeError("internal", `the credential-ledger row ${key} does not validate for the endpoint family: ${e.message}`);
+        }
+    }
+    else {
+        throw new EpEnvelopeError("internal", `the credential-ledger row key ${key} is under neither ledger family prefix (SPEC 13.1)`);
+    }
+    if (expected !== key)
+        throw new EpEnvelopeError("internal", `the credential-ledger row at ${key} embeds an identity that rebuilds ${expected}; a key-mismatched row never authorizes (SPEC 13.1)`);
+    return o;
+}
+/** Create-only write of a ledger/index row with the BYTE-IDENTICAL retry (a crashed writer's
+ *  retry of its OWN deterministic row proceeds; foreign content under a staged name refuses —
+ *  a name never silently re-binds, SPEC 13.6 discipline). PACKAGE-INTERNAL: the session
+ *  adapter writes its `epcred.` rows through this. */
+export async function createRowByteIdempotent(kv, key, value) {
+    const bytes = JSON.stringify(value);
+    try {
+        await kv.create(key, enc.encode(bytes));
+    }
+    catch (e) {
+        if (!isRawCasLoss(e))
+            throw new EpEnvelopeError("unavailable", `creating the row ${key} is ambiguous; the mint fails closed (SPEC 13.1): ${e?.message ?? String(e)}`);
+        const existing = await kv.get(key);
+        if (!existing || existing.operation !== "PUT" || dec.decode(existing.value) !== bytes)
+            throw new EpEnvelopeError("conflict", `the row ${key} exists with FOREIGN content; a staged name never silently re-binds (SPEC 13.1)`);
+    }
+}
+/** Idempotent monotonic revocation mark on a ledger row (revision-pinned CAS; a lost pin
+ *  re-reads — terminal-now returns, still-active retries). An ABSENT key refuses: the ledger
+ *  is never-deleted, so "revoke a row that does not exist" is a caller bug or corruption,
+ *  never a silent success. PACKAGE-INTERNAL (the session adapter routes through this too). */
+export async function markLedgerRowRevoked(kv, key) {
+    for (let attempt = 0; attempt < 4; attempt++) {
+        const entry = await kv.get(key);
+        if (!entry)
+            throw new EpEnvelopeError("failed-precondition", `no credential-ledger row exists at ${key}; a revocation mark needs its row (SPEC 13.1)`);
+        if (entry.operation !== "PUT")
+            throw new EpEnvelopeError("failed-precondition", `the credential-ledger row ${key} carries a ${entry.operation} marker; ledger rows are never deleted (corruption, not absence, SPEC 13.12)`);
+        const row = parseLedgerRow(entry.value, key);
+        if (row.state === "revoked")
+            return "already-revoked";
+        try {
+            await kv.update(key, enc.encode(JSON.stringify({ ...row, state: "revoked" })), entry.revision);
+            return "revoked";
+        }
+        catch (e) {
+            if (isRawCasLoss(e))
+                continue;
+            throw new EpEnvelopeError("unavailable", `revoking the row ${key} is ambiguous; the barrier retries (SPEC 13.1): ${e?.message ?? String(e)}`);
+        }
+    }
+    throw new EpEnvelopeError("unavailable", `revoking the row ${key} kept losing its pin; retry the barrier (SPEC 13.1)`);
+}
+function parseSourceGate(raw, key, issuerKeyId, id) {
+    let o;
+    try {
+        o = JSON.parse(dec.decode(raw));
+    }
+    catch {
+        throw new EpEnvelopeError("internal", `the source gate ${key} is not JSON (SPEC 13.1)`);
+    }
+    if (!isRec(o))
+        throw new EpEnvelopeError("internal", `the source gate ${key} is not an object`);
+    for (const k of Object.keys(o))
+        if (k !== "issuerKeyId" && k !== "id" && k !== "state")
+            throw new EpEnvelopeError("internal", `the source gate ${key} carries the unknown field "${k}" (closed schema, SPEC 13.1)`);
+    if (o.issuerKeyId !== issuerKeyId || o.id !== id || (o.state !== "open" && o.state !== "frozen"))
+        throw new EpEnvelopeError("internal", `the source gate ${key} does not validate (key binding/state); a garbled gate never authorizes (SPEC 13.1)`);
+    return o;
+}
+/** Observe a source gate (the candidate read feeding a pinned CAS/touch). A DEL/PURGE marker
+ *  refuses loudly — a gate is never deleted. */
+export async function observeSourceGate(reg, args) {
+    const { authKv } = registryStores(reg);
+    const key = srcgateKey(args.issuerKeyId, args.id);
+    const entry = await authKv.get(key);
+    if (!entry)
+        return undefined;
+    if (entry.operation !== "PUT")
+        throw new EpEnvelopeError("failed-precondition", `the source gate ${key} carries a ${entry.operation} marker; a gate is never deleted (corruption, not absence, SPEC 13.12)`);
+    return { row: parseSourceGate(entry.value, key, args.issuerKeyId, args.id), revision: entry.revision };
+}
+/** Create a handle's source gate OPEN (at the handle's own provisioning). Create-only:
+ *  idempotent for the identical row; anything else (including a deletion marker) conflicts. */
+export async function createSourceGateOpen(reg, args) {
+    const { authKv } = registryStores(reg);
+    const row = { issuerKeyId: assertKeySegment(args.issuerKeyId, "issuerKeyId"), id: assertKeySegment(args.id, "handle id"), state: "open" };
+    await createRowByteIdempotent(authKv, srcgateKey(args.issuerKeyId, args.id), row);
+}
+/** CAS a source gate `open → frozen` at the observed revision — the handle-revocation fence
+ *  (SPEC 13.1: freeze BEFORE enumerating `bysrc.`; an in-flight redemption either finished
+ *  before the freeze, so its rows are in the enumeration, or loses its pinned touch). */
+export async function freezeSourceGate(reg, args) {
+    const { authKv } = registryStores(reg);
+    const key = srcgateKey(args.issuerKeyId, args.id);
+    const row = { issuerKeyId: args.issuerKeyId, id: args.id, state: "frozen" };
+    try {
+        await authKv.update(key, enc.encode(JSON.stringify(row)), args.revision);
+    }
+    catch (e) {
+        if (isRawCasLoss(e))
+            throw new EpEnvelopeError("conflict", `the source-gate freeze for ${key} lost (expected revision ${args.revision}); re-observe and re-decide (SPEC 13.1)`);
+        throw e;
+    }
+}
+function parseBysrcRow(raw, key) {
+    let o;
+    try {
+        o = JSON.parse(dec.decode(raw));
+    }
+    catch {
+        throw new EpEnvelopeError("internal", `the lineage index row ${key} is not JSON (SPEC 13.1)`);
+    }
+    if (!isRec(o) || Object.keys(o).some((k) => k !== "ref") || typeof o.ref !== "string" || !(o.ref.startsWith("cred.") || o.ref.startsWith("epcred.")))
+        throw new EpEnvelopeError("internal", `the lineage index row ${key} does not validate (a bare { ref: <ledger row key> }, SPEC 13.1)`);
+    // KEY BINDING: the index key's own `<lifecycleUid>.<credentialId>` tail must be the tail of
+    // the row it names, so a poisoned index can never walk revocation onto a DIFFERENT credential.
+    const tail = key.split(".").slice(3).join(".");
+    if (!(o.ref === `cred.${tail}` || (o.ref.startsWith("epcred.") && o.ref.endsWith(`.${tail}`))))
+        throw new EpEnvelopeError("internal", `the lineage index row ${key} names ${o.ref}, which does not carry the index's own identity tail; a mismatched index never authorizes (SPEC 13.1)`);
+    return o;
+}
+const STAGED_MINTS = new WeakMap();
+/**
+ * Stage an AGENT-family mint (SPEC 13.1 mint protocol, steps observe + write-rows): observe
+ * the lifecycle issuance gate (must exist and be `open` — a frozen gate is a barrier in
+ * flight, a retired one is terminal) and EVERY presented handle's source gate (must exist and
+ * be `open`), recording each revision; then create the ledger row (`state: "active"` — the
+ * row is authority only after finalize releases, and the barrier enumerates it either way)
+ * and one `bysrc.` index row per handle chain member. Returns the staged coordinates for
+ * {@link finalizeAgentMint}. Nothing is released here.
+ */
+export async function stageAgentMint(reg, args) {
+    const { authKv } = registryStores(reg);
+    assertHolderPrincipal(args.holderPrincipal, "holderPrincipal");
+    if (!uint(args.exp))
+        throw new EpEnvelopeError("failed-precondition", `exp ${JSON.stringify(args.exp)} is not a non-negative safe integer (SPEC 13.1)`);
+    const chain = assertSourceChain(args.sourceChain, "sourceChain");
+    const rowKey = credRowKey(args.lifecycleUid, args.credentialId);
+    // 0. BIND holderPrincipal to the UID's reserved identity (SPEC 13.1: the barrier evicts this
+    // principal, so a trusted caller cannot ledger a row that names a FOREIGN principal to KICK).
+    const reservation = await readUidReservation(reg, args.lifecycleUid);
+    if (reservation === undefined)
+        throw new EpEnvelopeError("permission-denied", `lifecycle ${args.lifecycleUid} has no uid reservation; a mint binds its holderPrincipal to the reserved identity (SPEC 13.1)`);
+    const boundPrincipal = `${reservation.owner}.${reservation.actor}`;
+    if (args.holderPrincipal !== boundPrincipal)
+        throw new EpEnvelopeError("permission-denied", `the mint's holderPrincipal "${args.holderPrincipal}" is not the reserved identity "${boundPrincipal}" for uid ${args.lifecycleUid}; the eviction target is derived from the reservation, never free-standing (SPEC 13.1)`);
+    // 1. Observe the lifecycle gate: only an OPEN gate mints.
+    const gate = await observeGate(reg, args.lifecycleUid);
+    if (gate === undefined)
+        throw new EpEnvelopeError("permission-denied", `lifecycle ${args.lifecycleUid} has no issuance gate; a never-activated or foreign lifecycle mints nothing (SPEC 13.1)`);
+    if (gate.row.state !== "open")
+        throw new EpEnvelopeError("permission-denied", `the issuance gate for ${args.lifecycleUid} is "${gate.row.state}"; only an open gate mints (a frozen gate is a barrier in flight, a retired one is terminal, SPEC 13.1)`);
+    // 2. Observe EVERY presented handle's source gate (SPEC 13.1: the same fence per issuing handle).
+    const pins = [{ key: `gate.${args.lifecycleUid}`, revision: gate.revision }];
+    const bysrcKeys = [];
+    for (const member of chain) {
+        const parsed = parseSourceMember(member);
+        if (parsed.kind !== "handle")
+            continue;
+        const src = await observeSourceGate(reg, parsed);
+        if (src === undefined)
+            throw new EpEnvelopeError("permission-denied", `the presented handle ${parsed.issuerKeyId}.${parsed.id} has no source gate; an unprovisioned or revoked-and-collapsed handle mints nothing (SPEC 13.1)`);
+        if (src.row.state !== "open")
+            throw new EpEnvelopeError("permission-denied", `the source gate for handle ${parsed.issuerKeyId}.${parsed.id} is frozen; a revoked handle mints nothing (SPEC 13.1)`);
+        pins.push({ key: srcgateKey(parsed.issuerKeyId, parsed.id), revision: src.revision });
+        bysrcKeys.push(bysrcKey(parsed.issuerKeyId, parsed.id, args.lifecycleUid, args.credentialId));
+    }
+    // 3. Write the ledger row + its lineage index rows (create-only, byte-identical retry).
+    const row = {
+        credentialId: args.credentialId, holderPrincipal: args.holderPrincipal, lifecycleUid: args.lifecycleUid,
+        sourceChain: chain, state: "active", exp: args.exp,
+    };
+    await createRowByteIdempotent(authKv, rowKey, row);
+    for (const k of bysrcKeys)
+        await createRowByteIdempotent(authKv, k, { ref: rowKey });
+    // The AUTHORITATIVE snapshot is module-private (finalize reads only this, never the object's
+    // own fields); the public object is deep-frozen as well, so a strict-mode mutation throws.
+    const snapshot = { pins: pins.map((p) => ({ ...p })), rowKey };
+    const staged = Object.freeze({
+        lifecycleUid: args.lifecycleUid, credentialId: args.credentialId,
+        pins: Object.freeze(pins.map((p) => Object.freeze({ ...p }))), rowKey,
+    });
+    STAGED_MINTS.set(staged, snapshot);
+    return staged;
+}
+/**
+ * Finalize an AGENT-family mint (SPEC 13.1 mint protocol, step gate-CAS): touch-CAS every
+ * observed gate — the lifecycle gate and each presented source gate — at its pinned revision,
+ * each DISTINCT key once, in CANONICAL (sorted) order (the same crossed-pair discipline as the
+ * session stage). The touch preserves the value and bumps only the revision: a barrier or a
+ * handle revocation that moved ANY of them since observation makes the pinned write LOSE, the
+ * mint marks its OWN row revoked, and throws `permission-denied` — it never releases. Only a
+ * finalize that returns cleanly permits the caller to release the credential bytes.
+ */
+export async function finalizeAgentMint(reg, staged) {
+    const { authKv } = registryStores(reg);
+    // BRAND CHECK + AUTHORITATIVE SNAPSHOT: only stageAgentMint mints a StagedAgentMint, so a
+    // hand-assembled object never reaches the touch-CAS — and the pins/rowKey used below come
+    // from the module-private snapshot, never from fields the caller's object hands back (a
+    // mutated pin object could otherwise duplicate the source-gate pin and the dedup would skip
+    // the lifecycle gate entirely).
+    const snap = STAGED_MINTS.get(staged);
+    if (snap === undefined)
+        throw new EpEnvelopeError("failed-precondition", "the staged mint was not produced by stageAgentMint(); a hand-assembled StagedAgentMint never authorizes a finalize (SPEC 13.12)");
+    if (snap.pins.length === 0)
+        throw new EpEnvelopeError("internal", `the staged mint for ${snap.rowKey} carries no gate pins; a finalize proves at least the lifecycle gate (SPEC 13.1)`);
+    const byKey = new Map();
+    for (const pin of snap.pins) {
+        const seen = byKey.get(pin.key);
+        if (seen !== undefined && seen !== pin.revision)
+            throw new EpEnvelopeError("internal", `the gate ${pin.key} was observed at two revisions (${seen} vs ${pin.revision}); one observation feeds the pinned touch (SPEC 13.1)`);
+        byKey.set(pin.key, pin.revision);
+    }
+    const lose = async (key, detail) => {
+        await markLedgerRowRevoked(authKv, snap.rowKey);
+        throw new EpEnvelopeError("permission-denied", `the mint for ${snap.rowKey} lost its fence on ${key} (${detail}); its row is revoked and nothing releases (SPEC 13.1)`);
+    };
+    for (const key of [...byKey.keys()].sort()) {
+        const revision = byKey.get(key);
+        const entry = await authKv.get(key);
+        if (!entry || entry.operation !== "PUT" || entry.revision !== revision)
+            return lose(key, `revision ${entry?.revision ?? "gone"} vs pinned ${revision}`);
+        try {
+            await authKv.update(key, entry.value, revision);
+        }
+        catch (e) {
+            if (isRawCasLoss(e))
+                return lose(key, "the pinned touch lost the CAS");
+            throw new EpEnvelopeError("unavailable", `the gate touch for ${key} is ambiguous; the mint fails closed (SPEC 13.1): ${e?.message ?? String(e)}`);
+        }
+    }
+}
+/**
+ * Parse a sealed-scanner family read into closed {@link EnumeratedRow}s. FAIL-LOUD is the
+ * contract: a DEL/PURGE marker under a ledger prefix is corruption (rows are revoked, never
+ * deleted), and a row that does not parse aborts the enumeration — a barrier that skipped either
+ * would report a family it did not actually cover. The {@link RawScanEntry} seam stays here (the
+ * ledger's own parse layer): each entry becomes a closed parsed row BEFORE anything reaches a
+ * barrier dependency.
+ */
+function parseLedgerEntries(entries) {
+    return entries.map((e) => {
+        if (e.op === "DEL" || e.op === "PURGE")
+            throw new EpEnvelopeError("failed-precondition", `the ledger key ${e.key} carries a ${e.op} marker; ledger rows are revoked, never deleted; the enumeration refuses (corruption, SPEC 13.12)`);
+        return { key: e.key, row: parseLedgerRow(e.data, e.key), revision: e.seq };
+    });
+}
+/**
+ * Enumerate a lifecycle's FULL descendant family `cred.<lifecycleUid>.>` (SPEC 13.1/13.9) through
+ * the SEALED auth-ledger scanner ({@link registryScanner}). The scan is a fence-free LastPerSubject
+ * read: under the normative history=1 store a same-subject `active→revoked` overwrite EVICTS the
+ * pre-scan revision, so the scanner delivers each subject's CURRENT last (a concurrent revoke is
+ * SEEN, never dropped). The scanner holds the ONLY auth-stream `CONSUMER.CREATE` on its own sealed
+ * credential; the barrier profile holds none (a consumer-create body is not subject-ACL confinable,
+ * nats-server#8274 — ledger-scanner.ts).
+ */
+export async function enumerateAgentFamily(reg, lifecycleUid) {
+    return parseLedgerEntries(await registryScanner(reg).scanCredentialFamily(assertLifecycleToken(lifecycleUid)));
+}
+/**
+ * Enumerate every durable OPERATION intent `stage.<opId>` (SPEC 13.1) — the boot-resume
+ * discovery: a barrier executor that crashed mid-operation finds what it may owe here (whether
+ * an intent is actually OWED is the gate's call: only a gate still frozen by that opId is —
+ * completed and lost operations leave their intent behind by design). Multi-segment `stage.`
+ * keys (the session release pins) are not operations and are skipped; a single-segment intent
+ * that carries a DEL/PURGE marker, fails to parse, or names an unknown kind THROWS — an intent
+ * is never deleted while resumable, and garbled trusted-path state never drives a barrier.
+ */
+export async function enumerateOperationIntents(reg) {
+    const entries = await registryScanner(reg).scanStageFamily();
+    const out = [];
+    for (const e of entries) {
+        const opId = e.key.slice("stage.".length);
+        if (opId.includes("."))
+            continue; // session release pins etc. — not operation intents
+        if (e.op === "DEL" || e.op === "PURGE")
+            throw new EpEnvelopeError("failed-precondition", `the operation intent ${e.key} carries a ${e.op} marker; an intent is never deleted while resumable (corruption, SPEC 13.12)`);
+        let o;
+        try {
+            o = JSON.parse(dec.decode(e.data));
+        }
+        catch {
+            throw new EpEnvelopeError("internal", `the operation intent ${e.key} is not JSON (SPEC 13.1)`);
+        }
+        if (!isRec(o) || (o.kind !== "takeover" && o.kind !== "retirement"))
+            throw new EpEnvelopeError("internal", `the operation intent ${e.key} carries an unknown kind ${isRec(o) ? JSON.stringify(o.kind ?? null) : "(not an object)"} (closed set, SPEC 13.1)`);
+        if (typeof o.lifecycleUid !== "string")
+            throw new EpEnvelopeError("internal", `the operation intent ${e.key} carries no lifecycleUid (SPEC 13.1)`);
+        let uid;
+        try {
+            uid = assertLifecycleToken(o.lifecycleUid);
+        }
+        catch {
+            throw new EpEnvelopeError("internal", `the operation intent ${e.key} carries a malformed lifecycleUid (SPEC 13.1)`);
+        }
+        out.push({ opId, kind: o.kind, lifecycleUid: uid });
+    }
+    return out;
+}
+function parseTakeoverIntent(raw, key) {
+    let o;
+    try {
+        o = JSON.parse(dec.decode(raw));
+    }
+    catch {
+        throw new EpEnvelopeError("internal", `the operation intent ${key} is not JSON (SPEC 13.1)`);
+    }
+    if (!isRec(o))
+        throw new EpEnvelopeError("internal", `the operation intent ${key} is not an object`);
+    const allowed = new Set(["kind", "lifecycleUid", "owner", "actor", "fromEpoch", "fromGeneration"]);
+    for (const k of Object.keys(o))
+        if (!allowed.has(k))
+            throw new EpEnvelopeError("internal", `the operation intent ${key} carries the unknown field "${k}" (closed schema, SPEC 13.1)`);
+    if (o.kind !== "takeover" || typeof o.lifecycleUid !== "string" || typeof o.owner !== "string" || o.owner.length === 0 ||
+        typeof o.actor !== "string" || o.actor.length === 0 || !uint(o.fromEpoch) || o.fromEpoch < 1 || !uint(o.fromGeneration) || o.fromGeneration < 1)
+        throw new EpEnvelopeError("internal", `the operation intent ${key} does not validate as a takeover intent (SPEC 13.1)`);
+    try {
+        assertLifecycleToken(o.lifecycleUid);
+    }
+    catch {
+        throw new EpEnvelopeError("internal", `the operation intent ${key} carries a malformed lifecycleUid (SPEC 13.1)`);
+    }
+    return o;
+}
+async function readTakeoverIntent(authKv, opId) {
+    const key = stageIntentKey(opId);
+    const entry = await authKv.get(key);
+    if (!entry)
+        return undefined;
+    if (entry.operation !== "PUT")
+        throw new EpEnvelopeError("failed-precondition", `the operation intent ${key} carries a ${entry.operation} marker; an intent is never deleted while resumable (corruption, SPEC 13.12)`);
+    return { intent: parseTakeoverIntent(entry.value, key), revision: entry.revision };
+}
+/**
+ * The shared CONTAINMENT core of the lifecycle barriers (SPEC 13.1: takeover and terminal
+ * retirement run the SAME revoke + verified-evict discipline over the SAME family):
+ * point-in-time enumeration of `cred.<lifecycleUid>.>` → revoke EVERY row (idempotent — a
+ * resumed barrier finds some already revoked; the row CAS is the deny-new SUBSTRATE, module
+ * header) → reconcile BOTH halves of every session-derived credential (the reconciler
+ * terminalizes `session.<sessionId>` and revokes the paired serving `epcred.` row, returning
+ * the serving holders; a lifecycle that HAS session-derived credentials but no reconciler
+ * fails loud — the serving half would be left live) → VERIFIED cluster-wide eviction of every
+ * enumerated holder principal (revoked earlier runs included: their connections may still be
+ * live), the alias principal itself, and every session-serving principal. Fail-closed per
+ * principal: anything but `verifiedGone` throws and the calling barrier's gate stays frozen.
+ * PACKAGE-INTERNAL: both barriers reach it through the sealed registry only.
+ */
+export async function containLifecycleFamily(reg, args, deps) {
+    const { authKv } = registryStores(reg);
+    const { evictPrincipal, reconcileSessionPair } = deps;
+    const family = await enumerateAgentFamily(reg, args.lifecycleUid);
+    let revokedRows = 0;
+    for (const item of family) {
+        if ((await markLedgerRowRevoked(authKv, item.key)) === "revoked")
+            revokedRows++;
+    }
+    const sessionIds = new Set();
+    for (const item of family)
+        for (const member of item.row.sourceChain) {
+            const parsed = parseSourceMember(member);
+            if (parsed.kind === "session")
+                sessionIds.add(parsed.sessionId);
+        }
+    const servingPrincipals = new Set();
+    if (sessionIds.size > 0) {
+        if (reconcileSessionPair === undefined)
+            throw new EpEnvelopeError("failed-precondition", `lifecycle ${args.lifecycleUid} has ${sessionIds.size} session-derived credential(s) but the ${args.barrier} barrier was given no session-pair reconciler; the serving half would be left live (SPEC 13.1)`);
+        for (const sid of [...sessionIds].sort())
+            for (const p of (await reconcileSessionPair(sid)).servingPrincipals)
+                servingPrincipals.add(p);
+    }
+    const principals = new Set(family.map((f) => f.row.holderPrincipal));
+    principals.add(`${args.owner}.${args.actor}`);
+    for (const p of servingPrincipals)
+        principals.add(p);
+    const evicted = [];
+    for (const principal of [...principals].sort()) {
+        const res = await evictPrincipal(principal);
+        if (res.verifiedGone !== true)
+            throw new EpEnvelopeError("unavailable", `the ${args.barrier} barrier could not VERIFY eviction of principal ${principal} (kicked ${res.kicked}, remaining ${res.remaining}, scanComplete ${res.scanComplete}${res.note ? `; ${res.note}` : ""}); the gate stays frozen (SPEC 13.1)`);
+        evicted.push(principal);
+    }
+    return { revokedRows, evictedPrincipals: evicted };
+}
+/**
+ * Run the FULL takeover issuance barrier for a managed-agent lifecycle (SPEC 13.1, in the
+ * normative order — see the module header). Idempotent/crash-resumable: every step re-checks
+ * durable state, so calling it again with the SAME `opId` (directly or via
+ * {@link resumeAgentTakeover}) finishes the same operation; a DIFFERENT operation's freeze,
+ * a foreign epoch/generation movement, or a stranger's opId refuses before any CAS.
+ *
+ * FAIL-CLOSED CONTRACT: any failure after the freeze leaves the gate FROZEN (nothing mints)
+ * and the epoch un-advanced; eviction failure (`verifiedGone !== true` for ANY principal)
+ * throws `unavailable` — takeover MUST fail loud rather than proceed over a live predecessor.
+ */
+export async function runAgentTakeoverBarrier(reg, args, deps) {
+    const { authKv } = registryStores(reg);
+    const opId = assertLifecycleToken(args.opId);
+    assertLifecycleToken(args.lifecycleUid);
+    // 0. The durable intent: read-or-create BEFORE any gate movement, so every later step (and
+    // every resume) works from the SAME captured coordinates.
+    let intentRead = await readTakeoverIntent(authKv, opId);
+    if (intentRead !== undefined) {
+        const it = intentRead.intent;
+        if (it.lifecycleUid !== args.lifecycleUid || it.owner !== args.owner || it.actor !== args.actor)
+            throw new EpEnvelopeError("permission-denied", `the operation intent ${stageIntentKey(opId)} belongs to lifecycle ${it.lifecycleUid} ("${it.owner}/${it.actor}"), not ${args.lifecycleUid} ("${args.owner}/${args.actor}"); an opId resumes only its OWN operation (SPEC 13.1)`);
+    }
+    else {
+        const head = await readLifecycleHeadForOperation(reg, args.owner, args.actor);
+        if (head === undefined || head.mapping.state !== "active" || head.mapping.lifecycleUid !== args.lifecycleUid)
+            throw new EpEnvelopeError("failed-precondition", `takeover for "${args.owner}/${args.actor}" requires an ACTIVE head at uid ${args.lifecycleUid}; found ${head === undefined ? "no head" : `${head.mapping.state} at ${head.mapping.lifecycleUid}`} (SPEC 13.1)`);
+        const gate0 = await observeGate(reg, args.lifecycleUid);
+        if (gate0 === undefined)
+            throw new EpEnvelopeError("failed-precondition", `lifecycle ${args.lifecycleUid} has no issuance gate; nothing to take over (SPEC 13.1)`);
+        if (gate0.row.state !== "open" || gate0.row.generation < 1)
+            throw new EpEnvelopeError("failed-precondition", `the issuance gate for ${args.lifecycleUid} is "${gate0.row.state}" at generation ${gate0.row.generation}; a takeover freezes an OPEN, mintable gate (another operation owns a frozen one, SPEC 13.1)`);
+        // COORDINATE-PAIR COHERENCE (SPEC 13.1): the head and gate reads above are two reads, and a
+        // COMPLETED foreign takeover can land between them, leaving a TORN pair (old epoch, new
+        // generation). An intent persisted from a torn pair freezes the winner's reopened gate,
+        // revokes the successor's rows, and then wedges forever on the foreign epoch stamp — so
+        // re-read the head and refuse any movement BEFORE the intent becomes durable.
+        const head2 = await readLifecycleHeadForOperation(reg, args.owner, args.actor);
+        if (head2 === undefined || head2.mapping.state !== "active" || head2.mapping.lifecycleUid !== args.lifecycleUid || head2.mapping.processEpoch !== head.mapping.processEpoch)
+            throw new EpEnvelopeError("conflict", `the head for "${args.owner}/${args.actor}" moved while this takeover captured its coordinates (epoch ${head.mapping.processEpoch} → ${head2 === undefined ? "gone" : `${head2.mapping.state}@${head2.mapping.processEpoch}`}); the captured pair is torn; re-read and re-decide with fresh coordinates (SPEC 13.1)`);
+        const intent = {
+            kind: "takeover", lifecycleUid: args.lifecycleUid, owner: args.owner, actor: args.actor,
+            fromEpoch: head.mapping.processEpoch, fromGeneration: gate0.row.generation,
+        };
+        await createRowByteIdempotent(authKv, stageIntentKey(opId), intent);
+        intentRead = await readTakeoverIntent(authKv, opId);
+        if (intentRead === undefined)
+            throw new EpEnvelopeError("internal", `the operation intent ${stageIntentKey(opId)} vanished after its create (SPEC 13.12)`);
+    }
+    const intent = intentRead.intent;
+    // 1. Freeze the gate under OUR intent (or recognize our own freeze / our own completed
+    // reopen). A freeze-CAS loss means a mint's finalize touch bumped the revision — that is the
+    // normative serialization on one key — so re-observe and retry the freeze, bounded.
+    for (let attempt = 0;; attempt++) {
+        const gate = await observeGate(reg, intent.lifecycleUid);
+        if (gate === undefined)
+            throw new EpEnvelopeError("internal", `the issuance gate for ${intent.lifecycleUid} vanished mid-operation; a gate is never deleted (corruption, SPEC 13.12)`);
+        if (gate.row.state === "frozen") {
+            if (gate.row.op?.opId !== opId)
+                throw new EpEnvelopeError("failed-precondition", `the issuance gate for ${intent.lifecycleUid} is frozen by operation ${gate.row.op?.opId ?? "<none>"}, not ${opId}; one barrier at a time (SPEC 13.1)`);
+            // Our own freeze (fresh or resumed). Whether we are still the CURRENT operation or a
+            // stale loser whose freeze straddled a foreign completion is decided at the epoch CAS
+            // (step 5), NOT here: a freeze held over a foreign head may already have PARTIALLY
+            // revoked the family before crashing, so recovery MUST complete containment (revoke +
+            // reconcile + verified-evict every family holder) before it aborts — reopening early
+            // would leave a revoked credential's connection live. We therefore proceed into the
+            // containment steps unconditionally and let advanceEpochWithinTakeover detect the loss.
+            break;
+        }
+        if (gate.row.state === "open" && gate.row.generation === intent.fromGeneration + 1) {
+            // The gate reopened at OUR successor generation. Confirm the head shows a completed
+            // takeover AND that OUR opId is the one that advanced it: a LOSING concurrent takeover
+            // that captured the same (fromEpoch, fromGeneration) also lands here, and it MUST NOT
+            // claim the winner's completion (SPEC 13.1). The epoch stamp binds completion to one op.
+            const head = await readLifecycleHeadForOperation(reg, intent.owner, intent.actor);
+            if (head === undefined || head.mapping.state !== "active" || head.mapping.lifecycleUid !== intent.lifecycleUid || head.mapping.processEpoch !== intent.fromEpoch + 1)
+                throw new EpEnvelopeError("internal", `the gate for ${intent.lifecycleUid} reopened at generation ${gate.row.generation} but the head does not show the completed takeover (SPEC 13.1); inspect the operation ${opId}`);
+            if (head.mapping.lastTakeoverOpId !== opId)
+                throw new EpEnvelopeError("conflict", `the takeover of ${intent.lifecycleUid} at epoch ${intent.fromEpoch + 1} was completed by operation ${head.mapping.lastTakeoverOpId ?? "<none>"}, not ${opId}; a concurrent takeover won and this operation lost (SPEC 13.1)`);
+            return { opId, lifecycleUid: intent.lifecycleUid, toEpoch: intent.fromEpoch + 1, toGeneration: intent.fromGeneration + 1, revokedRows: 0, evictedPrincipals: [] };
+        }
+        if (!(gate.row.state === "open" && gate.row.generation === intent.fromGeneration))
+            throw new EpEnvelopeError("failed-precondition", `the issuance gate for ${intent.lifecycleUid} is "${gate.row.state}" at generation ${gate.row.generation}, not this takeover's captured generation ${intent.fromGeneration} (or its +1); a foreign operation moved it (SPEC 13.1)`);
+        // HEAD GUARD, immediately before the freeze CAS (SPEC 13.1): the intent's coordinates are
+        // durable and may be STALE — if a foreign operation advanced the head since capture, this
+        // operation has already lost, and it must refuse WITHOUT moving the gate (a stale intent
+        // that freezes anyway revokes the winner's successor and wedges on the foreign epoch
+        // stamp). The gate CAS then serializes the residue: a foreign takeover completing after
+        // this read must first freeze the gate itself, which makes OUR freeze CAS lose and re-loop.
+        const headNow = await readLifecycleHeadForOperation(reg, intent.owner, intent.actor);
+        if (headNow === undefined || headNow.mapping.state !== "active" || headNow.mapping.lifecycleUid !== intent.lifecycleUid || headNow.mapping.processEpoch !== intent.fromEpoch)
+            throw new EpEnvelopeError("conflict", `the head for "${intent.owner}/${intent.actor}" is ${headNow === undefined ? "gone" : `${headNow.mapping.state}@epoch ${headNow.mapping.processEpoch} (uid ${headNow.mapping.lifecycleUid})`}, not this takeover's captured epoch ${intent.fromEpoch}; the intent is stale and this operation lost; the gate was not moved (SPEC 13.1)`);
+        try {
+            await freezeGate(reg, { lifecycleUid: intent.lifecycleUid, revision: gate.revision, op: { opId, kind: "takeover" } });
+            break;
+        }
+        catch (e) {
+            if (e instanceof EpEnvelopeError && e.code === "conflict" && attempt < 4)
+                continue;
+            throw e;
+        }
+    }
+    // 2-4. The shared containment core (enumerate → revoke → session reconcile → verified evict):
+    // post-freeze, a mint that won its fence wrote its rows before the freeze, so the scan sees
+    // them; a mint that lost never released.
+    const { revokedRows, evictedPrincipals: evicted } = await containLifecycleFamily(reg, { owner: intent.owner, actor: intent.actor, lifecycleUid: intent.lifecycleUid, barrier: "takeover" }, deps);
+    // 5. The epoch head CAS — LAST among the containment steps (SPEC 13.1: no predecessor egress
+    // survives to publish under the old epoch once the successor's epoch exists). It STAMPS this
+    // op's id, so the completion is bound to exactly this operation. Idempotent for our own advance.
+    // If a FOREIGN operation already advanced the epoch (a stale/torn intent that froze the gate
+    // and revoked the family before crashing), this throws `conflict`. We have already completed
+    // CONTAINMENT above (every revoked row's holder is verified-evicted), so the state is
+    // consistent — no revoked credential is left live. We then ABORT SAFELY: reopen our own
+    // freeze WITHOUT advancing the epoch (the winner owns it) so the lifecycle is not wedged, and
+    // rethrow. This is the crash-boundary counterpart to the pre-freeze head guard (which stops a
+    // FRESH stale intent from freezing at all).
+    try {
+        await advanceEpochWithinTakeover(reg, { owner: intent.owner, actor: intent.actor, lifecycleUid: intent.lifecycleUid, fromEpoch: intent.fromEpoch, opId });
+    }
+    catch (e) {
+        if (e instanceof EpEnvelopeError && e.code === "conflict") {
+            const g = await observeGate(reg, intent.lifecycleUid);
+            if (g !== undefined && g.row.state === "frozen" && g.row.op?.opId === opId)
+                await reopenGate(reg, { lifecycleUid: intent.lifecycleUid, revision: g.revision, opId }); // abort, no epoch advance
+            throw new EpEnvelopeError("conflict", `the takeover ${opId} of ${intent.lifecycleUid} lost: a foreign operation already advanced the epoch (captured ${intent.fromEpoch}). Containment completed (${revokedRows} row(s) revoked and every holder verified-evicted) and the gate was reopened without an epoch advance; nothing is wedged and no revoked credential is left live (SPEC 13.1)`);
+        }
+        throw e;
+    }
+    // 6. Reopen the gate at the successor's first mintable generation — the barrier's own final
+    // step (SPEC 13.1: no credential of generation G is ever live when G+1 mints).
+    const latest = await observeGate(reg, intent.lifecycleUid);
+    if (latest === undefined)
+        throw new EpEnvelopeError("internal", `the issuance gate for ${intent.lifecycleUid} vanished before the reopen (corruption, SPEC 13.12)`);
+    if (latest.row.state === "frozen")
+        await reopenGate(reg, { lifecycleUid: intent.lifecycleUid, revision: latest.revision, opId });
+    else if (!(latest.row.state === "open" && latest.row.generation === intent.fromGeneration + 1))
+        throw new EpEnvelopeError("internal", `the issuance gate for ${intent.lifecycleUid} is "${latest.row.state}" at generation ${latest.row.generation} at the reopen step; a foreign movement inside our freeze is corruption (SPEC 13.1)`);
+    return { opId, lifecycleUid: intent.lifecycleUid, toEpoch: intent.fromEpoch + 1, toGeneration: intent.fromGeneration + 1, revokedRows, evictedPrincipals: evicted };
+}
+/** Resume a crashed takeover from its durable intent alone (`{ opId }` — SPEC 13.1: the intent
+ *  decides WHICH operation a frozen gate belongs to; `{ opId, kind }` alone resumes
+ *  deterministically). Re-runs {@link runAgentTakeoverBarrier} with the intent's own
+ *  coordinates; a stranger's opId (no intent) is `not-found`. */
+export async function resumeAgentTakeover(reg, opId, deps) {
+    const { authKv } = registryStores(reg);
+    const read = await readTakeoverIntent(authKv, assertLifecycleToken(opId));
+    if (read === undefined)
+        throw new EpEnvelopeError("not-found", `no operation intent exists at ${stageIntentKey(opId)}; there is nothing to resume (SPEC 13.1)`);
+    const it = read.intent;
+    return runAgentTakeoverBarrier(reg, { owner: it.owner, actor: it.actor, lifecycleUid: it.lifecycleUid, opId }, deps);
+}
+// ---- handle revocation (the source-gate walk) ---------------------------------------------------
+/**
+ * Revoke a sturdy handle at its SOURCE (SPEC 13.1): CAS the source gate `open → frozen` FIRST
+ * (the fence — an in-flight redemption under this handle either finished before the freeze,
+ * so its rows are in the enumeration, or loses its pinned finalize touch and never releases),
+ * then enumerate `bysrc.<issuerKeyId>.<id>.>`, revoke EVERY descendant ledger row it indexes
+ * (credentials minted under this handle OR under any descendant handle that carried it in the
+ * chain), and run VERIFIED cluster-wide eviction of every revoked row's holder principal —
+ * fail-closed, exactly the takeover discipline. The source gate stays frozen forever (a
+ * revoked handle never mints again); an already-frozen gate resumes the walk idempotently.
+ */
+export async function revokeHandleSource(reg, args, deps) {
+    const { authKv } = registryStores(reg);
+    const { evictPrincipal, reconcileSessionPair } = deps;
+    // 1. Freeze FIRST (idempotent resume over an already-frozen gate).
+    const gate = await observeSourceGate(reg, args);
+    if (gate === undefined)
+        throw new EpEnvelopeError("not-found", `no source gate exists for handle ${args.issuerKeyId}.${args.id}; nothing to revoke (SPEC 13.1)`);
+    if (gate.row.state === "open")
+        await freezeSourceGate(reg, { issuerKeyId: args.issuerKeyId, id: args.id, revision: gate.revision });
+    // 2. Enumerate the lineage index, point-in-time (same throwaway-consumer mechanics).
+    const indexRows = await enumerateBysrc(reg, args.issuerKeyId, args.id);
+    // 3. Revoke every indexed descendant row (the index names the row; the ROW is the authority).
+    let revokedRows = 0;
+    const principals = new Set();
+    const sessionIds = new Set();
+    for (const { key, ref } of indexRows) {
+        const entry = await authKv.get(ref);
+        if (!entry || entry.operation !== "PUT")
+            throw new EpEnvelopeError("failed-precondition", `the lineage index ${key} names ${ref}, which ${!entry ? "does not exist" : `carries a ${entry.operation} marker`}; ledger rows are never deleted (corruption, SPEC 13.12)`);
+        const row = parseLedgerRow(entry.value, ref);
+        principals.add(row.holderPrincipal);
+        for (const member of row.sourceChain) {
+            const parsed = parseSourceMember(member);
+            if (parsed.kind === "session")
+                sessionIds.add(parsed.sessionId);
+        }
+        if ((await markLedgerRowRevoked(authKv, ref)) === "revoked")
+            revokedRows++;
+    }
+    // 3b. Tear down BOTH halves of any session-derived descendant (as the takeover barrier does),
+    // and JOIN the serving principals into the eviction set below (SPEC 13.6).
+    if (sessionIds.size > 0) {
+        if (reconcileSessionPair === undefined)
+            throw new EpEnvelopeError("failed-precondition", `handle ${args.issuerKeyId}.${args.id} has ${sessionIds.size} session-derived descendant credential(s) but the revocation was given no session-pair reconciler (SPEC 13.1)`);
+        for (const sid of [...sessionIds].sort())
+            for (const p of (await reconcileSessionPair(sid)).servingPrincipals)
+                principals.add(p);
+    }
+    // 4. VERIFIED eviction of every descendant holder (SPEC 13.1: an already-connected descendant
+    // credential is never silently left with live grants; acked only after this completes).
+    const evicted = [];
+    for (const principal of [...principals].sort()) {
+        const res = await evictPrincipal(principal);
+        if (res.verifiedGone !== true)
+            throw new EpEnvelopeError("unavailable", `handle revocation for ${args.issuerKeyId}.${args.id} could not VERIFY eviction of principal ${principal} (kicked ${res.kicked}, remaining ${res.remaining}, scanComplete ${res.scanComplete}${res.note ? `; ${res.note}` : ""}); re-run the revocation (SPEC 13.1)`);
+        evicted.push(principal);
+    }
+    return { revokedRows, evictedPrincipals: evicted };
+}
+/** Enumerate a handle's lineage index `bysrc.<issuerKeyId>.<id>.>` (the walk's read). The
+ *  index parse is closed and key-bound; the referenced rows are parsed by the walk itself. */
+async function enumerateBysrc(reg, issuerKeyId, id) {
+    // The SEALED scanner's fence-free LastPerSubject read over `bysrc.<issuerKeyId>.<id>.>`
+    // (ledger-scanner.ts: a consumer-create grant is body-unconfinable, so the CREATE lives only in
+    // the scanner's own sealed credential). Index rows are never deleted, so a DEL/PURGE marker is
+    // corruption and refuses.
+    return (await registryScanner(reg).scanBysrc(assertKeySegment(issuerKeyId, "issuerKeyId"), assertKeySegment(id, "handle id"))).map((e) => {
+        if (e.op === "DEL" || e.op === "PURGE")
+            throw new EpEnvelopeError("failed-precondition", `the lineage index key ${e.key} carries a ${e.op} marker; index rows are never deleted (corruption, SPEC 13.12)`);
+        return { key: e.key, ref: parseBysrcRow(e.data, e.key).ref };
+    });
+}
+//# sourceMappingURL=credential-ledger.js.map