@chances-ai/engine 28.0.0 → 30.0.0

package/dist/hashline/patcher.js

@@ -0,0 +1,332 @@
+/**
+ * High-level patch orchestrator. Reads each section's target file via the
+ * configured {@link Filesystem}, strips BOM and normalizes line endings,
+ * validates the section snapshot tag (with {@link Recovery}), applies the
+ * result back through the same {@link Filesystem}. Ported from oh-my-pi
+ * `packages/hashline/src/patcher.ts`.
+ *
+ * **chances-cli change (7.9 R1-M3):** the live-match integrity check is exact
+ * snapshot-text equality (`byHash(path, tag)?.text === live`), NOT hash
+ * equality. The 4-hex tag is only a fast index; comparing the stored full text
+ * means a 16-bit collision can never silently apply stale line numbers to
+ * different live content — it degrades to recovery → forced re-read. The cost
+ * is that an edit to a file whose snapshot was evicted from the bounded store
+ * (or carried from a prior session) re-reads instead of fast-applying; that is
+ * the safe direction.
+ *
+ * Two layers:
+ *
+ * - {@link Patcher.apply} — high-level, all-or-nothing. Preflights every
+ *   section in memory before any write hits disk, then commits in order.
+ * - {@link Patcher.prepare} / {@link Patcher.commit} — granular primitives
+ *   for callers that need per-section control (e.g. the engine `edit` tool,
+ *   which holds the per-file mutation lock across the whole prepare+commit
+ *   span — 7.9 R1-M1).
+ *
+ * Because `prepare` already runs the full apply, a multi-section batch is
+ * naturally all-or-nothing: by the time any `commit` runs, every section
+ * has been validated.
+ *
+ * The patcher itself is stateless across calls; reuse one instance per
+ * filesystem configuration.
+ */
+import { applyEdits } from "./apply.js";
+import { hasBlockEdit, resolveBlockEdits } from "./block.js";
+import { computeFileHash, formatHashlineHeader, hashTrimsTrailing } from "./format.js";
+import { isNotFound } from "./fs.js";
+import { HEADTAIL_DRIFT_WARNING, missingSnapshotTagMessage } from "./messages.js";
+import { MismatchError } from "./mismatch.js";
+import { detectLineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize.js";
+import { Recovery } from "./recovery.js";
+/**
+ * Opaque token returned by {@link Patcher.prepare}. Carries the section, the
+ * raw file content read off disk, and the in-memory apply result.
+ * {@link Patcher.commit} just writes the {@link PreparedSection.applyResult}.
+ */
+export class PreparedSection {
+    section;
+    canonicalPath;
+    exists;
+    rawContent;
+    bom;
+    lineEnding;
+    normalized;
+    applyResult;
+    parseWarnings;
+    /** @internal */
+    constructor(section, canonicalPath, exists, rawContent, bom, lineEnding, normalized, applyResult, parseWarnings) {
+        this.section = section;
+        this.canonicalPath = canonicalPath;
+        this.exists = exists;
+        this.rawContent = rawContent;
+        this.bom = bom;
+        this.lineEnding = lineEnding;
+        this.normalized = normalized;
+        this.applyResult = applyResult;
+        this.parseWarnings = parseWarnings;
+    }
+    /** Convenience: returns true when the apply produced no change. */
+    get isNoop() {
+        return this.applyResult.text === this.normalized;
+    }
+}
+function hasAnchorScopedEdit(edits) {
+    return edits.some((edit) => {
+        if (edit.kind === "delete")
+            return true;
+        // A `replace block N:` edit anchors to concrete content on line N.
+        if (edit.kind === "block")
+            return true;
+        return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor";
+    });
+}
+function assertSectionHashPresent(sectionPath, fileHash) {
+    if (fileHash !== undefined)
+        return;
+    throw new Error(missingSnapshotTagMessage(sectionPath));
+}
+function recoveryToApplyResult(result) {
+    return {
+        text: result.text,
+        firstChangedLine: result.firstChangedLine,
+        warnings: result.warnings,
+    };
+}
+function mergeWarnings(...sources) {
+    const out = [];
+    for (const source of sources) {
+        if (!source)
+            continue;
+        for (const warning of source)
+            out.push(warning);
+    }
+    return out;
+}
+function assertUniqueCanonicalPaths(prepared) {
+    const seen = new Map();
+    for (const entry of prepared) {
+        const previous = seen.get(entry.canonicalPath);
+        if (previous !== undefined) {
+            throw new Error(`Multiple hashline sections resolve to the same file (${previous} and ${entry.section.path}). Merge their ops under one header before applying.`);
+        }
+        seen.set(entry.canonicalPath, entry.section.path);
+    }
+}
+/**
+ * High-level patcher. Wires a {@link Filesystem} and a required
+ * {@link SnapshotStore} together with the parsing + applying core.
+ *
+ * Construct once per FS configuration; reuse across patches.
+ */
+export class Patcher {
+    fs;
+    snapshots;
+    recovery;
+    blockResolver;
+    constructor(options) {
+        if (!options.snapshots) {
+            throw new Error("Hashline Patcher requires a SnapshotStore; section tags are opaque store pointers.");
+        }
+        this.fs = options.fs;
+        this.snapshots = options.snapshots;
+        this.recovery = new Recovery(options.snapshots);
+        this.blockResolver = options.blockResolver;
+    }
+    /**
+     * Apply every section in `patch`. `prepare` runs the full apply for each
+     * section in memory before any write hits the filesystem, so a
+     * multi-section batch is naturally all-or-nothing. Returns one
+     * {@link PatchSectionResult} per section in the original patch order.
+     */
+    async apply(patch) {
+        // Single-section fast path.
+        if (patch.sections.length === 1) {
+            const prepared = await this.prepare(patch.sections[0]);
+            return { sections: [await this.commit(prepared)] };
+        }
+        // Prepare every section first so any failure (stale hash, missing
+        // file, parse error, in-memory no-op) surfaces before any write.
+        const prepared = [];
+        for (const section of patch.sections)
+            prepared.push(await this.prepare(section));
+        assertUniqueCanonicalPaths(prepared);
+        for (const entry of prepared) {
+            if (entry.isNoop) {
+                throw new Error(`Edits to ${entry.section.path} resulted in no changes being made.`);
+            }
+        }
+        const results = [];
+        for (const entry of prepared)
+            results.push(await this.commit(entry));
+        return { sections: results };
+    }
+    /**
+     * Run the preflight pass only: read, parse, validate, apply-in-memory.
+     * No writes hit the filesystem. Use for CI checks and dry runs.
+     */
+    async preflight(patch) {
+        const prepared = [];
+        for (const section of patch.sections)
+            prepared.push(await this.prepare(section));
+        assertUniqueCanonicalPaths(prepared);
+        for (const entry of prepared) {
+            if (entry.isNoop) {
+                throw new Error(`Edits to ${entry.section.path} resulted in no changes being made.`);
+            }
+        }
+    }
+    /**
+     * Read a section's target file, parse the section, validate the snapshot
+     * tag (with recovery), and apply the edits in memory. Returns a
+     * {@link PreparedSection} which can be fed to {@link commit} to land
+     * the result on the filesystem.
+     *
+     * Throws on parse error, missing-file-for-anchored-edit, or unrecovered
+     * tag mismatch ({@link MismatchError}).
+     */
+    async prepare(section) {
+        const { edits, warnings: parseWarnings } = section.parse();
+        assertSectionHashPresent(section.path, section.fileHash);
+        const canonicalPath = this.fs.canonicalPath(section.path);
+        await this.fs.preflightWrite(section.path);
+        const { exists, rawContent } = await this.#tryRead(section.path);
+        if (!exists) {
+            throw new Error(`File not found: ${section.path}. Use the write tool to create new files.`);
+        }
+        const { bom, text } = stripBom(rawContent);
+        const lineEnding = detectLineEnding(text);
+        const normalized = normalizeToLF(text);
+        const applyResult = this.#applyWithRecovery({
+            section,
+            canonicalPath,
+            exists,
+            normalized,
+            edits,
+        });
+        return new PreparedSection(section, canonicalPath, exists, rawContent, bom, lineEnding, normalized, applyResult, parseWarnings);
+    }
+    /**
+     * Commit a previously {@link prepare}d section to the filesystem.
+     * Restores line endings and BOM, writes via the {@link Filesystem}, and
+     * records a fresh snapshot in the {@link SnapshotStore} keyed by the
+     * filesystem-canonical path.
+     */
+    async commit(prepared) {
+        const { section, normalized, bom, lineEnding, parseWarnings, exists, applyResult, canonicalPath } = prepared;
+        const after = applyResult.text;
+        const warnings = mergeWarnings(parseWarnings, applyResult.warnings);
+        if (after === normalized) {
+            const hash = this.#recordFullSnapshot(canonicalPath, normalized);
+            return {
+                path: section.path,
+                canonicalPath,
+                op: "noop",
+                before: normalized,
+                after: normalized,
+                persisted: prepared.rawContent,
+                written: prepared.rawContent,
+                fileHash: hash,
+                header: formatHashlineHeader(section.path, hash),
+                warnings,
+            };
+        }
+        const persisted = bom + restoreLineEndings(after, lineEnding);
+        const write = await this.fs.writeText(section.path, persisted);
+        const fileHash = this.#recordFullSnapshot(canonicalPath, after);
+        const op = exists ? "update" : "create";
+        return {
+            path: section.path,
+            canonicalPath,
+            op,
+            before: normalized,
+            after,
+            persisted,
+            written: write.text,
+            fileHash,
+            header: formatHashlineHeader(section.path, fileHash),
+            firstChangedLine: applyResult.firstChangedLine,
+            warnings,
+        };
+    }
+    async #tryRead(path) {
+        try {
+            const content = await this.fs.readText(path);
+            return { exists: true, rawContent: content };
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return { exists: false, rawContent: "" };
+            throw error;
+        }
+    }
+    #recordFullSnapshot(canonicalPath, normalized) {
+        return this.snapshots.record(canonicalPath, normalized);
+    }
+    #mismatchError(section, canonicalPath, normalized, expected, hashRecognized) {
+        // Display the live content's tag (path-aware) without disturbing the
+        // version history's head/recency: compute directly rather than record.
+        const actualFileHash = computeFileHash(normalized, hashTrimsTrailing(section.path));
+        return new MismatchError({
+            path: section.path,
+            expectedFileHash: expected,
+            actualFileHash,
+            fileLines: normalized.split("\n"),
+            anchorLines: section.collectAnchorLines(),
+            hashRecognized,
+        });
+    }
+    #applyWithRecovery(args) {
+        const { section, canonicalPath, exists, normalized, edits } = args;
+        const expected = exists ? section.fileHash : undefined;
+        // R1-M3: the tag is a fast INDEX; the integrity check is exact stored-text
+        // equality. A 16-bit collision can therefore never silently apply stale
+        // line numbers — it falls through to recovery / re-read.
+        const liveMatches = expected !== undefined && this.snapshots.byHash(canonicalPath, expected)?.text === normalized;
+        // Resolve `replace block N:` edits to concrete ranges before recovery
+        // runs. Block anchors are expressed against the snapshot the section tag
+        // names, so resolve against that exact text:
+        //   - live content matches the tag (or there is no tag) → resolve against
+        //     the live, normalized content;
+        //   - the file drifted → resolve against the tagged snapshot's text so the
+        //     resulting ranges flow through the 3-way-merge recovery below.
+        // When a block edit needs the tagged snapshot but it is unavailable, the
+        // range cannot be placed safely — reject with a MismatchError (re-read).
+        let resolved = edits;
+        if (hasBlockEdit(edits)) {
+            const baseText = expected === undefined || liveMatches ? normalized : this.snapshots.byHash(canonicalPath, expected)?.text;
+            if (baseText === undefined) {
+                throw this.#mismatchError(section, canonicalPath, normalized, expected ?? "", false);
+            }
+            resolved = resolveBlockEdits(edits, baseText, section.path, this.blockResolver, { onUnresolved: "throw" });
+        }
+        if (expected === undefined)
+            return applyEdits(normalized, resolved);
+        // Whole-file unchanged → the tag still names the live content, so an
+        // edit anchored at ANY line (displayed or not) is safe to apply.
+        if (liveMatches)
+            return applyEdits(normalized, resolved);
+        // Head/tail-only inserts are position-stable: "start"/"end" cannot move
+        // with content drift, so a stale tag is non-fatal — BUT only when the tag
+        // was actually minted this session (R2-M1). An unrecognized tag (`byHash`
+        // null — fabricated or carried from a prior session) must still force a
+        // re-read; otherwise the model could append to a file it never read,
+        // breaking the "tag comes from read" contract (the M3 safety boundary).
+        if (!hasAnchorScopedEdit(resolved) && this.snapshots.byHash(canonicalPath, expected) !== null) {
+            const result = applyEdits(normalized, resolved);
+            return { ...result, warnings: [HEADTAIL_DRIFT_WARNING, ...(result.warnings ?? [])] };
+        }
+        // File drifted: try to replay the edit against the version the tag
+        // names and 3-way-merge it onto the live content.
+        const recovered = this.recovery.tryRecover({
+            path: canonicalPath,
+            currentText: normalized,
+            fileHash: expected,
+            edits: resolved,
+        });
+        if (recovered)
+            return recoveryToApplyResult(recovered);
+        const hashRecognized = this.snapshots.byHash(canonicalPath, expected) !== null;
+        throw this.#mismatchError(section, canonicalPath, normalized, expected, hashRecognized);
+    }
+}
+//# sourceMappingURL=patcher.js.map

package/dist/hashline/patcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patcher.js","sourceRoot":"","sources":["../../src/hashline/patcher.ts"],"names":[],"mappings":"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"}

package/dist/hashline/recovery.d.ts

@@ -0,0 +1,41 @@
+import type { SnapshotStore } from "./snapshots.js";
+import type { Edit } from "./types.js";
+export interface RecoveryArgs {
+    path: string;
+    currentText: string;
+    fileHash: string;
+    edits: readonly Edit[];
+}
+export interface RecoveryResult {
+    /** Post-recovery text. */
+    text: string;
+    /** First changed line (1-indexed) relative to the live `currentText`, or `undefined`. */
+    firstChangedLine: number | undefined;
+    /** Warnings collected during recovery, including the user-facing recovery banner. */
+    warnings: string[];
+}
+/**
+ * Stateless recovery driver over a {@link SnapshotStore}. Construct once and
+ * call {@link Recovery.tryRecover} per stale-tag incident. The default
+ * implementation tries two strategies in order:
+ *
+ * 1. Apply the edits on the full-file version the tag names, then 3-way-merge
+ *    the resulting patch onto the live content (handles external writes).
+ * 2. (Session chain) If that version wasn't the head, replay the edits onto
+ *    the live content directly when line counts match AND every edit's anchor
+ *    line content is unchanged between version and current — a prior in-session
+ *    edit advanced the tag and the model's anchors still name the same logical
+ *    rows. Emits a dedicated {@link RECOVERY_SESSION_REPLAY_WARNING} because
+ *    even with both guards a coincidental insert+delete pair on duplicate rows
+ *    can still land the edit on the wrong row; see {@link replaySessionChainOnCurrent}.
+ */
+export declare class Recovery {
+    readonly store: SnapshotStore;
+    constructor(store: SnapshotStore);
+    /**
+     * Attempt recovery. Returns `null` when no path forward is found — the
+     * caller should then surface a {@link MismatchError}.
+     */
+    tryRecover(args: RecoveryArgs): RecoveryResult | null;
+}
+//# sourceMappingURL=recovery.d.ts.map

package/dist/hashline/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../src/hashline/recovery.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAY,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAuB,IAAI,EAAE,MAAM,YAAY,CAAC;AAO5D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,qFAAqF;IACrF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAkHD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,QAAQ;IACP,QAAQ,CAAC,KAAK,EAAE,aAAa;gBAApB,KAAK,EAAE,aAAa;IACzC;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,cAAc,GAAG,IAAI;CAetD"}

package/dist/hashline/recovery.js

@@ -0,0 +1,175 @@
+/**
+ * Recover from a stale section snapshot tag by replaying the would-be edit
+ * against a cached pre-edit snapshot of the file and 3-way-merging the
+ * result onto the current on-disk content. Ported from oh-my-pi
+ * `packages/hashline/src/recovery.ts`.
+ *
+ * This is the synthesis the 7.9 decision [5.1] calls for: claude-code's
+ * normalization cascade survives here as the WITHIN-block content fallback —
+ * when the live file drifted, we replay the edit on the version the tag names
+ * and 3-way-merge onto live, instead of hard-rejecting.
+ *
+ * The patcher consults this when a section tag resolves to a snapshot that no
+ * longer matches the live file content. The recovery class is stateless apart
+ * from the {@link SnapshotStore} it queries; the snapshot store is the seam
+ * that lets you plug in your own caching strategy.
+ */
+import * as Diff from "diff";
+import { applyEdits } from "./apply.js";
+import { RECOVERY_EXTERNAL_WARNING, RECOVERY_SESSION_CHAIN_WARNING, RECOVERY_SESSION_REPLAY_WARNING, } from "./messages.js";
+// Section tags are line-precise; never let Diff.applyPatch slide a hunk
+// onto a duplicate closer 100+ lines away. If snapshot replay does not
+// align exactly, refuse and let the caller re-read.
+const RECOVERY_FUZZ_FACTOR = 0;
+function applyEditsToSnapshot(previousText, currentText, edits, recoveryWarning) {
+    let applied;
+    try {
+        applied = applyEdits(previousText, [...edits]);
+    }
+    catch {
+        return null;
+    }
+    if (applied.text === previousText)
+        return null;
+    const patch = Diff.structuredPatch("file", "file", previousText, applied.text, "", "", { context: 3 });
+    const merged = Diff.applyPatch(currentText, patch, { fuzzFactor: RECOVERY_FUZZ_FACTOR });
+    if (typeof merged !== "string" || merged === currentText)
+        return null;
+    const firstChangedLine = findFirstChangedLine(currentText, merged) ?? applied.firstChangedLine;
+    const hasNetChange = firstChangedLine !== undefined;
+    const warnings = hasNetChange ? [recoveryWarning, ...(applied.warnings ?? [])] : [...(applied.warnings ?? [])];
+    return { text: merged, firstChangedLine, warnings };
+}
+function collectAnchorLines(edits) {
+    const lines = [];
+    for (const edit of edits) {
+        for (const anchor of getEditAnchors(edit))
+            lines.push(anchor.line);
+    }
+    return lines;
+}
+function getEditAnchors(edit) {
+    if (edit.kind === "delete")
+        return [edit.anchor];
+    // Recovery only ever receives already-resolved edits (no `block`); this arm
+    // exists for type-exhaustiveness over the full `Edit` union.
+    if (edit.kind === "block")
+        return [edit.anchor];
+    return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor" ? [edit.cursor.anchor] : [];
+}
+/**
+ * Returns true when every anchor line in `edits` has identical content in
+ * `previousText` and `currentText`. The session-chain replay fast-path
+ * requires this: if the prior in-session edit rewrote the line the model is
+ * now re-targeting with a stale hash, replaying onto current would silently
+ * overwrite the new content with whatever the model authored against the
+ * old content — a corruption window, not a recovery.
+ */
+function verifyAnchorContent(previousText, currentText, edits) {
+    const lines = collectAnchorLines(edits);
+    if (lines.length === 0)
+        return true;
+    const prev = previousText.split("\n");
+    const curr = currentText.split("\n");
+    for (const line of lines) {
+        const idx = line - 1;
+        if (idx < 0 || idx >= prev.length || idx >= curr.length)
+            return false;
+        if (prev[idx] !== curr[idx])
+            return false;
+    }
+    return true;
+}
+function replaySessionChainOnCurrent(previousText, currentText, edits) {
+    // Two guards narrow the corruption window. Neither alone is sufficient,
+    // and even together they don't fully prove correctness — replay is the
+    // less-certain recovery mode and emits RECOVERY_SESSION_REPLAY_WARNING
+    // so the caller can verify the diff.
+    //   - Equal line counts: every line number in `edits` still resolves to
+    //     SOME logical row (no net shift across the prior chain). A
+    //     coincidental insert+delete pair can still leave indices pointing
+    //     at different logical rows than the model anchored against.
+    //   - Anchor-content alignment: the row at each anchor's line index has
+    //     identical content in previous and current. Catches the common
+    //     case of a prior edit rewriting the targeted line; can still be
+    //     coincidentally satisfied by a duplicated row at the shifted
+    //     index.
+    if (previousText.split("\n").length !== currentText.split("\n").length)
+        return null;
+    if (!verifyAnchorContent(previousText, currentText, edits))
+        return null;
+    let applied;
+    try {
+        applied = applyEdits(currentText, [...edits]);
+    }
+    catch {
+        return null;
+    }
+    if (applied.text === currentText)
+        return null;
+    return {
+        text: applied.text,
+        firstChangedLine: applied.firstChangedLine,
+        warnings: [RECOVERY_SESSION_REPLAY_WARNING, ...(applied.warnings ?? [])],
+    };
+}
+/** First 1-indexed line at which `a` and `b` diverge, or `undefined` if equal. */
+function findFirstChangedLine(a, b) {
+    if (a === b)
+        return undefined;
+    const aLines = a.split("\n");
+    const bLines = b.split("\n");
+    const max = Math.max(aLines.length, bLines.length);
+    for (let i = 0; i < max; i++) {
+        if (aLines[i] !== bLines[i])
+            return i + 1;
+    }
+    return undefined;
+}
+function isHeadSnapshot(head, snapshot) {
+    return head === snapshot;
+}
+/**
+ * Stateless recovery driver over a {@link SnapshotStore}. Construct once and
+ * call {@link Recovery.tryRecover} per stale-tag incident. The default
+ * implementation tries two strategies in order:
+ *
+ * 1. Apply the edits on the full-file version the tag names, then 3-way-merge
+ *    the resulting patch onto the live content (handles external writes).
+ * 2. (Session chain) If that version wasn't the head, replay the edits onto
+ *    the live content directly when line counts match AND every edit's anchor
+ *    line content is unchanged between version and current — a prior in-session
+ *    edit advanced the tag and the model's anchors still name the same logical
+ *    rows. Emits a dedicated {@link RECOVERY_SESSION_REPLAY_WARNING} because
+ *    even with both guards a coincidental insert+delete pair on duplicate rows
+ *    can still land the edit on the wrong row; see {@link replaySessionChainOnCurrent}.
+ */
+export class Recovery {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Attempt recovery. Returns `null` when no path forward is found — the
+     * caller should then surface a {@link MismatchError}.
+     */
+    tryRecover(args) {
+        const { path, currentText, fileHash, edits } = args;
+        const snapshot = this.store.byHash(path, fileHash);
+        if (!snapshot)
+            return null;
+        const isHead = isHeadSnapshot(this.store.head(path), snapshot);
+        const recoveryWarning = isHead ? RECOVERY_EXTERNAL_WARNING : RECOVERY_SESSION_CHAIN_WARNING;
+        const merged = applyEditsToSnapshot(snapshot.text, currentText, edits, recoveryWarning);
+        if (merged !== null)
+            return merged;
+        // Session-chain fallback: the 3-way merge on the version refused.
+        // Replay onto current is gated by line-count equality AND
+        // anchor-content alignment — see `replaySessionChainOnCurrent`
+        // for why both guards together still don't fully prove correctness.
+        if (!isHead)
+            return replaySessionChainOnCurrent(snapshot.text, currentText, edits);
+        return null;
+    }
+}
+//# sourceMappingURL=recovery.js.map

package/dist/hashline/recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.js","sourceRoot":"","sources":["../../src/hashline/recovery.ts"],"names":[],"mappings":"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"}

package/dist/hashline/snapshots.d.ts

@@ -0,0 +1,62 @@
+/**
+ * One full-file version observed at a point in time. The tag the model sees is
+ * {@link Snapshot.hash}; recovery replays edits against {@link Snapshot.text}.
+ */
+export interface Snapshot {
+    /** Canonical path this version belongs to. */
+    readonly path: string;
+    /** Full normalized (LF, no BOM) file text as observed. */
+    readonly text: string;
+    /** Content-derived tag for {@link Snapshot.text} (see {@link computeFileHash}). */
+    readonly hash: string;
+    /** Timestamp (ms since epoch) the version was recorded. */
+    recordedAt: number;
+}
+/**
+ * Storage seam for full-file version snapshots. The patcher calls {@link head}
+ * for the latest version of a path and {@link byHash} when it needs the
+ * specific historical version a section's stale tag names.
+ */
+export declare abstract class SnapshotStore {
+    /** Most-recently recorded version for `path`, or `null` if none. */
+    abstract head(path: string): Snapshot | null;
+    /** Recorded version for `path` whose tag equals `hash`, or `null`. */
+    abstract byHash(path: string, hash: string): Snapshot | null;
+    /** Record the full normalized text of `path` and return its content tag. */
+    abstract record(path: string, fullText: string): string;
+    /** Drop the version history for a single path. */
+    abstract invalidate(path: string): void;
+    /** Drop every version history. */
+    abstract clear(): void;
+}
+export interface InMemorySnapshotStoreOptions {
+    /** Maximum number of distinct paths tracked at once (default 30). LRU eviction. */
+    maxPaths?: number;
+    /** Maximum full-file versions retained per path (default 4). Oldest dropped first. */
+    maxVersionsPerPath?: number;
+    /**
+     * Clock used to stamp {@link Snapshot.recordedAt}. Defaults to `Date.now`;
+     * injectable so tests stay deterministic. (recordedAt is advisory only —
+     * recency ordering uses the version array order, not the timestamp.)
+     */
+    now?: () => number;
+}
+/**
+ * In-memory {@link SnapshotStore} backed by {@link LruMap}. Per-path history is
+ * a short ring of full-file versions (oldest dropped first); per-session path
+ * tracking is LRU-bounded so cold paths age out automatically.
+ *
+ * Recording byte-identical content again refreshes recency and reuses the
+ * existing tag (read fusion); recording new content unshifts a fresh version
+ * onto the front of the path history.
+ */
+export declare class InMemorySnapshotStore extends SnapshotStore {
+    #private;
+    constructor(options?: InMemorySnapshotStoreOptions);
+    head(path: string): Snapshot | null;
+    byHash(path: string, hash: string): Snapshot | null;
+    record(path: string, fullText: string): string;
+    invalidate(path: string): void;
+    clear(): void;
+}
+//# sourceMappingURL=snapshots.d.ts.map

package/dist/hashline/snapshots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshots.d.ts","sourceRoot":"","sources":["../../src/hashline/snapshots.ts"],"names":[],"mappings":"AA6BA;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,8BAAsB,aAAa;IACjC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAE5C,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAE5D,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAEvD,kDAAkD;IAClD,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAEvC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,IAAI,IAAI;CACvB;AA8CD,MAAM,WAAW,4BAA4B;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,aAAa;;gBAK1C,OAAO,GAAE,4BAAiC;IAOtD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAInC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAKnD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAoB9C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,KAAK,IAAI,IAAI;CAGd"}