swarm-deploy 0.1.0 → 0.3.0

package/dist/server.js

@@ -3,25 +3,35 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FINGERPRINT_LENGTH = exports.MAX_ACTIVE_UPLOADS = exports.MAX_CONNECTIONS = exports.DEFAULT_MIN_FREE_BYTES = exports.DEFAULT_MAX_ACTIVE_UPLOADS = exports.DEFAULT_MAX_CONNECTIONS = exports.Server = void 0;
+exports.FINGERPRINT_LENGTH = exports.MAX_ACTIVE_UPLOADS = exports.MAX_CONNECTIONS = exports.DEFAULT_MIN_FREE_BYTES = exports.DEFAULT_MAX_ACTIVE_UPLOADS = exports.DEFAULT_MAX_CONNECTIONS = exports.Server = exports.MAX_OWED_POST_COMMIT_RETENTION = void 0;
 exports.fingerprint = fingerprint;
 const b4a_1 = __importDefault(require("b4a"));
 const _events_1 = __importDefault(require("#events"));
 const _fs_1 = __importDefault(require("#fs"));
+const _path_1 = __importDefault(require("#path"));
 const sodium_native_1 = __importDefault(require("sodium-native"));
 const abort_js_1 = require("./abort.js");
 const direct_dht_js_1 = require("./direct-dht.js");
 const errors_js_1 = require("./errors.js");
 const files_js_1 = require("./files.js");
+const hooks_js_1 = require("./hooks.js");
 const identity_js_1 = require("./identity.js");
+const release_js_1 = require("./release.js");
 const commit_store_js_1 = require("./storage/commit-store.js");
+const link_store_js_1 = require("./storage/link-store.js");
 const layout_js_1 = require("./storage/layout.js");
+const root_coordinator_js_1 = require("./storage/root-coordinator.js");
 const recovery_js_1 = require("./storage/recovery.js");
 const retention_js_1 = require("./storage/retention.js");
 const session_store_js_1 = require("./storage/session-store.js");
+const tree_fs_js_1 = require("./storage/tree-fs.js");
+const controls_js_1 = require("./tar-protocol/controls.js");
 const direct_wire_js_1 = require("./tar-protocol/direct-wire.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 symlinks_js_1 = require("./symlinks.js");
+const commit_journal_js_1 = require("./storage/commit-journal.js");
 const EventEmitter = _events_1.default.EventEmitter;
 const DEFAULT_MAX_CONNECTIONS = 64;
 exports.DEFAULT_MAX_CONNECTIONS = DEFAULT_MAX_CONNECTIONS;
@@ -36,6 +46,15 @@ exports.MAX_ACTIVE_UPLOADS = MAX_ACTIVE_UPLOADS;
 const FINGERPRINT_LENGTH = 12;
 exports.FINGERPRINT_LENGTH = FINGERPRINT_LENGTH;
 const TAR_DURABILITY_BATCH_BYTES = 1024 * 1024;
+/**
+ * How many transfers may owe a deferred post-commit retention pass at once.
+ *
+ * The set grows only when an `afterCommit` hook fails after a durable commit,
+ * and entries are removed as soon as a retry succeeds, so reaching the bound
+ * means a persistently failing hook. Capping it at the connection ceiling
+ * keeps a broken deployment step from growing server memory without limit.
+ */
+exports.MAX_OWED_POST_COMMIT_RETENTION = MAX_CONNECTIONS;
 function fail(code, message, cause = null) {
     return new errors_js_1.SwarmDeployError(code, message, cause);
 }
@@ -91,6 +110,11 @@ class Server extends EventEmitter {
     minFreeBytes;
     maxAge;
     maxStorageBytes;
+    artifactPatterns;
+    maxCount;
+    maxVersions;
+    versionGranularity;
+    releaseMatcher;
     allowedKeySnapshot;
     logger;
     dht;
@@ -98,6 +122,11 @@ class Server extends EventEmitter {
     storage;
     scheduler;
     replaceNames;
+    hooks;
+    symlinks;
+    linkNames;
+    managedLinkNamesSnapshot;
+    links = null;
     listening = false;
     closed = false;
     keyPair;
@@ -105,6 +134,24 @@ class Server extends EventEmitter {
     abort = (0, abort_js_1.createAbortController)();
     active = new Map();
     activeUploads = new Set();
+    /**
+     * Transfer IDs this process committed but whose deferred post-commit
+     * retention is still owed because `afterCommit` has not yet succeeded. Only
+     * these may start a retention pass from an already-committed retry, so an
+     * ordinary duplicate offer cannot be used to force repeated full passes.
+     * The set is in-memory only and bounded by `MAX_OWED_POST_COMMIT_RETENTION`;
+     * a restart or an eviction loses an entry, and the documented fallback is the
+     * next startup, scheduled, or commit-triggered pass.
+     */
+    pendingAfterCommit = new Set();
+    /**
+     * Authenticated transfer IDs a connection currently owns. One connection
+     * holds at most one entry and releases it in a `finally`, so the set is
+     * bounded by `maxConnections`. A second connection offering the same
+     * transfer is rejected with `FILE_BUSY` rather than running the lifecycle
+     * and its hooks concurrently against one staging and commit identity.
+     */
+    activeTransfers = new Set();
     receives = new Set();
     layout = null;
     sessions = null;
@@ -149,6 +196,38 @@ class Server extends EventEmitter {
         }
         this.maxAge = options.maxAge;
         this.maxStorageBytes = options.maxStorageBytes;
+        const patterns = options.artifactPatterns ?? [];
+        if (typeof patterns[Symbol.iterator] !== 'function') {
+            throw fail(errors_js_1.ERRORS.PROTOCOL_INVALID, 'Invalid artifact patterns');
+        }
+        try {
+            this.artifactPatterns = Object.freeze([...patterns]);
+            this.releaseMatcher = new release_js_1.ReleaseMatcher(this.artifactPatterns);
+        }
+        catch (error) {
+            throw fail(errors_js_1.ERRORS.PROTOCOL_INVALID, 'Invalid artifact patterns', error);
+        }
+        if (options.maxCount !== undefined) {
+            positive(options.maxCount, 'maxCount');
+            if (this.releaseMatcher.size === 0) {
+                throw fail(errors_js_1.ERRORS.PROTOCOL_INVALID, 'maxCount requires artifact patterns');
+            }
+        }
+        if (options.maxVersions !== undefined) {
+            positive(options.maxVersions, 'maxVersions');
+            if (!this.releaseMatcher.hasVersionPattern) {
+                throw fail(errors_js_1.ERRORS.PROTOCOL_INVALID, 'maxVersions requires a {version} artifact pattern');
+            }
+            if (options.versionGranularity !== 'major' && options.versionGranularity !== 'minor') {
+                throw fail(errors_js_1.ERRORS.PROTOCOL_INVALID, 'Invalid versionGranularity');
+            }
+        }
+        else if (options.versionGranularity !== undefined) {
+            throw fail(errors_js_1.ERRORS.PROTOCOL_INVALID, 'versionGranularity requires maxVersions');
+        }
+        this.maxCount = options.maxCount;
+        this.maxVersions = options.maxVersions;
+        this.versionGranularity = options.versionGranularity;
         const allow = [];
         if (!options.allowedKeys ||
             typeof options.allowedKeys[Symbol.iterator] !== 'function') {
@@ -167,9 +246,24 @@ class Server extends EventEmitter {
         this.storage = options.storage || _fs_1.default.promises;
         this.scheduler = options.scheduler || { setTimeout, clearTimeout, setInterval, clearInterval };
         this.replaceNames = (0, files_js_1.validateReplaceNames)(options.replaceNames);
+        this.hooks = (0, hooks_js_1.snapshotHooks)(options.hooks);
+        this.symlinks = (0, symlinks_js_1.compileSymlinkRules)(options.symlinks);
+        this.linkNames = (0, symlinks_js_1.symlinkRuleNames)(this.symlinks);
+        this.managedLinkNamesSnapshot = new Set(this.linkNames);
+        if (this.symlinks.length > 0)
+            (0, tree_fs_js_1.assertSymlinkCapable)(this.storage);
         this.logger = safeLogger(options.logger);
         this.signal = this.abort.signal;
     }
+    artifactKind(metadata) {
+        return (0, controls_js_1.isTreeMetadata)(metadata) ? 'directory' : 'file';
+    }
+    payloadBytes(metadata) {
+        return (0, controls_js_1.isTreeMetadata)(metadata) ? metadata.payloadBytes : metadata.fileSize;
+    }
+    payloadDigest(metadata) {
+        return (0, controls_js_1.isTreeMetadata)(metadata) ? metadata.treeSha256 : metadata.fileSha256;
+    }
     emitSafe(type, payload) {
         try {
             this.emit(type, payload);
@@ -189,8 +283,220 @@ class Server extends EventEmitter {
         return {
             transfer: fingerprint(b4a_1.default.from(metadata.transferId, 'hex')),
             name: metadata.name,
-            size: metadata.fileSize
+            kind: this.artifactKind(metadata),
+            size: this.payloadBytes(metadata)
+        };
+    }
+    async rejectOffer(socket, event, owner, reason) {
+        await (0, direct_wire_js_1.writeAdmission)(socket, { v: 1, status: 'REJECTED', code: reason }, { signal: this.signal, timeout: this.idleTimeout });
+        this.emitSafe('offer', {
+            ...event,
+            fingerprint: fingerprint(owner),
+            status: 'rejected',
+            reason
+        });
+    }
+    hookArtifact(metadata, release) {
+        return Object.freeze({
+            name: metadata.name,
+            kind: this.artifactKind(metadata),
+            size: this.payloadBytes(metadata),
+            sha256: this.payloadDigest(metadata),
+            transferId: metadata.transferId,
+            ...((0, controls_js_1.isTreeMetadata)(metadata) ? { entryCount: metadata.entryCount } : {}),
+            ...(metadata.sourceParent === undefined ? {} : { sourceParent: metadata.sourceParent }),
+            ...(release === null
+                ? {}
+                : {
+                    release: Object.freeze({
+                        series: release.series,
+                        ...(release.version === undefined ? {} : { version: release.version })
+                    })
+                })
+        });
+    }
+    /**
+     * Computes and converges the desired links from durable commit records.
+     * Called with the root lease already held.
+     */
+    async reconcileLinksUnlocked(records) {
+        const desired = (0, symlinks_js_1.selectDesiredLinks)(this.symlinks, records);
+        if (!this.links)
+            return new Set(desired.map((link) => link.transferId));
+        await this.links.reconcile(desired, this.linkNames, {
+            managedArtifactNames: new Set(records.map((record) => record.name))
+        });
+        const ledger = await this.links.list();
+        this.setManagedLinkNames(ledger);
+        const pins = new Set(desired.map((link) => link.transferId));
+        for (const link of ledger) {
+            if (link.mode !== 'manual')
+                continue;
+            const target = records.find((record) => record.name === link.target);
+            if (target)
+                pins.add(target.transferId);
+            else
+                pins.add(link.transferId);
+        }
+        return pins;
+    }
+    /** Pins link targets when reconciliation fails but retention must continue. */
+    async linkPinsFallbackUnlocked(records) {
+        const pins = new Set((0, symlinks_js_1.selectDesiredLinks)(this.symlinks, records).map((link) => link.transferId));
+        if (!this.links)
+            return pins;
+        for (const ledger of await this.links.list()) {
+            pins.add(ledger.transferId);
+            const target = records.find((record) => record.name === ledger.target);
+            if (target)
+                pins.add(target.transferId);
+        }
+        return pins;
+    }
+    /** Reconciles after a durable commit; this is the only caller that leases the root. */
+    async reconcileAfterCommit() {
+        if (!this.links || !this.commits)
+            return;
+        try {
+            await (0, root_coordinator_js_1.withRootLease)(this.layout.root, async () => this.reconcileLinksUnlocked(await this.commits.list()));
+        }
+        catch (error) {
+            if (error instanceof errors_js_1.SwarmDeployError && error.code === errors_js_1.ERRORS.LINK_CONFLICT)
+                throw error;
+            throw new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.LINK_FAILED, 'Unable to reconcile managed symlinks', error);
+        }
+    }
+    setManagedLinkNames(records) {
+        this.managedLinkNamesSnapshot = new Set([
+            ...this.linkNames,
+            ...records.map((record) => record.name)
+        ]);
+    }
+    async refreshManagedLinkNames() {
+        if (!this.links) {
+            this.managedLinkNamesSnapshot = new Set(this.linkNames);
+            return;
+        }
+        this.setManagedLinkNames(await this.links.list());
+    }
+    async receiveLink(socket, reader, owner, request) {
+        let emitted = false;
+        let resultWriteStarted = false;
+        const emitTerminal = (status, reason) => {
+            if (emitted)
+                return;
+            emitted = true;
+            this.emitSafe('link', {
+                fingerprint: fingerprint(owner),
+                target: request.target,
+                name: request.name,
+                status,
+                ...(reason === undefined ? {} : { reason })
+            });
         };
+        try {
+            // A link request has no payload: EOF is the required no-trailing-data boundary.
+            await reader.requireEnd(this.signal, this.idleTimeout);
+            if (request.target === request.name) {
+                throw fail(errors_js_1.ERRORS.LINK_NOT_ALLOWED, 'Manual link cannot target itself');
+            }
+            if (!(0, symlinks_js_1.isManualSymlinkTargetAllowed)(this.symlinks, request.target)) {
+                throw fail(errors_js_1.ERRORS.LINK_NOT_ALLOWED, 'Manual link target is not allowed');
+            }
+            if (this.linkNames.has(request.name)) {
+                throw fail(errors_js_1.ERRORS.LINK_NOT_ALLOWED, 'Manual link name is reserved by an automatic rule');
+            }
+            const result = await (0, root_coordinator_js_1.withRootLease)(this.layout.root, async () => {
+                const records = await this.commits.list();
+                const target = records.find((record) => record.name === request.target && !(0, files_js_1.isReservedHistoryName)(record.name));
+                if (!target)
+                    throw fail(errors_js_1.ERRORS.LINK_TARGET_NOT_FOUND, 'Manual link target was not found');
+                const artifacts = new Set(records.map((record) => record.name));
+                if (artifacts.has(request.name)) {
+                    throw fail(errors_js_1.ERRORS.LINK_CONFLICT, 'Manual link name conflicts with an artifact');
+                }
+                if (!this.links)
+                    throw fail(errors_js_1.ERRORS.LINK_FAILED, 'Managed link storage is unavailable');
+                const link = {
+                    name: request.name,
+                    target: target.name,
+                    transferId: target.transferId,
+                    targetKind: (0, commit_journal_js_1.commitRecordKind)(target)
+                };
+                const linked = await this.links.linkManual(link, {
+                    managedArtifactNames: artifacts,
+                    automaticLinkNames: this.linkNames
+                });
+                await this.refreshManagedLinkNames();
+                return linked;
+            });
+            resultWriteStarted = true;
+            await (0, direct_wire_js_1.writeLinkResult)(socket, { v: 1, status: result.status }, { signal: this.signal, timeout: this.idleTimeout });
+            emitTerminal(result.status === 'LINKED' ? 'linked' : 'unchanged');
+        }
+        catch (error) {
+            let reason = error instanceof errors_js_1.SwarmDeployError &&
+                (error.code === errors_js_1.ERRORS.LINK_NOT_ALLOWED ||
+                    error.code === errors_js_1.ERRORS.LINK_TARGET_NOT_FOUND ||
+                    error.code === errors_js_1.ERRORS.LINK_CONFLICT ||
+                    error.code === errors_js_1.ERRORS.LINK_FAILED)
+                ? error.code
+                : errors_js_1.ERRORS.LINK_FAILED;
+            const rejected = reason === errors_js_1.ERRORS.LINK_NOT_ALLOWED ||
+                reason === errors_js_1.ERRORS.LINK_TARGET_NOT_FOUND ||
+                reason === errors_js_1.ERRORS.LINK_CONFLICT;
+            if (!resultWriteStarted) {
+                resultWriteStarted = true;
+                try {
+                    await (0, direct_wire_js_1.writeLinkResult)(socket, { v: 1, status: 'FAILED', code: reason }, { timeout: this.idleTimeout });
+                }
+                catch {
+                    reason = errors_js_1.ERRORS.LINK_FAILED;
+                }
+            }
+            else {
+                reason = errors_js_1.ERRORS.LINK_FAILED;
+            }
+            this.logger.warn('Direct link failed', { fingerprint: fingerprint(owner), reason });
+            this.emitSafe('failure', { fingerprint: fingerprint(owner), reason });
+            emitTerminal(rejected && reason !== errors_js_1.ERRORS.LINK_FAILED ? 'rejected' : 'failed', reason);
+            try {
+                socket.destroy();
+            }
+            catch { }
+        }
+    }
+    /** Runs a gating callback; only callback exceptions become HOOK_FAILED. */
+    async runHook(phase, hook, context) {
+        if (hook === undefined)
+            return;
+        (0, abort_js_1.throwIfAborted)(this.signal);
+        let outcome;
+        try {
+            outcome = await (0, hooks_js_1.invokeHook)(hook, context, this.signal);
+        }
+        catch (cause) {
+            throw (0, hooks_js_1.hookError)(phase, cause);
+        }
+        if (outcome === 'aborted')
+            throw (0, abort_js_1.abortError)();
+    }
+    /** Runs onFailure once; its own failure is logged and never replaces the original. */
+    async runFailureHook(context, owner, transfer) {
+        const hook = this.hooks.onFailure;
+        if (hook === undefined)
+            return;
+        try {
+            await (0, hooks_js_1.invokeHook)(hook, context, this.signal);
+        }
+        catch {
+            this.logger.warn('Failure hook failed', {
+                fingerprint: owner ? fingerprint(owner) : 'invalid',
+                transfer,
+                phase: context.phase,
+                reason: errors_js_1.ERRORS.HOOK_FAILED
+            });
+        }
     }
     async receive(socket) {
         const owner = socket.remotePublicKey;
@@ -231,30 +537,160 @@ class Server extends EventEmitter {
         let verificationSucceeded = false;
         let commitStarted = false;
         let commitSucceeded = false;
+        let artifact = null;
+        let phase = 'offer';
+        let hookPath = null;
+        let resumed = false;
+        let alreadyCommitted = false;
+        let hooksFinished = false;
+        let finalStarted = false;
+        let failureReported = false;
+        let guardedTransfer = null;
+        /**
+         * Hands the transfer back before this connection's last await. Clearing
+         * `guardedTransfer` makes the `finally` a no-op, so a late release can
+         * never take ownership away from the connection that acquired it next.
+         */
+        const releaseTransfer = () => {
+            if (guardedTransfer === null)
+                return;
+            this.activeTransfers.delete(guardedTransfer);
+            guardedTransfer = null;
+        };
+        // Runs onFailure at most once per connection, after the client was answered.
+        const reportFailure = async (error) => {
+            if (failureReported || !event || !artifact)
+                return;
+            failureReported = true;
+            // The guard serializes the commit lifecycle, and this connection has
+            // finished its own. `onFailure` only observes, so holding the transfer
+            // across a slow callback would reject the client's legitimate retry.
+            releaseTransfer();
+            await this.runFailureHook(Object.freeze({ artifact, path: hookPath, phase, resumed, alreadyCommitted, error }), owner, event.transfer);
+        };
+        const rejectEarly = async (reason, message) => {
+            await this.rejectOffer(socket, event, owner, reason);
+            sentAdmission = true;
+            await reportFailure(fail(reason, message));
+        };
         try {
-            const metadata = await reader.control(direct_wire_js_1.decodeDirectMetadata, this.signal, this.idleTimeout);
-            (0, manifest_js_1.assertMetadataTransferId)(owner, metadata);
+            const first = await reader.control(controls_js_1.decodeFirstControlRecord, this.signal, this.idleTimeout);
+            if ('kind' in first && first.kind === 'link') {
+                await this.receiveLink(socket, reader, owner, first);
+                return;
+            }
+            const metadata = first;
+            // The decoded record is shape-validated but not yet authenticated; the
+            // artifact context carries only its non-secret descriptive fields.
             event = this.transfer(metadata);
-            if (metadata.fileSize > this.maxFileBytes ||
-                this.activeUploads.size >= this.maxActiveUploads) {
-                const reason = metadata.fileSize > this.maxFileBytes ? errors_js_1.ERRORS.FILE_TOO_LARGE : errors_js_1.ERRORS.ACTIVE_UPLOAD_LIMIT;
-                await (0, direct_wire_js_1.writeAdmission)(socket, { v: 1, status: 'REJECTED', code: reason }, { signal: this.signal, timeout: this.idleTimeout });
-                sentAdmission = true;
-                this.emitSafe('offer', {
+            artifact = this.hookArtifact(metadata, null);
+            if ((0, controls_js_1.isTreeMetadata)(metadata))
+                (0, tree_manifest_js_1.assertTreeMetadataTransferId)(owner, metadata);
+            else
+                (0, manifest_js_1.assertMetadataTransferId)(owner, metadata);
+            // The transfer ID is authenticated from here on, so it is safe to key
+            // the single-owner guard on it.
+            if (this.activeTransfers.has(metadata.transferId)) {
+                await rejectEarly(errors_js_1.ERRORS.FILE_BUSY, 'Transfer is already in progress');
+                return;
+            }
+            this.activeTransfers.add(metadata.transferId);
+            guardedTransfer = metadata.transferId;
+            let release = null;
+            if (this.releaseMatcher.size > 0) {
+                release = this.releaseMatcher.match(metadata.name, metadata.sourceParent);
+                if (release === null) {
+                    await rejectEarly(errors_js_1.ERRORS.INVALID_FILENAME, 'Artifact name does not match a configured pattern');
+                    return;
+                }
+                artifact = this.hookArtifact(metadata, release);
+            }
+            if (this.managedLinkNamesSnapshot.has(metadata.name)) {
+                await rejectEarly(errors_js_1.ERRORS.INVALID_FILENAME, 'Artifact name is a configured symlink name');
+                return;
+            }
+            const hookArtifact = artifact;
+            const stagingHookPath = (0, controls_js_1.isTreeMetadata)(metadata)
+                ? _path_1.default.join(this.layout.staging, `${metadata.transferId}.tree`)
+                : _path_1.default.join(this.layout.staging, `${metadata.transferId}.part`);
+            const finish = async (verified) => {
+                phase = 'beforeCommit';
+                hookPath = stagingHookPath;
+                await this.runHook('beforeCommit', this.hooks.beforeCommit, Object.freeze({
+                    artifact: hookArtifact,
+                    path: hookPath,
+                    resumed,
+                    alreadyCommitted: false
+                }));
+                phase = 'commit';
+                commitStarted = true;
+                await this.commits.commit(verified, {
+                    retentionManager: this.retention,
+                    signal: this.signal,
+                    replaceNames: this.replaceNames,
+                    release,
+                    deferPostCommitRetention: this.hooks.afterCommit !== undefined
+                });
+                this.emitSafe('commit', {
                     ...event,
                     fingerprint: fingerprint(owner),
-                    status: 'rejected',
-                    reason
+                    status: 'succeeded'
                 });
+                commitSucceeded = true;
+                hookPath = _path_1.default.join(this.layout.root, metadata.name);
+                await this.retireQuietly(verified.transferId, owner);
+                await this.reconcileAfterCommit();
+                phase = 'afterCommit';
+                if (this.hooks.afterCommit !== undefined) {
+                    this.owePostCommitRetention(metadata.transferId);
+                }
+                await this.runHook('afterCommit', this.hooks.afterCommit, Object.freeze({
+                    artifact: hookArtifact,
+                    path: hookPath,
+                    resumed,
+                    alreadyCommitted: false
+                }));
+                hooksFinished = true;
+                await this.settleDeferredRetention(metadata.transferId, owner);
+                finalStarted = true;
+                await (0, direct_wire_js_1.writeFinal)(socket, { v: 1, status: 'COMMITTED' }, { signal: this.signal, timeout: this.idleTimeout });
+            };
+            const payloadBytes = this.payloadBytes(metadata);
+            if (payloadBytes > this.maxFileBytes || this.activeUploads.size >= this.maxActiveUploads) {
+                if (payloadBytes > this.maxFileBytes) {
+                    await rejectEarly(errors_js_1.ERRORS.FILE_TOO_LARGE, 'File exceeds the maximum size');
+                }
+                else {
+                    await rejectEarly(errors_js_1.ERRORS.ACTIVE_UPLOAD_LIMIT, 'Active upload capacity exceeded');
+                }
                 return;
             }
             const inspected = await this.commits.inspect(metadata.name, {
                 name: metadata.name,
-                size: metadata.fileSize,
-                digest: b4a_1.default.from(metadata.fileSha256, 'hex'),
-                transferId: b4a_1.default.from(metadata.transferId, 'hex')
+                kind: this.artifactKind(metadata),
+                size: payloadBytes,
+                digest: b4a_1.default.from(this.payloadDigest(metadata), 'hex'),
+                ...((0, controls_js_1.isTreeMetadata)(metadata) ? { entryCount: metadata.entryCount } : {}),
+                transferId: b4a_1.default.from(metadata.transferId, 'hex'),
+                release
             }, { replaceNames: this.replaceNames });
             if (inspected.status === 'ALREADY_COMMITTED') {
+                alreadyCommitted = true;
+                hookPath = _path_1.default.join(this.layout.root, metadata.name);
+                await this.reconcileAfterCommit();
+                phase = 'afterCommit';
+                await this.runHook('afterCommit', this.hooks.afterCommit, Object.freeze({
+                    artifact: hookArtifact,
+                    path: hookPath,
+                    resumed: false,
+                    alreadyCommitted: true
+                }));
+                hooksFinished = true;
+                // Only a transfer this process committed can still owe a deferred
+                // pass; an ordinary duplicate offer never starts one.
+                if (this.pendingAfterCommit.has(metadata.transferId)) {
+                    await this.settleDeferredRetention(metadata.transferId, owner);
+                }
                 await (0, direct_wire_js_1.writeAdmission)(socket, { v: 1, status: 'ALREADY_COMMITTED' }, { signal: this.signal, timeout: this.idleTimeout });
                 sentAdmission = true;
                 this.emitSafe('offer', {
@@ -265,25 +701,22 @@ class Server extends EventEmitter {
                 return;
             }
             if (inspected.status === 'FILE_EXISTS') {
-                throw fail(errors_js_1.ERRORS.FILE_EXISTS, 'Destination already exists');
+                await rejectEarly(errors_js_1.ERRORS.FILE_EXISTS, 'Destination already exists');
+                return;
             }
             if (this.activeUploads.size >= this.maxActiveUploads) {
-                await (0, direct_wire_js_1.writeAdmission)(socket, { v: 1, status: 'REJECTED', code: errors_js_1.ERRORS.ACTIVE_UPLOAD_LIMIT }, { signal: this.signal, timeout: this.idleTimeout });
-                sentAdmission = true;
-                this.emitSafe('offer', {
-                    ...event,
-                    fingerprint: fingerprint(owner),
-                    status: 'rejected',
-                    reason: errors_js_1.ERRORS.ACTIVE_UPLOAD_LIMIT
-                });
+                await rejectEarly(errors_js_1.ERRORS.ACTIVE_UPLOAD_LIMIT, 'Active upload capacity exceeded');
                 return;
             }
             this.activeUploads.add(socket);
             const admission = await this.sessions.admit(owner, metadata);
             current.transfer = metadata.transferId;
+            resumed = admission.status !== 'ACCEPT';
             if (admission.status === 'VERIFIED') {
                 await (0, direct_wire_js_1.writeAdmission)(socket, { v: 1, status: 'VERIFIED' }, { signal: this.signal, timeout: this.idleTimeout });
                 sentAdmission = true;
+                phase = 'verification';
+                hookPath = stagingHookPath;
                 this.emitSafe('verification', {
                     ...event,
                     fingerprint: fingerprint(owner),
@@ -297,20 +730,7 @@ class Server extends EventEmitter {
                     status: 'succeeded'
                 });
                 verificationSucceeded = true;
-                commitStarted = true;
-                await this.commits.commit(verified, {
-                    retentionManager: this.retention,
-                    signal: this.signal,
-                    replaceNames: this.replaceNames
-                });
-                this.emitSafe('commit', {
-                    ...event,
-                    fingerprint: fingerprint(owner),
-                    status: 'succeeded'
-                });
-                commitSucceeded = true;
-                await this.retireQuietly(b4a_1.default.from(metadata.transferId, 'hex'), owner);
-                await (0, direct_wire_js_1.writeFinal)(socket, { v: 1, status: 'COMMITTED' }, { signal: this.signal, timeout: this.idleTimeout });
+                await finish(verified);
                 return;
             }
             await (0, direct_wire_js_1.writeAdmission)(socket, admission.status === 'ACCEPT'
@@ -322,6 +742,8 @@ class Server extends EventEmitter {
                     prefixSha256: b4a_1.default.toString(admission.prefixSha256, 'hex')
                 }, { signal: this.signal, timeout: this.idleTimeout });
             sentAdmission = true;
+            phase = 'transfer';
+            hookPath = _path_1.default.join(this.layout.staging, `${metadata.transferId}.tar.part`);
             this.emitSafe('offer', {
                 ...event,
                 fingerprint: fingerprint(owner),
@@ -360,6 +782,7 @@ class Server extends EventEmitter {
             }, this.signal, this.idleTimeout);
             await flush();
             await reader.requireEnd(this.signal, this.idleTimeout);
+            phase = 'verification';
             this.emitSafe('verification', {
                 ...event,
                 fingerprint: fingerprint(owner),
@@ -373,20 +796,7 @@ class Server extends EventEmitter {
                 status: 'succeeded'
             });
             verificationSucceeded = true;
-            commitStarted = true;
-            await this.commits.commit(verified, {
-                retentionManager: this.retention,
-                signal: this.signal,
-                replaceNames: this.replaceNames
-            });
-            this.emitSafe('commit', {
-                ...event,
-                fingerprint: fingerprint(owner),
-                status: 'succeeded'
-            });
-            commitSucceeded = true;
-            await this.retireQuietly(verified.transferId, owner);
-            await (0, direct_wire_js_1.writeFinal)(socket, { v: 1, status: 'COMMITTED' }, { signal: this.signal, timeout: this.idleTimeout });
+            await finish(verified);
         }
         catch (error) {
             const reason = codeOf(error);
@@ -415,7 +825,7 @@ class Server extends EventEmitter {
                 if (!sentAdmission) {
                     await (0, direct_wire_js_1.writeAdmission)(socket, { v: 1, status: 'REJECTED', code: reason }, { timeout: this.idleTimeout });
                 }
-                else if (!commitSucceeded) {
+                else if (!finalStarted) {
                     await (0, direct_wire_js_1.writeFinal)(socket, { v: 1, status: 'FAILED', code: reason }, { timeout: this.idleTimeout });
                 }
             }
@@ -424,12 +834,59 @@ class Server extends EventEmitter {
                 socket.destroy();
             }
             catch { }
+            this.activeUploads.delete(socket);
+            if (!hooksFinished)
+                await reportFailure((0, hooks_js_1.callbackError)(error));
         }
         finally {
             this.activeUploads.delete(socket);
+            releaseTransfer();
             reader.closeReader();
         }
     }
+    /**
+     * Records that a transfer still owes its deferred post-commit retention
+     * pass, keeping at most `MAX_OWED_POST_COMMIT_RETENTION` entries.
+     *
+     * `Set` preserves insertion order, so the oldest owed transfer is evicted
+     * first and eviction is deterministic. An evicted transfer loses nothing
+     * durable: its artifact is already committed and its rotation falls back to
+     * the next startup, scheduled, or commit-triggered pass.
+     */
+    owePostCommitRetention(transferId) {
+        if (this.pendingAfterCommit.has(transferId))
+            return;
+        if (this.pendingAfterCommit.size >= exports.MAX_OWED_POST_COMMIT_RETENTION) {
+            const oldest = this.pendingAfterCommit.values().next();
+            if (!oldest.done)
+                this.pendingAfterCommit.delete(oldest.value);
+        }
+        this.pendingAfterCommit.add(transferId);
+    }
+    /**
+     * Runs the post-commit retention pass that a configured `afterCommit` hook
+     * deferred, only after that hook succeeded, and then stops owing it. The
+     * retention manager already reports its own failures as non-fatal, so
+     * nothing here can fail the upload; the pass is attempted exactly once per
+     * successful hook, which is why the transfer is cleared either way.
+     */
+    async settleDeferredRetention(transferId, owner) {
+        if (this.hooks.afterCommit === undefined)
+            return;
+        try {
+            if (this.retention)
+                await this.retention.afterCommit();
+        }
+        catch (error) {
+            this.logger.warn('Post-commit retention failed', {
+                fingerprint: owner ? fingerprint(owner) : 'invalid',
+                reason: codeOf(error)
+            });
+        }
+        finally {
+            this.pendingAfterCommit.delete(transferId);
+        }
+    }
     /**
      * Retires a committed session without letting cleanup undo a durable commit.
      *
@@ -466,6 +923,13 @@ class Server extends EventEmitter {
                 storage: this.storage,
                 logger: this.logger
             });
+            if (this.symlinks.length > 0 ||
+                (typeof this.storage.symlink === 'function' && typeof this.storage.readlink === 'function')) {
+                this.links = new link_store_js_1.LinkStore({
+                    layout: this.layout,
+                    storage: this.storage
+                });
+            }
             this.emitSafe('recovery', { status: 'started' });
             await (0, recovery_js_1.prepareStorageRecovery)({
                 layout: this.layout,
@@ -496,6 +960,9 @@ class Server extends EventEmitter {
                 sessionStore: this.sessions,
                 commitStore: this.commits,
                 maxAge: this.maxAge,
+                maxCount: this.maxCount,
+                maxVersions: this.maxVersions,
+                versionGranularity: this.versionGranularity,
                 maxStorageBytes: this.maxStorageBytes,
                 resumeTtl: this.resumeTtl,
                 cleanupInterval: this.cleanupInterval,
@@ -504,9 +971,13 @@ class Server extends EventEmitter {
                 isSessionActive: (session) => [...this.active.values()].some((active) => active.transfer === session.id),
                 hasActiveUploads: () => this.activeUploads.size > 0,
                 isPinned: (record) => this.replaceNames.has(record.name),
+                managedLinkNames: () => this.managedLinkNamesSnapshot,
+                reconcileLinks: (records) => this.reconcileLinksUnlocked(records),
+                linkPinsFallback: (records) => this.linkPinsFallbackUnlocked(records),
                 logger: this.logger,
                 onEvent: ({ type, ...event }) => this.emitSafe(type, event)
             });
+            await this.refreshManagedLinkNames();
             await this.retention.start();
             (0, abort_js_1.throwIfAborted)(this.signal);
             this.transport = new direct_dht_js_1.DirectDhtServer({
@@ -550,8 +1021,11 @@ class Server extends EventEmitter {
         this.transport = null;
         await Promise.allSettled([...this.receives]);
         this.active.clear();
+        this.activeTransfers.clear();
+        this.pendingAfterCommit.clear();
         await this.retention?.stop().catch(() => { });
         this.retention = null;
+        this.links = null;
         await this.sessions?.close().catch(() => { });
         this.sessions = null;
         if (this.releaseLock)