jeopi-hashline 16.2.13

package/src/block.ts

@@ -0,0 +1,168 @@
+/**
+ * Expand deferred block edits (`replace_block N:` / `delete_block N` /
+ * `insert_after_block N:`) into concrete inserts + deletes.
+ *
+ * The hashline parser cannot expand a block edit on its own — the line span is
+ * unknown until file text + path (→ language) are available. This transform
+ * runs at every apply/preview boundary that has text: it calls the injected
+ * {@link BlockResolver} to resolve each block's `[start, end]` span, then emits
+ * the exact same edits the concrete form produces in the parser: `replace
+ * start.=end:` inserts + deletes for a replace, a pure range delete for a
+ * delete, and plain `after_anchor` inserts at `end` for an insert-after. After
+ * it runs, no `block` edits remain, so {@link applyEdits} (and recovery) only
+ * ever see resolved edits.
+ */
+import { STRUCTURAL_CLOSER_RE } from "./apply";
+import {
+	BLOCK_RESOLVER_UNAVAILABLE,
+	blockSingleLineMessage,
+	blockUnresolvedMessage,
+	insertAfterBlockCloserLoweredWarning,
+	insertAfterBlockUnresolvedLoweredWarning,
+} from "./messages";
+import type { BlockResolution, BlockResolver, Cursor, Edit } from "./types";
+
+export interface ResolveBlockEditsOptions {
+	/**
+	 * How to handle a replace/delete block edit that cannot be resolved
+	 * (missing resolver or a `null` span). `"throw"` (default) raises a
+	 * `blockUnresolvedMessage` error — used by the authoritative apply + final
+	 * preview paths. `"drop"` silently skips the edit — used by the streaming
+	 * preview, where a half-written file or transient parse error must not
+	 * throw. Unresolvable `insert_after_block N:` edits never reach this: they
+	 * are lowered to plain `insert after N:` with a warning.
+	 */
+	onUnresolved?: "throw" | "drop";
+	/**
+	 * Invoked once per successfully resolved block edit, in patch order, with
+	 * the anchor line and the concrete span it resolved to. Lets the host echo
+	 * the resolution back to the caller. Never fired for dropped/unresolvable
+	 * edits.
+	 */
+	onResolved?: (resolution: BlockResolution) => void;
+	/**
+	 * Invoked once per diagnostic produced while resolving — currently the
+	 * `insert_after_block N:` lowerings (closer anchor or unresolvable block).
+	 * Hosts should surface these on the apply result's `warnings`.
+	 */
+	onWarning?: (message: string) => void;
+}
+
+/** True when at least one edit is an unresolved deferred block edit. */
+export function hasBlockEdit(edits: readonly Edit[]): boolean {
+	return edits.some(edit => edit.kind === "block");
+}
+
+/**
+ * Resolve every deferred block edit in `edits` against `text` (parsed as the
+ * language inferred from `path`). Non-block edits pass through untouched.
+ * Returns a fresh edit list with no `block` variants. The fast path returns the
+ * input unchanged when there is nothing to resolve.
+ *
+ * Synthesized inserts/deletes carry sequential `index` values for readability
+ * only — {@link applyEdits} re-derives every edit's index from array order, so
+ * the passthrough edits keeping their original indices is harmless.
+ */
+export function resolveBlockEdits(
+	edits: readonly Edit[],
+	text: string,
+	path: string,
+	resolver: BlockResolver | undefined,
+	options: ResolveBlockEditsOptions = {},
+): readonly Edit[] {
+	if (!hasBlockEdit(edits)) return edits;
+	const onUnresolved = options.onUnresolved ?? "throw";
+	const resolved: Edit[] = [];
+	let synthIndex = 0;
+	for (const edit of edits) {
+		if (edit.kind !== "block") {
+			resolved.push(edit);
+			continue;
+		}
+		const op = edit.mode === "insert_after" ? "insert_after" : edit.payloads.length === 0 ? "delete" : "replace";
+		const span = resolver ? resolver({ path, text, line: edit.anchor.line }) : null;
+		if (span === null) {
+			// `insert_after_block N:` never fails the patch — lower it to plain
+			// `insert after N:` with a warning instead. Two flavors:
+			// - anchored on a pure closing-delimiter line: no block begins
+			//   there, but line N IS the end of one, and "after the end of the
+			//   block" is exactly the plain form — warn with the opener rule.
+			// - otherwise (unsupported language, blank line, unparsable block,
+			//   or no resolver wired): "after the block at N" degrades to
+			//   "after line N" — warn to verify the landing line.
+			if (op === "insert_after") {
+				const anchorText = text.split("\n")[edit.anchor.line - 1];
+				const isCloser = anchorText !== undefined && STRUCTURAL_CLOSER_RE.test(anchorText);
+				options.onWarning?.(
+					isCloser
+						? insertAfterBlockCloserLoweredWarning(edit.anchor.line)
+						: insertAfterBlockUnresolvedLoweredWarning(edit.anchor.line),
+				);
+				for (const payload of edit.payloads) {
+					const cursor: Cursor = { kind: "after_anchor", anchor: { line: edit.anchor.line } };
+					resolved.push({ kind: "insert", cursor, text: payload, lineNum: edit.lineNum, index: synthIndex++ });
+				}
+				continue;
+			}
+			if (onUnresolved === "drop") continue;
+			throw new Error(
+				`line ${edit.lineNum}: ${
+					resolver ? blockUnresolvedMessage(edit.anchor.line, op, text.split("\n")) : BLOCK_RESOLVER_UNAVAILABLE
+				}`,
+			);
+		}
+		if (span.start === span.end) {
+			// A single-line block resolution means line N is a bare statement, not
+			// the opening line of a multi-line construct — the common mis-anchor
+			// that lands a body in the wrong scope (e.g. between a `case` body line
+			// and its `break;`). The plain op is exact for one line, so reject and
+			// point at it; drop instead on the lenient preview path.
+			if (onUnresolved === "drop") continue;
+			throw new Error(`line ${edit.lineNum}: ${blockSingleLineMessage(edit.anchor.line, op)}`);
+		}
+		options.onResolved?.({
+			anchorLine: edit.anchor.line,
+			start: span.start,
+			end: span.end,
+			op,
+		});
+		if (op === "insert_after") {
+			// Mirror the parser's `insert after N:` lowering: one `after_anchor`
+			// insert per payload row, anchored on the block's last line. The
+			// `blockStart` tag lets the applier's landing correction slide a
+			// body that claims a depth inside the block back across the block's
+			// trailing closer lines.
+			for (const payload of edit.payloads) {
+				const cursor: Cursor = { kind: "after_anchor", anchor: { line: span.end } };
+				resolved.push({
+					kind: "insert",
+					cursor,
+					text: payload,
+					lineNum: edit.lineNum,
+					index: synthIndex++,
+					blockStart: span.start,
+				});
+			}
+			continue;
+		}
+		// Mirror the parser's `replace start.=end:` expansion exactly: one
+		// `before_anchor` replacement insert per payload row at `span.start`,
+		// then one delete per line across `[span.start, span.end]`. An empty
+		// `payloads` (from `delete_block N`) emits no inserts — a pure deletion.
+		for (const payload of edit.payloads) {
+			const cursor: Cursor = { kind: "before_anchor", anchor: { line: span.start } };
+			resolved.push({
+				kind: "insert",
+				cursor,
+				text: payload,
+				lineNum: edit.lineNum,
+				index: synthIndex++,
+				mode: "replacement",
+			});
+		}
+		for (let line = span.start; line <= span.end; line++) {
+			resolved.push({ kind: "delete", anchor: { line }, lineNum: edit.lineNum, index: synthIndex++ });
+		}
+	}
+	return resolved;
+}

package/src/diff-preview.ts

@@ -0,0 +1,124 @@
+/**
+ * Re-number a unified diff that uses the `+<lineNum>|content` /
+ * `-<lineNum>|content` / ` <lineNum>|content` line format into a compact
+ * current-file preview. Removed lines are counted for stats and post-edit
+ * offset tracking, but omitted from the preview. Added and context lines are
+ * anchored to their post-edit positions so a follow-up edit can reuse visible
+ * concrete lines directly. Long contiguous added runs are summarized with a
+ * `…` marker instead of echoing every inserted line.
+ *
+ * This is intentionally decoupled from the diff producer: anything that
+ * emits the `<sign><lineNum>|<content>` shape works.
+ */
+import type { CompactDiffOptions, CompactDiffPreview } from "./types";
+
+const DEFAULT_ADDED_RUN_CONTEXT_LINES = 2;
+
+const PREVIEW_ELISION_MARKER = "…";
+/** Blank row separating non-contiguous regions of a numbered diff. */
+const PREVIEW_GAP_ROW = "";
+const RAW_ELISION_MARKERS = new Set(["...", PREVIEW_ELISION_MARKER, `+${PREVIEW_ELISION_MARKER}`]);
+
+function isPreviewSeparator(line: string | undefined): boolean {
+	return line === PREVIEW_ELISION_MARKER || line === PREVIEW_GAP_ROW;
+}
+
+function appendPreviewLine(output: string[], line: string): void {
+	const normalized = RAW_ELISION_MARKERS.has(line) ? PREVIEW_ELISION_MARKER : line;
+	// Separators (elision markers, blank gap rows) never stack: omitted
+	// removed lines between two separators would otherwise leave them
+	// adjacent. A leading separator is dropped outright.
+	if (isPreviewSeparator(normalized) && (output.length === 0 || isPreviewSeparator(output[output.length - 1]))) {
+		return;
+	}
+	output.push(normalized);
+}
+
+interface ParsedDiffLine {
+	kind: "+" | "-" | " ";
+	lineNumber: number;
+	content: string;
+}
+
+function normalizeAddedRunContext(value: number | undefined): number {
+	if (value === undefined || !Number.isFinite(value)) return DEFAULT_ADDED_RUN_CONTEXT_LINES;
+	return Math.max(1, Math.trunc(value));
+}
+
+function parseNumberedDiffLine(line: string): ParsedDiffLine | undefined {
+	const kind = line[0];
+	if (kind !== "+" && kind !== "-" && kind !== " ") return undefined;
+
+	const body = line.slice(1);
+	const sep = body.indexOf("|");
+	if (sep === -1) return undefined;
+
+	const lineNumber = Number.parseInt(body.slice(0, sep), 10);
+	if (!Number.isFinite(lineNumber)) return undefined;
+
+	return { kind, lineNumber, content: body.slice(sep + 1) };
+}
+
+function appendAddedRun(output: string[], run: string[], edgeLines: number): void {
+	if (run.length === 0) return;
+
+	const collapseThreshold = edgeLines * 2 + 1;
+	if (run.length <= collapseThreshold) {
+		for (const text of run) appendPreviewLine(output, text);
+		return;
+	}
+
+	for (let i = 0; i < edgeLines; i++) appendPreviewLine(output, run[i]);
+	appendPreviewLine(output, PREVIEW_ELISION_MARKER);
+	for (let i = run.length - edgeLines; i < run.length; i++) appendPreviewLine(output, run[i]);
+}
+
+export function buildCompactDiffPreview(diff: string, options: CompactDiffOptions = {}): CompactDiffPreview {
+	const lines = diff.length === 0 ? [] : diff.split("\n");
+	const addedRunContext = normalizeAddedRunContext(options.maxAddedRunContext ?? options.maxUnchangedRun);
+	let addedLines = 0;
+	let removedLines = 0;
+	const formatted: string[] = [];
+	const addedRun: string[] = [];
+
+	const flushAddedRun = (): void => {
+		appendAddedRun(formatted, addedRun, addedRunContext);
+		addedRun.length = 0;
+	};
+
+	// External diff producers number `+` lines with the post-edit line number,
+	// `-` lines with the pre-edit line number, and context lines with the
+	// pre-edit line number. To emit fresh line numbers usable for follow-up
+	// edits, convert context-line numbers to post-edit positions by tracking
+	// the running offset (added so far - removed so far) as we walk the diff.
+	for (const line of lines) {
+		const parsed = parseNumberedDiffLine(line);
+		if (!parsed) {
+			flushAddedRun();
+			appendPreviewLine(formatted, line);
+			continue;
+		}
+
+		switch (parsed.kind) {
+			case "+": {
+				addedLines++;
+				addedRun.push(`${parsed.lineNumber}:${parsed.content}`);
+				break;
+			}
+			case "-":
+				flushAddedRun();
+				removedLines++;
+				break;
+			default: {
+				flushAddedRun();
+				const newLineNumber = parsed.lineNumber + addedLines - removedLines;
+				appendPreviewLine(formatted, `${newLineNumber}:${parsed.content}`);
+				break;
+			}
+		}
+	}
+	flushAddedRun();
+	while (formatted.length > 0 && isPreviewSeparator(formatted[formatted.length - 1])) formatted.pop();
+
+	return { preview: formatted.join("\n"), addedLines, removedLines };
+}

package/src/format.ts

@@ -0,0 +1,141 @@
+/**
+ * Hashline format primitives: sigils, separators, regex fragments, and
+ * display helpers. These are the single source of truth for the parser, the
+ * tokenizer, the prompt, and the formal grammar.
+ */
+
+import type { Cursor } from "./types";
+
+/** File-section header delimiters: `[path#hash]`. */
+export const HL_FILE_PREFIX = "[";
+export const HL_FILE_SUFFIX = "]";
+
+/** Payload sigil for literal body rows. */
+export const HL_PAYLOAD_REPLACE = "+";
+
+/** Hunk-header keyword for concrete line replacement. */
+export const HL_REPLACE_KEYWORD = "SWAP";
+/** Hunk-header keyword for concrete line deletion. */
+export const HL_DELETE_KEYWORD = "DEL";
+/** Hunk-header keyword for insertion operations. */
+export const HL_INSERT_KEYWORD = "INS";
+/** Insert position keyword for inserting before a concrete line. */
+export const HL_INSERT_BEFORE = "PRE";
+/** Insert position keyword for inserting after a concrete line. */
+export const HL_INSERT_AFTER = "POST";
+/** Insert position keyword for inserting at the start of the file. */
+export const HL_INSERT_HEAD = "HEAD";
+/** Insert position keyword for inserting at the end of the file. */
+export const HL_INSERT_TAIL = "TAIL";
+/** Hunk-header keyword: `SWAP.BLK N:` resolves N to a tree-sitter block range and replaces its span. */
+export const HL_REPLACE_BLOCK_KEYWORD = "SWAP.BLK";
+/** Hunk-header keyword: `DEL.BLK N` resolves N to a tree-sitter block range and deletes its span. */
+export const HL_DELETE_BLOCK_KEYWORD = "DEL.BLK";
+/** Hunk-header keyword: `INS.BLK.POST N:` inserts after the last line of the tree-sitter block at N. */
+export const HL_INSERT_AFTER_BLOCK_KEYWORD = "INS.BLK.POST";
+/** File-level keyword: `REM` deletes the whole file named by the section header. */
+export const HL_REM_KEYWORD = "REM";
+/** File-level keyword: `MV DEST` renames/moves the section file to `DEST`. */
+export const HL_MOVE_KEYWORD = "MV";
+export const HL_HEADER_COLON = ":";
+
+/** Separator between a hashline file path and its opaque snapshot tag. */
+export const HL_FILE_HASH_SEP = "#";
+
+/** Separator between two line numbers in a range, e.g. `5.=10`. */
+export const HL_RANGE_SEP = ".=";
+
+/** Separator between a line number and displayed line content in hashline mode. */
+export const HL_LINE_BODY_SEP = ":";
+
+function regexEscape(str: string): string {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Bare positive line-number Lid (no decorations, no captures, no anchors). */
+export const HL_LINE_RE_RAW = `[1-9]\\d*`;
+
+/** Capture-group form of {@link HL_LINE_RE_RAW}. */
+export const HL_LINE_CAPTURE_RE_RAW = `(${HL_LINE_RE_RAW})`;
+
+/** Format a concrete replacement hunk header. */
+export function formatReplaceHeader(start: number, end: number): string {
+	return `${HL_REPLACE_KEYWORD} ${start}${HL_RANGE_SEP}${end}${HL_HEADER_COLON}`;
+}
+
+/** Format a concrete deletion hunk header. */
+export function formatDeleteHeader(start: number, end = start): string {
+	return start === end ? `${HL_DELETE_KEYWORD} ${start}` : `${HL_DELETE_KEYWORD} ${start}${HL_RANGE_SEP}${end}`;
+}
+
+/** Format an insertion hunk header for a cursor position. */
+export function formatInsertHeader(cursor: Cursor): string {
+	switch (cursor.kind) {
+		case "before_anchor":
+			return `${HL_INSERT_KEYWORD}.${HL_INSERT_BEFORE} ${cursor.anchor.line}${HL_HEADER_COLON}`;
+		case "after_anchor":
+			return `${HL_INSERT_KEYWORD}.${HL_INSERT_AFTER} ${cursor.anchor.line}${HL_HEADER_COLON}`;
+		case "bof":
+			return `${HL_INSERT_KEYWORD}.${HL_INSERT_HEAD}${HL_HEADER_COLON}`;
+		case "eof":
+			return `${HL_INSERT_KEYWORD}.${HL_INSERT_TAIL}${HL_HEADER_COLON}`;
+	}
+}
+
+/** Number of hex characters in a content-derived file-hash tag. */
+export const HL_FILE_HASH_LENGTH = 4;
+/** Canonical uppercase hexadecimal content-hash tag carried by a hashline section header. */
+export const HL_FILE_HASH_RE_RAW = `[0-9A-F]{${HL_FILE_HASH_LENGTH}}`;
+/** Capture-group form of {@link HL_FILE_HASH_RE_RAW}. */
+export const HL_FILE_HASH_CAPTURE_RE_RAW = `(${HL_FILE_HASH_RE_RAW})`;
+/** Regex-escaped form of {@link HL_LINE_BODY_SEP}, safe for embedding inside a regex. */
+export const HL_LINE_BODY_SEP_RE_RAW = regexEscape(HL_LINE_BODY_SEP);
+/**
+ * Representative file-hash tags for use in user-facing error messages and
+ * prompt examples.
+ */
+export const HL_FILE_HASH_EXAMPLES = ["1A2B", "3C4D", "9F3E"] as const;
+/**
+ * Normalize text before hashing: trim trailing `[ \t\r]` from every line (and
+ * the final line) in a single pass so CRLF endings and display-trimmed lines
+ * do not invalidate a tag.
+ */
+function normalizeFileHashText(text: string): string {
+	return text.replace(/[ \t\r]+(?=\n|$)/g, "");
+}
+/**
+ * Compute the content-derived hash tag carried by a hashline section header.
+ * The tag is a 4-hex fingerprint of the whole file's normalized text: any read
+ * of byte-identical content mints the same tag, and a follow-up edit anchored
+ * at any line validates whenever the live file still hashes to it.
+ */
+export function computeFileHash(text: string): string {
+	const normalized = normalizeFileHashText(text);
+	const low16 = Bun.hash.xxHash32(normalized, 0) & 0xffff;
+	return low16.toString(16).padStart(HL_FILE_HASH_LENGTH, "0").toUpperCase();
+}
+
+/**
+ * Format a comma-separated list of example anchors with an optional line-number
+ * prefix, quoted for inclusion in error messages: `"160", "42", "7"`.
+ */
+export function describeAnchorExamples(linePrefix = ""): string {
+	const examples = linePrefix ? [linePrefix, `${linePrefix.slice(0, -1) || "4"}2`, "7"] : ["160", "42", "7"];
+	return examples.map(e => `"${e}"`).join(", ");
+}
+
+/** Format a hashline section header for a file path and snapshot tag. */
+export function formatHashlineHeader(filePath: string, fileHash: string): string {
+	return `${HL_FILE_PREFIX}${filePath}${HL_FILE_HASH_SEP}${fileHash}${HL_FILE_SUFFIX}`;
+}
+
+/** Formats a single numbered line as `LINE:TEXT`. */
+export function formatNumberedLine(lineNumber: number, line: string): string {
+	return `${lineNumber}${HL_LINE_BODY_SEP}${line}`;
+}
+
+/** Format file text with hashline-mode line-number prefixes for display. */
+export function formatNumberedLines(text: string, startLine = 1): string {
+	const lines = text.split("\n");
+	return lines.map((line, i) => formatNumberedLine(startLine + i, line)).join("\n");
+}

package/src/fs.ts

@@ -0,0 +1,246 @@
+/**
+ * Storage seam for the hashline patcher. {@link Filesystem} is intentionally
+ * minimal — `readText`, `writeText`, `exists` — so any backing store can be
+ * adapted: disk, memory, S3, an LSP text-document protocol, a Git tree, a
+ * VFS, etc.
+ *
+ * The patcher does its own BOM stripping and LF normalization between
+ * {@link Filesystem.readText} and {@link Filesystem.writeText}; the FS deals
+ * only in raw text strings.
+ */
+import * as fs from "node:fs/promises";
+import * as pathModule from "node:path";
+
+/**
+ * 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 class NotFoundError extends Error {
+	readonly code = "ENOENT";
+
+	constructor(path: string, cause?: unknown) {
+		super(`File not found: ${path}`);
+		this.name = "NotFoundError";
+		if (cause !== undefined) (this as Error & { cause?: unknown }).cause = cause;
+	}
+}
+
+/** Type guard for {@link NotFoundError} and structurally-compatible errors. */
+export function isNotFound(error: unknown): boolean {
+	if (error instanceof NotFoundError) return true;
+	if (error instanceof Error && (error as Error & { code?: string }).code === "ENOENT") return true;
+	return false;
+}
+
+/**
+ * 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 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. */
+	async 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. */
+	async delete(path: string): Promise<void> {
+		throw new Error(`Filesystem does not support delete: ${path}`);
+	}
+
+	/**
+	 * Move/rename `from` to `to`. When `content` is provided the destination
+	 * receives that text; otherwise implementations may preserve the source bytes.
+	 */
+	async move(from: string, to: string, content?: string): Promise<void> {
+		void content;
+		throw new Error(`Filesystem does not support move: ${from} -> ${to}`);
+	}
+
+	/** Return true when the path exists and can be read. Default: probe via {@link readText}. */
+	async exists(path: string): Promise<boolean> {
+		try {
+			await this.readText(path);
+			return true;
+		} catch (error) {
+			if (isNotFound(error)) return false;
+			throw error;
+		}
+	}
+
+	/**
+	 * 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 {
+		return path;
+	}
+
+	/**
+	 * 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 {
+		return true;
+	}
+}
+
+/**
+ * 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 class InMemoryFilesystem extends Filesystem {
+	#files = new Map<string, string>();
+
+	constructor(initial?: Iterable<readonly [string, string]>) {
+		super();
+		if (initial) {
+			for (const [path, content] of initial) this.#files.set(path, content);
+		}
+	}
+
+	async readText(path: string): Promise<string> {
+		const text = this.#files.get(path);
+		if (text === undefined) throw new NotFoundError(path);
+		return text;
+	}
+
+	async writeText(path: string, content: string): Promise<WriteResult> {
+		this.#files.set(path, content);
+		return { text: content };
+	}
+
+	async delete(path: string): Promise<void> {
+		if (!this.#files.delete(path)) throw new NotFoundError(path);
+	}
+
+	async move(from: string, to: string, content?: string): Promise<void> {
+		const existing = this.#files.get(from);
+		if (existing === undefined) throw new NotFoundError(from);
+		const finalContent = content ?? existing;
+		this.#files.set(to, finalContent);
+		this.#files.delete(from);
+	}
+
+	async exists(path: string): Promise<boolean> {
+		return this.#files.has(path);
+	}
+
+	/** Synchronous helper for setting up fixtures without awaiting. */
+	set(path: string, content: string): void {
+		this.#files.set(path, content);
+	}
+
+	/** Synchronous helper for inspecting state without awaiting. */
+	get(path: string): string | undefined {
+		return this.#files.get(path);
+	}
+
+	/** Wipe all entries. */
+	clear(): void {
+		this.#files.clear();
+	}
+
+	/** Iterate `[path, content]` pairs. */
+	entries(): IterableIterator<[string, string]> {
+		return this.#files.entries();
+	}
+}
+
+/**
+ * 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 class NodeFilesystem extends Filesystem {
+	async readText(path: string): Promise<string> {
+		const file = Bun.file(path);
+		if (!(await file.exists())) throw new NotFoundError(path);
+		return file.text();
+	}
+
+	async readBinary(path: string): Promise<Uint8Array> {
+		try {
+			return await fs.readFile(path);
+		} catch (error) {
+			if (isNotFound(error)) throw new NotFoundError(path, error);
+			throw error;
+		}
+	}
+
+	async writeText(path: string, content: string): Promise<WriteResult> {
+		await Bun.write(path, content);
+		return { text: content };
+	}
+
+	async delete(path: string): Promise<void> {
+		try {
+			await fs.rm(path);
+		} catch (error) {
+			if (isNotFound(error)) throw new NotFoundError(path, error);
+			throw error;
+		}
+	}
+
+	async move(from: string, to: string, content?: string): Promise<void> {
+		if (content !== undefined) {
+			await Bun.write(to, content);
+			await this.delete(from);
+			return;
+		}
+		try {
+			await fs.rename(from, to);
+		} catch (error) {
+			if (isNotFound(error)) throw new NotFoundError(from, error);
+			throw error;
+		}
+	}
+
+	canonicalPath(path: string): string {
+		return pathModule.resolve(path);
+	}
+
+	async exists(path: string): Promise<boolean> {
+		return Bun.file(path).exists();
+	}
+}