swarm-deploy 0.1.0 → 0.3.0

package/dist/storage/commit-store.d.ts

@@ -1,5 +1,7 @@
+import type { ReleaseCoordinates } from '../release.js';
 import { CorruptJournalError, COMMIT_VERSION, MAX_COMMIT_METADATA_BYTES } from './commit-journal.js';
-import type { AnyCommitJournal, CommitJournal, CommitRecord, FileIdentity, ReplacementJournal, ReplacementPhase } from './commit-journal.js';
+import type { AnyCommitJournal, CommitJournal, CommitRecord, CommitRelease, FileIdentity, DirectoryCommitJournal, DirectoryPhase, ReplacementJournal, ReplacementPhase } from './commit-journal.js';
+import { type TreePathState } from './tree-fs.js';
 import type { StorageAdapter, StorageLayout, StorageStat } from './types.js';
 interface AbortSignalLike {
     aborted: boolean;
@@ -8,9 +10,12 @@ interface CommitSession {
     id: string;
     transferId: Uint8Array;
     ownerKey: Uint8Array;
+    kind?: 'file' | 'directory';
     name: string;
+    sourceParent?: string;
     size: number;
     digest: Uint8Array;
+    entryCount?: number;
     /** Direct-TAR sessions carry these immutable archive fields. */
     tarSize: number;
     tarDigest: Uint8Array;
@@ -18,9 +23,13 @@ interface CommitSession {
 }
 interface CommitOffer {
     name: string;
+    kind?: 'file' | 'directory';
     size: number;
     digest: Uint8Array;
+    entryCount?: number;
     transferId: Uint8Array;
+    /** Matched release identity; transfer and release must agree for an idempotent result. */
+    release?: ReleaseCoordinates | null;
 }
 interface RetentionManager {
     run(options?: {
@@ -78,6 +87,10 @@ declare class CommitStore {
     constructor({ layout, clock, storage, logger }: CommitStoreOptions);
     _stagingPath(id: string): string;
     _tarStagingPath(id: string): string;
+    _treeStagingPath(id: string): string;
+    _trashTreePath(id: string): string;
+    /** The visible state of one top-level directory path, without following links. */
+    _rootTreeState(name: string): Promise<TreePathState>;
     _sessionPath(id: string): string;
     _journalPath(id: string): string;
     _recordPath(id: string): string;
@@ -99,8 +112,8 @@ declare class CommitStore {
     }>;
     _linkJournal(id: string, journal: AnyCommitJournal, attempt: string): Promise<void>;
     _writeJournal(record: CommitRecord, sourceStagingIdentity: FileIdentity): Promise<string>;
-    /** A replacement always starts a fresh attempt; leftovers belong to recovery. */
-    _writeReplacementJournal(journal: ReplacementJournal): Promise<void>;
+    /** A replacement or directory commit always starts a fresh attempt; leftovers belong to recovery. */
+    _writeFreshJournal(journal: ReplacementJournal | DirectoryCommitJournal): Promise<void>;
     /**
      * Records the boundary an attempt has already passed. The observable
      * filesystem state stays authoritative during recovery; the phase is the
@@ -120,7 +133,7 @@ declare class CommitStore {
     _abortAttempt(record: CommitRecord, expectedIdentity: FileIdentity, attemptId: string, aborted: unknown): Promise<never>;
     _removeOwnedFile(filePath: string, directory: string, identity: FileIdentity): Promise<boolean>;
     _matchesRecord(filePath: string, directory: string, record: CommitRecord, syncFirst?: boolean): Promise<boolean>;
-    _recordFromSession(session: CommitSession): CommitRecord;
+    _recordFromSession(session: CommitSession, release?: CommitRelease): CommitRecord;
     inspect(name: string, offer: CommitOffer, { replaceNames }?: ReplacePolicy): Promise<{
         status: 'AVAILABLE';
     } | {
@@ -132,7 +145,7 @@ declare class CommitStore {
     } | {
         status: 'FILE_EXISTS';
     }>;
-    _inspect(name: string, offer: CommitOffer, mutable: Set<string>): Promise<{
+    _inspect(name: string, offer: CommitOffer, mutable: Set<string>, release: CommitRelease | undefined): Promise<{
         status: 'AVAILABLE';
     } | {
         status: 'ALREADY_COMMITTED';
@@ -143,6 +156,14 @@ declare class CommitStore {
     } | {
         status: 'FILE_EXISTS';
     }>;
+    _inspectDirectory(name: string, offer: CommitOffer): Promise<{
+        status: 'AVAILABLE';
+    } | {
+        status: 'ALREADY_COMMITTED';
+        record: CommitRecord;
+    } | {
+        status: 'FILE_EXISTS';
+    }>;
     /** The managed record whose verified content currently owns a visible name. */
     _managedCurrent(name: string): Promise<{
         record: CommitRecord;
@@ -153,12 +174,28 @@ declare class CommitStore {
         sessionFile: StorageStat | null;
         staging: StorageStat | null;
     }>;
-    commit(session: CommitSession, { retentionManager, signal, replaceNames }?: {
+    commit(session: CommitSession, { retentionManager, signal, replaceNames, release, deferPostCommitRetention }?: {
         retentionManager?: RetentionManager | null;
         signal?: AbortSignalLike | null;
         replaceNames?: Iterable<string>;
+        release?: ReleaseCoordinates | null;
+        /**
+         * Skips the post-commit retention pass so the caller can run it later
+         * (via the retention manager) once work that needs the committed files
+         * has finished. Pre-commit quota and age checks still run.
+         */
+        deferPostCommitRetention?: boolean;
     }): Promise<CommitRecord>;
-    _commit(session: CommitSession, retentionManager: RetentionManager | null, signal: AbortSignalLike | null, mutable?: Set<string>): Promise<CommitRecord>;
+    _commit(session: CommitSession, retentionManager: RetentionManager | null, signal: AbortSignalLike | null, mutable?: Set<string>, release?: CommitRelease, deferPostCommitRetention?: boolean): Promise<CommitRecord>;
+    /**
+     * 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.
+     */
+    _commitDirectory(record: CommitRecord, retentionManager: RetentionManager | null, signal: AbortSignalLike | null, mutable: Set<string>, deferPostCommitRetention?: boolean): Promise<CommitRecord>;
+    _setDirectoryPhase(journal: DirectoryCommitJournal, phase: DirectoryPhase): Promise<DirectoryCommitJournal>;
+    /** Returns a proven renamed tree to staging; a foreign destination is preserved. */
+    _rollbackDirectory(journal: DirectoryCommitJournal): Promise<void>;
     /**
      * Classifies a configured mutable name. Only an exact managed current record
      * whose verified content owns the visible path may be replaced; every other
@@ -177,7 +214,7 @@ declare class CommitStore {
     _replace(record: CommitRecord, stagingIdentity: FileIdentity, plan: {
         oldRecord: CommitRecord;
         finalIdentity: FileIdentity;
-    }, retentionManager: RetentionManager | null, signal: AbortSignalLike | null): Promise<CommitRecord>;
+    }, retentionManager: RetentionManager | null, signal: AbortSignalLike | null, deferPostCommitRetention?: boolean): Promise<CommitRecord>;
     /**
      * Restores the exact pinned old inode at the mutable name and removes only
      * transaction-owned history, publication, and sidecar paths. A foreign
@@ -210,6 +247,16 @@ declare class CommitStore {
     _repairHistorySidecar(journal: ReplacementJournal): Promise<void>;
     _cleanupReplacementLeftovers(id: string, journal: ReplacementJournal, sessionStore: SessionStore | null): Promise<void>;
     /** 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.
+     */
+    _recoverDirectoryJournal(id: string, journal: DirectoryCommitJournal, sessionStore: SessionStore, isAuthorized?: ((ownerKey: Uint8Array) => boolean) | null): Promise<{
+        status: 'COMMITTED' | 'RESUMABLE';
+        record: CommitRecord;
+    }>;
     _assertReplacementRetryable(id: string, journal: ReplacementJournal, sessionStore: SessionStore | null): Promise<boolean>;
     recoverJournal(id: string, sessionStore: SessionStore, { isAuthorized }?: {
         isAuthorized?: ((ownerKey: Uint8Array) => boolean) | null;
@@ -235,6 +282,20 @@ declare class CommitStore {
      * still carry the mutable name on the sidecar the caller knows as history.
      */
     _storedRecordFor(record: CommitRecord): Promise<CommitRecord | null>;
+    /**
+     * 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.
+     */
+    sweepTrash(): Promise<number>;
+    /**
+     * 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.
+     */
+    _removeManagedTree(record: CommitRecord): Promise<{
+        removed: boolean;
+        preservedPath: boolean;
+    }>;
     delete(record: CommitRecord): Promise<boolean>;
     purge(record: CommitRecord, { preservePath }?: {
         preservePath?: boolean;