swarm-deploy 0.0.0 → 0.1.0

package/dist/storage/commit-store.js

@@ -0,0 +1,1339 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_COMMIT_METADATA_BYTES = exports.COMMIT_VERSION = exports.CorruptJournalError = exports.CommitStore = void 0;
+const b4a_1 = __importDefault(require("b4a"));
+const error_code_js_1 = require("../error-code.js");
+const _fs_1 = __importDefault(require("#fs"));
+const _path_1 = __importDefault(require("#path"));
+const sodium_native_1 = __importDefault(require("sodium-native"));
+const errors_js_1 = require("../errors.js");
+const files_js_1 = require("../files.js");
+const hash_js_1 = require("../tar-protocol/hash.js");
+const manifest_js_1 = require("../tar-protocol/manifest.js");
+const validation_js_1 = require("../validation.js");
+const layout_js_1 = require("./layout.js");
+const atomic_file_js_1 = require("./atomic-file.js");
+const commit_journal_js_1 = require("./commit-journal.js");
+Object.defineProperty(exports, "CorruptJournalError", { enumerable: true, get: function () { return commit_journal_js_1.CorruptJournalError; } });
+Object.defineProperty(exports, "COMMIT_VERSION", { enumerable: true, get: function () { return commit_journal_js_1.COMMIT_VERSION; } });
+Object.defineProperty(exports, "MAX_COMMIT_METADATA_BYTES", { enumerable: true, get: function () { return commit_journal_js_1.MAX_COMMIT_METADATA_BYTES; } });
+const root_coordinator_js_1 = require("./root-coordinator.js");
+function storageError(message, cause = null) {
+    return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, message, cause);
+}
+function commitError(message, cause = null) {
+    return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.COMMIT_FAILED, message, cause);
+}
+function existsError(message) {
+    return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_EXISTS, message);
+}
+function assertNotAborted(signal) {
+    if (signal?.aborted)
+        throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.ABORTED, 'Upload was aborted');
+}
+function toHex(bytes) {
+    return b4a_1.default.toString(bytes, 'hex');
+}
+function sameHex32(left, right) {
+    return (/^[0-9a-f]{64}$/.test(left) &&
+        /^[0-9a-f]{64}$/.test(right) &&
+        sodium_native_1.default.sodium_memcmp(b4a_1.default.from(left, 'hex'), b4a_1.default.from(right, 'hex')));
+}
+function isCommitRecordName(name) {
+    return typeof name === 'string' && /^[0-9a-f]{64}\.json$/.test(name);
+}
+function attemptId() {
+    const bytes = b4a_1.default.allocUnsafe(32);
+    sodium_native_1.default.randombytes_buf(bytes);
+    return toHex(bytes);
+}
+function fingerprint(ownerKey) {
+    return toHex((0, hash_js_1.sodiumSha256)(ownerKey));
+}
+function replacementsEqual(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    return (left.name === right.name &&
+        sameHex32(left.transferId, right.transferId) &&
+        left.historyName === right.historyName);
+}
+function recordsEqual(left, right) {
+    return (left.version === right.version &&
+        left.name === right.name &&
+        left.size === right.size &&
+        sameHex32(left.sha256, right.sha256) &&
+        left.committedAt === right.committedAt &&
+        left.uploaderFingerprint === right.uploaderFingerprint &&
+        sameHex32(left.transferId, right.transferId) &&
+        replacementsEqual(left.replaces, right.replaces));
+}
+function sameContent(left, right) {
+    return left.size === right.size && sameHex32(left.sha256, right.sha256);
+}
+/** The record the old sidecar becomes once its inode is only reachable as history. */
+function historyRecord(oldRecord, name) {
+    return (0, commit_journal_js_1.assertCommitRecord)({ ...oldRecord, name });
+}
+function assertSession(session) {
+    if (!session || typeof session !== 'object')
+        throw storageError('Invalid commit session');
+    const candidate = session;
+    if (candidate.state !== 'verified')
+        throw storageError('Session is not verified');
+    if (!(0, commit_journal_js_1.isHex)(candidate.id))
+        throw storageError('Invalid session ID');
+    (0, validation_js_1.assertFixed32)(candidate.transferId, 'session transfer ID');
+    (0, validation_js_1.assertFixed32)(candidate.ownerKey, 'session owner key');
+    if (typeof candidate.name !== 'string')
+        throw storageError('Invalid filename');
+    (0, files_js_1.validateBasename)(candidate.name);
+    (0, validation_js_1.assertSafeUint)(candidate.size, 'session size');
+    (0, validation_js_1.assertFixed32)(candidate.digest, 'session digest');
+    if (!sameHex32(candidate.id, toHex(candidate.transferId))) {
+        throw storageError('Session ID mismatch');
+    }
+    (0, validation_js_1.assertSafeUint)(candidate.tarSize, 'session TAR size');
+    (0, validation_js_1.assertFixed32)(candidate.tarDigest, 'session TAR digest');
+    (0, manifest_js_1.assertMetadataTransferId)(candidate.ownerKey, {
+        v: 1,
+        name: candidate.name,
+        fileSize: candidate.size,
+        fileSha256: toHex(candidate.digest),
+        tarSize: candidate.tarSize,
+        tarSha256: toHex(candidate.tarDigest),
+        transferId: candidate.id,
+        reset: false
+    });
+}
+async function readExactly(handle, bytes, position) {
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+        const read = await handle.read(bytes, offset, bytes.byteLength - offset, position + offset);
+        const count = typeof read === 'number' ? read : read.bytesRead;
+        if (!Number.isSafeInteger(count) || count <= 0)
+            return false;
+        offset += count;
+    }
+    return true;
+}
+async function writeAll(handle, bytes) {
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+        const written = await handle.write(bytes, offset, bytes.byteLength - offset, offset);
+        const count = typeof written === 'number' ? written : written.bytesWritten;
+        if (!Number.isSafeInteger(count) || count <= 0) {
+            throw storageError('Unable to write commit journal');
+        }
+        offset += count;
+    }
+}
+async function syncDirectory(directory, storage) {
+    const handle = await storage.open(directory, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function digestExactFile(filePath, size, storage, syncFirst = false) {
+    return (0, layout_js_1.withSafeDirectoryIdentity)(_path_1.default.dirname(filePath), storage, async () => {
+        const handle = await (0, layout_js_1.openSafeRegularFile)(filePath, 'read', storage);
+        try {
+            if (syncFirst)
+                await handle.sync();
+            const before = await handle.stat();
+            if (!before.isFile() || before.size !== size)
+                return null;
+            const hash = new hash_js_1.SodiumSha256();
+            let position = 0;
+            while (position < size) {
+                const bytes = b4a_1.default.alloc(Math.min(64 * 1024, size - position));
+                if (!(await readExactly(handle, bytes, position)))
+                    return null;
+                hash.update(bytes);
+                position += bytes.byteLength;
+            }
+            const after = await handle.stat();
+            if (!after.isFile() ||
+                after.size !== size ||
+                after.dev !== before.dev ||
+                after.ino !== before.ino) {
+                return null;
+            }
+            return {
+                digest: hash.digest(),
+                identity: (0, commit_journal_js_1.fileIdentity)(before)
+            };
+        }
+        finally {
+            await handle.close();
+        }
+    });
+}
+class CommitStore {
+    layout;
+    clock;
+    storage;
+    logger;
+    journalAttempts;
+    constructor({ layout, clock = Date, storage = _fs_1.default.promises, logger = null }) {
+        if (!layout || typeof layout !== 'object')
+            throw storageError('Invalid storage layout');
+        if (!clock || typeof clock.now !== 'function')
+            throw storageError('Invalid clock');
+        if (!storage || typeof storage !== 'object')
+            throw storageError('Invalid storage adapter');
+        this.layout = layout;
+        this.clock = clock;
+        this.storage = storage;
+        this.logger = logger;
+        this.journalAttempts = new Map();
+    }
+    _stagingPath(id) {
+        return _path_1.default.join(this.layout.staging, `${id}.part`);
+    }
+    _tarStagingPath(id) {
+        return _path_1.default.join(this.layout.staging, `${id}.tar.part`);
+    }
+    _sessionPath(id) {
+        return _path_1.default.join(this.layout.sessions, `${id}.json`);
+    }
+    _journalPath(id) {
+        return _path_1.default.join(this.layout.journals, `${id}.json`);
+    }
+    _recordPath(id) {
+        return _path_1.default.join(this.layout.commits, `${id}.json`);
+    }
+    _finalPath(name) {
+        return _path_1.default.join(this.layout.root, name);
+    }
+    _publicationPath(name) {
+        return _path_1.default.join(this.layout.publications, name);
+    }
+    async _assertLayout() {
+        for (const directory of (0, layout_js_1.protectedDirectories)(this.layout)) {
+            await (0, layout_js_1.assertSafeDirectory)(directory, this.storage);
+        }
+    }
+    /** Inspects one top-level path without following or trusting symlinks. */
+    _rootPathState(name) {
+        const filePath = this._finalPath(name);
+        return (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, async () => {
+            let stat;
+            try {
+                stat = await this.storage.lstat(filePath);
+            }
+            catch (err) {
+                if ((0, error_code_js_1.isMissing)(err))
+                    return { present: false, stat: null };
+                throw err;
+            }
+            if (stat.isSymbolicLink() || !stat.isFile())
+                return { present: true, stat: null };
+            return { present: true, stat };
+        });
+    }
+    async _syncRoot() {
+        await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, () => syncDirectory(this.layout.root, this.storage));
+    }
+    async _safeFileOrAbsent(filePath, directory) {
+        try {
+            return await (0, layout_js_1.withSafeDirectoryIdentity)(directory, this.storage, () => (0, layout_js_1.assertSafeFile)(filePath, this.storage));
+        }
+        catch (err) {
+            if ((0, error_code_js_1.isMissing)(err))
+                return null;
+            throw err;
+        }
+    }
+    async _readRecordOrAbsent(recordPath) {
+        const stat = await this._safeFileOrAbsent(recordPath, this.layout.commits);
+        if (!stat)
+            return null;
+        return (0, commit_journal_js_1.assertCommitRecord)(await (0, atomic_file_js_1.readJson)(recordPath, this.storage, commit_journal_js_1.MAX_COMMIT_METADATA_BYTES));
+    }
+    async _writeRecord(record) {
+        const recordPath = this._recordPath(record.transferId);
+        const existing = await this._readRecordOrAbsent(recordPath);
+        if (existing) {
+            if (!recordsEqual(existing, record))
+                throw storageError('Conflicting commit record');
+            return false;
+        }
+        await (0, atomic_file_js_1.writeAtomic)(recordPath, b4a_1.default.from(JSON.stringify(record)), this.storage);
+        return true;
+    }
+    /** Persists a sidecar transition over its own previous durable content. */
+    async _rewriteRecord(record) {
+        (0, commit_journal_js_1.assertCommitRecord)(record);
+        await (0, atomic_file_js_1.writeAtomic)(this._recordPath(record.transferId), b4a_1.default.from(JSON.stringify(record)), this.storage);
+    }
+    async _removeFile(filePath, directory) {
+        let removed = false;
+        await (0, layout_js_1.withSafeDirectoryIdentity)(directory, this.storage, async () => {
+            try {
+                await (0, layout_js_1.assertSafeFile)(filePath, this.storage);
+            }
+            catch (err) {
+                if ((0, error_code_js_1.isMissing)(err))
+                    return;
+                throw err;
+            }
+            await this.storage.unlink(filePath);
+            removed = true;
+        });
+        if (removed) {
+            await (0, layout_js_1.withSafeDirectoryIdentity)(directory, this.storage, () => syncDirectory(directory, this.storage));
+        }
+        return removed;
+    }
+    async _removeManagedFinalOrAbsent(record) {
+        let removed = false;
+        let preservedPath = false;
+        const finalPath = this._finalPath(record.name);
+        await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, async () => {
+            let stat;
+            try {
+                stat = await this.storage.lstat(finalPath);
+            }
+            catch (err) {
+                if ((0, error_code_js_1.isMissing)(err))
+                    return;
+                throw err;
+            }
+            if (stat.isDirectory()) {
+                try {
+                    await this.storage.rmdir(finalPath);
+                    removed = true;
+                }
+                catch (err) {
+                    if ((0, error_code_js_1.errorCode)(err) === 'ENOTEMPTY' || (0, error_code_js_1.errorCode)(err) === 'EEXIST') {
+                        preservedPath = true;
+                        return;
+                    }
+                    throw err;
+                }
+                return;
+            }
+            await this.storage.unlink(finalPath);
+            removed = true;
+        });
+        if (removed) {
+            await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, () => syncDirectory(this.layout.root, this.storage));
+        }
+        return { removed, preservedPath };
+    }
+    async _linkJournal(id, journal, attempt) {
+        const journalPath = this._journalPath(id);
+        const temporary = _path_1.default.join(this.layout.journals, `.${id}.${attempt}.tmp`);
+        const bytes = b4a_1.default.from(JSON.stringify((0, commit_journal_js_1.serializeJournal)(journal)));
+        try {
+            await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.journals, this.storage, async () => {
+                const handle = await (0, layout_js_1.openSafeRegularFile)(temporary, 'create', this.storage);
+                try {
+                    await writeAll(handle, bytes);
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                await this.storage.link(temporary, journalPath);
+                this.journalAttempts.set(id, attempt);
+                await syncDirectory(this.layout.journals, this.storage);
+            });
+        }
+        finally {
+            await this._removeFile(temporary, this.layout.journals).catch(() => { });
+        }
+    }
+    async _writeJournal(record, sourceStagingIdentity) {
+        const journalPath = this._journalPath(record.transferId);
+        if (await this._safeFileOrAbsent(journalPath, this.layout.journals)) {
+            let existing;
+            try {
+                existing = await this._readJournal(record.transferId);
+            }
+            catch (err) {
+                if (!(err instanceof commit_journal_js_1.CorruptJournalError))
+                    throw err;
+                await this.retireCorruptJournal(record.transferId);
+            }
+            if (existing) {
+                if (existing.version !== commit_journal_js_1.JOURNAL_VERSION ||
+                    existing.state !== 'committing' ||
+                    !recordsEqual(existing.record, record) ||
+                    !(0, commit_journal_js_1.identitiesEqual)(existing.sourceStagingIdentity, sourceStagingIdentity) ||
+                    this.journalAttempts.get(record.transferId) !== existing.attemptId) {
+                    throw storageError('Foreign commit journal already exists');
+                }
+                await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.journals, this.storage, () => syncDirectory(this.layout.journals, this.storage));
+                return existing.attemptId;
+            }
+        }
+        const id = attemptId();
+        await this._linkJournal(record.transferId, {
+            version: commit_journal_js_1.JOURNAL_VERSION,
+            state: 'committing',
+            attemptId: id,
+            sourceStagingIdentity,
+            record
+        }, id);
+        return id;
+    }
+    /** A replacement always starts a fresh attempt; leftovers belong to recovery. */
+    async _writeReplacementJournal(journal) {
+        const id = journal.transferId;
+        if (await this._safeFileOrAbsent(this._journalPath(id), this.layout.journals)) {
+            let existing = null;
+            try {
+                existing = await this._readJournal(id);
+            }
+            catch (err) {
+                if (!(err instanceof commit_journal_js_1.CorruptJournalError))
+                    throw err;
+                await this.retireCorruptJournal(id);
+            }
+            if (existing)
+                throw storageError('Foreign commit journal already exists');
+        }
+        await this._linkJournal(id, journal, journal.attemptId);
+    }
+    /**
+     * Records the boundary an attempt has already passed. The observable
+     * filesystem state stays authoritative during recovery; the phase is the
+     * durable intent trail the journal must carry.
+     */
+    async _setReplacementPhase(journal, phase) {
+        const next = { ...journal, phase };
+        await (0, atomic_file_js_1.writeAtomic)(this._journalPath(journal.transferId), b4a_1.default.from(JSON.stringify((0, commit_journal_js_1.serializeJournal)(next))), this.storage);
+        return next;
+    }
+    async retireCorruptJournal(id) {
+        if (!(0, commit_journal_js_1.isHex)(id))
+            throw storageError('Invalid corrupt journal ID');
+        const journalPath = this._journalPath(id);
+        const quarantine = _path_1.default.join(this.layout.journals, `.${id}.corrupt-${attemptId()}`);
+        let retired = false;
+        await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.journals, this.storage, async () => {
+            try {
+                await (0, layout_js_1.assertSafeFile)(journalPath, this.storage);
+            }
+            catch (err) {
+                if ((0, error_code_js_1.isMissing)(err))
+                    return;
+                throw err;
+            }
+            await this.storage.rename(journalPath, quarantine);
+            retired = true;
+        });
+        if (retired) {
+            this.journalAttempts.delete(id);
+            await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.journals, this.storage, () => syncDirectory(this.layout.journals, this.storage));
+        }
+        return retired;
+    }
+    async retireCorruptAttempt(id) {
+        if (!(0, commit_journal_js_1.isHex)(id))
+            throw storageError('Invalid corrupt journal ID');
+        const session = await this._safeFileOrAbsent(this._sessionPath(id), this.layout.sessions);
+        let removedStaging = false;
+        if (!session) {
+            removedStaging = await this._removeFile(this._stagingPath(id), this.layout.staging);
+        }
+        const retired = await this.retireCorruptJournal(id);
+        return { retired, removedStaging };
+    }
+    async _discardJournal(id, expectedAttemptId) {
+        const journal = await this._readJournal(id);
+        if (!journal) {
+            if (this.journalAttempts.get(id) === expectedAttemptId)
+                this.journalAttempts.delete(id);
+            return false;
+        }
+        if (journal.attemptId !== expectedAttemptId)
+            return false;
+        const removed = await this._removeFile(this._journalPath(id), this.layout.journals);
+        if (removed && this.journalAttempts.get(id) === expectedAttemptId) {
+            this.journalAttempts.delete(id);
+        }
+        return removed;
+    }
+    async _markAttemptAborting(id, expectedAttemptId) {
+        const journal = await this._readJournal(id);
+        if (!journal || journal.attemptId !== expectedAttemptId) {
+            throw storageError('Commit journal changed before abort');
+        }
+        if (journal.state === 'aborting')
+            return journal;
+        const bytes = b4a_1.default.from(JSON.stringify({ ...(0, commit_journal_js_1.serializeJournal)(journal), state: 'aborting' }));
+        await (0, atomic_file_js_1.writeAtomic)(this._journalPath(id), bytes, this.storage);
+        const marked = await this._readJournal(id);
+        if (!marked ||
+            marked.version !== journal.version ||
+            marked.attemptId !== expectedAttemptId ||
+            marked.state !== 'aborting') {
+            throw storageError('Commit journal changed while marking abort');
+        }
+        return marked;
+    }
+    _linkStaging(stagingPath, finalPath, expectedIdentity, signal) {
+        return (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, () => (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, async () => {
+            const staging = await (0, layout_js_1.assertSafeFile)(stagingPath, this.storage);
+            if (!(0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(staging), expectedIdentity)) {
+                throw storageError('Staging file changed before commit');
+            }
+            assertNotAborted(signal);
+            await this.storage.link(stagingPath, finalPath);
+            assertNotAborted(signal);
+        }));
+    }
+    async _removeAbortedPublication(record, expectedIdentity) {
+        const errors = [];
+        try {
+            const finalPath = this._finalPath(record.name);
+            const final = await this._safeFileOrAbsent(finalPath, this.layout.root);
+            if (final && (0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(final), expectedIdentity)) {
+                await this._removeFile(finalPath, this.layout.root);
+            }
+        }
+        catch (err) {
+            errors.push(err);
+        }
+        try {
+            const recordPath = this._recordPath(record.transferId);
+            const sidecar = await this._readRecordOrAbsent(recordPath);
+            if (sidecar && recordsEqual(sidecar, record)) {
+                await this._removeFile(recordPath, this.layout.commits);
+            }
+        }
+        catch (err) {
+            errors.push(err);
+        }
+        if (errors.length)
+            throw new AggregateError(errors, 'Unable to roll back publication');
+    }
+    _reportCleanupPending(record, err) {
+        try {
+            this.logger?.warn?.('Committed artifact cleanup remains pending', {
+                fingerprint: record.uploaderFingerprint,
+                name: record.name,
+                code: (0, error_code_js_1.errorCode)(err),
+                reason: err instanceof Error ? err.message : String(err)
+            });
+        }
+        catch { }
+    }
+    async _abortAttempt(record, expectedIdentity, attemptId, aborted) {
+        try {
+            await this._markAttemptAborting(record.transferId, attemptId);
+            await this._removeAbortedPublication(record, expectedIdentity);
+            await this._discardJournal(record.transferId, attemptId);
+        }
+        catch (cleanupError) {
+            throw new AggregateError([aborted, cleanupError], 'Unable to clean up aborted commit');
+        }
+        throw aborted;
+    }
+    async _removeOwnedFile(filePath, directory, identity) {
+        const stat = await this._safeFileOrAbsent(filePath, directory);
+        if (!stat || !(0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(stat), identity))
+            return false;
+        return this._removeFile(filePath, directory);
+    }
+    async _matchesRecord(filePath, directory, record, syncFirst = false) {
+        const stat = await this._safeFileOrAbsent(filePath, directory);
+        if (!stat)
+            return false;
+        const result = await digestExactFile(filePath, record.size, this.storage, syncFirst);
+        return result !== null && (0, hash_js_1.digestMatches)(result.digest, b4a_1.default.from(record.sha256, 'hex'));
+    }
+    _recordFromSession(session) {
+        assertSession(session);
+        const record = {
+            version: commit_journal_js_1.COMMIT_VERSION,
+            name: session.name,
+            size: session.size,
+            sha256: toHex(session.digest),
+            committedAt: this.clock.now(),
+            uploaderFingerprint: fingerprint(session.ownerKey),
+            transferId: session.id
+        };
+        return (0, commit_journal_js_1.assertCommitRecord)(record);
+    }
+    async inspect(name, offer, { replaceNames } = {}) {
+        await this._assertLayout();
+        (0, files_js_1.validateBasename)(name);
+        if ((0, files_js_1.isReservedHistoryName)(name)) {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.INVALID_FILENAME, 'Reserved artifact name');
+        }
+        if (!offer || typeof offer !== 'object')
+            throw storageError('Invalid commit offer');
+        if (offer.name !== name)
+            throw storageError('Commit offer name mismatch');
+        (0, validation_js_1.assertSafeUint)(offer.size, 'commit offer size');
+        (0, validation_js_1.assertFixed32)(offer.digest, 'commit offer digest');
+        (0, validation_js_1.assertFixed32)(offer.transferId, 'commit offer transfer ID');
+        const mutable = (0, files_js_1.validateReplaceNames)(replaceNames);
+        return (0, root_coordinator_js_1.withNameLease)(this.layout.root, name, () => this._inspect(name, offer, mutable));
+    }
+    async _inspect(name, offer, mutable) {
+        const finalPath = this._finalPath(name);
+        const final = await this._safeFileOrAbsent(finalPath, this.layout.root);
+        if (!final)
+            return { status: 'AVAILABLE' };
+        const id = toHex(offer.transferId);
+        const record = await this._readRecordOrAbsent(this._recordPath(id));
+        if (record &&
+            record.name === name &&
+            record.size === offer.size &&
+            sameHex32(record.sha256, toHex(offer.digest)) &&
+            sameHex32(record.transferId, id) &&
+            (await this._matchesRecord(finalPath, this.layout.root, record))) {
+            return { status: 'ALREADY_COMMITTED', record };
+        }
+        if (!mutable.has(name))
+            return { status: 'FILE_EXISTS' };
+        const current = await this._managedCurrent(name);
+        if (!current || !(0, commit_journal_js_1.identitiesEqual)(current.identity, (0, commit_journal_js_1.fileIdentity)(final))) {
+            return { status: 'FILE_EXISTS' };
+        }
+        if (current.record.size === offer.size &&
+            sameHex32(current.record.sha256, toHex(offer.digest))) {
+            return { status: 'ALREADY_COMMITTED', record: current.record };
+        }
+        return { status: 'REPLACEABLE', record: current.record };
+    }
+    /** The managed record whose verified content currently owns a visible name. */
+    async _managedCurrent(name) {
+        const finalPath = this._finalPath(name);
+        const matches = (await this._scanRecords()).filter((record) => record.name === name);
+        if (matches.length === 0)
+            return null;
+        if (matches.length > 1)
+            throw storageError('Duplicate managed commit filename');
+        const record = matches[0];
+        const digested = await digestExactFile(finalPath, record.size, this.storage);
+        if (!digested || !(0, hash_js_1.digestMatches)(digested.digest, b4a_1.default.from(record.sha256, 'hex')))
+            return null;
+        return { record, identity: digested.identity };
+    }
+    _assertSessionMatchesRecord(session, record, message) {
+        assertSession(session);
+        if (session.name !== record.name ||
+            session.size !== record.size ||
+            toHex(session.digest) !== record.sha256 ||
+            fingerprint(session.ownerKey) !== record.uploaderFingerprint) {
+            throw new commit_journal_js_1.CorruptJournalError(message);
+        }
+    }
+    async _validateAttemptLeftovers(id, journal, sessionStore) {
+        const { record, sourceStagingIdentity } = journal;
+        const sessionPath = this._sessionPath(id);
+        const stagingPath = this._stagingPath(id);
+        const sessionFile = await this._safeFileOrAbsent(sessionPath, this.layout.sessions);
+        const staging = await this._safeFileOrAbsent(stagingPath, this.layout.staging);
+        if (sessionFile) {
+            if (!sessionStore || typeof sessionStore.readVerified !== 'function') {
+                throw storageError('Session store cannot validate commit cleanup');
+            }
+            const session = await sessionStore.readVerified(b4a_1.default.from(id, 'hex'));
+            this._assertSessionMatchesRecord(session, record, 'Commit journal does not match verified session');
+        }
+        if (staging &&
+            (!(0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(staging), sourceStagingIdentity) ||
+                !(await this._matchesRecord(stagingPath, this.layout.staging, record)))) {
+            throw storageError('Staging file does not match commit journal');
+        }
+        return { sessionFile, staging };
+    }
+    commit(session, { retentionManager = null, signal = null, replaceNames } = {}) {
+        try {
+            assertSession(session);
+            if (retentionManager !== null &&
+                (typeof retentionManager.run !== 'function' ||
+                    typeof retentionManager.afterCommit !== 'function' ||
+                    typeof retentionManager._runUnlocked !== 'function' ||
+                    typeof retentionManager._afterCommitUnlocked !== 'function')) {
+                return Promise.reject(storageError('Invalid retention manager'));
+            }
+            if (signal !== null && (typeof signal !== 'object' || typeof signal.aborted !== 'boolean')) {
+                return Promise.reject(storageError('Invalid commit abort signal'));
+            }
+            const mutable = (0, files_js_1.validateReplaceNames)(replaceNames);
+            return (0, root_coordinator_js_1.withNameLease)(this.layout.root, session.name, () => (0, root_coordinator_js_1.withRootLease)(this.layout.root, () => this._commit(session, retentionManager, signal, mutable)));
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    async _commit(session, retentionManager, signal, mutable = new Set()) {
+        assertNotAborted(signal);
+        await this._assertLayout();
+        const record = this._recordFromSession(session);
+        if ((0, files_js_1.isReservedHistoryName)(record.name)) {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.INVALID_FILENAME, 'Reserved artifact name');
+        }
+        const stagingPath = this._stagingPath(record.transferId);
+        const finalPath = this._finalPath(record.name);
+        const stagingDigest = await digestExactFile(stagingPath, record.size, this.storage, true);
+        if (stagingDigest === null ||
+            !(0, hash_js_1.digestMatches)(stagingDigest.digest, b4a_1.default.from(record.sha256, 'hex'))) {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.CHECKSUM_MISMATCH, 'Staging file checksum mismatch');
+        }
+        if (mutable.has(record.name)) {
+            const plan = await this._planReplacement(record);
+            if (plan.mode === 'idempotent') {
+                await this._removeFile(this._sessionPath(record.transferId), this.layout.sessions);
+                await this._removeFile(stagingPath, this.layout.staging);
+                return plan.record;
+            }
+            if (plan.mode === 'replace') {
+                return this._replace(record, stagingDigest.identity, plan, retentionManager, signal);
+            }
+        }
+        if (retentionManager) {
+            await retentionManager._runUnlocked({ incomingBytes: record.size, trigger: 'commit' });
+        }
+        assertNotAborted(signal);
+        const journalAttemptId = await this._writeJournal(record, stagingDigest.identity);
+        let linked = false;
+        let linearized = false;
+        try {
+            assertNotAborted(signal);
+            await this._linkStaging(stagingPath, finalPath, stagingDigest.identity, signal);
+            linked = true;
+            await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, () => syncDirectory(this.layout.root, this.storage));
+            assertNotAborted(signal);
+            await this._writeRecord(record);
+            linearized = true;
+            assertNotAborted(signal);
+            await this._removeFile(this._sessionPath(record.transferId), this.layout.sessions);
+            assertNotAborted(signal);
+            await this._removeFile(stagingPath, this.layout.staging);
+            await this._removeFile(this._tarStagingPath(record.transferId), this.layout.staging);
+            assertNotAborted(signal);
+            await this._discardJournal(record.transferId, journalAttemptId);
+            if (retentionManager)
+                await retentionManager._afterCommitUnlocked();
+            return record;
+        }
+        catch (err) {
+            if (linearized) {
+                this._reportCleanupPending(record, err);
+                return record;
+            }
+            if ((0, error_code_js_1.errorCode)(err) === errors_js_1.ERRORS.ABORTED) {
+                return this._abortAttempt(record, stagingDigest.identity, journalAttemptId, err);
+            }
+            if (!linked && (0, error_code_js_1.errorCode)(err) !== 'EEXIST') {
+                const final = await this._safeFileOrAbsent(finalPath, this.layout.root);
+                linked =
+                    !!final &&
+                        (0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(final), stagingDigest.identity) &&
+                        (await this._matchesRecord(finalPath, this.layout.root, record));
+            }
+            if (linked) {
+                try {
+                    await this._removeAbortedPublication(record, stagingDigest.identity);
+                    await this._discardJournal(record.transferId, journalAttemptId);
+                }
+                catch (cleanupError) {
+                    throw new AggregateError([err, cleanupError], 'Unable to roll back failed publication');
+                }
+                throw err;
+            }
+            try {
+                await this._discardJournal(record.transferId, journalAttemptId);
+            }
+            catch (cleanupCause) {
+                throw Object.assign(commitError('Unable to create final artifact', err), { cleanupCause });
+            }
+            if ((0, error_code_js_1.errorCode)(err) === 'EEXIST') {
+                throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_EXISTS, 'Destination already exists', err);
+            }
+            throw commitError('Unable to create final artifact', err);
+        }
+    }
+    /**
+     * Classifies a configured mutable name. Only an exact managed current record
+     * whose verified content owns the visible path may be replaced; every other
+     * occupied path is an existing-name conflict.
+     */
+    async _planReplacement(record) {
+        const state = await this._rootPathState(record.name);
+        if (!state.present)
+            return { mode: 'create' };
+        if (!state.stat)
+            throw existsError('Destination already exists');
+        const current = await this._managedCurrent(record.name);
+        if (!current || !(0, commit_journal_js_1.identitiesEqual)(current.identity, (0, commit_journal_js_1.fileIdentity)(state.stat))) {
+            throw existsError('Destination already exists');
+        }
+        if (sameContent(current.record, record))
+            return { mode: 'idempotent', record: current.record };
+        return { mode: 'replace', oldRecord: current.record, finalIdentity: current.identity };
+    }
+    /**
+     * A repeated A→B→A sequence reuses a transfer ID that already owns a history
+     * artifact of identical content. The superseded duplicate is dropped inside
+     * the transaction so the returning content becomes the only copy.
+     */
+    async _dedupHistory(record) {
+        const name = (0, files_js_1.historyName)(record.transferId);
+        const existing = await this._readRecordOrAbsent(this._recordPath(record.transferId));
+        if (!existing)
+            return null;
+        if (existing.name !== name || !sameContent(existing, record)) {
+            throw storageError('Conflicting commit record');
+        }
+        const state = await this._rootPathState(name);
+        if (!state.present)
+            return { name, identity: null };
+        if (!state.stat)
+            throw existsError('History destination already exists');
+        const digested = await digestExactFile(this._finalPath(name), existing.size, this.storage);
+        if (!digested || !(0, hash_js_1.digestMatches)(digested.digest, b4a_1.default.from(existing.sha256, 'hex'))) {
+            throw existsError('History destination already exists');
+        }
+        return { name, identity: digested.identity };
+    }
+    async _replace(record, stagingIdentity, plan, retentionManager, signal) {
+        const { oldRecord, finalIdentity } = plan;
+        const history = (0, files_js_1.historyName)(oldRecord.transferId);
+        const newRecord = (0, commit_journal_js_1.assertCommitRecord)({
+            ...record,
+            version: commit_journal_js_1.REPLACEMENT_COMMIT_VERSION,
+            replaces: { name: record.name, transferId: oldRecord.transferId, historyName: history }
+        });
+        const finalPath = this._finalPath(record.name);
+        const historyPath = this._finalPath(history);
+        const stagingPath = this._stagingPath(record.transferId);
+        const historyState = await this._rootPathState(history);
+        if (historyState.present &&
+            !(historyState.stat && (0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(historyState.stat), finalIdentity))) {
+            throw existsError('History destination already exists');
+        }
+        const dedup = await this._dedupHistory(newRecord);
+        if (retentionManager) {
+            await retentionManager._runUnlocked({ incomingBytes: newRecord.size, trigger: 'commit' });
+        }
+        assertNotAborted(signal);
+        const pinned = await this._rootPathState(record.name);
+        if (!pinned.stat || !(0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(pinned.stat), finalIdentity)) {
+            throw commitError('Managed artifact changed before replacement');
+        }
+        const attempt = attemptId();
+        let journal = {
+            version: commit_journal_js_1.REPLACEMENT_JOURNAL_VERSION,
+            intent: 'replace',
+            state: 'committing',
+            phase: 'journaled',
+            transferId: newRecord.transferId,
+            attemptId: attempt,
+            name: newRecord.name,
+            historyName: history,
+            publicationName: `${attempt}.part`,
+            sourceStagingIdentity: stagingIdentity,
+            finalIdentity,
+            historyIdentity: finalIdentity,
+            publicationIdentity: stagingIdentity,
+            dedupHistoryName: dedup ? dedup.name : null,
+            oldRecord,
+            record: newRecord
+        };
+        const publicationPath = this._publicationPath(journal.publicationName);
+        await this._writeReplacementJournal(journal);
+        let linearized = false;
+        try {
+            assertNotAborted(signal);
+            if (dedup) {
+                if (dedup.identity) {
+                    await this._removeOwnedFile(this._finalPath(dedup.name), this.layout.root, dedup.identity);
+                }
+                await this._removeFile(this._recordPath(newRecord.transferId), this.layout.commits);
+                journal = await this._setReplacementPhase(journal, 'deduped');
+            }
+            assertNotAborted(signal);
+            if (!(await this._rootPathState(history)).present) {
+                await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, () => this.storage.link(finalPath, historyPath));
+                await this._syncRoot();
+            }
+            journal = await this._setReplacementPhase(journal, 'history-linked');
+            assertNotAborted(signal);
+            await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.publications, this.storage, () => (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, () => this.storage.link(stagingPath, publicationPath)));
+            await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.publications, this.storage, () => syncDirectory(this.layout.publications, this.storage));
+            journal = await this._setReplacementPhase(journal, 'publication-linked');
+            assertNotAborted(signal);
+            await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, () => (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.publications, this.storage, () => this.storage.rename(publicationPath, finalPath)));
+            await this._syncRoot();
+            journal = await this._setReplacementPhase(journal, 'final-renamed');
+            assertNotAborted(signal);
+            await this._writeRecord(newRecord);
+            linearized = true;
+            journal = await this._setReplacementPhase(journal, 'current-sidecar');
+            await this._rewriteRecord(historyRecord(oldRecord, history));
+            journal = await this._setReplacementPhase(journal, 'history-sidecar');
+            await this._removeFile(this._sessionPath(newRecord.transferId), this.layout.sessions);
+            await this._removeFile(stagingPath, this.layout.staging);
+            await this._removeFile(this._tarStagingPath(newRecord.transferId), this.layout.staging);
+            await this._discardJournal(newRecord.transferId, attempt);
+            if (retentionManager)
+                await retentionManager._afterCommitUnlocked();
+            return newRecord;
+        }
+        catch (err) {
+            if (linearized) {
+                this._reportCleanupPending(newRecord, err);
+                return newRecord;
+            }
+            const aborted = (0, error_code_js_1.errorCode)(err) === errors_js_1.ERRORS.ABORTED;
+            try {
+                if (aborted)
+                    await this._markAttemptAborting(newRecord.transferId, attempt);
+                await this._rollbackReplacement(journal);
+                await this._discardJournal(newRecord.transferId, attempt);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([err, cleanupError], aborted
+                    ? 'Unable to clean up aborted replacement'
+                    : 'Unable to roll back failed replacement');
+            }
+            throw err;
+        }
+    }
+    /**
+     * Restores the exact pinned old inode at the mutable name and removes only
+     * transaction-owned history, publication, and sidecar paths. A foreign
+     * destination is never overwritten or removed.
+     */
+    async _rollbackReplacement(journal) {
+        const { name, historyName: history, sourceStagingIdentity, finalIdentity } = journal;
+        const finalPath = this._finalPath(name);
+        const historyPath = this._finalPath(history);
+        const publicationPath = this._publicationPath(journal.publicationName);
+        const final = await this._rootPathState(name);
+        const historyState = await this._rootPathState(history);
+        const ownsHistory = historyState.present &&
+            historyState.stat !== null &&
+            (0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(historyState.stat), finalIdentity);
+        if (historyState.present && !ownsHistory) {
+            throw storageError('Foreign artifact at replacement history name');
+        }
+        if (final.stat && (0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(final.stat), finalIdentity)) {
+            if (ownsHistory)
+                await this._removeFile(historyPath, this.layout.root);
+        }
+        else if ((final.stat && (0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(final.stat), sourceStagingIdentity)) ||
+            !final.present) {
+            if (!ownsHistory) {
+                if (final.present)
+                    throw storageError('Replacement cannot restore the old artifact');
+            }
+            else {
+                await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, () => this.storage.rename(historyPath, finalPath));
+                await this._syncRoot();
+            }
+        }
+        else {
+            throw storageError('Foreign artifact at replacement destination');
+        }
+        await this._removeOwnedFile(publicationPath, this.layout.publications, sourceStagingIdentity);
+        const sidecar = await this._readRecordOrAbsent(this._recordPath(journal.record.transferId));
+        if (sidecar && recordsEqual(sidecar, journal.record)) {
+            await this._removeFile(this._recordPath(journal.record.transferId), this.layout.commits);
+        }
+    }
+    _readJournal(id) {
+        return (0, commit_journal_js_1.readCommitJournal)(id, this.layout, this.storage);
+    }
+    /** Every parsable v2 journal, used to explain transient duplicate names. */
+    async _pendingReplacements() {
+        const names = await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.journals, this.storage, () => this.storage.readdir(this.layout.journals));
+        const pending = [];
+        for (const filename of names.filter(isCommitRecordName).sort()) {
+            let journal;
+            try {
+                journal = await this._readJournal(filename.slice(0, -'.json'.length));
+            }
+            catch (err) {
+                if (err instanceof commit_journal_js_1.CorruptJournalError)
+                    continue;
+                throw err;
+            }
+            if ((0, commit_journal_js_1.isReplacementJournal)(journal))
+                pending.push(journal);
+        }
+        return pending;
+    }
+    /**
+     * Finalizes or rolls back one v2 attempt. The durable new current sidecar is
+     * the linearization point: before it the old content is restored, after it
+     * the new content is preserved while history metadata and cleanup converge.
+     */
+    async _convergeReplacement(id, journal, sessionStore, { forceAbort = false } = {}) {
+        const { record, name, attemptId: attempt } = journal;
+        const finalPath = this._finalPath(name);
+        const newSidecar = await this._readRecordOrAbsent(this._recordPath(record.transferId));
+        if (newSidecar && !recordsEqual(newSidecar, record)) {
+            throw storageError('Commit sidecar does not match journal');
+        }
+        if (newSidecar) {
+            const final = await this._rootPathState(name);
+            if (!final.stat ||
+                !(0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(final.stat), journal.sourceStagingIdentity) ||
+                !(await this._matchesRecord(finalPath, this.layout.root, record))) {
+                throw storageError('Linearized replacement does not own its final artifact');
+            }
+            await this._repairHistorySidecar(journal);
+            await this._removeOwnedFile(this._publicationPath(journal.publicationName), this.layout.publications, journal.sourceStagingIdentity);
+            await this._cleanupReplacementLeftovers(id, journal, sessionStore);
+            await this._discardJournal(id, attempt);
+            return { status: 'COMMITTED', record };
+        }
+        if (forceAbort && journal.state === 'committing') {
+            const marked = await this._markAttemptAborting(id, attempt);
+            if (!(0, commit_journal_js_1.isReplacementJournal)(marked))
+                throw storageError('Commit journal changed before abort');
+            journal = marked;
+        }
+        if (!(await this._assertReplacementRetryable(id, journal, sessionStore))) {
+            throw new commit_journal_js_1.CorruptJournalError('Replacement journal does not own verified staging');
+        }
+        await this._rollbackReplacement(journal);
+        await this._discardJournal(id, attempt);
+        return { status: journal.state === 'aborting' ? 'ABORTED' : 'RESUMABLE', record };
+    }
+    /**
+     * Startup recovery for one v2 attempt. Revocation of a still-live session
+     * aborts the attempt first so the same rollback path converges.
+     */
+    _recoverReplacementJournal(id, journal, sessionStore, isAuthorized) {
+        let forceAbort = journal.state === 'aborting';
+        if (isAuthorized && journal.state === 'committing') {
+            if (!sessionStore || !(sessionStore.sessions instanceof Map)) {
+                throw storageError('Session store cannot validate commit journal');
+            }
+            const session = sessionStore.sessions.get(id);
+            if (session && !isAuthorized(session.ownerKey))
+                forceAbort = true;
+        }
+        return this._convergeReplacement(id, journal, sessionStore, { forceAbort });
+    }
+    /** Writes or drops the history sidecar for an already linearized attempt. */
+    async _repairHistorySidecar(journal) {
+        const { oldRecord, historyName: history, finalIdentity } = journal;
+        const expected = historyRecord(oldRecord, history);
+        const sidecar = await this._readRecordOrAbsent(this._recordPath(oldRecord.transferId));
+        if (sidecar && !recordsEqual(sidecar, expected) && !recordsEqual(sidecar, oldRecord)) {
+            throw storageError('Replacement history sidecar does not match journal');
+        }
+        const state = await this._rootPathState(history);
+        if (state.present &&
+            (!state.stat || !(0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(state.stat), finalIdentity))) {
+            throw storageError('Foreign artifact at replacement history name');
+        }
+        if (!state.present) {
+            const sidecarPath = this._recordPath(oldRecord.transferId);
+            if (sidecar)
+                await this._removeFile(sidecarPath, this.layout.commits);
+            return;
+        }
+        if (!(await this._matchesRecord(this._finalPath(history), this.layout.root, expected))) {
+            throw storageError('Replacement history artifact does not match its record');
+        }
+        if (!sidecar || !recordsEqual(sidecar, expected))
+            await this._rewriteRecord(expected);
+    }
+    async _cleanupReplacementLeftovers(id, journal, sessionStore) {
+        const sessionFile = await this._safeFileOrAbsent(this._sessionPath(id), this.layout.sessions);
+        if (sessionFile) {
+            if (!sessionStore || typeof sessionStore.readVerified !== 'function') {
+                throw storageError('Session store cannot validate commit cleanup');
+            }
+            this._assertSessionMatchesRecord(await sessionStore.readVerified(b4a_1.default.from(id, 'hex')), journal.record, 'Commit journal does not match verified session');
+            await this._removeFile(this._sessionPath(id), this.layout.sessions);
+        }
+        const stagingPath = this._stagingPath(id);
+        const staging = await this._safeFileOrAbsent(stagingPath, this.layout.staging);
+        if (staging) {
+            if (!(0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(staging), journal.sourceStagingIdentity)) {
+                throw storageError('Staging file does not match commit journal');
+            }
+            await this._removeFile(stagingPath, this.layout.staging);
+        }
+        await this._removeFile(this._tarStagingPath(id), this.layout.staging);
+    }
+    /** Proves the verified session and staging an aborted attempt must retain. */
+    async _assertReplacementRetryable(id, journal, sessionStore) {
+        if (!sessionStore || typeof sessionStore.readVerified !== 'function') {
+            throw storageError('Session store cannot validate commit journal');
+        }
+        const session = await sessionStore.readVerified(b4a_1.default.from(id, 'hex'));
+        this._assertSessionMatchesRecord(session, journal.record, 'Replacement journal does not match verified session');
+        const stagingPath = this._stagingPath(id);
+        const staging = await this._safeFileOrAbsent(stagingPath, this.layout.staging);
+        if (!staging || !(0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(staging), journal.sourceStagingIdentity)) {
+            return false;
+        }
+        return this._matchesRecord(stagingPath, this.layout.staging, journal.record);
+    }
+    async recoverJournal(id, sessionStore, { isAuthorized = null } = {}) {
+        await this._assertLayout();
+        if (isAuthorized !== null && typeof isAuthorized !== 'function') {
+            throw storageError('Invalid recovery authorization callback');
+        }
+        const journal = await this._readJournal(id);
+        if (!journal)
+            return { status: 'MISSING' };
+        if ((0, commit_journal_js_1.isReplacementJournal)(journal)) {
+            return (0, root_coordinator_js_1.withNameLease)(this.layout.root, journal.name, () => this._recoverReplacementJournal(id, journal, sessionStore, isAuthorized));
+        }
+        const { record, attemptId: journalAttemptId, sourceStagingIdentity } = journal;
+        const finalPath = this._finalPath(record.name);
+        const final = await this._safeFileOrAbsent(finalPath, this.layout.root);
+        const sidecar = await this._readRecordOrAbsent(this._recordPath(id));
+        if (final &&
+            sidecar &&
+            recordsEqual(sidecar, record) &&
+            (0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(final), sourceStagingIdentity) &&
+            (await this._matchesRecord(finalPath, this.layout.root, record))) {
+            await this._removeFile(this._sessionPath(id), this.layout.sessions);
+            await this._removeFile(this._stagingPath(id), this.layout.staging);
+            await this._removeFile(this._tarStagingPath(id), this.layout.staging);
+            await this._discardJournal(id, journalAttemptId);
+            return { status: 'COMMITTED', record };
+        }
+        if (journal.state === 'aborting') {
+            if (!sessionStore || typeof sessionStore.readVerified !== 'function') {
+                throw storageError('Session store cannot validate aborted commit journal');
+            }
+            const session = await sessionStore.readVerified(b4a_1.default.from(id, 'hex'));
+            if (session.name !== record.name ||
+                session.size !== record.size ||
+                toHex(session.digest) !== record.sha256 ||
+                fingerprint(session.ownerKey) !== record.uploaderFingerprint) {
+                throw new commit_journal_js_1.CorruptJournalError('Revoked commit journal does not match verified session');
+            }
+            const staging = await (0, layout_js_1.assertSafeFile)(this._stagingPath(id), this.storage);
+            if (!(0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(staging), sourceStagingIdentity)) {
+                throw new commit_journal_js_1.CorruptJournalError('Revoked commit staging does not match journal');
+            }
+            await this._removeAbortedPublication(record, sourceStagingIdentity);
+            await this._discardJournal(id, journalAttemptId);
+            return { status: 'ABORTED', record };
+        }
+        if (isAuthorized) {
+            if (!sessionStore || !(sessionStore.sessions instanceof Map)) {
+                throw storageError('Session store cannot validate commit journal');
+            }
+            const authorizedSession = sessionStore.sessions.get(id);
+            if (authorizedSession && !isAuthorized(authorizedSession.ownerKey)) {
+                await this._markAttemptAborting(id, journalAttemptId);
+                return this.recoverJournal(id, sessionStore, { isAuthorized });
+            }
+        }
+        if (final) {
+            const staging = await this._safeFileOrAbsent(this._stagingPath(id), this.layout.staging);
+            const provenanced = (0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(final), sourceStagingIdentity) ||
+                (staging && (0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(final), (0, commit_journal_js_1.fileIdentity)(staging)));
+            if (!provenanced) {
+                await this._discardJournal(id, journalAttemptId);
+                return { status: 'FILE_EXISTS', record };
+            }
+            if (!(await this._matchesRecord(finalPath, this.layout.root, record))) {
+                throw storageError('Final file does not match commit journal');
+            }
+            if (!sidecar) {
+                const session = await sessionStore.readVerified(b4a_1.default.from(id, 'hex'));
+                if (session.name !== record.name ||
+                    session.size !== record.size ||
+                    toHex(session.digest) !== record.sha256 ||
+                    fingerprint(session.ownerKey) !== record.uploaderFingerprint) {
+                    throw new commit_journal_js_1.CorruptJournalError('Commit journal does not match verified session');
+                }
+                await this._writeRecord(record);
+            }
+            if (sidecar && !recordsEqual(sidecar, record)) {
+                throw storageError('Commit sidecar does not match journal');
+            }
+            await this._removeFile(this._sessionPath(id), this.layout.sessions);
+            await this._removeFile(this._stagingPath(id), this.layout.staging);
+            await this._removeFile(this._tarStagingPath(id), this.layout.staging);
+            await this._discardJournal(id, journalAttemptId);
+            return { status: 'COMMITTED', record };
+        }
+        if (sidecar && !recordsEqual(sidecar, record)) {
+            throw storageError('Commit sidecar does not match journal');
+        }
+        if (sidecar)
+            await this._removeFile(this._recordPath(id), this.layout.commits);
+        if (!sessionStore || typeof sessionStore.readVerified !== 'function') {
+            throw storageError('Session store cannot validate recovery state');
+        }
+        const session = await sessionStore.readVerified(b4a_1.default.from(id, 'hex'));
+        if (session.name !== record.name ||
+            session.size !== record.size ||
+            toHex(session.digest) !== record.sha256) {
+            throw storageError('Verified session does not match commit journal');
+        }
+        const stagingPath = this._stagingPath(id);
+        const staging = await this._safeFileOrAbsent(stagingPath, this.layout.staging);
+        if (!staging || !(0, commit_journal_js_1.identitiesEqual)((0, commit_journal_js_1.fileIdentity)(staging), sourceStagingIdentity)) {
+            throw new commit_journal_js_1.CorruptJournalError('Commit journal does not own verified staging');
+        }
+        if (!(await this._matchesRecord(stagingPath, this.layout.staging, record))) {
+            throw storageError('Verified staging does not match commit journal');
+        }
+        await this._discardJournal(id, journalAttemptId);
+        return { status: 'RESUMABLE', record };
+    }
+    async _scanRecords() {
+        const names = await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.commits, this.storage, () => this.storage.readdir(this.layout.commits));
+        const records = [];
+        for (const filename of names.filter(isCommitRecordName).sort()) {
+            const id = filename.slice(0, -'.json'.length);
+            const record = await this._readRecordOrAbsent(this._recordPath(id));
+            if (!record)
+                throw storageError('Commit record disappeared during enumeration');
+            if (record.transferId !== id)
+                throw storageError('Commit record ID does not match path');
+            records.push(record);
+        }
+        return records;
+    }
+    async scrubRecords() {
+        await this._assertLayout();
+        const names = await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.commits, this.storage, () => this.storage.readdir(this.layout.commits));
+        const records = [];
+        let deleted = 0;
+        for (const filename of names.filter(isCommitRecordName).sort()) {
+            const id = filename.slice(0, -'.json'.length);
+            const recordPath = this._recordPath(id);
+            let record = null;
+            let invalid = false;
+            try {
+                const parsed = await (0, atomic_file_js_1.readJson)(recordPath, this.storage, commit_journal_js_1.MAX_COMMIT_METADATA_BYTES);
+                try {
+                    record = (0, commit_journal_js_1.assertCommitRecord)(parsed);
+                    invalid = record.transferId !== id;
+                }
+                catch {
+                    invalid = true;
+                }
+            }
+            catch (err) {
+                if (!(err instanceof atomic_file_js_1.MetadataFormatError))
+                    throw err;
+                invalid = true;
+            }
+            if (invalid) {
+                await this._removeFile(recordPath, this.layout.commits);
+                deleted++;
+                continue;
+            }
+            if (!record)
+                throw storageError('Commit record disappeared during scrub');
+            records.push(record);
+        }
+        return { records: await this._resolveRecords(records), deleted };
+    }
+    async _resolveRecords(records) {
+        const counts = new Map();
+        for (const record of records)
+            counts.set(record.name, (counts.get(record.name) ?? 0) + 1);
+        let pending = null;
+        const resolved = [];
+        for (const record of records) {
+            if ((counts.get(record.name) ?? 0) < 2) {
+                resolved.push(record);
+                continue;
+            }
+            if (pending === null)
+                pending = await this._pendingReplacements();
+            const owner = pending.find((journal) => journal.name === record.name &&
+                journal.oldRecord.transferId === record.transferId &&
+                recordsEqual(journal.oldRecord, record));
+            resolved.push(owner ? historyRecord(record, owner.historyName) : record);
+        }
+        const seen = new Set();
+        for (const record of resolved) {
+            if (seen.has(record.name))
+                throw storageError('Duplicate managed commit filename');
+            seen.add(record.name);
+        }
+        return resolved;
+    }
+    /**
+     * A replacement makes the old sidecar the history record after its new
+     * current sidecar is durable, so one name can briefly carry two records.
+     * Only a journal-owned duplicate is tolerated, reported at the history name
+     * that recovery will persist; anything else fails closed.
+     */
+    async list() {
+        await this._assertLayout();
+        return this._resolveRecords(await this._scanRecords());
+    }
+    /**
+     * Locates the durable record a caller is deleting. A pending replacement may
+     * still carry the mutable name on the sidecar the caller knows as history.
+     */
+    async _storedRecordFor(record) {
+        const stored = await this._readRecordOrAbsent(this._recordPath(record.transferId));
+        if (!stored)
+            return null;
+        if (recordsEqual(stored, record))
+            return stored;
+        if (stored.name !== record.name &&
+            recordsEqual(historyRecord(stored, record.name), record) &&
+            (await this._pendingReplacements()).some((journal) => journal.name === stored.name &&
+                journal.historyName === record.name &&
+                recordsEqual(journal.oldRecord, stored))) {
+            return stored;
+        }
+        throw storageError('Commit record changed before deletion');
+    }
+    async delete(record) {
+        await this._assertLayout();
+        (0, commit_journal_js_1.assertCommitRecord)(record);
+        if (!(await this._storedRecordFor(record)))
+            return false;
+        const finalPath = this._finalPath(record.name);
+        const final = await this._safeFileOrAbsent(finalPath, this.layout.root);
+        if (final)
+            await this._removeFile(finalPath, this.layout.root);
+        await this._removeFile(this._recordPath(record.transferId), this.layout.commits);
+        return true;
+    }
+    async purge(record, { preservePath = false } = {}) {
+        await this._assertLayout();
+        (0, commit_journal_js_1.assertCommitRecord)(record);
+        if (!(await this._storedRecordFor(record)))
+            return false;
+        let final;
+        if (preservePath) {
+            let preservedPath = false;
+            await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, async () => {
+                try {
+                    await this.storage.lstat(this._finalPath(record.name));
+                    preservedPath = true;
+                }
+                catch (err) {
+                    if (!(0, error_code_js_1.isMissing)(err))
+                        throw err;
+                }
+            });
+            final = { removed: false, preservedPath };
+        }
+        else {
+            final = await this._removeManagedFinalOrAbsent(record);
+        }
+        await this._removeFile(this._recordPath(record.transferId), this.layout.commits);
+        return { purged: true, preservedPath: final.preservedPath };
+    }
+}
+exports.CommitStore = CommitStore;
+//# sourceMappingURL=commit-store.js.map