@cotal-ai/auth 0.89.0 → 0.90.0

package/dist/service-custody.js

@@ -0,0 +1,667 @@
+import { EpEnvelopeError, assertLifecycleToken, canonicalJson, epAuthBucket, isAccountNkey, isCasLoss, isContractDigest, lifecycleHeadKey, mintLifecycleUid, parseNativeUidCustody, recordsBucket, uidReservationKey, } from "@cotal-ai/core";
+import { registryStores } from "./lifecycle-registry.js";
+import { serviceGateRows } from "./native-service-gate.js";
+import { readNativeServiceName } from "./native-service-name.js";
+import { genuinePlaneHold } from "./plane-claim.js";
+import { ROOT_CREDENTIAL_TTL_MS } from "./root-credential.js";
+import { encodeRoundTrip, parseServiceHead, parseServiceNativeGate, parseServiceNativeRoot, serviceCustodyIdentity, } from "./service-custody-shapes.js";
+import { readRegistryServiceRoot } from "./service-root-reader.js";
+/** One broker request, clipped to the remaining original deadline. */
+export const S1_REQUEST_TIMEOUT_MS = 5_000;
+/** Re-reads after a CAS loss before a step holds. */
+export const S1_MAX_CAS_REDECIDE = 4;
+/** Re-pins of a byte-identical open native gate after a sibling's touch. */
+export const S1_MAX_GATE_REPIN = 8;
+/** Classify-then-retry rounds for a write whose outcome is unknown. */
+export const S1_MAX_UNKNOWN_ROUNDS = 3;
+const HOSTS = new WeakMap();
+const BOOTSTRAPS = new WeakMap();
+const CANCELS = new WeakMap();
+const enc = new TextEncoder();
+const dec = new TextDecoder("utf-8", { fatal: true });
+function denied(detail) {
+    throw new EpEnvelopeError("permission-denied", `service custody ${detail}`);
+}
+/** The one trusted composition: a genuine registry, a genuine hold for the same space, the
+ *  configured account, and a fatal latch only the returned `trip` sets. The held check is the
+ *  closure captured when the hold was acquired, never the hold's mutable `guard` field. */
+export function openServiceCustodyHost(opts) {
+    const { space } = registryStores(opts.registry);
+    const genuine = genuinePlaneHold(opts.hold);
+    if (genuine === undefined)
+        return denied("requires a plane claim hold this process acquired");
+    if (genuine.space !== space)
+        denied(`hold belongs to another space than the registry's "${space}"`);
+    if (typeof opts.accountPublicKey !== "string" || !isAccountNkey(opts.accountPublicKey))
+        denied("requires the configured account public key");
+    const internals = { registry: opts.registry, assertHeld: genuine.assertHeld, space, accountPublicKey: opts.accountPublicKey };
+    const host = Object.freeze({ space, accountPublicKey: opts.accountPublicKey });
+    HOSTS.set(host, internals);
+    return { host, trip: (reason) => { if (internals.tripped === undefined)
+            internals.tripped = reason; } };
+}
+function material(host, reservation) {
+    const h = HOSTS.get(host);
+    if (h === undefined)
+        return denied("requires a sealed host");
+    const lifecycleUid = assertLifecycleToken(reservation?.native?.lifecycleUid);
+    const uidBytes = enc.encode(canonicalJson(reservation));
+    const custody = parseNativeUidCustody(uidBytes, lifecycleUid);
+    if (custody.kind !== "service")
+        return denied("requires a service UID reservation");
+    if (custody.uid.native.accountPublicKey !== h.accountPublicKey || custody.uid.native.space !== h.space)
+        denied("reservation belongs to another account or space than the host");
+    const id = serviceCustodyIdentity(custody.uid);
+    const binding = { accountPublicKey: h.accountPublicKey, space: h.space, owner: id.owner, endpoint: id.endpoint,
+        instanceId: id.instanceId, lifecycleUid, assignmentDigest: id.digest };
+    return { host: h, id, uidBytes, binding, epgate: serviceGateRows(h.registry, binding) };
+}
+/** Seal the original admitted bootstrap material once. `notAfterMs` is the creation authority's
+ *  fixed deadline; the writer never defaults, extends or resets it. */
+export function sealServiceBootstrapIntent(host, input) {
+    const m = material(host, input.reservation);
+    if (!Number.isSafeInteger(input.notAfterMs) || input.notAfterMs <= 0)
+        denied("bootstrap intent requires an explicit positive notAfterMs");
+    const intent = Object.freeze({ lifecycleUid: m.id.lifecycleUid, notAfterMs: input.notAfterMs });
+    BOOTSTRAPS.set(intent, { ...m, notAfterMs: input.notAfterMs });
+    return intent;
+}
+/** Seal an accepted cancellation of this exact reservation. The intent itself does not expire. */
+export function sealServiceCancelIntent(host, input) {
+    const m = material(host, input.reservation);
+    const opId = assertLifecycleToken(input.opId, "opId");
+    if (typeof input.requestDigest !== "string" || !isContractDigest(input.requestDigest))
+        denied("cancel intent requires a request digest");
+    const intent = Object.freeze({ lifecycleUid: m.id.lifecycleUid, opId });
+    CANCELS.set(intent, { ...m, op: { kind: "service-cancel", opId, requestDigest: input.requestDigest } });
+    return intent;
+}
+// ---- held control flow, readiness and bounded broker access ----------------------------------
+class Held extends Error {
+    reason;
+    step;
+    constructor(reason, step, detail) {
+        super(detail);
+        this.reason = reason;
+        this.step = step;
+    }
+}
+function held(reason, step, detail = reason) {
+    throw new Held(reason, step, detail);
+}
+const message = (e) => (e instanceof Error ? e.message : String(e));
+function context(h, deadlineMs) {
+    const stores = registryStores(h.registry);
+    return { h, jsm: stores.jsm, kv: { records: stores.recordsKv, auth: stores.authKv },
+        bucket: { records: recordsBucket(h.space), auth: epAuthBucket(h.space) }, deadlineMs, deadlineReason: "deadline", step: "open" };
+}
+/** Bootstrap only, after the plan step: `liveUntilMs = min(deadline, plan.expMs)` bounds every
+ *  later request. Cancellation keeps its own deadline, so an accepted cancellation can proceed
+ *  after the root expires. */
+function clipToPlan(ctx, plan) {
+    if (plan.expMs < ctx.deadlineMs) {
+        ctx.deadlineMs = plan.expMs;
+        ctx.deadlineReason = "plan-expired";
+    }
+}
+/** Run one broker request with a timeout of `min(S1_REQUEST_TIMEOUT_MS, remaining)`. A request
+ *  is never started at or past the live-authority bound, and a request still in flight when that
+ *  bound is reached ends the step held under the bound's reason. The abandoned request's
+ *  settlement is still handled. */
+async function bounded(ctx, start) {
+    const remaining = ctx.deadlineMs - Date.now(), ms = Math.min(S1_REQUEST_TIMEOUT_MS, remaining);
+    const bound = ctx.deadlineReason === "plan-expired" ? "the RootPlan expiry" : "the original deadline";
+    if (ms <= 0)
+        return held(ctx.deadlineReason, ctx.step, `${bound} has passed; no request starts`);
+    let timer;
+    const timeout = new Promise((r) => { timer = setTimeout(() => r({ ok: false, timedOut: true }), ms); });
+    const settled = start().then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }));
+    let r;
+    try {
+        r = await Promise.race([settled, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!r.ok && "timedOut" in r && ms === remaining)
+        held(ctx.deadlineReason, ctx.step, `${bound} was reached during a request`);
+    return r;
+}
+function checkSync(ctx) {
+    if (ctx.h.tripped !== undefined)
+        held("readiness", ctx.step, `the host is fenced: ${ctx.h.tripped}`);
+}
+/** Awaited current-hold check before a write. */
+async function readyBefore(ctx) {
+    checkSync(ctx);
+    const r = await bounded(ctx, () => ctx.h.assertHeld("before"));
+    if (!r.ok)
+        held("readiness", ctx.step, "timedOut" in r ? "the plane claim check timed out" : message(r.error));
+    checkSync(ctx);
+}
+/** Awaited current-hold re-read after a write, then the latch. Any loss here means the write may
+ *  have landed under a lost or fenced host: the step reports held, never success. */
+async function readyAfter(ctx) {
+    const r = await bounded(ctx, () => ctx.h.assertHeld("after"));
+    if (!r.ok)
+        held("post-write-readiness", ctx.step, "timedOut" in r ? "the post-write plane claim check timed out" : message(r.error));
+    if (ctx.h.tripped !== undefined)
+        held("post-write-readiness", ctx.step, `the host was fenced during the write: ${ctx.h.tripped}`);
+}
+/** Leader-served last message for one key. `absent` means the subject has no message at all. */
+async function leader(ctx, bucket, key) {
+    const name = ctx.bucket[bucket];
+    const r = await bounded(ctx, () => ctx.jsm.streams.getMessage(`KV_${name}`, { last_by_subj: `$KV.${name}.${key}` }));
+    if (!r.ok) {
+        if ("error" in r && r.error?.code === 10037)
+            return { state: "absent" };
+        return held("unavailable", ctx.step, "timedOut" in r ? `the leader read of ${key} timed out` : message(r.error));
+    }
+    const m = r.value;
+    if (!m)
+        return { state: "absent" };
+    const op = m.header?.get("KV-Operation");
+    if (op)
+        return { state: "marker", op };
+    try {
+        return { state: "value", bytes: m.data, value: JSON.parse(dec.decode(m.data)), revision: m.seq };
+    }
+    catch {
+        return { state: "malformed", revision: m.seq };
+    }
+}
+const same = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+/** One conditional write under readiness. Returns the landed revision, or `moved` when the key no
+ *  longer matches this step's decision (the caller re-reads and re-decides). An unknown outcome
+ *  is classified by an immediate leader read before anything is reissued; only exact absence for
+ *  a create, or the exact preimage at the pinned revision for a CAS, permits the same write again.
+ *  `precheck` runs before every attempt, including each reissue. */
+async function write(ctx, bucket, key, bytes, expect, precheck) {
+    for (let round = 0; round < S1_MAX_UNKNOWN_ROUNDS; round++) {
+        if (precheck)
+            await precheck();
+        await readyBefore(ctx);
+        const kv = ctx.kv[bucket];
+        const r = await bounded(ctx, () => ("create" in expect ? kv.put(key, bytes, { previousSeq: 0 }) : kv.update(key, bytes, expect.revision)));
+        await readyAfter(ctx);
+        if (!r.ok && "error" in r && isCasLoss(r.error))
+            return "moved";
+        const cur = await leader(ctx, bucket, key);
+        if (cur.state === "value" && same(cur.bytes, bytes) && ("create" in expect || cur.revision !== expect.revision))
+            return cur.revision;
+        if (r.ok)
+            return "moved";
+        const retry = "create" in expect ? cur.state === "absent"
+            : cur.state === "value" && cur.revision === expect.revision && same(cur.bytes, expect.preimage);
+        if (!retry)
+            return "moved";
+    }
+    return held("unknown", ctx.step, `the outcome of the write to ${key} stayed unknown`);
+}
+/** Leader-read and classify this assignment's endpoint gate. Every endpoint-gate request is the
+ *  writer's own, so none can start after it returns. */
+async function endpoint(ctx, m) {
+    const cur = await leader(ctx, "auth", m.epgate.key);
+    if (cur.state === "absent")
+        return { kind: "absent" };
+    if (cur.state === "marker")
+        return held("endpoint-tombstone", ctx.step, `the endpoint gate carries a ${cur.op} marker`);
+    if (cur.state === "malformed")
+        return held("endpoint-malformed", ctx.step, "the endpoint gate is not JSON");
+    let row;
+    try {
+        row = m.epgate.parse(cur.bytes);
+    }
+    catch (e) {
+        if (e instanceof EpEnvelopeError && e.code === "conflict")
+            return { kind: "foreign" };
+        return held("endpoint-malformed", ctx.step, message(e));
+    }
+    const state = row.serviceAuthority.state;
+    return { kind: state === "pending-root" ? "pending" : state, row, bytes: cur.bytes, revision: cur.revision };
+}
+async function uid(ctx, m) {
+    const cur = await leader(ctx, "records", uidReservationKey(m.id.lifecycleUid));
+    if (cur.state === "absent")
+        return "absent";
+    if (cur.state === "marker")
+        return "marker";
+    if (cur.state === "malformed")
+        return "foreign";
+    try {
+        const custody = parseNativeUidCustody(cur.bytes, m.id.lifecycleUid);
+        return custody.kind === "service" && custody.uidDigest === m.id.digest ? "exact" : "foreign";
+    }
+    catch {
+        return "foreign";
+    }
+}
+async function parsed(ctx, bucket, key, parse) {
+    const cur = await leader(ctx, bucket, key);
+    if (cur.state === "absent")
+        return cur;
+    if (cur.state === "marker")
+        return { state: "marker", detail: `${key} carries a ${cur.op} marker` };
+    if (cur.state === "malformed")
+        return { state: "other", detail: `${key} is not JSON` };
+    try {
+        return { state: "value", row: parse(cur.value), bytes: cur.bytes, revision: cur.revision };
+    }
+    catch (e) {
+        return { state: "other", detail: message(e) };
+    }
+}
+const headKey = (m) => lifecycleHeadKey(m.id.owner, m.id.actor);
+const gateKey = (m) => `gate.${m.id.lifecycleUid}`;
+const rootKey = (m, credentialId) => `cred.${m.id.lifecycleUid}.${credentialId}`;
+const head = (ctx, m) => parsed(ctx, "records", headKey(m), (v) => parseServiceHead(v, m.id));
+const gate = (ctx, m) => parsed(ctx, "auth", gateKey(m), (v) => parseServiceNativeGate(v, m.id));
+const root = (ctx, m, credentialId) => parsed(ctx, "auth", rootKey(m, credentialId), (v) => parseServiceNativeRoot(v, m.id, credentialId));
+const encodeHead = (m, h) => encodeRoundTrip(h, (v) => parseServiceHead(v, m.id));
+const encodeGate = (m, g) => encodeRoundTrip(g, (v) => parseServiceNativeGate(v, m.id));
+const encodeRoot = (m, r) => encodeRoundTrip(r, (v) => parseServiceNativeRoot(v, m.id, r.credentialId));
+const rootRow = (m, plan, state) => ({
+    credentialId: plan.credentialId, holderPrincipal: m.id.holderPrincipal, lifecycleUid: m.id.lifecycleUid, sourceChain: ["root"],
+    state, exp: plan.expMs, serviceCustody: { ...m.id.mirror },
+});
+const headBase = (m) => ({ owner: m.id.owner, actor: m.id.actor, lifecycleUid: m.id.lifecycleUid, managerInstance: m.id.instanceId, processEpoch: 1, serviceCustody: { ...m.id.mirror } });
+class Stopped extends Error {
+    result;
+    constructor(result) {
+        super(result.kind);
+        this.result = result;
+    }
+}
+function stop(result) {
+    throw new Stopped(result);
+}
+async function endpointRecheck(ctx, m) {
+    const e = await endpoint(ctx, m);
+    if (e.kind === "revoked")
+        stop({ kind: "endpoint-revoked" });
+    if (e.kind === "foreign")
+        held("foreign-assignment", ctx.step, "the endpoint gate belongs to another immutable assignment");
+}
+/** Classify the head for bootstrap; cancelling stops, any non-matching head is a collision. */
+function bootstrapHead(ctx, h) {
+    if (h.state === "marker")
+        return held("head-tombstone", ctx.step, h.detail);
+    if (h.state === "other")
+        return stop({ kind: "identity-collision" });
+    if (h.state === "value" && h.row.state === "service-cancelling")
+        stop({ kind: "cancelled", opId: h.row.op.opId });
+    return h;
+}
+async function bootstrap(ctx, m) {
+    const creationOp = m.id.uid.creation.operationId;
+    await readyBefore(ctx);
+    ctx.step = "name";
+    const name = await bounded(ctx, () => readNativeServiceName(m.host.registry, { accountPublicKey: m.host.accountPublicKey, space: m.host.space }, m.id.endpoint));
+    if (!name.ok) {
+        if ("error" in name && name.error instanceof EpEnvelopeError && name.error.code === "conflict")
+            return { kind: "name-unbound" };
+        return held("unavailable", ctx.step, "timedOut" in name ? "the service name read timed out" : message(name.error));
+    }
+    if (name.value === undefined || name.value.owner !== m.id.owner)
+        return { kind: "name-unbound" };
+    ctx.step = "open";
+    await endpointRecheck(ctx, m);
+    ctx.step = "B0-uid";
+    for (let i = 0;; i++) {
+        if (i >= S1_MAX_CAS_REDECIDE)
+            held("contention", ctx.step);
+        const u = await uid(ctx, m);
+        if (u === "exact")
+            break;
+        if (u === "foreign")
+            return { kind: "uid-burned" };
+        if (u === "marker")
+            held("uid-tombstone", ctx.step, "the UID reservation carries a deletion marker");
+        await write(ctx, "records", uidReservationKey(m.id.lifecycleUid), m.uidBytes, { create: true });
+    }
+    ctx.step = "B1-endpoint";
+    for (let i = 0;; i++) {
+        if (i >= S1_MAX_CAS_REDECIDE)
+            held("contention", ctx.step);
+        const e = await endpoint(ctx, m);
+        if (e.kind === "pending" || e.kind === "approved")
+            break;
+        if (e.kind === "revoked")
+            return { kind: "endpoint-revoked" };
+        if (e.kind === "foreign")
+            held("foreign-assignment", ctx.step, "the endpoint gate belongs to another immutable assignment");
+        await write(ctx, "auth", m.epgate.key, m.epgate.pending, { create: true });
+    }
+    ctx.step = "B2-head";
+    let current;
+    for (let i = 0; current === undefined; i++) {
+        if (i >= S1_MAX_CAS_REDECIDE)
+            held("contention", ctx.step);
+        const h = bootstrapHead(ctx, await head(ctx, m));
+        if (h.state === "value") {
+            current = h.row;
+            break;
+        }
+        const creating = { ...headBase(m), state: "service-creating", op: { kind: "service-create", opId: creationOp, requestDigest: m.id.uid.creation.requestDigest }, rootPlan: null };
+        await write(ctx, "records", headKey(m), encodeHead(m, creating), { create: true });
+    }
+    if (current.state === "active")
+        return verify(ctx, m, current.currentCredentialId);
+    ctx.step = "B3-gate";
+    for (let i = 0;; i++) {
+        if (i >= S1_MAX_CAS_REDECIDE)
+            held("contention", ctx.step);
+        const g = await gate(ctx, m);
+        if (g.state === "other" || g.state === "marker")
+            held("gate-foreign", ctx.step, g.detail);
+        if (g.state === "absent") {
+            const frozen = { lifecycleUid: m.id.lifecycleUid, state: "frozen", generation: 0, serviceCustody: { ...m.id.mirror }, op: { opId: creationOp, kind: "activation" } };
+            await write(ctx, "auth", gateKey(m), encodeGate(m, frozen), { create: true });
+            continue;
+        }
+        const row = g.row;
+        if (row.state === "open")
+            break;
+        if (row.op.kind === "service-cancel")
+            return { kind: "cancelled", opId: row.op.opId };
+        if (row.op.opId !== creationOp || row.generation !== 0)
+            held("gate-foreign", ctx.step, "the frozen native gate belongs to another operation");
+        ctx.step = "B4-open";
+        const open = { lifecycleUid: m.id.lifecycleUid, state: "open", generation: 1, serviceCustody: { ...m.id.mirror } };
+        await write(ctx, "auth", gateKey(m), encodeGate(m, open), { revision: g.revision, preimage: g.bytes });
+        ctx.step = "B3-gate";
+    }
+    // Endpoint rechecks before B5, B6 and B8 run once per step and again before every write attempt.
+    const recheck = () => endpointRecheck(ctx, m);
+    ctx.step = "B5-plan";
+    await recheck();
+    let plan;
+    for (let i = 0; plan === undefined; i++) {
+        if (i >= S1_MAX_CAS_REDECIDE)
+            held("contention", ctx.step);
+        const h = bootstrapHead(ctx, await head(ctx, m));
+        if (h.state === "absent")
+            held("head-vanished", ctx.step, "the creating head is no longer readable");
+        if (h.row.state === "active")
+            return verify(ctx, m, h.row.currentCredentialId);
+        if (h.row.state !== "service-creating")
+            return held("head-foreign", ctx.step);
+        if (h.row.rootPlan !== null) {
+            plan = h.row.rootPlan;
+            break;
+        }
+        // Fixed once: the id and expiry are chosen here and only a winning CAS persists them.
+        const candidate = { credentialId: mintLifecycleUid(), expMs: Date.now() + ROOT_CREDENTIAL_TTL_MS };
+        await write(ctx, "records", headKey(m), encodeHead(m, { ...h.row, rootPlan: candidate }), { revision: h.revision, preimage: h.bytes }, recheck);
+    }
+    clipToPlan(ctx, plan);
+    ctx.step = "B6-root";
+    await recheck();
+    for (let i = 0;; i++) {
+        if (i >= S1_MAX_CAS_REDECIDE)
+            held("contention", ctx.step);
+        if (Date.now() >= plan.expMs)
+            held("plan-expired", ctx.step, "the persisted root plan has expired; cancel this incarnation");
+        const h = bootstrapHead(ctx, await head(ctx, m));
+        if (h.state === "absent" || h.row.state !== "service-creating" || h.row.rootPlan?.credentialId !== plan.credentialId) {
+            if (h.state === "value" && h.row.state === "active")
+                return verify(ctx, m, h.row.currentCredentialId);
+            held("head-moved", ctx.step, "the creating head no longer carries this plan");
+        }
+        const r = await root(ctx, m, plan.credentialId);
+        if (r.state === "other" || r.state === "marker")
+            held("root-foreign", ctx.step, r.detail);
+        if (r.state === "value") {
+            if (r.row.exp !== plan.expMs)
+                held("root-foreign", ctx.step, "the planned root row carries another expiry");
+            // A revoked planned root is a cancellation's D4 fence; the re-read head names its operation.
+            if (r.row.state === "revoked") {
+                bootstrapHead(ctx, await head(ctx, m));
+                held("root-revoked", ctx.step, "the planned root is revoked under a creating head");
+            }
+            break;
+        }
+        await write(ctx, "auth", rootKey(m, plan.credentialId), encodeRoot(m, rootRow(m, plan, "active")), { create: true }, recheck);
+    }
+    ctx.step = "B7-finalize";
+    for (let i = 0;; i++) {
+        if (i >= S1_MAX_GATE_REPIN)
+            held("contention", ctx.step);
+        const g = await gate(ctx, m);
+        if (g.state !== "value")
+            held("gate-foreign", ctx.step, g.state === "absent" ? "the native gate vanished" : g.detail);
+        if (g.row.state === "frozen") {
+            if (g.row.op.kind === "service-cancel")
+                return { kind: "cancelled", opId: g.row.op.opId };
+            held("gate-foreign", ctx.step, "the native gate is frozen under another operation");
+        }
+        // Identical-bytes touch: a sibling's touch is benign and re-pins; anything else refuses.
+        if ((await write(ctx, "auth", gateKey(m), g.bytes, { revision: g.revision, preimage: g.bytes })) !== "moved")
+            break;
+    }
+    ctx.step = "B8-stamp";
+    await recheck();
+    for (let i = 0;; i++) {
+        if (i >= S1_MAX_CAS_REDECIDE)
+            held("contention", ctx.step);
+        if (Date.now() >= plan.expMs)
+            held("plan-expired", ctx.step, "the persisted root plan has expired; cancel this incarnation");
+        const h = bootstrapHead(ctx, await head(ctx, m));
+        if (h.state === "absent")
+            held("head-vanished", ctx.step, "the creating head is no longer readable");
+        if (h.row.state === "active") {
+            if (h.row.currentCredentialId !== plan.credentialId)
+                held("head-foreign", ctx.step, "the active head stamps another root");
+            break;
+        }
+        if (h.row.state !== "service-creating" || h.row.rootPlan?.credentialId !== plan.credentialId)
+            held("head-moved", ctx.step);
+        const active = { ...headBase(m), state: "active", currentCredentialId: plan.credentialId };
+        await write(ctx, "records", headKey(m), encodeHead(m, active), { revision: h.revision, preimage: h.bytes }, recheck);
+    }
+    return verify(ctx, m, plan.credentialId);
+}
+/** B9: the root coordinate is returned only after the unchanged active-root reader proves it and
+ *  the endpoint is not revoked. No connect-reader proof is claimed here. The already-active paths
+ *  reach this step before any plan clip, so the reader's clock and both root reads can predate the
+ *  root's expiry; a final synchronous check, with no await before the return, holds instead of
+ *  reporting a root whose expiry it observes. That is not freshness at the caller's receipt. */
+async function verify(ctx, m, credentialId) {
+    ctx.step = "B9-verify";
+    const proof = await bounded(ctx, () => readRegistryServiceRoot(m.host.registry, m.binding, credentialId, Date.now()));
+    if (!proof.ok) {
+        const h = await head(ctx, m);
+        if (h.state === "value" && h.row.state === "service-cancelling")
+            return { kind: "cancelled", opId: h.row.op.opId };
+        return held("verify", ctx.step, "timedOut" in proof ? "the root proof timed out" : message(proof.error));
+    }
+    await endpointRecheck(ctx, m);
+    const r = await root(ctx, m, credentialId);
+    if (r.state !== "value" || r.row.state !== "active")
+        held("verify", ctx.step, "the proven root row is not readable as active");
+    if (r.row.exp <= Date.now())
+        held("plan-expired", ctx.step, "the root expired before verification completed");
+    return { kind: "active", root: { credentialId, expMs: r.row.exp } };
+}
+/** Bootstrap the exact sealed reservation toward an active stamped root, resuming any durable
+ *  progress of the same creation. Every request is bounded by the intent's original deadline. */
+export async function runServiceBootstrap(intent) {
+    const m = BOOTSTRAPS.get(intent);
+    if (m === undefined)
+        return denied("requires a sealed bootstrap intent");
+    const ctx = context(m.host, m.notAfterMs);
+    try {
+        return await bootstrap(ctx, m);
+    }
+    catch (e) {
+        if (e instanceof Stopped)
+            return e.result;
+        if (e instanceof Held)
+            return { kind: "held", reason: e.reason, step: e.step, detail: e.message, opId: m.id.uid.creation.operationId };
+        return { kind: "held", reason: "unavailable", step: ctx.step, detail: message(e), opId: m.id.uid.creation.operationId };
+    }
+}
+// ---- cancellation -------------------------------------------------------------------------------
+class Refused extends Error {
+    result;
+    constructor(result) {
+        super(result.kind);
+        this.result = result;
+    }
+}
+function refuse(result) {
+    throw new Refused(result);
+}
+const sameOp = (a, b) => a.opId === b.opId && a.requestDigest === b.requestDigest;
+async function confirmCancelling(ctx, m) {
+    const h = await head(ctx, m);
+    if (h.state !== "value" || h.row.state !== "service-cancelling")
+        return held("head-moved", ctx.step, "the cancelling head is not readable");
+    if (!sameOp(h.row.op, m.op))
+        refuse({ kind: "foreign-operation", opId: h.row.op.opId });
+    return h.row;
+}
+async function cancel(ctx, m) {
+    const opId = m.op.opId;
+    await readyBefore(ctx);
+    ctx.step = "U-uid";
+    const u = await uid(ctx, m);
+    if (u === "foreign" || u === "marker")
+        return { kind: "uid-foreign" };
+    ctx.step = "L1-endpoint";
+    for (let i = 0;; i++) {
+        if (i >= S1_MAX_CAS_REDECIDE)
+            held("contention", ctx.step);
+        const e = await endpoint(ctx, m);
+        if (e.kind === "revoked")
+            break;
+        if (e.kind === "foreign")
+            held("foreign-assignment", ctx.step, "the endpoint gate belongs to another immutable assignment");
+        if (e.kind === "absent") {
+            await write(ctx, "auth", m.epgate.key, m.epgate.uncreatedFence(opId), { create: true });
+            continue;
+        }
+        const next = m.epgate.deny(e.row, opId);
+        if (next === undefined)
+            break;
+        await write(ctx, "auth", m.epgate.key, next, { revision: e.revision, preimage: e.bytes });
+    }
+    if (u === "absent") {
+        // D3: endpoint-only denied residue under this intent. No head, gate or root authority.
+        if ((await uid(ctx, m)) !== "exact")
+            return { kind: "uid-unconfirmed", held: true, opId };
+    }
+    ctx.step = "L2-head";
+    for (let i = 0;; i++) {
+        if (i >= S1_MAX_CAS_REDECIDE)
+            held("contention", ctx.step);
+        const h = await head(ctx, m);
+        if (h.state === "other" || h.state === "marker")
+            held("head-foreign", ctx.step, h.detail);
+        let next;
+        if (h.state === "absent") {
+            next = { ...headBase(m), state: "service-cancelling", op: m.op, rootPlan: null, currentCredentialId: null };
+            await write(ctx, "records", headKey(m), encodeHead(m, next), { create: true });
+            continue;
+        }
+        const row = h.row;
+        if (row.state === "service-cancelling") {
+            if (!sameOp(row.op, m.op))
+                return { kind: "foreign-operation", opId: row.op.opId };
+            break;
+        }
+        if (row.state === "service-creating") {
+            next = { ...headBase(m), state: "service-cancelling", op: m.op, rootPlan: row.rootPlan, currentCredentialId: null };
+        }
+        else {
+            // active -> cancelling: derive the preserved plan from the exact stamped root row, never guess.
+            const r = await root(ctx, m, row.currentCredentialId);
+            if (r.state !== "value")
+                held("root-unreadable", ctx.step, r.state === "absent" ? "the stamped root row is absent" : r.detail);
+            next = { ...headBase(m), state: "service-cancelling", op: m.op, rootPlan: { credentialId: row.currentCredentialId, expMs: r.row.exp }, currentCredentialId: row.currentCredentialId };
+        }
+        await write(ctx, "records", headKey(m), encodeHead(m, next), { revision: h.revision, preimage: h.bytes });
+    }
+    ctx.step = "L3-gate";
+    for (let i = 0;; i++) {
+        if (i >= S1_MAX_CAS_REDECIDE)
+            held("contention", ctx.step);
+        await confirmCancelling(ctx, m);
+        const g = await gate(ctx, m);
+        if (g.state === "other" || g.state === "marker")
+            held("gate-foreign", ctx.step, g.detail);
+        const cancelGate = (generation) => ({ lifecycleUid: m.id.lifecycleUid, state: "frozen", generation, serviceCustody: { ...m.id.mirror }, op: { opId, kind: "service-cancel" } });
+        if (g.state === "absent") {
+            await write(ctx, "auth", gateKey(m), encodeGate(m, cancelGate(0)), { create: true });
+            continue;
+        }
+        const row = g.row;
+        if (row.state === "frozen" && row.op.kind === "service-cancel") {
+            if (row.op.opId !== opId)
+                return { kind: "foreign-operation", opId: row.op.opId };
+            break;
+        }
+        if (row.state === "frozen" && row.op.opId !== m.id.uid.creation.operationId)
+            held("gate-foreign", ctx.step, "the frozen native gate belongs to another operation");
+        await write(ctx, "auth", gateKey(m), encodeGate(m, cancelGate(row.generation)), { revision: g.revision, preimage: g.bytes });
+    }
+    ctx.step = "L4-root";
+    const h = await confirmCancelling(ctx, m);
+    const pending = (root, rootDetail) => ({ kind: "pending", phase: "cancelled-nonterminal", root, ...(rootDetail ? { rootDetail } : {}), opId });
+    if (h.currentCredentialId !== null)
+        return pending("retained-stamped");
+    if (h.rootPlan === null)
+        return pending("none");
+    const plan = h.rootPlan;
+    // D4 preconditions, freshly proven: exact reservation, endpoint deny-new, native service-cancel fence.
+    if ((await uid(ctx, m)) !== "exact")
+        held("uid-moved", ctx.step);
+    if ((await endpoint(ctx, m)).kind !== "revoked")
+        held("endpoint-not-denied", ctx.step);
+    const g = await gate(ctx, m);
+    if (g.state !== "value" || g.row.state !== "frozen" || g.row.op.kind !== "service-cancel" || g.row.op.opId !== opId)
+        held("gate-not-fenced", ctx.step);
+    let detail;
+    for (let i = 0; detail === undefined; i++) {
+        if (i >= S1_MAX_CAS_REDECIDE)
+            held("contention", ctx.step);
+        const r = await root(ctx, m, plan.credentialId);
+        if (r.state === "other" || r.state === "marker")
+            held("root-foreign", ctx.step, r.detail);
+        if (r.state === "absent") {
+            if ((await write(ctx, "auth", rootKey(m, plan.credentialId), encodeRoot(m, rootRow(m, plan, "revoked")), { create: true })) !== "moved")
+                detail = "created-revoked";
+            continue;
+        }
+        if (r.row.exp !== plan.expMs)
+            held("root-foreign", ctx.step, "the planned root row carries another expiry");
+        if (r.row.state === "revoked") {
+            detail = "already-revoked";
+            break;
+        }
+        if ((await write(ctx, "auth", rootKey(m, plan.credentialId), encodeRoot(m, rootRow(m, plan, "revoked")), { revision: r.revision, preimage: r.bytes })) !== "moved")
+            detail = "cas-revoked";
+    }
+    return pending("revoked", detail);
+}
+/** Run one bounded invocation of an accepted cancellation. `deadlineMs` bounds this invocation
+ *  only; the same intent may be invoked again and resumes its own durable progress. */
+export async function cancelServiceCustody(intent, opts) {
+    const m = CANCELS.get(intent);
+    if (m === undefined)
+        return denied("requires a sealed cancel intent");
+    if (!Number.isSafeInteger(opts.deadlineMs))
+        denied("cancel invocation requires an explicit deadline");
+    const ctx = context(m.host, opts.deadlineMs);
+    try {
+        return await cancel(ctx, m);
+    }
+    catch (e) {
+        if (e instanceof Refused)
+            return e.result;
+        if (e instanceof Held)
+            return { kind: "held", reason: e.reason, step: e.step, detail: e.message, opId: m.op.opId };
+        return { kind: "held", reason: "unavailable", step: ctx.step, detail: message(e), opId: m.op.opId };
+    }
+}
+//# sourceMappingURL=service-custody.js.map