@sagmans/dsh-tui 0.3.0 → 0.5.0

package/lib/stash/lock.js

@@ -0,0 +1,374 @@
+// Private cross-process lock for one stash file.
+//
+// Two `dsh --profile tui` runs can share a working directory, so every read that
+// feeds a write and every write itself happens under an exclusive directory
+// lock: none of them can lose another's entry to a read-modify-write race.
+// Ownership is recorded in the lock so a lock left by a crashed process is
+// reclaimed rather than wedging the bank forever.
+//
+// Releasing *moves* the lock out of its path with one atomic rename before it
+// judges or deletes it, and reclaiming judges a lock and removes it under a
+// separate claim that only one contender can take. Removing the path on the
+// strength of an earlier look would let a contender delete the live lock that
+// replaced the one it judged, and two writers would then run at once.
+import { createHash } from 'node:crypto';
+import { link, mkdir, rename, rm } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { assertPrivateDirectory, ensurePrivateDirectory, hasErrorCode, PRIVATE_DIR_MODE, readPrivateTextFile, removePrivateDirectory, writePrivateFileExclusive, } from "./private-fs.js";
+import { createNewId } from "./schema.js";
+const LOCK_RETRY_MS = 25;
+const LOCK_TIMEOUT_MS = 2000;
+const LOCK_STALE_MS = 30_000;
+const LOCK_OWNER_FILE = 'owner.json';
+const LOCK_TAKEOVER_SUFFIX = '.taken';
+/**
+ * The name reclaimers link their claim file onto, so exactly one of them wins.
+ *
+ * A storage directory holds a bank per working directory, so the claim is named
+ * after the bank it guards: one crashed reclaimer then stops recovery for that
+ * bank alone instead of for every directory that shares the storage. The name is
+ * a digest rather than the key itself, because a key at the sanitizer's limit
+ * plus a suffix and a token is longer than the longest name a filesystem accepts.
+ */
+const RECLAIM_PREFIX = '.claim-';
+const RECLAIM_DIGEST_LENGTH = 16;
+const LOCK_CHANGED_MESSAGE = 'stash lock changed before release';
+/**
+ * A mutation that landed on disk while a later step failed.
+ *
+ * The write is not undone — reporting it as a failure would tell the reader
+ * their draft was lost when it is readable — so the failure travels beside the
+ * result and the caller reports success plus the warning.
+ */
+export class StashCommittedError extends Error {
+    committed = true;
+    result;
+    failure;
+    /** Set when the lock could not be released either, so both are reported. */
+    releaseFailure;
+    constructor(result, failure, releaseFailure) {
+        super(releaseFailure === undefined
+            ? `stash mutation committed but ${failure.phase} failed`
+            : `stash mutation committed but ${failure.phase} and ${releaseFailure.phase} failed`, { cause: failure.error });
+        this.name = 'StashCommittedError';
+        this.result = result;
+        this.failure = failure;
+        this.releaseFailure = releaseFailure;
+    }
+}
+/** Take the file lock for a read that must not observe a half-written file. */
+export function withStashFileLock(filePath, operation) {
+    return withStashLock(filePath, operation, false);
+}
+/**
+ * Take the lock for a mutation, and classify an unlock failure as committed.
+ *
+ * Only a callback that reports `didPersist` turns a failed unlock into a
+ * committed error: an unlock failure after a refused mutation is an ordinary
+ * failure.
+ */
+export async function withStashMutationLock(filePath, operation) {
+    const outcome = await withStashLock(filePath, operation, true);
+    return outcome.result;
+}
+async function withStashLock(filePath, operation, mutation) {
+    await ensurePrivateDirectory(path.dirname(filePath));
+    const lockDir = `${filePath}.lock`;
+    const owner = await acquireStashLock(lockDir);
+    let result;
+    try {
+        result = await operation();
+    }
+    catch (operationError) {
+        try {
+            await releaseStashLock(lockDir, owner);
+        }
+        catch (releaseError) {
+            if (operationError instanceof StashCommittedError) {
+                // The mutation is on disk, and the caller has to keep hearing that: an
+                // AggregateError would read as a plain failure, and a retry of an
+                // index-based drop would then delete the draft that followed the one
+                // already removed. Both failed steps travel on the committed error.
+                throw new StashCommittedError(operationError.result, operationError.failure, {
+                    phase: 'lock-release',
+                    error: releaseError,
+                });
+            }
+            throw new AggregateError([operationError, releaseError], 'stash operation and lock release both failed');
+        }
+        throw operationError;
+    }
+    try {
+        await releaseStashLock(lockDir, owner);
+    }
+    catch (releaseError) {
+        if (mutation && isPersistedMutation(result)) {
+            throw new StashCommittedError(result.result, { phase: 'lock-release', error: releaseError });
+        }
+        // A read already has its answer, and the answer cannot be wrong because the
+        // lock outlived it: the next contender reclaims a lock whose owner is gone.
+        // Failing here would throw away what the caller just learned — including the
+        // path of a bank that was quarantined while it was being read.
+        if (mutation)
+            throw releaseError;
+    }
+    return result;
+}
+function isPersistedMutation(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'didPersist' in value &&
+        value.didPersist === true &&
+        'result' in value);
+}
+async function acquireStashLock(lockDir) {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            await mkdir(lockDir, { mode: PRIVATE_DIR_MODE });
+            try {
+                await assertPrivateDirectory(lockDir, 'stash lock');
+                return await writeLockOwner(lockDir);
+            }
+            catch (error) {
+                // Losing the name while publishing it is a retry, not a failure: a
+                // contender that judged a lock abandoned can take the name away, and the
+                // owner write then either finds the name gone or finds a successor's
+                // owner file. Deleting the directory in either case would be deleting a
+                // lock this process never held, and the successor would lose its turn.
+                if (hasErrorCode(error, 'ENOENT') || hasErrorCode(error, 'EEXIST')) {
+                    if (Date.now() >= deadline)
+                        throw lockTimeout(lockDir);
+                    continue;
+                }
+                throw error;
+            }
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'EEXIST'))
+                throw error;
+            try {
+                await assertPrivateDirectory(lockDir, 'stash lock');
+            }
+            catch (validationError) {
+                if (hasErrorCode(validationError, 'ENOENT'))
+                    continue;
+                throw validationError;
+            }
+            if (await reclaimAbandonedLock(lockDir))
+                continue;
+            if (Date.now() >= deadline)
+                throw lockTimeout(lockDir);
+            await delay(LOCK_RETRY_MS);
+        }
+    }
+}
+function lockTimeout(lockDir) {
+    const mutex = reclaimMutexPath(lockDir);
+    return new Error(`timed out waiting for the stash lock at ${lockDir}; remove it and ${mutex} once no surface is running`);
+}
+/**
+ * The claim a reclaimer takes, named after the bank whose lock it guards.
+ *
+ * Exported because it is the path a timeout tells the reader to clear by hand.
+ */
+export function reclaimMutexPath(lockDir) {
+    const digest = createHash('sha256').update(path.basename(lockDir), 'utf8').digest('hex');
+    return path.join(path.dirname(lockDir), `${RECLAIM_PREFIX}${digest.slice(0, RECLAIM_DIGEST_LENGTH)}`);
+}
+async function writeLockOwner(lockDir) {
+    const owner = {
+        pid: process.pid,
+        host: hostname(),
+        token: createNewId(),
+        createdAt: new Date().toISOString(),
+    };
+    await writePrivateFileExclusive(path.join(lockDir, LOCK_OWNER_FILE), `${JSON.stringify(owner)}\n`);
+    return owner;
+}
+async function readLockOwner(lockDir) {
+    let text;
+    try {
+        await assertPrivateDirectory(lockDir, 'stash lock');
+        text = (await readPrivateTextFile(path.join(lockDir, LOCK_OWNER_FILE), 'lock owner file')).text;
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+    try {
+        const value = JSON.parse(text);
+        return isLockOwner(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isLockOwner(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'pid' in value &&
+        Number.isSafeInteger(value.pid) &&
+        'host' in value &&
+        typeof value.host === 'string' &&
+        'token' in value &&
+        typeof value.token === 'string' &&
+        value.token.length > 0 &&
+        'createdAt' in value &&
+        typeof value.createdAt === 'string');
+}
+async function releaseStashLock(lockDir, expected) {
+    const taken = await takeLockDirectory(lockDir);
+    if (taken === undefined)
+        throw new Error(LOCK_CHANGED_MESSAGE);
+    const owner = await readLockOwner(taken);
+    if (owner?.token !== expected.token) {
+        await putBackLockDirectory(taken, lockDir);
+        throw new Error(LOCK_CHANGED_MESSAGE);
+    }
+    await removePrivateDirectory(taken, 'stash lock');
+}
+/**
+ * Move the lock out of its path, so only this caller can act on what it finds.
+ *
+ * One rename is atomic: two contenders cannot both take the same lock, and a
+ * lock published afterwards lands at the original path rather than under this
+ * name. Nothing is ever deleted through the path a fresh lock would occupy.
+ */
+async function takeLockDirectory(lockDir) {
+    const taken = `${lockDir}${LOCK_TAKEOVER_SUFFIX}.${createNewId()}`;
+    try {
+        await rename(lockDir, taken);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT') || hasErrorCode(error, 'ENOTEMPTY') || hasErrorCode(error, 'EEXIST')) {
+            return undefined;
+        }
+        throw error;
+    }
+    return taken;
+}
+/**
+ * Put a lock back that turned out to belong to someone else.
+ *
+ * A fresh lock at the original path means this one can never be restored. It is
+ * left where it is rather than deleted: whoever holds it is running, so a lock
+ * that is merely hard to find costs a warning on release, while a deleted one
+ * costs a second writer in the bank.
+ */
+async function putBackLockDirectory(taken, lockDir) {
+    try {
+        await rename(taken, lockDir);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return;
+        throw error;
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // Only ESRCH proves the process is gone; every other failure (permissions,
+        // an unknown error) is uncertainty and must keep the lock held.
+        return !hasErrorCode(error, 'ESRCH');
+    }
+}
+/** Read a lock and the identity of the directory it was read from, in one pass. */
+export async function observeLock(lockDir) {
+    let stats;
+    try {
+        stats = await assertPrivateDirectory(lockDir, 'stash lock');
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+    const owner = await readLockOwner(lockDir);
+    return { owner, device: stats.dev, inode: stats.ino, modified: stats.mtimeMs };
+}
+/**
+ * Reclaim a lock whose owner is gone.
+ *
+ * Reclaimers serialize on a claim file created by link, which exactly one of
+ * them can win, so only one of them ever judges and removes a given lock. The
+ * winner looks once, decides from that look, and then removes only if the lock
+ * still is the directory it looked at: a holder that released in between would
+ * otherwise leave its successor's live lock to be deleted, and both writers
+ * would then run at once.
+ *
+ * A reclaimer killed inside that section leaves the claim file behind, and every
+ * later reclaim fails closed at the timeout instead of guessing. That message
+ * names the file, because clearing it by hand is the one recovery that cannot
+ * cost an update.
+ */
+async function reclaimAbandonedLock(lockDir) {
+    const mutex = reclaimMutexPath(lockDir);
+    const claim = await claimReclaim(mutex);
+    if (claim === undefined)
+        return false;
+    try {
+        const observed = await observeLock(lockDir);
+        if (observed === undefined || !isAbandonedLock(observed))
+            return false;
+        return await removeObservedLock(lockDir, observed);
+    }
+    finally {
+        await rm(claim, { force: true }).catch(() => undefined);
+        await rm(mutex, { force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Remove the lock a judgement was made about, and nothing that replaced it.
+ *
+ * Exported so the race this exists for can be driven from a test: hold an
+ * observation, publish a live lock in its place, and the removal has to refuse.
+ */
+export async function removeObservedLock(lockDir, observed) {
+    const current = await observeLock(lockDir);
+    if (current === undefined)
+        return false;
+    if (current.device !== observed.device || current.inode !== observed.inode)
+        return false;
+    if (current.owner?.token !== observed.owner?.token)
+        return false;
+    await removePrivateDirectory(lockDir, 'stash lock');
+    return true;
+}
+/** Whether one observation of a lock shows an owner that can no longer hold it. */
+function isAbandonedLock(observed) {
+    if (observed.owner === undefined)
+        return Date.now() - observed.modified > LOCK_STALE_MS;
+    if (observed.owner.host !== hostname())
+        return false;
+    return !processIsAlive(observed.owner.pid);
+}
+/**
+ * Win the right to reclaim, by linking a private claim file onto one name.
+ *
+ * `link` is the atomic test-and-set this needs: it fails when the name exists,
+ * and it never replaces what is already there, so a contender that loses reads
+ * the winner's claim rather than breaking it.
+ */
+async function claimReclaim(mutex) {
+    const claim = `${mutex}.${createNewId()}`;
+    await writePrivateFileExclusive(claim, `${JSON.stringify({ pid: process.pid, host: hostname() })}\n`);
+    try {
+        await link(claim, mutex);
+        return claim;
+    }
+    catch (error) {
+        await rm(claim, { force: true }).catch(() => undefined);
+        if (hasErrorCode(error, 'EEXIST'))
+            return undefined;
+        throw error;
+    }
+}
+//# sourceMappingURL=lock.js.map

package/lib/stash/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/stash/lock.ts"],"names":[],"mappings":"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"}

package/lib/stash/paths.d.ts

@@ -0,0 +1,22 @@
+/** The stash file for one session. */
+export interface StashPaths {
+    /** The exact session this bank belongs to. */
+    readonly sessionId: string;
+    /** Flattened session id, used as the on-disk key. */
+    readonly key: string;
+    /** JSON file holding this session's stash entries. */
+    readonly file: string;
+}
+export declare function sanitizeSessionId(sessionId: string): string;
+/**
+ * The directory the harness keeps its own state in.
+ *
+ * DSH_HOME is the one thing that moves that directory, and it is resolved the
+ * same way the settings document resolves it, so a scratch home keeps stash data
+ * out of a reader's real home during a test run.
+ */
+export declare function dshHomeDir(env?: NodeJS.ProcessEnv, home?: string): string;
+/** The root every session's stash file sits under. */
+export declare function stashBaseDir(env?: NodeJS.ProcessEnv, home?: string): string;
+export declare function resolveStashPaths(sessionId: string, baseDir?: string): StashPaths;
+//# sourceMappingURL=paths.d.ts.map

package/lib/stash/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/stash/paths.ts"],"names":[],"mappings":"AA0CA,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAuBD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAM3D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAGjG;AAED,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAEnG;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,MAAuB,GAAG,UAAU,CAGjG"}

package/lib/stash/paths.js

@@ -0,0 +1,84 @@
+// Disk layout for prompt stashes.
+//
+// A bank is scoped to one session: two terminals working in the same directory
+// keep separate drafts, and a resumed session finds the drafts it parked before
+// the restart, because the session id is what a resume preserves. The id is
+// flattened into a filename-safe key that stays human-readable in the agent
+// directory.
+//
+// Readability cannot be bought with injectivity: a separator made of hyphens
+// cannot be told apart from a hyphen inside a session id, and truncating a long
+// id can land on a name a shorter id already owns. Two sessions sharing one bank
+// would let one read or delete another's drafts, so every key ends with a digest
+// of the exact session id. The readable part is then only a label: two distinct
+// ids collide in the label, never in the file.
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import path from 'node:path';
+/** The directory `DSH_HOME` points at when the environment names none. */
+const DEFAULT_DSH_HOME_DIR = '.dsh';
+/** The subtree of `DSH_HOME` this surface owns. */
+const STASH_DIR_NAME = 'tui-stash';
+// POSIX filenames may not contain "/" or NUL, and everything else is legal, so
+// once separators are flattened the result is filename-safe on the platforms
+// this surface targets. 200 keeps the whole key, digest included, well under the
+// common 255-byte filename limit.
+const SANITIZE_MAX_LENGTH = 200;
+const SEPARATOR = '--';
+const KEY_FORMAT_VERSION = 'v2';
+const KEY_PREFIX = `${KEY_FORMAT_VERSION}${SEPARATOR}`;
+const ESCAPE_CHARACTER = '%';
+const ESCAPED_ESCAPE_CHARACTER = '%25';
+const ESCAPED_SEPARATOR = '%2D%2D';
+const BACKSLASH = '\\';
+const ESCAPED_BACKSLASH = '%5C';
+const HASH_ALGORITHM = 'sha256';
+/** 64 bits of digest, which no deliberate name can be built to collide with. */
+const HASH_LENGTH = 16;
+/** Escape one key segment so it cannot collide with the separator or an escape. */
+function escapeSegment(segment) {
+    return segment
+        .replaceAll(ESCAPE_CHARACTER, ESCAPED_ESCAPE_CHARACTER)
+        .replaceAll(BACKSLASH, ESCAPED_BACKSLASH)
+        .replaceAll(SEPARATOR, ESCAPED_SEPARATOR);
+}
+/** Keep whole characters while fitting a byte budget, so a cut cannot split one. */
+function truncateToUtf8Bytes(value, maxBytes) {
+    let bytes = 0;
+    let result = '';
+    for (const character of value) {
+        const characterBytes = Buffer.byteLength(character);
+        if (bytes + characterBytes > maxBytes)
+            break;
+        result += character;
+        bytes += characterBytes;
+    }
+    return result;
+}
+export function sanitizeSessionId(sessionId) {
+    const readable = sessionId.split('/').filter(Boolean).map(escapeSegment).join(SEPARATOR);
+    const digest = createHash(HASH_ALGORITHM).update(sessionId, 'utf8').digest('hex').slice(0, HASH_LENGTH);
+    const suffix = `${SEPARATOR}${digest}`;
+    const budget = SANITIZE_MAX_LENGTH - Buffer.byteLength(KEY_PREFIX) - Buffer.byteLength(suffix);
+    return `${KEY_PREFIX}${truncateToUtf8Bytes(readable, Math.max(budget, 0))}${suffix}`;
+}
+/**
+ * The directory the harness keeps its own state in.
+ *
+ * DSH_HOME is the one thing that moves that directory, and it is resolved the
+ * same way the settings document resolves it, so a scratch home keeps stash data
+ * out of a reader's real home during a test run.
+ */
+export function dshHomeDir(env = process.env, home = homedir()) {
+    const configured = env.DSH_HOME?.trim();
+    return configured === undefined || configured === '' ? path.join(home, DEFAULT_DSH_HOME_DIR) : configured;
+}
+/** The root every session's stash file sits under. */
+export function stashBaseDir(env = process.env, home = homedir()) {
+    return path.join(dshHomeDir(env, home), STASH_DIR_NAME);
+}
+export function resolveStashPaths(sessionId, baseDir = stashBaseDir()) {
+    const key = sanitizeSessionId(sessionId);
+    return { sessionId, key, file: path.join(baseDir, `${key}.json`) };
+}
+//# sourceMappingURL=paths.js.map

package/lib/stash/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/stash/paths.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,4EAA4E;AAC5E,4EAA4E;AAC5E,aAAa;AACb,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,iFAAiF;AACjF,iFAAiF;AACjF,gFAAgF;AAChF,+CAA+C;AAE/C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,IAAI,MAAM,WAAW,CAAA;AAE5B,0EAA0E;AAC1E,MAAM,oBAAoB,GAAG,MAAM,CAAA;AAEnC,mDAAmD;AACnD,MAAM,cAAc,GAAG,WAAW,CAAA;AAElC,+EAA+E;AAC/E,6EAA6E;AAC7E,iFAAiF;AACjF,kCAAkC;AAClC,MAAM,mBAAmB,GAAG,GAAG,CAAA;AAC/B,MAAM,SAAS,GAAG,IAAI,CAAA;AACtB,MAAM,kBAAkB,GAAG,IAAI,CAAA;AAC/B,MAAM,UAAU,GAAG,GAAG,kBAAkB,GAAG,SAAS,EAAE,CAAA;AACtD,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAC5B,MAAM,wBAAwB,GAAG,KAAK,CAAA;AACtC,MAAM,iBAAiB,GAAG,QAAQ,CAAA;AAClC,MAAM,SAAS,GAAG,IAAI,CAAA;AACtB,MAAM,iBAAiB,GAAG,KAAK,CAAA;AAC/B,MAAM,cAAc,GAAG,QAAQ,CAAA;AAC/B,gFAAgF;AAChF,MAAM,WAAW,GAAG,EAAE,CAAA;AAYtB,mFAAmF;AACnF,SAAS,aAAa,CAAC,OAAe;IACpC,OAAO,OAAO;SACX,UAAU,CAAC,gBAAgB,EAAE,wBAAwB,CAAC;SACtD,UAAU,CAAC,SAAS,EAAE,iBAAiB,CAAC;SACxC,UAAU,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAA;AAC7C,CAAC;AAED,oFAAoF;AACpF,SAAS,mBAAmB,CAAC,KAAa,EAAE,QAAgB;IAC1D,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,IAAI,MAAM,GAAG,EAAE,CAAA;IACf,KAAK,MAAM,SAAS,IAAI,KAAK,EAAE,CAAC;QAC9B,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAA;QACnD,IAAI,KAAK,GAAG,cAAc,GAAG,QAAQ;YAAE,MAAK;QAC5C,MAAM,IAAI,SAAS,CAAA;QACnB,KAAK,IAAI,cAAc,CAAA;IACzB,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IACxF,MAAM,MAAM,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAA;IACvG,MAAM,MAAM,GAAG,GAAG,SAAS,GAAG,MAAM,EAAE,CAAA;IACtC,MAAM,MAAM,GAAG,mBAAmB,GAAG,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;IAC9F,OAAO,GAAG,UAAU,GAAG,mBAAmB,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,CAAA;AACtF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAE,OAAe,OAAO,EAAE;IACvF,MAAM,UAAU,GAAG,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAA;IACvC,OAAO,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC,UAAU,CAAA;AAC3G,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAE,OAAe,OAAO,EAAE;IACzF,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,cAAc,CAAC,CAAA;AACzD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,UAAkB,YAAY,EAAE;IACnF,MAAM,GAAG,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAA;IACxC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,EAAE,CAAA;AACpE,CAAC"}

package/lib/stash/private-fs.d.ts

@@ -0,0 +1,61 @@
+import { type Stats } from 'node:fs';
+export declare const PRIVATE_DIR_MODE = 448;
+export declare const PRIVATE_FILE_MODE = 384;
+type FileIdentity = Pick<Stats, 'dev' | 'ino'>;
+export interface PrivateTextFile {
+    readonly text: string;
+    readonly identity: FileIdentity;
+}
+/** Where a quarantined file went, and whether that location reached the disk. */
+export interface QuarantineResult {
+    readonly path: string;
+    /** Set when the directory naming the copy could not be synced. */
+    readonly syncError: unknown;
+}
+/** A file that exceeded the caller's byte budget, which is a refusal, not corruption. */
+export declare class FileTooLargeError extends Error {
+    constructor(label: string);
+}
+/**
+ * Prepare the storage directory, and make the directories that name it durable.
+ *
+ * A directory that names a new child holds the only record of that child, so
+ * every directory this call creates is flushed through its parent before the
+ * call returns. A step that fails takes the created directories away again:
+ * leaving them behind would turn the next attempt into one that finds nothing
+ * left to flush, and a save could then report success for a tree that a power
+ * loss is free to drop.
+ *
+ * The rollback only ever removes an empty directory. Another surface can reach a
+ * directory this call just created and save into it while this one is flushing,
+ * and a recursive removal would then delete that surface's committed bank: an
+ * entry left unflushed costs durability, while a removed bank costs the draft.
+ */
+export declare function ensurePrivateDirectory(directory: string, label?: string, syncDirectory?: typeof syncDirectoryEntry): Promise<void>;
+/**
+ * Flush one directory entry without asserting who owns the directory.
+ *
+ * An ancestor may legitimately be root-owned (`/tmp`, a mount point) and still
+ * have to be synced for the entry below it to survive a power loss, so the
+ * ownership rule that guards the storage directory itself is not applied here.
+ * A directory that is already gone needs no flushing.
+ */
+export declare function syncDirectoryEntry(directory: string): Promise<void>;
+export declare function assertPrivateDirectory(directory: string, label: string): Promise<Stats>;
+export declare function syncPrivateDirectory(directory: string, label?: string): Promise<void>;
+export declare function readPrivateTextFile(filePath: string, label?: string, maxBytes?: number): Promise<PrivateTextFile>;
+export declare function writePrivateFileExclusive(filePath: string, data: string | Uint8Array): Promise<void>;
+/**
+ * Move a file aside without losing it.
+ *
+ * A hard-link reservation keeps the original bytes reachable under a new name
+ * before the source is unlinked, so an interrupted quarantine leaves either the
+ * readable original or the readable copy, never neither.
+ */
+export declare function quarantinePrivateFile(filePath: string, identity: FileIdentity, label: string, syncDirectory?: typeof syncPrivateDirectory): Promise<QuarantineResult>;
+export declare function removePrivateDirectory(directory: string, label?: string): Promise<void>;
+export declare function assertRegularOwnedFile(stats: Stats, label: string): void;
+export declare function pathExists(target: string): Promise<boolean>;
+export declare function hasErrorCode(value: unknown, code: string): boolean;
+export {};
+//# sourceMappingURL=private-fs.d.ts.map

package/lib/stash/private-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-fs.d.ts","sourceRoot":"","sources":["../../src/stash/private-fs.ts"],"names":[],"mappings":"AAQA,OAAO,EAAa,KAAK,KAAK,EAAE,MAAM,SAAS,CAAA;AAI/C,eAAO,MAAM,gBAAgB,MAAQ,CAAA;AACrC,eAAO,MAAM,iBAAiB,MAAQ,CAAA;AAgBtC,KAAK,YAAY,GAAG,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,CAAA;AAE9C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;CAChC;AAED,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED,yFAAyF;AACzF,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,KAAK,EAAE,MAAM;CAI1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,KAAK,SAAsB,EAC3B,aAAa,GAAE,OAAO,kBAAuC,GAC5D,OAAO,CAAC,IAAI,CAAC,CAyBf;AAuGD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAazE;AAED,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAO7F;AAED,wBAAsB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxG;AAED,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,KAAK,SAAe,EACpB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,CAAC,CAa1B;AAeD,wBAAsB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAa1G;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,MAAM,EACb,aAAa,GAAE,OAAO,oBAA2C,GAChE,OAAO,CAAC,gBAAgB,CAAC,CAgC3B;AAED,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY1G;AAwBD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIxE;AAmBD,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQjE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAOlE"}