@junghanacs/entwurf 0.41.2 → 0.50.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/pi-durable-owner-fence.js

@@ -0,0 +1,1132 @@
+/**
+ * pi-durable OWNER FENCE (#157 B3, pre-release fence) — the claim an owned pi-durable open takes inside its
+ * native session directory D BEFORE the native lease (proper-lockfile's `${D}.lock`), and carries through
+ * storage open and close.
+ *
+ * WHAT THIS IS. Three fixed names inside D, never derived from the session id and never under the SDK's
+ * `session.sqlite` prefix:
+ *   - `entwurf-owner.json` — the claim: one regular file, replaced by tmp+rename, read no-follow;
+ *   - `entwurf-owner.tx` — the transaction mutex S_D, created `wx`; its body is evidence only;
+ *   - `entwurf-owner.json.tmp-<pid>-<hex>` — the atomic temp a write renames into place.
+ * Every claim write — the first creation of an absent claim included — happens inside ONE S_D hold, on a
+ * decision read inside that hold; an owner's own transition also requires the generation it last wrote.
+ * The holder unlinks only the tx it created, in `finally`. A tx it did not create (another holder, or crash
+ * residue) is never removed, taken over or aged out: there is no TTL, no mtime rule and no cleanup verb.
+ *
+ * WHAT IT GUARANTEES. Mutual exclusion among PARTICIPATING owned openers only. It does not prove that no
+ * foreign lease exists, and it does not make a legacy or non-participating opener safe (an opener with
+ * neither a fence nor a lease is invisible to it). A `closed` claim is a participating owner's end receipt in
+ * one of two rows; it is not "untouched since", not dormancy and not public-resume evidence, and neither is
+ * `firstParticipation`, which records the first participation attempt for D, not a completed enrollment.
+ *
+ * SCHEMA. A new admission writes schema 2, whose `selected` also carries `profile`: the agent directory exactly as
+ * the owned open's `getAgentDir()` returned it, the value its `directory` was joined from. A schema 1 claim (the
+ * pre-profile build: `selected` is `{n, directory}`) is still read, and every admission row judges it as before; its
+ * profile is never inferred, and it is replaced only by the next admission's own claim, never rewritten to migrate.
+ * Schema 2 alone knows `reserved` with its `reservation`, and `adoptedFrom`; an older reader refuses schema 2, so the
+ * rollout is complete only once every participating reader is this one.
+ *
+ * RESERVATION (#157 B3 I-2). A parent reserves one citizen's D for one child (`reservePiDurableSession`), the child
+ * adopts exactly that reservation (`createPiDurableOwnerFence({adoption})`), and only the parent withdraws its own
+ * (`withdrawPiDurableReservation`). The reserve and the adoption take record-arm(gid), then S_D(R), on the record and
+ * C4 pair read inside the arm hold; the withdrawal takes S_D only. A parent's per-target lock is its caller's outer
+ * scope and is never taken here. The claim and S_D live in R, the physical D; the SDK's lease is `${S}.lock`, S being
+ * the donor's own selection, and every lease snapshot is taken there. `observePiDurableReservation` is a read, never a
+ * watch.
+ *
+ * DEATH POLICY stays in meta-session.ts (Hard Rule 14): `classifyMarkerOwner` over `processStartKey` and
+ * `probePidExistence`, plus `isPlausibleOwnerPid`. A live or uncertain owner — this very process included — is
+ * refused; only a proven-dead owner on this host is reclaimed, and an unattributed lease that is present is
+ * never presumed to be the dead owner's.
+ *
+ * The owned app (pi/pi-durable/src/experimental/durable/sessions.ts) declares the `SessionFence` and
+ * `FenceTicket` shapes this module implements, type-only and without importing Entwurf; the packaged
+ * bootstrap builds one fence from the compiled twin of this file and hands it to every owned open.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { acquireLock, releaseLock } from "./entwurf-v2-lock.js";
+import { classifyMarkerOwner, defaultMetaRecordArmLocksDir, isPlausibleOwnerPid, probePidExistence, processStartKey, readStoreRecordFile, requireAttachIncarnation, requireGardenId, } from "./meta-session.js";
+import { verifyPiDurableLocation } from "./pi-durable-location.js";
+export const PI_DURABLE_OWNER_CLAIM = "entwurf-owner.json";
+export const PI_DURABLE_OWNER_TX = "entwurf-owner.tx";
+export const PI_DURABLE_OWNER_TMP_PREFIX = `${PI_DURABLE_OWNER_CLAIM}.tmp-`;
+/** The schema a new admission writes: `selected` is `{n, directory, profile}`. */
+export const PI_DURABLE_OWNER_SCHEMA_VERSION = 2;
+/** The pre-profile schema, still read and never written: `selected` is `{n, directory}`. */
+const LEGACY_SCHEMA_VERSION = 1;
+/** The bounded wait for S_D: 20 attempts 100 ms apart, then `tx-held`. */
+const TX_ATTEMPTS = 20;
+const TX_DELAY_MS = 100;
+const CAUSE_MAX = 512;
+const HEX32 = /^[0-9a-f]{32}$/;
+export class PiDurableOwnerFenceError extends Error {
+    reason;
+    holderState;
+    written;
+    constructor(reason, message, context = {}) {
+        super(`${reason}: ${message}`);
+        this.name = "PiDurableOwnerFenceError";
+        this.reason = reason;
+        if (context.holderState !== undefined)
+            this.holderState = context.holderState;
+        if (context.written !== undefined)
+            this.written = context.written;
+    }
+}
+function refuse(reason, message, context) {
+    return new PiDurableOwnerFenceError(reason, message, context);
+}
+/**
+ * A release failure that came AFTER this call's own decision write committed keeps its reason, message and cause; it
+ * only gains what was written. Any other error, or one that already names a write, is returned as it is.
+ */
+function afterWrite(error, written) {
+    if (written !== undefined &&
+        error instanceof PiDurableOwnerFenceError &&
+        error.written === undefined &&
+        (error.reason === "tx-release-failed" || error.reason === "record-arm-release-failed")) {
+        Object.assign(error, { written });
+    }
+    return error;
+}
+function writtenOf(claim) {
+    return { resource: claim.resource, state: claim.state, generation: claim.generation, ownerPid: claim.owner.pid };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The fence an owned open takes. Building it reads and writes nothing; every check happens at `admit`. With an
+ * adoption, `admit` adopts exactly that reservation or refuses; it never falls back to an ordinary admission.
+ */
+export function createPiDurableOwnerFence(options = {}) {
+    if (options.adoption === undefined)
+        return { admit: (request) => admitOwner(request) };
+    const adoption = requireAdoption(options.adoption);
+    return { admit: (request) => adoptOwner(request, adoption) };
+}
+// ── The claim's schema and its state × lease × end table ─────────────────────────────────────────
+const NATIVE_STATES = ["fenced", "leased", "storage-open", "closed", "close-failed"];
+/** Schema 2's states; schema 1 knows only the native ones. */
+const STATES = [...NATIVE_STATES, "reserved"];
+const NATIVE_LEASES = ["absent", "present-attributed"];
+const LEASES = ["never-held", "held", "released", "failed", "unknown"];
+const STORAGE_ENDS = ["closed", "never-opened", "failed", "unknown"];
+const PARTICIPATIONS = ["fresh", "unarmed-existing"];
+const CLAIM_KEYS = [
+    "schemaVersion",
+    "resource",
+    "selected",
+    "state",
+    "owner",
+    "generation",
+    "firstParticipation",
+    "lease",
+    "writtenAt",
+];
+const CLAIM_OPTIONAL_KEYS = ["reclaimedFrom", "end"];
+/** Only schema 2 carries a reservation or an adoption. */
+const CLAIM_OPTIONAL_KEYS_V2 = [...CLAIM_OPTIONAL_KEYS, "reservation", "adoptedFrom"];
+const RESERVATION_KEYS = ["gardenId", "n", "cwd", "resource", "profile", "attachIncarnation", "nativeLease", "from"];
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, required, optional = []) {
+    const keys = Object.keys(value);
+    return (required.every((key) => keys.includes(key)) && keys.every((key) => required.includes(key) || optional.includes(key)));
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isTime(value) {
+    return nonEmpty(value) && Number.isFinite(Date.parse(value));
+}
+function isOwner(value) {
+    return (isObject(value) &&
+        hasExactKeys(value, ["pid", "startKey", "hostname"]) &&
+        isPlausibleOwnerPid(value.pid) &&
+        nonEmpty(value.startKey) &&
+        nonEmpty(value.hostname));
+}
+function isEnd(value) {
+    return (isObject(value) &&
+        hasExactKeys(value, ["at", "storage", "lease"], ["envCleanup", "cause"]) &&
+        isTime(value.at) &&
+        STORAGE_ENDS.includes(value.storage) &&
+        LEASES.includes(value.lease) &&
+        (value.envCleanup === undefined || value.envCleanup === "failed") &&
+        (value.cause === undefined || (typeof value.cause === "string" && value.cause.length <= CAUSE_MAX)));
+}
+/**
+ * The complete table (anything else is a malformed claim):
+ *   reserved      never-held                     —   (schema 2 only)
+ *   fenced        never-held                     —
+ *   leased        held                           —
+ *   storage-open  held                           —
+ *   closed        released                       closed | never-opened
+ *   closed        never-held                     never-opened
+ *   close-failed  released | failed | unknown    failed | unknown; closed or never-opened only when the release
+ *                                                failed or is unknown
+ * `end.lease` repeats the claim's `lease`; an env-cleanup failure never rides a storage that was never opened.
+ */
+function combinationValid(state, lease, end) {
+    if (state === "reserved")
+        return lease === "never-held" && end === undefined;
+    if (state === "fenced")
+        return lease === "never-held" && end === undefined;
+    if (state === "leased" || state === "storage-open")
+        return lease === "held" && end === undefined;
+    if (end === undefined || end.lease !== lease)
+        return false;
+    if (end.envCleanup !== undefined && end.storage === "never-opened")
+        return false;
+    if (state === "closed") {
+        if (lease === "released")
+            return end.storage === "closed" || end.storage === "never-opened";
+        return lease === "never-held" && end.storage === "never-opened";
+    }
+    if (lease !== "released" && lease !== "failed" && lease !== "unknown")
+        return false;
+    if (end.storage === "failed" || end.storage === "unknown")
+        return true;
+    return lease !== "released";
+}
+/**
+ * A claim body exactly as the schema and the table allow, or a named refusal; never a default. A body read from D
+ * is `claim-unreadable`; a body about to be written is `transition-invalid`.
+ */
+function requireClaim(value, where, reason = "claim-unreadable") {
+    const bad = (what) => refuse(reason, `${where}: ${what}`);
+    if (!isObject(value))
+        throw bad("not a JSON object");
+    const v2 = value.schemaVersion === PI_DURABLE_OWNER_SCHEMA_VERSION;
+    if (!v2 && value.schemaVersion !== LEGACY_SCHEMA_VERSION)
+        throw bad("unknown schemaVersion");
+    const optional = v2 ? CLAIM_OPTIONAL_KEYS_V2 : CLAIM_OPTIONAL_KEYS;
+    if (!hasExactKeys(value, CLAIM_KEYS, optional))
+        throw bad("its keys are not exactly the claim's keys");
+    if (!nonEmpty(value.resource) || !path.isAbsolute(value.resource))
+        throw bad("resource is not an absolute path");
+    const selected = value.selected;
+    if (!isObject(selected) ||
+        !hasExactKeys(selected, v2 ? ["n", "directory", "profile"] : ["n", "directory"]) ||
+        !nonEmpty(selected.n) ||
+        !nonEmpty(selected.directory) ||
+        !path.isAbsolute(selected.directory)) {
+        throw bad(v2 ? "selected is not {n, directory, profile}" : "selected is not {n, directory}");
+    }
+    // Schema 2's profile is the value its directory was joined from, as it was read; schema 1 has none to infer.
+    if (v2) {
+        const profile = selected.profile;
+        if (!nonEmpty(profile) || !path.isAbsolute(profile))
+            throw bad("selected.profile is not an absolute path");
+        const n = selected.n;
+        const directory = selected.directory;
+        const joined = path.join(profile, "experimental", "durable-sessions", path.basename(path.dirname(directory)), n);
+        if (joined !== directory)
+            throw bad("selected.directory is not joined from selected.profile and selected.n");
+    }
+    const states = v2 ? STATES : NATIVE_STATES;
+    if (!states.includes(value.state))
+        throw bad("unknown state");
+    if (!isOwner(value.owner))
+        throw bad("owner is not {pid, startKey, hostname} of a plausible pid");
+    if (typeof value.generation !== "string" || !HEX32.test(value.generation))
+        throw bad("generation is not 32 hex");
+    const first = value.firstParticipation;
+    if (!isObject(first) ||
+        !hasExactKeys(first, ["at", "generation", "from"]) ||
+        !isTime(first.at) ||
+        typeof first.generation !== "string" ||
+        !HEX32.test(first.generation) ||
+        !PARTICIPATIONS.includes(first.from)) {
+        throw bad("firstParticipation is not {at, generation, from}");
+    }
+    const reclaimed = value.reclaimedFrom;
+    if (reclaimed !== undefined &&
+        !(isObject(reclaimed) &&
+            hasExactKeys(reclaimed, ["generation", "state", "owner", "leaseOutcome"]) &&
+            typeof reclaimed.generation === "string" &&
+            HEX32.test(reclaimed.generation) &&
+            states.includes(reclaimed.state) &&
+            isOwner(reclaimed.owner) &&
+            LEASES.includes(reclaimed.leaseOutcome))) {
+        throw bad("reclaimedFrom is not {generation, state, owner, leaseOutcome}");
+    }
+    if (!LEASES.includes(value.lease))
+        throw bad("unknown lease outcome");
+    if (value.end !== undefined && !isEnd(value.end))
+        throw bad("end is not {at, storage, lease, envCleanup?, cause?}");
+    if (!isTime(value.writtenAt))
+        throw bad("writtenAt is not a time");
+    const claim = value;
+    if (!combinationValid(claim.state, claim.lease, claim.end)) {
+        throw bad(`state ${claim.state} with lease ${claim.lease} and end ${JSON.stringify(claim.end ?? null)} is invalid`);
+    }
+    // Exactly a `reserved` claim carries a reservation (#157 B3); an adoption rides only an owned state.
+    if ((claim.state === "reserved") !== (value.reservation !== undefined)) {
+        throw bad(`a ${claim.state} claim ${claim.state === "reserved" ? "lacks" : "carries"} a reservation`);
+    }
+    if (value.reservation !== undefined)
+        requireReservation(value.reservation, claim, bad);
+    if (value.adoptedFrom !== undefined && (claim.state === "reserved" || !isAdoptedFrom(value.adoptedFrom))) {
+        throw bad("adoptedFrom is not {generation, owner} on an owned state");
+    }
+    return claim;
+}
+function isAdoptedFrom(value) {
+    return (isObject(value) &&
+        hasExactKeys(value, ["generation", "owner"]) &&
+        typeof value.generation === "string" &&
+        HEX32.test(value.generation) &&
+        isOwner(value.owner));
+}
+/** Whether a native row's own lease outcome makes a present lease that owner's: held, or held and never seen released. */
+function leaseAttributed(lease) {
+    return lease === "held" || lease === "unknown";
+}
+/**
+ * A reservation exactly as the reserve writes it: it names the claim's resource, session and profile; its donor is ONE
+ * flat native row whose selection is the claim's; a present lease is attributed only to a donor that held one.
+ */
+function requireReservation(value, claim, bad) {
+    if (!isObject(value) || !hasExactKeys(value, RESERVATION_KEYS))
+        throw bad("reservation is not the reservation's keys");
+    try {
+        requireGardenId(value.gardenId);
+        if (requireAttachIncarnation(value.attachIncarnation) === null)
+            throw new Error("attachIncarnation is null");
+    }
+    catch (error) {
+        throw bad(`reservation: ${messageOf(error)}`);
+    }
+    if (!nonEmpty(value.cwd) || !path.isAbsolute(value.cwd))
+        throw bad("reservation.cwd is not an absolute path");
+    if (value.resource !== claim.resource || value.n !== claim.selected.n || value.profile !== claim.selected.profile) {
+        throw bad("reservation does not name the claim's resource, session and profile");
+    }
+    if (!NATIVE_LEASES.includes(value.nativeLease))
+        throw bad("reservation.nativeLease is unknown");
+    const from = value.from;
+    if (!isObject(from) ||
+        !hasExactKeys(from, ["generation", "state", "owner", "lease", "selected"], ["end"]) ||
+        typeof from.generation !== "string" ||
+        !HEX32.test(from.generation) ||
+        !NATIVE_STATES.includes(from.state) ||
+        !isOwner(from.owner) ||
+        !LEASES.includes(from.lease) ||
+        (from.end !== undefined && !isEnd(from.end))) {
+        throw bad("reservation.from is not one flat native owner row");
+    }
+    // The reserve selects nothing itself: the donor's selection IS the claim's.
+    const selected = from.selected;
+    if (!isObject(selected) ||
+        !hasExactKeys(selected, ["n", "directory", "profile"]) ||
+        selected.n !== claim.selected.n ||
+        selected.directory !== claim.selected.directory ||
+        selected.profile !== claim.selected.profile) {
+        throw bad("reservation.from.selected is not the claim's selected");
+    }
+    const donor = from;
+    if (!combinationValid(donor.state, donor.lease, donor.end))
+        throw bad("reservation.from is not a row the table allows");
+    const attributable = leaseAttributed(donor.lease);
+    if (value.nativeLease === "present-attributed" && !attributable) {
+        throw bad("reservation.nativeLease is present-attributed for a donor that held no lease");
+    }
+}
+// ── Reads, writes and the S_D hold ───────────────────────────────────────────────────────────────
+/** The claim of D, or undefined when there is none; a symlink, a non-regular entry or a bad body is refused. */
+function readClaim(resource) {
+    const file = path.join(resource, PI_DURABLE_OWNER_CLAIM);
+    let text;
+    try {
+        text = readStoreRecordFile(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw refuse("claim-unreadable", `${file}: ${messageOf(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw refuse("claim-unreadable", `${file}: ${messageOf(error)}`);
+    }
+    return requireClaim(parsed, file);
+}
+/** tmp+rename, mode 0600, fsync'd before the rename. Only a body the schema and the table accept is written. */
+function writeClaim(resource, body) {
+    requireClaim(JSON.parse(JSON.stringify(body)), "the claim about to be written", "transition-invalid");
+    const tmp = path.join(resource, `${PI_DURABLE_OWNER_TMP_PREFIX}${process.pid}-${randomBytes(6).toString("hex")}`);
+    // Ownership of the temp is its creation by THIS call: a `wx` that failed (EEXIST included) made nothing here.
+    let created = false;
+    try {
+        const fd = fs.openSync(tmp, "wx", 0o600);
+        created = true;
+        try {
+            fs.writeSync(fd, `${JSON.stringify(body, null, "\t")}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmp, path.join(resource, PI_DURABLE_OWNER_CLAIM));
+    }
+    catch (error) {
+        // Only the temp this call created is its to remove; a file that was already there is left as it is.
+        if (created)
+            fs.rmSync(tmp, { force: true });
+        throw error;
+    }
+}
+/** Whether `${D}.lock` (the lease this opener would take) exists in any form; an unreadable answer throws. */
+function leasePresent(directory) {
+    try {
+        fs.lstatSync(`${directory}.lock`);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/** What a busy tx says about its holder, as evidence only; nothing is decided from it. */
+function txEvidence(tx) {
+    try {
+        return readStoreRecordFile(tx).trim().slice(0, CAUSE_MAX) || "(empty)";
+    }
+    catch (error) {
+        return `(unreadable: ${error.code ?? messageOf(error)})`;
+    }
+}
+async function enterTx(tx) {
+    for (let attempt = 1;; attempt++) {
+        let fd;
+        try {
+            fd = fs.openSync(tx, "wx", 0o600);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        if (fd !== undefined) {
+            try {
+                const evidence = {
+                    pid: process.pid,
+                    startKey: processStartKey(process.pid),
+                    hostname: os.hostname(),
+                    enteredAt: new Date().toISOString(),
+                };
+                fs.writeSync(fd, `${JSON.stringify(evidence)}\n`);
+                const { dev, ino } = fs.fstatSync(fd);
+                return { dev, ino };
+            }
+            catch (error) {
+                // This tx was created by this call a moment ago, so it is this actor's own to remove.
+                fs.rmSync(tx, { force: true });
+                throw error;
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        if (attempt >= TX_ATTEMPTS) {
+            throw refuse("tx-held", `${tx} is held (${txEvidence(tx)}); a tx this fence did not create is never removed, taken over or aged out`);
+        }
+        await sleep(TX_DELAY_MS);
+    }
+}
+/**
+ * Unlink the tx this actor created, and only that one. A failure is reported; it does not prove the file remains (it
+ * may be gone, or another actor's), so the report says what a remaining file does rather than that one remains.
+ */
+function leaveTx(tx, held, during) {
+    try {
+        const now = fs.lstatSync(tx);
+        if (now.dev !== held.dev || now.ino !== held.ino) {
+            throw new Error("the transaction file is no longer the one this owner created");
+        }
+        fs.unlinkSync(tx);
+    }
+    catch (error) {
+        throw refuse("tx-release-failed", `${tx}: ${messageOf(error)}${during === undefined ? "" : `; the step had already failed: ${messageOf(during)}`}; if that transaction file remains, it fails closed until an operator removes it`);
+    }
+}
+/** One S_D hold around a synchronous decision read and write. */
+async function withTx(resource, step) {
+    const tx = path.join(resource, PI_DURABLE_OWNER_TX);
+    const held = await enterTx(tx);
+    let stepError;
+    try {
+        return step();
+    }
+    catch (error) {
+        stepError = error;
+        throw error;
+    }
+    finally {
+        leaveTx(tx, held, stepError);
+    }
+}
+function newGeneration() {
+    return randomBytes(16).toString("hex");
+}
+function boundedCause(cause) {
+    return cause === undefined ? {} : { cause: cause.slice(0, CAUSE_MAX) };
+}
+// ── Admission ────────────────────────────────────────────────────────────────────────────────────
+function requireAdmission(request) {
+    if (!isObject(request) ||
+        !nonEmpty(request.directory) ||
+        !path.isAbsolute(request.directory) ||
+        !nonEmpty(request.selectedN) ||
+        typeof request.created !== "boolean" ||
+        !nonEmpty(request.profile) ||
+        !path.isAbsolute(request.profile)) {
+        throw refuse("admission-invalid", "an admission names an absolute directory, its session id, whether it was created and the absolute profile it was joined from");
+    }
+    return request;
+}
+function thisOwner() {
+    const pid = process.pid;
+    if (!isPlausibleOwnerPid(pid))
+        throw refuse("owner-pid-implausible", `pid ${pid} cannot own a session`);
+    const startKey = processStartKey(pid);
+    if (startKey === "")
+        throw refuse("owner-start-key-unreadable", `the start key of pid ${pid} cannot be read`);
+    return { pid, startKey, hostname: os.hostname() };
+}
+/**
+ * The admission table, inside the S_D hold, after D is chosen and before `lockfile.lock`:
+ *   absent + created by this call            → fenced, from "fresh"
+ *   absent + D existed, or `closed`          → `${D}.lock` present (any age): legacy-lease-present, nothing
+ *                                              written; absent: fenced (a `closed` claim's firstParticipation kept)
+ *   resource ≠ realpath(D)                   → claim-resource-mismatch, never read as absent
+ *   an owner on another host                 → owner-other-host
+ *   an owner live or uncertain (this pid too)→ owner-live / owner-uncertain
+ *   a dead owner, unattributed lease         → `${D}.lock` present: lease-unattributed; absent: reclaim
+ *   a dead owner, attributed lease           → reclaim (the library's stale takeover is admissible only here)
+ *   a dead reservation's parent              → as a dead owner, its lease attributed only by its donor's snapshot
+ *                                              and only for that snapshot's own selection
+ * A differing `selected` (another N or another spelling of D) with an equal resource is an alias, judged by the
+ * rows above.
+ */
+async function admitOwner(request) {
+    const { directory, selectedN, created, profile } = requireAdmission(request);
+    let resource;
+    try {
+        resource = fs.realpathSync(directory);
+        if (!fs.statSync(resource).isDirectory())
+            throw new Error("not a directory");
+    }
+    catch (error) {
+        throw refuse("directory-invalid", `${directory}: ${messageOf(error)}`);
+    }
+    const owner = thisOwner();
+    const written = await withTx(resource, () => {
+        const read = readClaim(resource);
+        if (read !== undefined && read.resource !== resource) {
+            throw refuse("claim-resource-mismatch", `the claim in ${directory} names ${read.resource}, not ${resource}`);
+        }
+        // Only a claim for THIS resource is judged below; a mismatched one was refused above, never read as absent.
+        const claim = read;
+        const at = new Date().toISOString();
+        const generation = newGeneration();
+        const fenced = (firstParticipation, reclaimedFrom) => ({
+            schemaVersion: PI_DURABLE_OWNER_SCHEMA_VERSION,
+            resource,
+            selected: { n: selectedN, directory, profile },
+            state: "fenced",
+            owner,
+            generation,
+            firstParticipation,
+            ...(reclaimedFrom === undefined ? {} : { reclaimedFrom }),
+            lease: "never-held",
+            writtenAt: at,
+        });
+        // `selected` is never compared: an alias of D (another N, another spelling) is judged by the same rows.
+        if (claim === undefined || claim.state === "closed") {
+            // An unarmed or ended D: a lease seen here is nobody this fence can name, so its stale takeover is never invoked.
+            if ((claim !== undefined || !created) && leasePresent(directory)) {
+                throw refuse("legacy-lease-present", `${directory}.lock exists while no participating owner holds it`);
+            }
+            const from = created ? "fresh" : "unarmed-existing";
+            const body = fenced(claim?.firstParticipation ?? { at, generation, from });
+            writeClaim(resource, body);
+            return body;
+        }
+        if (claim.owner.hostname !== owner.hostname) {
+            throw refuse("owner-other-host", `${directory} is claimed by pid ${claim.owner.pid} on ${claim.owner.hostname}`);
+        }
+        const verdict = classifyMarkerOwner(claim.owner.startKey, {
+            currentStartKey: processStartKey(claim.owner.pid),
+            pidExists: probePidExistence(claim.owner.pid),
+        });
+        const proven = verdict === "dead";
+        if (!proven) {
+            throw refuse(verdict === "live" ? "owner-live" : "owner-uncertain", `${directory} is ${claim.state} under pid ${claim.owner.pid}, which is ${verdict}`);
+        }
+        // A dead owner whose recorded lease is attributable to it: held, or held and its release never observed.
+        const attributed = claim.lease === "held" || claim.lease === "unknown";
+        // A dead reservation's parent never held a lease: only its donor's snapshot attributes one, and only to the very
+        // selection that snapshot was taken on; another spelling's sidecar is not that evidence (#157 B3).
+        const snapshot = claim.reservation;
+        const reservedAttributed = snapshot?.nativeLease === "present-attributed" && snapshot.from.selected.directory === directory;
+        if (!(attributed || reservedAttributed) && leasePresent(directory)) {
+            throw refuse("lease-unattributed", `${directory}.lock exists, and the dead owner's claim (${claim.state}, lease ${claim.lease}) does not make it that owner's`);
+        }
+        const body = fenced(claim.firstParticipation, {
+            generation: claim.generation,
+            state: claim.state,
+            owner: claim.owner,
+            leaseOutcome: claim.lease,
+        });
+        writeClaim(resource, body);
+        return body;
+    });
+    return new OwnerTicket(resource, written);
+}
+// ── An admitted owner's transitions ──────────────────────────────────────────────────────────────
+const UNLEASED_END = { storage: "never-opened", lease: "never-held" };
+function requireEnd(end) {
+    if (!isObject(end) ||
+        !hasExactKeys(end, ["storage", "lease"], ["envCleanup", "cause"]) ||
+        !STORAGE_ENDS.includes(end.storage) ||
+        !LEASES.includes(end.lease) ||
+        (end.envCleanup !== undefined && end.envCleanup !== "failed") ||
+        (end.cause !== undefined && typeof end.cause !== "string")) {
+        throw refuse("transition-invalid", "an end is {storage, lease, envCleanup?, cause?}");
+    }
+    return end;
+}
+class OwnerTicket {
+    storageOpenAttempted = false;
+    #resource;
+    /** The body this owner last wrote; its generation is what the next transition requires. */
+    #claim;
+    #ended = false;
+    constructor(resource, claim) {
+        this.#resource = resource;
+        this.#claim = claim;
+    }
+    async leased() {
+        await this.#write(["fenced"], "leased", "held", undefined);
+    }
+    async storageOpened() {
+        if (!this.storageOpenAttempted) {
+            throw refuse("transition-invalid", "storage-open without an attempted storage open");
+        }
+        await this.#write(["leased"], "storage-open", "held", undefined);
+    }
+    async endUnleased() {
+        await this.#end(["fenced"], "closed", UNLEASED_END);
+    }
+    async closed(end) {
+        const checked = this.#checkEnd(end);
+        if (checked.storage === "closed" && this.#claim.state !== "storage-open") {
+            throw refuse("transition-invalid", "a storage close is recorded only for an opened storage");
+        }
+        await this.#end(["leased", "storage-open"], "closed", checked);
+    }
+    async closeFailed(end) {
+        await this.#end(["leased", "storage-open"], "close-failed", this.#checkEnd(end));
+    }
+    #checkEnd(end) {
+        const checked = requireEnd(end);
+        if (checked.storage === "never-opened" && this.storageOpenAttempted) {
+            throw refuse("transition-invalid", "the storage open was attempted, so this end is not never-opened");
+        }
+        return checked;
+    }
+    async #end(from, to, end) {
+        await this.#write(from, to, end.lease, end);
+        this.#ended = true;
+    }
+    async #write(from, to, lease, end) {
+        if (this.#ended)
+            throw refuse("transition-invalid", "this owner's claim has already ended");
+        if (!from.includes(this.#claim.state)) {
+            throw refuse("transition-invalid", `${this.#claim.state} → ${to} is not a transition`);
+        }
+        const last = this.#claim;
+        this.#claim = await withTx(this.#resource, () => {
+            const current = readClaim(this.#resource);
+            if (current === undefined) {
+                throw refuse("claim-missing", `the claim this owner wrote in ${this.#resource} is gone`);
+            }
+            if (current.generation !== last.generation) {
+                throw refuse("generation-mismatch", `the claim in ${this.#resource} is generation ${current.generation}, not ${last.generation} this owner wrote`);
+            }
+            const at = new Date().toISOString();
+            const body = {
+                schemaVersion: PI_DURABLE_OWNER_SCHEMA_VERSION,
+                resource: last.resource,
+                selected: last.selected,
+                state: to,
+                owner: last.owner,
+                generation: newGeneration(),
+                firstParticipation: last.firstParticipation,
+                ...(last.adoptedFrom === undefined ? {} : { adoptedFrom: last.adoptedFrom }),
+                lease,
+                ...(end === undefined
+                    ? {}
+                    : {
+                        end: {
+                            at,
+                            storage: end.storage,
+                            lease: end.lease,
+                            ...(end.envCleanup === undefined ? {} : { envCleanup: end.envCleanup }),
+                            ...boundedCause(end.cause),
+                        },
+                    }),
+                writtenAt: at,
+            };
+            writeClaim(this.#resource, body);
+            return body;
+        });
+    }
+}
+const META_ROOT_CHILDREN = {
+    sessionsDir: "meta-sessions",
+    mailboxDir: "meta-mailbox",
+    sendersDir: "meta-senders",
+    receiversDir: "meta-receivers",
+};
+function standardRoots(metaRoot) {
+    return {
+        sessionsDir: path.join(metaRoot, META_ROOT_CHILDREN.sessionsDir),
+        mailboxDir: path.join(metaRoot, META_ROOT_CHILDREN.mailboxDir),
+        sendersDir: path.join(metaRoot, META_ROOT_CHILDREN.sendersDir),
+        receiversDir: path.join(metaRoot, META_ROOT_CHILDREN.receiversDir),
+    };
+}
+/** ONE meta root whose standard children are exactly the four roots given; any other shape is refused, never merged. */
+function requireMetaRoot(roots) {
+    const fields = Object.keys(META_ROOT_CHILDREN);
+    const absolute = (field) => {
+        const root = isObject(roots) ? roots[field] : undefined;
+        return nonEmpty(root) && path.isAbsolute(root);
+    };
+    if (!fields.every(absolute))
+        throw refuse("reservation-invalid", "a reservation names four absolute meta roots");
+    const given = roots;
+    const metaRoot = path.dirname(given.sessionsDir);
+    const standard = standardRoots(metaRoot);
+    const split = fields.filter((field) => given[field] !== standard[field]);
+    if (split.length > 0) {
+        throw refuse("reserve-meta-root-split", `${split.join(", ")}: not the standard children of ${metaRoot}`);
+    }
+    return metaRoot;
+}
+function requireReservationGardenId(value) {
+    try {
+        return requireGardenId(value);
+    }
+    catch (error) {
+        throw refuse("reservation-invalid", messageOf(error));
+    }
+}
+function requireAdoption(value) {
+    if (!isObject(value) ||
+        !hasExactKeys(value, ["gardenId", "metaRoot", "sourceGeneration"]) ||
+        !nonEmpty(value.metaRoot) ||
+        !path.isAbsolute(value.metaRoot) ||
+        typeof value.sourceGeneration !== "string" ||
+        !HEX32.test(value.sourceGeneration)) {
+        throw refuse("reservation-invalid", "an adoption is exactly {gardenId, metaRoot, sourceGeneration}");
+    }
+    const metaRoot = value.metaRoot;
+    return {
+        gardenId: requireReservationGardenId(value.gardenId),
+        metaRoot,
+        sourceGeneration: value.sourceGeneration,
+        roots: standardRoots(metaRoot),
+    };
+}
+/** Takes the record-arm lock of `gardenId` at once; a busy lock refuses with nothing read or written. */
+function takeRecordArm(gardenId, roots) {
+    const acquired = acquireLock(gardenId, { dir: defaultMetaRecordArmLocksDir(roots.receiversDir) });
+    if (!acquired.ok)
+        throw refuse("record-arm-busy", `${acquired.conflict.detail}; nothing was read or written`);
+    return acquired.claim;
+}
+/**
+ * Releases the record-arm lock, after S_D. Returns what the caller throws: the step's own error when the release
+ * answered `released`, else a named release failure carrying it, and the write that step had committed if it names
+ * one. A clean step whose release answered returns undefined.
+ */
+function leaveRecordArm(arm, during) {
+    let released;
+    try {
+        released = releaseLock(arm);
+    }
+    catch (error) {
+        released = `threw: ${messageOf(error)}`;
+    }
+    if (released === "released")
+        return during;
+    const failed = during === undefined ? "" : `; the step had already failed: ${messageOf(during)}`;
+    const written = during instanceof PiDurableOwnerFenceError ? during.written : undefined;
+    return refuse("record-arm-release-failed", `the record-arm lock of ${arm.gardenId} answered ${released}${failed}`, written === undefined ? undefined : { written });
+}
+/** The record and C4 pair read NOW, inside the caller's arm hold (P1), or a named refusal. */
+function freshPair(gardenId, roots) {
+    const { sessionsDir, receiversDir } = roots;
+    const verdict = verifyPiDurableLocation({ gardenId, sessionsDir, receiversDir });
+    if (!verdict.ok) {
+        const reason = verdict.reason === "binding-mismatch" ? "binding-mismatch" : "profile-record-unbound";
+        throw refuse(reason, `${gardenId}: ${verdict.reason}: ${verdict.detail}`);
+    }
+    return { record: verdict.record, location: verdict.location };
+}
+/** The current holder's liveness by the shared death policy; only `dead` lets a reserve take D over. */
+function holderVerdict(holder) {
+    return classifyMarkerOwner(holder.startKey, {
+        currentStartKey: processStartKey(holder.pid),
+        pidExists: probePidExistence(holder.pid),
+    });
+}
+/** Reserve rows 3–4: the current holder of a non-closed claim, a reservation's parent included; its host first. */
+function requireHolderGone(claim, resource, hostname) {
+    const where = `${resource} is ${claim.state} under pid ${claim.owner.pid} on ${claim.owner.hostname}`;
+    const otherHost = claim.owner.hostname !== hostname;
+    const verdict = otherHost ? "other-host" : holderVerdict(claim.owner);
+    // The holder's state rides beside the reason: a live reservation parent is not a running citizen (S3 joint review D4).
+    const context = { holderState: claim.state };
+    if (verdict === "other-host")
+        throw refuse("owner-other-host", where, context);
+    if (verdict !== "dead") {
+        throw refuse(verdict === "live" ? "owner-live" : "owner-uncertain", `${where}: ${verdict}`, context);
+    }
+}
+/** The reservation a `reserved` claim carries; the reader guarantees one. */
+function reservationOf(claim) {
+    if (claim.reservation === undefined) {
+        throw refuse("claim-unreadable", `the ${claim.state} claim in ${claim.resource} carries no reservation`);
+    }
+    return claim.reservation;
+}
+/** The native donor: a `reserved` claim's flat `from`, or a native claim's own row. Never a reservation's parent. */
+function donorOf(claim) {
+    if (claim.state === "reserved")
+        return reservationOf(claim).from;
+    return {
+        generation: claim.generation,
+        state: claim.state,
+        owner: claim.owner,
+        lease: claim.lease,
+        ...(claim.end === undefined ? {} : { end: claim.end }),
+        selected: claim.selected,
+    };
+}
+function reclaimOf(claim) {
+    return { generation: claim.generation, state: claim.state, owner: claim.owner, leaseOutcome: claim.lease };
+}
+/**
+ * P2–P6 on the native donor, on the pair read in this hold (P1); P2 is the claim's resource row before this. The donor
+ * is the incarnation C4's binding names, on this host; its selection is the record's session, joined from its own raw
+ * profile, and still reaches R. Returns that profile. A schema 1 donor recorded none, and none is ever inferred.
+ */
+function requireProfile(donor, pair, resource) {
+    const { record, location } = pair;
+    const { owner, selected } = donor;
+    if (owner.hostname !== os.hostname())
+        throw refuse("profile-other-host", `the donor was owned on ${owner.hostname}`);
+    if (owner.pid !== location.ownerPid || owner.startKey !== location.ownerStartKey) {
+        throw refuse("profile-unattributed", `pid ${owner.pid} is not the incarnation ${record.gardenId}'s binding names`);
+    }
+    if (selected.n !== record.nativeSessionId) {
+        throw refuse("profile-n-mismatch", `the donor selected ${selected.n}, the record names ${record.nativeSessionId}`);
+    }
+    const recorded = selected.profile;
+    if (!nonEmpty(recorded))
+        throw refuse("profile-unattributed", "the donor's schema 1 claim records no profile");
+    const cwdHash = createHash("sha256").update(record.cwd).digest("hex").slice(0, 24);
+    if (path.join(recorded, "experimental", "durable-sessions", cwdHash, selected.n) !== selected.directory) {
+        throw refuse("profile-layout-mismatch", `${selected.directory} is not joined from ${recorded} and ${record.cwd}`);
+    }
+    let real;
+    try {
+        real = fs.realpathSync(selected.directory);
+    }
+    catch (error) {
+        throw refuse("profile-alias-moved", `${selected.directory}: ${messageOf(error)}`);
+    }
+    if (real !== resource)
+        throw refuse("profile-alias-moved", `${selected.directory} now reaches ${real}, not ${resource}`);
+    return recorded;
+}
+/**
+ * A parent's reservation of one pi-durable citizen's D for one child (#157 B3): record-arm(gid), then S_D(R), on the
+ * record and C4 pair read inside the arm hold. Both are released before this returns, so before any launch; the
+ * caller's own per-target lock, if it holds one, stays its outer scope and is never taken here. An eligibility
+ * refusal writes nothing. A release that fails AFTER the reservation was written is a different failure: the
+ * reservation exists, and the error names it in `written` (its reason and message stay the release's own). Either
+ * way its caller must not launch, and nothing here withdraws, retries or repairs.
+ */
+export async function reservePiDurableSession(request) {
+    if (!isObject(request))
+        throw refuse("reservation-invalid", "a reserve names a garden id and four meta roots");
+    const gardenId = requireReservationGardenId(request.gardenId);
+    const metaRoot = requireMetaRoot(request.roots);
+    const roots = standardRoots(metaRoot);
+    const owner = thisOwner();
+    const arm = takeRecordArm(gardenId, roots);
+    let reserved;
+    try {
+        reserved = await reserveInPair(gardenId, roots, metaRoot, owner);
+    }
+    catch (error) {
+        throw leaveRecordArm(arm, error);
+    }
+    const failure = leaveRecordArm(arm, undefined);
+    if (failure !== undefined) {
+        const { resource, generation } = reserved;
+        throw afterWrite(failure, { resource, state: "reserved", generation, ownerPid: owner.pid });
+    }
+    return reserved;
+}
+/** The reserve's rows and write, inside S_D(R), on the pair read in this arm hold. Rows decide before P-rules. */
+async function reserveInPair(gardenId, roots, metaRoot, owner) {
+    const pair = freshPair(gardenId, roots);
+    const { record, location } = pair;
+    const resource = location.nativeDirectory;
+    // Set once the write returned: a release failing after it must name the reservation it left (joint review D3).
+    let committed;
+    const written = await withTx(resource, () => {
+        const claim = readClaim(resource);
+        if (claim === undefined)
+            throw refuse("reserve-unarmed", `${resource} holds no claim; a reserve never enrolls`);
+        if (claim.resource !== resource) {
+            throw refuse("claim-resource-mismatch", `the claim in ${resource} names ${claim.resource}`);
+        }
+        if (claim.state !== "closed")
+            requireHolderGone(claim, resource, owner.hostname);
+        if (claim.state === "closed" && claim.end?.storage !== "closed") {
+            throw refuse("reserve-not-clean", `${resource} closed without its storage ever opening`);
+        }
+        // P1–P6 judge the native donor: a dead reservation's flat `from`, never its parent.
+        const donor = donorOf(claim);
+        const profile = requireProfile(donor, pair, resource);
+        // The snapshot is taken on S, the donor's own selection: the SDK's lease is `${S}.lock`, never `${R}.lock`.
+        const sidecar = leasePresent(donor.selected.directory);
+        let nativeLease = "absent";
+        if (claim.state === "closed") {
+            if (sidecar)
+                throw refuse("legacy-lease-present", `${donor.selected.directory}.lock exists after a clean close`);
+        }
+        else if (claim.state === "reserved") {
+            const before = reservationOf(claim).nativeLease;
+            if (before === "absent" && sidecar) {
+                throw refuse("lease-appeared", `${donor.selected.directory}.lock appeared after its reservation saw none`);
+            }
+            if (before === "present-attributed" && sidecar)
+                nativeLease = "present-attributed";
+        }
+        else if (leaseAttributed(claim.lease)) {
+            if (sidecar)
+                nativeLease = "present-attributed";
+        }
+        else if (sidecar) {
+            throw refuse("lease-unattributed", `${donor.selected.directory}.lock exists, and the dead owner never held it`);
+        }
+        const body = {
+            schemaVersion: PI_DURABLE_OWNER_SCHEMA_VERSION,
+            resource,
+            selected: donor.selected,
+            state: "reserved",
+            owner,
+            generation: newGeneration(),
+            firstParticipation: claim.firstParticipation,
+            ...(claim.state === "closed" ? {} : { reclaimedFrom: reclaimOf(claim) }),
+            reservation: {
+                gardenId: record.gardenId,
+                n: record.nativeSessionId,
+                cwd: record.cwd,
+                resource,
+                profile,
+                attachIncarnation: location.attachIncarnation,
+                nativeLease,
+                from: donor,
+            },
+            lease: "never-held",
+            writtenAt: new Date().toISOString(),
+        };
+        writeClaim(resource, body);
+        committed = writtenOf(body);
+        return body;
+    }).catch((error) => {
+        throw afterWrite(error, committed);
+    });
+    return {
+        gardenId: record.gardenId,
+        metaRoot,
+        resource,
+        generation: written.generation,
+        profile: reservationOf(written).profile,
+        cwd: record.cwd,
+        owner,
+    };
+}
+/**
+ * A launched child's adoption of exactly one reservation (#157 B3), inside record-arm(gid) then S_D(R), never the
+ * parent's per-target lock, on the pair read in this hold. Every row must hold; a refusal writes nothing and takes no
+ * lease. The admission's directory is resolved inside S_D, never before it. The ticket returns only after both locks
+ * are released, so the native lease and storage come after them.
+ */
+async function adoptOwner(request, adoption) {
+    const admission = requireAdmission(request);
+    const owner = thisOwner();
+    const arm = takeRecordArm(adoption.gardenId, adoption.roots);
+    let adopted;
+    try {
+        adopted = await adoptInPair(admission, adoption, owner);
+    }
+    catch (error) {
+        throw leaveRecordArm(arm, error);
+    }
+    const failure = leaveRecordArm(arm, undefined);
+    if (failure !== undefined)
+        throw failure;
+    return new OwnerTicket(adopted.resource, adopted);
+}
+/** The adoption's rows and write, inside S_D(R), on the pair read in this arm hold. */
+async function adoptInPair(admission, adoption, owner) {
+    const { record, location } = freshPair(adoption.gardenId, adoption.roots);
+    const resource = location.nativeDirectory;
+    const { directory, selectedN, profile } = admission;
+    return withTx(resource, () => {
+        const claim = readClaim(resource);
+        if (claim !== undefined && claim.resource !== resource) {
+            throw refuse("claim-resource-mismatch", `the claim in ${resource} names ${claim.resource}`);
+        }
+        if (claim === undefined || claim.state !== "reserved") {
+            throw refuse("adopt-not-reserved", `${resource} holds no reservation to adopt`);
+        }
+        const reservation = reservationOf(claim);
+        if (claim.generation !== adoption.sourceGeneration) {
+            throw refuse("adopt-generation-mismatch", `${resource} is at ${claim.generation}, not ${adoption.sourceGeneration}`);
+        }
+        if (record.attachIncarnation !== reservation.attachIncarnation) {
+            throw refuse("adopt-binding-changed", `${record.gardenId} was bound again after its reservation`);
+        }
+        // D as the admission names it NOW, in this hold: a path resolved before S_D is not this decision's evidence.
+        let real;
+        try {
+            real = fs.realpathSync(directory);
+        }
+        catch (error) {
+            throw refuse("directory-invalid", `${directory}: ${messageOf(error)}`);
+        }
+        const expected = [adoption.gardenId, record.nativeSessionId, record.cwd, real];
+        const named = [reservation.gardenId, reservation.n, reservation.cwd, reservation.resource];
+        if (expected.some((value, index) => value !== named[index])) {
+            throw refuse("adopt-reservation-mismatch", `the reservation names ${named.join(", ")}, not ${expected.join(", ")}`);
+        }
+        const cwdHash = createHash("sha256").update(record.cwd).digest("hex").slice(0, 24);
+        const joined = path.join(profile, "experimental", "durable-sessions", cwdHash, record.nativeSessionId);
+        if (profile !== reservation.profile || directory !== claim.selected.directory || joined !== directory) {
+            throw refuse("adopt-profile-mismatch", `${directory} with profile ${profile} is not the reserved selection`);
+        }
+        if (claim.owner.hostname !== owner.hostname) {
+            throw refuse("owner-other-host", `the reservation in ${resource} was taken on ${claim.owner.hostname}`);
+        }
+        if (reservation.nativeLease === "absent" && leasePresent(directory)) {
+            throw refuse("adopt-lease-appeared", `${directory}.lock appeared after the reservation saw none`);
+        }
+        const body = {
+            schemaVersion: PI_DURABLE_OWNER_SCHEMA_VERSION,
+            resource,
+            selected: { n: selectedN, directory, profile },
+            state: "fenced",
+            owner,
+            generation: newGeneration(),
+            firstParticipation: claim.firstParticipation,
+            adoptedFrom: { generation: claim.generation, owner: claim.owner },
+            lease: "never-held",
+            writtenAt: new Date().toISOString(),
+        };
+        writeClaim(resource, body);
+        return body;
+    });
+}
+function sameOwner(a, b) {
+    return a.pid === b.pid && a.startKey === b.startKey && a.hostname === b.hostname;
+}
+/**
+ * The parent's withdrawal of its OWN reservation, once its launch is definitely none-created (its caller's judgement
+ * from the rail's own outcome). One S_D hold and no record or C4 read: only `reserved` + this owner + exactly g_r is
+ * withdrawn, back to the donor's own row under a new generation. Nothing of the reservation, the reserve's reclaim or
+ * any earlier history is carried; anything else writes nothing and refuses `withdraw-not-own`. A release that fails
+ * after the donor's row was written names that row in `written` (joint review D1): the reservation is gone then, and
+ * only the release's residue is left.
+ */
+export async function withdrawPiDurableReservation(reservation) {
+    const owner = thisOwner();
+    const resource = reservation.resource;
+    let committed;
+    await withTx(resource, () => {
+        const claim = readClaim(resource);
+        if (claim?.state !== "reserved")
+            throw refuse("withdraw-not-own", `${resource} is not reserved`);
+        if (claim.generation !== reservation.generation) {
+            throw refuse("withdraw-not-own", `${resource} is at ${claim.generation}, not ${reservation.generation}`);
+        }
+        if (!sameOwner(claim.owner, owner)) {
+            throw refuse("withdraw-not-own", `${resource} is reserved by pid ${claim.owner.pid}, not this process`);
+        }
+        const donor = reservationOf(claim).from;
+        const body = {
+            schemaVersion: PI_DURABLE_OWNER_SCHEMA_VERSION,
+            resource: claim.resource,
+            selected: donor.selected,
+            state: donor.state,
+            owner: donor.owner,
+            generation: newGeneration(),
+            firstParticipation: claim.firstParticipation,
+            lease: donor.lease,
+            ...(donor.end === undefined ? {} : { end: donor.end }),
+            writtenAt: new Date().toISOString(),
+        };
+        writeClaim(resource, body);
+        committed = writtenOf(body);
+    }).catch((error) => {
+        throw afterWrite(error, committed);
+    });
+}
+/**
+ * `adopted`: any state carrying `adoptedFrom.generation === g_r` (an adoption write, not readiness or success);
+ * `not-yet-adopted`: still `reserved` at g_r; `lost`: any other claim the strict reader accepted. A claim that could
+ * not be read, is gone, or names another resource is `unobserved` by name, never `lost`.
+ */
+export function observePiDurableReservation(reservation) {
+    let claim;
+    try {
+        claim = readClaim(reservation.resource);
+    }
+    catch (error) {
+        if (error instanceof PiDurableOwnerFenceError) {
+            return { class: "unobserved", reason: error.reason, detail: error.message };
+        }
+        throw error;
+    }
+    if (claim === undefined) {
+        return { class: "unobserved", reason: "claim-missing", detail: `${reservation.resource} holds no claim` };
+    }
+    if (claim.resource !== reservation.resource) {
+        return { class: "unobserved", reason: "claim-resource-mismatch", detail: `the claim names ${claim.resource}` };
+    }
+    if (claim.adoptedFrom?.generation === reservation.generation)
+        return { class: "adopted" };
+    if (claim.state === "reserved" && claim.generation === reservation.generation)
+        return { class: "not-yet-adopted" };
+    return { class: "lost" };
+}