@teepin/sdk 0.2.1 → 0.3.0-rc.1

package/dist/esm/node/journal.js

@@ -0,0 +1,824 @@
+// Copyright 2026 TEEPIN Project
+// Licensed under the Apache License, Version 2.0
+// Local state for direct uploads in the node entry (TEEPIN-STORAGE-DESIGN.md sections 17.2, 22.6 and 24.4): where it
+// lives, the journal each run keeps, and the lock that keeps two processes off one run.
+//
+// - The state directory is per OS: $XDG_STATE_HOME/teepin (by default ~/.local/state/teepin), ~/Library/Application
+//   Support/teepin on macOS, %LOCALAPPDATA%\teepin on Windows, or TEEPIN_STATE_DIR. It is created 0700 and its files
+//   0600, since journals hold file paths and wrapped keys. On Windows the profile directory's user-only ACL is
+//   inherited.
+// - Each run has <state>/<kind>/<run-id>/ (kind: uploads or downloads) with run.json, an append-only events.jsonl, a
+//   lock file, and for uploads packs/ and keys/ (a large upload's data key, E3). Run ids are UUIDv7, so they sort by
+//   time. The layout isn't shared with the Python SDK: each resumes only its own runs.
+// - The journal: every write is one line (a batch of rows, so it lands whole or not at all), written and fsynced
+//   before the action that needs it (section 17.1, rule 3). A torn last line (a crash mid-write) is ignored; a bad line
+//   anywhere else is an error. When a run is reopened, its journal is compacted: rewritten as one line in a temporary
+//   file, fsynced, renamed over the old one, and the directory fsynced where the OS allows.
+// - The lock: a file made with O_EXCL holding the host, the PID, the process's start time and a nonce. A lock whose
+//   process is gone (a dead PID on this host, or a PID reused: its start time differs) is taken over atomically: a
+//   taker first claims that one stale lock with an O_EXCL claim file named by its nonce (only one claim wins), checks
+//   the lock is still that stale one, then replaces it whole (a temporary file renamed over it), so there is never a
+//   moment without a lock and a live lock is never moved. Within a process, locks are kept in a registry, so two runs
+//   in one process never share one either, and an interrupted run is released in the same process (S7-2).
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, open, readdir, readFile, rename, rm, stat, unlink } from 'node:fs/promises';
+import { homedir, hostname } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { uuid7 } from '../direct/common.js';
+import { Rows } from '../direct/journal.js';
+export const STATE_ENV = 'TEEPIN_STATE_DIR';
+export const RUN_FILE = 'run.json';
+export const EVENTS_FILE = 'events.jsonl';
+export const LOCK_FILE = 'lock';
+export const PACKS_DIR = 'packs';
+export const KEYS_DIR = 'keys';
+export const HISTORY_FILE = 'history.log';
+/** The journal's own format version, in run.json. */
+export const JOURNAL_FORMAT = 1;
+/** A lock file whose content can't be read yet is being written: held for this long, then stale. */
+export const LOCK_GRACE_MS = 10000;
+const POSIX = process.platform !== 'win32';
+/** The state directory for this OS (section 19.12), or TEEPIN_STATE_DIR. */
+export function defaultStateDir() {
+    const override = process.env[STATE_ENV];
+    if (override)
+        return override;
+    if (process.platform === 'win32')
+        return join(process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'), 'teepin');
+    if (process.platform === 'darwin')
+        return join(homedir(), 'Library', 'Application Support', 'teepin');
+    return join(process.env.XDG_STATE_HOME || join(homedir(), '.local', 'state'), 'teepin');
+}
+function code(err) {
+    return typeof err === 'object' && err !== null && 'code' in err ? String(err.code) : '';
+}
+/** Creates path (and its parents) readable by its owner only. */
+export async function privateDir(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    if (POSIX)
+        await chmod(path, 0o700);
+    return path;
+}
+/** fsyncs a directory, so a rename or a new file in it survives a crash; nothing where the OS can't (Windows). */
+export async function fsyncDir(path) {
+    if (!POSIX)
+        return;
+    let fh;
+    try {
+        fh = await open(path, 'r');
+        await fh.sync();
+    }
+    catch {
+        // a file system that can't: the rename is still atomic
+    }
+    finally {
+        await fh?.close().catch(() => undefined);
+    }
+}
+/** How long a rename over a file another process has open is tried again on Windows (tests shorten it), and how often. */
+export const sharing = { retryMs: 2000 };
+const SHARING_RETRY_STEP_MS = 20;
+/**
+ * Renames from over to, trying again for up to sharing.retryMs on Windows while another process holds to open
+ * (EPERM, EACCES or EBUSY: a reader of a lock, a history file being appended to). Elsewhere a rename replaces an open
+ * file, so it is tried once (profile 1's W-1; Go's journal does the same).
+ */
+export async function renameOver(from, to, retryMs = sharing.retryMs) {
+    const until = Date.now() + retryMs;
+    for (;;) {
+        try {
+            await rename(from, to);
+            return;
+        }
+        catch (err) {
+            const c = code(err);
+            if (process.platform !== 'win32' || !(c === 'EPERM' || c === 'EACCES' || c === 'EBUSY') || Date.now() >= until)
+                throw err;
+            await new Promise((r) => setTimeout(r, SHARING_RETRY_STEP_MS));
+        }
+    }
+}
+/** Writes data to path all at once: a temporary file (0600), fsynced, then renamed over it, and the directory fsynced. */
+export async function writeAtomic(path, data) {
+    const tmp = `${path}.${randomUUID().replace(/-/g, '')}.tmp`;
+    const fh = await open(tmp, 'wx', 0o600);
+    try {
+        try {
+            await fh.writeFile(data);
+            await fh.sync();
+        }
+        finally {
+            await fh.close();
+        }
+        await renameOver(tmp, path);
+    }
+    catch (err) {
+        await unlink(tmp).catch(() => undefined);
+        throw err;
+    }
+    await fsyncDir(dirname(path));
+}
+/** A file's bytes, or undefined when it isn't there. */
+async function readIfThere(path) {
+    try {
+        return new Uint8Array(await readFile(path));
+    }
+    catch (err) {
+        if (code(err) === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+}
+// --- the journal ------------------------------------------------------------------------------------------------
+const TABLES = new Set(['run', 'files', 'packs', 'uploads', 'parts']);
+function asEntries(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    for (const e of v) {
+        if (typeof e !== 'object' || e === null)
+            return undefined;
+        const x = e;
+        if (typeof x.table !== 'string' || !TABLES.has(x.table) || typeof x.id !== 'string')
+            return undefined;
+        if (x.remove !== true && (typeof x.row !== 'object' || x.row === null))
+            return undefined;
+    }
+    return v;
+}
+/** A run's rows, replayed from its events; whether its last line was torn, and how many lines it took. */
+async function replay(dir, rows) {
+    const meta = await readIfThere(join(dir, RUN_FILE));
+    if (!meta)
+        throw new Error(`${dir} is not a run: it has no ${RUN_FILE}`);
+    let format;
+    try {
+        format = JSON.parse(new TextDecoder().decode(meta)).format;
+    }
+    catch {
+        throw new Error(`${join(dir, RUN_FILE)} is damaged`);
+    }
+    if (typeof format !== 'number' || format > JOURNAL_FORMAT) {
+        throw new Error(`this run was written by a newer SDK (journal format ${String(format)}); upgrade to resume it`);
+    }
+    const raw = await readIfThere(join(dir, EVENTS_FILE));
+    if (!raw?.length)
+        return { lines: 0, torn: false };
+    const text = new TextDecoder().decode(raw);
+    const parts = text.split('\n');
+    // A file that doesn't end in a newline ends in a torn line: its write never finished, so its action never happened.
+    let torn = parts[parts.length - 1] !== '';
+    const lines = parts.slice(0, -1);
+    for (let i = 0; i < lines.length; i++) {
+        let entries;
+        try {
+            entries = asEntries(JSON.parse(lines[i]));
+        }
+        catch {
+            entries = undefined;
+        }
+        if (!entries) {
+            if (i === lines.length - 1 && !torn) {
+                torn = true; // the last line, damaged (a crash can leave zeros where it was being written): ignored
+                break;
+            }
+            throw new Error(`${join(dir, EVENTS_FILE)} is damaged at line ${i + 1}`);
+        }
+        for (const e of entries)
+            rows.apply(e);
+    }
+    return { lines: lines.length, torn };
+}
+/**
+ * One run's journal on disk: run.json, and events.jsonl appended a line per write. Writes resolve once they are
+ * fsynced; a batch is one line, so it lands whole or not at all. Only the run's lock holder opens it to write.
+ */
+export class FileJournal {
+    dir;
+    durable = true;
+    data = new Rows();
+    fh;
+    chain = Promise.resolve();
+    closed = false;
+    broken;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    /** Opens a run's journal to write: replayed, then compacted when it has more than one line or a torn one. */
+    static async open(dir) {
+        const j = new FileJournal(dir);
+        const { lines, torn } = await replay(dir, j.data);
+        if (torn || lines > 1)
+            await j.rewrite();
+        j.fh = await open(join(dir, EVENTS_FILE), 'a', 0o600);
+        if (POSIX)
+            await chmod(join(dir, EVENTS_FILE), 0o600);
+        await fsyncDir(dir);
+        return j;
+    }
+    /** A run's rows, read without writing anything (a run another process may hold). */
+    static async read(dir) {
+        const rows = new Rows();
+        await replay(dir, rows);
+        return { get: (t, id) => rows.get(t, id), rows: (t) => rows.rows(t) };
+    }
+    async put(table, id, row) {
+        return this.write([{ table, id, row }]);
+    }
+    write(entries) {
+        this.check();
+        const line = JSON.stringify(entries) + '\n';
+        const run = this.chain.then(async () => {
+            this.check();
+            const fh = this.fh;
+            if (!fh)
+                throw new Error('journal: not open');
+            try {
+                await fh.write(line);
+                await fh.datasync();
+            }
+            catch (err) {
+                // A line that may be half written: nothing more is appended after it, so on reopen it is the torn last line.
+                this.broken = err;
+                throw err;
+            }
+            for (const e of entries)
+                this.data.apply(e);
+        });
+        this.chain = run.catch(() => undefined);
+        return run;
+    }
+    get(table, id) {
+        return this.data.get(table, id);
+    }
+    rows(table) {
+        return this.data.rows(table);
+    }
+    nextId(table) {
+        return this.data.nextId(table);
+    }
+    /** Rewrites the journal as one line, atomically. */
+    async compact() {
+        this.check();
+        const run = this.chain.then(async () => {
+            await this.fh?.close();
+            this.fh = undefined;
+            await this.rewrite();
+            this.fh = await open(join(this.dir, EVENTS_FILE), 'a', 0o600);
+        });
+        this.chain = run.catch(() => undefined);
+        return run;
+    }
+    async rewrite() {
+        const entries = this.data.entries();
+        await writeAtomic(join(this.dir, EVENTS_FILE), entries.length ? JSON.stringify(entries) + '\n' : '');
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.chain;
+        await this.fh?.close().catch(() => undefined);
+        this.fh = undefined;
+    }
+    check() {
+        if (this.closed)
+            throw new Error('journal: written after it was closed');
+        if (this.broken !== undefined)
+            throw new Error('journal: a write failed; reopen the run to go on', { cause: this.broken });
+    }
+}
+/** Locks this process holds (or is taking), by path: one registry for every copy of this module (ESM and CommonJS). */
+function registry() {
+    const g = globalThis;
+    const k = Symbol.for('teepin.runLocks');
+    return (g[k] ??= new Set());
+}
+const HOST = hostname();
+/** Whether a process is alive (one of another user's counts: it can't be signalled, but it is there). */
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return code(err) === 'EPERM';
+    }
+}
+function run(file, args, env) {
+    return new Promise((resolve) => {
+        execFile(file, args, { timeout: 15000, windowsHide: true, env }, (err, stdout) => resolve(err ? undefined : String(stdout).trim() || undefined));
+    });
+}
+/**
+ * When process pid started, as this OS tells it: a token that is the same for the same process every time it's asked,
+ * and differs for a process that reused its PID. undefined when the OS can't tell (then a live PID counts as the
+ * holder). Linux: /proc's start time in ticks since boot, with the boot's id; macOS and the BSDs: ps's start time;
+ * Windows: the process's creation time, from PowerShell.
+ */
+export async function processStart(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return undefined;
+    switch (process.platform) {
+        case 'linux':
+        case 'android': {
+            try {
+                const stat = await readFile(`/proc/${pid}/stat`, 'utf8');
+                const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+                const boot = (await readFile('/proc/sys/kernel/random/boot_id', 'utf8').catch(() => '')).trim();
+                return fields[19] ? `linux:${boot}:${fields[19]}` : undefined; // field 22, starttime
+            }
+            catch {
+                return undefined;
+            }
+        }
+        case 'darwin':
+        case 'freebsd':
+        case 'openbsd':
+        case 'netbsd':
+        case 'sunos':
+        case 'aix': {
+            const out = await run('ps', ['-o', 'lstart=', '-p', String(pid)], { ...process.env, TZ: 'UTC', LC_ALL: 'C' });
+            return out ? `ps:${out}` : undefined;
+        }
+        case 'win32': {
+            const out = await run('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                `[Console]::Out.Write((Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToFileTimeUtc())`,
+            ]);
+            return out && /^\d+$/.test(out) ? `win:${out}` : undefined;
+        }
+    }
+    return undefined;
+}
+let ownStart;
+/** This process's start token (asked once). */
+function selfStart() {
+    return (ownStart ??= processStart(process.pid));
+}
+async function readLock(path) {
+    let text;
+    let mtimeMs;
+    let size;
+    try {
+        [text, { mtimeMs, size }] = await Promise.all([readFile(path, 'utf8'), stat(path)]);
+    }
+    catch (err) {
+        if (code(err) === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+    try {
+        const d = JSON.parse(text);
+        if (typeof d.nonce !== 'string' || typeof d.host !== 'string' || typeof d.pid !== 'number')
+            throw new Error('not a lock');
+        return { id: d.nonce, host: d.host, pid: d.pid, start: typeof d.start === 'string' ? d.start : undefined, garbled: false, mtimeMs };
+    }
+    catch {
+        return { id: `g${Math.round(mtimeMs)}-${size}`, garbled: true, mtimeMs };
+    }
+}
+/** Creates path with text only if nothing is there (O_EXCL), fsynced. */
+async function createExclusive(path, text) {
+    const fh = await open(path, 'wx', 0o600);
+    try {
+        await fh.writeFile(text);
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * An exclusive lock on a run, held while it is open, so two processes (or two runs in one process) never work one run
+ * (section 17.2). A process that ends without releasing it leaves it stale, and the next taker takes it over.
+ */
+export class RunLock {
+    path;
+    /** Our nonce while we hold it. */
+    mine;
+    constructor(path) {
+        this.path = path;
+    }
+    get held() {
+        return this.mine !== undefined;
+    }
+    get key() {
+        return resolve(this.path);
+    }
+    /** Takes the lock if no live process (this one included) holds it. */
+    async acquire() {
+        if (this.mine)
+            return true;
+        const reg = registry();
+        const key = this.key;
+        if (reg.has(key))
+            return false; // this process holds it, or is taking it
+        reg.add(key);
+        try {
+            const nonce = randomUUID();
+            const text = JSON.stringify({ host: HOST, pid: process.pid, start: await selfStart(), nonce });
+            for (let attempt = 0; attempt < 5; attempt++) {
+                try {
+                    await createExclusive(this.path, text);
+                    this.mine = nonce;
+                    return true;
+                }
+                catch (err) {
+                    if (code(err) !== 'EEXIST')
+                        throw err;
+                }
+                const cur = await readLock(this.path);
+                if (!cur)
+                    continue; // released meanwhile: try again
+                if (!(await this.stale(cur, true)))
+                    return false;
+                if (await this.takeOver(cur, text)) {
+                    this.mine = nonce;
+                    return true;
+                }
+            }
+            return false;
+        }
+        finally {
+            if (!this.mine)
+                reg.delete(key);
+        }
+    }
+    /**
+     * Whether a lock is stale: its process is gone (a dead PID on this host, or a reused one, whose start time differs),
+     * or it is this process's and no run here holds it (taking, when this lock object is the one taking it). A lock from
+     * another host is never stale: its PID means nothing here.
+     */
+    async stale(cur, taking) {
+        if (cur.garbled)
+            return Date.now() - cur.mtimeMs > LOCK_GRACE_MS;
+        if (cur.host !== HOST || cur.pid === undefined)
+            return false;
+        if (cur.pid === process.pid)
+            return taking || !registry().has(this.key);
+        if (!alive(cur.pid))
+            return true;
+        if (cur.start) {
+            const now = await processStart(cur.pid);
+            if (now !== undefined && now !== cur.start)
+                return true; // the PID was reused
+        }
+        return false;
+    }
+    /**
+     * Takes over a stale lock: only one taker's claim (an O_EXCL file named by the stale lock's identity) wins, and the
+     * winner replaces the lock whole only if it is still that stale one.
+     */
+    async takeOver(cur, text) {
+        const claim = `${this.path}.take-${cur.id.replace(/[^A-Za-z0-9-]/g, '')}`;
+        try {
+            await createExclusive(claim, text);
+        }
+        catch (err) {
+            if (code(err) !== 'EEXIST')
+                throw err;
+            // Another taker's claim. One whose taker died is cleared, so a later try can go on.
+            const c = await readLock(claim);
+            if (c && (await this.staleClaim(c)))
+                await unlink(claim).catch(() => undefined);
+            return false;
+        }
+        try {
+            const again = await readLock(this.path);
+            if (!again || again.id !== cur.id)
+                return false; // replaced meanwhile
+            try {
+                await writeAtomic(this.path, text); // never a moment without a lock
+            }
+            catch (err) {
+                // Still held open by another reader after the retries (Windows): not taken this time; acquire goes round.
+                const c = code(err);
+                if (c === 'EPERM' || c === 'EACCES' || c === 'EBUSY')
+                    return false;
+                throw err;
+            }
+            return true;
+        }
+        finally {
+            await unlink(claim).catch(() => undefined);
+        }
+    }
+    async staleClaim(c) {
+        if (c.garbled)
+            return Date.now() - c.mtimeMs > LOCK_GRACE_MS;
+        if (c.host !== HOST || c.pid === undefined)
+            return false;
+        if (c.pid === process.pid)
+            return false; // a taker in this process, at work now
+        if (!alive(c.pid))
+            return true;
+        if (c.start) {
+            const now = await processStart(c.pid);
+            if (now !== undefined && now !== c.start)
+                return true;
+        }
+        return false;
+    }
+    /** Lets the lock go (deleting its file, if it is still ours). Safe to call twice. */
+    async release() {
+        const nonce = this.mine;
+        if (!nonce)
+            return;
+        this.mine = undefined;
+        try {
+            const cur = await readLock(this.path).catch(() => undefined);
+            if (cur && cur.id === nonce)
+                await unlink(this.path).catch(() => undefined);
+        }
+        finally {
+            registry().delete(this.key);
+        }
+    }
+    /** Whether a live process (this one included, through another lock object) holds the lock. */
+    async heldElsewhere() {
+        if (this.mine)
+            return false;
+        const cur = await readLock(this.path);
+        if (!cur)
+            return false;
+        if (registry().has(this.key))
+            return true;
+        return !(await this.stale(cur, false));
+    }
+}
+// --- runs ----------------------------------------------------------------------------------------------------------
+/** Every run of a kind in the state directory, oldest first. */
+export async function runIds(stateDir, kind = 'uploads') {
+    const root = join(stateDir, kind);
+    let names;
+    try {
+        names = await readdir(root);
+    }
+    catch (err) {
+        if (code(err) === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const n of names) {
+        if (await stat(join(root, n, RUN_FILE)).then((s) => s.isFile(), () => false))
+            out.push(n);
+    }
+    return out.sort();
+}
+/** A run's directory in the state directory, with its lock and journal: a RunPlace for the upload engine. */
+export class RunDir {
+    id;
+    kind;
+    path;
+    lock;
+    j;
+    released = false;
+    constructor(stateDir, id, kind) {
+        this.id = id;
+        this.kind = kind;
+        this.path = join(stateDir, kind, id);
+        this.lock = new RunLock(join(this.path, LOCK_FILE));
+    }
+    get journal() {
+        if (!this.j)
+            throw new Error(`run ${this.id}: its journal isn't open`);
+        return this.j;
+    }
+    /** A new run, locked by this process, its journal open. */
+    static async create(stateDir, kind = 'uploads') {
+        await privateDir(join(stateDir, kind));
+        const rd = new RunDir(stateDir, uuid7(), kind);
+        await privateDir(rd.path);
+        if (!(await rd.lock.acquire()))
+            throw new Error(`run ${rd.id} is locked`);
+        try {
+            if (kind === 'uploads') {
+                await privateDir(join(rd.path, PACKS_DIR));
+                await privateDir(join(rd.path, KEYS_DIR));
+            }
+            await writeAtomic(join(rd.path, RUN_FILE), JSON.stringify({ format: JOURNAL_FORMAT, id: rd.id, kind, created: Date.now() }) + '\n');
+            rd.j = await FileJournal.open(rd.path);
+            await fsyncDir(join(stateDir, kind));
+        }
+        catch (err) {
+            await rd.lock.release();
+            await rm(rd.path, { recursive: true, force: true }).catch(() => undefined);
+            throw err;
+        }
+        return rd;
+    }
+    /** A run, locked for this caller with its journal open; undefined when a live process (or another run here) holds it. */
+    static async take(stateDir, id, kind = 'uploads') {
+        const rd = new RunDir(stateDir, id, kind);
+        if (!(await rd.lock.acquire()))
+            return undefined;
+        try {
+            rd.j = await FileJournal.open(rd.path);
+        }
+        catch (err) {
+            await rd.lock.release();
+            throw err;
+        }
+        return rd;
+    }
+    /** A run's journal read without taking it, and whether a live process holds it. */
+    static async peek(stateDir, id, kind = 'uploads') {
+        const rd = new RunDir(stateDir, id, kind);
+        const inUse = await rd.lock.heldElsewhere();
+        return { journal: await FileJournal.read(rd.path), inUse };
+    }
+    packPath(name) {
+        return join(this.path, PACKS_DIR, name);
+    }
+    keyPath(id) {
+        return join(this.path, KEYS_DIR, `${id}.key`);
+    }
+    async writePack(name, data) {
+        await privateDir(join(this.path, PACKS_DIR));
+        await writeAtomic(this.packPath(name), data);
+    }
+    readPack(name) {
+        return readIfThere(this.packPath(name)).catch(() => undefined);
+    }
+    async removePack(name) {
+        await rm(this.packPath(name), { force: true });
+    }
+    async packNames() {
+        return readdir(join(this.path, PACKS_DIR)).catch(() => []);
+    }
+    async writeKey(id, key) {
+        await privateDir(join(this.path, KEYS_DIR));
+        await writeAtomic(this.keyPath(id), key);
+    }
+    readKey(id) {
+        return readIfThere(this.keyPath(id));
+    }
+    /** Overwrites the key's file with zeros (fsynced), then deletes it. */
+    async removeKey(id) {
+        const path = this.keyPath(id);
+        try {
+            const fh = await open(path, 'r+');
+            try {
+                const { size } = await fh.stat();
+                await fh.write(new Uint8Array(size), 0, size, 0);
+                await fh.sync();
+            }
+            finally {
+                await fh.close();
+            }
+        }
+        catch (err) {
+            if (code(err) === 'ENOENT')
+                return;
+            throw err;
+        }
+        await rm(path, { force: true });
+    }
+    /** The ids of the keys kept; leftovers of a write cut short are deleted. */
+    async keyNames() {
+        const dir = join(this.path, KEYS_DIR);
+        const out = [];
+        for (const n of await readdir(dir).catch(() => [])) {
+            if (n.endsWith('.key'))
+                out.push(n.slice(0, -'.key'.length));
+            else
+                await rm(join(dir, n), { force: true }).catch(() => undefined);
+        }
+        return out;
+    }
+    async release() {
+        if (this.released)
+            return;
+        this.released = true;
+        await this.j?.close();
+        await this.lock.release();
+    }
+    /** Deletes the run while it still holds the lock (run.json first, so it's no longer listed), then lets the lock go. */
+    async remove() {
+        await this.j?.close();
+        await rm(join(this.path, RUN_FILE), { force: true });
+        // A data key still kept (an upload that never ended) is zeroed before it goes, as one is when its upload ends.
+        for (const id of await this.keyNames())
+            await this.removeKey(id).catch(() => undefined);
+        for (const n of await readdir(this.path).catch(() => [])) {
+            if (n !== LOCK_FILE)
+                await rm(join(this.path, n), { recursive: true, force: true });
+        }
+        this.released = true;
+        await this.lock.release();
+        await rm(this.path, { recursive: true, force: true });
+    }
+}
+/** An append that finds the history past this many bytes trims it to 7 days. */
+export const HISTORY_TRIM_BYTES = 1 << 20;
+/**
+ * One line about a finished run (section 17.12). Every SDK on this machine shares the file, so a line is added with
+ * one append (O_APPEND) and the file is never rewritten here (profile 1's G-3). It's trimmed to 7 days by
+ * trimHistory: by cleanUploads, or here once it passes HISTORY_TRIM_BYTES.
+ */
+export async function appendHistory(stateDir, line, kind = 'uploads', trimAt = HISTORY_TRIM_BYTES) {
+    const root = await privateDir(join(stateDir, kind));
+    const fh = await open(join(root, HISTORY_FILE), 'a', 0o600);
+    let size;
+    try {
+        await fh.write(`${Math.round(Date.now() / 1000)} ${line}\n`);
+        size = (await fh.stat()).size;
+    }
+    finally {
+        await fh.close();
+    }
+    if (size > trimAt)
+        await trimHistory(stateDir, kind);
+}
+/**
+ * Keeps the history's last 7 days, in one atomic rewrite. A line another SDK appends during the rewrite can be lost,
+ * so this runs only at cleanUploads or past the size cap, never on each run.
+ */
+export async function trimHistory(stateDir, kind = 'uploads') {
+    const path = join(stateDir, kind, HISTORY_FILE);
+    const old = await readIfThere(path);
+    if (!old)
+        return;
+    const week = Date.now() / 1000 - 7 * 86400;
+    const kept = [];
+    for (const l of new TextDecoder().decode(old).split('\n')) {
+        const t = Number(l.split(' ', 1)[0]);
+        if (l && Number.isFinite(t) && t >= week)
+            kept.push(l);
+    }
+    await writeAtomic(path, kept.map((l) => l + '\n').join(''));
+}
+/** The bytes under path. */
+export async function directorySize(path) {
+    let total = 0;
+    let names;
+    try {
+        names = await readdir(path);
+    }
+    catch {
+        return 0;
+    }
+    for (const n of names) {
+        const p = join(path, n);
+        const s = await stat(p).catch(() => undefined);
+        if (!s)
+            continue;
+        total += s.isDirectory() ? await directorySize(p) : s.size;
+    }
+    return total;
+}
+// --- the account key pin ---------------------------------------------------------------------------------------------
+/**
+ * The first public key seen for each account and key version (section 11.4), kept in the state directory's keys.json
+ * (and in memory when it can't be written): a different key under the same version is refused.
+ */
+export class FilePins {
+    path;
+    mem = {};
+    chain = Promise.resolve();
+    constructor(stateDir) {
+        this.path = join(stateDir, 'keys.json');
+    }
+    check(accountId, version, publicKey) {
+        const run = this.chain.then(() => this.checkNow(accountId, version, publicKey));
+        this.chain = run.catch(() => undefined);
+        return run;
+    }
+    async checkNow(accountId, version, publicKey) {
+        const encoded = Buffer.from(publicKey).toString('base64');
+        const pins = await this.load();
+        const have = pins[accountId]?.[String(version)];
+        if (have !== undefined)
+            return have === encoded;
+        (pins[accountId] ??= {})[String(version)] = encoded;
+        this.mem = pins;
+        try {
+            await privateDir(dirname(this.path));
+            await writeAtomic(this.path, JSON.stringify(pins));
+        }
+        catch {
+            // a read-only state directory: the pin stays in memory
+        }
+        return true;
+    }
+    async load() {
+        try {
+            const data = JSON.parse(await readFile(this.path, 'utf8'));
+            if (data && typeof data === 'object' && !Array.isArray(data)) {
+                const merged = { ...data };
+                for (const [acct, versions] of Object.entries(this.mem))
+                    merged[acct] = { ...(merged[acct] ?? {}), ...versions };
+                return merged;
+            }
+        }
+        catch {
+            // none yet, or unreadable: memory's
+        }
+        return { ...this.mem };
+    }
+}
+//# sourceMappingURL=journal.js.map