@mikode13/harness 4.0.1 → 5.0.0

package/dist/recovery/infrastructure/fileRecoveryStore.d.ts

@@ -0,0 +1,133 @@
+import { type JournalEntry, type MoveOptions, type Revision, type RecoveryStore, type RunJournal, type RunRecord } from '../domain/recoveryStore.ts';
+/** Where an application keeps state that is neither configuration nor cache, per platform. */
+export declare function defaultStateDirectory(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, home?: string): string;
+/**
+ * The recovery store on disk, in a private directory per workspace under the platform's state
+ * directory:
+ *
+ * ```text
+ * <directory>/workspaces/<hash of the root>/
+ *   workspace.json            the root it belongs to
+ *   lock                      the run writing now, if any
+ *   head.json                 the run the workspace is at, and a move in progress
+ *   revisions.jsonl           every move of the workspace through its history
+ *   content/<ab>/<hash>       file contents, named by their SHA-256
+ *   runs/<runId>/run.json     the run's record
+ *   runs/<runId>/journal.jsonl  its changes, one line per step, appended and synced
+ * ```
+ *
+ * The lock only keeps a second run of this harness from writing at the same time. It does not
+ * stop an editor or another program, and two processes taking over a dead run's lock in the
+ * same instant could both believe they hold it.
+ */
+export declare class FileRecoveryStore implements RecoveryStore {
+    private readonly root;
+    private readonly directory;
+    private readonly keepRuns;
+    private constructor();
+    static open({ root, directory, keepRuns, }: {
+        root: string;
+        /** Defaults to the platform's state directory. */
+        directory?: string;
+        /**
+         * The most runs kept per workspace, the one being recorded included. Defaults to 25. At
+         * least 3: the run the workspace is at is never removed, and the last run of its line has
+         * no next run to be chained into, so pruning can leave two runs besides the new one.
+         */
+        keepRuns?: number;
+    }): Promise<FileRecoveryStore>;
+    startRun(): Promise<RunJournal>;
+    listRuns(): Promise<{
+        head?: string;
+        runs: RunRecord[];
+    }>;
+    readRun(runId: string): Promise<{
+        record: RunRecord;
+        entries: JournalEntry[];
+    }>;
+    private readRecord;
+    private runDirectory;
+    private readHead;
+    private writeHead;
+    goTo(target: string, options?: MoveOptions): Promise<Revision>;
+    undo(options?: MoveOptions): Promise<Revision>;
+    redo(options?: MoveOptions): Promise<Revision>;
+    listRevisions(): Promise<Revision[]>;
+    /** Holds the workspace like a run does, then moves it to the run `resolve` picks. */
+    private move;
+    /** Finishes a move whose process stopped halfway, from the run its last step reached. */
+    private finishPendingMove;
+    /**
+     * Undoes, then redoes, one run at a time from where the head is to `pending.to`. After each
+     * step the head names the run reached, with the move still pending, so a crash loses at
+     * most the step in progress, and that step is safe to take again.
+     */
+    private takeSteps;
+    /** Takes one run's changes back to its parent, or forward again, file by file. */
+    private step;
+    /**
+     * Writes the state the step leads to, only if the file holds the state it leaves. A file
+     * already there is left alone, so taking a step again is safe. Returns whether the file
+     * ends where the step leads.
+     */
+    private moveFile;
+    /** Throws `HistoryExpiredError` if retention removed `runId` or chained it into a later run. */
+    private assertNotAbsorbed;
+    private listPruned;
+    /**
+     * Brings the history down to `keepRuns - 1`, so the run about to start makes `keepRuns`, then
+     * frees the contents no run kept refers to.
+     */
+    private prune;
+    /**
+     * Chains the changes of `older` into `newer`, its child: `newer` then hangs from `older`'s
+     * parent and goes back to where `older` started. The new record is the commit point. Before
+     * it, the history is as it was; after it, `finishChains` removes what is left of `older`.
+     */
+    private chain;
+    /**
+     * Removes what a chain or a removal a crash interrupted left behind: the folders of runs
+     * pruned or absorbed by a kept run, and journals a run no longer reads.
+     */
+    private finishChains;
+    /**
+     * Removes a run whole, recording its id first so a move to it reports an expired history.
+     * Its record goes next, so a crash halfway leaves no run behind.
+     */
+    private removeRun;
+    /**
+     * Takes a run that changed nothing out of the history, under the lock: the workspace goes back
+     * to its parent first, so the head never names a run that is gone. Until the run is removed,
+     * `listRuns` already hides it, and the next run or move finishes removing it. The contents it
+     * saved are freed by the next prune.
+     */
+    private discardRun;
+    /** Removes the stored contents no kept run refers to. */
+    private collectContent;
+    private appendRevision;
+    /**
+     * Marks every other run still recorded as `running` as `interrupted`: this run holds the lock,
+     * so their processes are gone. Each change one left `prepared` is settled from what its file
+     * holds now: its `after` means it was made, its `before` that it was not. A file that holds
+     * neither stays `prepared`, because nothing tells whether the change reached it.
+     */
+    private settleInterrupted;
+    /**
+     * The lines that record what a command an interrupted run was observing changed: every file of
+     * its manifest that holds something else now, as changed by that command, and then the end of
+     * the observation. A file recorded after the observation began is left alone: the run
+     * recorded it itself. One that is now a folder, a link or too large to record is left out.
+     */
+    private settleObservation;
+    /** What `path` holds now, with its content stored, or `undefined` for what no entry records. */
+    private saveState;
+    private readEntries;
+    /**
+     * A run's changes, the observations it began and never finished, and the highest sequence
+     * number its journal uses, which the next line it gets must exceed.
+     */
+    private readJournal;
+    readContent(hash: string): Promise<Buffer>;
+    private lock;
+    private unlock;
+}