swarm-deploy 0.3.0 → 0.4.1

package/dist/storage/reset.d.ts

@@ -0,0 +1,95 @@
+import type { StorageAdapter } from './types.js';
+/** Every private metadata directory a reset archives, in archive order. */
+export declare const METADATA_DIRECTORIES: readonly ['staging', 'sessions', 'commits', 'journals', 'publications', 'links', 'trash'];
+export type MetadataDirectoryName = (typeof METADATA_DIRECTORIES)[number];
+export declare const ARCHIVE_DIRECTORY_NAME = "archive";
+export declare const ARCHIVE_MARKER_NAME = "reset.json";
+/** Verbatim copy of a version 1 marker, kept when a retry upgrades it to the bounded format. */
+export declare const ARCHIVE_LEGACY_MARKER_NAME = "reset.v1.json";
+export interface StorageResetOptions {
+    storageDir: string;
+    /** Archive the metadata. Without it the reset is a read-only preview. */
+    apply?: boolean;
+    /** Milliseconds to keep polling a live lock before failing closed. */
+    wait?: number;
+    storage?: StorageAdapter;
+    isProcessAlive?: (pid: number) => boolean;
+    clock?: {
+        now(): number;
+    };
+    pid?: number;
+    pollInterval?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export type ResetLockState = {
+    status: 'free';
+} | {
+    status: 'held';
+    pid: number;
+    ageMs: number;
+} | {
+    status: 'stale';
+    pid: number;
+    ageMs: number;
+} | {
+    status: 'malformed';
+} | {
+    status: 'unsafe';
+};
+/** What an archive physically holds. Lock residue is counted; its names stay in `locks/`. */
+export interface ArchiveHoldings {
+    directories: string[];
+    lockEntries: number;
+}
+export interface ArchiveSummary {
+    name: string;
+    path: string;
+    /** What the marker claims; an `in-progress` marker can lag the archive after a hard stop. */
+    status: 'completed' | 'in-progress' | 'unknown';
+    /** What the archive physically holds, read from the filesystem rather than the marker. */
+    held: ArchiveHoldings;
+}
+export interface StorageResetReport {
+    root: string;
+    applied: boolean;
+    lock: ResetLockState;
+    /** Entry counts per private metadata directory before the reset. */
+    metadata: Record<MetadataDirectoryName, number>;
+    commits: {
+        records: number;
+        missingPayloads: string[];
+        invalid: number;
+    };
+    links: {
+        records: number;
+        invalid: number;
+    };
+    obsoleteLocks: number;
+    /** Entries in the internal directory the reset does not recognise and leaves alone. */
+    unknownInternal: string[];
+    archives: ArchiveSummary[];
+    /** Visible root entries the reset never touches; they stay after the reset. */
+    remaining: {
+        payloads: string[];
+        symlinks: string[];
+        other: string[];
+    };
+    /** True only when nothing visible remains, so the next server really starts empty. */
+    freshStart: boolean;
+    resetPending: boolean;
+    /** The archive an interrupted reset left pending, which the next apply resumes. */
+    pendingArchive: string | null;
+    /** The archive this run created or resumed, when applied. */
+    archive: string | null;
+    /** What a resumed archive already held before this run; null when a new archive was made. */
+    resumed: ArchiveHoldings | null;
+}
+/** Read-only inspection of a storage root: never creates, moves, or locks anything. */
+export declare function inspectStorageReset(options: StorageResetOptions): Promise<StorageResetReport>;
+/**
+ * Archives every private metadata directory of a storage root into
+ * `.swarm-deploy/archive/<reset-stamp>/` and recreates them empty, under the
+ * storage lock. Visible payloads and symlinks in the root are never touched,
+ * and nothing is deleted: the archive is restorable by moving it back.
+ */
+export declare function resetStorage(options: StorageResetOptions): Promise<StorageResetReport>;