dsh-rewind-plugin 0.21.0 → 0.21.1

package/lib/types/snapshot.d.ts

@@ -36,6 +36,10 @@
  *
  * @module dsh-rewind/snapshot
  */
+import type { ByteSource, ClearSessionReport, CrashPoint, DeleteFile, DiskProbe, FileImpact, PendingBackup, PruneStaleReport, RestoreOutcome, RestoreReconcileReport, RestoreRunOptions, StoredEntry, UncoveredPath } from './snapshot-format.ts';
+export { CURRENT_STORE_VERSION, UnknownStoreVersionError, isLinkEntry } from './snapshot-format.ts';
+export type { ByteSource, CheckpointEntry, ClearSessionReport, CopyOutcome, CrashPoint, DeleteFile, DiskProbe, FileImpact, LinkEntry, PendingBackup, PlannedAction, PruneStaleReport, RestoreJournal, RestoreJournalAction, RestoreJournalState, RestoreOutcome, RestoreReconcileReport, RestoreRunOptions, StoredEntry, UncoveredPath, } from './snapshot-format.ts';
+export { defaultProbe } from './snapshot-fs.ts';
 /**
  * A regular file larger than this is NOT backed up. This plugin is a
  * lightweight, conversation-scoped undo, not a backup system: copying a very
@@ -46,378 +50,6 @@
 export declare const DEFAULT_MAX_FILE_BYTES: number;
 /** Number of newest anchor groups (user messages) kept per session. */
 export declare const MAX_ANCHOR_GROUPS = 100;
-/**
- * Current on-disk store format version (the session's `store` marker value and
- * the `store` field of every entry this build writes). A value ABOVE this one
- * means the snapshots were written by a NEWER build: readers must then fail
- * closed (no file restore, nothing changed) instead of guessing what the extra
- * fields mean. A missing marker (or `1`) means the released v1 string format,
- * which is still read.
- */
-export declare const CURRENT_STORE_VERSION = 2;
-/**
- * Thrown when snapshots carry a store format newer than this build understands
- * (ADR-10: whole-operation fail-closed — never a partial restore, never a
- * clear). The session rewind itself does not depend on snapshots and still
- * works.
- */
-export declare class UnknownStoreVersionError extends Error {
-    /** The version found on disk. */
-    readonly version: number;
-    /** Where it was found (a marker or an entry file). */
-    readonly source: string;
-    constructor(
-    /** The version found on disk. */
-    version: number, 
-    /** Where it was found (a marker or an entry file). */
-    source: string);
-}
-/**
- * Recorded before-content — always bytes, never a decoded string:
- *
- * - `blob`: a raw byte copy inside the store (the format every new write uses).
- * - `text`: the exact UTF-8 bytes of a released-v1 string record (a v1 record
- *   that was decoded from valid UTF-8 is byte-exact, so restoring it is safe).
- * - `lossyText`: a released-v1 string record that contains U+FFFD, i.e. one
- *   the v1 build produced by a LOSSY decode of non-UTF-8 bytes. The original
- *   bytes are unknowable, so it can be compared against the disk but must
- *   never be written back as a restore target (that would destroy live data).
- */
-export type ByteSource = {
-    readonly kind: 'blob';
-    readonly path: string;
-} | {
-    readonly kind: 'text';
-    readonly bytes: Buffer;
-} | {
-    readonly kind: 'lossyText';
-    readonly text: string;
-};
-/** A staged raw byte copy waiting to be committed (`recordBackup`). */
-export interface PendingBackup {
-    /** Absolute path of the staged file (inside the session's `.pending/`). */
-    readonly file: string;
-    /** Byte size of the staged content. */
-    readonly size: number;
-    /**
-     * Permission bits of the source file (`stat().mode & 0o7777`), captured
-     * best-effort. Restored alongside the content — never on its own, and never
-     * as part of the change decision (ADR-9).
-     */
-    readonly mode?: number;
-}
-/** One committed before-backup, keyed by tool call. */
-export interface CheckpointEntry {
-    readonly callId: string;
-    /** Seq of the user message anchoring the turn in which the change happened. */
-    readonly anchorSeq: number;
-    /** Resolved display path (absolute) of the tracked file. */
-    readonly path: string;
-    /** Byte source of the content before the change; null when the file was created. */
-    readonly before: ByteSource | null;
-    /** Byte size of `before` (0 when the file was created). */
-    readonly size: number;
-    /**
-     * Checkpoint-time location pin: the `realpath` of `dirname(path)` at the
-     * moment the entry was committed. A restore refuses the path when its parent
-     * directory no longer resolves there, because a repointed or moved ancestor
-     * would otherwise redirect the write (or the unlink) outside the recorded
-     * location — only the path's FINAL component is link-checked. Absent means
-     * "no pin": a released-v1 entry, a v2 entry written before this field
-     * existed, or a commit whose parent could not be resolved; the restore then
-     * falls back to the final-component check alone.
-     */
-    readonly parent?: string;
-    /**
-     * Permission bits recorded at capture time, when known. Applied only when
-     * the CONTENT is restored (a mode-only difference is never a reason to plan
-     * a restore); a missing value means "leave the live mode alone".
-     */
-    readonly mode?: number;
-    /**
-     * Set when this entry's sidecar holds re-encoded LOSSY text (a released-v1
-     * record that was decoded with replacement characters, e.g. after `prune`
-     * materialized its link). The bytes are comparable but must never be written
-     * back: a reader turns such an entry into a `lossyText` source again.
-     */
-    readonly lossy?: boolean;
-    /** Epoch ms the entry was committed (stable ordering within a group). */
-    readonly time: number;
-    /**
-     * Absolute file this entry was READ from (in-memory only, never serialized):
-     * a dedup reference must name the file that actually exists, which for an
-     * entry written by an older build is not necessarily the name the current
-     * naming function would produce.
-     */
-    readonly file?: string;
-}
-/**
- * One in-place dedup link, keyed by tool call. When a tracked file is
- * recorded with a `before` content identical to the immediately-prior entry
- * for that path, the entry is stored as a LINK instead of a full copy: it
- * carries no content, only a `ref` naming the prior entry file
- * (`<anchorSeq>/<callId>.json`). The linear (predecessor-chained) ref makes
- * restore resolution and prune materialization rewrite-free.
- */
-export interface LinkEntry {
-    readonly callId: string;
-    readonly anchorSeq: number;
-    readonly path: string;
-    /** `<anchorSeq>/<callId>.json` of the immediately-prior entry for the path. */
-    readonly ref: string;
-    /**
-     * Checkpoint-time location pin (see {@link CheckpointEntry.parent}); a link
-     * records its own, so a materialized or resolved entry never loses the
-     * location the path was committed under.
-     */
-    readonly parent?: string;
-    readonly time: number;
-    /** Absolute file this link was read from (in-memory only, never serialized). */
-    readonly file?: string;
-}
-/** Any on-disk entry: a full before-backup or an in-place dedup link. */
-export type StoredEntry = CheckpointEntry | LinkEntry;
-/** True when an entry is a dedup link (carries `ref`, not `before`). */
-export declare function isLinkEntry(entry: StoredEntry): entry is LinkEntry;
-/** Per-file restore impact preview (served by the host preview route). */
-export interface FileImpact {
-    readonly path: string;
-    /** `restore` = write the before content back; `delete` = remove the file. */
-    readonly action: 'restore' | 'delete';
-}
-/** A recorded path whose current on-disk size is over the backup cap. */
-export interface UncoveredPath {
-    readonly path: string;
-    /** Byte size observed on disk, when the probe could read one. */
-    readonly size?: number;
-}
-/** Outcome of one restore pass. */
-export interface RestoreOutcome {
-    readonly restored: readonly string[];
-    readonly deleted: readonly string[];
-    /** Symlinked or hard-linked paths left untouched. */
-    readonly skipped: readonly string[];
-    readonly failed: readonly {
-        path: string;
-        message: string;
-    }[];
-}
-/** Deletes one file by its real path (node:fs, bypassing the fs service). */
-export type DeleteFile = (path: string) => Promise<void>;
-/**
- * Test-only fault injection: a crash point inside the write/restore paths.
- * The hook THROWS to simulate a host crash at the exact point; the throw
- * propagates out of the store method, leaving the journal on disk in its
- * current state. Production callers never pass it (undefined = no-op).
- */
-export type CrashPoint = 'before-action' | 'after-action' | 'after-temp-write';
-/** Options for the journaled restore paths; `crash` is the test-only seam. */
-export interface RestoreRunOptions {
-    /**
-     * Throws at the given point to simulate a host crash: `before-action`
-     * (before an action's fs op), `after-action` (right after the fs op,
-     * before its done-mark is persisted), `after-temp-write` (inside an atomic
-     * commit, between the temp write and the rename). `index` is the action
-     * index for the restore loops.
-     */
-    readonly crash?: (point: CrashPoint, index?: number) => void;
-}
-/**
- * Lifecycle of one restore operation journal. Terminal states are kept on
- * disk as a tiny audit trail and skipped by reconciliation.
- */
-export type RestoreJournalState = 'running' | 'rollback-running' | 'completed' | 'rolled-back' | 'recovery-required';
-/**
- * One journaled restore action — a mutable working record that the restore
- * loop updates (done/failed) as it applies the pass.
- */
-export interface RestoreJournalAction {
-    readonly path: string;
-    readonly action: 'restore' | 'delete';
-    /** Target content for a restore; null for a delete. */
-    readonly before: ByteSource | null;
-    /**
-     * Pre-restore disk state ("rescue"): a raw byte copy of what the file had
-     * right before the restore started, or null when it was absent. Rollback
-     * writes this back, so the pre-restore state is recoverable exactly.
-     */
-    readonly rescue: ByteSource | null;
-    /** Set when the rescue capture failed: rollback then skips this path. */
-    rescueError?: string;
-    /** Permission bits the restored content should end up with, when recorded. */
-    readonly mode?: number;
-    /**
-     * Checkpoint-time location pin copied from the entry the action was planned
-     * from (see {@link CheckpointEntry.parent}): a continue or rollback after a
-     * restart re-checks it before touching the path.
-     */
-    readonly parent?: string;
-    /** Permission bits the file had BEFORE the restore, for a faithful rollback. */
-    readonly rescueMode?: number;
-    /** True once the action's fs op completed and was marked. */
-    done: boolean;
-    /** Per-action failure message; the restore pass never aborts. */
-    failed?: string;
-}
-/** Durable journal for one attempted restore (written atomically). */
-export interface RestoreJournal {
-    /** On-disk schema version: 2 = byte references, 1 = inline legacy strings. */
-    readonly version: 1 | 2;
-    readonly id: string;
-    readonly sessionId: string;
-    readonly targetSeq: number;
-    readonly startedAt: number;
-    finishedAt?: number;
-    state: RestoreJournalState;
-    readonly actions: RestoreJournalAction[];
-    /** Set when a rollback pass failed partway (state becomes `recovery-required`). */
-    rollbackError?: string;
-    /**
-     * Absolute file this journal was read from (in-memory only, never
-     * serialized): a legacy `restore-journal-` file is updated IN PLACE so an
-     * op that was interrupted before the upgrade never ends up with two
-     * divergent versions on disk.
-     */
-    sourceFile?: string;
-}
-/**
- * Result of reconciling one interrupted restore journal against the real
- * disk. Path status is relative to the op's current goal: the restore target
- * for `running` journals, the pre-restore (rescue) state for
- * `rollback-running` / `recovery-required` journals — disambiguate with
- * {@link RestoreReconcileReport.journalState}.
- */
-export interface RestoreReconcileReport {
-    readonly opId: string;
-    /** `interrupted` = a crash left the op unfinished; `recovery-required` = a rollback could not complete. */
-    readonly state: 'interrupted' | 'recovery-required';
-    /** Raw journal state (`running` | `rollback-running` | `recovery-required`). */
-    readonly journalState: RestoreJournalState;
-    readonly targetSeq: number;
-    readonly startedAt: number;
-    /** Paths whose disk already matches the op's goal. */
-    readonly restored: readonly string[];
-    /** Paths still short of the op's goal (not yet applied / not yet rolled back). */
-    readonly pending: readonly string[];
-    /** Actions that failed during the pass (kept failed until a redo succeeds). */
-    readonly failed: readonly {
-        path: string;
-        message: string;
-    }[];
-    readonly rollbackError?: string;
-    /** Set when the journal file itself is corrupt: it cannot be reconciled. */
-    readonly corrupt?: string;
-}
-/**
- * Current-on-disk state probe used by restore planning and reconciliation.
- * Injected so the logic runs against a fake FS in tests; the production
- * default reads the real file system with plain `node:fs` (see
- * {@link defaultProbe}) and compares byte streams, never whole files in memory.
- */
-export interface DiskProbe {
-    /**
-     * Compare the recorded content with the file currently at `path`.
-     *
-     * - `true`  = the disk matches the record byte-for-byte (for a `null`
-     *   source: the path is absent).
-     * - `false` = it differs — including "the record says the file did not
-     *   exist but it does" and "the record has content but the file is gone".
-     * - `undefined` = the comparison could not be decided (IO/permission
-     *   failure). Callers stay conservative: a restore is still attempted and a
-     *   delete still attempted, so an unreadable file is never silently skipped.
-     *
-     * A `lossyText` source is compared with the same lossy decode the released
-     * v1 build used (its original bytes cannot be recovered).
-     */
-    matches(source: ByteSource | null, path: string): Promise<boolean | undefined>;
-    /**
-     * Stage a raw byte copy of the file at `path` into `dest` (the store's
-     * rescue area) without loading it into memory.
-     */
-    copy(path: string, dest: string): Promise<CopyOutcome>;
-    /**
-     * Byte size of the regular file at `path`, or `undefined` when absent or
-     * unreadable. Consulted before any content comparison so an over-cap file is
-     * skipped without being read. Optional; a missing accessor reads as "size
-     * unknown", which never counts as "too big".
-     */
-    size?(path: string): Promise<number | undefined>;
-    /** True when the path is a symlink or a hard link (never planned/restored). */
-    isLink(path: string): Promise<boolean>;
-}
-/** Result of staging one on-disk byte copy. */
-export type CopyOutcome = {
-    readonly kind: 'copied';
-    readonly size: number;
-} | {
-    readonly kind: 'absent';
-} | {
-    readonly kind: 'failed';
-    readonly message: string;
-};
-/** One restore action the planner derived from record + disk reconciliation. */
-export type PlannedAction = {
-    readonly path: string;
-    readonly action: 'restore';
-    readonly before: ByteSource;
-    readonly mode?: number;
-    readonly parent?: string;
-} | {
-    readonly path: string;
-    readonly action: 'delete';
-    readonly parent?: string;
-};
-/** Production probe: real byte comparisons via node:fs, links via lstat + nlink. */
-export declare const defaultProbe: DiskProbe;
-/**
- * Result of a stale-session cleanup sweep ({@link SnapshotStore.pruneStale}).
- *
- * The sweep is ANTI-DELETE: it only ever removes WHOLE session directories
- * that have been idle past `maxAgeDays`. `scanned` counts every session dir
- * evaluated; `kept` + `skippedActive` + `deleted` sum to it. `remainingBytes`
- * is the total of directories that SURVIVE the policy (when `dryRun` it is the
- * would-be total, not the current on-disk total), so it is comparable across
- * dry and real runs.
- */
-export interface PruneStaleReport {
-    /** Number of session directories evaluated. */
-    readonly scanned: number;
-    /** Session directories removed (would-be count when `dryRun`). */
-    readonly deleted: number;
-    /** Bytes reclaimed (would-be bytes when `dryRun`). */
-    readonly freedBytes: number;
-    /** Session directories retained (not past the cutoff, not the active one). */
-    readonly kept: number;
-    /** Bytes across the retained + skipped-active directories. */
-    readonly remainingBytes: number;
-    /** Directories skipped because they are the active session. */
-    readonly skippedActive: number;
-    /** Whether nothing was really removed (the sweep only reported). */
-    readonly dryRun: boolean;
-}
-/**
- * Result of a manual whole-session clear ({@link SnapshotStore.clearSession}).
- *
- * Unlike the age-based sweep, a clear removes EVERY snapshot of ONE session
- * (all anchor groups, all checkpoint entries, all restore journals) on demand —
- * the active session the user is driving, to drop the rewind overhead or to
- * archive a conversation immediately. `dryRun` reports what would be removed
- * without touching disk or memory.
- */
-export interface ClearSessionReport {
-    /** The session whose records were (or would be) cleared. */
-    readonly sessionId: string;
-    /** Number of anchor-group (user-message) directories present. */
-    readonly anchorGroups: number;
-    /** Number of committed checkpoint entries (full backups + dedup links). */
-    readonly entries: number;
-    /** Number of restore-journal files (terminal + pending). */
-    readonly journals: number;
-    /** Bytes occupied by the session directory (the amount freed). */
-    readonly bytes: number;
-    /** Whether nothing was really removed (the clear only reported). */
-    readonly dryRun: boolean;
-}
 /**
  * On-disk checkpoint store. Every write goes straight through `node:fs`, so a
  * restore reliably lands on the real file system.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "In-window conversation rewind with workspace file restore",
   "icon": "./assets/icon.svg",
   "keywords": [