swarm-deploy 0.0.0 → 0.2.0

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

@@ -0,0 +1,307 @@
+import type { ReleaseCoordinates } from '../release.js';
+import { CorruptJournalError, COMMIT_VERSION, MAX_COMMIT_METADATA_BYTES } 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;
+}
+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;
+    state: string;
+}
+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?: {
+        trigger?: string;
+    }): Promise<unknown>;
+    afterCommit(): Promise<unknown>;
+    _runUnlocked(options: {
+        incomingBytes: number;
+        trigger: 'commit';
+    }): Promise<unknown>;
+    _afterCommitUnlocked(): Promise<unknown>;
+}
+interface SessionStore {
+    readVerified(transferId: Uint8Array): Promise<CommitSession>;
+    sessions?: Map<string, CommitSession>;
+}
+interface Logger {
+    warn?: (message: string, details: Record<string, unknown>) => void;
+}
+interface CommitStoreOptions {
+    layout: StorageLayout;
+    clock?: {
+        now(): number;
+    };
+    storage?: StorageAdapter;
+    logger?: Logger | null;
+}
+interface ReplacePolicy {
+    replaceNames?: Iterable<string>;
+}
+/** The visible state of one top-level path, without following symlinks. */
+interface RootPathState {
+    present: boolean;
+    /** Set only for a regular file; an unmanaged non-regular path leaves it null. */
+    stat: StorageStat | null;
+}
+type ReplacementPlan = {
+    mode: 'create';
+} | {
+    mode: 'idempotent';
+    record: CommitRecord;
+} | {
+    mode: 'replace';
+    oldRecord: CommitRecord;
+    finalIdentity: FileIdentity;
+};
+declare class CommitStore {
+    layout: StorageLayout;
+    clock: {
+        now(): number;
+    };
+    storage: StorageAdapter;
+    logger: Logger | null;
+    journalAttempts: Map<string, string>;
+    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;
+    _finalPath(name: string): string;
+    _publicationPath(name: string): string;
+    _assertLayout(): Promise<void>;
+    /** Inspects one top-level path without following or trusting symlinks. */
+    _rootPathState(name: string): Promise<RootPathState>;
+    _syncRoot(): Promise<void>;
+    _safeFileOrAbsent(filePath: string, directory: string): Promise<StorageStat | null>;
+    _readRecordOrAbsent(recordPath: string): Promise<CommitRecord | null>;
+    _writeRecord(record: CommitRecord): Promise<boolean>;
+    /** Persists a sidecar transition over its own previous durable content. */
+    _rewriteRecord(record: CommitRecord): Promise<void>;
+    _removeFile(filePath: string, directory: string): Promise<boolean>;
+    _removeManagedFinalOrAbsent(record: CommitRecord): Promise<{
+        removed: boolean;
+        preservedPath: boolean;
+    }>;
+    _linkJournal(id: string, journal: AnyCommitJournal, attempt: string): Promise<void>;
+    _writeJournal(record: CommitRecord, sourceStagingIdentity: FileIdentity): Promise<string>;
+    /** 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
+     * durable intent trail the journal must carry.
+     */
+    _setReplacementPhase(journal: ReplacementJournal, phase: ReplacementPhase): Promise<ReplacementJournal>;
+    retireCorruptJournal(id: string): Promise<boolean>;
+    retireCorruptAttempt(id: string): Promise<{
+        retired: boolean;
+        removedStaging: boolean;
+    }>;
+    _discardJournal(id: string, expectedAttemptId: string): Promise<boolean>;
+    _markAttemptAborting(id: string, expectedAttemptId: string): Promise<AnyCommitJournal>;
+    _linkStaging(stagingPath: string, finalPath: string, expectedIdentity: FileIdentity, signal: AbortSignalLike | null): Promise<void>;
+    _removeAbortedPublication(record: CommitRecord, expectedIdentity: FileIdentity): Promise<void>;
+    _reportCleanupPending(record: CommitRecord, err: unknown): void;
+    _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, release?: CommitRelease): CommitRecord;
+    inspect(name: string, offer: CommitOffer, { replaceNames }?: ReplacePolicy): Promise<{
+        status: 'AVAILABLE';
+    } | {
+        status: 'ALREADY_COMMITTED';
+        record: CommitRecord;
+    } | {
+        status: 'REPLACEABLE';
+        record: CommitRecord;
+    } | {
+        status: 'FILE_EXISTS';
+    }>;
+    _inspect(name: string, offer: CommitOffer, mutable: Set<string>, release: CommitRelease | undefined): Promise<{
+        status: 'AVAILABLE';
+    } | {
+        status: 'ALREADY_COMMITTED';
+        record: CommitRecord;
+    } | {
+        status: 'REPLACEABLE';
+        record: CommitRecord;
+    } | {
+        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;
+        identity: FileIdentity;
+    } | null>;
+    _assertSessionMatchesRecord(session: CommitSession, record: CommitRecord, message: string): void;
+    _validateAttemptLeftovers(id: string, journal: CommitJournal, sessionStore: SessionStore): Promise<{
+        sessionFile: StorageStat | null;
+        staging: StorageStat | null;
+    }>;
+    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>, 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
+     * occupied path is an existing-name conflict.
+     */
+    _planReplacement(record: CommitRecord): Promise<ReplacementPlan>;
+    /**
+     * A repeated A→B→A sequence reuses a transfer ID that already owns a history
+     * artifact of identical content. The superseded duplicate is dropped inside
+     * the transaction so the returning content becomes the only copy.
+     */
+    _dedupHistory(record: CommitRecord): Promise<{
+        name: string;
+        identity: FileIdentity | null;
+    } | null>;
+    _replace(record: CommitRecord, stagingIdentity: FileIdentity, plan: {
+        oldRecord: CommitRecord;
+        finalIdentity: FileIdentity;
+    }, 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
+     * destination is never overwritten or removed.
+     */
+    _rollbackReplacement(journal: ReplacementJournal): Promise<void>;
+    _readJournal(id: string): Promise<AnyCommitJournal | null>;
+    /** Every parsable v2 journal, used to explain transient duplicate names. */
+    _pendingReplacements(): Promise<ReplacementJournal[]>;
+    /**
+     * Finalizes or rolls back one v2 attempt. The durable new current sidecar is
+     * the linearization point: before it the old content is restored, after it
+     * the new content is preserved while history metadata and cleanup converge.
+     */
+    _convergeReplacement(id: string, journal: ReplacementJournal, sessionStore: SessionStore | null, { forceAbort }?: {
+        forceAbort?: boolean;
+    }): Promise<{
+        status: 'COMMITTED' | 'ABORTED' | 'RESUMABLE';
+        record: CommitRecord;
+    }>;
+    /**
+     * Startup recovery for one v2 attempt. Revocation of a still-live session
+     * aborts the attempt first so the same rollback path converges.
+     */
+    _recoverReplacementJournal(id: string, journal: ReplacementJournal, sessionStore: SessionStore, isAuthorized: ((ownerKey: Uint8Array) => boolean) | null): Promise<{
+        status: 'COMMITTED' | 'ABORTED' | 'RESUMABLE';
+        record: CommitRecord;
+    }>;
+    /** Writes or drops the history sidecar for an already linearized attempt. */
+    _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;
+    }): Promise<{
+        status: 'MISSING' | 'FILE_EXISTS' | 'COMMITTED' | 'ABORTED' | 'RESUMABLE';
+        record?: CommitRecord;
+    }>;
+    _scanRecords(): Promise<CommitRecord[]>;
+    scrubRecords(): Promise<{
+        records: CommitRecord[];
+        deleted: number;
+    }>;
+    _resolveRecords(records: CommitRecord[]): Promise<CommitRecord[]>;
+    /**
+     * A replacement makes the old sidecar the history record after its new
+     * current sidecar is durable, so one name can briefly carry two records.
+     * Only a journal-owned duplicate is tolerated, reported at the history name
+     * that recovery will persist; anything else fails closed.
+     */
+    list(): Promise<CommitRecord[]>;
+    /**
+     * Locates the durable record a caller is deleting. A pending replacement may
+     * still carry the mutable name on the sidecar the caller knows as history.
+     */
+    _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;
+    }): Promise<false | {
+        purged: true;
+        preservedPath: boolean;
+    }>;
+}
+export { CommitStore, CorruptJournalError, COMMIT_VERSION, MAX_COMMIT_METADATA_BYTES };