Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.
TypeScript ai-sdkclaude-codeclicode-searchcodexcoding-agentscontext-retrievaldeveloper-toolsjevsemantic-searchtypescriptvercel-ai-gateway
Reuse a snapshot while its file identity is unchanged
taeskimea708e5f7863
diff --git a/docs/architecture.md b/docs/architecture.mdindex 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 transporand authentication, not retrieval semantics. Bounded retries, cancellation andfreshness 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 improvementdiff --git a/packages/core/src/filesystem.ts b/packages/core/src/filesystem.tsindex 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.tsindex 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): Promisif (["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.tsindex 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.mdindex 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:** souas 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 oadds 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 evaluatingthe 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 distinctsource donor is checked; stale excerpts are removed and the result becomesdiff --git a/test/retrieval.test.ts b/test/retrieval.test.tsindex 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";