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

package/dist/store.js

@@ -64,10 +64,19 @@ export const PROFILE_PRAGMAS = {
     exclusive: { locking_mode: "exclusive", journal_mode: "wal", synchronous: 2, mmap_size: 0 },
     shared: { locking_mode: "normal", journal_mode: "wal", synchronous: 2, mmap_size: 0 },
 };
-/** Read every pragma of `profile` back and refuse (StorePragmaError) when any differs. */
-export async function assertPragmas(database, profile) {
+/**
+ * On macOS, fsync does not flush the drive's cache, so a commit FULL syncs could still be lost to a power cut. These make
+ * SQLite sync with F_FULLFSYNC instead, at every commit and every checkpoint.
+ */
+export const FULLFSYNC_PRAGMAS = { fullfsync: 1, checkpoint_fullfsync: 1 };
+/** What `profile` must read back on `platform`: its own pragmas, and on macOS `FULLFSYNC_PRAGMAS` too. */
+export function profilePragmas(profile, platform = process.platform) {
+    return platform === "darwin" ? { ...PROFILE_PRAGMAS[profile], ...FULLFSYNC_PRAGMAS } : PROFILE_PRAGMAS[profile];
+}
+/** Read every pragma of `profile` on `platform` (default this one) back and refuse (StorePragmaError) when any differs. */
+export async function assertPragmas(database, profile, platform = process.platform) {
     const mismatches = [];
-    for (const [pragma, expected] of Object.entries(PROFILE_PRAGMAS[profile])) {
+    for (const [pragma, expected] of Object.entries(profilePragmas(profile, platform))) {
         const row = await database.get(`PRAGMA ${pragma}`);
         const actual = row === undefined ? undefined : Object.values(row)[0];
         if (actual !== expected)
@@ -203,7 +212,10 @@ export async function openArchilStore(file, profile = "exclusive", options = {})
         }
         await database.exec("PRAGMA synchronous = FULL"); // fsync the WAL on every commit
         await database.exec("PRAGMA mmap_size = 0"); // no mmap I/O of the database file on a network filesystem
-        await assertPragmas(database, profile);
+        const platform = options.platform ?? process.platform;
+        for (const pragma of platform === "darwin" ? Object.keys(FULLFSYNC_PRAGMAS) : [])
+            await database.exec(`PRAGMA ${pragma} = ON`);
+        await assertPragmas(database, profile, platform);
         const storage = await SqliteStorage.open(database);
         return { storage, database, profile, file };
     }

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. */
@@ -241,6 +264,25 @@ export type TokenUser = {
     expiresAt?: string;
     createdAt?: string;
 };
+/** What `archilControl` returns: everything `ensureRunning`, `superviseRuns`, `checkHost`, `fork` and the token janitor use. */
+export type ArchilControl = SupervisorControl & CheckControl & {
+    listUsers(): Promise<TokenUser[]>;
+};
+/** The two calls of the `disk` client (this package's dependency) that `archilControl` makes. */
+export type DiskClient = Pick<typeof import("disk"), "configure" | "getDisk">;
+/**
+ * One Archil disk's control API from an API key, the object `pi-durable-disk supervise` builds for itself: a library
+ * caller that composes its own supervisor (with `daytonaHost`, or a driver of its own) passes it as `control`. The S3 and
+ * control calls go to the disk the key reaches; `listUsers` reads the disk record again on every call (the list lags by
+ * seconds). `configure` is the `disk` client's process-wide setting, so one process controls disks of one key and region.
+ * `client` replaces the `disk` client (tests).
+ */
+export declare function archilControl(options: {
+    readonly apiKey: string;
+    readonly disk: string;
+    readonly region: string;
+    readonly client?: DiskClient;
+}): Promise<ArchilControl>;
 export interface TokenSweepOptions {
     /** The disk's token users (`getDisk(id).authorizedUsers`; the list lags by seconds). */
     listUsers(): Promise<TokenUser[]>;

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 });
@@ -347,6 +347,31 @@ export async function superviseRuns(refs, host, opts) {
     }
     return out;
 }
+/**
+ * One Archil disk's control API from an API key, the object `pi-durable-disk supervise` builds for itself: a library
+ * caller that composes its own supervisor (with `daytonaHost`, or a driver of its own) passes it as `control`. The S3 and
+ * control calls go to the disk the key reaches; `listUsers` reads the disk record again on every call (the list lags by
+ * seconds). `configure` is the `disk` client's process-wide setting, so one process controls disks of one key and region.
+ * `client` replaces the `disk` client (tests).
+ */
+export async function archilControl(options) {
+    const { configure, getDisk } = options.client ?? (await import("disk"));
+    configure({ apiKey: options.apiKey, region: options.region });
+    const disk = await getDisk(options.disk);
+    return {
+        getObject: (key) => disk.getObject(key),
+        headObject: (key) => disk.headObject(key),
+        putObject: (key, body, putOptions) => disk.putObject(key, body, putOptions),
+        addUser: (user) => disk.addUser(user),
+        removeUser: (type, identifier) => disk.removeUser(type, identifier),
+        listDelegations: () => disk.listDelegations(),
+        revokeDelegation: (d) => disk.revokeDelegation(d),
+        exec: (command) => disk.exec(command),
+        listObjects: (prefix, listOptions) => disk.listObjects(prefix, listOptions),
+        deleteObjects: (keys, deleteOptions) => disk.deleteObjects(keys, deleteOptions),
+        listUsers: async () => (await getDisk(options.disk)).authorizedUsers ?? [],
+    };
+}
 const RELEASED = ["paused", "sleeping", "done", "failed"];
 /**
  * Remove mount-token users that no live mount needs. Removing a token user under a live mount makes that mount lose its

package/dist/watchdog.d.ts

@@ -9,6 +9,8 @@ export interface SweepOptions {
     readonly proc?: string;
     readonly sys?: string;
     readonly kill?: (pid: number, signal: NodeJS.Signals) => void;
+    /** Lists processes with this ps(1) instead of reading `proc`: the default on macOS, which has no /proc, unless `proc` is given. */
+    readonly ps?: (file: string, args: readonly string[]) => string;
 }
 /** One look at the shared state at `now`. True once the lease has lapsed, for good; the first look records the age. */
 export declare const lapsed: (shared: BigInt64Array, now: bigint) => boolean;
@@ -16,7 +18,7 @@ export declare const lapsed: (shared: BigInt64Array, now: bigint) => boolean;
  * SIGKILL the instance's commands: the process group of each direct child (pi starts each command as its own group's
  * leader), or the child alone when it shares the instance's group; with `ownCgroup`, every other process of the cgroup.
  * Never the instance or its group. A process this user may not signal (sudo's archil helpers) is skipped. Returns the
- * number of signals sent. `stat` lines are `pid (comm) state ppid pgrp ...`, read after the last `)` since comm may hold
+ * number of signals sent. Where there is no /proc (macOS) the processes come from one ps listing, and there is no cgroup. `stat` lines are `pid (comm) state ppid pgrp ...`, read after the last `)` since comm may hold
  * spaces and parentheses.
  */
 export declare const sweep: (instance: number, options?: SweepOptions) => number;

package/dist/watchdog.js

@@ -1,8 +1,9 @@
 // The lease watchdog on a thread of its own. A store commit is synchronous, so a FUSE daemon that stops
 // answering blocks the instance's main thread inside the kernel, and with it every timer the main thread owns. This
-// thread never touches the mount: it reads a clock reading the main thread shares, /proc and the cgroup, and sends
-// signals. Once the lease has lapsed it kills the instance's commands on every look, until the main thread runs again,
+// thread never touches the mount: it reads a clock reading the main thread shares, /proc and the cgroup (on macOS, one
+// ps listing), and sends signals. Once the lease has lapsed it kills the instance's commands on every look, until the main thread runs again,
 // sees the flag and takes the normal fence path (exit 75).
+import * as child_process from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { Worker } from "node:worker_threads";
@@ -49,20 +50,49 @@ function cgroupPids(instance, proc, sys) {
   }
 }
 
-function sweep(instance, options = {}) {
-  const proc = options.proc ?? "/proc";
-  const kill = options.kill ?? ((pid, signal) => process.kill(pid, signal));
+/** The instance's group and its direct children, from /proc. */
+function procTree(instance, proc) {
   const own = stat(proc, instance);
-  if (own === undefined) return 0;
-  const targets = new Set();
+  if (own === undefined) return undefined;
+  const children = [];
   for (const entry of fs.readdirSync(proc)) {
     const pid = Number(entry);
     if (!Number.isInteger(pid) || pid <= 0 || pid === instance) continue;
     const child = stat(proc, pid);
-    if (child === undefined || child.ppid !== instance) continue;
-    targets.add(child.pgrp === own.pgrp || child.pgrp <= 1 ? pid : -child.pgrp);
+    if (child !== undefined && child.ppid === instance) children.push({ pid, pgrp: child.pgrp });
+  }
+  return { pgrp: own.pgrp, children };
+}
+
+/** The same from one ps listing, where there is no /proc (macOS). */
+function psTree(instance, ps) {
+  let text;
+  try {
+    text = ps("/bin/ps", ["-A", "-o", "pid=,ppid=,pgid="]);
+  } catch {
+    return undefined;
+  }
+  const rows = [];
+  for (const line of text.split("\n")) {
+    const f = line.trim().split(/\s+/).map(Number);
+    if (f.length === 3 && f.every(Number.isInteger)) rows.push({ pid: f[0], ppid: f[1], pgrp: f[2] });
   }
-  if (options.ownCgroup) {
+  const own = rows.find((row) => row.pid === instance);
+  if (own === undefined) return undefined;
+  return { pgrp: own.pgrp, children: rows.filter((row) => row.ppid === instance && row.pid > 0 && row.pid !== instance) };
+}
+
+const runPs = (file, args) => child_process.execFileSync(file, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10000 });
+
+function sweep(instance, options = {}) {
+  const proc = options.proc ?? "/proc";
+  const kill = options.kill ?? ((pid, signal) => process.kill(pid, signal));
+  const ps = options.ps ?? (options.proc === undefined && process.platform === "darwin" ? runPs : undefined);
+  const tree = ps === undefined ? procTree(instance, proc) : psTree(instance, ps);
+  if (tree === undefined) return 0;
+  const targets = new Set();
+  for (const child of tree.children) targets.add(child.pgrp === tree.pgrp || child.pgrp <= 1 ? child.pid : -child.pgrp);
+  if (options.ownCgroup && ps === undefined) {
     for (const pid of cgroupPids(instance, proc, options.sys ?? "/sys/fs/cgroup")) if (pid !== instance && pid > 0) targets.add(pid);
   }
   let sent = 0;
@@ -78,6 +108,7 @@ function sweep(instance, options = {}) {
 }
 `;
 const WORKER_SOURCE = `"use strict";
+const child_process = require("node:child_process");
 const fs = require("node:fs");
 const path = require("node:path");
 const { workerData } = require("node:worker_threads");
@@ -88,14 +119,14 @@ setInterval(() => {
   Atomics.add(shared, SLOT_KILLED, BigInt(sweep(workerData.instance, { ownCgroup: workerData.ownCgroup })));
 }, workerData.checkMs);
 `;
-const compiled = new Function("fs", "path", `"use strict";${LIB}\nreturn { lapsed, sweep };`)(fs, path);
+const compiled = new Function("child_process", "fs", "path", `"use strict";${LIB}\nreturn { lapsed, sweep };`)(child_process, fs, path);
 /** One look at the shared state at `now`. True once the lease has lapsed, for good; the first look records the age. */
 export const lapsed = compiled.lapsed;
 /**
  * SIGKILL the instance's commands: the process group of each direct child (pi starts each command as its own group's
  * leader), or the child alone when it shares the instance's group; with `ownCgroup`, every other process of the cgroup.
  * Never the instance or its group. A process this user may not signal (sudo's archil helpers) is skipped. Returns the
- * number of signals sent. `stat` lines are `pid (comm) state ppid pgrp ...`, read after the last `)` since comm may hold
+ * number of signals sent. Where there is no /proc (macOS) the processes come from one ps listing, and there is no cgroup. `stat` lines are `pid (comm) state ppid pgrp ...`, read after the last `)` since comm may hold
  * spaces and parentheses.
  */
 export const sweep = compiled.sweep;

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`);
+    }
+}