mixdog 0.7.1

package/src/agent/orchestrator/tools/builtin/edit-byte-plan.mjs

@@ -0,0 +1,240 @@
+import { stripTrailingWhitespaceForEdit } from '../edit-normalize.mjs';
+import {
+    bufferWithTrailingLf,
+    concatByteReplacements,
+    hashBytesWithReplacements,
+} from './edit-byte-utils.mjs';
+import {
+    countLfInString,
+    maybeAutoStripLineNumberPrefixes,
+} from './edit-context-utils.mjs';
+import { replacementForOriginalSlice } from './edit-match-utils.mjs';
+
+export function tryBuildExactEditBuffer(rawBuf, oldStr, newStr, replaceAll, snapshot, filePath) {
+    if (!Buffer.isBuffer(rawBuf) || typeof oldStr !== 'string' || oldStr.length === 0 || typeof newStr !== 'string') return null;
+    const oldBytes = Buffer.from(oldStr, 'utf-8');
+    if (oldBytes.length === 0) return null;
+    let eOldStr = oldStr;
+    let eOldBytes = oldBytes;
+    const _pureDeletion = newStr === '' && !oldStr.endsWith('\n') && !oldStr.endsWith('\r');
+    // Single-occurrence pure deletion: probe globally so the unique
+    // match also covers its trailing line terminator (CRLF first to
+    // avoid leaving a stray \r on CRLF files, then LF, then lone-CR).
+    // Replace-all pure deletion CANNOT use a single global rewrite of
+    // eOldBytes — when occurrences are mixed (some followed by \n, some
+    // bare / at EOF), an eOldBytes that includes the terminator would
+    // silently skip every bare occurrence. Per-occurrence absorption
+    // below extends each span over its own trailing \r\n / \n / \r so
+    // every match is removed regardless of what follows it.
+    if (_pureDeletion && !replaceAll) {
+        // Judge ambiguity on the BARE oldBytes BEFORE newline absorption.
+        // Absorbing a trailing terminator first can narrow a >1-occurrence
+        // bare match down to a unique extended span (e.g. 'X' present as
+        // 'X\r\n...X'), silently single-deleting instead of surfacing the
+        // ambiguous-match error. If the bare oldBytes occurs more than once
+        // return null — the same signal the spans.length>1 path emits (→ the
+        // caller's code-9 ambiguous-match error). Only absorb when the bare
+        // match is unique.
+        const _firstBare = rawBuf.indexOf(oldBytes);
+        if (_firstBare !== -1 && rawBuf.indexOf(oldBytes, _firstBare + 1) !== -1) {
+            return null;
+        }
+        const oldWithCrlf = Buffer.from(`${oldStr}\r\n`, 'utf-8');
+        const oldWithLf = bufferWithTrailingLf(oldBytes);
+        const oldWithCr = Buffer.from(`${oldStr}\r`, 'utf-8');
+        if (rawBuf.indexOf(oldWithCrlf) !== -1) {
+            eOldStr = `${oldStr}\r\n`;
+            eOldBytes = oldWithCrlf;
+        } else if (rawBuf.indexOf(oldWithLf) !== -1) {
+            eOldStr = `${oldStr}\n`;
+            eOldBytes = oldWithLf;
+        } else if (rawBuf.indexOf(oldWithCr) !== -1) {
+            eOldStr = `${oldStr}\r`;
+            eOldBytes = oldWithCr;
+        }
+    }
+    const _perOccurrenceAbsorb = _pureDeletion && replaceAll;
+    if (!replaceAll) {
+        const _fb = rawBuf.indexOf(eOldBytes);
+        if (_fb !== -1 && rawBuf.indexOf(eOldBytes, _fb + 1) !== -1) return null;
+    }
+    const spans = [];
+    let idx = 0;
+    while ((idx = rawBuf.indexOf(eOldBytes, idx)) !== -1) {
+        let _end = idx + eOldBytes.length;
+        if (_perOccurrenceAbsorb) {
+            // CRLF (\r\n) first so we don't strand a stray \r; then LF;
+            // then lone-CR. Bare / EOF occurrences leave _end as-is.
+            if (rawBuf[_end] === 0x0d && rawBuf[_end + 1] === 0x0a) _end += 2;
+            else if (rawBuf[_end] === 0x0a) _end += 1;
+            else if (rawBuf[_end] === 0x0d) _end += 1;
+        }
+        spans.push({ start: idx, end: _end });
+        if (!replaceAll && spans.length > 1) return null;
+        idx += eOldBytes.length;
+    }
+    if (spans.length === 0) return null;
+    const fileUtf8 = rawBuf.toString('utf-8');
+    const replacements = spans.map((span) => ({
+        ...span,
+        newBytes: Buffer.from(
+            replacementForOriginalSlice(newStr, rawBuf.subarray(span.start, span.end).toString('utf-8'), fileUtf8),
+            'utf-8',
+        ),
+    }));
+    const sameSize = replacements.every((span) => span.end - span.start === span.newBytes.length);
+    if (spans.length === 1) {
+        const first = spans[0].start;
+        if (sameSize) {
+            return {
+                replacements,
+                sameSize: true,
+                contentHash: hashBytesWithReplacements(rawBuf, replacements),
+            };
+        }
+        return {
+            replacements,
+            sameSize: false,
+            updated: Buffer.concat([
+                rawBuf.subarray(0, first),
+                replacements[0].newBytes,
+                rawBuf.subarray(spans[0].end),
+            ], rawBuf.length - (spans[0].end - first) + replacements[0].newBytes.length),
+        };
+    }
+    if (sameSize) {
+        return {
+            replacements,
+            sameSize: true,
+            contentHash: hashBytesWithReplacements(rawBuf, replacements),
+        };
+    }
+    return {
+        replacements,
+        sameSize: false,
+        updated: concatByteReplacements(rawBuf, replacements),
+    };
+}
+
+export function tryBuildMultiExactEditBuffer(rawBuf, edits, args, snapshot, filePath) {
+    if (!Buffer.isBuffer(rawBuf) || !Array.isArray(edits) || edits.length === 0) return null;
+    // Fast path treats every edit as locating its span in the ORIGINAL buffer
+    // and applies all replacements at once. Sequential-apply semantics differ
+    // whenever edit A's new_string can synthesise (or destroy) bytes that
+    // edit B's old_string would match. Disable the fast path unless edits
+    // are provably independent — no pair where one's new_string contains
+    // another's old_string. The slow path runs them sequentially.
+    if (edits.length > 1) {
+        for (let a = 0; a < edits.length; a++) {
+            const ea = edits[a];
+            if (!ea || typeof ea.old_string !== 'string' || typeof ea.new_string !== 'string') return null;
+            for (let b = 0; b < edits.length; b++) {
+                if (a === b) continue;
+                const eb = edits[b];
+                if (!eb || typeof eb.old_string !== 'string') return null;
+                if (eb.old_string.length === 0) continue;
+                if (ea.new_string.indexOf(eb.old_string) !== -1) return null;
+            }
+        }
+    }
+    const isMarkdown = /\.(?:md|mdx)$/i.test(filePath);
+    const replacements = [];
+    const normalizedEdits = [];
+    for (let i = 0; i < edits.length; i++) {
+        const entry = edits[i];
+        if (!entry || typeof entry.old_string !== 'string' || typeof entry.new_string !== 'string') return null;
+        let oldString = entry.old_string;
+        let newString = entry.new_string;
+        {
+            const _nulIdx = newString.indexOf('\u0000');
+            if (_nulIdx !== -1) {
+                return { error: `Error [code 11]: edit ${i} — new_string contains NUL byte (U+0000) at offset ${_nulIdx} — source text must not contain NUL: ${filePath}` };
+            }
+        }
+        const replaceAll = entry.replace_all === true;
+        // Size gate moved out of the pre-loop guard: the exact byte
+        // path proves uniqueness below (spans.length === 1 for
+        // !replaceAll), so an exact-unique multi edit applies at any
+        // size. The fold-fallback path in edit-engine still enforces
+        // the >=30-line code-10 wording for genuine fold-misses.
+        if (/^\s*\d+[\t│→]/.test(oldString)) {
+            const stripped = maybeAutoStripLineNumberPrefixes(oldString);
+            if (stripped === null) return null;
+            oldString = stripped;
+        }
+        // Final-line-aware hygiene — same rule as the edit-engine slow path
+        // (stripTrailingWhitespaceForEdit), so fast/slow paths cannot diverge
+        // on identical inputs.
+        if (!isMarkdown) newString = stripTrailingWhitespaceForEdit(newString, oldString);
+        if (oldString.length === 0) {
+            return { error: `Error: edit ${i} — old_string must be non-empty` };
+        }
+        if (oldString === newString) {
+            return { error: `Error: edit ${i} — new_string must differ from old_string` };
+        }
+        if (newString === '' || countLfInString(oldString) !== countLfInString(newString)) return null;
+        const oldBytes = Buffer.from(oldString, 'utf-8');
+        const fileUtf8 = rawBuf.toString('utf-8');
+        if (oldBytes.length === 0) return null;
+        if (!replaceAll) {
+            const _fb = rawBuf.indexOf(oldBytes);
+            if (_fb !== -1 && rawBuf.indexOf(oldBytes, _fb + 1) !== -1) return null;
+        }
+        normalizedEdits.push({ oldString, newString, replaceAll });
+        const spans = [];
+        let idx = 0;
+        while ((idx = rawBuf.indexOf(oldBytes, idx)) !== -1) {
+            const spanEnd = idx + oldBytes.length;
+            const sliceText = rawBuf.subarray(idx, spanEnd).toString('utf-8');
+            const newBytes = Buffer.from(
+                replacementForOriginalSlice(newString, sliceText, fileUtf8),
+                'utf-8',
+            );
+            spans.push({ start: idx, end: spanEnd, editIndex: i, newBytes });
+            if (!replaceAll && spans.length > 1) return null;
+            idx += oldBytes.length;
+        }
+        if (spans.length === 0) return null;
+        replacements.push(...spans);
+    }
+    replacements.sort((a, b) => a.start - b.start || a.end - b.end);
+    for (let i = 1; i < replacements.length; i++) {
+        if (replacements[i].start < replacements[i - 1].end) return null;
+    }
+    // Independence guard (above) only checks new_string-contains-old_string; it
+    // misses old_strings SYNTHESISED across edit boundaries (e.g. "A"->"y" turns
+    // "Az yz" into "yz yz", making a later "yz"->Q match twice — which sequential
+    // apply would reject as ambiguous). Verify the fast (apply-in-original)
+    // result equals an in-order SEQUENTIAL replay; on any divergence or
+    // sequential-reject, return null so the caller runs the slow sequential
+    // path. Fail-safe: a false mismatch only costs a fallback, never corruption.
+    {
+        const _fastBytes = concatByteReplacements(rawBuf, replacements);
+        let seq = rawBuf.toString('utf-8');
+        for (const { oldString: _o, newString: _n, replaceAll: _ra } of normalizedEdits) {
+            const repl = replacementForOriginalSlice(_n, _o, seq);
+            if (_ra) {
+                if (!seq.includes(_o)) return null;
+                seq = seq.split(_o).join(repl);
+            } else {
+                const first = seq.indexOf(_o);
+                if (first === -1 || seq.indexOf(_o, first + _o.length) !== -1) return null;
+                seq = seq.slice(0, first) + repl + seq.slice(first + _o.length);
+            }
+        }
+        if (!Buffer.from(seq, 'utf-8').equals(_fastBytes)) return null;
+    }
+    const sameSize = replacements.every((span) => span.end - span.start === span.newBytes.length);
+    if (sameSize) {
+        return {
+            replacements,
+            sameSize: true,
+            contentHash: hashBytesWithReplacements(rawBuf, replacements),
+        };
+    }
+    return {
+        replacements,
+        sameSize: false,
+        updated: concatByteReplacements(rawBuf, replacements),
+    };
+}

package/src/agent/orchestrator/tools/builtin/edit-byte-utils.mjs

@@ -0,0 +1,113 @@
+import { createHash } from 'crypto';
+import { statSync } from 'fs';
+import { hashText } from './hash-utils.mjs';
+import { statMatchesSnapshot } from './snapshot-helpers.mjs';
+
+export function lineRangesForByteSpans(rawBuf, spans) {
+    if (!Buffer.isBuffer(rawBuf) || !Array.isArray(spans) || spans.length === 0) return [];
+    const sorted = spans
+        .filter((span) => span && Number.isFinite(span.start) && Number.isFinite(span.end) && span.start >= 0 && span.end >= span.start)
+        .sort((a, b) => a.start - b.start);
+    const out = [];
+    let lineNo = 1;
+    let scanned = 0;
+    for (const span of sorted) {
+        const start = Math.min(rawBuf.length, span.start);
+        const end = Math.min(rawBuf.length, span.end);
+        for (let i = scanned; i < start; i++) {
+            if (rawBuf[i] === 10) lineNo++;
+        }
+        const startLine = lineNo;
+        let lineCount = 1;
+        for (let i = start; i < end; i++) {
+            if (rawBuf[i] === 10) lineCount++;
+        }
+        for (let i = start; i < end; i++) {
+            if (rawBuf[i] === 10) lineNo++;
+        }
+        scanned = end;
+        out.push({ startLine, endLine: startLine + lineCount - 1 });
+    }
+    return out;
+}
+
+export function bufferWithTrailingLf(buf) {
+    const out = Buffer.allocUnsafe(buf.length + 1);
+    buf.copy(out, 0);
+    out[buf.length] = 10;
+    return out;
+}
+
+export function concatByteReplacements(rawBuf, replacements) {
+    const parts = [];
+    let cursor = 0;
+    let totalLength = 0;
+    for (const span of replacements) {
+        if (span.start < cursor) return null;
+        const before = rawBuf.subarray(cursor, span.start);
+        parts.push(before, span.newBytes);
+        totalLength += before.length + span.newBytes.length;
+        cursor = span.end;
+    }
+    const tail = rawBuf.subarray(cursor);
+    parts.push(tail);
+    totalLength += tail.length;
+    return Buffer.concat(parts, totalLength);
+}
+
+export function hashBytesWithReplacements(rawBuf, replacements) {
+    const hasher = createHash('sha256');
+    let cursor = 0;
+    const sorted = Array.isArray(replacements)
+        ? replacements.slice().sort((a, b) => a.start - b.start || a.end - b.end)
+        : [];
+    for (const span of sorted) {
+        if (!span || span.start < cursor || span.end < span.start || !Buffer.isBuffer(span.newBytes)) return hashText(rawBuf);
+        hasher.update(rawBuf.subarray(cursor, span.start));
+        hasher.update(span.newBytes);
+        cursor = span.end;
+    }
+    hasher.update(rawBuf.subarray(cursor));
+    return hasher.digest('hex');
+}
+
+export function materialiseByteReplacements(rawBuf, replacements) {
+    return concatByteReplacements(rawBuf, replacements);
+}
+
+export function partialByteWriteEnabled() {
+    return !/^(0|false|no|off|atomic)$/i.test(String(process.env.MIXDOG_EDIT_PARTIAL_WRITE || process.env.MIXDOG_PARTIAL_WRITE || ''));
+}
+
+export function captureStableBaseStatSnapshot(fullPath, statHint, rawBuf) {
+    if (!fullPath || !statHint || !Buffer.isBuffer(rawBuf)) return null;
+    try {
+        const postReadStat = statSync(fullPath);
+        if (statMatchesSnapshot(postReadStat, statHint) && postReadStat.size === rawBuf.length) {
+            return {
+                mtimeMs: postReadStat.mtimeMs,
+                ctimeMs: postReadStat.ctimeMs,
+                size: postReadStat.size,
+                ino: Number(postReadStat.ino),
+            };
+        }
+    } catch {}
+    return null;
+}
+
+/** TOCTOU guard for atomicWrite — same shape as write-tool captureTargetSnapshot. */
+export function captureExpectedTargetSnapshot(fullPath, statHint = null) {
+    try {
+        const st = statHint || statSync(fullPath);
+        return {
+            exists: true,
+            size: st.size,
+            mtimeMs: Number(st.mtimeMs),
+            ctimeMs: Number(st.ctimeMs),
+            ino: Number(st.ino),
+        };
+    } catch (err) {
+        if (err && err.code === 'ENOENT') return { exists: false };
+        throw err;
+    }
+}

package/src/agent/orchestrator/tools/builtin/edit-commit.mjs

@@ -0,0 +1,74 @@
+import { markCodeGraphDirtyPaths } from '../code-graph.mjs';
+import { atomicWrite } from './atomic-write.mjs';
+import {
+    invalidateBuiltinResultCache,
+    seedRawContentCacheAfterWrite,
+} from './cache-layers.mjs';
+import { captureExpectedTargetSnapshot, materialiseByteReplacements } from './edit-byte-utils.mjs';
+import { postEditSnapshotMeta } from './edit-context-utils.mjs';
+import { tryWriteSameSizeByteReplacementsSync } from './edit-partial-write.mjs';
+import { recordReadSnapshot } from './read-snapshot-runtime.mjs';
+import { validatePreparedEditBase } from './edit-base-guard.mjs';
+
+function commitHooks(hooks = {}) {
+    return {
+        ioTraceStart: typeof hooks.ioTraceStart === 'function' ? hooks.ioTraceStart : () => 0,
+        ioTraceDone: typeof hooks.ioTraceDone === 'function' ? hooks.ioTraceDone : () => {},
+    };
+}
+
+export async function commitPreparedEditUnlocked(prepared, readStateScope, options = {}, hooks = {}) {
+    const traceHooks = commitHooks(hooks);
+    if (Array.isArray(prepared.sameSizeByteReplacements) && prepared.sameSizeByteReplacements.length > 0) {
+        const partial = tryWriteSameSizeByteReplacementsSync(prepared.fullPath, prepared.sameSizeByteReplacements, {
+            baseStatSnapshot: prepared.baseStatSnapshot,
+            baseMutationGeneration: prepared.baseMutationGeneration,
+            baseContentHash: prepared.baseContentHash,
+            contentHash: prepared.contentHash,
+            fsync: options?.fsync,
+            filePath: prepared.filePath,
+        }, {
+            ...traceHooks,
+            validatePreparedEditBase,
+        });
+        if (partial?.ok) {
+            invalidateBuiltinResultCache([prepared.fullPath]);
+            markCodeGraphDirtyPaths([prepared.fullPath]);
+            const afterBuf = materialiseByteReplacements(prepared.baseRawContent, prepared.sameSizeByteReplacements);
+            const snapMeta = postEditSnapshotMeta(prepared.snapshot, 'edit', afterBuf, {
+                contentBeforeEdit: prepared.baseRawContent,
+                shiftRanges: false,
+            });
+            recordReadSnapshot(prepared.fullPath, partial.stat || undefined, readStateScope, snapMeta);
+            return;
+        }
+        if (partial?.error) throw new Error(partial.error.replace(/^Error:\s*/, ''));
+        if (!Buffer.isBuffer(prepared.content) && Buffer.isBuffer(prepared.baseRawContent)) {
+            prepared.content = materialiseByteReplacements(prepared.baseRawContent, prepared.sameSizeByteReplacements);
+        }
+    }
+    if (!Buffer.isBuffer(prepared.content) && typeof prepared.content !== 'string') {
+        throw new Error('prepared edit missing materialised content');
+    }
+    const expectedTargetSnapshot = prepared.expectedTargetSnapshot
+        || captureExpectedTargetSnapshot(prepared.fullPath);
+    await atomicWrite(prepared.fullPath, prepared.content, {
+        sessionId: options?.sessionId,
+        mode: prepared.baseMode,
+        expectedTargetSnapshot,
+    });
+    invalidateBuiltinResultCache([prepared.fullPath]);
+    const writtenStat = seedRawContentCacheAfterWrite(prepared.fullPath, prepared.content);
+    markCodeGraphDirtyPaths([prepared.fullPath]);
+    recordReadSnapshot(prepared.fullPath, writtenStat || undefined, readStateScope, postEditSnapshotMeta(prepared.snapshot, 'edit', prepared.content, {
+        contentBeforeEdit: prepared.baseRawContent,
+        shiftRanges: false,
+    }));
+}
+
+export async function commitPreparedEditCheckedUnlocked(prepared, readStateScope, options = {}, hooks = {}) {
+    const prewriteErr = validatePreparedEditBase(prepared);
+    if (prewriteErr) return { ok: false, error: prewriteErr };
+    await commitPreparedEditUnlocked(prepared, readStateScope, options, hooks);
+    return { ok: true };
+}

package/src/agent/orchestrator/tools/builtin/edit-context-utils.mjs

@@ -0,0 +1,242 @@
+import { hashText } from './hash-utils.mjs';
+import { renderReadLine } from './read-formatting.mjs';
+import {
+    snapshotCoversFullFile,
+    snapshotRangesCoverAllLines,
+} from './snapshot-helpers.mjs';
+
+export function countLfInString(value) {
+    let n = 0;
+    const s = String(value ?? '');
+    for (let i = 0; i < s.length; i++) {
+        if (s.charCodeAt(i) === 10) n++;
+    }
+    return n;
+}
+
+function normaliseSnapshotRange(r) {
+    if (!r) return null;
+    const startLine = Math.max(1, Number(r.startLine) || 1);
+    const endLine = r.endLine === Infinity ? Infinity : Number(r.endLine);
+    if (!Number.isFinite(startLine)) return null;
+    if (endLine !== Infinity && (!Number.isFinite(endLine) || endLine < startLine)) return null;
+    return { startLine, endLine };
+}
+
+function isFullFileSentinelRange(r) {
+    return r && r.startLine <= 1 && r.endLine === Infinity;
+}
+
+export function lineRangeForSubstring(content, needle, { replaceAll = false } = {}) {
+    if (typeof content !== 'string' || typeof needle !== 'string' || needle.length === 0) return null;
+    let oldLineCount = 1;
+    for (let i = 0; i < needle.length; i++) {
+        if (needle.charCodeAt(i) === 10) oldLineCount++;
+    }
+    // A needle ending in "\n" terminates its last content line rather than
+    // starting a new one. Without this, endLine over-counts by 1 and the edit
+    // marks the FOLLOWING line as part of its (inclusive) range, mis-shifting
+    // snapshot/context ranges. Reviewer-verified: ranges are inclusive
+    // end-to-end with no downstream compensation. No effect for needles that
+    // do not end in "\n".
+    if (needle.endsWith('\n')) oldLineCount--;
+    let idx = 0;
+    let scanned = 0;
+    let lineNo = 1;
+    let minStart = Infinity;
+    let maxEnd = 0;
+    let found = false;
+    while ((idx = content.indexOf(needle, idx)) !== -1) {
+        for (let i = scanned; i < idx; i++) {
+            if (content.charCodeAt(i) === 10) lineNo++;
+        }
+        scanned = idx;
+        const startLine = lineNo;
+        const endLine = startLine + oldLineCount - 1;
+        minStart = Math.min(minStart, startLine);
+        maxEnd = Math.max(maxEnd, endLine);
+        found = true;
+        idx += needle.length;
+        if (!replaceAll) break;
+    }
+    if (!found) return null;
+    return { startLine: minStart, endLine: maxEnd };
+}
+
+export function shiftSnapshotRangesForEdit(snapshot, opts = {}) {
+    if (!snapshot || !Array.isArray(snapshot.ranges)) return snapshot;
+    const lineDelta = Number(opts.lineDelta);
+    const delta = Number.isFinite(lineDelta) ? lineDelta : 0;
+    const editStart = Number(opts.editStartLine);
+    const editEnd = Number(opts.editEndLine);
+    const hasSpan = Number.isFinite(editStart) && Number.isFinite(editEnd) && editStart >= 1 && editEnd >= editStart;
+
+    const out = [];
+    for (const raw of snapshot.ranges) {
+        const r = normaliseSnapshotRange(raw);
+        if (!r) continue;
+        if (isFullFileSentinelRange(r)) {
+            out.push({ startLine: 1, endLine: Infinity });
+            continue;
+        }
+        let { startLine, endLine } = r;
+        if (!hasSpan) {
+            if (delta !== 0) {
+                startLine = Math.max(1, startLine + delta);
+                if (endLine !== Infinity) endLine = endLine + delta;
+            }
+        } else if (endLine !== Infinity && endLine < editStart) {
+            // entirely before the edited span
+        } else if (startLine > editEnd) {
+            startLine = Math.max(1, startLine + delta);
+            if (endLine !== Infinity) endLine = endLine + delta;
+        } else {
+            // overlaps the edited span — keep start, extend/shrink end safely
+            if (endLine !== Infinity) {
+                endLine = Math.max(startLine, endLine + delta);
+            }
+        }
+        if (endLine !== Infinity && endLine < startLine) continue;
+        out.push({ startLine, endLine });
+    }
+    return { ...snapshot, ranges: out };
+}
+
+export function shiftSnapshotRangesByLineDelta(snapshot, lineDelta) {
+    return shiftSnapshotRangesForEdit(snapshot, { lineDelta });
+}
+
+export function isStrongExactEditTarget(oldStr, stage) {
+    const s = String(oldStr ?? '').trim();
+    const fuzzy = stage && stage !== 'exact';
+    const singleLineMin = fuzzy ? 16 : 32;
+    const multiLineMin = fuzzy ? 10 : 20;
+    if (s.length >= singleLineMin) return true;
+    if (s.includes('\n') && s.length >= multiLineMin) return true;
+    return false;
+}
+
+function snapshotMetaHasFullCoverage(meta, content) {
+    if (!meta || !Array.isArray(meta.ranges)) return false;
+    if (snapshotCoversFullFile(meta)) return true;
+    const lineCount = String(content ?? '').split(/\r?\n/).length;
+    return snapshotRangesCoverAllLines(meta, lineCount);
+}
+
+export function postEditSnapshotMeta(prevSnapshot, source, content, opts = {}) {
+    const text = Buffer.isBuffer(content) ? content.toString('utf-8') : String(content ?? '');
+    let lineDelta = Number(opts.lineDelta);
+    if (!Number.isFinite(lineDelta) && opts.contentBeforeEdit != null) {
+        const before = Buffer.isBuffer(opts.contentBeforeEdit)
+            ? opts.contentBeforeEdit.toString('utf-8')
+            : String(opts.contentBeforeEdit ?? '');
+        const after = text;
+        lineDelta = countLfInString(after) - countLfInString(before);
+    }
+    if (!Number.isFinite(lineDelta) && opts.oldStr != null && opts.newStr != null) {
+        const per = countLfInString(opts.newStr) - countLfInString(opts.oldStr);
+        const beforeText = Buffer.isBuffer(opts.contentBeforeEdit)
+            ? opts.contentBeforeEdit.toString('utf-8')
+            : String(opts.contentBeforeEdit ?? '');
+        const occ = opts.replaceAll === true
+            ? Math.max(1, countOccurrences(beforeText, opts.oldStr))
+            : 1;
+        lineDelta = per * occ;
+    }
+    if (!Number.isFinite(lineDelta)) lineDelta = 0;
+
+    let editStartLine = Number(opts.editStartLine);
+    let editEndLine = Number(opts.editEndLine);
+    if (!(Number.isFinite(editStartLine) && Number.isFinite(editEndLine)) && typeof opts.oldStr === 'string' && opts.contentBeforeEdit != null) {
+        const beforeText = Buffer.isBuffer(opts.contentBeforeEdit)
+            ? opts.contentBeforeEdit.toString('utf-8')
+            : String(opts.contentBeforeEdit ?? '');
+        const span = lineRangeForSubstring(beforeText, opts.oldStr, { replaceAll: opts.replaceAll === true });
+        if (span) {
+            editStartLine = span.startLine;
+            editEndLine = span.endLine;
+        }
+    }
+
+    const meta = { source };
+    if (prevSnapshot && Array.isArray(prevSnapshot.ranges)) {
+        if (opts.shiftRanges === false) {
+            meta.ranges = prevSnapshot.ranges.map((r) => ({ ...r }));
+        } else {
+            const shifted = shiftSnapshotRangesForEdit(prevSnapshot, {
+                lineDelta,
+                editStartLine,
+                editEndLine,
+            });
+            if (shifted && Array.isArray(shifted.ranges)) meta.ranges = shifted.ranges;
+        }
+    }
+    if (snapshotMetaHasFullCoverage(meta, text)) {
+        meta.contentHash = hashText(text);
+    }
+    return meta;
+}
+
+export function maybeAutoStripLineNumberPrefixes(oldStr) {
+    if (typeof oldStr !== 'string' || oldStr.length === 0) return null;
+    if (!/^\s*\d+[\t│→]/.test(oldStr)) return null;
+    const lines = oldStr.split('\n');
+    const stripped = [];
+    for (const ln of lines) {
+        const m = ln.match(/^\s*\d+[\t│→](.*)$/);
+        if (!m) return null;
+        stripped.push(m[1]);
+    }
+    return stripped.join('\n');
+}
+
+export function countOccurrences(haystack, needle) {
+    if (typeof needle !== 'string' || needle.length === 0) return 0;
+    let count = 0;
+    let idx = 0;
+    while ((idx = haystack.indexOf(needle, idx)) !== -1) {
+        count++;
+        idx += needle.length;
+    }
+    return count;
+}
+
+export function lineContextAround(content, startLine, endLine, radius = 3, maxChars = 1600) {
+    const lines = String(content ?? '').split('\n');
+    const total = lines.length;
+    const start = Math.max(1, Math.min(total, startLine) - radius);
+    const end = Math.min(total, Math.max(startLine, endLine) + radius);
+    let out = lines
+        .slice(start - 1, end)
+        .map((line, i) => renderReadLine(start + i, line, { truncateLongLine: false }))
+        .join('\n');
+    if (out.length > maxChars) {
+        const head = out.slice(0, Math.floor(maxChars * 0.6));
+        const tail = out.slice(Math.max(0, out.length - Math.floor(maxChars * 0.4)));
+        out = `${head}\n... [context middle omitted] ...\n${tail}`;
+    }
+    return out;
+}
+
+export function compactEditContext(content, startLine, endLine, opts = {}) {
+    const lines = String(content ?? '').split('\n');
+    const total = Math.max(1, lines.length);
+    const maxLines = Math.max(1, Math.min(20, Number(opts.maxLines) || 20));
+    const targetStart = Math.max(1, Math.min(total, Number(startLine) || 1));
+    const targetEnd = Math.max(targetStart, Math.min(total, Number(endLine) || targetStart));
+    const targetLines = Math.max(1, targetEnd - targetStart + 1);
+    const extra = Math.max(0, maxLines - targetLines);
+    let start = Math.max(1, targetStart - Math.floor(extra / 2));
+    let end = Math.min(total, start + maxLines - 1);
+    start = Math.max(1, Math.min(start, Math.max(1, end - maxLines + 1)));
+    const range = { startLine: start, endLine: end };
+    const maxLineChars = Math.max(80, Math.min(240, Number(opts.maxLineChars) || 180));
+    let text = lines.slice(start - 1, end).map((line, i) => {
+        let s = String(line ?? '');
+        if (s.length > maxLineChars) s = `${s.slice(0, Math.max(20, maxLineChars - 24))} ... [line truncated]`;
+        return renderReadLine(start + i, s, { truncateLongLine: false });
+    }).join('\n');
+    const maxChars = Math.max(300, Math.min(1800, Number(opts.maxChars) || 1400));
+    if (text.length > maxChars) text = `${text.slice(0, maxChars - 28)}\n... [context truncated]`;
+    return { range, text };
+}