@parcha/pi-durable-disk 0.1.0-beta.14 → 0.1.0-beta.15

package/dist/run.js

@@ -311,12 +311,15 @@ class Lease {
         return this.#fence?.done ?? Promise.resolve();
     }
     /**
-     * The order after the claim. `run.json` is written (`running`, generation + 1, this holder, a heartbeat) and the
-     * heartbeat starts right after the owner lock, before the store and the Harness open, so a supervisor never sees the
-     * previous incarnation's stale heartbeat on a live claim. That first write keeps the previous `sealedSeq`, which the
-     * seal check still needs; `live()` clears it once the store is open.
+     * The order after the claim: the owner lock, the layout, the reap of a killed incarnation's commands, `afterClaim`
+     * (openDurableRun's), a new run's seed (afterClaim's over the options'), then `run.json` (`running`, generation + 1,
+     * this holder, a heartbeat) and the heartbeat, before
+     * the store and the Harness open. Nothing is published before that write: an open that fails earlier leaves `run.json`
+     * as it found it, so a supervisor counts a failed start and backs off; its start grace covers the steps before it.
+     * Once written, a supervisor never sees the previous incarnation's stale heartbeat on the live claim. That first write
+     * keeps the previous `sealedSeq`, which the seal check still needs; `live()` clears it once the store is open.
      */
-    async open(step, holder) {
+    async open(step, holder, afterClaim) {
         const claim = this.rawClaim;
         // SQLite resolves symbolic links in a file name, `/proc/self/fd/<n>` included, so `owner.lock` is the one file opened
         // by path: right after the mount check, and the file it names must then be the one in the claim directory.
@@ -341,6 +344,25 @@ class Lease {
         const previous = await this.#readPrevious();
         this.#previous = previous;
         this.#lastSeq = previous?.sealedSeq ?? 0;
+        await step("layout", () => this.#layout());
+        // A claim that records its commands (a local run's): end what a killed incarnation left running, before any code of
+        // this incarnation runs, so no command of it still writes in work/ once the run resumes. A process of it that outlives
+        // its SIGKILL refuses the open (HeldError, 76): the run never resumes beside it, and its record stays for the next open.
+        const commands = claim.commands;
+        if (commands !== undefined)
+            await step("commands", () => reapOrRefuse(commands));
+        const given = afterClaim ? await step("after-claim", () => afterClaim(claim)) : undefined;
+        // A new run (no run.json): its seed writes what it starts with, and only then is it published. afterClaim's seed
+        // goes over the options'.
+        const seed = given?.seed ?? this.#options.seed;
+        if (seed !== undefined && previous === undefined) {
+            await step("seed", async () => {
+                await this.#dir.assertMounted();
+                await seed({ root: claim.root, storePath: join(claim.store, STORE_FILE), workDir: claim.work });
+                await this.#dir.assertMounted();
+                await claim.barrier();
+            });
+        }
         await step("run.json", async () => {
             const now = new Date().toISOString();
             this.#noteBeat(await this.#write(() => ({
@@ -366,19 +388,21 @@ class Lease {
                 ownCgroup: this.#options.ownCgroup === true,
             });
         });
-        await step("layout", async () => {
-            for (const dir of [claim.store, claim.work, join(claim.root, "tmp")]) {
-                const under = relative(claim.root, dir);
-                if (under === "" || under.startsWith("..") || isAbsolute(under))
-                    throw new RunError("INVALID_ARGUMENT", `${dir} is not under the claim root ${claim.root}`);
-                try {
-                    await mkdir(join(this.#dir.at, under), { recursive: true });
-                }
-                catch (error) {
-                    throw ownWriteFenced(dir, error);
-                }
+    }
+    /** `store/`, `work/` and `tmp/`, made through the held claim directory. */
+    async #layout() {
+        const claim = this.rawClaim;
+        for (const dir of [claim.store, claim.work, join(claim.root, "tmp")]) {
+            const under = relative(claim.root, dir);
+            if (under === "" || under.startsWith("..") || isAbsolute(under))
+                throw new RunError("INVALID_ARGUMENT", `${dir} is not under the claim root ${claim.root}`);
+            try {
+                await mkdir(join(this.#dir.at, under), { recursive: true });
             }
-        });
+            catch (error) {
+                throw ownWriteFenced(dir, error);
+            }
+        }
     }
     async checkSeal(store) {
         const sealed = this.sealedSeq;
@@ -611,7 +635,7 @@ class Lease {
             throw new RunError("RUN_RELEASED", `run ${this.ref.id} is released`);
     }
 }
-async function openLease(ref, options, step) {
+async function openLease(ref, options, step, afterClaim) {
     const context = options.context ?? BACKGROUND_CONTEXT;
     leaseOf(options.lease);
     let holder;
@@ -633,7 +657,7 @@ async function openLease(ref, options, step) {
     }));
     const lease = new Lease(ref, claim, options, context);
     try {
-        await lease.open(step, holder);
+        await lease.open(step, holder, afterClaim);
     }
     catch (error) {
         await lease.abandon(error);
@@ -642,8 +666,9 @@ async function openLease(ref, options, step) {
     return lease;
 }
 /**
- * Open the claim's lifecycle for run `ref` (see `RunLease`): acquire and verify the claim, take the owner lock, write
- * `run.json` and start the heartbeat and the self-fence, create `store/`, `work/` and `tmp/`. Errors are typed as for
+ * Open the claim's lifecycle for run `ref` (see `RunLease`): acquire and verify the claim, take the owner lock, create
+ * `store/`, `work/` and `tmp/`, reap a killed incarnation's commands, seed a new run, write `run.json` and start the
+ * heartbeat and the self-fence. Errors are typed as for
  * `openDurableRun`: HeldError (76), FencedError (75, also passed to `onFenced`), RunRecordError (65), RunError
  * INVALID_ARGUMENT before any claim.
  */
@@ -697,6 +722,7 @@ class Run {
         // Both refusals here are terminal: the run is marked `failed`, keeping its seal, so the supervisor stops on it.
         await step("seal", () => lease.checkSeal(this.#store));
         const storage = lease.observe(this.#store.storage);
+        // openDurableRun refused an open without Harness options (here or from afterClaim) before this runs.
         this.#harness = await step("harness", () => Harness.open(storage, { ...this.#options.harness, env: this.env }, this.#context));
         await step("live", () => lease.live());
         const before = this.#options.beforeResume;
@@ -749,8 +775,8 @@ class Run {
     }
 }
 /**
- * Open run `ref` on this host: the lease (`openRunLease`: claim, owner lock, `run.json`, heartbeat and
- * self-fence, layout), then the store, the seal check before anything commits, pi's Harness with the app's registry,
+ * Open run `ref` on this host: the lease (`openRunLease`: claim, owner lock, layout, the commands reap, then
+ * `afterClaim`, a new run's seed, then `run.json`, heartbeat and self-fence), then the store, the seal check before anything commits, pi's Harness with the app's registry,
  * the seal cleared in `run.json`, resume.
  *
  * Errors are typed: HeldError (76) when another client, another process on this host or another connection holds the
@@ -758,25 +784,32 @@ class Run {
  * RunError STORE_HEAD_UNREADABLE (70), each after marking the run `failed` and releasing the claim.
  */
 export async function openDurableRun(ref, options) {
+    if (!options.harness && !options.afterClaim)
+        throw new RunError("INVALID_ARGUMENT", "openDurableRun needs pi's Harness options, from its options or from afterClaim");
     const context = options.context ?? BACKGROUND_CONTEXT;
     const step = stepper(options.onStep);
     let env;
-    const lease = await openLease(ref, { ...options, context, cleanup: (c) => env?.cleanup(c) ?? Promise.resolve() }, step);
+    let opening = options;
+    const given = options.afterClaim;
+    // Inside the lease's open, before run.json: a factory that fails publishes nothing of this incarnation.
+    const afterClaim = given &&
+        (async ({ ref: claimRef, root, work, store }) => {
+            const got = await given({ ref: claimRef, root, work, store });
+            opening = { ...options, ...(got.harness ? { harness: got.harness } : {}), ...(got.beforeResume ? { beforeResume: got.beforeResume } : {}) };
+            if (!opening.harness)
+                throw new RunError("INVALID_ARGUMENT", "openDurableRun needs pi's Harness options: afterClaim returned none, and its options give none");
+            return got.seed ? { seed: got.seed } : {};
+        });
+    // The lease's cleanup is the environment's: abandoning the lease cleans both.
+    const lease = await openLease(ref, { ...options, context, cleanup: (c) => env?.cleanup(c) ?? Promise.resolve() }, step, afterClaim);
     try {
-        // A claim that records its commands (a local run's): end what a killed incarnation left running, now that the owner
-        // lock is held and before the Harness opens, so no command of it still writes in work/ once the run resumes.
-        const commands = lease.rawClaim.commands;
-        // A process of a killed incarnation that outlives its SIGKILL refuses the open (HeldError, 76): the run never resumes
-        // beside it, and its record stays for the next open.
-        if (commands !== undefined)
-            await step("commands", () => reapOrRefuse(commands));
         env = (options.env ?? ((c) => archilEnv(c)))(lease.rawClaim);
     }
     catch (error) {
         await lease.abandon(error);
         throw error;
     }
-    const run = new Run(lease, env, options, context);
+    const run = new Run(lease, env, opening, context);
     try {
         await run.open(step);
     }

package/dist/status.d.ts

@@ -55,6 +55,14 @@ export declare class RunRecordError extends PdaError {
 export declare function parseRunRecord(text: string): RunRecord;
 /** The `run.json` under a run's root on a local mount (or in a claim directory), or undefined when the run has none yet. */
 export declare function readRunRecord(root: string | ClaimDir): Promise<RunRecord | undefined>;
+/**
+ * The status of a run on a local directory (`localRun`): `<root>/run.json`, where `root` is the directory `localRun(root)`
+ * takes (not its `work/`). Read as `readRunStatus` reads a disk's through the control API: the same strict parser and the
+ * same `RunRecord`. It only reads: no lock, no mount and no store are touched, so it is safe beside a live instance, whose
+ * next write replaces the file whole. A run with no `run.json` yet, or no directory, is `null`; a record that is malformed
+ * is `RunRecordError` (`RUN_JSON_INVALID`); any other read error is thrown.
+ */
+export declare function readLocalRunStatus(root: string): Promise<RunRecord | null>;
 /**
  * True while the record's last heartbeat is younger than `expiryMs` on the reader's clock. The supervisor allows for
  * clock skew between hosts inside the expiry.

package/dist/status.js

@@ -96,6 +96,16 @@ export async function readRunRecord(root) {
     }
     return parseRunRecord(text);
 }
+/**
+ * The status of a run on a local directory (`localRun`): `<root>/run.json`, where `root` is the directory `localRun(root)`
+ * takes (not its `work/`). Read as `readRunStatus` reads a disk's through the control API: the same strict parser and the
+ * same `RunRecord`. It only reads: no lock, no mount and no store are touched, so it is safe beside a live instance, whose
+ * next write replaces the file whole. A run with no `run.json` yet, or no directory, is `null`; a record that is malformed
+ * is `RunRecordError` (`RUN_JSON_INVALID`); any other read error is thrown.
+ */
+export async function readLocalRunStatus(root) {
+    return (await readRunRecord(root)) ?? null;
+}
 /**
  * True while the record's last heartbeat is younger than `expiryMs` on the reader's clock. The supervisor allows for
  * clock skew between hosts inside the expiry.

package/dist/supervise.d.ts

@@ -12,9 +12,14 @@ export type HostHandle = {
     driver: string;
     [key: string]: Json;
 };
-/** Which start this is: the generation the instance will open (run.json's generation + 1), also in the token's nickname. */
+/**
+ * Which start this is: the generation the instance will open (run.json's generation + 1), also in the token's nickname.
+ * `env`: what this start adds to the instance's environment (a place's per-attempt order), merged over the driver's own
+ * `env`. PATH and PDA_HOLDER are the driver's: a start that sets either, or a name that is not a variable name, is refused.
+ */
 export type StartAttempt = {
     attempt: number;
+    env?: Record<string, string>;
 };
 /** Compute is disposable and pluggable: a driver is these three calls. */
 export interface HostDriver {
@@ -28,6 +33,14 @@ export interface HostDriver {
     status(handle: HostHandle): Promise<HostStatus>;
     /** Stop the instance and whatever it left on its host. A handle the driver cannot reach is a no-op. */
     stop(handle: HostHandle): Promise<void>;
+    /**
+     * Optional: take the instance away abruptly, as a crash would. No drain, no release, nothing cleaned: the run's claim is
+     * left as a crash leaves it (orphaned with its box, or held by a live mount until its lease lapses), and the
+     * supervisor's next pass decides what follows. A handle the driver cannot reach is a no-op.
+     */
+    kill?(handle: HostHandle): Promise<void>;
+    /** What `kill` takes: `process`, the instance's processes while its machine stays (a restart policy may bring them back), or `box`, its machine. */
+    readonly kills?: "process" | "box";
 }
 /** The control-plane calls the supervisor uses; an archil `Disk` satisfies it. */
 export interface SupervisorControl extends ControlApi {
@@ -73,6 +86,16 @@ export interface EnsureOptions {
     tokenTtl?: string;
     /** Prefix of each mount token's nickname. */
     tokenPrefix?: string;
+    /**
+     * A mount token the caller minted for this start (`mintMountToken`), for a caller that mints its own (a place's
+     * `token(attempt)`): a start uses it instead of minting one, and removes it as it would its own when the driver starts
+     * nothing or adopts. A decision that starts nothing leaves it to the caller.
+     */
+    mountToken?: {
+        token: string;
+        identifier: string;
+        nickname: string;
+    };
     /** The caller has work for the run now: start a paused run, or a sleeping one before its `wakeAt`. */
     demand?: boolean;
     /** Create `runs/<id>/` with this owner when it does not exist and nothing holds it. */

package/dist/supervise.js

@@ -282,7 +282,7 @@ async function startInstance(ref, host, opts, why) {
     let token;
     try {
         // The attempt is the generation the instance will write, so the token user names the incarnation it served.
-        token = await mintMountToken(opts.control, { run: { id: ref.id, attempt: why.generation + 1 }, prefix: opts.tokenPrefix, ttl: opts.tokenTtl ?? TOKEN_TTL, now: opts.now });
+        token = opts.mountToken ?? await mintMountToken(opts.control, { run: { id: ref.id, attempt: why.generation + 1 }, prefix: opts.tokenPrefix, ttl: opts.tokenTtl ?? TOKEN_TTL, now: opts.now });
     }
     catch (err) {
         throw new SuperviseError("CONTROL_API_FAILED", `minting a mount token for ${runPath(ref.id)} failed`, { cause: err });

package/dist/with-claim.d.ts

@@ -0,0 +1,63 @@
+import { type ArchilHost } from "./claim.js";
+import type { SupervisorControl } from "./supervise.js";
+/** The control API both calls use; `archilControl`'s satisfies it. */
+export type ClaimControl = Pick<SupervisorControl, "putObject" | "addUser" | "removeUser" | "listDelegations" | "revokeDelegation" | "exec" | "getObject" | "headObject">;
+/** The path `fn` holds: `root` is where it is mounted on this host. */
+export interface HeldPath {
+    readonly root: string;
+    readonly path: string;
+    /** Aborted once the claim is known lost (a barrier refused) or the caller's `signal` aborts. */
+    readonly signal: AbortSignal;
+    /** `archil sync` now: every write so far is durable when it resolves; a refusal is FENCED. */
+    barrier(): Promise<{
+        ms: number;
+    }>;
+}
+export interface WithClaimOptions {
+    /** How long the holder may hold the path; written in its `.claim` as its deadline. Default 60 s. */
+    readonly holdMs?: number;
+    /** How long to queue behind a live holder before CLAIM_HELD. Default 30 s. */
+    readonly waitMs?: number;
+    /** Where the mount goes: `<mountRoot>/runs/<pid>-<uuid>`, of this call's own. Default `/mnt/archil/.claims`. */
+    readonly mountRoot?: string;
+    readonly host?: ArchilHost;
+    readonly signal?: AbortSignal;
+    /** The owner and mode of the path's directories it makes when the disk lacks them. Default this process's, 0700. */
+    readonly owner?: {
+        readonly uid: number;
+        readonly gid: number;
+        readonly mode?: number;
+    };
+}
+export declare const DEFAULT_HOLD_MS = 60000;
+export declare const DEFAULT_WAIT_MS = 30000;
+/**
+ * Hold `path` exclusively while `fn` runs: wait for a live holder (`waitMs`), revoke a lost one, mount `<disk>:/<path>` at
+ * a fresh `<mountRoot>/runs/<pid>-<uuid>`, write `.claim` with this holder's deadline (`holdMs`), run `fn`, then barrier,
+ * unmount and give the mount token back, whether `fn` resolved or threw. Returns `fn`'s value; throws `fn`'s own error,
+ * else INVALID_ARGUMENT, CLAIM_HELD (76, retryable), CONTROL_API_FAILED, the mount's errors, or FENCED (75: the claim was
+ * revoked from under `fn`, whose writes are then not durable).
+ */
+export declare function withClaim<T>(where: {
+    readonly control: ClaimControl;
+    readonly disk: string;
+    readonly region: string;
+    readonly path: string;
+}, fn: (held: HeldPath) => Promise<T>, options?: WithClaimOptions): Promise<T>;
+/**
+ * `<path>/<file>` over S3, once it is released: no delegation on the path (or an ancestor or a descendant) before or
+ * after the read, for SQLite (`sqlite`) no `-wal` with content (its writer checkpointed with TRUNCATE and closed), and the
+ * object unchanged across the read. A held path is CLAIM_HELD (76, retryable; never read an older release instead), a
+ * WAL with content NOT_RELEASED; a file that moved during every one of `attempts` reads (default 3) is CLAIM_HELD. Null
+ * when the file does not exist. It never mounts, so it never blocks a carry back.
+ */
+export declare function readReleased(where: {
+    readonly control: ClaimControl;
+    readonly path: string;
+}, file: string, options?: {
+    readonly sqlite?: boolean;
+    readonly attempts?: number;
+}): Promise<{
+    bytes: Uint8Array;
+    etag: string | null;
+} | null>;

package/dist/with-claim.js

@@ -0,0 +1,325 @@
+// A short exclusive claim on any path of a disk (withClaim), and a consistent S3 read of a released file (readReleased),
+// for a host that keeps state beside its runs: pi-durable-agent's agent home under `agent/`, carried back at a run's end.
+//
+// A claim is one exclusive mount. Archil refuses a second client's mount of the path, of an ancestor or of a descendant,
+// and that refusal is the exclusivity; the delegation listing only decides whom to wait for and whom to revoke. A holder
+// is lost when its client is gone (orphaned), or when it holds exactly the path and the `.claim` there names a deadline
+// that has passed and stays the same across a few seconds (a holder that just mounted rewrites it at once); only a lost
+// holder is revoked. Safety rests on the fence, never on the deadline: a holder revoked while still alive gets EIO at
+// its next fsync, so its commit rolls back and its own call throws FENCED. Both calls are supervisor side: they need the
+// API key's control API.
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { CLAIM_PROBE, DEFAULT_MOUNT_ROOT, exclusiveMount, mintMountToken, removeMountToken, revokeCompanions } from "./claim.js";
+import { ClaimError, HeldError } from "./errors.js";
+export const DEFAULT_HOLD_MS = 60_000;
+export const DEFAULT_WAIT_MS = 30_000;
+const POLL_MS = 250;
+/**
+ * How long a past-deadline `.claim` must stay the same, with the same holder, before that holder counts as lost. A holder
+ * that mounted a moment ago writes its own `.claim` right after its mount; until then the one there is its predecessor's.
+ */
+const CONFIRM_MS = 3_000;
+const TOKEN_TTL = "10m";
+const SEGMENT = /^[A-Za-z0-9._-]+$/;
+/** CLAIM_HELD reads as retryable: the path is not released yet, and nothing older stands in for it. */
+const notReleased = (path, why, cause) => new HeldError("claim", `${path} is held by another client and is not released yet (${why}). CLAIM_HELD is retryable: retry within waitMs, ` +
+    "and never fall back to an older release.", { cause });
+/** `path` if it is one relative path of safe segments that no run owns; else INVALID_ARGUMENT. */
+function claimPath(path) {
+    const segments = path.split("/");
+    if (path === "" || segments.some((s) => !SEGMENT.test(s) || s === "." || s === "..")) {
+        throw new ClaimError("INVALID_ARGUMENT", `${JSON.stringify(path)} is not a relative path of safe segments (letters, digits, ".", "_", "-")`);
+    }
+    if (segments[0] === "runs")
+        throw new ClaimError("INVALID_ARGUMENT", `${path} is under runs/, which openDurableRun and the supervisor claim`);
+    if (segments[0] === ".archil")
+        throw new ClaimError("INVALID_ARGUMENT", `${path} is under .archil/, Archil's own`);
+    return path;
+}
+/** Whether a delegation's path is `path`, under it, or above it (the disk root included): each conflicts with a mount of it. */
+const conflicts = (delegated, path) => {
+    const p = delegated.replace(/^\/+/, "").replace(/\/+$/, "");
+    return p === "" || p === path || p.startsWith(`${path}/`) || path.startsWith(`${p}/`);
+};
+/**
+ * The delegations that conflict with a mount of `path`, from one listing. A pathless one is attributed by inode with one
+ * `exec` (the path's ancestors and everything under it); one that cannot be attributed fails CONTROL_API_FAILED, never
+ * reads as unheld.
+ */
+async function holdersOf(control, path) {
+    let all;
+    try {
+        all = await control.listDelegations();
+    }
+    catch (err) {
+        throw new ClaimError("CONTROL_API_FAILED", "listing delegations failed", { cause: err });
+    }
+    const holders = all.filter((d) => d.path !== undefined && d.path !== null && conflicts(d.path, path));
+    const pathless = all.filter((d) => !d.path);
+    if (pathless.length > 0)
+        holders.push(...(await pathlessOn(control, path, pathless)));
+    return { holders, all };
+}
+async function pathlessOn(control, path, pathless) {
+    if (!control.exec)
+        throw new ClaimError("CONTROL_API_FAILED", `a delegation with no path may be on ${path}, and the control API has no exec to attribute it`);
+    const inodes = [...new Set(pathless.map((d) => d.inodeId))];
+    if (!inodes.every((i) => Number.isSafeInteger(i) && i >= 0))
+        throw new ClaimError("CONTROL_API_FAILED", "a pathless delegation has no valid inode id");
+    // Every path relative to the disk root as ./<path>, so a segment that begins with "-" is never read as an option.
+    const segments = path.split("/");
+    const above = [".", ...segments.slice(0, -1).map((_, i) => `./${segments.slice(0, i + 1).join("/")}`)];
+    const test = inodes.map((i) => `-inum ${i}`).join(" -o ");
+    let r;
+    try {
+        r = await control.exec(`for a in ${above.join(" ")}; do if [ -e "$a" ]; then stat -c '%i' -- "$a" || exit 3; fi; done; if [ -e ./${path} ]; then find ./${path} \\( ${test} \\) -printf '%i\\n' || exit 3; fi`);
+    }
+    catch (err) {
+        throw new ClaimError("CONTROL_API_FAILED", `attributing pathless delegations to ${path} failed`, { cause: err });
+    }
+    if (r.exitCode !== 0)
+        throw new ClaimError("CONTROL_API_FAILED", `attributing pathless delegations to ${path}: exit ${r.exitCode}`);
+    const on = new Set(String(r.stdout ?? "").split("\n").filter(Boolean).map(Number));
+    return pathless.filter((d) => on.has(d.inodeId));
+}
+/** `<path>/.claim` over S3, and whether the deadline it names has passed; null when it cannot be read or parsed. */
+async function readClaim(control, path) {
+    try {
+        const text = new TextDecoder().decode(await control.getObject(`${path}/${CLAIM_PROBE}`));
+        const claim = JSON.parse(text);
+        const deadline = typeof claim.deadline === "string" ? Date.parse(claim.deadline) : Number.NaN;
+        return Number.isFinite(deadline) ? { text, expired: deadline < Date.now() } : null;
+    }
+    catch {
+        return null;
+    }
+}
+const exactly = (d, path) => typeof d.path === "string" && d.path.replace(/^\/+/, "").replace(/\/+$/, "") === path;
+const clientsOf = (holders) => [...new Set(holders.map((d) => d.clientId))].sort().join(",");
+/**
+ * Whether the live holders are lost past their deadline. Only a holder of exactly `path` has its deadline there, so any
+ * other (a descendant's, an ancestor's, one with no path) is never lost this way. And the `.claim` must be the same
+ * expired one, with the same holders, across CONFIRM_MS: a holder that just mounted rewrites it within that time.
+ */
+async function lostPastDeadline(control, path, holders, signal) {
+    if (!holders.every((d) => exactly(d, path)))
+        return false;
+    const first = await readClaim(control, path);
+    if (!first?.expired)
+        return false;
+    await sleep(CONFIRM_MS, undefined, { signal }).catch(() => signal?.throwIfAborted());
+    const again = await holdersOf(control, path);
+    if (clientsOf(again.holders) !== clientsOf(holders))
+        return false;
+    const second = await readClaim(control, path);
+    return second !== null && second.expired && second.text === first.text;
+}
+/** Until nothing conflicts with a mount of `path`: lost holders are revoked, live ones waited for until `deadline`. */
+async function settle(control, path, deadline, signal) {
+    for (;;) {
+        signal?.throwIfAborted();
+        const { holders, all } = await holdersOf(control, path);
+        if (holders.length === 0)
+            return;
+        if (holders.every((d) => d.isOrphaned) || (await lostPastDeadline(control, path, holders, signal))) {
+            try {
+                for (const d of holders)
+                    await control.revokeDelegation({ clientId: d.clientId, inodeId: d.inodeId });
+            }
+            catch (err) {
+                throw new ClaimError("CONTROL_API_FAILED", `revoking the lost holder of ${path} failed`, { cause: err });
+            }
+            await revokeCompanions(control, holders, all);
+            continue;
+        }
+        signal?.throwIfAborted();
+        if (Date.now() >= deadline)
+            throw notReleased(path, `a live holder within its deadline: ${holders.map((d) => d.clientId).join(", ")}`);
+        await sleep(POLL_MS, undefined, { signal }).catch(() => signal?.throwIfAborted());
+    }
+}
+/**
+ * The directories of `path` the disk lacks, made over S3 with `owner`: archil mounts no path whose directory is missing
+ * ("the configured subdirectory does not exist"). A write refused with 409 met another caller that made the directory
+ * and holds it: HeldError, which the caller queues on as on a refused mount.
+ */
+async function ensureDirectories(control, path, owner) {
+    const segments = path.split("/");
+    for (let i = 1; i <= segments.length; i++) {
+        const key = `${segments.slice(0, i).join("/")}/`;
+        try {
+            if ((await control.headObject(key)) === null)
+                await control.putObject(key, "", owner);
+        }
+        catch (err) {
+            if (err.status === 409)
+                throw new HeldError("claim", `${key} is held by the caller that made it (409)`, { cause: err });
+            throw new ClaimError("CONTROL_API_FAILED", `making ${key} on the disk failed`, { cause: err });
+        }
+    }
+}
+const positive = (name, value) => {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new ClaimError("INVALID_ARGUMENT", `${name} ${value} is not a positive whole number of milliseconds`);
+    return value;
+};
+/**
+ * Hold `path` exclusively while `fn` runs: wait for a live holder (`waitMs`), revoke a lost one, mount `<disk>:/<path>` at
+ * a fresh `<mountRoot>/runs/<pid>-<uuid>`, write `.claim` with this holder's deadline (`holdMs`), run `fn`, then barrier,
+ * unmount and give the mount token back, whether `fn` resolved or threw. Returns `fn`'s value; throws `fn`'s own error,
+ * else INVALID_ARGUMENT, CLAIM_HELD (76, retryable), CONTROL_API_FAILED, the mount's errors, or FENCED (75: the claim was
+ * revoked from under `fn`, whose writes are then not durable).
+ */
+export async function withClaim(where, fn, options = {}) {
+    const path = claimPath(where.path);
+    const holdMs = positive("holdMs", options.holdMs ?? DEFAULT_HOLD_MS);
+    const deadline = Date.now() + positive("waitMs", options.waitMs ?? DEFAULT_WAIT_MS);
+    const { control } = where;
+    const mountRoot = options.mountRoot ?? join(DEFAULT_MOUNT_ROOT, ".claims");
+    const owner = { uid: options.owner?.uid ?? process.getuid(), gid: options.owner?.gid ?? process.getgid(), mode: options.owner?.mode ?? 0o700 };
+    for (;;) {
+        await settle(control, path, deadline, options.signal);
+        options.signal?.throwIfAborted();
+        try {
+            await ensureDirectories(control, path, owner);
+        }
+        catch (err) {
+            // Another caller made the directory and holds it: queue again, within the same wait.
+            if (err instanceof HeldError && Date.now() < deadline && !options.signal?.aborted) {
+                await sleep(POLL_MS);
+                continue;
+            }
+            options.signal?.throwIfAborted();
+            throw err instanceof HeldError ? notReleased(path, "its directory is being made by another holder", err) : err;
+        }
+        const minted = await mintMountToken(control, { nickname: `pdc-${path.replaceAll("/", ".")}-${Date.now().toString(36)}`, ttl: TOKEN_TTL });
+        const at = new Date();
+        let mount;
+        try {
+            // <mountRoot>/runs/<name>: the shape archil-scoped's cleanup verbs take, for a host that cannot unmount (Sysbox).
+            mount = await exclusiveMount({ disk: where.disk, region: where.region, path }, join(mountRoot, "runs", `${process.pid}-${randomUUID()}`), minted.token, {
+                host: options.host,
+                probe: `${JSON.stringify({ pid: process.pid, host: hostname(), at: at.toISOString(), deadline: new Date(at.getTime() + holdMs).toISOString() })}\n`,
+            });
+        }
+        catch (err) {
+            await removeMountToken(control, minted.identifier).catch(() => { });
+            // Another caller mounted between the listing and the mount: queue again, within the same wait.
+            if (err instanceof HeldError && Date.now() < deadline && !options.signal?.aborted) {
+                await sleep(POLL_MS);
+                continue;
+            }
+            options.signal?.throwIfAborted();
+            throw err instanceof HeldError ? notReleased(path, "its mount was refused", err) : err;
+        }
+        // Aborted while it mounted: fn never runs, and nothing it holds is kept.
+        if (options.signal?.aborted) {
+            await mount.unmount().catch(() => undefined);
+            await removeMountToken(control, minted.identifier).catch(() => { });
+            options.signal.throwIfAborted();
+        }
+        const lost = new AbortController();
+        const onAbort = () => lost.abort(options.signal?.reason);
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        const barrier = async () => {
+            try {
+                return await mount.barrier();
+            }
+            catch (err) {
+                lost.abort(err);
+                throw err;
+            }
+        };
+        let outcome;
+        try {
+            outcome = { ok: true, value: await fn({ root: mount.root, path, signal: lost.signal, barrier }) };
+        }
+        catch (error) {
+            outcome = { ok: false, error };
+        }
+        let release;
+        try {
+            await barrier();
+        }
+        catch (err) {
+            release = err;
+        }
+        try {
+            await mount.unmount();
+        }
+        catch (err) {
+            release ??= err;
+        }
+        await removeMountToken(control, minted.identifier).catch(() => { });
+        options.signal?.removeEventListener("abort", onAbort);
+        if (!outcome.ok)
+            throw outcome.error;
+        if (release !== undefined)
+            throw release;
+        return outcome.value;
+    }
+}
+/** An object's identity for "did it move": its etag, else its size and last-modified time. */
+function identity(head) {
+    if (head === null || typeof head !== "object")
+        return null;
+    const { etag, size, lastModified } = head;
+    if (typeof etag === "string" && etag !== "")
+        return `etag:${etag}`;
+    return `size:${String(size)}@${lastModified instanceof Date ? lastModified.toISOString() : String(lastModified)}`;
+}
+const sizeOf = (head) => (head !== null && typeof head === "object" ? Number(head.size ?? 0) : 0);
+/**
+ * `<path>/<file>` over S3, once it is released: no delegation on the path (or an ancestor or a descendant) before or
+ * after the read, for SQLite (`sqlite`) no `-wal` with content (its writer checkpointed with TRUNCATE and closed), and the
+ * object unchanged across the read. A held path is CLAIM_HELD (76, retryable; never read an older release instead), a
+ * WAL with content NOT_RELEASED; a file that moved during every one of `attempts` reads (default 3) is CLAIM_HELD. Null
+ * when the file does not exist. It never mounts, so it never blocks a carry back.
+ */
+export async function readReleased(where, file, options = {}) {
+    const path = claimPath(where.path);
+    const key = `${path}/${claimPath(file)}`;
+    const attempts = positive("attempts", options.attempts ?? 3);
+    const { control } = where;
+    const head = async (name) => {
+        try {
+            return await control.headObject(name);
+        }
+        catch (err) {
+            throw new ClaimError("CONTROL_API_FAILED", `head ${name} failed`, { cause: err });
+        }
+    };
+    for (let attempt = 1;; attempt++) {
+        const { holders } = await holdersOf(control, path);
+        if (holders.length > 0)
+            throw notReleased(path, `held by ${holders.map((d) => d.clientId).join(", ")}`);
+        if (options.sqlite && sizeOf(await head(`${key}-wal`)) > 0) {
+            throw new ClaimError("NOT_RELEASED", `${key}-wal has content: its writer did not checkpoint (TRUNCATE) and close, so ${key} alone is not the database`);
+        }
+        const before = await head(key);
+        if (before === null)
+            return null;
+        let bytes;
+        try {
+            bytes = await control.getObject(key);
+        }
+        catch (err) {
+            throw new ClaimError("CONTROL_API_FAILED", `get ${key} failed`, { cause: err });
+        }
+        const after = await head(key);
+        // A writer that mounted, committed to the WAL and let go during the read leaves the database file as it was.
+        if (options.sqlite && sizeOf(await head(`${key}-wal`)) > 0) {
+            throw new ClaimError("NOT_RELEASED", `${key}-wal gained content during the read: a writer committed without a checkpoint (TRUNCATE)`);
+        }
+        const still = (await holdersOf(control, path)).holders.length === 0;
+        if (still && after !== null && identity(after) === identity(before) && sizeOf(after) === bytes.length) {
+            const etag = after.etag;
+            return { bytes, etag: typeof etag === "string" ? etag : null };
+        }
+        if (attempt >= attempts)
+            throw notReleased(path, `${key} changed while it was read, ${attempts} times`);
+    }
+}