pi-supernova 0.5.0 → 0.6.0

package/src/context/snap.js

@@ -20,6 +20,8 @@ const TYPED_EXT = new Set([".ts", ".tsx", ".rs", ".go"]);
 
 const MAX_SEARCH_CHARS = 2 * 1024 * 1024;
 
+const MAX_NEEDLE_CHARS = 128;
+
 const MAX_ALTERNATIVES = 3;
 
 /** Light suffix stripping so "terminated" ⊇ "terminat" matches "terminate"; deterministic, no dictionary. */
@@ -82,21 +84,25 @@ function makeCandidate(filePath, dir, query, tokens, flags) {
   const lower = relative.toLowerCase();
   const base = path.basename(lower);
 
+  const extension = path.extname(base);
+  const stemBase = extension ? base.slice(0, -extension.length) : base;
   const exactPath = lower === query.toLowerCase() || base === query.toLowerCase()
-    || base.slice(0, -path.extname(base).length) === query.toLowerCase();
+    || stemBase === query.toLowerCase();
+
+  const needles = tokens.map(token => stem(token).slice(0, MAX_NEEDLE_CHARS));
 
   return { path: filePath, pathScore: scorePathTopology(relative, tokens, flags), exactPath,
-    pathCoverage: tokens.filter(token => lower.includes(token)).length,
+    pathCoverage: tokens.filter((token, index) => lower.includes(needles[index] ?? token)).length,
     matched: new Set(), exactDefinition: false, definitionCoverage: 0, lineCoverage: 0,
     line: 1, signature: "", context: new Map(), recent: [], anchorScore: -1, exactLines: new Set() };
 }
 
-function inspectLine(candidate, lineNumber, raw, query, tokens, isMatch) {
+function inspectLine(candidate, lineNumber, raw, query, tokens, needles, isMatch) {
   const text = raw.replace(/\r?\n$/, "");
   const lower = text.toLowerCase();
 
   if (isMatch) {
-    const matches = tokens.filter(token => lower.includes(token));
+    const matches = tokens.filter((token, index) => lower.includes(needles[index] ?? token));
 
     for (const token of matches) candidate.matched.add(token);
     const ext = path.extname(candidate.path).toLowerCase();
@@ -108,7 +114,7 @@ function inspectLine(candidate, lineNumber, raw, query, tokens, isMatch) {
     for (const item of items) {
       const name = item.name.toLowerCase();
       const itemExact = name === query.toLowerCase();
-      const coverage = tokens.filter(token => name.includes(token)).length;
+      const coverage = tokens.filter((token, index) => name.includes(needles[index] ?? token)).length;
 
       if (itemExact || coverage > definitionCoverage) { declaration = item; definitionCoverage = coverage; exact = itemExact; }
 
@@ -140,33 +146,47 @@ function inspectLine(candidate, lineNumber, raw, query, tokens, isMatch) {
   if (candidate.recent.length > 2) candidate.recent.shift();
 }
 
-function inspectOverlay(candidate, text, needles, query, tokens) {
-  const lines = text.split("\n");
-  const matches = [];
-
-  for (let i = 0; i < lines.length; i++) if (needles.some(needle => lines[i].toLowerCase().includes(needle))) matches.push(i);
-
-  for (const i of matches) inspectLine(candidate, i + 1, lines[i], query, tokens, true);
-  candidate.context.clear();
+function inspectOverlay(candidate, text, needles, query, tokens, signal) {
+  let start = 0, line = 1, truncated = false;
+
+  // Keep only the candidate and its short context, not another copy of every
+  // line in a staged document. Oversized individual lines disclose uncertainty.
+  while (start < text.length) {
+    if ((line & 127) === 0) signal?.throwIfAborted();
+    const newline = text.indexOf("\n", start);
+    const end = newline < 0 ? text.length : newline + 1;
+
+    if (end - start > MAX_SEARCH_CHARS) truncated = true;
+    else {
+      const row = text.slice(start, end);
+      const lower = row.toLowerCase();
+      inspectLine(candidate, line, row, query, tokens, needles, needles.some(needle => lower.includes(needle)));
+    }
+    start = end;
+    line++;
+  }
 
-  for (let i = Math.max(0, candidate.line - 3); i < Math.min(lines.length, candidate.line + 4); i++) candidate.context.set(i + 1, truncateChars(lines[i], 240, "source line").text);
+  return truncated;
 }
 
-async function contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles }) {
-  const needles = exact ? [query.toLowerCase()] : tokens;
+async function contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles, focusFile }) {
+  const needles = exact ? [query.toLowerCase().slice(0, MAX_NEEDLE_CHARS)] : tokens.map(token => stem(token).slice(0, MAX_NEEDLE_CHARS));
+  const searchNeedles = [...new Set(needles)];
+  const candidateRoot = focusFile ? path.dirname(focusFile) : dir;
+  const candidates = new Map();
+
   const args = ["rg", "--json", "--fixed-strings", "--ignore-case", "--before-context", "2", "--after-context", "4"];
 
   if (includeHidden) args.push("--hidden");
   args.push("-g", "!.git/**", "-g", "!**/.git/**");
 
-  for (const needle of needles) args.push("-e", needle);
-  args.push("--", dir);
+  for (const needle of searchNeedles) args.push("-e", needle);
+  args.push("--", focusFile ?? dir);
 
-  const response = diskFiles ? await run(args, { cwd: dir, timeoutMs: 15000, maxOutputChars: MAX_SEARCH_CHARS, signal })
+  const response = diskFiles || (focusFile && overlayText(focusFile) === undefined) ? await run(args, { cwd: focusFile ? path.dirname(focusFile) : dir, timeoutMs: 15000, maxOutputChars: MAX_SEARCH_CHARS, signal })
     : { stdout: "", stderr: "", exitCode: 1 };
 
   if (response.exitCode !== 0 && response.exitCode !== 1) throw new Error("source search failed: " + response.stderr.trim());
-  const candidates = new Map();
   const records = response.stdout.split("\n");
 
   for (let i = 0; i < records.length; i++) {
@@ -190,24 +210,26 @@ async function contentCandidates({ dir, includeHidden, query, tokens, flags, pen
     let candidate = candidates.get(filePath);
 
     if (!candidate) {
-      candidate = makeCandidate(filePath, dir, query, tokens, flags);
+      candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
       candidates.set(filePath, candidate);
     }
 
-    inspectLine(candidate, data.line_number, data.lines.text, query, tokens, record.type === "match");
+    inspectLine(candidate, data.line_number, data.lines.text, query, tokens, needles, record.type === "match");
   }
 
+  let overlayTruncated = false;
+
   for (const filePath of pendingPaths) {
     const pending = overlayText(filePath);
 
     if (pending === undefined) continue;
-    const candidate = makeCandidate(filePath, dir, query, tokens, flags);
-    inspectOverlay(candidate, pending, needles, query, tokens);
+    const candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
+    overlayTruncated = inspectOverlay(candidate, pending, needles, query, tokens, signal) || overlayTruncated;
 
     if (candidate.matched.size) candidates.set(filePath, candidate);
   }
 
-  return { candidates, truncated: response.outputTruncated === true };
+  return { candidates, truncated: response.outputTruncated === true || overlayTruncated };
 }
 
 function rankScore(candidate, tokenCount) {
@@ -224,25 +246,48 @@ function location(candidate, root) {
     context: [...context].sort((a, b) => a[0] - b[0]).map(([line, text]) => (line === candidate.line ? "►" : " ") + line + " " + text) };
 }
 
-async function spanCandidates(filePath, lines, root, overlayText) {
+async function spanCandidates(filePath, lines, root, overlayText, signal) {
   const staged = overlayText(filePath);
-  const text = staged !== undefined ? staged : await fs.readFile(filePath, "utf8");
-  const spans = WorkspaceIndex.spansOf(WorkspaceIndex.fromText(filePath, text));
   const rel = path.relative(root, filePath);
+  let text = staged;
+
+  if (text === undefined) {
+    const file = await fs.open(filePath, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+
+    try {
+      const stat = await file.stat();
+
+      if (!stat.isFile()) throw new Error("source candidate is not a regular file: " + filePath);
+      if (stat.size > 512 * 1024) return lines.map(line => ({ path: rel, line, signature: "", context: [] }));
+      text = await file.readFile({ encoding: "utf8", signal });
+    } finally { await file.close(); }
+  }
+  const spans = WorkspaceIndex.spansOf(WorkspaceIndex.fromText(filePath, text));
 
   return lines.map(line => {
     const span = pickSpan(spans, { line }) ?? { start: line, end: line };
+    const end = Math.min(span.end, span.start + 119);
 
-    return spanCandidate(rel, line, spanWindow(text, span.start, span.end));
+    return spanCandidate(rel, line, spanWindow(text, span.start, end));
   });
 }
 
-async function rankedSpanCandidates(ranked, root, overlayText) {
+async function rankedSpanCandidates(ranked, root, overlayText, signal) {
   const out = [];
 
   for (const candidate of ranked) {
     const lines = candidate.exactLines?.size ? [...candidate.exactLines].sort((a, b) => a - b) : [candidate.line];
-    out.push(...await spanCandidates(candidate.path, lines, root, overlayText));
+    const staged = overlayText(candidate.path);
+    let large = false;
+
+    if (staged !== undefined) large = Buffer.byteLength(staged) > 512 * 1024;
+    else try { large = (await fs.stat(candidate.path)).size > 512 * 1024; } catch {}
+
+    if (large) out.push(location(candidate, root));
+    else {
+      try { out.push(...await spanCandidates(candidate.path, lines, root, overlayText, signal)); }
+      catch (error) { signal?.throwIfAborted(); out.push(location(candidate, root)); }
+    }
     if (out.length >= MAX_ALTERNATIVES) break;
   }
 
@@ -251,11 +296,11 @@ async function rankedSpanCandidates(ranked, root, overlayText) {
 
 export async function executeSnap({ query, searchDir, root, includeHidden = false, run = runCommand, overlayText = () => undefined, pendingPaths = [], pathContext = {}, signal }) {
   const flags = tokenizeQuery(query);
+
+  if (flags.tokens.length > 16) throw new Error("source question is too broad; use at most 16 keywords");
   const tokens = [...new Set(flags.tokens.map(stem))];
 
   if (tokens.length === 0) throw new Error("read requires a file path or a searchable source question");
-
-  if (tokens.length > 16) throw new Error("source question is too broad; use at most 16 keywords");
   query = query.trim();
   const dir = path.resolve(searchDir || process.cwd());
 
@@ -264,15 +309,21 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
   flags.wantsTest ||= isTestPath(path.relative(root ?? dir, dir));
   pendingPaths = pendingPaths.filter(file => inScope(file, dir, includeHidden));
 
-  const diskFiles = await fs.stat(dir).then(stat => stat.isDirectory(), error => {
-    if (error.code !== "ENOENT" || !pendingPaths.length) throw error;
+  const empty = { path: null, line: null, signature: "", confidence: 0, context: [] };
+  const dirStat = await fs.stat(dir).catch(error => {
+    if (error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error;
 
-    return false;
+    return null;
   });
 
-  const empty = { path: null, line: null, signature: "", confidence: 0, context: [] };
+  if (!dirStat && !pendingPaths.length) return { ...empty, status: "not_found" };
+  const diskFiles = dirStat?.isDirectory() === true;
+  const focusFile = dirStat?.isFile() === true || pendingPaths.includes(dir) ? dir : null;
+
   const exact = /^[a-zA-Z_$][\w$]*$/.test(query);
-  const search = await contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles });
+
+  if (!tokens.length) return { ...empty, status: "not_found" };
+  const search = await contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles, focusFile });
   // A declaration hit needs no prerequisite file listing or persistent index.
   // Bare names can name files, even when callers mention the same word.
   const needsPaths = !search.candidates.size || (exact && ![...search.candidates.values()].some(candidate => candidate.exactDefinition));
@@ -283,26 +334,27 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
 
   if (listing.exitCode !== 0 && listing.exitCode !== 1) throw new Error("source file listing failed: " + listing.stderr.trim());
 
-  const paths = [...new Set([...listing.stdout.split("\0").flatMap(file => file ? [path.resolve(dir, file)] : []), ...pendingPaths])]
+  const paths = [...new Set([...listing.stdout.split("\0").flatMap(file => file ? [path.resolve(dir, file)] : []), ...(focusFile ? [focusFile] : []), ...pendingPaths])]
     .filter(file => inScope(file, dir, includeHidden));
+  const candidateRoot = focusFile ? path.dirname(focusFile) : dir;
 
   for (const filePath of paths) {
     if (!inScope(filePath, dir, includeHidden) || search.candidates.has(filePath)) continue;
-    const relative = path.relative(dir, filePath).toLowerCase();
+    const relative = path.relative(candidateRoot, filePath).toLowerCase();
 
     if (!tokens.some(token => relative.includes(token))) continue;
 
     if (exact && tokens.length > 1 && !relative.includes(query.toLowerCase())) continue;
-    const candidate = makeCandidate(filePath, dir, query, tokens, flags);
+    const candidate = makeCandidate(filePath, candidateRoot, query, tokens, flags);
 
-    if (candidate.pathScore > 0) search.candidates.set(filePath, candidate);
+    if (focusFile || candidate.pathScore > 0) search.candidates.set(filePath, candidate);
   }
 
   const ranked = [];
 
   for (const candidate of search.candidates.values()) {
-    if (candidate.pathScore > -50) {
-      ranked.push({ ...candidate, score: rankScore(candidate, tokens.length) });
+    if (focusFile || candidate.pathScore > -50) {
+      ranked.push({ ...candidate, score: focusFile ? Math.max(1, rankScore(candidate, tokens.length)) : rankScore(candidate, tokens.length) });
     }
   }
 
@@ -336,11 +388,11 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
   const uniqueExact = best.exactDefinition && !second?.exactDefinition || best.exactPath && !second?.exactPath && !second?.exactDefinition;
 
   if (!uniqueExact && (coverage < 0.6 || margin < 0.15 || best.definitionCoverage / tokens.length < 0.5)) {
-    return { ...empty, status: "ambiguous", candidates: await rankedSpanCandidates(ranked, relativeRoot, overlayText) };
+    return { ...empty, status: "ambiguous", candidates: await rankedSpanCandidates(ranked, relativeRoot, overlayText, signal) };
   }
 
   if (best.exactLines.size > 1) {
-    return { ...empty, status: "ambiguous", candidates: await rankedSpanCandidates([best], relativeRoot, overlayText) };
+    return { ...empty, status: "ambiguous", candidates: await rankedSpanCandidates([best], relativeRoot, overlayText, signal) };
   }
 
   const confidence = uniqueExact ? 0.95 : Math.min(0.85, 0.5 + coverage * 0.2 + margin * 0.15);

package/src/context/surface.js

@@ -8,14 +8,20 @@ function scanPython(lines) {
     const line = lines[i];
     const match = /^([ \t]*)(def|class|async def)\s+([a-zA-Z0-9_]+)(\(.*?\))?:?/.exec(line);
 
-    if (!match) continue;
-    items.push({
-      kind: match[2].includes("def") ? "function" : "class",
-      name: match[3],
-      signature: match[0].trim(),
-      line: i + 1,
-      depth: Math.floor(match[1].length / 4),
-    });
+    if (match) {
+      items.push({
+        kind: match[2].includes("def") ? "function" : "class",
+        name: match[3],
+        signature: match[0].trim(),
+        line: i + 1,
+        depth: Math.floor(match[1].length / 4),
+      });
+      continue;
+    }
+
+    const constant = /^([ \t]*)([A-Z][A-Z0-9_]*)\s*(?::[^=\n]+)?=/.exec(line);
+
+    if (constant && constant[1].length === 0) items.push({ kind: "constant", name: constant[2], signature: constant[0].replace(/=\s*$/, "=").trim(), line: i + 1, depth: 0 });
   }
 
   return items;
@@ -141,7 +147,7 @@ const SCANNERS = {
 export function extractStructuralSurface(code, extension = "js") {
   if (!isString(code) || !code.trim()) return { items: [], lineCount: 0 };
   const lines = code.split("\n");
-  const ext = extension.replace(/^\./, "").toLowerCase();
+  const ext = String(extension ?? "").replace(/^\./, "").toLowerCase();
   const scanner = SCANNERS[ext] || SCANNERS.js;
   const items = scanner(lines);
 

package/src/fs/check.js

@@ -60,7 +60,7 @@ function skipComment(text, i) {
 
   const end = text.indexOf("*/", i + 2);
 
-  return end < 0 ? text.length : end + 2;
+  return end < 0 ? -1 : end + 2;
 }
 
 function skipRegex(text, i) {
@@ -126,7 +126,13 @@ function consumeLiteral(text, i, stack, prev) {
 
   if (c !== "/") return null;
 
-  if (text[i + 1] === "/" || text[i + 1] === "*") return { end: skipComment(text, i), prev };
+  if (text[i + 1] === "/" || text[i + 1] === "*") {
+    const end = skipComment(text, i);
+
+    if (end < 0) return { error: "unterminated comment", at: i };
+
+    return { end, prev };
+  }
 
   if (prev !== "" && !REGEX_PRECEDERS.has(prev)) return null;
   const end = skipRegex(text, i);
@@ -190,6 +196,8 @@ const CODE_EXT = new Set([".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".mts",
 
 /** { ok: true } | { ok: false, message }; message names the problem and line. */
 export function quickCheck(text, ext) {
+  ext = String(ext ?? "").toLowerCase();
+
   if (ext === ".json") {
     try {
       JSON.parse(text);

package/src/fs/patch.js

@@ -67,7 +67,9 @@ function findHunkMatch(fileLines, expectedOld, nominal) {
 
   if (!expectedOld.length) return -1;
 
-  for (let delta = 1; delta <= Math.max(fileLines.length, 100); delta++) {
+  const maxDrift = Math.min(Math.max(fileLines.length, 100), 200);
+
+  for (let delta = 1; delta <= maxDrift; delta++) {
     if (matchAt(nominal + delta)) return nominal + delta;
 
     if (matchAt(nominal - delta)) return nominal - delta;
@@ -103,7 +105,7 @@ export function applyPatchToText(originalText, patchText) {
       const line = hunk.lines[i];
 
       if (line[0] === "+") {
-        replacement.push({ text: textOf(line), ending: hunk.noNewline.includes(i) ? "" : line.endsWith("\r") ? "\r\n" : ending });
+        replacement.push({ text: textOf(line), ending: hunk.noNewline.includes(i) ? "" : ending });
       } else {
         const original = fileLines[oldIndex++];
 

package/src/fs/vfs.js

@@ -1,20 +1,73 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isString } from "../shared/decode.js";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 
 const VFS_CACHE_MAX = 1024;
 
+const VFS_CACHE_MAX_BYTES = 64 * 1024 * 1024;
+
 // Serialize validation + replacement across Supernova transactions in this host.
 let commitTail = Promise.resolve();
 
+function textSignature(text) {
+  return { size: Buffer.byteLength(text, "utf8"), sha256: createHash("sha256").update(text, "utf8").digest("hex") };
+}
+
+function sameFileVersion(a, b) {
+  return ["dev", "ino", "size", "mtimeMs", "ctimeMs"].every(key => a[key] === b[key]);
+}
+
+async function fileSignature(target, signal, observed) {
+  const file = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+
+  try {
+    const actual = await file.stat();
+
+    if (!actual.isFile()) throw new Error("read requires a regular file: " + target);
+    if (observed && !sameFileVersion(observed, actual)) throw new Error("file changed while reading: " + target);
+    const hash = createHash("sha256");
+
+    for await (const chunk of file.createReadStream({ autoClose: false, signal })) hash.update(chunk);
+    const after = await file.stat();
+
+    if (!after.isFile() || !sameFileVersion(actual, after)) throw new Error("file changed while signing: " + target);
+
+    return { size: actual.size, sha256: hash.digest("hex") };
+  } finally {
+    await file.close();
+  }
+}
+
+// realpath() cannot resolve a missing leaf. Canonicalize its nearest existing
+// ancestor so two symlink spellings still share one commit destination.
+async function canonicalNewPath(target) {
+  let ancestor = path.dirname(target);
+
+  for (;;) {
+    try { return path.join(await fs.realpath(ancestor), path.relative(ancestor, target)); }
+    catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const parent = path.dirname(ancestor);
+
+      if (parent === ancestor) throw error;
+      ancestor = parent;
+    }
+  }
+}
+
+function sameSignature(a, b) {
+  return a === b || (a !== null && b !== null && a.size === b.size && a.sha256 === b.sha256);
+}
+
 export class CausalVfs {
   constructor(onNewFile, validateWrite) {
     this.validateWrite = validateWrite;
-    // Last-seen original bytes for write CAS, not a read cache. read() always
-    // hits disk unless an overlay is staged. Serving cache on read would be a
-    // false-valid against editors/git between two reads.
+    // Optional receipt bodies, never the authority for CAS. Signatures survive
+    // body eviction. Explicit reads hit disk and replace the observed snapshot;
+    // internal receipt reads preserve it until an external-mutation boundary.
     this.cache = new Map();
+    this.cacheBytes = 0;
     this.overlays = [];
     this.expected = new Map();
     this.onNewFile = onNewFile;
@@ -28,9 +81,31 @@ export class CausalVfs {
     this.signal?.throwIfAborted();
   }
 
+  dropCache(target) {
+    const previous = this.cache.get(target);
+
+    if (previous !== undefined && this.cache.delete(target)) this.cacheBytes -= Buffer.byteLength(previous, "utf8");
+  }
+
   setCache(target, content) {
-    if (this.cache.size >= VFS_CACHE_MAX && !this.cache.has(target)) this.cache.delete(this.cache.keys().next().value);
+    const bytes = Buffer.byteLength(content, "utf8");
+
+    if (bytes > VFS_CACHE_MAX_BYTES) {
+      this.dropCache(target);
+      return;
+    }
+
+    this.dropCache(target);
+
+    while ((this.cache.size >= VFS_CACHE_MAX || this.cacheBytes + bytes > VFS_CACHE_MAX_BYTES) && this.cache.size) {
+      const oldest = this.cache.keys().next().value;
+
+      this.cacheBytes -= Buffer.byteLength(this.cache.get(oldest), "utf8");
+      this.cache.delete(oldest);
+    }
+
     this.cache.set(target, content);
+    this.cacheBytes += bytes;
   }
 
   getOverlay(target) {
@@ -43,28 +118,30 @@ export class CausalVfs {
     return [...new Set(this.overlays.flatMap(overlay => [...overlay.keys()]))];
   }
 
-  async read(target, { preserveRead = false, maxBytes } = {}) {
+  async read(target, { preserveRead = false, maxBytes, label = "read input" } = {}) {
     const overlay = this.getOverlay(target);
 
     if (overlay !== undefined) {
-      if (maxBytes !== undefined && Buffer.byteLength(overlay, "utf8") > maxBytes) throw new Error("JSON input exceeds " + maxBytes + " bytes; use a streaming parser through bash");
+      if (maxBytes !== undefined && Buffer.byteLength(overlay, "utf8") > maxBytes) throw new Error(label + " exceeds " + maxBytes + " bytes; use a streaming parser through bash");
 
       return overlay;
     }
 
     // External editors and captured tools can change a file between any two reads.
+    // Open once with O_NONBLOCK so a FIFO or device cannot park a host I/O worker.
     try {
-      let text;
+      const file = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+      let bytes;
 
-      if (maxBytes === undefined) text = await fs.readFile(target, "utf8");
-      else {
-        const file = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+      try {
+        const stat = await file.stat();
 
-        try {
-          const stat = await file.stat();
+        if (stat.isDirectory()) throw new Error("read path is a directory, not a file: " + target);
+        if (!stat.isFile()) throw new Error("read requires a regular file: " + target);
 
-          if (!stat.isFile()) throw new Error("JSON read requires a regular file: " + target);
-          const tooLarge = () => new Error("JSON input exceeds " + maxBytes + " bytes; use a streaming parser through bash");
+        if (maxBytes === undefined) bytes = await file.readFile({ signal: this.signal });
+        else {
+          const tooLarge = () => new Error(label + " exceeds " + maxBytes + " bytes; use a streaming parser through bash");
 
           if (stat.size > maxBytes) throw tooLarge();
           const chunks = [];
@@ -77,15 +154,19 @@ export class CausalVfs {
             chunks.push(chunk);
           }
 
-          text = Buffer.concat(chunks).toString("utf8");
-        } finally { await file.close(); }
-      }
+          bytes = Buffer.concat(chunks);
+        }
+        if (!sameFileVersion(stat, await file.stat())) throw new Error("file changed while reading: " + target);
+      } finally { await file.close(); }
 
-      if (!preserveRead || !this.cache.has(target)) this.setCache(target, text);
+      // Hash the actual bytes, not a lossy UTF-8 decode/re-encode.
+      if (!preserveRead || !this.expected.has(target)) this.expected.set(target, textSignature(bytes));
+      const text = bytes.toString("utf8");
+      this.setCache(target, text);
 
       return text;
     } catch (err) {
-      this.cache.delete(target);
+      this.dropCache(target);
 
       if (err.code === "EISDIR") throw new Error("read path is a directory, not a file: " + target);
 
@@ -99,6 +180,27 @@ export class CausalVfs {
     }
   }
 
+  async #diskSignature(target) {
+    let stat;
+
+    try { stat = await fs.stat(target); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+
+    return stat?.isFile() ? await fileSignature(target, this.signal, stat) : null;
+  }
+
+  async captureExpected(target) {
+    if (this.getOverlay(target) !== undefined || this.expected.has(target)) return;
+
+    this.expected.set(target, await this.#diskSignature(target));
+  }
+
+  async recordExpected(target, observed) {
+    if (this.getOverlay(target) !== undefined) return;
+    const signature = observed ? await fileSignature(target, this.signal, observed) : await this.#diskSignature(target);
+    this.expected.set(target, signature);
+  }
+
   async write(target, content) {
     this.assertWritable();
 
@@ -112,14 +214,7 @@ export class CausalVfs {
 
     this.assertWritable();
 
-    if (this.getOverlay(target) === undefined) {
-      let original;
-
-      try { original = this.cache.has(target) ? this.cache.get(target) : await fs.readFile(target, "utf8"); }
-      catch (error) { if (error.code !== "ENOENT") throw error; original = null; }
-
-      this.expected.set(target, original);
-    }
+    await this.captureExpected(target);
 
     this.assertWritable();
 
@@ -169,6 +264,7 @@ export class CausalVfs {
           if (!stat.isFile()) throw new Error("cannot write to a non-file: " + logicalPath);
         } catch (err) {
           if (err.code !== "ENOENT") throw err;
+          target = await canonicalNewPath(logicalPath);
         }
 
         await this.validateWrite?.(logicalPath);
@@ -177,9 +273,9 @@ export class CausalVfs {
         targets.add(target);
 
         if (this.expected.has(logicalPath)) {
-          const current = stat ? await fs.readFile(target, "utf8") : null;
+          const current = stat ? await fileSignature(target, this.signal) : null;
 
-          if (current !== this.expected.get(logicalPath)) {
+          if (!sameSignature(current, this.expected.get(logicalPath))) {
             throw new Error("write conflict: file changed since it was read: " + logicalPath + "; read it again before retrying");
           }
         }
@@ -227,10 +323,12 @@ export class CausalVfs {
 
       for (const entry of staged) {
         this.setCache(entry.logicalPath, entry.content);
-        this.expected.delete(entry.logicalPath);
+        this.expected.set(entry.logicalPath, textSignature(entry.content));
       }
 
-      if (staged.length) this.onNewFile?.(staged.map(entry => entry.target));
+      // Canonical commit destinations must not rewrite established event paths
+      // for newly created files, whose callers supplied a logical cwd spelling.
+      if (staged.length) this.onNewFile?.(staged.map(entry => entry.existed ? entry.target : entry.logicalPath));
       this.mutations.committed += staged.length;
     } catch (error) {
       failed = true;
@@ -291,9 +389,8 @@ export class CausalVfs {
     const top = this.overlays.pop();
     this.mutations.rolledBack += top?.size ?? 0;
 
-    for (const target of top?.keys() ?? []) {
-      if (this.getOverlay(target) === undefined) this.expected.delete(target);
-    }
+    // Rolling back staged writes does not undo observations of disk. Keep the
+    // read snapshot, including for files without a surviving parent overlay.
 
     return { rolledBack: top?.size ?? 0, depth: this.overlays.length };
   }
@@ -316,7 +413,7 @@ export class CausalVfs {
     return pending.size > 0;
   }
 
-  invalidateCache() { this.cache.clear(); }
+  invalidateCache() { this.cache.clear(); this.cacheBytes = 0; this.expected.clear(); }
   getCacheSize() { return this.cache.size; }
   getOverlayDepth() { return this.overlays.length; }
 }