@north-light/api 0.3.579 → 0.3.587

package/dist/core/bash-jobs.js

@@ -0,0 +1,455 @@
+// File-backed control plane for bash commands started by the canvas bash valve.
+// Every foreground command owns job.run; backgrounding atomically renames it to
+// job.bg, while foreground completion renames it to job.done. The detached
+// supervisor can therefore outlive pi and still decide whether to report exit.
+import { randomBytes } from 'node:crypto';
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { captureTeardownSnapshot, isAnyPidAlive, isPidAlive, killProcessTreePids } from './canvas/pid.js';
+import { launcherRequest } from '../launcher/client.js';
+import { LaunchRefused } from '../launcher/spec.js';
+import { createFileBeneath, existsBeneath, readTextBeneathIfExists, readdirBeneath, readFileBeneath, renameBeneath, unlinkBeneath, writeFileBeneath } from './spaces/open-beneath.js';
+const MAX_BASH_JOB_PURPOSE_BYTES = 280;
+/** A purpose is display text, never shell input. Keep the file-backed control
+ * plane to one bounded, visible line so old or hand-written job directories
+ * cannot inject control content into terminal or JSON presenters. */
+export function normalizeBashJobPurpose(value) {
+    if (typeof value !== 'string' || /[\p{Cc}\p{Cf}]/u.test(value))
+        return null;
+    const purpose = value.trim();
+    if (purpose === '')
+        return null;
+    return Buffer.byteLength(purpose, 'utf8') <= MAX_BASH_JOB_PURPOSE_BYTES ? purpose : null;
+}
+export function bashJobsDir(contextDir) {
+    return join(contextDir, 'jobs');
+}
+function readJobText(contextDir, path) {
+    return readFileBeneath(dirname(contextDir), path).toString('utf8');
+}
+function jobIds(contextDir) {
+    return readdirBeneath(dirname(contextDir), bashJobsDir(contextDir)).map((entry) => entry.name);
+}
+function has(paths, path) {
+    return existsBeneath(paths.root, path);
+}
+function unlinkIfPresent(root, path) {
+    try {
+        unlinkBeneath(root, path);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+/** Whether a job id can safely be used as one path segment. Generated ids are
+ * numeric epoch prefixes plus a hex suffix; this broader safe alphabet keeps
+ * older file-backed ids readable without allowing path or request delimiters. */
+export function isSafeBashJobId(jobId) {
+    return typeof jobId === 'string'
+        && jobId !== '' && jobId !== '.' && jobId !== '..'
+        && /^[A-Za-z0-9._~-]+$/u.test(jobId)
+        && Buffer.byteLength(jobId, 'utf8') <= 128;
+}
+export function bashJobPaths(contextDir, jobId) {
+    const dir = join(bashJobsDir(contextDir), jobId);
+    return {
+        jobId,
+        root: dirname(contextDir),
+        dir,
+        cmdSh: join(dir, 'cmd.sh'),
+        jobLog: join(dir, 'job.log'),
+        jobExit: join(dir, 'job.exit'),
+        jobRun: join(dir, 'job.run'),
+        jobBg: join(dir, 'job.bg'),
+        jobDone: join(dir, 'job.done'),
+        jobPgid: join(dir, 'job.pgid'),
+        jobPgidIdentity: join(dir, 'job.pgid-identity'),
+        jobActivity: join(dir, 'job.activity'),
+        jobDeadline: join(dir, 'job.deadline'),
+        jobReported: join(dir, 'job.reported'),
+    };
+}
+/** The job's supervisor process group, or undefined for a job started before
+ * pgid was persisted (or a partially-written dir). */
+export function readJobPgid(contextDir, jobId) {
+    try {
+        const n = Number(readJobText(contextDir, bashJobPaths(contextDir, jobId).jobPgid).trim());
+        return Number.isInteger(n) && n > 1 ? n : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Launch-time identity of the supervisor. Missing for jobs created before
+ * process-identity persistence, which are deliberately not safe to signal. */
+export function readJobPgidIdentity(contextDir, jobId) {
+    try {
+        const identity = readJobText(contextDir, bashJobPaths(contextDir, jobId).jobPgidIdentity).trim();
+        return identity === '' ? undefined : identity;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readJobSupervisorState(contextDir, jobId) {
+    const paths = bashJobPaths(contextDir, jobId);
+    const state = {};
+    const pgid = readJobPgid(contextDir, jobId);
+    const identity = readJobPgidIdentity(contextDir, jobId);
+    if (pgid !== undefined)
+        state.pgid = pgid;
+    if (identity !== undefined)
+        state.pgidIdentity = identity;
+    const exit = readTextBeneathIfExists(paths.root, paths.jobExit);
+    if (exit !== null && Number.isSafeInteger(Number(exit.trim())) && exit.trim() !== '')
+        state.exitCode = Number(exit.trim());
+    const deadline = readTextBeneathIfExists(paths.root, paths.jobDeadline);
+    if (deadline !== null && deadline.trim() !== '' && Number.isFinite(Number(deadline.trim())))
+        state.deadlineMs = Number(deadline.trim());
+    const sample = readTextBeneathIfExists(paths.root, paths.jobActivity);
+    if (sample !== null) {
+        const [head, ...files] = sample.split('\n');
+        const [lastActivityMs, sampledAtMs] = (head ?? '').split(' ').map(Number);
+        if (Number.isFinite(lastActivityMs) && Number.isFinite(sampledAtMs)) {
+            state.activity = { lastActivityMs: lastActivityMs, sampledAtMs: sampledAtMs, files: files.filter((file) => file !== '') };
+        }
+    }
+    return state;
+}
+/** Write the auto-handoff cancel deadline beside the job; `clearJobDeadlineFile` removes it once the job row carries it. */
+export function writeJobDeadlineFile(paths, deadlineMs) {
+    writeFileBeneath(paths.root, paths.jobDeadline, `${Math.trunc(deadlineMs)}\n`);
+}
+export function clearJobDeadlineFile(paths) {
+    unlinkIfPresent(paths.root, paths.jobDeadline);
+}
+/** Ids of this node's job directories whose command has not exited — foreground (job.run) or backgrounded (job.bg),
+ *  with or without a job row. What a node stop must signal. */
+export function unfinishedBashJobIds(contextDir) {
+    let entries;
+    try {
+        entries = jobIds(contextDir);
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((jobId) => {
+        const paths = bashJobPaths(contextDir, jobId);
+        try {
+            return (has(paths, paths.jobRun) || has(paths, paths.jobBg)) && !has(paths, paths.jobExit);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Scheduler niceness every command a node runs is started with. Agent work —
+ * builds, test suites, typechecks — sits below the daemon, the brokers, the
+ * viewers, and the person's own shell, so a fan-out of release builds cannot
+ * starve them: the scheduler only honors this under contention and it costs
+ * nothing on an idle host. */
+export const DEFAULT_BASH_NICENESS = 10;
+/** The politest priority the scheduler accepts. A NEGATIVE niceness (more
+ * priority than the broker itself) needs root: `nice` prints a permission error
+ * into the command's own log and runs it at the inherited priority anyway, so
+ * the override range stops at 0. */
+export const MAX_BASH_NICENESS = 19;
+/** Per-node override of the bash niceness, written by `crtr node config --nice`
+ * and read by the valve when it starts each command. Node-local like the job
+ * dirs beside it, so a change applies to the node's very next command without
+ * waiting for a revive. */
+export function bashNicenessPath(contextDir) {
+    return join(bashJobsDir(contextDir), 'niceness');
+}
+/** The niceness this node's commands run at. Any missing, malformed, or
+ * out-of-range file reads as the default rather than an odd priority. */
+export function readBashNiceness(contextDir) {
+    try {
+        const n = Number(readJobText(contextDir, bashNicenessPath(contextDir)).trim());
+        if (!Number.isInteger(n) || n < 0 || n > MAX_BASH_NICENESS)
+            return DEFAULT_BASH_NICENESS;
+        return n;
+    }
+    catch {
+        return DEFAULT_BASH_NICENESS;
+    }
+}
+/** Set the node's bash niceness. The caller owns validation; the store keeps
+ * one integer so the valve's read stays a single file read per command. */
+export function writeBashNiceness(contextDir, niceness) {
+    writeFileBeneath(dirname(contextDir), bashNicenessPath(contextDir), `${Math.trunc(niceness)}\n`);
+}
+/** Launcher jobs have a root-owned bwrap pid, not a process group; direct
+ *  jobs keep their detached supervisor process group. */
+export function isBashJobProcessGroupAlive(pgid, identity) {
+    if (identity === `launcher:${pgid}`)
+        return isPidAlive(pgid);
+    try {
+        process.kill(-pgid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** Whether the job's process is CONFIRMED gone: a direct job's process group has no member
+ *  (signal 0 answers ESRCH), a launcher job's pid is dead. EPERM, any other error, and a missing
+ *  pgid or identity are not confirmation, so a job that cannot be read is never declared gone. */
+export function isBashJobProcessConfirmedGone(pgid, identity) {
+    if (pgid === undefined || identity === undefined)
+        return false;
+    if (identity === `launcher:${pgid}`)
+        return !isPidAlive(pgid);
+    try {
+        process.kill(-pgid, 0);
+        return false;
+    }
+    catch (err) {
+        return err.code === 'ESRCH';
+    }
+}
+/** Best-effort cancellation for a detached bash supervisor. It snapshots the
+ * observable descendant tree while the supervisor is still alive, signals its
+ * leaves before their parents, then uses the shared identity-guarded KILL
+ * escalation. A descendant that detached and reparented before this snapshot
+ * is outside this guarantee. */
+export async function cancelBashJobProcessTree(pgid, expectedIdentity) {
+    const snapshot = captureTeardownSnapshot(pgid, expectedIdentity);
+    if (snapshot.reused || snapshot.tree.length === 0)
+        return false;
+    const tree = [...snapshot.tree].reverse();
+    const signaled = isAnyPidAlive(tree);
+    killProcessTreePids(tree, 'SIGTERM', snapshot.identities);
+    await new Promise((resolve) => setTimeout(resolve, 400));
+    killProcessTreePids(tree, 'SIGKILL', snapshot.identities);
+    return signaled;
+}
+/** Stop a job's process: a launcher job through the launcher, a direct job by its supervisor's process tree.
+ *  False when no process was left to signal. */
+export async function signalBashJob(pgid, identity, nodeId) {
+    if (identity !== `launcher:${pgid}`)
+        return await cancelBashJobProcessTree(pgid, identity);
+    if (nodeId === undefined)
+        throw new Error('launcher job stop requires its owning node');
+    try {
+        const reply = await launcherRequest({ operation: 'stop', pid: pgid, nodeId });
+        if (!('ok' in reply))
+            throw new Error('launcher did not stop job');
+        return true;
+    }
+    catch (error) {
+        if (!(error instanceof LaunchRefused && error.refusal === 'invalid_spec'))
+            throw error;
+        return false;
+    }
+}
+/** Stop one live background job using the same best-effort tree cancellation
+ * semantics as inline abort and timeout. The caller owns the user-facing
+ * notification; this primitive owns only the job control-plane mutation.
+ *
+ * Only a job in the live-background state the roster projects (job.bg present,
+ * job.exit absent) may be signaled. Job directories persist after the
+ * supervisor exits, so a retired, still-foreground, or already-stopped job
+ * would otherwise have its recorded pgid signaled long after the OS could have
+ * reused that id for an unrelated process group. */
+export async function stopBackgroundBashJob(contextDir, jobId, allowForeground = false, nodeId, reason) {
+    const paths = bashJobPaths(contextDir, jobId);
+    if (!has(paths, paths.dir))
+        return { kind: 'missing' };
+    if ((!has(paths, paths.jobBg) && !(allowForeground && has(paths, paths.jobRun))) || has(paths, paths.jobExit))
+        return { kind: 'retired', logPath: paths.jobLog };
+    const pgid = readJobPgid(contextDir, jobId);
+    const pgidIdentity = readJobPgidIdentity(contextDir, jobId);
+    if (pgid === undefined || pgidIdentity === undefined)
+        return { kind: 'not-stoppable', logPath: paths.jobLog };
+    // Claim cancellation before signaling, without claiming completion: a failed
+    // launcher request must leave the job's actual exit status authoritative.
+    const marker = join(paths.dir, 'job.stop');
+    try {
+        createFileBeneath(paths.root, marker, reason === undefined ? '' : `${reason}\n`);
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return { kind: 'retired', logPath: paths.jobLog };
+        throw err;
+    }
+    try {
+        const signaled = await signalBashJob(pgid, pgidIdentity, nodeId);
+        try {
+            createFileBeneath(paths.root, paths.jobExit, '143\n');
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+        return { kind: 'stopped', signaled, pgid, logPath: paths.jobLog };
+    }
+    catch (error) {
+        unlinkIfPresent(paths.root, marker);
+        throw error;
+    }
+}
+/** Last `count` lines of a job log, cheaply: read at most the trailing 64 KiB
+ * rather than the whole file, which for a long-running job can be enormous. */
+export function tailJobLog(logPath, count) {
+    if (count <= 0)
+        return [];
+    const WINDOW = 64 * 1024;
+    let fd;
+    try {
+        const size = statSync(logPath).size;
+        const start = Math.max(0, size - WINDOW);
+        const buf = Buffer.alloc(Math.min(size, WINDOW));
+        fd = openSync(logPath, 'r');
+        readSync(fd, buf, 0, buf.length, start);
+        const text = buf.toString('utf8');
+        // A partial first line (we cut mid-line) is dropped, not shown truncated.
+        const lines = (start > 0 ? text.slice(text.indexOf('\n') + 1) : text).split('\n');
+        if (lines[lines.length - 1] === '')
+            lines.pop();
+        return lines.slice(-count);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** Lines written to a job log so far, counting a trailing unterminated line as
+ * one. Reads the whole file in fixed-size chunks, so even a log at the 10 MiB
+ * cap costs one buffer rather than its full size in memory. */
+export function countJobLogLines(logPath) {
+    let fd;
+    try {
+        fd = openSync(logPath, 'r');
+        const buf = Buffer.alloc(64 * 1024);
+        let lines = 0;
+        let lastByte = 0;
+        for (;;) {
+            const read = readSync(fd, buf, 0, buf.length, null);
+            if (read === 0)
+                break;
+            for (let i = 0; i < read; i += 1)
+                if (buf[i] === 0x0a)
+                    lines += 1;
+            lastByte = buf[read - 1];
+        }
+        return lastByte !== 0 && lastByte !== 0x0a ? lines + 1 : lines;
+    }
+    catch {
+        return 0;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** Mint a fresh job id — `${Date.now()}-${hex}`. The sole minting site; the
+ * valve calls this instead of building the literal inline so the epoch-ms
+ * prefix is a real contract shared with its parser (jobStartedAtMs), not an
+ * incidental string format. */
+export function newBashJobId() {
+    return `${Date.now()}-${randomBytes(4).toString('hex')}`;
+}
+/** Parse the start epoch (ms) out of a job id's prefix. undefined unless the
+ * id is exactly `<finite-number>-<nonempty-suffix>` — defensive against a
+ * hand-created directory that doesn't follow the newBashJobId contract,
+ * including one with no separator at all (`indexOf('-') === -1` must not
+ * silently parse as a truncated prefix). */
+export function jobStartedAtMs(jobId) {
+    const sep = jobId.indexOf('-');
+    if (sep <= 0 || sep === jobId.length - 1)
+        return undefined;
+    const n = Number(jobId.slice(0, sep));
+    return Number.isFinite(n) ? n : undefined;
+}
+/** Render an elapsed duration the way every bash-handoff surface (the valve's
+ * notice, the `node bash background` result/toast, and the attach cockpit)
+ * shows it: `<60s -> "12s"`; `60s-59m -> "3m 40s"`; `>=60m -> "1h 04m"`. */
+export function formatBashElapsed(ms) {
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const totalMinutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (totalMinutes < 60)
+        return `${totalMinutes}m ${String(seconds).padStart(2, '0')}s`;
+    const hours = Math.floor(totalMinutes / 60);
+    const minutes = totalMinutes % 60;
+    return `${hours}h ${String(minutes).padStart(2, '0')}m`;
+}
+/** The command line worth SHOWING for a job: the first non-empty line of
+ * `cmd.sh`, whitespace-collapsed to one line. */
+export function bashJobCommandLine(command) {
+    const first = command.split('\n').map((line) => line.trim()).find((line) => line !== '');
+    return (first ?? '').replace(/\s+/g, ' ');
+}
+/** Atomically hand one foreground job to its detached supervisor. The rename
+ * is the ownership decision: exactly one caller can move job.run to job.bg,
+ * while the supervisor races to move the same source to job.done. */
+export function backgroundBashJob(paths) {
+    try {
+        renameBeneath(paths.root, paths.jobRun, paths.jobBg);
+        return 'backgrounded';
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        if (has(paths, paths.jobBg))
+            return 'already-backgrounded';
+        if (has(paths, paths.jobDone))
+            return 'finished';
+        return 'missing';
+    }
+}
+/** Every still-foreground bash command for this node. job.run is the sole live
+ * foreground state; a handoff or foreground completion atomically removes it.
+ * Invalid or concurrently-removed directories are ignored. */
+function runningBashJobs(contextDir) {
+    let entries;
+    try {
+        entries = jobIds(contextDir);
+    }
+    catch {
+        return [];
+    }
+    return entries.flatMap((jobId) => {
+        const paths = bashJobPaths(contextDir, jobId);
+        try {
+            return has(paths, paths.cmdSh) && has(paths, paths.jobLog) && has(paths, paths.jobRun) ? [paths] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** The start time (ms epoch) of the oldest still-foreground bash command for
+ * this node, or undefined when none is running. This is the authoritative
+ * source for the attach viewer's background hint: a fresh or reconnected
+ * attach reads the same job.run state that backgrounding and completion race
+ * to claim, without viewer-local call tracking that can go stale. */
+export function oldestRunningBashJobStartedAtMs(contextDir) {
+    let oldest;
+    for (const paths of runningBashJobs(contextDir)) {
+        const startedAtMs = jobStartedAtMs(paths.jobId);
+        if (startedAtMs === undefined)
+            continue;
+        if (oldest === undefined || startedAtMs < oldest)
+            oldest = startedAtMs;
+    }
+    return oldest;
+}
+/** Request immediate handoff for every bash command still waiting on pi. Only
+ * the caller that wins the job.run → job.bg rename reports the job as handed
+ * off; another backgrounder or the foreground-completion path may win the race. */
+export function backgroundRunningBashJobs(contextDir) {
+    const backgrounded = [];
+    for (const paths of runningBashJobs(contextDir)) {
+        if (backgroundBashJob(paths) === 'backgrounded')
+            backgrounded.push(paths);
+    }
+    return backgrounded;
+}

package/dist/core/blobs/directory.d.ts

@@ -0,0 +1,11 @@
+import { type BlobStore } from './index.js';
+/** Move the objects of the directory store's former place (`<layout root>/blobs`) to `root`, one object at a time. Safe when
+ *  several processes run it at once and when an older build is still writing to `former`: an object is published at its new key
+ *  with a hard link (which refuses to replace an existing object) and its old name is removed only after that, so an interrupted
+ *  or raced move leaves every object readable in one place or the other. Entries it did not move (an object whose key already
+ *  exists at `root`, or one written after the listing) stay in `former` and are picked up by the next call. A `former` that is
+ *  a symbolic link is followed, so the objects behind it move too. When the objects are on another filesystem (`link` fails with
+ *  EXDEV) each is copied to a temporary file, fsynced and linked in. Does nothing once `former` is gone. */
+export declare function adoptBlobDirectory(former: string, root: string, link?: (from: string, to: string) => void): void;
+/** Objects as files under `root`: written to a temp file, fsynced, renamed into place, and the directory fsynced. */
+export declare function createDirectoryBlobStore(root: string): BlobStore;

package/dist/core/blobs/directory.js

@@ -0,0 +1,216 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, writeSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { assertBlobKey } from './index.js';
+import { blobFault } from './fault.js';
+function syncDir(path) {
+    const fd = openSync(path, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Move the objects of the directory store's former place (`<layout root>/blobs`) to `root`, one object at a time. Safe when
+ *  several processes run it at once and when an older build is still writing to `former`: an object is published at its new key
+ *  with a hard link (which refuses to replace an existing object) and its old name is removed only after that, so an interrupted
+ *  or raced move leaves every object readable in one place or the other. Entries it did not move (an object whose key already
+ *  exists at `root`, or one written after the listing) stay in `former` and are picked up by the next call. A `former` that is
+ *  a symbolic link is followed, so the objects behind it move too. When the objects are on another filesystem (`link` fails with
+ *  EXDEV) each is copied to a temporary file, fsynced and linked in. Does nothing once `former` is gone. */
+export function adoptBlobDirectory(former, root, link = linkSync) {
+    let source;
+    try {
+        source = realpathSync(former);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (source === resolve(root))
+        return;
+    const touched = new Set();
+    const adopt = (dir, prefix) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const entry of entries) {
+            if (entry.name.endsWith('.tmp'))
+                continue;
+            const from = join(dir, entry.name);
+            const rel = join(prefix, entry.name);
+            if (entry.isDirectory()) {
+                adopt(from, rel);
+                try {
+                    rmdirSync(from);
+                }
+                catch (error) {
+                    if (!['ENOTEMPTY', 'ENOENT'].includes(error.code ?? ''))
+                        throw error;
+                }
+                continue;
+            }
+            const to = join(root, rel);
+            mkdirSync(dirname(to), { recursive: true, mode: 0o700 });
+            touched.add(dirname(to));
+            try {
+                link(from, to);
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'EEXIST') {
+                    if (sameFile(from, to))
+                        rmSync(from, { force: true });
+                    continue;
+                } // an object already at the new place wins; a different older twin stays where it is
+                if (code === 'ENOENT')
+                    continue; // another process moved it
+                if (!copyInto(from, to))
+                    continue;
+            }
+            rmSync(from, { force: true });
+        }
+    };
+    adopt(source, '');
+    for (const dir of touched)
+        syncDir(dir);
+    try {
+        rmdirSync(source);
+    }
+    catch (error) {
+        if (!['ENOTEMPTY', 'ENOENT'].includes(error.code ?? ''))
+            throw error;
+    }
+    if (lstatSync(former, { throwIfNoEntry: false })?.isSymbolicLink() && !existsSync(former))
+        rmSync(former, { force: true });
+}
+function sameFile(a, b) {
+    try {
+        const x = statSync(a);
+        const y = statSync(b);
+        return x.ino === y.ino && x.dev === y.dev;
+    }
+    catch {
+        return false;
+    }
+}
+/** Publish a copy of `from` at `to` unless an object is already there: temp file, fsync, hard link, remove the temp.
+ *  False when `from` vanished or `to` exists, so the caller leaves `from` alone. */
+function copyInto(from, to) {
+    const temp = `${to}.${randomUUID()}.tmp`;
+    try {
+        const fd = openSync(temp, 'wx', 0o600);
+        try {
+            let bytes;
+            try {
+                bytes = readFileSync(from);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return false;
+                throw error;
+            }
+            let written = 0;
+            while (written < bytes.length)
+                written += writeSync(fd, bytes, written);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        try {
+            linkSync(temp, to);
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+        return true;
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+/** Objects as files under `root`: written to a temp file, fsynced, renamed into place, and the directory fsynced. */
+export function createDirectoryBlobStore(root) {
+    const pathOf = (key) => { assertBlobKey(key); return join(root, ...key.split('/')); };
+    function walk(dir, prefix, out) {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const entry of entries) {
+            if (entry.name.endsWith('.tmp'))
+                continue;
+            const key = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+            if (entry.isDirectory())
+                walk(join(dir, entry.name), key, out);
+            else
+                out.push(key);
+        }
+    }
+    return {
+        async put(key, data) {
+            blobFault('put');
+            const path = pathOf(key);
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            const temp = `${path}.${randomUUID()}.tmp`;
+            const fd = openSync(temp, 'wx', 0o600);
+            try {
+                const bytes = typeof data === 'string' ? Buffer.from(data, 'utf8') : Buffer.from(data);
+                let written = 0;
+                while (written < bytes.length)
+                    written += writeSync(fd, bytes, written);
+                fsyncSync(fd);
+            }
+            catch (error) {
+                closeSync(fd);
+                rmSync(temp, { force: true });
+                throw error;
+            }
+            closeSync(fd);
+            renameSync(temp, path);
+            syncDir(dirname(path));
+        },
+        async get(key, range) {
+            try {
+                if (!range)
+                    return readFileSync(pathOf(key));
+                const fd = openSync(pathOf(key), 'r');
+                try {
+                    const buffer = Buffer.allocUnsafe(range.length);
+                    const got = readSync(fd, buffer, 0, range.length, range.start);
+                    return buffer.subarray(0, got);
+                }
+                finally {
+                    closeSync(fd);
+                }
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return null;
+                throw error;
+            }
+        },
+        async list(prefix) {
+            const out = [];
+            walk(root, '', out);
+            return out.filter((key) => key.startsWith(prefix)).sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+        },
+        async delete(key) { rmSync(pathOf(key), { force: true }); },
+    };
+}

package/dist/core/blobs/fault.d.ts

@@ -0,0 +1,3 @@
+/** Fault switch for the blob store (design-fleet, faulting-store seam): `CRTR_FAULT_BLOB=put_fail` makes every `put`
+ *  throw. Read on each call so a seam test can flip it in the serving process's environment. */
+export declare function blobFault(op: 'put'): void;