Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

Reuse a snapshot while its file identity is unchanged

taeskimea708e5f7863
diff --git a/docs/architecture.md b/docs/architecture.md
index 574c500..a8c9974 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -94,9 +94,10 @@ source text is a field inside those objects. Provider selection changes transpor
and authentication, not retrieval semantics. Bounded retries, cancellation and
freshness checks apply before source is uploaded or returned.
-Ignore rules are reused within a search only while fresh filesystem identity and
-canonical-path checks still match. Edits, replacement and deletion invalidate
-that reuse. Source snapshots retain their existing read and freshness checks.
+Ignore rules and source snapshots are reused within a search only while fresh
+eligibility and filesystem identity checks still match. Edits, replacement and
+deletion invalidate that reuse. A file changed within a few seconds of its read is
+always read again, because coarse timestamps cannot separate two writes in one tick.
## Version improvement
diff --git a/packages/core/src/filesystem.ts b/packages/core/src/filesystem.ts
index bd8db4c..b7c51fb 100644
--- a/packages/core/src/filesystem.ts
+++ b/packages/core/src/filesystem.ts
@@ -68,6 +68,8 @@ export const filesystemDefaults = Object.freeze({
maxOpenDirectories: 64,
maxFileBytes: 16 * 1024 * 1024,
maxIgnoreBytes: 1024 * 1024,
+ /** Source bytes of earlier snapshots retained for identity-checked reuse. */
+ maxReusableBytes: 32 * 1024 * 1024,
});
export type FilesystemOptions = {
root: string;
@@ -77,11 +79,17 @@ export type FilesystemOptions = {
limits?: Partial<
Pick<
typeof filesystemDefaults,
- "pageSize" | "maxOpenDirectories" | "maxFileBytes" | "maxIgnoreBytes"
+ "pageSize" | "maxOpenDirectories" | "maxFileBytes" | "maxIgnoreBytes" | "maxReusableBytes"
>
>;
signal?: AbortSignal;
+ /** Wall-clock milliseconds, compared with file timestamps; injectable for tests. */
+ now?: () => number;
};
+/** Timestamps are coarse on some filesystems (two seconds on FAT). A write in the same tick as a
+ * read can leave a file's identity unchanged, so only a file whose last change is older than this
+ * margin at the start of its read can later be recognized by identity alone. */
+const recentChangeNs = 3_000_000_000n;
type Scope = { directory: string; git?: Ignore; search?: Ignore };
type Eligible = {
@@ -138,10 +146,12 @@ export async function createFilesystem(options: FilesystemOptions) {
"maxOpenDirectories",
"maxFileBytes",
"maxIgnoreBytes",
+ "maxReusableBytes",
] as const) {
if (!Number.isSafeInteger(limits[name]) || limits[name] < 1)
throw new Error(`Invalid filesystem limit: ${name}`);
}
+ const now = options.now ?? (() => Date.now());
const protectedPaths = await Promise.all(
[storageDirectory("config"), storageDirectory("cache"), ...(options.protectedPaths ?? [])].map(
async (path) => {
@@ -360,10 +370,70 @@ export async function createFilesystem(options: FilesystemOptions) {
if (result.status !== "eligible") return result;
return result.stat.isFile() ? { status: "file" as const } : excluded("not_file");
}
- async function readSnapshot(path: string): Promise<SnapshotResult> {
+ type Reusable = { snapshot: Snapshot; stat: BigIntStats; bytes: number };
+ // Trusted earlier reads, least recently used first; bounded by source bytes.
+ const reusable = new Map<string, Reusable>();
+ let reusableBytes = 0;
+ function forget(path: string) {
+ const entry = reusable.get(path);
+ if (!entry) return;
+ reusable.delete(path);
+ reusableBytes -= entry.bytes;
+ }
+ function retain(path: string, entry: Reusable) {
+ forget(path);
+ if (entry.bytes > limits.maxReusableBytes) return;
+ reusable.set(path, entry);
+ reusableBytes += entry.bytes;
+ for (const [oldest, value] of reusable) {
+ if (reusableBytes <= limits.maxReusableBytes) break;
+ reusable.delete(oldest);
+ reusableBytes -= value.bytes;
+ }
+ }
+ /** Compares identity without reading bytes. Opening, unlike lstat alone, revalidates attributes
+ * that network filesystems cache between clients. */
+ async function sameFile(identity: Eligible, known: BigIntStats) {
+ if (!same(known, identity.stat) || stopped(identity.path) !== undefined) return false;
+ let handle;
+ try {
+ handle = await open(
+ identity.absolute,
+ constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+ );
+ const current = await handle.stat({ bigint: true });
+ return current.isFile() && same(known, current);
+ } catch {
+ return false;
+ } finally {
+ await handle?.close();
+ }
+ }
+ /** Eligibility is evaluated on every call. With `reuse`, a file whose identity (device, inode,
+ * size, modification and change times) matches a trusted earlier read returns that snapshot
+ * instead of being reread and rehashed; any other file is read again. */
+ async function readSnapshot(
+ path: string,
+ options: { reuse?: boolean } = {},
+ ): Promise<SnapshotResult> {
+ const started = BigInt(Math.floor(now())) * 1_000_000n;
const admitted = await eligibility(path);
- if (admitted.status !== "eligible") return admitted;
- if (!admitted.stat.isFile()) return excluded("not_file");
+ if (admitted.status !== "eligible") {
+ const named = pathName(path);
+ if (named) forget(named.path);
+ return admitted;
+ }
+ if (!admitted.stat.isFile()) {
+ forget(admitted.path);
+ return excluded("not_file");
+ }
+ const known = reusable.get(admitted.path);
+ if (options.reuse && known && (await sameFile(admitted, known.stat))) {
+ reusable.delete(admitted.path);
+ reusable.set(admitted.path, known);
+ return { status: "ok", snapshot: known.snapshot };
+ }
+ forget(admitted.path);
const read = await readBytes(admitted, limits.maxFileBytes);
if (read.status !== "ok") return read;
const current = await eligibility(path);
@@ -381,14 +451,15 @@ export async function createFilesystem(options: FilesystemOptions) {
return excluded("private_key");
if (!policy.includeSensitive && containsLikelySecret(source))
return excluded("sensitive_content");
- return {
- status: "ok",
- snapshot: Object.freeze({
- path: admitted.path,
- source,
- contentHash: createHash("sha256").update(read.bytes).digest("hex"),
- }),
- };
+ const snapshot = Object.freeze({
+ path: admitted.path,
+ source,
+ contentHash: createHash("sha256").update(read.bytes).digest("hex"),
+ });
+ const { mtimeNs, ctimeNs } = admitted.stat;
+ if ((mtimeNs > ctimeNs ? mtimeNs : ctimeNs) + recentChangeNs < started)
+ retain(admitted.path, { snapshot, stat: admitted.stat, bytes: read.bytes.length });
+ return { status: "ok", snapshot };
}
async function discard(token: string) {
const cursor = cursors.get(token);
@@ -485,6 +556,8 @@ export async function createFilesystem(options: FilesystemOptions) {
async function close() {
closed = true;
ruleCache.clear();
+ reusable.clear();
+ reusableBytes = 0;
await Promise.all([...cursors.keys()].map(discard));
}
return { root, readSnapshot, lookupFile, listPage, closeCursor: discard, close };
diff --git a/packages/core/src/retrieve.ts b/packages/core/src/retrieve.ts
index 4175d8a..f7f591d 100644
--- a/packages/core/src/retrieve.ts
+++ b/packages/core/src/retrieve.ts
@@ -99,7 +99,7 @@ export async function retrieve(input: SearchInput, evaluator: Evaluator): Promis
if (["authentication", "request-limit", "cancelled", "interrupted"].includes(kind)) stop = true;
}
async function snapshot(path: string) {
- const result = await reader.readSnapshot(path);
+ const result = await reader.readSnapshot(path, { reuse: true });
if (result.status === "issue") {
issue(result.issue.kind);
return;
@@ -494,7 +494,8 @@ export async function retrieve(input: SearchInput, evaluator: Evaluator): Promis
);
}
async function unchanged(candidate: { path: string; contentHash: string }) {
- const result = await reader.readSnapshot(candidate.path);
+ // Unchanged file identity reuses the reader's earlier snapshot; any change rereads and rehashes.
+ const result = await reader.readSnapshot(candidate.path, { reuse: true });
if (result.status === "ok" && result.snapshot.contentHash === candidate.contentHash) {
inspected.add(candidate.path);
return result.snapshot;
diff --git a/packages/core/test/filesystem.test.ts b/packages/core/test/filesystem.test.ts
index e31b17e..e7fc8f1 100644
--- a/packages/core/test/filesystem.test.ts
+++ b/packages/core/test/filesystem.test.ts
@@ -539,3 +539,157 @@ test("includeSensitive also bypasses GitLab token content filtering", async () =
await broadReader.close();
}
});
+/** Counts OS reads whose returned bytes contain each sentinel: one per full read of that file. */
+async function sourceReads(file: string, sentinels: string[]) {
+ const probe = await open(file);
+ const prototype = Object.getPrototypeOf(probe);
+ const originalRead = prototype.read;
+ await probe.close();
+ const counts = new Map(sentinels.map((sentinel) => [sentinel, 0]));
+ const spy = spyOn(prototype, "read").mockImplementation(async function (
+ this: unknown,
+ ...args: unknown[]
+ ) {
+ const result = await originalRead.apply(this, args);
+ const text = result.buffer.subarray(0, result.bytesRead).toString("utf8");
+ for (const sentinel of sentinels)
+ if (text.includes(sentinel)) counts.set(sentinel, counts.get(sentinel)! + 1);
+ return result;
+ });
+ return { count: (sentinel: string) => counts.get(sentinel)!, restore: () => spy.mockRestore() };
+}
+// The reader's clock runs ahead, so freshly written fixtures fall outside the recent-change guard.
+const ahead = () => Date.now() + 10_000;
+
+test("identity-checked reuse returns the earlier snapshot until the file changes", async () => {
+ const root = await fixture({ "source.ts": "export const REUSE = 1;\n" });
+ // Two writes can share a coarse clock tick; pin the first mtime so the later edit is observable.
+ await utimes(join(root, "source.ts"), 0, 0);
+ const reads = await sourceReads(join(root, "source.ts"), ["REUSE"]);
+ const reader = await createFilesystem({ root, now: ahead });
+ try {
+ const first = await reader.readSnapshot("source.ts", { reuse: true });
+ const second = await reader.readSnapshot("./source.ts", { reuse: true });
+ if (first.status !== "ok" || second.status !== "ok") throw new Error("Expected snapshots");
+ expect(second.snapshot).toBe(first.snapshot);
+ expect(reads.count("REUSE")).toBe(1);
+ // Without reuse the reader always rereads, and a reread refreshes the retained snapshot.
+ const plain = await reader.readSnapshot("source.ts");
+ expect(plain).toMatchObject({
+ status: "ok",
+ snapshot: { source: "export const REUSE = 1;\n" },
+ });
+ expect(reads.count("REUSE")).toBe(2);
+ await writeFile(join(root, "source.ts"), "export const REUSE = 2;\n");
+ const edited = await reader.readSnapshot("source.ts", { reuse: true });
+ expect(edited).toMatchObject({
+ status: "ok",
+ snapshot: { source: "export const REUSE = 2;\n" },
+ });
+ expect(reads.count("REUSE")).toBe(3);
+ await reader.readSnapshot("source.ts", { reuse: true });
+ expect(reads.count("REUSE")).toBe(3);
+ } finally {
+ reads.restore();
+ await reader.close();
+ }
+});
+
+test("a file changed shortly before its read is always read again", async () => {
+ const root = await fixture({ "recent.ts": "export const RECENT = 1;\n" });
+ const reads = await sourceReads(join(root, "recent.ts"), ["RECENT"]);
+ const reader = await createFilesystem({ root });
+ try {
+ const first = await reader.readSnapshot("recent.ts", { reuse: true });
+ const second = await reader.readSnapshot("recent.ts", { reuse: true });
+ if (first.status !== "ok" || second.status !== "ok") throw new Error("Expected snapshots");
+ expect(second.snapshot).not.toBe(first.snapshot);
+ expect(second.snapshot.contentHash).toBe(first.snapshot.contentHash);
+ expect(reads.count("RECENT")).toBe(2);
+ } finally {
+ reads.restore();
+ await reader.close();
+ }
+});
+
+test("reuse still applies current eligibility and notices replacement", async () => {
+ const root = await fixture({ "kept.ts": "export const KEPT = 1;\n" });
+ const reads = await sourceReads(join(root, "kept.ts"), ["KEPT"]);
+ const reader = await createFilesystem({ root, now: ahead });
+ try {
+ expect(await reader.readSnapshot("kept.ts", { reuse: true })).toMatchObject({ status: "ok" });
+ await writeFile(join(root, ".ignore"), "kept.ts\n");
+ expect(await reader.readSnapshot("kept.ts", { reuse: true })).toMatchObject({
+ status: "excluded",
+ reason: "ignored",
+ });
+ await rm(join(root, ".ignore"));
+ // Exclusion discards the retained snapshot, so the next read goes back to the file.
+ expect(await reader.readSnapshot("kept.ts", { reuse: true })).toMatchObject({ status: "ok" });
+ expect(reads.count("KEPT")).toBe(2);
+ // An atomic replacement with identical bytes is a new file and is read again.
+ await writeFile(join(root, "replacement"), "export const KEPT = 1;\n");
+ await rename(join(root, "replacement"), join(root, "kept.ts"));
+ expect(await reader.readSnapshot("kept.ts", { reuse: true })).toMatchObject({
+ status: "ok",
+ snapshot: { source: "export const KEPT = 1;\n" },
+ });
+ expect(reads.count("KEPT")).toBe(3);
+ await rm(join(root, "kept.ts"));
+ expect(await reader.readSnapshot("kept.ts", { reuse: true })).toMatchObject({
+ status: "issue",
+ issue: { kind: "changed" },
+ });
+ } finally {
+ reads.restore();
+ await reader.close();
+ }
+});
+
+test("retained snapshots are bounded by source bytes, least recently used first", async () => {
+ const root = await fixture({
+ "a.ts": "export const EVICT_A = 1;\n",
+ "b.ts": "export const EVICT_B = 1;\n",
+ });
+ const reads = await sourceReads(join(root, "a.ts"), ["EVICT_A", "EVICT_B"]);
+ const reader = await createFilesystem({ root, now: ahead, limits: { maxReusableBytes: 40 } });
+ try {
+ await reader.readSnapshot("a.ts", { reuse: true });
+ await reader.readSnapshot("a.ts", { reuse: true });
+ expect(reads.count("EVICT_A")).toBe(1);
+ // Retaining b exceeds the bound and evicts a.
+ await reader.readSnapshot("b.ts", { reuse: true });
+ await reader.readSnapshot("b.ts", { reuse: true });
+ await reader.readSnapshot("a.ts", { reuse: true });
+ expect(reads.count("EVICT_A")).toBe(2);
+ expect(reads.count("EVICT_B")).toBe(1);
+ await reader.readSnapshot("b.ts", { reuse: true });
+ expect(reads.count("EVICT_B")).toBe(2);
+ } finally {
+ reads.restore();
+ await reader.close();
+ }
+});
+
+test("exclude patterns apply to retained snapshots of every reader", async () => {
+ const root = await fixture({ "src/kept.ts": "export const KEPT = 1;\n" });
+ const reuse = { reuse: true };
+ const open = await createFilesystem({ root, now: ahead });
+ const narrowed = await createFilesystem({
+ root,
+ now: ahead,
+ policy: { exclude: ["src/kept.ts"] },
+ });
+ try {
+ expect(await open.readSnapshot("src/kept.ts", reuse)).toMatchObject({ status: "ok" });
+ expect(await open.readSnapshot("src/kept.ts", reuse)).toMatchObject({ status: "ok" });
+ // Retention belongs to one reader; another reader's policy still decides eligibility.
+ expect(await narrowed.readSnapshot("src/kept.ts", reuse)).toMatchObject({
+ status: "excluded",
+ reason: "exclude_pattern",
+ });
+ } finally {
+ await open.close();
+ await narrowed.close();
+ }
+});
diff --git a/specs/done/jevgrep/choices.md b/specs/done/jevgrep/choices.md
index ace634e..969921c 100644
--- a/specs/done/jevgrep/choices.md
+++ b/specs/done/jevgrep/choices.md
@@ -7,8 +7,9 @@ The [implementation record](README.md) owns the closure decision and the
[corrected confirmation](assets/freshness-confirmation.md) owns measured outcomes.
Review these medium-confidence choices first: the benchmark work clock, ordering
-inside cross-file evidence, and the shared Python interpreter. They preserve the
-intended behavior but create boundaries that future changes must respect.
+inside cross-file evidence, the shared Python interpreter and identity-based
+snapshot reuse. They preserve the intended behavior but create boundaries that
+future changes must respect.
## Sound — medium confidence
@@ -179,6 +180,31 @@ and the write that triggers a sweep pays for one metadata pass. **Verdict:** sou
as a bounded-storage owner without per-write scans. **Confidence:** medium.
Owner: [cache](../../../packages/core/src/cache.ts).
+### Reuse a snapshot while its file identity is unchanged
+
+**When:** performance review after overlapping declaration groups.
+
+Retrieval checks the same files many times: before each declaration group, before
+each provider attempt and for every cross-file donor. Each check used to reread
+and rehash the whole file; a 58-file search performed 985 full reads, and the
+serialized validation queue delayed requests behind them. The reader now keeps
+its earlier snapshot while the file's identity matches: device, inode, size and
+both modification and change times, confirmed by opening the file without
+reading it. Eligibility is still evaluated on every check, so ignore edits and
+exclusions apply immediately. A file whose last change is less than three seconds
+older than its read is never reused, because a second write in the same coarse
+timestamp tick could leave its identity unchanged. Retained source is bounded to
+32 MiB, least recently used first.
+
+**Gap:** freshness requires detecting changes between validations, not a specific
+detection mechanism. **Reach:** identity cannot see a write that leaves size and
+both timestamps unchanged, such as a delayed timestamp update through a shared
+memory map, a backward clock step, or a network server whose clock lags the client
+by more than the guard. Callers that omit `reuse` still reread every time.
+**Verdict:** sound for ordinary edits, saves, replacements and deletions.
+**Confidence:** medium. Owners: [reader](../../../packages/core/src/filesystem.ts)
+and [retrieval](../../../packages/core/src/retrieve.ts).
+
## Sound — high confidence
### Revalidate buffered source through the same filesystem policy
@@ -190,10 +216,11 @@ A request is queued with source from A and B. While it waits, the user edits A o
adds an ignore rule excluding it. The request retains A's original content hash,
a fingerprint of the bytes it used, outside the data sent to Jev. Before evaluating
the buffered request, and before each provider attempt after any waiting, the
-same reader checks eligibility and compares current bytes with that hash. A
-changed source cannot knowingly be submitted again. If a navigation group has
-both invalid and healthy members, finite splitting lets the healthy siblings
-continue instead of discarding the entire group.
+same reader checks eligibility and confirms that the current snapshot still has
+that hash. A file whose identity shows no change keeps its earlier snapshot; any
+other file is reread. A changed source cannot knowingly be submitted again. If a
+navigation group has both invalid and healthy members, finite splitting lets the
+healthy siblings continue instead of discarding the entire group.
The same rule applies when one file supplies context for another. Each distinct
source donor is checked; stale excerpts are removed and the result becomes
diff --git a/test/retrieval.test.ts b/test/retrieval.test.ts
index 3b61b2f..4bd9bab 100644
--- a/test/retrieval.test.ts
+++ b/test/retrieval.test.ts
@@ -1,7 +1,7 @@
import { renderResult } from "../apps/cli/src/render";
import { routeProviderFetch } from "./fixtures/provider-route.mjs";
-import { expect, test } from "bun:test";
-import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { expect, spyOn, test } from "bun:test";
+import { mkdtemp, mkdir, open, writeFile, rm, utimes } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { testIfDocker } from "./helpers/docker";