@oh-my-pi-zen/hashline 16.3.6-zen.1

package/dist/types/fs.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Result returned by {@link Filesystem.writeText}. The patcher echoes back
+ * `text` so adapters that transform on serialization (e.g. notebooks) can
+ * report what actually landed on disk.
+ */
+export interface WriteResult {
+    /** Final text that was persisted. May differ from the input if the FS transformed it. */
+    text: string;
+}
+import type { FileOp } from "./types";
+/** Optional hints for {@link Filesystem.preflightWrite}. */
+export interface PreflightWriteOptions {
+    fileOp?: FileOp;
+}
+/**
+ * ENOENT-like error thrown by {@link Filesystem.readText} when a path is
+ * missing. Carrying a `code` property keeps the contract compatible with
+ * `node:fs` callers that already check `err.code === "ENOENT"`.
+ */
+export declare class NotFoundError extends Error {
+    readonly code = "ENOENT";
+    constructor(path: string, cause?: unknown);
+}
+/** Type guard for {@link NotFoundError} and structurally-compatible errors. */
+export declare function isNotFound(error: unknown): boolean;
+/**
+ * Abstract storage backend the {@link Patcher} reads from and writes to.
+ * Subclass for new backends; the package ships {@link InMemoryFilesystem} and
+ * {@link NodeFilesystem} for the most common cases.
+ *
+ * Implementations work with raw text — the patcher handles BOM stripping and
+ * line-ending normalization itself. `readText` MUST throw {@link
+ * NotFoundError} (or any error for which {@link isNotFound} returns true)
+ * when the path doesn't exist; that's how the patcher detects a create-vs-
+ * update.
+ */
+export declare abstract class Filesystem {
+    /** Read the file's full text content. Throw on missing file. */
+    abstract readText(path: string): Promise<string>;
+    /** Read raw bytes for backends whose text is a direct decode of persisted bytes. */
+    readBinary?(path: string): Promise<Uint8Array | undefined>;
+    /** Validate that `path` is writable before a prepared batch starts committing. */
+    preflightWrite(_path: string, _options?: PreflightWriteOptions): Promise<void>;
+    /** Persist `content` at `path`. Returns the actual final text that was written. */
+    abstract writeText(path: string, content: string): Promise<WriteResult>;
+    /** Delete the file at `path`. Default: not supported. */
+    delete(path: string): Promise<void>;
+    /**
+     * Move/rename `from` to `to`. When `content` is provided the destination
+     * receives that text; otherwise implementations may preserve the source bytes.
+     */
+    move(from: string, to: string, content?: string): Promise<void>;
+    /** Return true when the path exists and can be read. Default: probe via {@link readText}. */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Canonical path used as a key by external caches (e.g. snapshot
+     * stores). The default is identity; override to return an absolute or
+     * otherwise canonicalised path so producers and consumers of cached
+     * snapshots agree on the key without each having to redo the resolution.
+     */
+    canonicalPath(path: string): string;
+    /**
+     * Whether a section whose authored path is missing may be redirected to
+     * the file its snapshot tag names (tag-based path recovery in
+     * {@link Patcher.prepare}). `resolvedPath` is the canonical path the
+     * redirect would read and write. Default: allow.
+     *
+     * Hosts that grant write privileges by path shape override this to refuse
+     * redirects that could escalate beyond what the caller approved — e.g. an
+     * internal-URL authored target (approved read-only), or a `resolvedPath`
+     * outside the working tree (a sandbox/vault/out-of-tree write).
+     */
+    allowTagPathRecovery(_authoredPath: string, _resolvedPath: string): boolean;
+}
+/**
+ * In-memory {@link Filesystem}. Useful for tests, sandboxes, dry-runs, and as
+ * a building block for stacked adapters (e.g. an LRU layer on top).
+ */
+export declare class InMemoryFilesystem extends Filesystem {
+    #private;
+    constructor(initial?: Iterable<readonly [string, string]>);
+    readText(path: string): Promise<string>;
+    writeText(path: string, content: string): Promise<WriteResult>;
+    delete(path: string): Promise<void>;
+    move(from: string, to: string, content?: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    /** Synchronous helper for setting up fixtures without awaiting. */
+    set(path: string, content: string): void;
+    /** Synchronous helper for inspecting state without awaiting. */
+    get(path: string): string | undefined;
+    /** Wipe all entries. */
+    clear(): void;
+    /** Iterate `[path, content]` pairs. */
+    entries(): IterableIterator<[string, string]>;
+}
+/**
+ * Disk-backed {@link Filesystem} using Bun's file APIs. The default for CLI
+ * use. Paths are accepted as-is; callers responsible for any cwd or
+ * jail/sandbox resolution should wrap this with their own subclass.
+ */
+export declare class NodeFilesystem extends Filesystem {
+    readText(path: string): Promise<string>;
+    readBinary(path: string): Promise<Uint8Array>;
+    writeText(path: string, content: string): Promise<WriteResult>;
+    delete(path: string): Promise<void>;
+    move(from: string, to: string, content?: string): Promise<void>;
+    canonicalPath(path: string): string;
+    exists(path: string): Promise<boolean>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./apply";
+export * from "./block";
+export * from "./diff-preview";
+export * from "./format";
+export * from "./fs";
+export * from "./input";
+export * from "./messages";
+export * from "./mismatch";
+export * from "./normalize";
+export * from "./parser";
+export * from "./patcher";
+export * from "./prefixes";
+export * from "./recovery";
+export * from "./snapshots";
+export * from "./stream";
+export * from "./tokenizer";
+export * from "./types";

package/dist/types/input.d.ts

@@ -0,0 +1,110 @@
+import type { ApplyResult, BlockResolver, Edit, FileOp, SplitOptions } from "./types";
+interface RawSection {
+    path: string;
+    fileHash?: string;
+    diff: string;
+}
+/**
+ * Returns true when the input contains at least one line that the tokenizer
+ * recognizes as a hashline op. Used by streaming previews to decide whether
+ * the partial input is worth treating as a hashline patch yet.
+ */
+export declare function containsRecognizableHashlineOperations(input: string): boolean;
+/**
+ * Snapshot of one section in a parsed {@link Patch}: a target file plus the
+ * lazily-parsed list of edits that should land on it. Constructed by
+ * {@link Patch.parse}; consumers usually iterate `patch.sections` rather
+ * than build these directly.
+ */
+export declare class PatchSection {
+    #private;
+    readonly path: string;
+    readonly fileHash: string | undefined;
+    readonly diff: string;
+    constructor(raw: RawSection);
+    /**
+     * Parse this section's diff body. Cached: subsequent calls return the
+     * same `{ edits, fileOp?, warnings }` object so callers can safely call this from
+     * multiple paths (preflight, apply, diff-preview).
+     */
+    parse(): {
+        edits: Edit[];
+        fileOp?: FileOp;
+        warnings: readonly string[];
+    };
+    /** Parsed edits for this section. */
+    get edits(): readonly Edit[];
+    /** Optional whole-file operation (`REM` / `MV`). */
+    get fileOp(): FileOp | undefined;
+    /** Warnings emitted during parsing of this section. */
+    get warnings(): readonly string[];
+    /**
+     * True when at least one edit anchors to concrete file content. Pure
+     * `insert head:` / `insert tail:` literal inserts do not count: those are
+     * safe to apply to files that don't yet exist.
+     */
+    get hasAnchorScopedEdit(): boolean;
+    /** Anchor lines touched by this section, sorted ascending and deduplicated. */
+    collectAnchorLines(): readonly number[];
+    /**
+     * Apply this section's edits to `text` and return the post-edit result.
+     * Pure: does no I/O, does not validate the section snapshot tag. The
+     * {@link Patcher} owns tag validation and recovery; reach for this
+     * method directly when you've already validated the file content and
+     * just want the result.
+     *
+     * `blockResolver` resolves any `replace_block N:` edits against `text`; an
+     * unresolvable block throws (this is the final, authoritative preview path).
+     */
+    applyTo(text: string, blockResolver?: BlockResolver): ApplyResult;
+    /**
+     * Streaming-tolerant counterpart to {@link applyTo}. Uses
+     * {@link parsePatchStreaming} so a trailing in-flight op (no payload yet,
+     * or a per-token parse error mid-stream) does not throw or emit a phantom
+     * empty-payload edit. Intended for incremental diff previews; the writer
+     * path should always use {@link applyTo}.
+     *
+     * `blockResolver` resolves any `replace_block N:` edits against `text`; an
+     * unresolvable block is silently dropped so a half-written file does not
+     * throw mid-stream.
+     */
+    applyPartialTo(text: string, blockResolver?: BlockResolver): ApplyResult;
+    /**
+     * A copy of this section rebound to a different target `path`, preserving
+     * the snapshot tag, diff body, and any cached parse result. Used by the
+     * patcher's tag-based path recovery to redirect an edit whose authored
+     * path does not exist onto the file its snapshot tag actually names.
+     */
+    withPath(path: string): PatchSection;
+}
+/**
+ * A parsed hashline patch — zero or more {@link PatchSection}s, each rooted
+ * at a `[PATH#HASH]` header. Construct via {@link Patch.parse}.
+ *
+ * `Patch` is pure data: parsing is line-anchored and does not look at the
+ * filesystem. To apply a patch, hand it to {@link Patcher.apply}.
+ */
+export declare class Patch {
+    readonly sections: readonly PatchSection[];
+    private constructor();
+    /**
+     * Parse `input` into a {@link Patch}. `options.cwd` resolves absolute
+     * paths inside headers to cwd-relative form; `options.path` provides a
+     * fallback when the input lacks a header but contains hashline ops
+     * (useful for streaming previews).
+     *
+     * Consecutive sections targeting the same path are merged into a single
+     * section with concatenated diff bodies. Anchors authored against the
+     * same file snapshot must be applied as one batch; otherwise the first
+     * sub-edit shifts line numbers out from under the second's anchors and
+     * validation fails.
+     */
+    static parse(input: string, options?: SplitOptions): Patch;
+    /**
+     * Parse `input` and return only the first section. Throws if the input
+     * has zero sections. Convenience for the single-section case where the
+     * caller already knows the patch is one hunk.
+     */
+    static parseSingle(input: string, options?: SplitOptions): PatchSection;
+}
+export {};

package/dist/types/messages.d.ts

@@ -0,0 +1,147 @@
+/** Centralized error/warning text for the hashline parser, applier, and patcher. */
+/** Lines of context shown either side of a hash mismatch. */
+export declare const MISMATCH_CONTEXT = 2;
+/**
+ * Numbered `LINE:TEXT` rows around `anchorLines` (±{@link MISMATCH_CONTEXT}),
+ * `*`-marking anchors, `...` between non-adjacent runs. Out-of-range anchors
+ * contribute no rows.
+ */
+export declare function formatAnchoredContext(anchorLines: readonly number[], fileLines: readonly string[]): string[];
+/** Optional patch envelope start marker; silently consumed. */
+export declare const BEGIN_PATCH_MARKER = "*** Begin Patch";
+/** Optional patch envelope end marker; terminates parsing. */
+export declare const END_PATCH_MARKER = "*** End Patch";
+/**
+ * Truncation sentinel emitted by an agent loop mid-call. Ends parsing like
+ * {@link END_PATCH_MARKER}, without a warning.
+ */
+export declare const ABORT_MARKER = "*** Abort";
+/** Two consecutive hunks targeted the exact same concrete range. */
+export declare const REPLACE_PAIR_COALESCED_WARNING = "Two hunks targeted the same range; kept only the second. One `SWAP N.=M:` hunk per range \u2014 the body is the final content, never old+new.";
+/** Bare body rows auto-converted to literal `+` rows. */
+export declare const BARE_BODY_AUTO_PIPED_WARNING = "Auto-prefixed bare body row(s) with `+`. Body rows must be `+TEXT` literal lines.";
+/** Unified-diff-style `-` row in a hunk body. */
+export declare const MINUS_ROW_REJECTED = "`-` rows are not valid; the range already names the lines being changed. For Markdown bullets or other literal `-` lines, prefix the literal row with `+`: `+- item`.";
+/** Replace hunk with no body. */
+export declare const EMPTY_REPLACE = "`SWAP N.=M:` needs at least one `+TEXT` body row. To delete lines, use `DEL N.=M`.";
+/** `replace_block N:` hunk with no body. */
+export declare const EMPTY_BLOCK = "`SWAP.BLK N:` needs at least one `+TEXT` body row. To delete a block, use `DEL.BLK N`.";
+/**
+ * Block-anchored replace/delete could not resolve to a syntactic block
+ * (unsupported language, blank/out-of-range line, no node beginning on N, or
+ * parse error). Appends a {@link formatAnchoredContext} preview when
+ * `fileLines` is given. `insert_after_block N:` never reaches this — it is
+ * lowered to plain `insert after N:` instead (see
+ * {@link insertAfterBlockUnresolvedLoweredWarning}).
+ */
+export declare function blockUnresolvedMessage(line: number, op?: "replace" | "delete", fileLines?: readonly string[]): string;
+/** Block-anchored edit reached a path with no {@link BlockResolver} wired in — a host-configuration bug. */
+export declare const BLOCK_RESOLVER_UNAVAILABLE = "`SWAP.BLK`/`DEL.BLK`/`INS.BLK.POST` are not available here (no block resolver configured). Use a concrete line range.";
+/**
+ * `insert_after_block N:` anchored on a closing-delimiter line, lowered to
+ * plain `insert after N:` — the closer ends a block, and inserting after it
+ * is exactly what the plain form does.
+ */
+export declare function insertAfterBlockCloserLoweredWarning(line: number): string;
+/**
+ * `insert_after_block N:` anchor unresolvable (unsupported language, blank
+ * line, parse error, or no resolver), lowered to plain `insert after N:` —
+ * applying with a warning beats failing the patch.
+ */
+export declare function insertAfterBlockUnresolvedLoweredWarning(line: number): string;
+/**
+ * Internal invariant: `applyEdits` received an unresolved `replace_block N:`
+ * edit; `resolveBlockEdits` must run first. Wiring bug, not authored input.
+ */
+export declare const UNRESOLVED_BLOCK_INTERNAL = "internal error: unresolved `SWAP.BLK` edit reached the applier (resolveBlockEdits was not run).";
+/** Delete hunk received a body row. */
+export declare const DELETE_TAKES_NO_BODY = "`DEL N.=M` does not take body rows. Remove the body, or use `SWAP N.=M:`.";
+/** `REM` received a body row or coexists with line edits. */
+export declare const REM_TAKES_NO_BODY = "`REM` deletes the whole file and takes no body rows or line ops. Issue it alone under the header.";
+/** `MV` received a body row. */
+export declare const MOVE_TAKES_NO_BODY = "`MV DEST` does not take body rows. Put line edits above the `MV` row; the destination path follows `MV` on the same line.";
+/** `delete_block N` hunk received a body row. */
+export declare const DELETE_BLOCK_TAKES_NO_BODY = "`DEL.BLK N` does not take body rows. Remove the body, or use `SWAP.BLK N:`.";
+/** Insert hunk with no body. */
+export declare const EMPTY_INSERT = "`INS` needs at least one `+TEXT` body row.";
+/**
+ * `insert after` body indented shallower than the anchor: the landing slid
+ * forward past trailing closer lines — the common "anchored on the last line
+ * I read instead of after the block" mistake.
+ */
+export declare function afterInsertLandingShiftWarning(anchorLine: number, landingLine: number, crossed: number): string;
+/**
+ * `insert_after_block N:` body indented deeper than the block's closer: the
+ * landing was pulled inside the block — a deeper body almost always means
+ * "append inside the block's body".
+ */
+export declare function blockInsertLandingShiftWarning(blockStart: number, closerLine: number, landingLine: number): string;
+/** `Recovery`: an external write matched a cached snapshot. */
+export declare const RECOVERY_EXTERNAL_WARNING = "Recovered from a stale file hash using a previous read snapshot (file changed externally between read and edit).";
+/** `Recovery`: a prior in-session edit advanced the hash. */
+export declare const RECOVERY_SESSION_CHAIN_WARNING = "Recovered from a stale file hash using an earlier in-session snapshot (a prior edit in this session advanced the hash).";
+/**
+ * `Recovery`: session-chain replay fast-path. Less certain than
+ * {@link RECOVERY_SESSION_CHAIN_WARNING} — the 3-way merge refused, the
+ * anchor-content gate passed, but a coincidental insert+delete earlier in
+ * the chain could still misplace an anchor — hence the verify hedge.
+ */
+export declare const RECOVERY_SESSION_REPLAY_WARNING = "Recovered by replaying your edits onto the current file content (a prior in-session edit changed the lines you re-targeted with a stale hash). Verify the diff matches your intent.";
+/** `Recovery`: stale anchors were relocated to unchanged live lines after drift. */
+export declare const RECOVERY_LINE_REMAP_WARNING = "Recovered by remapping stale line anchors to unchanged current lines (file changed since the tagged read). Verify the diff matches your intent.";
+/**
+ * `insert head:`/`insert tail:` applied despite a stale snapshot tag.
+ * Head/tail position is content-independent, so drift is non-fatal: apply
+ * onto live content and warn instead of hard-failing.
+ */
+export declare const HEADTAIL_DRIFT_WARNING = "Applied the `INS.HEAD:`/`INS.TAIL:` edit despite a stale snapshot tag (file changed since your read) \u2014 head/tail position is content-independent. Re-read if the drift was unexpected.";
+/**
+ * Section omitted the mandatory snapshot tag. Shared by the apply
+ * ({@link Patcher.prepare}) and preview/diff paths so both stay in lockstep.
+ */
+export declare function missingSnapshotTagMessage(sectionPath: string): string;
+/**
+ * A section named a path that does not exist, but its filename and snapshot
+ * tag together match exactly one file read earlier this session — the model
+ * gave the bare filename (or wrong directory) for a file it just read. The
+ * edit was rebound to that file's full path. Surfaced as a warning so the
+ * model (and user) learn the corrected path and stop reusing the wrong one.
+ */
+export declare function pathRecoveredFromTagMessage(authoredPath: string, resolvedPath: string, tag: string): string;
+/** One anchored line whose actual content is being surfaced in an error message. */
+export interface RevealedLine {
+    line: number;
+    text: string;
+}
+/**
+ * Content preview handed to {@link unseenLinesMessage}. `lines` are the
+ * unseen anchor lines whose actual file content we surface inline (from the
+ * tagged snapshot the caller matched). `truncated` = true means the anchor
+ * range exceeded the inline reveal cap; the caller only revealed a prefix
+ * and the remaining unseen lines still require a range re-read.
+ */
+export interface UnseenLinesReveal {
+    lines: readonly RevealedLine[];
+    truncated: boolean;
+}
+/**
+ * An anchored edit referenced lines the read that minted the cited tag never
+ * displayed (a partial range, or a structural summary that collapsed bodies).
+ * Editing lines you have not read is the off-by-memory failure that mangles
+ * files. When `reveal.lines` is non-empty, the caller has already inlined the
+ * actual file content at those lines and merged them into the snapshot's
+ * seen-line set, so the message points the model at a straight retry with the
+ * same `[path#tag]` header; when the reveal is empty or truncated, the
+ * message falls back to instructing a range re-read.
+ */
+export declare function unseenLinesMessage(sectionPath: string, unseenLines: readonly number[], tag: string, reveal?: UnseenLinesReveal): string;
+/** Op kind of a deferred block edit, for {@link blockSingleLineMessage}. */
+export type BlockOp = "replace" | "delete" | "insert_after";
+/**
+ * A `replace_block`/`delete_block`/`insert_after_block` anchor resolved to a
+ * single line — almost always a bare statement the model mis-anchored, not a
+ * multi-line construct. The plain op is unambiguous for one line; the block
+ * form only earns its keep when it spares counting a closing line you cannot
+ * see. Reject and point at both fixes.
+ */
+export declare function blockSingleLineMessage(line: number, op: BlockOp): string;

package/dist/types/mismatch.d.ts

@@ -0,0 +1,44 @@
+/** Format the required-shape diagnostic shown when a line reference is malformed. */
+export declare function formatFullAnchorRequirement(raw?: string): string;
+/** Parse a decorated bare line-number anchor like `42`, `*42:foo`, ` > 7`. */
+export declare function parseTag(ref: string): {
+    line: number;
+};
+export interface MismatchDetails {
+    path?: string;
+    expectedFileHash: string;
+    actualFileHash: string;
+    fileLines: string[];
+    anchorLines?: readonly number[];
+    /**
+     * `true` when the section's expected hash resolved to a recorded snapshot
+     * (file content drifted since that snapshot), `false` when no snapshot
+     * was ever recorded for the hash (likely fabricated or carried over from
+     * a prior session). Drives a more actionable rejection message; defaults
+     * to `true` for backward compatibility with direct callers.
+     */
+    hashRecognized?: boolean;
+}
+/**
+ * Raised when a hashline section's snapshot tag doesn't match the live file's
+ * content (and recovery, if configured, declined the merge). Carries the
+ * file lines plus anchored lines so renderers can produce a richer
+ * diagnostic via {@link MismatchError.displayMessage}.
+ */
+export declare class MismatchError extends Error {
+    readonly path: string | undefined;
+    readonly expectedFileHash: string;
+    readonly actualFileHash: string;
+    readonly fileLines: string[];
+    readonly anchorLines: readonly number[];
+    readonly hashRecognized: boolean;
+    constructor(details: MismatchDetails);
+    get displayMessage(): string;
+    static rejectionHeader(details: MismatchDetails): string[];
+    static formatDisplayMessage(details: MismatchDetails): string;
+    static formatMessage(details: MismatchDetails): string;
+}
+/** Throws when the line reference is out of bounds for the given file. */
+export declare function validateLineRef(ref: {
+    line: number;
+}, fileLines: string[]): void;

package/dist/types/normalize.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal text-shape normalization: line-ending detection / round-trip and
+ * BOM stripping. The patcher uses these to canonicalize text to LF before
+ * applying edits and to restore the original shape on write-back.
+ */
+export type LineEnding = "\r\n" | "\n";
+/** Detect the first line ending style in `content`. Defaults to LF when neither is present. */
+export declare function detectLineEnding(content: string): LineEnding;
+/** Normalize every line ending to LF. */
+export declare function normalizeToLF(text: string): string;
+/** Re-encode LF text with the requested line ending. */
+export declare function restoreLineEndings(text: string, ending: LineEnding): string;
+export interface BomResult {
+    /** Either the empty string or the BOM sequence (currently UTF-8 BOM). */
+    bom: string;
+    /** Text with any leading BOM removed. */
+    text: string;
+}
+/** Strip a UTF-8 BOM if present and return both the BOM and the trailing text. */
+export declare function stripBom(content: string): BomResult;

package/dist/types/parser.d.ts

@@ -0,0 +1,27 @@
+import { type Token } from "./tokenizer";
+import type { Edit, FileOp } from "./types";
+export declare class Executor {
+    #private;
+    feed(token: Token): void;
+    end(): {
+        edits: Edit[];
+        fileOp?: FileOp;
+        warnings: string[];
+    };
+    endStreaming(): {
+        edits: Edit[];
+        fileOp?: FileOp;
+        warnings: string[];
+    };
+    reset(): void;
+}
+export declare function parsePatch(diff: string): {
+    edits: Edit[];
+    fileOp?: FileOp;
+    warnings: string[];
+};
+export declare function parsePatchStreaming(diff: string): {
+    edits: Edit[];
+    fileOp?: FileOp;
+    warnings: string[];
+};

package/dist/types/patcher.d.ts

@@ -0,0 +1,118 @@
+import type { Filesystem } from "./fs";
+import type { Patch, PatchSection } from "./input";
+import { type LineEnding } from "./normalize";
+import { Recovery } from "./recovery";
+import type { SnapshotStore } from "./snapshots";
+import type { ApplyResult, BlockResolution, BlockResolver, FileOp } from "./types";
+export interface PatcherOptions {
+    /** Storage backend used for all reads and writes. */
+    fs: Filesystem;
+    /** Snapshot store that minted and resolves hashline section tags. Required. */
+    snapshots: SnapshotStore;
+    /**
+     * Resolves `replace_block N:` anchors to concrete line spans via tree-sitter.
+     * Optional: when omitted, any `replace_block N:` edit throws on apply (the
+     * host did not wire a resolver). Plain line-range ops never need it.
+     */
+    blockResolver?: BlockResolver;
+}
+/** Per-section result returned by {@link Patcher.apply} / {@link Patcher.commit}. */
+export interface PatchSectionResult {
+    /** Section path (as authored, after cwd-resolution at parse time). */
+    path: string;
+    /** Filesystem-canonical key for this section (e.g. absolute path). */
+    canonicalPath: string;
+    /** `"noop"` when the apply produced no change; `"delete"` removes the file; otherwise `"create"` / `"update"`. */
+    op: "create" | "update" | "delete" | "noop";
+    /** Pre-edit text (LF-normalized, BOM-stripped). */
+    before: string;
+    /** Post-edit text (LF-normalized, BOM-stripped). For `"noop"` equals `before`. */
+    after: string;
+    /** Same text as `after` but with the original BOM and line ending restored. */
+    persisted: string;
+    /** Final text that the {@link Filesystem} actually wrote (may differ if the FS transformed it). */
+    written: string;
+    /** 4-hex content-hash tag for `after`. Use to anchor follow-up edits. */
+    fileHash: string;
+    /** Hashline section header (`[path#tag]`) of the post-edit content. */
+    header: string;
+    /** 1-indexed first changed line in `after`, or `undefined` for noops. */
+    firstChangedLine?: number;
+    /** Warnings collected by the parser, applier, and (optionally) recovery. */
+    warnings: string[];
+    /** Destination path when this section includes `MV DEST`. */
+    moveDest?: string;
+    /**
+     * Resolved spans for any `replace_block`/`delete_block` ops, present when the
+     * apply matched the tagged content. Undefined for patches with no block ops
+     * (and for resolutions routed through drift recovery, where numbers shift).
+     */
+    blockResolutions?: BlockResolution[];
+}
+export interface PatcherApplyResult {
+    sections: PatchSectionResult[];
+}
+/**
+ * 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 declare class PreparedSection {
+    readonly section: PatchSection;
+    readonly canonicalPath: string;
+    readonly exists: boolean;
+    readonly rawContent: string;
+    readonly bom: string;
+    readonly lineEnding: LineEnding;
+    readonly normalized: string;
+    readonly applyResult: ApplyResult;
+    readonly parseWarnings: readonly string[];
+    readonly fileOp: FileOp | undefined;
+    /** @internal */
+    constructor(section: PatchSection, canonicalPath: string, exists: boolean, rawContent: string, bom: string, lineEnding: LineEnding, normalized: string, applyResult: ApplyResult, parseWarnings: readonly string[], fileOp: FileOp | undefined);
+    /** Convenience: returns true when the apply produced no change and no file op. */
+    get isNoop(): boolean;
+}
+/**
+ * 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 declare class Patcher {
+    #private;
+    readonly fs: Filesystem;
+    readonly snapshots: SnapshotStore;
+    readonly recovery: Recovery;
+    readonly blockResolver: BlockResolver | undefined;
+    constructor(options: PatcherOptions);
+    /**
+     * 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.
+     */
+    apply(patch: Patch): Promise<PatcherApplyResult>;
+    /**
+     * Run the preflight pass only: read, parse, validate, apply-in-memory.
+     * No writes hit the filesystem. Use for CI checks and dry runs.
+     */
+    preflight(patch: Patch): Promise<void>;
+    /**
+     * 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}).
+     */
+    prepare(section: PatchSection): Promise<PreparedSection>;
+    /**
+     * 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.
+     */
+    commit(prepared: PreparedSection): Promise<PatchSectionResult>;
+}

package/dist/types/prefixes.d.ts

@@ -0,0 +1,42 @@
+/**
+ * When a hashline payload is authored against `read`/`search` output, each
+ * line is prefixed with either a hashline-mode line number (`123:`) or, for
+ * diff-style echoes, a leading `+`. These helpers detect that and recover
+ * the raw text. Two strip modes are exposed:
+ *
+ * - {@link stripNewLinePrefixes} — opportunistic: strips when the input
+ *   clearly carries hashline or diff prefixes, leaves it alone otherwise.
+ * - {@link stripHashlinePrefixes} — strict: only strips when every non-empty
+ *   content line is hashline-prefixed.
+ *
+ * These run *before* the tokenizer; they exist because hashline mode is the
+ * common case for echoed file content, and erroneously echoed prefixes will
+ * otherwise turn every content line into a (malformed) op.
+ */
+/**
+ * Single-pass variant of {@link stripLeadingHashlinePrefixes} that strips at
+ * most one leading hashline prefix (`N:`, `>>>N:`, `+N:` etc.) and does NOT
+ * loop. Use this when the input carries at most one snapshot prefix (e.g. a
+ * bare body row paste from `read` output) — recursive stripping would corrupt
+ * content whose own text starts with `digits:`.
+ */
+export declare function stripOneLeadingHashlinePrefix(line: string): string;
+/**
+ * Strip whichever prefix scheme the lines appear to be carrying:
+ * - hashline line-number prefixes (`123:`) when every content line has one
+ * - leading `+` (diff style) when at least half the lines have one
+ * - mixed `+<n>:` form when present
+ *
+ * Returns the lines untouched if no scheme is recognized.
+ */
+export declare function stripNewLinePrefixes(lines: string[]): string[];
+/**
+ * Strict variant: strip hashline prefixes only when every content line is
+ * hashline-prefixed. Returns the lines unchanged otherwise.
+ */
+export declare function stripHashlinePrefixes(lines: string[]): string[];
+/**
+ * Normalize line payloads by stripping read/search line prefixes. `null` /
+ * `undefined` yield `[]`; a single multiline string is split on `\n`.
+ */
+export declare function hashlineParseText(edit: string[] | string | null | undefined): string[];