@cotal-ai/auth 0.16.0 → 0.18.0

package/dist/lifecycle-registry.js

@@ -47,14 +47,10 @@
  */
 import { jetstream, jetstreamManager } from "@nats-io/jetstream";
 import { Kvm } from "@nats-io/kv";
-import { EpEnvelopeError, LIFECYCLE_HEAD, UID_RESERVATION, recordAtomicKey, createRecordEntry, updateRecordEntry, readRecordLeader, mintLifecycleUid, assertLifecycleToken, epAuthBucket, isCasLoss as isRawCasLoss, workPoolContext, } from "@cotal-ai/core";
+import { EpEnvelopeError, recordsBucket as coreRecordsBucket, lifecycleHeadKey as headKey, parseLifecycleHead as parseMapping, headCandidate, gateObserve, gateCreateFrozen, gateFreeze, gateReopen, gateRetire, uidTryReserve, uidReserveFresh, uidReadReservation, headAdvanceEpochWithinTakeover, headSetCurrentRootCredential, headBeginRetirement, headCompleteRetirement, runActivationSaga, runActivationSagaAtUid, resumeActivationSaga, createRecordEntry, updateRecordEntry, readRecordLeader, epAuthBucket, workPoolContext, } from "@cotal-ai/core";
 import { assertScannerSpace } from "./ledger-scanner.js";
 import { assertRecordsScannerSpace } from "./records-scanner.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;
-const isCasLoss = (e) => e instanceof EpEnvelopeError && e.code === "conflict";
 const REGISTRIES = new WeakMap();
 const READERS = new WeakMap();
 function internals(reg) {
@@ -110,7 +106,10 @@ export function assertAuthorityStreamShape(cfg, bucket) {
 export async function openLifecycleRegistry(nc, space, scanner, recordsScanner) {
     const jsm = await jetstreamManager(nc);
     const kvm = new Kvm(nc);
-    const recordsBucket = `cotal_records_${space}`;
+    // ONE encoder for the records-bucket name (core `recordsBucket`): the previous inline
+    // `cotal_records_${space}` skipped `token(space)` — identical for every legal space name, but
+    // a second encoder of a load-bearing name is exactly the drift class the shared grammar bans.
+    const recordsBucket = coreRecordsBucket(space);
     const authBucket = epAuthBucket(space);
     let recordsKv, authKv;
     let recordsCfg;
@@ -154,7 +153,10 @@ export async function openLifecycleRegistry(nc, space, scanner, recordsScanner)
  *  records store refuses to serve authority reads (it could otherwise leader-read a MIRROR's
  *  leader and call that the mapping). */
 export async function openLifecycleMappingReader(nc, space) {
-    const recordsBucket = `cotal_records_${space}`;
+    // ONE encoder for the records-bucket name (core `recordsBucket`): the previous inline
+    // `cotal_records_${space}` skipped `token(space)` — identical for every legal space name, but
+    // a second encoder of a load-bearing name is exactly the drift class the shared grammar bans.
+    const recordsBucket = coreRecordsBucket(space);
     let jsm;
     let recordsCfg;
     try {
@@ -169,77 +171,20 @@ export async function openLifecycleMappingReader(nc, space) {
     READERS.set(rd, { space, jsm });
     return rd;
 }
-const HEAD_STATES = new Set(["active", "retiring", "retired"]);
-function headKey(owner, actor) {
-    return recordAtomicKey(LIFECYCLE_HEAD, [owner, actor]);
-}
-function uidKey(lifecycleUid) {
-    return recordAtomicKey(UID_RESERVATION, [lifecycleUid]);
-}
-/** Validate a head value at the consuming boundary — CLOSED schema (nested `op` included), and
- *  the embedded owner/actor MUST agree with the key so a key-mismatched row never authorizes. */
-function parseMapping(raw, key, owner, actor) {
-    let o;
-    try {
-        o = JSON.parse(dec.decode(raw));
-    }
-    catch {
-        throw new EpEnvelopeError("internal", `the lifecycle head ${key} is not JSON; garbled trusted-path state never authorizes (SPEC 13.1)`);
-    }
-    if (!isRec(o))
-        throw new EpEnvelopeError("internal", `the lifecycle head ${key} is not an object`);
-    const allowed = new Set(["owner", "actor", "lifecycleUid", "managerInstance", "processEpoch", "state", "currentCredentialId", "lastTakeoverOpId", "op"]);
-    for (const k of Object.keys(o))
-        if (!allowed.has(k))
-            throw new EpEnvelopeError("internal", `the lifecycle head ${key} carries the unknown field "${k}" (closed schema, SPEC 13.1)`);
-    if (o.owner !== owner || o.actor !== actor ||
-        typeof o.lifecycleUid !== "string" || typeof o.managerInstance !== "string" || o.managerInstance.length === 0 ||
-        !uint(o.processEpoch) || o.processEpoch < 1 || typeof o.state !== "string" || !HEAD_STATES.has(o.state) ||
-        (o.currentCredentialId !== undefined && (typeof o.currentCredentialId !== "string" || o.currentCredentialId.length === 0)) ||
-        (o.lastTakeoverOpId !== undefined && typeof o.lastTakeoverOpId !== "string"))
-        throw new EpEnvelopeError("internal", `the lifecycle head ${key} does not validate (owner/actor/uid/epoch/state); a garbled or key-mismatched head never authorizes (SPEC 13.1/13.3)`);
-    try {
-        assertLifecycleToken(o.lifecycleUid);
-        if (o.lastTakeoverOpId !== undefined)
-            assertLifecycleToken(o.lastTakeoverOpId);
-    }
-    catch {
-        throw new EpEnvelopeError("internal", `the lifecycle head ${key} carries a malformed lifecycleUid/lastTakeoverOpId (SPEC 13.1)`);
-    }
-    // The retirement op intent: REQUIRED at `retiring`, forbidden elsewhere; itself closed.
-    if (o.state === "retiring") {
-        if (!isRec(o.op))
-            throw new EpEnvelopeError("internal", `the lifecycle head ${key} is retiring without its durable op intent (SPEC 13.1: retiring is op-bound)`);
-    }
-    else if (o.op !== undefined) {
-        throw new EpEnvelopeError("internal", `the lifecycle head ${key} carries an op intent in state "${o.state}" (SPEC 13.1: only retiring is op-bound)`);
-    }
-    if (o.op !== undefined) {
-        const op = o.op;
-        for (const k of Object.keys(op))
-            if (k !== "opId" && k !== "kind")
-                throw new EpEnvelopeError("internal", `the lifecycle head ${key} op intent carries the unknown field "${k}" (closed schema)`);
-        if (typeof op.opId !== "string" || op.kind !== "retirement")
-            throw new EpEnvelopeError("internal", `the lifecycle head ${key} op intent does not validate (SPEC 13.1)`);
-        try {
-            assertLifecycleToken(op.opId);
-        }
-        catch {
-            throw new EpEnvelopeError("internal", `the lifecycle head ${key} op intent carries a malformed opId (SPEC 13.1)`);
-        }
-    }
-    return o;
-}
-/** Candidate read for a CAS-fenced mutation (raw `kv.get`; the auth decision is the CAS itself,
- *  §13.1: a read is never a fence). A DEL/PURGE marker is CORRUPTION, never absence. */
-async function readHeadCandidate(kv, owner, actor) {
-    const key = headKey(owner, actor);
-    const entry = await kv.get(key);
-    if (!entry)
-        return undefined;
-    if (entry.operation !== "PUT")
-        throw new EpEnvelopeError("failed-precondition", `the lifecycle head ${key} carries a ${entry.operation} marker; an authority head is never deleted (a deletion is corruption, not absence, SPEC 13.12)`);
-    return { mapping: parseMapping(entry.value, key, owner, actor), revision: entry.revision };
+/** The sealed registry's write transport for the shared §13.1 saga sequencing
+ *  (@cotal-ai/core `lifecycle-saga.ts`): constructed ONLY from this module's sealed internals,
+ *  so the WeakMap brand still gates every write; the transport carries no sequencing decisions
+ *  of its own (the three-way split: adapters are TRANSPORT, never a second saga). */
+function transportOf(reg) {
+    const { recordsKv, authKv } = internals(reg);
+    const entryOf = (e) => e === null ? undefined : { value: e.value, revision: e.revision, operation: e.operation };
+    return {
+        getRecord: async (key) => entryOf(await recordsKv.get(key)),
+        createRecord: (key, value) => createRecordEntry(recordsKv, key, value),
+        updateRecord: (key, value, rev) => updateRecordEntry(recordsKv, key, value, rev),
+        getAuth: async (key) => entryOf(await authKv.get(key)),
+        putAuth: (key, payload, rev) => authKv.put(key, payload, { previousSeq: rev }),
+    };
 }
 /** PACKAGE-INTERNAL accessor for the trusted auth path's sibling modules (the credential
  *  ledger + issuance barrier, which are the SAME authority over the SAME stores). Deliberately
@@ -272,43 +217,14 @@ export function registryRecordsScanner(reg) {
  *  through {@link advanceEpochWithinTakeover}). Same never-deleted discipline as every head
  *  read; never re-exported from the package index. */
 export async function readLifecycleHeadForOperation(reg, owner, actor) {
-    return readHeadCandidate(internals(reg).recordsKv, owner, actor);
+    return headCandidate(transportOf(reg), owner, actor);
 }
 /** The takeover barrier's epoch-advance head CAS (SPEC 13.1: NO public epoch advance exists;
- *  this is a finalization step of the takeover barrier, module-internal for the credential
- *  ledger's barrier only, and idempotent for the barrier's crash-resume). Advances the epoch by
- *  exactly one, revision-pinned, only while the head is ACTIVE at the SAME uid. */
+ *  module-internal for the credential ledger's barrier only) — delegates to the shared §13.1
+ *  sequencing (core `headAdvanceEpochWithinTakeover`, which also carries the C1 same-CAS
+ *  root-stamp clear) over this registry's sealed transport. */
 export async function advanceEpochWithinTakeover(reg, args) {
-    const { recordsKv } = internals(reg);
-    const cur = await readHeadCandidate(recordsKv, args.owner, args.actor);
-    if (cur === undefined || cur.mapping.state !== "active" || cur.mapping.lifecycleUid !== args.lifecycleUid)
-        throw new EpEnvelopeError("failed-precondition", `the takeover epoch advance for "${args.owner}/${args.actor}" requires an ACTIVE head at uid ${args.lifecycleUid}; found ${cur === undefined ? "no head" : `${cur.mapping.state} at ${cur.mapping.lifecycleUid}`} (SPEC 13.1)`);
-    if (cur.mapping.processEpoch === args.fromEpoch + 1) {
-        // Idempotent ONLY for our OWN completed advance: the epoch stamp binds the completion to one
-        // op, so a LOSING concurrent takeover that captured the same fromEpoch finds a foreign opId
-        // and refuses, never claiming the winner's advance (SPEC 13.1).
-        if (cur.mapping.lastTakeoverOpId !== args.opId)
-            throw new EpEnvelopeError("conflict", `the head for "${args.owner}/${args.actor}" is at epoch ${args.fromEpoch + 1} advanced by operation ${cur.mapping.lastTakeoverOpId ?? "<none>"}, not ${args.opId}; a concurrent takeover won and this operation lost (SPEC 13.1)`);
-        // C1 (panel HIGH): our own completed advance MUST have cleared the revoked root stamp too. If
-        // the epoch advanced under our opId but `currentCredentialId` is still set, that is IMPOSSIBLE
-        // persisted state (a partial write or an old binary) — fail loud rather than report success
-        // over a head that still wedges the successor mint.
-        if (cur.mapping.currentCredentialId !== undefined)
-            throw new EpEnvelopeError("failed-precondition", `the head for "${args.owner}/${args.actor}" advanced under takeover ${args.opId} but still names root credential ${cur.mapping.currentCredentialId}; the epoch CAS clears it atomically, so a residual stamp is impossible persisted state (SPEC 13.1)`);
-        return "already-advanced";
-    }
-    if (cur.mapping.processEpoch !== args.fromEpoch)
-        throw new EpEnvelopeError("failed-precondition", `the head for "${args.owner}/${args.actor}" is at epoch ${cur.mapping.processEpoch}, not the takeover's captured epoch ${args.fromEpoch} (or its +1); a foreign operation moved it (SPEC 13.1)`);
-    // C1 (panel HIGH, all lanes): advance the epoch AND clear `currentCredentialId` in the SAME CAS.
-    // The takeover's family revoke marked the incarnation's root row `revoked`; leaving the head
-    // still naming that revoked root permanently wedges the successor mint (`ensureRootCredential`'s
-    // fast path reads the stamped id, refuses its revoked state, and `setCurrentRootCredential`
-    // refuses a value flip). Clearing the stamp makes the head's root slot ABSENT, so the successor's
-    // release-last stamp can win. Root rotation stays a barrier's job — this CAS IS that barrier step.
-    const { currentCredentialId: _revoked, ...rest } = cur.mapping;
-    void _revoked;
-    await updateRecordEntry(recordsKv, headKey(args.owner, args.actor), { ...rest, processEpoch: args.fromEpoch + 1, lastTakeoverOpId: assertLifecycleToken(args.opId) }, cur.revision);
-    return "advanced";
+    return headAdvanceEpochWithinTakeover(transportOf(reg), args);
 }
 /**
  * The issuance path's head CAS stamping the incarnation's ROOT credential (SPEC 13.1: the head's
@@ -324,36 +240,14 @@ export async function advanceEpochWithinTakeover(reg, args) {
  * only; a foreign head movement between the caller's read and this CAS loses fail-closed.
  */
 export async function setCurrentRootCredential(reg, args) {
-    const { recordsKv } = internals(reg);
-    if (typeof args.credentialId !== "string" || args.credentialId.length === 0)
-        throw new EpEnvelopeError("failed-precondition", "setCurrentRootCredential requires a credentialId");
-    const cur = await readHeadCandidate(recordsKv, args.owner, args.actor);
-    if (cur === undefined || cur.mapping.state !== "active" || cur.mapping.lifecycleUid !== args.lifecycleUid)
-        throw new EpEnvelopeError("failed-precondition", `stamping the root credential for "${args.owner}/${args.actor}" requires an ACTIVE head at uid ${args.lifecycleUid}; found ${cur === undefined ? "no head" : `${cur.mapping.state} at ${cur.mapping.lifecycleUid}`} (SPEC 13.1)`);
-    if (cur.mapping.currentCredentialId === args.credentialId)
-        return; // our own completed stamp
-    if (cur.mapping.currentCredentialId !== undefined)
-        throw new EpEnvelopeError("permission-denied", `the head for "${args.owner}/${args.actor}" already names root credential ${cur.mapping.currentCredentialId}; rotating it takes the full family-revoke barrier, never a bare head flip (the old root's descendants would stay connectable under the leaf check, SPEC 13.1)`);
-    await updateRecordEntry(recordsKv, headKey(args.owner, args.actor), { ...cur.mapping, currentCredentialId: args.credentialId }, cur.revision);
+    return headSetCurrentRootCredential(transportOf(reg), args);
 }
 /** The retirement barrier's head CONTAINMENT CAS (SPEC 13.1: `active → retiring`, bound to the
  *  retirement operation's durable intent — from this point every currency seam yields no current
  *  mapping and no current epoch, and the alias is NOT replaceable). PACKAGE-INTERNAL for the
  *  barrier only (no public retire seam exists); idempotent for the barrier's crash-resume. */
 export async function beginHeadRetirementWithinBarrier(reg, args) {
-    const { recordsKv } = internals(reg);
-    const cur = await readHeadCandidate(recordsKv, args.owner, args.actor);
-    if (cur === undefined || cur.mapping.lifecycleUid !== args.lifecycleUid)
-        throw new EpEnvelopeError("failed-precondition", `the retirement of uid ${args.lifecycleUid} requires the head for "${args.owner}/${args.actor}" to name it; found ${cur === undefined ? "no head" : `uid ${cur.mapping.lifecycleUid}`} (SPEC 13.1)`);
-    if (cur.mapping.state === "retiring") {
-        if (cur.mapping.op?.opId !== args.opId)
-            throw new EpEnvelopeError("permission-denied", `the head for "${args.owner}/${args.actor}" is retiring under operation ${cur.mapping.op?.opId ?? "<none>"}, not ${args.opId}; one retirement at a time, and a stranger never advances it (SPEC 13.1)`);
-        return "already-retiring";
-    }
-    if (cur.mapping.state !== "active")
-        throw new EpEnvelopeError("failed-precondition", `the head for "${args.owner}/${args.actor}" is "${cur.mapping.state}", not active; only an active head enters retirement containment (a completed terminal is decided at the gate, never re-entered here, SPEC 13.1)`);
-    await updateRecordEntry(recordsKv, headKey(args.owner, args.actor), { ...cur.mapping, state: "retiring", op: { opId: assertLifecycleToken(args.opId), kind: "retirement" } }, cur.revision);
-    return "retiring";
+    return headBeginRetirement(transportOf(reg), args);
 }
 /** The retirement barrier's TERMINAL head CAS (`retiring → retired`, op-pinned) — the barrier's
  *  LAST step (SPEC 13.1: `retired` ASSERTS completed cleanup, which is what makes the alias
@@ -361,39 +255,14 @@ export async function beginHeadRetirementWithinBarrier(reg, args) {
  *  `retired` is decided by the CALLER against the gate's terminal op (the retired head itself
  *  carries no retirement stamp). PACKAGE-INTERNAL for the barrier only. */
 export async function completeHeadRetirementWithinBarrier(reg, args) {
-    const { recordsKv } = internals(reg);
-    const cur = await readHeadCandidate(recordsKv, args.owner, args.actor);
-    if (cur === undefined || cur.mapping.lifecycleUid !== args.lifecycleUid)
-        throw new EpEnvelopeError("failed-precondition", `the retirement terminal for uid ${args.lifecycleUid} requires the head for "${args.owner}/${args.actor}" to name it; found ${cur === undefined ? "no head" : `uid ${cur.mapping.lifecycleUid}`}; a replaced head is settled at the gate, never here (SPEC 13.1)`);
-    if (cur.mapping.state === "retired")
-        return "already-retired";
-    if (cur.mapping.state !== "retiring" || cur.mapping.op?.opId !== args.opId)
-        throw new EpEnvelopeError("permission-denied", `the head for "${args.owner}/${args.actor}" is ${cur.mapping.state === "retiring" ? `retiring under operation ${cur.mapping.op?.opId ?? "<none>"}` : `"${cur.mapping.state}"`}, not retiring under ${args.opId}; only the containing operation terminalizes its own retirement (SPEC 13.1)`);
-    const { op: _op, ...rest } = cur.mapping;
-    await updateRecordEntry(recordsKv, headKey(args.owner, args.actor), { ...rest, state: "retired" }, cur.revision);
-    return "retired";
+    return headCompleteRetirement(transportOf(reg), args);
 }
 /** PACKAGE-INTERNAL: read a UID reservation's audit `{ owner, actor }` (the minting authority
  *  recorded it at {@link tryReserveUid}). The credential ledger uses it to BIND a mint's
  *  `holderPrincipal` to the reserved identity, so a trusted caller cannot ledger a row that
  *  names a foreign principal for the barrier to evict. A DEL/PURGE marker refuses loudly. */
 export async function readUidReservation(reg, lifecycleUid) {
-    const { recordsKv } = internals(reg);
-    const entry = await recordsKv.get(uidKey(assertLifecycleToken(lifecycleUid)));
-    if (!entry)
-        return undefined;
-    if (entry.operation !== "PUT")
-        throw new EpEnvelopeError("failed-precondition", `the uid reservation for ${lifecycleUid} carries a ${entry.operation} marker; a reservation is never deleted (corruption, SPEC 13.12)`);
-    let o;
-    try {
-        o = JSON.parse(dec.decode(entry.value));
-    }
-    catch {
-        throw new EpEnvelopeError("internal", `the uid reservation for ${lifecycleUid} is not JSON (SPEC 13.1)`);
-    }
-    if (!isRec(o) || typeof o.owner !== "string" || typeof o.actor !== "string" || o.owner.length === 0 || o.actor.length === 0)
-        throw new EpEnvelopeError("internal", `the uid reservation for ${lifecycleUid} does not carry a valid owner/actor audit (SPEC 13.1)`);
-    return { owner: o.owner, actor: o.actor };
+    return uidReadReservation(transportOf(reg), lifecycleUid);
 }
 // ---- the space-global UID reservation (records store) ----------------------------------------
 /** Try to reserve ONE explicit candidate UID (test/provisioning-internal; production paths use
@@ -402,99 +271,23 @@ export async function readUidReservation(reg, lifecycleUid) {
  *  never-reuse rule. NOT exported from the package index: an explicit candidate is only for
  *  probes and migration tooling, never a caller-chosen identity. */
 export async function tryReserveUid(reg, lifecycleUid, audit) {
-    const { recordsKv } = internals(reg);
-    assertLifecycleToken(lifecycleUid);
-    try {
-        await createRecordEntry(recordsKv, uidKey(lifecycleUid), { owner: audit.owner, actor: audit.actor, mintedBy: audit.mintedBy });
-        return "won";
-    }
-    catch (e) {
-        if (isCasLoss(e))
-            return "burned";
-        throw e;
-    }
+    return uidTryReserve(transportOf(reg), lifecycleUid, audit);
 }
 /** Reserve a fresh lifecycle UID space-globally (§13.1): mint a CSPRNG candidate, win its
  *  create-only reservation, and on a collision burn the candidate and draw another. At ≥128
  *  bits a collision is effectively adversarial, so a handful of retries is a correctness
  *  formality, not a capacity plan; exhausting them refuses loudly. */
 export async function reserveLifecycleUid(reg, audit) {
-    for (let i = 0; i < 4; i++) {
-        const candidate = mintLifecycleUid();
-        if ((await tryReserveUid(reg, candidate, audit)) === "won")
-            return candidate;
-    }
-    throw new EpEnvelopeError("internal", "four fresh 128-bit UID candidates collided with existing reservations; that is not chance; inspect the uid.> family (SPEC 13.1)");
-}
-const GATE_STATES = new Set(["open", "frozen", "retired"]);
-const GATE_OP_KINDS = new Set(["activation", "takeover", "registration", "retirement"]);
-function gateKey(lifecycleUid) {
-    return `gate.${assertLifecycleToken(lifecycleUid)}`;
-}
-function parseGate(raw, key, lifecycleUid) {
-    let o;
-    try {
-        o = JSON.parse(dec.decode(raw));
-    }
-    catch {
-        throw new EpEnvelopeError("internal", `the issuance gate ${key} is not JSON; garbled trusted-path state never authorizes (SPEC 13.1)`);
-    }
-    if (!isRec(o))
-        throw new EpEnvelopeError("internal", `the issuance gate ${key} is not an object`);
-    for (const k of Object.keys(o))
-        if (k !== "lifecycleUid" && k !== "state" && k !== "generation" && k !== "op")
-            throw new EpEnvelopeError("internal", `the issuance gate ${key} carries the unknown field "${k}" (closed schema, SPEC 13.1)`);
-    if (o.lifecycleUid !== lifecycleUid || typeof o.state !== "string" || !GATE_STATES.has(o.state) || !uint(o.generation))
-        throw new EpEnvelopeError("internal", `the issuance gate ${key} does not validate (uid/state/generation); a garbled or key-mismatched gate never authorizes (SPEC 13.1)`);
-    if ((o.state === "frozen" || o.state === "retired") && !isRec(o.op))
-        throw new EpEnvelopeError("internal", `the issuance gate ${key} is ${o.state} without its durable op intent (SPEC 13.1: a frozen gate is op-bound, and a retired gate retains its terminalizing op)`);
-    if (o.state === "open" && o.op !== undefined)
-        throw new EpEnvelopeError("internal", `the issuance gate ${key} is open but carries an op intent (SPEC 13.1: open gates are not op-bound)`);
-    if (o.op !== undefined) {
-        const op = o.op;
-        for (const k of Object.keys(op))
-            if (k !== "opId" && k !== "kind" && k !== "successor")
-                throw new EpEnvelopeError("internal", `the issuance gate ${key} op intent carries the unknown field "${k}" (closed schema)`);
-        if (typeof op.opId !== "string" || typeof op.kind !== "string" || !GATE_OP_KINDS.has(op.kind))
-            throw new EpEnvelopeError("internal", `the issuance gate ${key} op intent does not validate (SPEC 13.1)`);
-        // STATE x KIND invariant (SPEC 13.1 per-kind transition sets): only an activation orphan or
-        // a retirement produces a `retired` gate, so a persisted `retired` gate carrying a
-        // takeover/registration kind is IMPOSSIBLE state — refuse it at parse, never let the terminal
-        // idempotence path return it as a settled success (fail-closed on corruption, not open).
-        if (o.state === "retired" && op.kind !== "activation" && op.kind !== "retirement")
-            throw new EpEnvelopeError("internal", `the issuance gate ${key} is retired under a ${op.kind} op; only an activation orphan or a retirement terminalizes (SPEC 13.1); impossible persisted state, refused`);
-        if (op.successor !== undefined && (typeof op.successor !== "string" || op.successor.length === 0 || (op.kind !== "takeover" && op.kind !== "registration")))
-            throw new EpEnvelopeError("internal", `the issuance gate ${key} op intent carries an invalid successor (SPEC 13.1: only takeover/registration stage successors, and the summary is a non-empty token)`);
-        try {
-            assertLifecycleToken(op.opId);
-        }
-        catch {
-            throw new EpEnvelopeError("internal", `the issuance gate ${key} op intent carries a malformed opId (SPEC 13.1)`);
-        }
-    }
-    return o;
+    return uidReserveFresh(transportOf(reg), audit);
 }
+// ---- the issuance-gate CAS primitives (auth store, agent family `gate.<lifecycleUid>`) -------
+// The gate row schema (`EpGateRow`), key builder, and boundary parser live in the shared §13.1
+// STATE GRAMMAR in @cotal-ai/core (`lifecycle-state.ts`), imported above as
+// `gateKey`/`parseGate`; the type is re-exported beside `LifecycleMapping`.
 /** Observe the gate (the candidate read feeding a revision-pinned CAS; the auth store is
  *  leader-only by shape, `allow_direct=false`). A DEL/PURGE marker refuses loudly. */
 export async function observeGate(reg, lifecycleUid) {
-    const { authKv } = internals(reg);
-    const key = gateKey(lifecycleUid);
-    const entry = await authKv.get(key);
-    if (!entry)
-        return undefined;
-    if (entry.operation !== "PUT")
-        throw new EpEnvelopeError("failed-precondition", `the issuance gate ${key} carries a ${entry.operation} marker; a gate is never deleted (a deletion is corruption, not absence, SPEC 13.12)`);
-    return { row: parseGate(entry.value, key, lifecycleUid), revision: entry.revision };
-}
-async function putGate(authKv, lifecycleUid, row, expectedRevision) {
-    try {
-        return await authKv.put(gateKey(lifecycleUid), enc.encode(JSON.stringify(row)), { previousSeq: expectedRevision });
-    }
-    catch (e) {
-        if (isRawCasLoss(e))
-            throw new EpEnvelopeError("conflict", `the issuance gate CAS for ${gateKey(lifecycleUid)} lost (expected revision ${expectedRevision}); re-read and re-decide (SPEC 13.8)`);
-        throw e;
-    }
+    return gateObserve(transportOf(reg), lifecycleUid);
 }
 /** Create the gate FROZEN under its operation's durable intent (create-only: conflicts on an
  *  existing gate or a deletion marker). A gate is BORN only under an ACTIVATION intent (SPEC
@@ -503,37 +296,12 @@ async function putGate(authKv, lifecycleUid, row, expectedRevision) {
  *  unreserved UID would mint outside the never-reuse fence. Born unmintable at generation 0:
  *  no credential can be released until the operation's own reopen (§13.1 activation saga). */
 export async function createGateFrozen(reg, args) {
-    const { authKv, recordsKv } = internals(reg);
-    if (args.op.kind !== "activation")
-        throw new EpEnvelopeError("failed-precondition", `an issuance gate is born only under an activation intent, not "${String(args.op.kind)}" (SPEC 13.1: other operations freeze an existing open gate)`);
-    const reservation = await recordsKv.get(uidKey(assertLifecycleToken(args.lifecycleUid)));
-    if (!reservation)
-        throw new EpEnvelopeError("failed-precondition", `no uid reservation exists for ${args.lifecycleUid}; the reservation is won BEFORE any gate or head write (SPEC 13.1)`);
-    if (reservation.operation !== "PUT")
-        throw new EpEnvelopeError("failed-precondition", `the uid reservation for ${args.lifecycleUid} carries a ${reservation.operation} marker; a reservation is never deleted (corruption, not absence, SPEC 13.12)`);
-    const row = { lifecycleUid: args.lifecycleUid, state: "frozen", generation: 0, op: { opId: assertLifecycleToken(args.op.opId), kind: "activation" } };
-    const revision = await putGate(authKv, args.lifecycleUid, row, 0);
-    return { row, revision };
+    return gateCreateFrozen(transportOf(reg), args);
 }
 /** CAS the gate `open → frozen` carrying the freezing operation's durable intent, at the
  *  observed revision. The bar of every barrier: a staged mint's own finalize CAS loses. */
 export async function freezeGate(reg, args) {
-    const { authKv } = internals(reg);
-    if (args.op.successor !== undefined && args.op.kind === "retirement")
-        throw new EpEnvelopeError("failed-precondition", "a retirement freeze carries no successor (SPEC 13.1: a retirement has none)");
-    if (args.op.successor !== undefined && args.op.successor.length === 0)
-        throw new EpEnvelopeError("failed-precondition", "the freeze carries an empty successor token; a summary token is a non-empty stage.<opId> reference or absent (SPEC 13.1); validate before the CAS, never persist corruption");
-    const current = await observeGate(reg, args.lifecycleUid);
-    if (current === undefined)
-        throw new EpEnvelopeError("not-found", `the issuance gate for ${args.lifecycleUid} does not exist (SPEC 13.1)`);
-    if (current.row.state !== "open")
-        throw new EpEnvelopeError("failed-precondition", `the issuance gate for ${args.lifecycleUid} is "${current.row.state}", not open; only an open gate freezes (a frozen/retired gate belongs to its own operation, SPEC 13.1)`);
-    const op = { opId: assertLifecycleToken(args.op.opId), kind: args.op.kind };
-    if (args.op.successor !== undefined)
-        op.successor = args.op.successor;
-    const row = { lifecycleUid: current.row.lifecycleUid, state: "frozen", generation: current.row.generation, op };
-    const revision = await putGate(authKv, args.lifecycleUid, row, args.revision);
-    return { row, revision };
+    return gateFreeze(transportOf(reg), args);
 }
 /** CAS the gate `frozen → open` at the NEXT generation — op-pinned: only the freeze's own
  *  operation (the same `opId`) reopens, as its barrier's final step; a stranger or a stale
@@ -541,19 +309,7 @@ export async function freezeGate(reg, args) {
  *  belongs to activation, takeover, and a registration abort — NEVER retirement (a
  *  retirement freeze never reopens; its only exit is the terminal). */
 export async function reopenGate(reg, args) {
-    const { authKv } = internals(reg);
-    const current = await observeGate(reg, args.lifecycleUid);
-    if (current === undefined)
-        throw new EpEnvelopeError("not-found", `the issuance gate for ${args.lifecycleUid} does not exist (SPEC 13.1)`);
-    if (current.row.state !== "frozen")
-        throw new EpEnvelopeError("failed-precondition", `the issuance gate for ${args.lifecycleUid} is "${current.row.state}", not frozen; there is no freeze to reopen (SPEC 13.1)`);
-    if (current.row.op?.opId !== args.opId)
-        throw new EpEnvelopeError("permission-denied", `the issuance gate for ${args.lifecycleUid} is frozen by operation ${current.row.op?.opId ?? "<none>"}, not ${args.opId}; only the completing operation reopens its own freeze (SPEC 13.1)`);
-    if (current.row.op.kind === "retirement")
-        throw new EpEnvelopeError("failed-precondition", `the issuance gate for ${args.lifecycleUid} is frozen by a RETIREMENT; a retirement freeze never reopens (SPEC 13.1: its only exit is the terminal)`);
-    const row = { lifecycleUid: current.row.lifecycleUid, state: "open", generation: current.row.generation + 1 };
-    const revision = await putGate(authKv, args.lifecycleUid, row, args.revision);
-    return { row, revision };
+    return gateReopen(transportOf(reg), args);
 }
 /** CAS the gate `frozen → retired` (terminal; never reopened) — op-pinned like the reopen. The
  *  activation saga uses it to terminalize a head-CAS loser's orphan gate; the retirement
@@ -562,24 +318,7 @@ export async function reopenGate(reg, args) {
  *  reopening, never by the terminal. Idempotence at `retired` is SAME-OP idempotence: a
  *  stranger's retry on a terminal gate refuses, it does not "succeed". */
 export async function retireGate(reg, args) {
-    const { authKv } = internals(reg);
-    const current = await observeGate(reg, args.lifecycleUid);
-    if (current === undefined)
-        throw new EpEnvelopeError("not-found", `the issuance gate for ${args.lifecycleUid} does not exist (SPEC 13.1)`);
-    if (current.row.state === "retired") {
-        if (current.row.op?.opId !== args.opId)
-            throw new EpEnvelopeError("permission-denied", `the issuance gate for ${args.lifecycleUid} was terminalized by operation ${current.row.op?.opId ?? "<none>"}, not ${args.opId}; terminal idempotence is same-op idempotence (SPEC 13.1)`);
-        return current; // idempotent terminal, same op
-    }
-    if (current.row.state !== "frozen")
-        throw new EpEnvelopeError("failed-precondition", `the issuance gate for ${args.lifecycleUid} is "${current.row.state}"; only a frozen gate terminalizes (freeze first; the bar precedes the terminal, SPEC 13.1)`);
-    if (current.row.op?.opId !== args.opId)
-        throw new EpEnvelopeError("permission-denied", `the issuance gate for ${args.lifecycleUid} is frozen by operation ${current.row.op?.opId ?? "<none>"}, not ${args.opId}; only the owning operation terminalizes its freeze (SPEC 13.1)`);
-    if (current.row.op.kind !== "activation" && current.row.op.kind !== "retirement")
-        throw new EpEnvelopeError("failed-precondition", `the issuance gate for ${args.lifecycleUid} is frozen by a ${current.row.op.kind}; only an activation orphan or a retirement terminalizes (a ${current.row.op.kind} aborts by reopening, SPEC 13.1)`);
-    const row = { lifecycleUid: current.row.lifecycleUid, state: "retired", generation: current.row.generation, op: current.row.op };
-    const revision = await putGate(authKv, args.lifecycleUid, row, args.revision);
-    return { row, revision };
+    return gateRetire(transportOf(reg), args);
 }
 // ---- the activation saga (§13.1: reserve → gate frozen → head CAS → reopen LAST) -------------
 /**
@@ -596,48 +335,7 @@ export async function retireGate(reg, args) {
  * minting under the reopened gate before this becomes reachable.
  */
 export async function activateLifecycle(reg, args) {
-    const { recordsKv } = internals(reg);
-    const { owner, actor } = args;
-    if (typeof args.managerInstance !== "string" || args.managerInstance.length === 0)
-        throw new EpEnvelopeError("failed-precondition", "activateLifecycle requires a managerInstance (the minting authority)");
-    const current = await readHeadCandidate(recordsKv, owner, actor);
-    if (current !== undefined && current.mapping.state === "active")
-        throw new EpEnvelopeError("already-exists", `lifecycle "${owner}/${actor}" is already active (uid ${current.mapping.lifecycleUid}); a takeover advances the epoch through its barrier, it does not re-activate (SPEC 13.1)`);
-    if (current !== undefined && current.mapping.state === "retiring")
-        throw new EpEnvelopeError("failed-precondition", `lifecycle "${owner}/${actor}" is retiring (op ${current.mapping.op?.opId}); a retiring alias is not replaceable until its barrier completes (SPEC 13.1)`);
-    const opId = mintLifecycleUid();
-    // 1. Win the space-global UID reservation.
-    const lifecycleUid = await reserveLifecycleUid(reg, { owner, actor, mintedBy: args.managerInstance });
-    // 2. Create the gate FROZEN under this activation's durable intent (unmintable from birth).
-    const gate = await createGateFrozen(reg, { lifecycleUid, op: { opId, kind: "activation" } });
-    // 3. CAS the alias head (create-only for virgin; revision-pinned over the retired predecessor).
-    const mapping = { owner, actor, lifecycleUid, managerInstance: args.managerInstance, processEpoch: 1, state: "active" };
-    let revision;
-    try {
-        revision = current === undefined
-            ? await createRecordEntry(recordsKv, headKey(owner, actor), mapping)
-            : await updateRecordEntry(recordsKv, headKey(owner, actor), mapping, current.revision);
-    }
-    catch (e) {
-        if (isCasLoss(e)) {
-            // The loser terminalizes ITS OWN orphan gate; its UID stays burned (never deleted, never
-            // reused). A cleanup failure is NEVER swallowed as success: the caller gets the durable
-            // coordinates and resumes the SAME op (resumeActivation) to finish the terminalization.
-            try {
-                await retireGate(reg, { lifecycleUid, revision: gate.revision, opId });
-            }
-            catch (cleanup) {
-                // The resume coordinates ride STRUCTURED details (never only the prose message): a
-                // recovery path reads {uid, opId} from `details`, it does not parse a sentence.
-                throw new EpEnvelopeError("unavailable", `lifecycle activation for "${owner}/${actor}" lost the head CAS AND terminalizing its orphan gate failed; the uid ${lifecycleUid} is burned but its gate is still frozen by op ${opId}; resume the same op with resumeActivation: ${cleanup?.message ?? String(cleanup)}`, [{ kind: "resume-activation", owner, actor, lifecycleUid, opId }]);
-            }
-            throw new EpEnvelopeError("conflict", `lifecycle activation for "${owner}/${actor}" lost the head CAS (a concurrent activation won); this saga's uid ${lifecycleUid} is burned and its gate terminalized (SPEC 13.1)`);
-        }
-        throw e;
-    }
-    // 4. Reopen the gate at its first mintable generation — the saga's LAST step.
-    await reopenGate(reg, { lifecycleUid, revision: gate.revision, opId });
-    return { mapping, revision, opId };
+    return runActivationSaga(transportOf(reg), args);
 }
 /**
  * Activate the alias `(owner, actor)` AT THE CALLER'S uid — the production ISSUANCE activation
@@ -655,90 +353,7 @@ export async function activateLifecycle(reg, args) {
  * held by a FOREIGN alias, a foreign-operation freeze, and a terminally retired gate.
  */
 export async function activateLifecycleAtUid(reg, args) {
-    const { recordsKv } = internals(reg);
-    const { owner, actor, lifecycleUid } = args;
-    assertLifecycleToken(lifecycleUid);
-    if (typeof args.managerInstance !== "string" || args.managerInstance.length === 0)
-        throw new EpEnvelopeError("failed-precondition", "activateLifecycleAtUid requires a managerInstance (the minting authority)");
-    const current = await readHeadCandidate(recordsKv, owner, actor);
-    if (current !== undefined && current.mapping.state === "active" && current.mapping.lifecycleUid !== lifecycleUid)
-        throw new EpEnvelopeError("already-exists", `lifecycle "${owner}/${actor}" is active at uid ${current.mapping.lifecycleUid}, not this grant's ${lifecycleUid}; retiring a live predecessor is the takeover barrier's job and production issuance does not run it (R1) - despawn/retire the predecessor first, or grant a fresh actor name (SPEC 13.1)`);
-    if (current !== undefined && current.mapping.state === "retiring")
-        throw new EpEnvelopeError("failed-precondition", `lifecycle "${owner}/${actor}" is retiring (op ${current.mapping.op?.opId}); a retiring alias is not replaceable until its barrier completes (SPEC 13.1)`);
-    const headIsOurs = current !== undefined && current.mapping.state === "active"; // same uid, by the guard above
-    // 1. The uid reservation: win it, or adopt a prior attempt's — SAME alias only.
-    if (!headIsOurs && (await tryReserveUid(reg, lifecycleUid, { owner, actor, mintedBy: args.managerInstance })) === "burned") {
-        const res = await readUidReservation(reg, lifecycleUid);
-        if (res === undefined || res.owner !== owner || res.actor !== actor)
-            throw new EpEnvelopeError("permission-denied", `uid ${lifecycleUid} is reserved by ${res ? `"${res.owner}/${res.actor}"` : "an unreadable reservation"}, not "${owner}/${actor}"; a grant's uid is never adopted across aliases (SPEC 13.1)`);
-    }
-    // 2. The activation gate: create frozen, or adopt OUR prior attempt's frozen activation gate
-    //    (the reservation above already binds this uid to this alias, so any activation freeze on
-    //    it is this alias's own activation). A retry loop absorbs the sibling-race CAS losses.
-    for (let attempt = 0;; attempt++) {
-        if (attempt > 4)
-            throw new EpEnvelopeError("unavailable", `activation for "${owner}/${actor}" at uid ${lifecycleUid} keeps losing its gate/head CASes to concurrent movement; re-read and re-decide (SPEC 13.1)`);
-        let gate = await observeGate(reg, lifecycleUid);
-        let opId;
-        if (gate === undefined) {
-            try {
-                gate = await createGateFrozen(reg, { lifecycleUid, op: { opId: mintLifecycleUid(), kind: "activation" } });
-            }
-            catch (e) {
-                if (isCasLoss(e))
-                    continue; // a sibling created it; re-observe and adopt
-                throw e;
-            }
-            opId = gate.row.op.opId;
-        }
-        else if (gate.row.state === "frozen") {
-            if (gate.row.op?.kind !== "activation")
-                throw new EpEnvelopeError("failed-precondition", `the issuance gate for ${lifecycleUid} is frozen by a ${gate.row.op?.kind ?? "<unknown>"} (op ${gate.row.op?.opId ?? "<none>"}); a barrier is in flight - issuance activation neither adopts nor overrides it (SPEC 13.1)`);
-            opId = gate.row.op.opId;
-        }
-        else if (gate.row.state === "retired") {
-            throw new EpEnvelopeError("permission-denied", `uid ${lifecycleUid} has a terminally retired issuance gate; a burned uid never re-activates - re-grant the actor for a fresh incarnation (SPEC 13.1)`);
-        }
-        else {
-            // Open gate: the saga writes the head BEFORE its reopen, so an open gate with the head
-            // active at our uid is a COMPLETED activation; anything else is foreign movement.
-            const head = await readHeadCandidate(recordsKv, owner, actor);
-            if (head !== undefined && head.mapping.state === "active" && head.mapping.lifecycleUid === lifecycleUid)
-                return;
-            throw new EpEnvelopeError("failed-precondition", `the issuance gate for ${lifecycleUid} is open but the head for "${owner}/${actor}" is ${head === undefined ? "absent" : `${head.mapping.state} at ${head.mapping.lifecycleUid}`}; an activation reopens only AFTER its head CAS - this is foreign movement or corruption, refuse (SPEC 13.1/13.12)`);
-        }
-        // 3. The head CAS (create-only for virgin; revision-pinned over a retired predecessor). A
-        //    loss converges if the sibling won for the SAME uid, refuses on a foreign winner.
-        if (!headIsOurs) {
-            const mapping = { owner, actor, lifecycleUid, managerInstance: args.managerInstance, processEpoch: 1, state: "active" };
-            try {
-                if (current === undefined)
-                    await createRecordEntry(recordsKv, headKey(owner, actor), mapping);
-                else
-                    await updateRecordEntry(recordsKv, headKey(owner, actor), mapping, current.revision);
-            }
-            catch (e) {
-                if (!isCasLoss(e))
-                    throw e;
-                const head = await readHeadCandidate(recordsKv, owner, actor);
-                if (!(head !== undefined && head.mapping.state === "active" && head.mapping.lifecycleUid === lifecycleUid))
-                    throw new EpEnvelopeError("conflict", `activation for "${owner}/${actor}" at uid ${lifecycleUid} lost the head CAS to a foreign movement (now ${head === undefined ? "absent" : `${head.mapping.state} at ${head.mapping.lifecycleUid}`}); re-grant raced this exchange - re-exchange (SPEC 13.1)`);
-            }
-        }
-        // 4. Reopen the gate — the saga's LAST step. A loss to the sibling's reopen is convergence.
-        try {
-            await reopenGate(reg, { lifecycleUid, revision: gate.revision, opId });
-            return;
-        }
-        catch (e) {
-            const g = await observeGate(reg, lifecycleUid);
-            if (g !== undefined && g.row.state === "open")
-                return; // the sibling finished it
-            if (e instanceof EpEnvelopeError && e.code === "conflict")
-                continue; // revision moved; re-observe
-            throw e;
-        }
-    }
+    return runActivationSagaAtUid(transportOf(reg), args);
 }
 /**
  * Resume a crashed activation saga from its durable coordinates (`{alias, lifecycleUid, opId}`,
@@ -751,35 +366,7 @@ export async function activateLifecycleAtUid(reg, args) {
  * what it did.
  */
 export async function resumeActivation(reg, args) {
-    const { recordsKv } = internals(reg);
-    const head = await readHeadCandidate(recordsKv, args.owner, args.actor);
-    const gate = await observeGate(reg, args.lifecycleUid);
-    const won = head !== undefined && head.mapping.state === "active" && head.mapping.lifecycleUid === args.lifecycleUid;
-    if (gate === undefined) {
-        // Crash before step 2: nothing durable beyond the reservation; the uid stays burned.
-        if (won)
-            throw new EpEnvelopeError("internal", `the head names uid ${args.lifecycleUid} but its gate does not exist; an active head without a gate is corruption (SPEC 13.1)`);
-        return "already-settled";
-    }
-    if (gate.row.state === "retired") {
-        // Terminal idempotence is SAME-OP idempotence: a stranger cannot claim another
-        // operation's terminal as its own settlement.
-        if (gate.row.op?.opId !== args.opId)
-            throw new EpEnvelopeError("permission-denied", `the gate for uid ${args.lifecycleUid} was terminalized by operation ${gate.row.op?.opId ?? "<none>"}, not ${args.opId} (SPEC 13.1)`);
-        return "already-settled";
-    }
-    if (gate.row.state === "open") {
-        if (!won)
-            throw new EpEnvelopeError("internal", `the gate for uid ${args.lifecycleUid} is open but the head does not name it; an open gate without its active head is corruption (SPEC 13.1)`);
-        return "already-settled";
-    }
-    // frozen: only OUR op may advance it (reopen/retire are op-pinned and will refuse a stranger).
-    if (won) {
-        await reopenGate(reg, { lifecycleUid: args.lifecycleUid, revision: gate.revision, opId: args.opId });
-        return "completed";
-    }
-    await retireGate(reg, { lifecycleUid: args.lifecycleUid, revision: gate.revision, opId: args.opId });
-    return "terminalized";
+    return resumeActivationSaga(transportOf(reg), args);
 }
 // ---- the leader-served mapping reader (the currency seam) ------------------------------------
 /**