handmux 0.23.0 → 0.25.0

package/dist/src/workspace/schema.js

@@ -0,0 +1,156 @@
+import crypto from 'node:crypto';
+export const WORKSPACE_SCHEMA_VERSION = 1;
+const byId = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+const byLink = (a, b) => (a.index - b.index || (a.windowId < b.windowId ? -1 : a.windowId > b.windowId ? 1 : 0));
+const hash = (value) => crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+function requireObject(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+}
+function requireArray(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array`);
+}
+function requireString(value, label) {
+    if (typeof value !== 'string' || !value)
+        throw new Error(`${label} must be a non-empty string`);
+}
+function requireIndex(value, label) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${label} must be a non-negative integer`);
+    }
+}
+function validateShape(input) {
+    requireString(input.capturedAt, 'capturedAt');
+    requireObject(input.environment, 'environment');
+    for (const field of ['id', 'bootIdentity'])
+        requireString(input.environment[field], `environment.${field}`);
+    if (input.environment.tmuxServerId !== null)
+        requireString(input.environment.tmuxServerId, 'environment.tmuxServerId');
+    requireString(input.tmuxVersion, 'tmuxVersion');
+    requireArray(input.sessions, 'sessions');
+    requireArray(input.windows, 'windows');
+    const empty = input.sessions.length === 0 && input.windows.length === 0;
+    if ((input.sessions.length === 0) !== (input.windows.length === 0))
+        throw new Error('sessions and windows must both be empty or non-empty');
+    if (empty) {
+        if (input.active !== null)
+            throw new Error('active must be null for an empty workspace');
+    }
+    else {
+        requireString(input.environment.tmuxServerId, 'environment.tmuxServerId');
+        requireObject(input.active, 'active');
+        for (const field of ['sessionId', 'windowId', 'paneId'])
+            requireString(input.active[field], `active.${field}`);
+    }
+    for (const [index, session] of input.sessions.entries()) {
+        const label = `sessions[${index}]`;
+        requireObject(session, label);
+        for (const field of ['id', 'runtimeId', 'name', 'activeWindowId'])
+            requireString(session[field], `${label}.${field}`);
+        if (session.windowIds !== undefined)
+            throw new Error(`${label}.windowIds is unsupported; use windowLinks`);
+        requireArray(session.windowLinks, `${label}.windowLinks`);
+        for (const [linkIndex, link] of session.windowLinks.entries()) {
+            const linkLabel = `${label}.windowLinks[${linkIndex}]`;
+            requireObject(link, linkLabel);
+            requireString(link.windowId, `${linkLabel}.windowId`);
+            requireIndex(link.index, `${linkLabel}.index`);
+        }
+    }
+    for (const [windowIndex, window] of input.windows.entries()) {
+        const label = `windows[${windowIndex}]`;
+        requireObject(window, label);
+        for (const field of ['id', 'runtimeId', 'name', 'layout', 'activePaneId'])
+            requireString(window[field], `${label}.${field}`);
+        requireIndex(window.index, `${label}.index`);
+        requireArray(window.panes, `${label}.panes`);
+        for (const [paneIndex, pane] of window.panes.entries()) {
+            const paneLabel = `${label}.panes[${paneIndex}]`;
+            requireObject(pane, paneLabel);
+            for (const field of ['id', 'runtimeId', 'cwd'])
+                requireString(pane[field], `${paneLabel}.${field}`);
+            requireIndex(pane.index, `${paneLabel}.index`);
+            if (pane.agent !== undefined && pane.agent !== null)
+                requireObject(pane.agent, `${paneLabel}.agent`);
+        }
+    }
+}
+function validateReferences(input, sessions, windows) {
+    if (sessions.length === 0)
+        return;
+    const windowsById = new Map(windows.map((window) => [window.id, window]));
+    const sessionsById = new Map(sessions.map((session) => [session.id, session]));
+    const active = input.active;
+    if (!active)
+        throw new Error('active must be an object');
+    for (const session of sessions) {
+        const windowIds = session.windowLinks.map((link) => link.windowId);
+        const windowIndexes = session.windowLinks.map((link) => link.index);
+        if (new Set(windowIds).size !== windowIds.length)
+            throw new Error(`duplicate window link in session ${session.id}`);
+        if (new Set(windowIndexes).size !== windowIndexes.length)
+            throw new Error(`duplicate window link index in session ${session.id}`);
+        for (const { windowId } of session.windowLinks) {
+            if (!windowsById.has(windowId))
+                throw new Error(`dangling windowLinks reference ${windowId}`);
+        }
+        if (!windowIds.includes(session.activeWindowId))
+            throw new Error(`dangling activeWindowId reference ${session.activeWindowId}`);
+    }
+    for (const window of windows) {
+        if (!window.panes.some((pane) => pane.id === window.activePaneId))
+            throw new Error(`dangling activePaneId reference ${window.activePaneId}`);
+    }
+    const activeSession = sessionsById.get(active.sessionId);
+    if (!activeSession)
+        throw new Error(`dangling active.sessionId reference ${active.sessionId}`);
+    if (!activeSession.windowLinks.some((link) => link.windowId === active.windowId))
+        throw new Error(`dangling active.windowId reference ${active.windowId}`);
+    const activeWindow = windowsById.get(active.windowId);
+    if (!activeWindow?.panes.some((pane) => pane.id === active.paneId))
+        throw new Error(`dangling active.paneId reference ${active.paneId}`);
+}
+export function canonicalizeSnapshot(input) {
+    requireObject(input, 'workspace');
+    if (input.schemaVersion !== WORKSPACE_SCHEMA_VERSION)
+        throw new Error('unsupported workspace schema');
+    validateShape(input);
+    const sessions = input.sessions.map((s) => ({ ...s, windowLinks: s.windowLinks.map((link) => ({ ...link })).sort(byLink) })).sort(byId);
+    const windows = input.windows.map((w) => ({ ...w, panes: [...w.panes].sort(byId) })).sort(byId);
+    const identitySets = [
+        ['session', sessions.map((x) => x.id)],
+        ['window', windows.map((x) => x.id)],
+        ['pane', windows.flatMap((w) => w.panes.map((p) => p.id))],
+    ];
+    for (const [label, ids] of identitySets) {
+        if (new Set(ids).size !== ids.length)
+            throw new Error(`duplicate ${label} id`);
+    }
+    validateReferences(input, sessions, windows);
+    return { ...input, sessions, windows };
+}
+export function fingerprintSnapshot(input) {
+    const { capturedAt, revision, payloadHash, ...payload } = canonicalizeSnapshot(input);
+    return hash(payload);
+}
+export function sealPayload(input) {
+    const payload = canonicalizeSnapshot(input);
+    return { ...payload, payloadHash: fingerprintSnapshot(payload) };
+}
+export function validateCheckpoint(input) {
+    try {
+        requireObject(input, 'checkpoint');
+        requireString(input.id, 'checkpoint id');
+        requireString(input.archivedAt, 'checkpoint archivedAt');
+        if (typeof input.payloadHash !== 'string' || !/^[0-9a-f]{64}$/.test(input.payloadHash))
+            throw new Error('invalid checkpoint payloadHash');
+        const expected = fingerprintSnapshot(input);
+        if (input.payloadHash !== expected)
+            throw new Error('checkpoint hash mismatch');
+        return { ok: true, value: canonicalizeSnapshot(input) };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/src/workspace/store.js

@@ -0,0 +1,464 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { ensurePrivateDir, writeJsonAtomic } from './atomicJson.js';
+import { workspacePaths } from './paths.js';
+import { canonicalizeSnapshot, fingerprintSnapshot, sealPayload, validateCheckpoint, } from './schema.js';
+import { validateRecoveryMapping } from './mapping.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+const RECOVERY_WINDOW_MS = 60 * 60 * 1000;
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const recordOf = (value) => (value && typeof value === 'object' && !Array.isArray(value)
+    ? value : null);
+function hasErrorCode(error, code) {
+    return recordOf(error)?.code === code;
+}
+function requireSafeId(id) {
+    if (typeof id !== 'string' || !SAFE_ID.test(id) || id === '.' || id === '..')
+        throw new Error('workspace id must be a safe filename');
+    return id;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function projectObject(value, fields) {
+    const record = recordOf(value);
+    if (!record)
+        return value;
+    return Object.fromEntries(fields.map((field) => [field, record[field]]));
+}
+function projectSnapshot(input) {
+    const record = recordOf(input);
+    if (!record)
+        return input;
+    const environment = projectObject(record.environment, ['id', 'bootIdentity', 'tmuxServerId']);
+    const active = record.active === null ? null : projectObject(record.active, ['sessionId', 'windowId', 'paneId']);
+    const sessions = Array.isArray(record.sessions) ? record.sessions.map((session) => {
+        const projected = projectObject(session, ['id', 'runtimeId', 'name', 'windowLinks', 'activeWindowId']);
+        const projectedRecord = recordOf(projected);
+        if (!projectedRecord || !Array.isArray(projectedRecord.windowLinks))
+            return projected;
+        projectedRecord.windowLinks = projectedRecord.windowLinks.map((link) => projectObject(link, ['windowId', 'index']));
+        return projectedRecord;
+    }) : record.sessions;
+    const windows = Array.isArray(record.windows) ? record.windows.map((window) => {
+        const projected = projectObject(window, ['id', 'runtimeId', 'name', 'index', 'layout', 'activePaneId', 'panes']);
+        const projectedRecord = recordOf(projected);
+        if (!projectedRecord || !Array.isArray(projectedRecord.panes))
+            return projected;
+        projectedRecord.panes = projectedRecord.panes.map((pane) => {
+            const projectedPane = projectObject(pane, ['id', 'runtimeId', 'index', 'cwd', 'agent']);
+            const paneRecord = recordOf(projectedPane);
+            if (!paneRecord)
+                return projectedPane;
+            if (paneRecord.agent !== null && paneRecord.agent !== undefined) {
+                paneRecord.agent = projectObject(paneRecord.agent, ['id', 'sessionId', 'transcriptPath']);
+            }
+            return paneRecord;
+        });
+        return projectedRecord;
+    }) : record.windows;
+    return {
+        schemaVersion: record.schemaVersion,
+        capturedAt: record.capturedAt,
+        environment,
+        tmuxVersion: record.tmuxVersion,
+        active,
+        sessions,
+        windows,
+    };
+}
+function validateLive(value) {
+    try {
+        const record = recordOf(value);
+        if (!record || !Number.isInteger(record.revision) || record.revision < 1)
+            throw new Error('invalid live revision');
+        if (typeof record.payloadHash !== 'string' || !/^[0-9a-f]{64}$/.test(record.payloadHash))
+            throw new Error('invalid live payloadHash');
+        if (fingerprintSnapshot(value) !== record.payloadHash)
+            throw new Error('live hash mismatch');
+        const canonical = canonicalizeSnapshot(value);
+        return {
+            ok: true,
+            value: {
+                ...canonical,
+                revision: record.revision,
+                payloadHash: record.payloadHash,
+            },
+        };
+    }
+    catch (error) {
+        return { ok: false, error: errorMessage(error) };
+    }
+}
+async function readJson(file, fs) {
+    try {
+        return { status: 'ok', value: JSON.parse(await fs.readFile(file, 'utf8')) };
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return { status: 'missing' };
+        return { status: 'corrupt', error: errorMessage(error) };
+    }
+}
+async function readValidated(file, fs, validate) {
+    const result = await readJson(file, fs);
+    if (result.status !== 'ok')
+        return result;
+    try {
+        const value = validate(result.value);
+        return { status: 'ok', value };
+    }
+    catch (error) {
+        return { status: 'corrupt', error: errorMessage(error) };
+    }
+}
+function validateRecovery(value, checkpointId) {
+    const record = recordOf(value);
+    if (!record)
+        throw new Error('invalid recovery state');
+    if (record.checkpointId !== checkpointId)
+        throw new Error('recovery checkpoint id mismatch');
+    for (const field of ['detectedAt', 'expiresAt']) {
+        const entry = record[field];
+        if (typeof entry !== 'string' || Number.isNaN(Date.parse(entry)))
+            throw new Error(`invalid recovery ${field}`);
+    }
+    for (const field of ['initialSessionIds', 'pendingSessionIds']) {
+        const entry = record[field];
+        if (!Array.isArray(entry) || entry.some((id) => typeof id !== 'string' || !id))
+            throw new Error(`invalid recovery ${field}`);
+        if (new Set(entry).size !== entry.length)
+            throw new Error(`duplicate recovery ${field}`);
+    }
+    const initialSessionIds = record.initialSessionIds;
+    const pendingSessionIds = record.pendingSessionIds;
+    const initial = new Set(initialSessionIds);
+    if (pendingSessionIds.some((id) => !initial.has(id)))
+        throw new Error('recovery pending ids must be initial ids');
+    if (record.resolvedAt !== null && (typeof record.resolvedAt !== 'string' || Number.isNaN(Date.parse(record.resolvedAt))))
+        throw new Error('invalid recovery resolvedAt');
+    if (record.resolvedAt !== null && pendingSessionIds.length > 0)
+        throw new Error('resolved recovery cannot contain pending session ids');
+    let mapping = null;
+    if (record.mapping !== null) {
+        mapping = validateRecoveryMapping(record.mapping, checkpointId);
+    }
+    return {
+        checkpointId,
+        detectedAt: record.detectedAt,
+        expiresAt: record.expiresAt,
+        initialSessionIds,
+        pendingSessionIds,
+        resolvedAt: record.resolvedAt,
+        mapping,
+    };
+}
+export function selectRetainedCheckpoints(rows, now, latestId) {
+    const valid = rows
+        .filter((row) => (row.status === 'ok' && Number.isFinite(Date.parse(row.value.archivedAt))))
+        .sort((a, b) => Date.parse(b.value.archivedAt) - Date.parse(a.value.archivedAt));
+    const retained = [];
+    const retainedIds = new Set();
+    const keep = (row) => {
+        if (!row || retainedIds.has(row.id))
+            return;
+        retained.push(row);
+        retainedIds.add(row.id);
+    };
+    for (const row of valid) {
+        if (Date.parse(row.value.archivedAt) >= now - DAY_MS)
+            keep(row);
+    }
+    for (const row of valid) {
+        if (retained.length >= 10)
+            break;
+        keep(row);
+    }
+    keep(rows.find((row) => row.id === latestId));
+    return retained;
+}
+export function createWorkspaceStore({ home, now = Date.now, fs = fsp }) {
+    const paths = workspacePaths(home);
+    async function ensureDirectories() {
+        for (const dir of [path.dirname(paths.root), paths.root, paths.liveDir, paths.checkpointsDir, paths.recoveryDir, paths.operationsDir]) {
+            await ensurePrivateDir(dir, { fs });
+        }
+    }
+    async function readLiveCopy(file) {
+        const result = await readJson(file, fs);
+        if (result.status !== 'ok')
+            return result;
+        const validated = validateLive(result.value);
+        return validated.ok ? { status: 'ok', value: validated.value } : { status: 'corrupt', error: validated.error };
+    }
+    async function readLive() {
+        const copies = await Promise.all([paths.liveCurrent, paths.liveMirror].map(readLiveCopy));
+        const valid = copies
+            .map((result, index) => ({ ...result, index }))
+            .filter((result) => result.status === 'ok')
+            .sort((a, b) => b.value.revision - a.value.revision || a.index - b.index);
+        if (valid.length === 0) {
+            if (copies.every((copy) => copy.status === 'missing'))
+                return { status: 'empty' };
+            return { status: 'corrupt', errors: copies.map((copy) => copy.status === 'corrupt' ? copy.error : copy.status) };
+        }
+        const chosenCopy = valid[0];
+        if (!chosenCopy)
+            return { status: 'corrupt', errors: ['missing valid live copy'] };
+        const chosen = chosenCopy.value;
+        let repaired = false;
+        await ensureDirectories();
+        for (let index = 0; index < copies.length; index += 1) {
+            const copy = copies[index];
+            if (copy?.status === 'ok' && copy.value.revision === chosen.revision && copy.value.payloadHash === chosen.payloadHash)
+                continue;
+            await writeJsonAtomic(index === 0 ? paths.liveCurrent : paths.liveMirror, chosen, { fs });
+            repaired = true;
+        }
+        return { status: 'ok', value: chosen, repaired };
+    }
+    async function writeLive(snapshot) {
+        const payload = canonicalizeSnapshot(projectSnapshot(snapshot));
+        await ensureDirectories();
+        const copies = await Promise.all([paths.liveCurrent, paths.liveMirror].map(readLiveCopy));
+        const revision = Math.max(0, ...copies
+            .filter((copy) => copy.status === 'ok')
+            .map((copy) => copy.value.revision)) + 1;
+        const value = { ...sealPayload({ ...payload, revision }), revision };
+        await writeJsonAtomic(paths.liveCurrent, value, { fs });
+        await writeJsonAtomic(paths.liveMirror, value, { fs });
+        return value;
+    }
+    async function readCheckpoint(id) {
+        requireSafeId(id);
+        const result = await readJson(path.join(paths.checkpointsDir, `${id}.json`), fs);
+        if (result.status !== 'ok')
+            return result;
+        const validation = validateCheckpoint(result.value);
+        if (!validation.ok)
+            return { status: 'corrupt', error: validation.error };
+        if (validation.value.id !== id)
+            return { status: 'corrupt', error: 'checkpoint id does not match filename' };
+        if (validation.value.environment.id !== id)
+            return { status: 'corrupt', error: 'checkpoint environment id does not match filename' };
+        return { status: 'ok', value: validation.value };
+    }
+    async function listCheckpoints() {
+        let names;
+        try {
+            names = await fs.readdir(paths.checkpointsDir);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ENOENT'))
+                return [];
+            throw error;
+        }
+        const rows = await Promise.all(names.filter((name) => name.endsWith('.json')).map(async (name) => {
+            const id = name.slice(0, -'.json'.length);
+            if (!SAFE_ID.test(id) || id === '.' || id === '..') {
+                return { status: 'corrupt', id, error: 'checkpoint filename is not a safe id' };
+            }
+            const result = await readCheckpoint(id);
+            if (result.status === 'ok')
+                return { status: 'ok', id, value: result.value };
+            return { status: 'corrupt', id, error: result.status === 'corrupt' ? result.error : result.status };
+        }));
+        return rows.sort((a, b) => {
+            if (a.status === 'ok' && b.status === 'ok')
+                return Date.parse(b.value.archivedAt) - Date.parse(a.value.archivedAt);
+            if (a.status === 'ok')
+                return -1;
+            if (b.status === 'ok')
+                return 1;
+            return a.id.localeCompare(b.id);
+        });
+    }
+    async function readLatestCheckpoint() {
+        const pointer = await readJson(paths.latest, fs);
+        let warning;
+        if (pointer.status === 'ok') {
+            try {
+                const pointerRecord = recordOf(pointer.value);
+                const checkpointId = requireSafeId(pointerRecord?.checkpointId);
+                if (typeof pointerRecord?.payloadHash !== 'string')
+                    throw new Error('invalid latest payloadHash');
+                const pointed = await readCheckpoint(checkpointId);
+                if (pointed.status === 'ok' && pointed.value.payloadHash === pointerRecord.payloadHash)
+                    return pointed;
+                warning = `latest checkpoint is ${pointed.status === 'ok' ? 'hash-mismatched' : pointed.status}`;
+            }
+            catch (error) {
+                warning = `latest pointer is corrupt: ${errorMessage(error)}`;
+            }
+        }
+        else if (pointer.status === 'corrupt') {
+            warning = `latest pointer is corrupt: ${pointer.error}`;
+        }
+        const rows = await listCheckpoints();
+        const fallback = rows.find((row) => row.status === 'ok');
+        if (fallback)
+            return { status: 'ok', value: fallback.value, ...(warning ? { warning } : {}) };
+        if (pointer.status === 'missing' && rows.length === 0)
+            return { status: 'missing' };
+        return { status: 'corrupt', error: warning ?? 'no valid checkpoint' };
+    }
+    async function readRecovery(checkpointId) {
+        requireSafeId(checkpointId);
+        return readValidated(path.join(paths.recoveryDir, `${checkpointId}.json`), fs, (value) => validateRecovery(value, checkpointId));
+    }
+    async function createRecovery(checkpointId, detectedAt) {
+        requireSafeId(checkpointId);
+        const existing = await readRecovery(checkpointId);
+        if (existing.status === 'ok')
+            return existing;
+        if (existing.status === 'corrupt')
+            throw new Error(existing.error);
+        const checkpoint = await readCheckpoint(checkpointId);
+        if (checkpoint.status !== 'ok')
+            return checkpoint;
+        if (typeof detectedAt !== 'string' || Number.isNaN(Date.parse(detectedAt)))
+            throw new Error('detectedAt must be an ISO timestamp');
+        const initialSessionIds = checkpoint.value.sessions.map((session) => session.id);
+        const value = {
+            checkpointId,
+            detectedAt,
+            expiresAt: new Date(Date.parse(detectedAt) + RECOVERY_WINDOW_MS).toISOString(),
+            initialSessionIds,
+            pendingSessionIds: [...initialSessionIds],
+            resolvedAt: null,
+            mapping: null,
+        };
+        await ensureDirectories();
+        await writeJsonAtomic(path.join(paths.recoveryDir, `${checkpointId}.json`), value, { fs });
+        return { status: 'ok', value };
+    }
+    async function resolveSessions(checkpointId, ids) {
+        if (!Array.isArray(ids))
+            throw new Error('resolved session ids must be an array');
+        const recovery = await readRecovery(checkpointId);
+        if (recovery.status !== 'ok')
+            return recovery;
+        if (recovery.value.resolvedAt !== null)
+            return recovery;
+        const resolved = new Set(ids.filter((id) => typeof id === 'string'));
+        const pendingSessionIds = recovery.value.pendingSessionIds.filter((id) => !resolved.has(id));
+        if (pendingSessionIds.length === recovery.value.pendingSessionIds.length && pendingSessionIds.length > 0)
+            return recovery;
+        const value = {
+            ...recovery.value,
+            pendingSessionIds,
+            resolvedAt: pendingSessionIds.length === 0 ? new Date(now()).toISOString() : null,
+        };
+        await writeJsonAtomic(path.join(paths.recoveryDir, `${checkpointId}.json`), value, { fs });
+        return { status: 'ok', value };
+    }
+    async function mergeRecoveryMapping(checkpointId, mapping) {
+        const recovery = await readRecovery(checkpointId);
+        if (recovery.status !== 'ok')
+            return recovery;
+        const validatedMapping = validateRecoveryMapping(mapping, checkpointId);
+        const value = validateRecovery({ ...recovery.value, mapping: validatedMapping }, checkpointId);
+        await writeJsonAtomic(path.join(paths.recoveryDir, `${checkpointId}.json`), value, { fs });
+        return { status: 'ok', value };
+    }
+    async function writeOperation(operation) {
+        requireSafeId(operation?.id);
+        await ensureDirectories();
+        await writeJsonAtomic(path.join(paths.operationsDir, `${operation.id}.json`), operation, { fs });
+        return operation;
+    }
+    async function readOperation(id) {
+        requireSafeId(id);
+        const result = await readJson(path.join(paths.operationsDir, `${id}.json`), fs);
+        return result.status === 'ok'
+            ? { status: 'ok', value: result.value }
+            : result;
+    }
+    async function listOperations() {
+        let names;
+        try {
+            names = await fs.readdir(paths.operationsDir);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ENOENT'))
+                return [];
+            throw error;
+        }
+        return Promise.all(names.filter((name) => name.endsWith('.json')).sort().map(async (name) => {
+            const id = name.slice(0, -'.json'.length);
+            if (!SAFE_ID.test(id) || id === '.' || id === '..')
+                return { status: 'corrupt', id, error: 'operation filename is not a safe id' };
+            const result = await readOperation(id);
+            if (result.status !== 'ok')
+                return { ...result, id };
+            const value = recordOf(result.value);
+            if (value?.id !== id)
+                return { status: 'corrupt', id, error: 'operation id does not match filename' };
+            return { status: 'ok', id, value: value };
+        }));
+    }
+    async function prune() {
+        const pointer = await readJson(paths.latest, fs);
+        const pointerRecord = pointer.status === 'ok' ? recordOf(pointer.value) : null;
+        const latestId = typeof pointerRecord?.checkpointId === 'string' ? pointerRecord.checkpointId : undefined;
+        const rows = await listCheckpoints();
+        const retained = new Set(selectRetainedCheckpoints(rows, now(), latestId).map((row) => row.id));
+        const canDeleteCorrupt = pointer.status === 'ok' && SAFE_ID.test(latestId ?? '');
+        await Promise.all(rows.map(async (row) => {
+            if (retained.has(row.id) || (row.status === 'corrupt' && !canDeleteCorrupt))
+                return;
+            await fs.unlink(path.join(paths.checkpointsDir, `${row.id}.json`));
+        }));
+        return rows.filter((row) => retained.has(row.id));
+    }
+    async function archiveEnvironment({ endedReason, detectedAt }) {
+        if (typeof endedReason !== 'string' || !endedReason)
+            throw new Error('endedReason must be a non-empty string');
+        if (typeof detectedAt !== 'string' || Number.isNaN(Date.parse(detectedAt)))
+            throw new Error('detectedAt must be an ISO timestamp');
+        const live = await readLive();
+        if (live.status !== 'ok')
+            return live;
+        if (live.value.sessions.length === 0)
+            return { status: 'empty' };
+        const id = requireSafeId(live.value.environment.id);
+        await ensureDirectories();
+        let checkpoint = await readCheckpoint(id);
+        if (checkpoint.status !== 'ok') {
+            const { payloadHash: ignoredHash, revision: ignoredRevision, ...unsealed } = live.value;
+            const sealed = sealPayload({
+                ...unsealed,
+                id,
+                archivedAt: new Date(now()).toISOString(),
+                environment: { ...unsealed.environment, endedReason },
+            });
+            const validation = validateCheckpoint(sealed);
+            if (!validation.ok)
+                throw new Error(validation.error);
+            const value = validation.value;
+            await writeJsonAtomic(path.join(paths.checkpointsDir, `${id}.json`), value, { fs });
+            checkpoint = { status: 'ok', value };
+        }
+        await writeJsonAtomic(paths.latest, { checkpointId: id, payloadHash: checkpoint.value.payloadHash }, { fs });
+        await createRecovery(id, detectedAt);
+        await prune().catch(() => { });
+        return checkpoint;
+    }
+    return {
+        paths,
+        readLive,
+        writeLive,
+        archiveEnvironment,
+        listCheckpoints,
+        readCheckpoint,
+        readLatestCheckpoint,
+        readRecovery,
+        createRecovery,
+        resolveSessions,
+        mergeRecoveryMapping,
+        writeOperation,
+        readOperation,
+        listOperations,
+        prune,
+    };
+}