swarm-deploy 0.1.0 → 0.3.0

package/dist/storage/commit-store.js

@@ -13,6 +13,7 @@ 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 tree_manifest_js_1 = require("../tar-protocol/tree-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");
@@ -21,6 +22,7 @@ Object.defineProperty(exports, "CorruptJournalError", { enumerable: true, get: f
 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");
+const tree_fs_js_1 = require("./tree-fs.js");
 function storageError(message, cause = null) {
     return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.PROTOCOL_INVALID, message, cause);
 }
@@ -60,19 +62,37 @@ function replacementsEqual(left, right) {
         sameHex32(left.transferId, right.transferId) &&
         left.historyName === right.historyName);
 }
+function releasesEqual(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    return left.series === right.series && left.version === right.version;
+}
 function recordsEqual(left, right) {
     return (left.version === right.version &&
+        left.kind === right.kind &&
         left.name === right.name &&
         left.size === right.size &&
+        left.entryCount === right.entryCount &&
         sameHex32(left.sha256, right.sha256) &&
         left.committedAt === right.committedAt &&
         left.uploaderFingerprint === right.uploaderFingerprint &&
         sameHex32(left.transferId, right.transferId) &&
+        releasesEqual(left.release, right.release) &&
         replacementsEqual(left.replaces, right.replaces));
 }
 function sameContent(left, right) {
     return left.size === right.size && sameHex32(left.sha256, right.sha256);
 }
+function snapshotRelease(release) {
+    if (release === null || release === undefined)
+        return undefined;
+    const snapshot = {
+        series: release.series,
+        ...(release.version === undefined ? {} : { version: release.version })
+    };
+    (0, commit_journal_js_1.assertCommitRelease)(snapshot);
+    return snapshot;
+}
 /** 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 });
@@ -97,9 +117,34 @@ function assertSession(session) {
     }
     (0, validation_js_1.assertSafeUint)(candidate.tarSize, 'session TAR size');
     (0, validation_js_1.assertFixed32)(candidate.tarDigest, 'session TAR digest');
+    if (candidate.kind === 'directory') {
+        (0, validation_js_1.assertSafeUint)(candidate.entryCount, 'session entry count');
+        (0, tree_manifest_js_1.assertTreeMetadataTransferId)(candidate.ownerKey, {
+            v: 1,
+            kind: 'directory',
+            name: candidate.name,
+            ...(candidate.sourceParent === undefined
+                ? {}
+                : { sourceParent: candidate.sourceParent }),
+            entryCount: candidate.entryCount,
+            payloadBytes: candidate.size,
+            treeSha256: toHex(candidate.digest),
+            tarSize: candidate.tarSize,
+            tarSha256: toHex(candidate.tarDigest),
+            transferId: candidate.id,
+            reset: false
+        });
+        return;
+    }
+    if (candidate.kind !== 'file' && candidate.kind !== undefined) {
+        throw storageError('Invalid session artifact kind');
+    }
     (0, manifest_js_1.assertMetadataTransferId)(candidate.ownerKey, {
         v: 1,
         name: candidate.name,
+        ...(candidate.sourceParent === undefined
+            ? {}
+            : { sourceParent: candidate.sourceParent }),
         fileSize: candidate.size,
         fileSha256: toHex(candidate.digest),
         tarSize: candidate.tarSize,
@@ -199,6 +244,16 @@ class CommitStore {
     _tarStagingPath(id) {
         return _path_1.default.join(this.layout.staging, `${id}.tar.part`);
     }
+    _treeStagingPath(id) {
+        return _path_1.default.join(this.layout.staging, `${id}.tree`);
+    }
+    _trashTreePath(id) {
+        return _path_1.default.join(this.layout.trash, `${id}.tree`);
+    }
+    /** The visible state of one top-level directory path, without following links. */
+    _rootTreeState(name) {
+        return (0, tree_fs_js_1.inspectTreePath)(this._finalPath(name), this.layout.root, this.storage);
+    }
     _sessionPath(id) {
         return _path_1.default.join(this.layout.sessions, `${id}.json`);
     }
@@ -384,8 +439,8 @@ class CommitStore {
         }, id);
         return id;
     }
-    /** A replacement always starts a fresh attempt; leftovers belong to recovery. */
-    async _writeReplacementJournal(journal) {
+    /** A replacement or directory commit always starts a fresh attempt; leftovers belong to recovery. */
+    async _writeFreshJournal(journal) {
         const id = journal.transferId;
         if (await this._safeFileOrAbsent(this._journalPath(id), this.layout.journals)) {
             let existing = null;
@@ -551,18 +606,25 @@ class CommitStore {
         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) {
+    _recordFromSession(session, release) {
         assertSession(session);
-        const record = {
-            version: commit_journal_js_1.COMMIT_VERSION,
+        const base = {
             name: session.name,
             size: session.size,
             sha256: toHex(session.digest),
             committedAt: this.clock.now(),
             uploaderFingerprint: fingerprint(session.ownerKey),
-            transferId: session.id
+            transferId: session.id,
+            ...(release === undefined ? {} : { release })
         };
-        return (0, commit_journal_js_1.assertCommitRecord)(record);
+        return (0, commit_journal_js_1.assertCommitRecord)(session.kind === 'directory'
+            ? {
+                version: commit_journal_js_1.DIRECTORY_COMMIT_VERSION,
+                kind: 'directory',
+                entryCount: session.entryCount,
+                ...base
+            }
+            : { version: commit_journal_js_1.COMMIT_VERSION, ...base });
     }
     async inspect(name, offer, { replaceNames } = {}) {
         await this._assertLayout();
@@ -577,10 +639,18 @@ class CommitStore {
         (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');
+        if (offer.kind !== undefined && offer.kind !== 'file' && offer.kind !== 'directory') {
+            throw storageError('Invalid commit offer kind');
+        }
+        if (offer.kind === 'directory')
+            (0, validation_js_1.assertSafeUint)(offer.entryCount, 'commit offer entry count');
+        const release = snapshotRelease(offer.release);
         const mutable = (0, files_js_1.validateReplaceNames)(replaceNames);
-        return (0, root_coordinator_js_1.withNameLease)(this.layout.root, name, () => this._inspect(name, offer, mutable));
+        return (0, root_coordinator_js_1.withNameLease)(this.layout.root, name, () => this._inspect(name, offer, mutable, release));
     }
-    async _inspect(name, offer, mutable) {
+    async _inspect(name, offer, mutable, release) {
+        if (offer.kind === 'directory')
+            return this._inspectDirectory(name, offer);
         const finalPath = this._finalPath(name);
         const final = await this._safeFileOrAbsent(finalPath, this.layout.root);
         if (!final)
@@ -592,6 +662,7 @@ class CommitStore {
             record.size === offer.size &&
             sameHex32(record.sha256, toHex(offer.digest)) &&
             sameHex32(record.transferId, id) &&
+            releasesEqual(record.release, release) &&
             (await this._matchesRecord(finalPath, this.layout.root, record))) {
             return { status: 'ALREADY_COMMITTED', record };
         }
@@ -601,12 +672,52 @@ class CommitStore {
         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 &&
+        const sameRelease = releasesEqual(current.record.release, release);
+        if (sameHex32(current.record.transferId, id) && !sameRelease) {
+            // One transfer ID names one authenticated upload; its release identity is immutable.
+            throw storageError('Release identity conflicts with the committed transfer');
+        }
+        if (sameRelease &&
+            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 };
     }
+    async _inspectDirectory(name, offer) {
+        if ((await this._rootTreeState(name)) === 'MISSING') {
+            const occupied = await this._safeFileOrAbsent(this._finalPath(name), this.layout.root);
+            return occupied ? { status: 'FILE_EXISTS' } : { status: 'AVAILABLE' };
+        }
+        const id = toHex(offer.transferId);
+        const record = await this._readRecordOrAbsent(this._recordPath(id));
+        if (!record ||
+            record.kind !== 'directory' ||
+            record.name !== name ||
+            record.size !== offer.size ||
+            record.entryCount !== offer.entryCount ||
+            !sameHex32(record.sha256, toHex(offer.digest)) ||
+            !sameHex32(record.transferId, id)) {
+            return { status: 'FILE_EXISTS' };
+        }
+        let digested;
+        try {
+            digested = await (0, tree_fs_js_1.digestTree)(this._finalPath(name), this.storage);
+        }
+        catch (error) {
+            if (error instanceof errors_js_1.SwarmDeployError &&
+                (error.code === errors_js_1.ERRORS.INVALID_FILENAME || error.code === errors_js_1.ERRORS.PROTOCOL_INVALID)) {
+                return { status: 'FILE_EXISTS' };
+            }
+            throw error;
+        }
+        if (digested.entryCount !== record.entryCount ||
+            digested.payloadBytes !== record.size ||
+            !(0, hash_js_1.digestMatches)(digested.treeSha256, b4a_1.default.from(record.sha256, 'hex'))) {
+            return { status: 'FILE_EXISTS' };
+        }
+        return { status: 'ALREADY_COMMITTED', record };
+    }
     /** The managed record whose verified content currently owns a visible name. */
     async _managedCurrent(name) {
         const finalPath = this._finalPath(name);
@@ -626,7 +737,9 @@ class CommitStore {
         if (session.name !== record.name ||
             session.size !== record.size ||
             toHex(session.digest) !== record.sha256 ||
-            fingerprint(session.ownerKey) !== record.uploaderFingerprint) {
+            fingerprint(session.ownerKey) !== record.uploaderFingerprint ||
+            (record.kind === 'directory' &&
+                (session.kind !== 'directory' || session.entryCount !== record.entryCount))) {
             throw new commit_journal_js_1.CorruptJournalError(message);
         }
     }
@@ -650,9 +763,10 @@ class CommitStore {
         }
         return { sessionFile, staging };
     }
-    commit(session, { retentionManager = null, signal = null, replaceNames } = {}) {
+    commit(session, { retentionManager = null, signal = null, replaceNames, release = null, deferPostCommitRetention = false } = {}) {
         try {
             assertSession(session);
+            const releaseSnapshot = snapshotRelease(release);
             if (retentionManager !== null &&
                 (typeof retentionManager.run !== 'function' ||
                     typeof retentionManager.afterCommit !== 'function' ||
@@ -664,19 +778,22 @@ class CommitStore {
                 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)));
+            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, releaseSnapshot, deferPostCommitRetention === true)));
         }
         catch (error) {
             return Promise.reject(error);
         }
     }
-    async _commit(session, retentionManager, signal, mutable = new Set()) {
+    async _commit(session, retentionManager, signal, mutable = new Set(), release, deferPostCommitRetention = false) {
         assertNotAborted(signal);
         await this._assertLayout();
-        const record = this._recordFromSession(session);
+        const record = this._recordFromSession(session, release);
         if ((0, files_js_1.isReservedHistoryName)(record.name)) {
             throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.INVALID_FILENAME, 'Reserved artifact name');
         }
+        if (session.kind === 'directory') {
+            return this._commitDirectory(record, retentionManager, signal, mutable, deferPostCommitRetention);
+        }
         const stagingPath = this._stagingPath(record.transferId);
         const finalPath = this._finalPath(record.name);
         const stagingDigest = await digestExactFile(stagingPath, record.size, this.storage, true);
@@ -692,7 +809,7 @@ class CommitStore {
                 return plan.record;
             }
             if (plan.mode === 'replace') {
-                return this._replace(record, stagingDigest.identity, plan, retentionManager, signal);
+                return this._replace(record, stagingDigest.identity, plan, retentionManager, signal, deferPostCommitRetention);
             }
         }
         if (retentionManager) {
@@ -717,8 +834,9 @@ class CommitStore {
             await this._removeFile(this._tarStagingPath(record.transferId), this.layout.staging);
             assertNotAborted(signal);
             await this._discardJournal(record.transferId, journalAttemptId);
-            if (retentionManager)
+            if (retentionManager && !deferPostCommitRetention) {
                 await retentionManager._afterCommitUnlocked();
+            }
             return record;
         }
         catch (err) {
@@ -758,12 +876,122 @@ class CommitStore {
             throw commitError('Unable to create final artifact', err);
         }
     }
+    /**
+     * Publishes one verified staging tree by rename. Directory artifacts are
+     * create-only: a configured mutable name, an occupied destination, and a
+     * kind change are all existing-name conflicts.
+     */
+    async _commitDirectory(record, retentionManager, signal, mutable, deferPostCommitRetention = false) {
+        if (mutable.has(record.name)) {
+            throw existsError('Directory artifacts cannot be replaced');
+        }
+        const treePath = this._treeStagingPath(record.transferId);
+        const finalPath = this._finalPath(record.name);
+        if ((await (0, tree_fs_js_1.inspectTreePath)(treePath, this.layout.staging, this.storage)) !== 'DIRECTORY') {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.CHECKSUM_MISMATCH, 'Verified staging tree is missing');
+        }
+        const digested = await (0, tree_fs_js_1.digestTree)(treePath, this.storage);
+        if (digested.entryCount !== record.entryCount ||
+            digested.payloadBytes !== record.size ||
+            !(0, hash_js_1.digestMatches)(digested.treeSha256, b4a_1.default.from(record.sha256, 'hex'))) {
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.CHECKSUM_MISMATCH, 'Staging tree checksum mismatch');
+        }
+        const stagingTreeIdentity = (0, commit_journal_js_1.fileIdentity)(await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, () => this.storage.lstat(treePath)));
+        for (const existing of await this._scanRecords()) {
+            if (existing.name === record.name)
+                throw existsError('Destination already exists');
+        }
+        if ((await this._rootTreeState(record.name)) !== 'MISSING') {
+            throw existsError('Destination already exists');
+        }
+        if (retentionManager) {
+            await retentionManager._runUnlocked({ incomingBytes: record.size, trigger: 'commit' });
+        }
+        assertNotAborted(signal);
+        const attempt = attemptId();
+        let journal = {
+            version: commit_journal_js_1.DIRECTORY_JOURNAL_VERSION,
+            intent: 'create-directory',
+            state: 'committing',
+            phase: 'journaled',
+            transferId: record.transferId,
+            attemptId: attempt,
+            name: record.name,
+            stagingTreeName: `${record.transferId}.tree`,
+            stagingTreeIdentity,
+            record
+        };
+        await this._writeFreshJournal(journal);
+        let linearized = false;
+        try {
+            assertNotAborted(signal);
+            if ((await this._rootTreeState(record.name)) !== 'MISSING') {
+                throw existsError('Destination already exists');
+            }
+            await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, () => (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, () => this.storage.rename(treePath, finalPath)));
+            await this._syncRoot();
+            journal = await this._setDirectoryPhase(journal, 'renamed');
+            assertNotAborted(signal);
+            await this._writeRecord(record);
+            linearized = true;
+            journal = await this._setDirectoryPhase(journal, 'sidecar');
+            await this._removeFile(this._sessionPath(record.transferId), this.layout.sessions);
+            await this._removeFile(this._tarStagingPath(record.transferId), this.layout.staging);
+            await this._discardJournal(record.transferId, attempt);
+            if (retentionManager && !deferPostCommitRetention) {
+                await retentionManager._afterCommitUnlocked();
+            }
+            return record;
+        }
+        catch (err) {
+            if (linearized) {
+                this._reportCleanupPending(record, err);
+                return record;
+            }
+            try {
+                await this._rollbackDirectory(journal);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([err, cleanupError], 'Unable to roll back directory commit');
+            }
+            throw err;
+        }
+    }
+    async _setDirectoryPhase(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;
+    }
+    /** Returns a proven renamed tree to staging; a foreign destination is preserved. */
+    async _rollbackDirectory(journal) {
+        const finalPath = this._finalPath(journal.name);
+        const treePath = this._treeStagingPath(journal.transferId);
+        if ((await this._rootTreeState(journal.name)) !== 'DIRECTORY') {
+            if ((await (0, tree_fs_js_1.inspectTreePath)(treePath, this.layout.staging, this.storage)) === 'DIRECTORY') {
+                await this._discardJournal(journal.transferId, journal.attemptId);
+            }
+            return;
+        }
+        const visible = (0, commit_journal_js_1.fileIdentity)(await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, () => this.storage.lstat(finalPath)));
+        if (!(0, commit_journal_js_1.identitiesEqual)(visible, journal.stagingTreeIdentity)) {
+            throw storageError('Foreign artifact at directory destination');
+        }
+        if ((await (0, tree_fs_js_1.inspectTreePath)(treePath, this.layout.staging, this.storage)) !== 'MISSING') {
+            throw storageError('Directory staging tree already exists');
+        }
+        await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, () => (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.staging, this.storage, () => this.storage.rename(finalPath, treePath)));
+        await this._syncRoot();
+        await this._discardJournal(journal.transferId, journal.attemptId);
+    }
     /**
      * 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) {
+        if ((await this._rootTreeState(record.name)) === 'DIRECTORY') {
+            throw existsError('Destination already exists');
+        }
         const state = await this._rootPathState(record.name);
         if (!state.present)
             return { mode: 'create' };
@@ -773,8 +1001,14 @@ class CommitStore {
         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))
+        const sameRelease = releasesEqual(current.record.release, record.release);
+        if (current.record.transferId === record.transferId && !sameRelease) {
+            // One transfer ID names one authenticated upload; its release identity is immutable.
+            throw storageError('Release identity conflicts with the committed transfer');
+        }
+        if (sameContent(current.record, record) && sameRelease) {
             return { mode: 'idempotent', record: current.record };
+        }
         return { mode: 'replace', oldRecord: current.record, finalIdentity: current.identity };
     }
     /**
@@ -787,7 +1021,9 @@ class CommitStore {
         const existing = await this._readRecordOrAbsent(this._recordPath(record.transferId));
         if (!existing)
             return null;
-        if (existing.name !== name || !sameContent(existing, record)) {
+        if (existing.name !== name ||
+            !sameContent(existing, record) ||
+            !releasesEqual(existing.release, record.release)) {
             throw storageError('Conflicting commit record');
         }
         const state = await this._rootPathState(name);
@@ -801,7 +1037,7 @@ class CommitStore {
         }
         return { name, identity: digested.identity };
     }
-    async _replace(record, stagingIdentity, plan, retentionManager, signal) {
+    async _replace(record, stagingIdentity, plan, retentionManager, signal, deferPostCommitRetention = false) {
         const { oldRecord, finalIdentity } = plan;
         const history = (0, files_js_1.historyName)(oldRecord.transferId);
         const newRecord = (0, commit_journal_js_1.assertCommitRecord)({
@@ -846,7 +1082,7 @@ class CommitStore {
             record: newRecord
         };
         const publicationPath = this._publicationPath(journal.publicationName);
-        await this._writeReplacementJournal(journal);
+        await this._writeFreshJournal(journal);
         let linearized = false;
         try {
             assertNotAborted(signal);
@@ -881,8 +1117,9 @@ class CommitStore {
             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)
+            if (retentionManager && !deferPostCommitRetention) {
                 await retentionManager._afterCommitUnlocked();
+            }
             return newRecord;
         }
         catch (err) {
@@ -1068,6 +1305,59 @@ class CommitStore {
         await this._removeFile(this._tarStagingPath(id), this.layout.staging);
     }
     /** Proves the verified session and staging an aborted attempt must retain. */
+    /**
+     * Converges one directory attempt. The durable sidecar is the linearization
+     * point: before it a proven renamed tree returns to staging, after it the
+     * published tree is kept and only residue is removed. A destination that
+     * cannot be proven is preserved and fails closed.
+     */
+    async _recoverDirectoryJournal(id, journal, sessionStore, isAuthorized = null) {
+        const { record, name, attemptId: attempt } = journal;
+        const sidecar = await this._readRecordOrAbsent(this._recordPath(id));
+        if (sidecar && !recordsEqual(sidecar, record)) {
+            throw storageError('Commit sidecar does not match journal');
+        }
+        const state = await this._rootTreeState(name);
+        if (state === 'UNMANAGED')
+            throw storageError('Foreign artifact at directory destination');
+        if (state === 'DIRECTORY') {
+            const digested = await (0, tree_fs_js_1.digestTree)(this._finalPath(name), this.storage);
+            if (digested.entryCount !== record.entryCount ||
+                digested.payloadBytes !== record.size ||
+                !(0, hash_js_1.digestMatches)(digested.treeSha256, b4a_1.default.from(record.sha256, 'hex'))) {
+                throw storageError('Published directory does not match its journal');
+            }
+            if (!sidecar && isAuthorized) {
+                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 (!isAuthorized(session.ownerKey)) {
+                    await this._rollbackDirectory(journal);
+                    return { status: 'RESUMABLE', record };
+                }
+            }
+            if (!sidecar)
+                await this._writeRecord(record);
+            await this._removeFile(this._sessionPath(id), this.layout.sessions);
+            await this._removeFile(this._tarStagingPath(id), this.layout.staging);
+            await this._discardJournal(id, attempt);
+            return { status: 'COMMITTED', record };
+        }
+        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'));
+        this._assertSessionMatchesRecord(session, record, 'Directory journal does not match verified session');
+        const treePath = this._treeStagingPath(id);
+        if ((await (0, tree_fs_js_1.inspectTreePath)(treePath, this.layout.staging, this.storage)) !== 'DIRECTORY') {
+            throw new commit_journal_js_1.CorruptJournalError('Directory journal does not own verified staging');
+        }
+        await this._discardJournal(id, attempt);
+        return { status: 'RESUMABLE', record };
+    }
     async _assertReplacementRetryable(id, journal, sessionStore) {
         if (!sessionStore || typeof sessionStore.readVerified !== 'function') {
             throw storageError('Session store cannot validate commit journal');
@@ -1089,6 +1379,9 @@ class CommitStore {
         const journal = await this._readJournal(id);
         if (!journal)
             return { status: 'MISSING' };
+        if ((0, commit_journal_js_1.isDirectoryJournal)(journal)) {
+            return (0, root_coordinator_js_1.withNameLease)(this.layout.root, journal.name, () => this._recoverDirectoryJournal(id, journal, sessionStore, isAuthorized));
+        }
         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));
         }
@@ -1296,11 +1589,61 @@ class CommitStore {
         }
         throw storageError('Commit record changed before deletion');
     }
+    /**
+     * Removes proven private trash trees left by an interrupted deletion. Only a
+     * `<64-hex>.tree` entry is ours; anything else in the directory is left alone.
+     */
+    async sweepTrash() {
+        await this._assertLayout();
+        const names = await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.trash, this.storage, () => this.storage.readdir(this.layout.trash));
+        let removed = 0;
+        for (const name of names.sort()) {
+            if (!/^[0-9a-f]{64}\.tree$/.test(name))
+                continue;
+            if (await (0, tree_fs_js_1.removeTree)(_path_1.default.join(this.layout.trash, name), this.layout.trash, this.storage)) {
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /**
+     * Removes a managed directory by renaming it into the private trash first, so
+     * the visible name disappears atomically, and only then removing the sidecar
+     * and recursively deleting the trash tree.
+     */
+    async _removeManagedTree(record) {
+        const finalPath = this._finalPath(record.name);
+        const trashPath = this._trashTreePath(record.transferId);
+        const state = await this._rootTreeState(record.name);
+        if (state === 'MISSING')
+            return { removed: false, preservedPath: false };
+        if (state === 'UNMANAGED')
+            return { removed: false, preservedPath: true };
+        if ((await (0, tree_fs_js_1.inspectTreePath)(trashPath, this.layout.trash, this.storage)) !== 'MISSING') {
+            await (0, tree_fs_js_1.removeTree)(trashPath, this.layout.trash, this.storage);
+        }
+        await (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.root, this.storage, () => (0, layout_js_1.withSafeDirectoryIdentity)(this.layout.trash, this.storage, () => this.storage.rename(finalPath, trashPath)));
+        await this._syncRoot();
+        await this._removeFile(this._recordPath(record.transferId), this.layout.commits);
+        await (0, tree_fs_js_1.removeTree)(trashPath, this.layout.trash, this.storage);
+        return { removed: true, preservedPath: false };
+    }
     async delete(record) {
         await this._assertLayout();
         (0, commit_journal_js_1.assertCommitRecord)(record);
         if (!(await this._storedRecordFor(record)))
             return false;
+        if (record.kind === 'directory') {
+            const removed = await this._removeManagedTree(record);
+            if (removed.preservedPath) {
+                await this._removeFile(this._recordPath(record.transferId), this.layout.commits);
+                return true;
+            }
+            if (!removed.removed) {
+                await this._removeFile(this._recordPath(record.transferId), this.layout.commits);
+            }
+            return true;
+        }
         const finalPath = this._finalPath(record.name);
         const final = await this._safeFileOrAbsent(finalPath, this.layout.root);
         if (final)
@@ -1313,6 +1656,15 @@ class CommitStore {
         (0, commit_journal_js_1.assertCommitRecord)(record);
         if (!(await this._storedRecordFor(record)))
             return false;
+        if (record.kind === 'directory') {
+            if (preservePath) {
+                await this._removeFile(this._recordPath(record.transferId), this.layout.commits);
+                return { purged: true, preservedPath: true };
+            }
+            const removed = await this._removeManagedTree(record);
+            await this._removeFile(this._recordPath(record.transferId), this.layout.commits);
+            return { purged: true, preservedPath: removed.preservedPath };
+        }
         let final;
         if (preservePath) {
             let preservedPath = false;