swarm-deploy 0.0.0 → 0.2.0

package/dist/storage/tar-session-store.js

@@ -0,0 +1,1044 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TarSessionStore = exports.TREE_SESSION_VERSION = 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 controls_js_1 = require("../tar-protocol/controls.js");
+const extract_js_1 = require("../tar-protocol/extract.js");
+const tree_extract_js_1 = require("../tar-protocol/tree-extract.js");
+const manifest_js_1 = require("../tar-protocol/manifest.js");
+const tree_manifest_js_1 = require("../tar-protocol/tree-manifest.js");
+const atomic_file_js_1 = require("./atomic-file.js");
+const commit_journal_js_1 = require("./commit-journal.js");
+const layout_js_1 = require("./layout.js");
+const tree_staging_js_1 = require("./tree-staging.js");
+const tree_fs_js_1 = require("./tree-fs.js");
+const validation_js_1 = require("../validation.js");
+const VERSION = 3;
+const LEGACY_VERSION = 2;
+/** Directory sessions are persisted at a version no file-only server understands. */
+exports.TREE_SESSION_VERSION = 4;
+const RECEIVING = 'receiving';
+const VERIFIED = 'verified';
+const DELETING = 'deleting';
+const READ_BYTES = 64 * 1024;
+function problem(message, cause = null) {
+    return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, message, cause);
+}
+function hex(bytes) {
+    return b4a_1.default.toString(bytes, 'hex');
+}
+function bytes(value, name) {
+    if (typeof value !== 'string' || !/^[0-9a-f]{64}$/.test(value))
+        throw problem(`Invalid ${name}`);
+    return b4a_1.default.from(value, 'hex');
+}
+function uint(value, name) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw problem(`Invalid ${name}`);
+    }
+}
+function key(value, name) {
+    if (!b4a_1.default.isBuffer(value) || value.byteLength !== 32)
+        throw problem(`Invalid ${name}`);
+}
+function sameMetadata(session, metadata, owner) {
+    if (!sodium_native_1.default.sodium_memcmp(session.ownerKey, owner) ||
+        session.name !== metadata.name ||
+        session.sourceParent !== metadata.sourceParent ||
+        session.tarSize !== metadata.tarSize ||
+        !sodium_native_1.default.sodium_memcmp(session.tarDigest, b4a_1.default.from(metadata.tarSha256, 'hex'))) {
+        return false;
+    }
+    if ((0, controls_js_1.isTreeMetadata)(metadata)) {
+        return (session.kind === 'directory' &&
+            session.entryCount === metadata.entryCount &&
+            session.size === metadata.payloadBytes &&
+            sodium_native_1.default.sodium_memcmp(session.digest, b4a_1.default.from(metadata.treeSha256, 'hex')));
+    }
+    return (session.kind === 'file' &&
+        session.size === metadata.fileSize &&
+        sodium_native_1.default.sodium_memcmp(session.digest, b4a_1.default.from(metadata.fileSha256, 'hex')));
+}
+async function writeAll(handle, value, position) {
+    let offset = 0;
+    while (offset < value.byteLength) {
+        const result = await handle.write(value, offset, value.byteLength - offset, position + offset);
+        const written = typeof result === 'number' ? result : result.bytesWritten;
+        if (!Number.isSafeInteger(written) || written <= 0)
+            throw problem('Unable to write TAR staging');
+        offset += written;
+    }
+}
+async function readAll(handle, size, position) {
+    const value = b4a_1.default.alloc(size);
+    let offset = 0;
+    while (offset < size) {
+        const result = await handle.read(value, offset, size - offset, position + offset);
+        const read = typeof result === 'number' ? result : result.bytesRead;
+        if (!Number.isSafeInteger(read) || read <= 0)
+            throw problem('Truncated TAR staging');
+        offset += read;
+    }
+    return value;
+}
+async function syncDirectory(directory, storage) {
+    const handle = await storage.open(directory, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Durable direct-TAR session authority. */
+class TarSessionStore {
+    layout;
+    maxStagingBytes;
+    minFreeBytes;
+    clock;
+    resumeTtl;
+    isSessionActive;
+    storage;
+    sessions = new Map();
+    reservedBytes = 0;
+    purgedSessions = 0;
+    /** Sessions dropped from memory whose staging files could not be unlinked. */
+    strandedSessions = 0;
+    initialized = false;
+    closed = false;
+    closing = false;
+    pending = Promise.resolve();
+    closePromise = null;
+    verifying = new Set();
+    verificationTasks = new Set();
+    run(operation) {
+        const result = this.pending.then(operation, operation);
+        this.pending = result.catch(() => { });
+        return result;
+    }
+    constructor({ layout, maxStagingBytes, minFreeBytes = 0, clock = Date, resumeTtl, isSessionActive = () => false, storage = _fs_1.default.promises }) {
+        if (!layout || typeof layout !== 'object')
+            throw problem('Invalid storage layout');
+        (0, validation_js_1.assertSafeUint)(maxStagingBytes, 'maxStagingBytes');
+        (0, validation_js_1.assertSafeUint)(minFreeBytes, 'minFreeBytes');
+        if (!clock || typeof clock.now !== 'function')
+            throw problem('Invalid clock');
+        if (resumeTtl !== undefined) {
+            (0, validation_js_1.assertSafeUint)(resumeTtl, 'resumeTtl');
+            if (resumeTtl === 0)
+                throw problem('Invalid resumeTtl');
+        }
+        if (typeof isSessionActive !== 'function')
+            throw problem('Invalid session activity predicate');
+        if (!storage || typeof storage !== 'object')
+            throw problem('Invalid storage adapter');
+        this.layout = layout;
+        this.maxStagingBytes = maxStagingBytes;
+        this.minFreeBytes = minFreeBytes;
+        this.clock = clock;
+        this.resumeTtl = resumeTtl;
+        this.isSessionActive = isSessionActive;
+        this.storage = storage;
+    }
+    sessionPath(id) {
+        return _path_1.default.join(this.layout.sessions, `${id}.json`);
+    }
+    tarPath(id) {
+        return _path_1.default.join(this.layout.staging, `${id}.tar.part`);
+    }
+    filePath(id) {
+        return _path_1.default.join(this.layout.staging, `${id}.part`);
+    }
+    treeStagingPath(id) {
+        return _path_1.default.join(this.layout.staging, `${id}.tree`);
+    }
+    /** Removes a staged tree through the contained primitives; never `storage.rm`. */
+    removeStagedTree(session) {
+        return (0, tree_fs_js_1.removeTree)(this.treeStagingPath(session.id), this.layout.staging, this.storage, {
+            layout: this.layout
+        });
+    }
+    journalPath(id) {
+        return _path_1.default.join(this.layout.journals, `${id}.json`);
+    }
+    reserve(session) {
+        return session.tarSize + session.size;
+    }
+    assertReady() {
+        if (!this.initialized || this.closing || this.closed) {
+            throw problem('Session store is not available');
+        }
+    }
+    metadata(input) {
+        return (0, controls_js_1.decodeAnyMetadataRecord)((0, controls_js_1.encodeAnyMetadataRecord)(input));
+    }
+    fileMetadata(input) {
+        const metadata = this.metadata(input);
+        if ((0, controls_js_1.isTreeMetadata)(metadata))
+            throw problem('Invalid file session metadata');
+        return metadata;
+    }
+    treeFromDisk(id, record) {
+        const persisted = record;
+        if (persisted.kind !== 'directory' || persisted.transferId !== id) {
+            throw problem('Invalid tree session');
+        }
+        const ownerKey = bytes(persisted.ownerKey, 'owner key');
+        uint(persisted.entryCount, 'tree entry count');
+        uint(persisted.payloadBytes, 'tree payload size');
+        uint(persisted.tarSize, 'TAR size');
+        uint(persisted.createdAt, 'creation time');
+        uint(persisted.updatedAt, 'update time');
+        if (!persisted.partialTar ||
+            persisted.partialTar.path !== `${id}.tar.part` ||
+            ![RECEIVING, VERIFIED, DELETING].includes(persisted.state)) {
+            throw problem('Invalid tree session metadata');
+        }
+        uint(persisted.partialTar.size, 'partial TAR size');
+        if (persisted.partialTar.size > persisted.tarSize)
+            throw problem('Oversized partial TAR');
+        const metadata = (0, controls_js_1.decodeTreeMetadataRecord)((0, controls_js_1.encodeTreeMetadataRecord)({
+            v: 1,
+            kind: 'directory',
+            name: persisted.name,
+            ...(persisted.sourceParent === undefined ? {} : { sourceParent: persisted.sourceParent }),
+            entryCount: persisted.entryCount,
+            payloadBytes: persisted.payloadBytes,
+            treeSha256: hex(bytes(persisted.treeSha256, 'tree digest')),
+            tarSize: persisted.tarSize,
+            tarSha256: hex(bytes(persisted.tarSha256, 'TAR digest')),
+            transferId: id,
+            reset: false
+        }));
+        (0, tree_manifest_js_1.assertTreeMetadataTransferId)(ownerKey, metadata);
+        return {
+            id,
+            transferId: b4a_1.default.from(id, 'hex'),
+            ownerKey,
+            kind: 'directory',
+            name: metadata.name,
+            sourceParent: metadata.sourceParent,
+            size: metadata.payloadBytes,
+            digest: b4a_1.default.from(metadata.treeSha256, 'hex'),
+            entryCount: metadata.entryCount,
+            tarSize: metadata.tarSize,
+            tarDigest: b4a_1.default.from(metadata.tarSha256, 'hex'),
+            tarPath: this.tarPath(id),
+            treePath: this.treeStagingPath(id),
+            partialTarSize: persisted.partialTar.size,
+            createdAt: persisted.createdAt,
+            updatedAt: persisted.updatedAt,
+            state: persisted.state
+        };
+    }
+    fromDisk(id, record) {
+        if (record.version === exports.TREE_SESSION_VERSION)
+            return this.treeFromDisk(id, record);
+        const persisted = record;
+        if ((persisted.version !== LEGACY_VERSION && persisted.version !== VERSION) ||
+            persisted.transferId !== id ||
+            (persisted.version === LEGACY_VERSION &&
+                Object.prototype.hasOwnProperty.call(record, 'sourceParent'))) {
+            throw problem('Invalid TAR session');
+        }
+        const ownerKey = bytes(persisted.ownerKey, 'owner key');
+        const transferId = bytes(persisted.transferId, 'transfer ID');
+        uint(persisted.fileSize, 'file size');
+        uint(persisted.tarSize, 'TAR size');
+        uint(persisted.createdAt, 'creation time');
+        uint(persisted.updatedAt, 'update time');
+        if (!persisted.partialTar ||
+            persisted.partialTar.path !== `${id}.tar.part` ||
+            ![RECEIVING, VERIFIED, DELETING].includes(persisted.state)) {
+            throw problem('Invalid TAR session metadata');
+        }
+        uint(persisted.partialTar.size, 'partial TAR size');
+        if (persisted.partialTar.size > persisted.tarSize) {
+            throw problem('Oversized partial TAR');
+        }
+        const metadata = this.fileMetadata({
+            v: 1,
+            name: persisted.name,
+            ...(persisted.sourceParent === undefined ? {} : { sourceParent: persisted.sourceParent }),
+            fileSize: persisted.fileSize,
+            fileSha256: hex(bytes(persisted.fileSha256, 'file digest')),
+            tarSize: persisted.tarSize,
+            tarSha256: hex(bytes(persisted.tarSha256, 'TAR digest')),
+            transferId: id,
+            reset: false
+        });
+        (0, manifest_js_1.assertMetadataTransferId)(ownerKey, metadata);
+        return {
+            id,
+            transferId,
+            ownerKey,
+            kind: 'file',
+            name: metadata.name,
+            sourceParent: metadata.sourceParent,
+            size: metadata.fileSize,
+            digest: b4a_1.default.from(metadata.fileSha256, 'hex'),
+            tarSize: metadata.tarSize,
+            tarDigest: b4a_1.default.from(metadata.tarSha256, 'hex'),
+            tarPath: this.tarPath(id),
+            partialTarSize: persisted.partialTar.size,
+            createdAt: persisted.createdAt,
+            updatedAt: persisted.updatedAt,
+            state: persisted.state
+        };
+    }
+    /**
+     * Version 3 only adds `sourceParent`, so a session without one is written as
+     * version 2. An older server can then still read, and resume, every session
+     * whose record it fully understands; only parent-bearing ones are lost to a
+     * downgrade.
+     */
+    serialize(session) {
+        if (session.kind === 'directory') {
+            return {
+                version: exports.TREE_SESSION_VERSION,
+                kind: 'directory',
+                transferId: session.id,
+                ownerKey: hex(session.ownerKey),
+                name: session.name,
+                sourceParent: session.sourceParent,
+                entryCount: session.entryCount,
+                payloadBytes: session.size,
+                treeSha256: hex(session.digest),
+                tarSize: session.tarSize,
+                tarSha256: hex(session.tarDigest),
+                partialTar: { path: `${session.id}.tar.part`, size: session.partialTarSize },
+                createdAt: session.createdAt,
+                updatedAt: session.updatedAt,
+                state: session.state
+            };
+        }
+        return {
+            version: session.sourceParent === undefined ? LEGACY_VERSION : VERSION,
+            transferId: session.id,
+            ownerKey: hex(session.ownerKey),
+            name: session.name,
+            sourceParent: session.sourceParent,
+            fileSize: session.size,
+            fileSha256: hex(session.digest),
+            tarSize: session.tarSize,
+            tarSha256: hex(session.tarDigest),
+            partialTar: { path: `${session.id}.tar.part`, size: session.partialTarSize },
+            createdAt: session.createdAt,
+            updatedAt: session.updatedAt,
+            state: session.state
+        };
+    }
+    async writeSession(session) {
+        await (0, atomic_file_js_1.writeAtomic)(this.sessionPath(session.id), b4a_1.default.from(JSON.stringify(this.serialize(session))), this.storage);
+    }
+    async remove(filePath, directory) {
+        await (0, layout_js_1.withSafeDirectoryIdentity)(directory, this.storage, async () => {
+            try {
+                await (0, layout_js_1.assertSafeFile)(filePath, this.storage);
+            }
+            catch (error) {
+                // `assertSafeFile` also throws for a path that exists but is not a
+                // regular file, and those errors carry a null cause; `isMissing`
+                // absorbs that rather than dereferencing it.
+                if ((0, error_code_js_1.isMissing)(error))
+                    return;
+                throw error;
+            }
+            await this.storage.unlink(filePath);
+        });
+        await (0, layout_js_1.withSafeDirectoryIdentity)(directory, this.storage, () => syncDirectory(directory, this.storage));
+    }
+    /** A verified directory session must still own its staging tree. */
+    async assertStagedTree(session) {
+        const state = await (0, tree_fs_js_1.inspectTreePath)(this.treeStagingPath(session.id), this.layout.staging, this.storage, { layout: this.layout });
+        if (state !== 'DIRECTORY')
+            throw problem('Session is not verified');
+    }
+    /** Verified directory sessions mid-commit may only have a durable journal tree. */
+    async assertVerifiedDirectorySession(session) {
+        const treeState = await (0, tree_fs_js_1.inspectTreePath)(this.treeStagingPath(session.id), this.layout.staging, this.storage, { layout: this.layout });
+        if (treeState === 'DIRECTORY') {
+            await this.assertStagedTree(session);
+            return;
+        }
+        const journal = await (0, commit_journal_js_1.readCommitJournal)(session.id, this.layout, this.storage);
+        if (!journal || !(0, commit_journal_js_1.isDirectoryJournal)(journal))
+            throw problem('Session is not verified');
+    }
+    async purgeCorruptSession(id) {
+        await this.remove(this.tarPath(id), this.layout.staging);
+        await this.remove(this.sessionPath(id), this.layout.sessions);
+        this.purgedSessions++;
+    }
+    /** Removes only a regular crash residue and syncs its parent before reporting it purged. */
+    async purgeSafeResidue(filePath, directory) {
+        await (0, layout_js_1.withSafeDirectoryIdentity)(directory, this.storage, async () => {
+            await (0, layout_js_1.assertSafeFile)(filePath, this.storage);
+            await this.storage.unlink(filePath);
+        });
+        await (0, layout_js_1.withSafeDirectoryIdentity)(directory, this.storage, () => syncDirectory(directory, this.storage));
+        this.purgedSessions++;
+    }
+    hashPrefix(session) {
+        return (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, async () => {
+            const handle = await (0, layout_js_1.openSafeRegularFile)(session.tarPath, 'read', this.storage);
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile() || stat.size !== session.partialTarSize) {
+                    throw problem('Partial TAR size changed');
+                }
+                const state = b4a_1.default.alloc(sodium_native_1.default.crypto_hash_sha256_STATEBYTES);
+                sodium_native_1.default.crypto_hash_sha256_init(state);
+                for (let position = 0; position < session.partialTarSize;) {
+                    const chunk = await readAll(handle, Math.min(READ_BYTES, session.partialTarSize - position), position);
+                    sodium_native_1.default.crypto_hash_sha256_update(state, chunk);
+                    position += chunk.byteLength;
+                }
+                const digest = b4a_1.default.alloc(32);
+                sodium_native_1.default.crypto_hash_sha256_final(state, digest);
+                return digest;
+            }
+            finally {
+                await handle.close();
+            }
+        });
+    }
+    ensureTarLength(session) {
+        return (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, async () => {
+            const handle = await (0, layout_js_1.openSafeRegularFile)(session.tarPath, 'write', this.storage);
+            try {
+                const stat = await handle.stat();
+                if (stat.size < session.partialTarSize)
+                    return false;
+                if (stat.size > session.tarSize) {
+                    throw problem('Oversized partial TAR');
+                }
+                if (stat.size > session.partialTarSize) {
+                    await handle.truncate(session.partialTarSize);
+                    await handle.sync();
+                }
+                return true;
+            }
+            finally {
+                await handle.close();
+            }
+        });
+    }
+    async diskReserve(incoming) {
+        if (this.minFreeBytes === 0)
+            return;
+        if (typeof this.storage.statfs !== 'function') {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.DISK_RESERVE, 'Free-disk reserve is unavailable');
+        }
+        const stat = await this.storage.statfs(this.layout.staging);
+        const available = BigInt(stat.bavail) * BigInt(stat.bsize);
+        if (available < BigInt(this.minFreeBytes) + BigInt(this.reservedBytes) + BigInt(incoming)) {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.DISK_RESERVE, 'Minimum free-disk reserve exceeded');
+        }
+    }
+    init() {
+        return this.run(async () => {
+            if (this.initialized)
+                return;
+            for (const directory of [
+                this.layout.root,
+                this.layout.internal,
+                this.layout.staging,
+                this.layout.sessions
+            ]) {
+                await (0, layout_js_1.withSafeDirectoryIdentity)(directory, this.storage, () => undefined);
+            }
+            const names = await this.storage.readdir(this.layout.sessions);
+            for (const name of names.sort()) {
+                if (!/^[0-9a-f]{64}\.json$/.test(name)) {
+                    if (/^\.[0-9a-f]{64}\.json\.[0-9a-f]{32,64}\.tmp$/.test(name)) {
+                        await this.purgeSafeResidue(_path_1.default.join(this.layout.sessions, name), this.layout.sessions);
+                        continue;
+                    }
+                    throw problem('Invalid session metadata path');
+                }
+                const id = name.slice(0, -5);
+                let record;
+                try {
+                    record = await (0, atomic_file_js_1.readJson)(this.sessionPath(id), this.storage, 16 * 1024);
+                }
+                catch (error) {
+                    if (!(error instanceof atomic_file_js_1.MetadataFormatError))
+                        throw error;
+                    await this.purgeCorruptSession(id);
+                    continue;
+                }
+                if (record.version === 1) {
+                    await this.remove(this.sessionPath(id), this.layout.sessions);
+                    await this.remove(this.tarPath(id), this.layout.staging);
+                    await this.remove(this.filePath(id), this.layout.staging);
+                    await this.remove(this.journalPath(id), this.layout.journals);
+                    this.purgedSessions++;
+                    continue;
+                }
+                let session;
+                try {
+                    session = this.fromDisk(id, record);
+                }
+                catch (error) {
+                    if (!(error instanceof errors_js_1.SwarmDeployError) || error.code !== errors_js_1.ERRORS.PROTOCOL_INVALID) {
+                        throw error;
+                    }
+                    await this.purgeCorruptSession(id);
+                    continue;
+                }
+                if (session.state === DELETING) {
+                    await this.remove(session.tarPath, this.layout.staging);
+                    if (session.kind === 'directory')
+                        await this.removeStagedTree(session);
+                    else
+                        await this.remove(this.filePath(id), this.layout.staging);
+                    await this.remove(this.sessionPath(id), this.layout.sessions);
+                    continue;
+                }
+                if (session.state === RECEIVING) {
+                    if (!(await this.ensureTarLength(session))) {
+                        session.partialTarSize = 0;
+                        session.updatedAt = this.clock.now();
+                        await this.writeSession(session);
+                    }
+                }
+                else if (session.kind === 'directory') {
+                    const treeState = await (0, tree_fs_js_1.inspectTreePath)(this.treeStagingPath(id), this.layout.staging, this.storage, { layout: this.layout });
+                    if (treeState !== 'DIRECTORY') {
+                        const journal = await (0, commit_journal_js_1.readCommitJournal)(id, this.layout, this.storage);
+                        if (!journal || !(0, commit_journal_js_1.isDirectoryJournal)(journal)) {
+                            await this.purgeCorruptSession(id);
+                            if (treeState !== 'MISSING') {
+                                await (0, tree_fs_js_1.removeTree)(this.treeStagingPath(id), this.layout.staging, this.storage, {
+                                    layout: this.layout
+                                }).catch(() => { });
+                            }
+                            continue;
+                        }
+                    }
+                    else {
+                        await this.assertVerifiedDirectorySession(session);
+                    }
+                }
+                else {
+                    await (0, layout_js_1.assertSafeFile)(this.filePath(id), this.storage);
+                }
+                this.sessions.set(id, session);
+                this.reservedBytes += this.reserve(session);
+                if (this.reservedBytes > this.maxStagingBytes) {
+                    throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.STAGING_LIMIT, 'Recovered TAR sessions exceed staging limit');
+                }
+            }
+            const expected = new Set();
+            for (const session of this.sessions.values()) {
+                expected.add(`${session.id}.tar.part`);
+                if (session.state === VERIFIED) {
+                    expected.add(session.kind === 'directory' ? `${session.id}.tree` : `${session.id}.part`);
+                }
+            }
+            for (const name of await this.storage.readdir(this.layout.staging)) {
+                if (expected.has(name))
+                    continue;
+                const tree = /^([0-9a-f]{64})\.tree$/.exec(name);
+                if (tree) {
+                    // A journal-owned tree belongs to a commit in flight; anything else is residue.
+                    if (await (0, commit_journal_js_1.readCommitJournal)(tree[1], this.layout, this.storage))
+                        continue;
+                    await (0, tree_fs_js_1.removeTree)(_path_1.default.join(this.layout.staging, name), this.layout.staging, this.storage, {
+                        layout: this.layout
+                    });
+                    this.purgedSessions++;
+                    continue;
+                }
+                const staged = /^([0-9a-f]{64})\.(?:part|tar\.part)$/.exec(name);
+                if (staged) {
+                    const journal = await (0, commit_journal_js_1.readCommitJournal)(staged[1], this.layout, this.storage);
+                    if (journal)
+                        continue;
+                    await this.purgeSafeResidue(_path_1.default.join(this.layout.staging, name), this.layout.staging);
+                    continue;
+                }
+                await this.purgeSafeResidue(_path_1.default.join(this.layout.staging, name), this.layout.staging);
+            }
+            this.initialized = true;
+        });
+    }
+    admit(ownerKey, input) {
+        return this.run(async () => {
+            this.assertReady();
+            key(ownerKey, 'owner key');
+            const metadata = this.metadata(input);
+            if ((0, controls_js_1.isTreeMetadata)(metadata))
+                (0, tree_manifest_js_1.assertTreeMetadataTransferId)(ownerKey, metadata);
+            else
+                (0, manifest_js_1.assertMetadataTransferId)(ownerKey, metadata);
+            const id = metadata.transferId;
+            if (this.resumeTtl !== undefined)
+                await this.expireUnlocked(this.resumeTtl);
+            let session = this.sessions.get(id);
+            if (session) {
+                if (!sameMetadata(session, metadata, ownerKey)) {
+                    throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, 'Transfer ID belongs to different immutable metadata');
+                }
+                if (this.verifying.has(id)) {
+                    throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, 'TAR session is being verified');
+                }
+                if (session.state === DELETING) {
+                    throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, 'TAR session is quarantined');
+                }
+                if (session.state === VERIFIED) {
+                    if (metadata.reset)
+                        throw problem('Cannot reset verified TAR session');
+                    return { status: 'VERIFIED' };
+                }
+                if (metadata.reset && session.state === RECEIVING) {
+                    await this.resetUnlocked(session);
+                    return { status: 'ACCEPT', offset: 0 };
+                }
+                if (session.state !== RECEIVING || session.partialTarSize === 0) {
+                    return { status: 'ACCEPT', offset: 0 };
+                }
+                return {
+                    status: 'RESUME',
+                    offset: session.partialTarSize,
+                    prefixSha256: await this.hashPrefix(session)
+                };
+            }
+            for (const candidate of this.sessions.values()) {
+                if (candidate.name === metadata.name) {
+                    throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, 'Destination has an active session');
+                }
+            }
+            const reservation = metadata.tarSize + ((0, controls_js_1.isTreeMetadata)(metadata) ? metadata.payloadBytes : metadata.fileSize);
+            if (this.reservedBytes > this.maxStagingBytes - reservation) {
+                throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.STAGING_LIMIT, 'Staging capacity exceeded');
+            }
+            await this.diskReserve(reservation);
+            const now = this.clock.now();
+            session = (0, controls_js_1.isTreeMetadata)(metadata)
+                ? {
+                    id,
+                    transferId: b4a_1.default.from(id, 'hex'),
+                    ownerKey: b4a_1.default.from(ownerKey),
+                    kind: 'directory',
+                    name: metadata.name,
+                    sourceParent: metadata.sourceParent,
+                    size: metadata.payloadBytes,
+                    digest: b4a_1.default.from(metadata.treeSha256, 'hex'),
+                    entryCount: metadata.entryCount,
+                    tarSize: metadata.tarSize,
+                    tarDigest: b4a_1.default.from(metadata.tarSha256, 'hex'),
+                    tarPath: this.tarPath(id),
+                    treePath: this.treeStagingPath(id),
+                    partialTarSize: 0,
+                    createdAt: now,
+                    updatedAt: now,
+                    state: RECEIVING
+                }
+                : {
+                    id,
+                    transferId: b4a_1.default.from(id, 'hex'),
+                    ownerKey: b4a_1.default.from(ownerKey),
+                    kind: 'file',
+                    name: metadata.name,
+                    sourceParent: metadata.sourceParent,
+                    size: metadata.fileSize,
+                    digest: b4a_1.default.from(metadata.fileSha256, 'hex'),
+                    tarSize: metadata.tarSize,
+                    tarDigest: b4a_1.default.from(metadata.tarSha256, 'hex'),
+                    tarPath: this.tarPath(id),
+                    partialTarSize: 0,
+                    createdAt: now,
+                    updatedAt: now,
+                    state: RECEIVING
+                };
+            await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, async () => {
+                const handle = await (0, layout_js_1.openSafeRegularFile)(session.tarPath, 'create', this.storage);
+                await handle.sync();
+                await handle.close();
+                await syncDirectory(this.layout.staging, this.storage);
+            });
+            await this.writeSession(session);
+            this.sessions.set(id, session);
+            this.reservedBytes += reservation;
+            return { status: 'ACCEPT', offset: 0 };
+        });
+    }
+    append(ownerKey, input, offset, data) {
+        return this.run(async () => {
+            this.assertReady();
+            key(ownerKey, 'owner key');
+            const metadata = this.metadata(input);
+            const session = this.sessions.get(metadata.transferId);
+            if (!session || !sameMetadata(session, metadata, ownerKey)) {
+                throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, 'Unknown or mismatched TAR session');
+            }
+            if (this.verifying.has(session.id)) {
+                throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, 'TAR session is being verified');
+            }
+            if (session.state === DELETING) {
+                throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, 'TAR session is quarantined');
+            }
+            if (session.state !== RECEIVING)
+                throw problem('Cannot append to verified TAR session');
+            if (!Number.isSafeInteger(offset) ||
+                offset !== session.partialTarSize ||
+                !b4a_1.default.isBuffer(data)) {
+                throw problem('TAR append offset does not match durable progress');
+            }
+            if (data.byteLength > session.tarSize - offset) {
+                throw problem('TAR append exceeds deterministic length');
+            }
+            if (data.byteLength === 0)
+                throw problem('TAR append must make positive progress');
+            const previous = session.partialTarSize;
+            try {
+                await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, async () => {
+                    const handle = await (0, layout_js_1.openSafeRegularFile)(session.tarPath, 'write', this.storage);
+                    try {
+                        await writeAll(handle, data, offset);
+                        await handle.sync();
+                    }
+                    finally {
+                        await handle.close();
+                    }
+                });
+            }
+            catch (cause) {
+                await this.rollbackOrQuarantine(session, previous, cause);
+                throw cause;
+            }
+            session.partialTarSize += data.byteLength;
+            session.updatedAt = this.clock.now();
+            try {
+                await this.writeSession(session);
+            }
+            catch (error) {
+                if (!(0, atomic_file_js_1.atomicWriteRenamed)(error)) {
+                    await this.rollbackOrQuarantine(session, previous, error);
+                    session.partialTarSize = previous;
+                }
+                throw error;
+            }
+            return session.partialTarSize;
+        });
+    }
+    async rollbackTar(session, length) {
+        await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, async () => {
+            const handle = await (0, layout_js_1.openSafeRegularFile)(session.tarPath, 'write', this.storage);
+            try {
+                await handle.truncate(length);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        });
+    }
+    async rollbackOrQuarantine(session, length, cause) {
+        try {
+            await this.rollbackTar(session, length);
+        }
+        catch (cleanupCause) {
+            session.state = DELETING;
+            try {
+                await this.writeSession(session);
+            }
+            catch (quarantineCause) {
+                throw Object.assign(problem('TAR append rollback and quarantine failed', cause), {
+                    cleanupCause,
+                    quarantineCause
+                });
+            }
+            throw Object.assign(problem('TAR append and rollback failed', cause), { cleanupCause });
+        }
+    }
+    async resetUnlocked(session) {
+        await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, async () => {
+            const handle = await (0, layout_js_1.openSafeRegularFile)(session.tarPath, 'write', this.storage);
+            try {
+                await handle.truncate(0);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        });
+        session.partialTarSize = 0;
+        session.updatedAt = this.clock.now();
+        await this.writeSession(session);
+    }
+    async quarantineVerificationFailure(session, cause, cleanupCause) {
+        const failure = Object.assign(problem('TAR verification cleanup failed', cause), {
+            cleanupCause
+        });
+        try {
+            await this.run(async () => {
+                session.state = DELETING;
+                session.updatedAt = this.clock.now();
+                await this.writeSession(session);
+            });
+        }
+        catch (quarantineCause) {
+            throw Object.assign(failure, { quarantineCause });
+        }
+        throw failure;
+    }
+    verify(ownerKey, input) {
+        const task = (async () => {
+            const prepared = await this.run(() => {
+                this.assertReady();
+                key(ownerKey, 'owner key');
+                const metadata = this.metadata(input);
+                const session = this.sessions.get(metadata.transferId);
+                if (!session ||
+                    session.state !== RECEIVING ||
+                    !sameMetadata(session, metadata, ownerKey) ||
+                    this.verifying.has(session.id)) {
+                    throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, 'Unknown or mismatched TAR session');
+                }
+                if (session.partialTarSize !== session.tarSize)
+                    throw problem('TAR transfer is incomplete');
+                this.verifying.add(session.id);
+                return { metadata, session };
+            });
+            const { metadata, session } = prepared;
+            let file = null;
+            let fileOffset = 0;
+            try {
+                if (session.kind === 'directory') {
+                    await this.extractTree(session, metadata);
+                }
+                else {
+                    file = await (0, layout_js_1.openSafeRegularFile)(this.filePath(session.id), 'create', this.storage);
+                    const source = this.readTar(session);
+                    await (0, extract_js_1.validateAndExtractTar)(source, metadata, {
+                        writeTar: () => { },
+                        writeFile: async (chunk) => {
+                            await writeAll(file, chunk, fileOffset);
+                            fileOffset += chunk.byteLength;
+                        },
+                        complete: async () => {
+                            await file.sync();
+                        },
+                        abort: async () => {
+                            await file?.close().catch(() => { });
+                            file = null;
+                            await this.remove(this.filePath(session.id), this.layout.staging).catch(() => { });
+                        }
+                    });
+                    await file.close();
+                    file = null;
+                    await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, () => syncDirectory(this.layout.staging, this.storage));
+                }
+                await this.run(async () => {
+                    if (this.sessions.get(session.id) !== session ||
+                        session.state !== RECEIVING ||
+                        !this.verifying.has(session.id)) {
+                        throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, 'TAR session changed during verification');
+                    }
+                    const previousUpdatedAt = session.updatedAt;
+                    session.state = VERIFIED;
+                    session.updatedAt = this.clock.now();
+                    try {
+                        await this.writeSession(session);
+                    }
+                    catch (error) {
+                        if (!(0, atomic_file_js_1.atomicWriteRenamed)(error)) {
+                            session.state = RECEIVING;
+                            session.updatedAt = previousUpdatedAt;
+                        }
+                        throw error;
+                    }
+                });
+                return session;
+            }
+            catch (error) {
+                if (file)
+                    await file.close().catch(() => { });
+                if (session.state !== VERIFIED) {
+                    try {
+                        if (session.kind === 'directory')
+                            await this.removeStagedTree(session);
+                        else
+                            await this.remove(this.filePath(session.id), this.layout.staging);
+                    }
+                    catch (cleanupCause) {
+                        await this.quarantineVerificationFailure(session, error, cleanupCause);
+                    }
+                }
+                throw error;
+            }
+            finally {
+                await this.run(() => {
+                    this.verifying.delete(session.id);
+                });
+            }
+        })();
+        this.verificationTasks.add(task);
+        const settled = () => {
+            this.verificationTasks.delete(task);
+        };
+        task.then(settled, settled);
+        return task;
+    }
+    /**
+     * Extracts the complete directory archive into its staging tree, then proves
+     * the tree from the bytes on disk alone: the recomputed canonical digest,
+     * entry count, and payload size must equal the offered values.
+     */
+    async extractTree(session, metadata) {
+        const treePath = this.treeStagingPath(session.id);
+        const options = { layout: this.layout };
+        // Residue of an interrupted attempt never survives into a new extraction.
+        await (0, tree_fs_js_1.removeTree)(treePath, this.layout.staging, this.storage, options);
+        const target = (0, tree_staging_js_1.createTreeStagingTarget)(treePath, this.layout.staging, this.storage, this.layout);
+        await (0, tree_extract_js_1.validateAndExtractTreeTar)(this.readTar(session), metadata, target);
+        const staged = await (0, tree_fs_js_1.digestTree)(treePath, this.storage);
+        if (staged.entryCount !== metadata.entryCount ||
+            staged.payloadBytes !== metadata.payloadBytes ||
+            !sodium_native_1.default.sodium_memcmp(staged.treeSha256, b4a_1.default.from(metadata.treeSha256, 'hex'))) {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.CHECKSUM_MISMATCH, 'Staged tree digest mismatch');
+        }
+        await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, () => syncDirectory(this.layout.staging, this.storage));
+    }
+    async *readTar(session) {
+        const handle = await (0, layout_js_1.openSafeRegularFile)(session.tarPath, 'read', this.storage);
+        try {
+            for (let position = 0; position < session.tarSize;) {
+                const chunk = await readAll(handle, Math.min(READ_BYTES, session.tarSize - position), position);
+                position += chunk.byteLength;
+                yield chunk;
+            }
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    readVerified(transferId) {
+        return this.run(async () => {
+            this.assertReady();
+            key(transferId, 'transfer ID');
+            const session = this.sessions.get(hex(transferId));
+            if (!session || session.state !== VERIFIED)
+                throw problem('Session is not verified');
+            if (session.kind === 'directory')
+                await this.assertVerifiedDirectorySession(session);
+            else
+                await (0, layout_js_1.assertSafeFile)(this.filePath(session.id), this.storage);
+            return session;
+        });
+    }
+    /**
+     * Drops a session from the in-memory authority exactly once.
+     *
+     * `reservedBytes` must always equal the sum of `reserve()` over `sessions`,
+     * so the bookkeeping runs in a `finally`: a failed unlink would otherwise
+     * strand the reservation for the lifetime of the process, and leave the name
+     * permanently colliding in `admit()`. Any file that survives the failure is a
+     * crash residue, which `init()` purges on the next start.
+     */
+    async removeSession(session) {
+        session.state = DELETING;
+        session.updatedAt = this.clock.now();
+        try {
+            await this.writeSession(session);
+            await this.remove(session.tarPath, this.layout.staging);
+            if (session.kind === 'directory')
+                await this.removeStagedTree(session);
+            else
+                await this.remove(this.filePath(session.id), this.layout.staging);
+            await this.remove(this.sessionPath(session.id), this.layout.sessions);
+        }
+        finally {
+            if (this.sessions.delete(session.id))
+                this.reservedBytes -= this.reserve(session);
+        }
+    }
+    delete(transferId) {
+        return this.run(async () => {
+            this.assertReady();
+            key(transferId, 'transfer ID');
+            const id = hex(transferId);
+            const session = this.sessions.get(id);
+            if (!session)
+                return false;
+            if (this.verifying.has(id)) {
+                throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, 'TAR session is being verified');
+            }
+            if (session.state === DELETING) {
+                throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.FILE_BUSY, 'TAR session is quarantined');
+            }
+            await this.removeSession(session);
+            return true;
+        });
+    }
+    /**
+     * Sweeps expired sessions without letting one failure abort the rest.
+     *
+     * `admit()` runs this opportunistically on every offer, so a single session
+     * whose files cannot be unlinked must not deny service to every later
+     * upload. Failures are counted in `strandedSessions` and reported to the
+     * explicit `expire()` caller, which asked for the sweep and can act on it.
+     */
+    async expireUnlocked(ttl, predicate = () => true) {
+        let removed = 0;
+        let failure = null;
+        for (const session of [...this.sessions.values()]) {
+            if (this.verifying.has(session.id) ||
+                session.state === DELETING ||
+                this.clock.now() - session.updatedAt <= ttl ||
+                !predicate(session) ||
+                this.isSessionActive(session)) {
+                continue;
+            }
+            try {
+                await this.removeSession(session);
+                removed++;
+            }
+            catch (error) {
+                this.strandedSessions++;
+                if (failure === null)
+                    failure = error;
+            }
+        }
+        return { removed, failure };
+    }
+    expire(ttl, predicate = () => true) {
+        return this.run(async () => {
+            this.assertReady();
+            const { removed, failure } = await this.expireUnlocked(ttl, predicate);
+            if (failure !== null)
+                throw failure;
+            return removed;
+        });
+    }
+    retireCommitted(transferId) {
+        return this.delete(transferId);
+    }
+    close() {
+        if (this.closePromise)
+            return this.closePromise;
+        this.closePromise = (async () => {
+            await this.run(() => {
+                this.closing = true;
+            });
+            await Promise.allSettled([...this.verificationTasks]);
+            await this.run(() => {
+                this.closed = true;
+            });
+        })();
+        return this.closePromise;
+    }
+}
+exports.TarSessionStore = TarSessionStore;
+//# sourceMappingURL=tar-session-store.js.map