Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

narrow to the refresh gate and incremental extraction

anirudhkumar-nanonetsb566db5686a8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 65686f0b..8cfdd981 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,13 @@
build's fingerprint (~3ms) and rebuild only if something moved. `check` is exempt — it is
the drift report, and refreshing first would make it always say OK.
+ A refresh writes only what a query reads: the wiring graph, the `ask` sidecar, and the
+ freshness record. It does **not** rewrite the markdown cards, `INDEX.md`, or your
+ `.gitignore` — a query is a read, and those stay the job of an explicit `graft build`
+ (which is what the Claude Code `Stop` hook already runs at the end of a turn). So the
+ retrieval tools are always current, while the markdown you might `grep` by hand can lag
+ an edit until the turn ends.
+
The refresh is structural and `$0`: it never calls the LLM, so `graft check` still reports
concept-node drift and stale summaries until you run `graft build --deep` yourself. A
refresh that fails answers from the graph on disk rather than failing the query.
@@ -24,19 +31,6 @@
GRAFT_NO_REFRESH=1 # same, for every command in the process
```
-- **The graph and its sidecars are written atomically, and in a consistent order.** Now
- that a query can rewrite the graph, a truncating write could hand a partial file to
- whatever was reading it at the time — the statusline, a second MCP call, another graft
- process — which surfaced as "no graph — run `graft build`" on a repo that has one. The
- `ask` sidecar is written before the graph, so a reader that sees a new `wiring.json`
- always sees an index that matches it.
-
-- **A failed write under `graft/` is reported instead of being retried forever.** One
- unwritable card or `INDEX.md` (a read-only mount, a directory you don't own) used to
- make every later query rebuild the whole repo and fail again. The graph and its
- freshness record are independent of those projections now, so a build converges and the
- failure is named in the query's own output.
-
### Added
- **Incremental extraction.** `graft build` memoizes each file's parse under `graft/.cache/`
@@ -47,6 +41,11 @@
now reports `parsed: N of M files (K replayed from cache)`, and `graft build --no-reuse`
forces a cold parse of everything.
+ Only the *parse* is skipped — every file is still read and hashed on every build. A stat
+ may decide whether a query bothers rebuilding; it may not decide what the rebuild itself
+ looks at, or `graft check` (which always re-hashes) could report drift that the `graft
+ build` it recommends refuses to repair.
+
- **`GRAFT_REFRESH=hash`** — confirm every file by hashing its contents instead of trusting
size and mtime, for tooling that rewrites files while preserving both.
diff --git a/README.md b/README.md
index 7fcedc87..3cba4add 100644
--- a/README.md
+++ b/README.md
@@ -222,8 +222,8 @@ Where a CLI agent supports user-level `hooks.json`, `init` also installs Graft's
`graft init` always wires up Claude Code, and Claude Code gets more than an instruction file. From then on, any Claude Code session opened in the repo gets:
-- **a live statusline** — graph size, % enriched, and a `⚠ N stale` warning when the code has moved ahead of the graph (it flips back to `✓ synced` as soon as any graft query refreshes it, without waiting for the turn to end)
-- **auto-sync** — every graft query brings the graph up to date first, so an answer always describes the code as it is right now, uncommitted edits included; a background rebuild also runs at the end of a turn that touched code. Both are structural and `$0` — auto-sync never calls the LLM on its own
+- **a live statusline** — graph size, % enriched, and a `⚠ N stale` warning when the code has moved ahead of the graph
+- **auto-sync** — every graft query brings the graph up to date first, so an answer always describes the code as it is right now, uncommitted edits included. A query refreshes only what it reads; the markdown under `graft/` is refreshed by the background rebuild at the end of a turn that touched code. Both are structural and `$0` — auto-sync never calls the LLM on its own
- **context on tap** — each prompt pulls the matching nodes into the session; editing a file surfaces what depends on it ("blast radius"); new sessions start with the repo map
<p align="center">
diff --git a/src/ask/index-file.ts b/src/ask/index-file.ts
index 8a2f9b5d..6d414bbe 100644
--- a/src/ask/index-file.ts
+++ b/src/ask/index-file.ts
@@ -19,11 +19,10 @@
* contribution is folded into the stored `df` at query time (see `ask.ts`),
* which is why `df` here counts symbol/file nodes only.
*/
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
import type { GraphV1 } from "../graph/types.js";
import { CACHE_DIR } from "../context/node-file.js";
-import { writeFileAtomic } from "../util/state.js";
/** Words too common/short to carry query intent — dropped before scoring. */
const STOP = new Set([
@@ -126,14 +125,8 @@ export function writeAskIndex(outDir: string, graph: GraphV1): string {
};
const outPath = askIndexPath(outDir);
- // Atomic, and `buildGraph` writes this BEFORE wiring.json. The sidecar has to
- // agree with the graph — `readAskIndex` rejects one whose ids don't match — and
- // the graph is what every reader gates on, so the graph must be the last of the
- // pair to flip. A truncating write here would have handed a reader the new graph
- // beside a half-written index, and the fallback path is badly degraded: the nodes
- // in wiring.json have had `body_text` stripped, so live re-tokenization has no
- // body to work from and body-only matches silently disappear.
- writeFileAtomic(outPath, JSON.stringify(index) + "\n");
+ mkdirSync(dirname(outPath), { recursive: true });
+ writeFileSync(outPath, JSON.stringify(index) + "\n");
return outPath;
}
diff --git a/src/claude/skill-template.ts b/src/claude/skill-template.ts
index 87bd0bd6..26500f57 100644
--- a/src/claude/skill-template.ts
+++ b/src/claude/skill-template.ts
@@ -80,9 +80,15 @@ hotspots, straight from the wiring graph.
or ask your way through every subsystem it lists. \`--max-dirs N\` widens it.
### 6 · Lifecycle: \`graft build\` / \`graft check\`
-Every tool above refreshes the graph itself before answering, so what you get back
-always describes the code as it is right now — including edits you just made and
-have not committed. You do **not** need to run \`build\` after editing.
+Every tool above refreshes the graph itself before answering, so what those tools
+return always describes the code as it is right now — including edits you just made
+and have not committed. You do **not** need to run \`build\` after editing.
+
+One caveat, if you \`grep\` the markdown under \`graft/\` directly: those cards are a
+projection, rebuilt at the end of the turn rather than on each query, so after an edit
+they can lag. The tools above never do — prefer them, and treat a card's spans as
+stale if you have edited that file this turn.
+
\`build\` is for the LLM layer (\`--deep\` adds a concept map; skip unless asked);
\`check\` fails when \`graft/\` is stale, for CI.
diff --git a/src/claude/state.ts b/src/claude/state.ts
index 19c305bf..d89fbea4 100644
--- a/src/claude/state.ts
+++ b/src/claude/state.ts
@@ -17,7 +17,7 @@ export {
patchStats,
readStats,
releaseLock,
- writeFileAtomic,
+ writeJsonAtomic,
writeStats,
} from '../util/state.js';
export type { Stats } from '../util/state.js';
diff --git a/src/claude/stats.ts b/src/claude/stats.ts
index 15ac5b28..6d85f1ac 100644
--- a/src/claude/stats.ts
+++ b/src/claude/stats.ts
@@ -1,14 +1,25 @@
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import type { GraphV1 } from '../graph/types.js';
-
-/** `computeStats` lives in `util/state.ts` alongside the rest of the `.cache/`
- * state, so the hooks and the graph's own pre-query refresh report the same
- * numbers. Re-exported here because that's where callers already import it from. */
-export { computeStats } from '../util/state.js';
+import type { Stats } from './state.js';
export function readWiring(projectDir: string): GraphV1 | null {
try {
return JSON.parse(readFileSync(join(projectDir, 'graft', '.graph', 'wiring.json'), 'utf8')) as GraphV1;
} catch { return null; }
}
+
+export function computeStats(
+ w: GraphV1,
+): Pick<Stats, 'nodeCount' | 'edgeCount' | 'languages' | 'totalCount' | 'readyCount'> {
+ const nodes = w.nodes ?? [];
+ const edges = w.edges ?? [];
+ const readyCount = nodes.filter((n) => n.summary_state === 'ready').length;
+ return {
+ nodeCount: w.meta?.nodeCount ?? nodes.length,
+ edgeCount: w.meta?.edgeCount ?? edges.length,
+ languages: w.meta?.languages ?? [],
+ totalCount: nodes.length,
+ readyCount,
+ };
+}
diff --git a/src/graph/build.ts b/src/graph/build.ts
index 2145675d..1f125e90 100644
--- a/src/graph/build.ts
+++ b/src/graph/build.ts
@@ -25,7 +25,7 @@ import {
writeExtractCache,
type ExtractEntry,
} from "./extract-cache.js";
-import { statUnchanged, writeFingerprint } from "./fingerprint.js";
+import { writeFingerprint } from "./fingerprint.js";
import { listSourceStats } from "./source-files.js";
import { resolveEdges, type GoModule } from "./resolve.js";
import { enrichGraph, type EnrichStats } from "./enrich.js";
@@ -69,6 +69,11 @@ export interface GraphBuildOptions {
/** Replay unchanged files from the extraction cache instead of re-parsing them
* (default true). False forces a cold parse of the whole repo. */
reuse?: boolean;
+ /** Write only what a query reads — the graph, the `ask` sidecar, the freshness
+ * record — and skip the markdown projections and the `.gitignore` touch. Set by
+ * the pre-query refresh (`graph/refresh.ts`); an explicit `graft build` never
+ * sets it. See the write block in {@link buildGraph} for why the split exists. */
+ graphOnly?: boolean;
/** Run the Tier-2 LLM meaning pass. Absent → Tier-1 only (cache is still preserved). */
summarizer?: CruxSummarizer;
/** Max files summarized in parallel during the Tier-2 pass. Default is set in enrich. */
@@ -140,10 +145,6 @@ export async function buildGraph(
// fall out of both the cache and the fingerprint with no separate pruning pass.
const priorExtract = opts.reuse === false ? emptyExtractCache() : readExtractCache(outDir);
const entries: Record<string, ExtractEntry> = {};
- // The Tier-2 pass reads source text for any node it must summarize, including
- // one in a file we didn't re-parse — so when a summarizer is in play, read
- // every file. Reading is ~0.05ms/file; parsing is the ~4.6ms we're skipping.
- const needAllSources = !!opts.summarizer;
let parsed = 0;
let reused = 0;
@@ -152,31 +153,32 @@ export async function buildGraph(
opts.onProgress?.({ phase: "parse", index: i, total: files.length, file: rel });
const lang = languageOf(f.abs)!;
const cached = priorExtract.files[rel];
- // `statUnchanged` is shared with the freshness probe on purpose: whatever the
- // probe treats as "moved" must be something this loop will actually re-read,
- // or a query rebuilds forever and still answers from the old parse.
- const unchanged = !!cached && statUnchanged(cached, f);
- let source: string | null = null;
- if (!unchanged || needAllSources) {
- try {
- source = readFileSync(f.abs, "utf8");
- } catch (err) {
- const message = `${rel}: ${err instanceof Error ? err.message : String(err)}`;
- errors.push(message);
- // Record it anyway (with the stat we do have) so the freshness probe's
- // fast path doesn't report this file as new on every single query.
- entries[rel] = { size: f.size, mtimeMs: f.mtimeMs, hash: "", nodes: [], rawEdges: [], error: message };
- return;
- }
+ // Every file is read and hashed, every build — only the *parse* is memoized.
+ // The tempting optimization is to trust the probe's `(size, mtimeMs)` and skip
+ // the read too, but then `graft build` inherits the probe's blind spot: on a
+ // filesystem with coarse mtime granularity, a same-length edit inside the same
+ // second is invisible, so `graft check` reports drift (it always re-hashes) and
+ // the `graft build` it tells you to run refuses to repair it — forever. A stat
+ // may decide whether a *query* bothers rebuilding; it may not decide what the
+ // rebuild itself looks at. Reading is ~0.05ms/file against the ~4.6ms parse
+ // this still skips.
+ let source: string;
+ try {
+ source = readFileSync(f.abs, "utf8");
+ } catch (err) {
+ const message = `${rel}: ${err instanceof Error ? err.message : String(err)}`;
+ errors.push(message);
+ // Record it anyway (with the stat we do have) so the freshness probe's
+ // fast path doesn't report this file as new on every single query.
+ entries[rel] = { size: f.size, mtimeMs: f.mtimeMs, hash: "", nodes: [], rawEdges: [], error: message };
+ return;
}
- // A stat mismatch is only a *suspicion*; confirm by bytes so a touch, or a
- // checkout that restores identical content, still replays the cache.
- const hash = source === null ? cached!.hash : contentHash(source);
+ const hash = contentHash(source);
if (cached && hash === cached.hash) {
entries[rel] = { ...cached, size: f.size, mtimeMs: f.mtimeMs };
- if (source !== null) sources.set(rel, source);
+ sources.set(rel, source);
reused++;
if (cached.error) {
errors.push(cached.error); // this file failed to parse last time too
@@ -190,10 +192,10 @@ export async function buildGraph(
parsed++;
try {
- const { nodes: fileNodes, rawEdges: fileEdges } = extractFile(rel, source!, lang);
+ const { nodes: fileNodes, rawEdges: fileEdges } = extractFile(rel, source, lang);
nodes.push(...fileNodes);
rawEdges.push(...fileEdges);
- sources.set(rel, source!);
+ sources.set(rel, source);
langs.add(lang);
entries[rel] = { size: f.size, mtimeMs: f.mtimeMs, hash, nodes: fileNodes, rawEdges: fileEdges };
} catch (err) {
@@ -244,18 +246,13 @@ export async function buildGraph(
edges,
};
- // ---- the ordered writes -------------------------------------------------
- // Order is load-bearing, and it follows from what readers gate on. A reader
- // decides whether it has a usable graph by reading wiring.json; everything else
- // it consults is keyed to that. So: dependencies first, wiring.json second
- // (atomically, so the flip is instantaneous), freshness third, projections last.
-
- // `ask`'s token/IDF sidecar — moves per-query corpus tokenization to build time
- // (~45% of query time on a 32k-node graph, profiled). It must land BEFORE
- // wiring.json: `readAskIndex` rejects a sidecar whose ids don't match the graph,
- // and the fallback is badly degraded (the nodes on disk have no `body_text`, so
- // live re-tokenization has no body and body-only matches vanish). Writing it
- // first means "new graph ⇒ new sidecar" always holds.
+ const graphPath = writeGraph(graph, outDir);
+ // `ask`'s token/IDF sidecar — moves per-query corpus tokenization to build
+ // time (~45% of query time on a 32k-node graph, profiled). Lives in the
+ // cache dir; `ask` falls back to live tokenization when it's absent/stale.
+ // Best-effort: wiring.json is already on disk at this point, so a sidecar
+ // write failure (e.g. an unwritable cache dir) must not abort cards/index/
+ // covers below — record it and keep going, same as other recoverable errors.
//
// MUST pass the in-memory `graph` here, never a re-read of wiringPath(outDir):
// `writeGraph` strips `body_text` from what it serializes (dead weight once
@@ -267,42 +264,32 @@ export async function buildGraph(
errors.push(`ask-index: ${err instanceof Error ? err.message : String(err)}`);
}
- const graphPath = writeGraph(graph, outDir);
- // The graph is a local, regenerable cache — make sure git ignores it. Runs on
- // every build (cheap, idempotent), so a fresh clone's first build self-ignores.
- ensureGitignored(root, outDir);
-
// The fingerprint claims exactly one thing: "the graph on disk was built from
- // these source bytes." That is true as of the line above, so it is written here.
- //
- // It says nothing about the projections below, and that is the point. Writing it
- // after them made a failure there — one read-only INDEX.md — strand freshness
- // forever: every later query would re-probe dirty, retake the lock, redo edge
- // resolution + enrichment + the ask index + every card, throw again, and answer
- // from a graph that was in fact already current. Projection failures are reported
- // (below, and surfaced by `refreshNote`), never expressed as permanent drift.
+ // these source bytes." Nothing about the projections below — which is why it is
+ // safe to write here, and why `graphOnly` builds (the query path, which stops
+ // right after this line) are still recorded as fresh.
writeFingerprint(outDir, entries);
- // Tier-2 passive surface: project the nodes into per-file markdown cards, refresh
- // the INDEX roster, and backfill concept nodes with their `covers:` list (the
- // OKF↔Wiring link; a no-op on a $0 build with no concept nodes). Pure projection —
- // no LLM, no network — and individually fallible: a read-only card, a card path
- // colliding with a directory, or ENOSPC records an error and lets the rest proceed.
+ // Tier-2 passive surface: project the nodes into per-file markdown cards, and
+ // refresh the INDEX roster. Pure projection — no LLM, no network.
+ //
+ // Skipped entirely on the query path (`graphOnly`). Retrieval answers from
+ // wiring.json and the ask sidecar; the markdown surface is for humans and for
+ // the agent's own greps, and it is rebuilt by an explicit `graft build` — which
+ // is what the Claude Code `Stop` hook already runs at the end of a turn. Keeping
+ // it off the query path is what makes a refresh cheap, leaves the repo untouched
+ // (`ensureGitignored` writes `.gitignore`, which a read has no business doing),
+ // and means a failure here can never be triggered by a query.
let cardStats: CardStats = { written: 0, pruned: 0, files: [] };
- try {
+ if (!opts.graphOnly) {
+ // The graph is a local, regenerable cache — make sure git ignores it. Cheap and
+ // idempotent, so a fresh clone's first build self-ignores.
+ ensureGitignored(root, outDir);
cardStats = writeCards(graph, outDir);
- } catch (err) {
- errors.push(`cards: ${err instanceof Error ? err.message : String(err)}`);
- }
- try {
writeIndex(outDir, cardStats.files);
- } catch (err) {
- errors.push(`INDEX.md: ${err instanceof Error ? err.message : String(err)}`);
- }
- try {
- errors.push(...writeCovers(graph, outDir).errors);
- } catch (err) {
- errors.push(`covers: ${err instanceof Error ? err.message : String(err)}`);
+ // Backfill concept nodes with their `covers:` symbol/file:line list (the
+ // OKF↔Wiring link). No-op when there are no concept nodes (a $0 build).
+ writeCovers(graph, outDir);
}
const byKind = {} as Record<Kind, number>;
diff --git a/src/graph/cards.ts b/src/graph/cards.ts
index 969f6200..c58e78b6 100644
--- a/src/graph/cards.ts
+++ b/src/graph/cards.ts
@@ -143,14 +143,6 @@ function pruneEmptyDirs(outDir: string): void {
if (existsSync(outDir)) visit(outDir);
}
-function readIfExists(path: string): string | null {
- try {
- return readFileSync(path, "utf8");
- } catch {
- return null;
- }
-}
-
/**
* Write one wiring card per source file into `outDir`, mirroring the source tree,
* and prune cards whose source no longer exists. Returns what changed.
@@ -172,12 +164,7 @@ export function writeCards(graph: GraphV1, outDir: string): CardStats {
const symbols = group.filter((n) => n.kind !== "file");
const cardPath = cardPathFor(outDir, sourcePath);
mkdirSync(dirname(cardPath), { recursive: true });
- const rendered = renderCard(sourcePath, fileNode, symbols, concepts.get(sourcePath) ?? []);
- // Skip identical rewrites. Cards are a pure projection, so most of them are
- // unchanged on a rebuild — and now that a rebuild can run before any query
- // (graph/refresh.ts), churning every card's mtime would wake editors and file
- // watchers on files that didn't actually change.
- if (readIfExists(cardPath) !== rendered) writeFileSync(cardPath, rendered);
+ writeFileSync(cardPath, renderCard(sourcePath, fileNode, symbols, concepts.get(sourcePath) ?? []));
written.add(cardPath);
files.push({ card: relative(outDir, cardPath), path: sourcePath, symbols: symbols.length });
}
@@ -231,12 +218,7 @@ export function writeIndex(outDir: string, files: CardFileInfo[]): void {
);
}
- // Same skip-if-identical rule as the cards themselves: a rebuild runs before every
- // query now, and INDEX.md is a pure projection, so rewriting it unchanged would wake
- // editors and file watchers on every single retrieval call.
- const rendered = lines.join("\n");
- const path = join(outDir, INDEX_FILE);
- if (readIfExists(path) !== rendered) writeFileSync(path, rendered);
+ writeFileSync(join(outDir, INDEX_FILE), lines.join("\n"));
}
/** One symbol a concept node covers: its name, kind, and `path:span` pointer. */
@@ -257,19 +239,11 @@ export interface CoverRef {
* A surgical frontmatter patch: the generated body and every other key are
* preserved verbatim; only `covers` is added/replaced. Concept nodes are the
* top-level `.md` files (cards live in subdirs; INDEX.md is skipped). On a $0
- * structure-only build there are no concept nodes, so this is a no-op.
- *
- * These are the one thing under `graft/` a human writes by hand, and a rebuild now
- * runs before every query rather than only on an explicit `graft build` — so this is
- * careful twice over. It never writes a file whose bytes wouldn't change, and it
- * refuses to touch a node whose frontmatter didn't parse: `matter()` reports
- * unparseable YAML by handing back zero keys and folding the whole `---` block into
- * the content, so re-stringifying would prepend a *second* frontmatter block and
- * bury the author's own text. Those are reported and skipped.
+ * structure-only build there are no concept nodes, so this is a no-op. Returns
+ * the number of nodes enriched.
*/
-export function writeCovers(graph: GraphV1, outDir: string): { enriched: number; errors: string[] } {
- const errors: string[] = [];
- if (!existsSync(outDir)) return { enriched: 0, errors };
+export function writeCovers(graph: GraphV1, outDir: string): number {
+ if (!existsSync(outDir)) return 0;
const symbolsByPath = new Map<string, NodeV1[]>();
for (const n of graph.nodes) {
@@ -286,23 +260,7 @@ export function writeCovers(graph: GraphV1, outDir: string): { enriched: number;
for (const entry of readdirSync(outDir)) {
if (!entry.endsWith(".md") || entry === INDEX_FILE) continue;
const full = join(outDir, entry);
- const raw = readIfExists(full);
- if (raw === null) continue;
-
- let parsed: matter.GrayMatterFile<string>;
- try {
- parsed = matter(raw);
- } catch (err) {
- errors.push(`${entry}: frontmatter unreadable, left untouched — ${err instanceof Error ? err.message : String(err)}`);
- continue;
- }
- // Delimiters present but nothing parsed out of them: broken YAML. Rewriting would
- // stack a new block on top of the old text instead of patching it.
- if (raw.startsWith("---") && Object.keys(parsed.data).length === 0) {
- errors.push(`${entry}: frontmatter did not parse, left untouched (fix its YAML to get \`covers:\`)`);
- continue;
- }
-
+ const parsed = matter(readFileSync(full, "utf8"));
const sources = Array.isArray(parsed.data.sources)
? (parsed.data.sources as Array<{ path?: string }>)
: [];
@@ -316,10 +274,8 @@ export function writeCovers(graph: GraphV1, outDir: string): { enriched: number;
// Re-stringify with covers appended last, so re-runs produce a stable diff.
const { covers: _prev, ...rest } = parsed.data as Record<string, unknown>;
- const rendered = matter.stringify(parsed.content, { ...rest, covers });
- if (rendered === raw) continue; // nothing moved — don't touch the author's file
- writeFileSync(full, rendered);
+ writeFileSync(full, matter.stringify(parsed.content, { ...rest, covers }));
enriched++;
}
- return { enriched, errors };
+ return enriched;
}
diff --git a/src/graph/fingerprint.ts b/src/graph/fingerprint.ts
index 7823c6ea..7de3928b 100644
--- a/src/graph/fingerprint.ts
+++ b/src/graph/fingerprint.ts
@@ -100,14 +100,12 @@ export function alwaysHash(): boolean {
* May a recorded `(size, mtimeMs, hash)` be trusted for the file `f` as it is on
* disk now, without reading it?
*
- * **One definition, shared by the probe and the builder.** They each had their own
- * once, and the two disagreed in both directions: `GRAFT_REFRESH=hash` was honored
- * here but not in `build.ts` (so the probe reported drift the rebuild then refused
- * to repair — a rebuild on every query, forever, still answering from pre-edit
- * code), and `build.ts` distrusted entries from a failed read while the probe
- * fast-pathed them (so a `chmod +r` that fixed a file was never noticed, because a
- * chmod changes neither size nor mtime). Any future rule about what a stat can be
- * trusted for belongs here and nowhere else.
+ * **The probe's rule only.** `buildGraph` deliberately does not use this: it reads
+ * and hashes every file, every time. A stat may decide whether a query bothers
+ * rebuilding; it may not decide what the rebuild itself looks at — otherwise
+ * `graft check` (which always re-hashes) can report drift that the `graft build` it
+ * recommends then refuses to repair. `GRAFT_REFRESH=hash` is the escape hatch for
+ * the probe's blind spot: a same-length edit inside one mtime tick.
*
* An empty `hash` means the last build never got the bytes — always re-read.
* A *parse* failure keeps its real hash, so it stays on the fast path: re-reading
diff --git a/src/graph/refresh.ts b/src/graph/refresh.ts
index 6d89e7ff..99c78c81 100644
--- a/src/graph/refresh.ts
+++ b/src/graph/refresh.ts
@@ -19,16 +19,22 @@
* - **Never a stampede.** It takes the same `graft/.cache/.sync.lock` the
* background sync uses, so concurrent MCP calls and the Stop hook can't pile up
* rebuilds on top of each other.
+ * - **Writes only what a query reads** (`graphOnly`): the graph, the `ask` sidecar,
+ * the freshness record. Not the markdown cards, not `INDEX.md`, not `.gitignore`.
+ * Those belong to an explicit `graft build` — which the `Stop` hook already runs
+ * at the end of a turn — so retrieval stays cheap and a read stays a read. It
+ * also leaves `stats.json` alone, so that same `Stop` hook still sees `dirty` and
+ * still rebuilds the passive surface.
*/
import { existsSync } from "node:fs";
import { join, resolve } from "node:path";
import { contextDirFor } from "../context/node-file.js";
-import { acquireLockIn, computeStats, patchStats, readStats, releaseLockIn } from "../util/state.js";
+import { acquireLockIn, releaseLockIn } from "../util/state.js";
import { CACHE_DIR } from "../context/node-file.js";
import { buildGraph } from "./build.js";
import { driftCount, isClean, probeDrift, type Drift } from "./fingerprint.js";
import { invalidateGraphCaches } from "./load.js";
-import { readGraph, wiringPath } from "./write.js";
+import { wiringPath } from "./write.js";
/** How long to wait for another process's in-flight rebuild before giving up and
* answering from the current graph. Long enough to ride out a small repo's build,
@@ -43,10 +49,6 @@ export interface RefreshResult {
drift?: Drift;
/** One-line explanation for the agent/user, when there's something worth saying. */
note?: string;
- /** Recoverable failures from the rebuild — a card that couldn't be written, a
- * concept node whose frontmatter didn't parse. The graph is fine; a projection
- * under `graft/` isn't, and nothing else would ever report it. */
- errors?: string[];
}
export interface RefreshOptions {
@@ -152,15 +154,14 @@ export async function ensureFreshGraph(root: string, opts: RefreshOptions = {}):
invalidateGraphCaches(outDir);
return CLEAN;
}
- // Tier-1 only: no summarizer, so no LLM call and no network, ever.
- const built = await buildGraph(dir, { contextDir: opts.contextDir });
+ // Tier-1 only: no summarizer, so no LLM call and no network, ever. And
+ // `graphOnly`: write the graph, the ask sidecar and the fingerprint, nothing
+ // else. The markdown projections under `graft/` stay the `Stop` hook's job —
+ // a query has no business rewriting the repo's `.gitignore` or churning every
+ // card's mtime, and skipping them is most of what keeps this cheap.
+ await buildGraph(dir, { contextDir: opts.contextDir, graphOnly: true });
invalidateGraphCaches(outDir);
- syncStats(dir, outDir);
- // The graph itself is current, but a projection under `graft/` may have failed
- // (a read-only card, ENOSPC). That can't be expressed as staleness — the
- // fingerprint is written and the next probe is clean by design — so say it out
- // loud instead of letting the passive markdown surface rot in silence.
- return { refreshed: true, drift: drift ?? undefined, errors: built.errors };
+ return { refreshed: true, drift: drift ?? undefined };
} finally {
unhook();
releaseLockIn(lockCache);
@@ -171,26 +172,6 @@ export async function ensureFreshGraph(root: string, opts: RefreshOptions = {}):
}
}
-/** Mirror what the background sync writes, so the statusline flips to `✓ synced`
- * mid-turn instead of showing `⚠ stale` until the turn ends. Best-effort: this is
- * a display cache, and the stats file only exists in a hooked-up repo anyway. */
-function syncStats(dir: string, outDir: string): void {
- try {
- if (!readStats(dir)) return; // no hooks in this repo — nothing reads it
- const w = readGraph(wiringPath(outDir));
- if (!w) return;
- patchStats(dir, {
- dirty: false,
- staleCount: 0,
- syncing: false,
- syncedAt: new Date().toISOString(),
- ...computeStats(w),
- });
- } catch {
- /* display-only — never let this fail a query */
- }
-}
-
/**
* Workspace variant: refresh each child repo's own graph (a workspace parent holds
* an index, never nodes). Children are independent, but they're refreshed in
@@ -228,17 +209,8 @@ export async function ensureFreshChildren(
/** The one-line note a CLI/MCP surface prints when a refresh actually happened.
* Null when there's nothing to say (the overwhelmingly common case). */
export function refreshNote(r: RefreshResult): string | null {
- if (r.note) return `[graft] ${r.note}${errorTail(r)}`;
+ if (r.note) return `[graft] ${r.note}`;
if (!r.refreshed) return null;
const n = r.drift ? driftCount(r.drift) : 0;
- return `[graft] refreshed the graph (${n || "?"} file${n === 1 ? "" : "s"} changed) before answering${errorTail(r)}`;
-}
-
-/** Projection failures, condensed. The first one is usually the whole story (they
- * share a cause — a permission, a full disk), so name it and count the rest. */
-function errorTail(r: RefreshResult): string {
- const errs = r.errors ?? [];
- if (!errs.length) return "";
- const more = errs.length > 1 ? ` (+${errs.length - 1} more)` : "";
- return `; ${errs.length} write error${errs.length === 1 ? "" : "s"} under graft/: ${errs[0]}${more}`;
+ return `[graft] refreshed the graph (${n || "?"} file${n === 1 ? "" : "s"} changed) before answering`;
}
diff --git a/src/graph/write.ts b/src/graph/write.ts
index 05c080a0..8b993a88 100644
--- a/src/graph/write.ts
+++ b/src/graph/write.ts
@@ -8,9 +8,8 @@
* timestamps, so rebuilding an unchanged repo produces a byte-identical file and
* git diffs stay minimal.
*/
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { writeFileAtomic } from "../util/state.js";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
import type { EdgeV1, GraphV1, NodeV1 } from "./types.js";
/** Hidden subdir under the context dir that holds machine-only graph artifacts. */
@@ -41,12 +40,8 @@ export function writeGraph(graph: GraphV1, outDir: string): string {
edges: [...graph.edges].sort(edgeOrder),
};
const path = wiringPath(outDir);
- // Atomic, because a query can now rebuild the graph (`graph/refresh.ts`) while
- // something else is reading it — a second MCP call, the statusline's poll, a
- // `graft check` from the edit hook, another graft process. None of those take
- // the build lock, and a truncating write would hand them a partial document,
- // which `readGraph` can only report as "no graph — run graft build".
- writeFileAtomic(path, JSON.stringify(sorted, null, 2) + "\n");
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, JSON.stringify(sorted, null, 2) + "\n");
return path;
}
diff --git a/src/util/state.ts b/src/util/state.ts
index cd33f1e2..0f309d4c 100644
--- a/src/util/state.ts
+++ b/src/util/state.ts
@@ -11,7 +11,6 @@
*/
import { readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
import { join, dirname } from 'node:path';
-import type { GraphV1 } from '../graph/types.js';
export interface Stats {
nodeCount: number; edgeCount: number; languages: string[];
@@ -36,33 +35,24 @@ export function readJson<T>(p: string): T | null {
try { return JSON.parse(readFileSync(p, 'utf8')) as T; } catch { return null; }
}
/**
- * Write `text` to `p` so a concurrent reader sees either the whole old file or the
- * whole new one — never a truncated prefix.
+ * Write JSON to `p` via a scratch file and a rename, so a concurrent reader sees
+ * either the whole old file or the whole new one — never a truncated prefix. The
+ * pid in the temp name keeps two concurrent writers off each other's scratch file.
*
- * `writeFileSync` truncates the destination to zero and *then* streams bytes into
- * it, so for the milliseconds that takes, anyone who opens the path reads a partial
- * document. Writing to a scratch file and renaming over the target avoids that
- * entirely: `rename` within a filesystem is atomic, and it replaces the directory
- * entry rather than modifying the file in place, so a reader that already opened
- * the old file keeps reading a complete one.
- *
- * The pid in the temp name keeps two concurrent writers off each other's scratch
- * file. This is the only atomic-write implementation in the codebase on purpose —
- * `graph/write.ts` uses it for `wiring.json` and `ask/index-file.ts` for the sidecar
- * that has to agree with it, both of which a query can now rewrite while the
- * statusline, a second graft process, or another MCP call is reading them.
+ * `compact` drops the indentation, for the caches only a machine ever opens —
+ * it's ~30% of the bytes on a big, deep object.
*
* A failed write takes its scratch file with it. Every CLI invocation is a new pid,
* so the names never collide and never get reused: leaving them behind means a repo
- * that fails this write once per query (ENOSPC, or a Windows indexer holding the
- * target open) accumulates one full-size copy of the graph per query, and nothing
- * in graft ever lists `.graph/` or `.cache/` to clean them up.
+ * that fails this write repeatedly (ENOSPC, or a Windows indexer holding the target
+ * open) accumulates one full-size file per attempt, and nothing in graft ever lists
+ * `.cache/` to clean them up.
*/
-export function writeFileAtomic(p: string, text: string): void {
+export function writeJsonAtomic(p: string, value: unknown, compact = false): void {
mkdirSync(dirname(p), { recursive: true });
const tmp = `${p}.${process.pid}.tmp`;
try {
- writeFileSync(tmp, text);
+ writeFileSync(tmp, compact ? JSON.stringify(value) : JSON.stringify(value, null, 2));
renameSync(tmp, p);
} catch (e) {
try { rmSync(tmp, { force: true }); } catch { /* nothing more we can do */ }
@@ -70,12 +60,6 @@ export function writeFileAtomic(p: string, text: string): void {
}
}
-/** {@link writeFileAtomic} for JSON. `compact` drops the indentation, for the
- * caches only a machine ever opens — it's ~30% of the bytes on a big, deep object. */
-export function writeJsonAtomic(p: string, value: unknown, compact = false): void {
- writeFileAtomic(p, compact ? JSON.stringify(value) : JSON.stringify(value, null, 2));
-}
-
export function readStats(d: string): Stats | null { return readJson<Stats>(statsPath(d)); }
export function writeStats(d: string, s: Stats): void { writeJsonAtomic(statsPath(d), s); }
// Best-effort read-modify-write; not atomic across concurrent processes, but acceptable
@@ -119,20 +103,3 @@ export function acquireLockIn(cache: string): boolean {
export function releaseLockIn(cache: string): void {
try { rmSync(join(cache, LOCK_FILE)); } catch { /* already gone */ }
}
-
-/** The graph-derived half of {@link Stats} — everything the statusline shows that
- * isn't drift state. Lives here so the hooks and the pre-query auto-refresh report
- * identical numbers. */
-export function computeStats(
- w: GraphV1,
-): Pick<Stats, 'nodeCount' | 'edgeCount' | 'languages' | 'totalCount' | 'readyCount'> {
- const nodes = w.nodes ?? [];
- const edges = w.edges ?? [];
- return {
- nodeCount: w.meta?.nodeCount ?? nodes.length,
- edgeCount: w.meta?.edgeCount ?? edges.length,
- languages: w.meta?.languages ?? [],
- totalCount: nodes.length,
- readyCount: nodes.filter((n) => n.summary_state === 'ready').length,
- };
-}
diff --git a/test/claude-state.test.ts b/test/claude-state.test.ts
index a4900cc8..4d052edd 100644
--- a/test/claude-state.test.ts
+++ b/test/claude-state.test.ts
@@ -5,7 +5,7 @@ import { tmpdir } from 'node:os';
import { join } from 'node:path';
import {
emptyStats, readStats, writeStats, patchStats,
- readSession, writeSession, acquireLock, releaseLock, cacheDir, LOCK_STALE_MS, writeFileAtomic,
+ readSession, writeSession, acquireLock, releaseLock, cacheDir, LOCK_STALE_MS, writeJsonAtomic,
} from '../src/claude/state.js';
function fresh(): string { return mkdtempSync(join(tmpdir(), 'graft-state-')); }
@@ -49,7 +49,7 @@ test('acquireLock reclaims a stale lock', () => {
assert.equal(acquireLock(d), true, 'stale lock reclaimed');
});
-test('writeFileAtomic leaves no scratch file behind when the write fails', (t) => {
+test('writeJsonAtomic leaves no scratch file behind when the write fails', (t) => {
if (process.getuid?.() === 0) return t.skip('root writes anywhere, so a read-only dir proves nothing');
const d = fresh();
const dir = join(d, 'locked');
@@ -57,10 +57,10 @@ test('writeFileAtomic leaves no scratch file behind when the write fails', (t) =
chmodSync(dir, 0o500);
// Every CLI invocation is a new pid, so a repeatedly failing write would leave one
- // full-size `<path>.<pid>.tmp` per query, and nothing in graft ever lists these
+ // full-size `<path>.<pid>.tmp` per attempt, and nothing in graft ever lists these
// directories to clean them up — on a nearly-full disk that accelerates the ENOSPC
// that caused it.
- assert.throws(() => writeFileAtomic(join(dir, 'out.json'), 'x'.repeat(1024)));
+ assert.throws(() => writeJsonAtomic(join(dir, 'out.json'), { pad: 'x'.repeat(1024) }));
chmodSync(dir, 0o700);
assert.deepEqual(readdirSync(dir), [], 'no .tmp residue');
});
diff --git a/test/covers.test.ts b/test/covers.test.ts
index 3cea34a6..6a9139fa 100644
--- a/test/covers.test.ts
+++ b/test/covers.test.ts
@@ -5,7 +5,7 @@
*/
import { test } from "node:test";
import assert from "node:assert/strict";
-import { mkdtempSync, writeFileSync, readFileSync, rmSync, statSync } from "node:fs";
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
import { join } from "node:path";
import { tmpdir } from "node:os";
import matter from "gray-matter";
@@ -74,56 +74,3 @@ test("re-running the wiring build leaves covers byte-stable", async () => {
rmSync(dir, { recursive: true, force: true });
}
});
-
-/**
- * Concept nodes are the one thing under `graft/` a human writes by hand, and a
- * rebuild now runs before every *query* rather than only on an explicit build. So
- * the projection has to leave alone anything it isn't actually changing, and refuse
- * to touch what it can't round-trip.
- */
-test("a rebuild leaves untouched concept nodes and INDEX.md alone", async () => {
- const dir = makeFixture();
- try {
- await buildContext(dir, { model: "fake", ...fakeProviders() });
- await buildGraph(dir);
-
- const node = join(dir, "graft", "auth-service.md");
- const index = join(dir, "graft", "INDEX.md");
- const before = { node: statSync(node).mtimeMs, index: statSync(index).mtimeMs };
-
- // Nothing about the repo changed, so nothing under graft/ should be rewritten:
- // every rewrite wakes editors and file watchers, once per query.
- await new Promise((r) => setTimeout(r, 12)); // let the clock move
- await buildGraph(dir);
-
- assert.equal(statSync(node).mtimeMs, before.node, "concept node was rewritten with identical bytes");
- assert.equal(statSync(index).mtimeMs, before.index, "INDEX.md was rewritten with identical bytes");
- } finally {
- rmSync(dir, { recursive: true, force: true });
- }
-});
-
-test("a concept node whose frontmatter does not parse is reported, not overwritten", async () => {
- const dir = makeFixture();
- try {
- await buildContext(dir, { model: "fake", ...fakeProviders() });
- await buildGraph(dir);
-
- // Frontmatter delimiters, but YAML that yields no keys. gray-matter reports that
- // by handing back zero data and folding the whole block into the content, so
- // re-stringifying would stack a SECOND `---` block on top of the author's text.
- const broken = join(dir, "graft", "hand-written.md");
- const raw = "---\nname: [unclosed\n bad: : :\n---\n\nSome prose I wrote myself.\n";
- writeFileSync(broken, raw);
-
- const built = await buildGraph(dir);
-
- assert.equal(readFileSync(broken, "utf8"), raw, "the author's file must come back byte-identical");
- assert.ok(
- built.errors.some((e) => e.startsWith("hand-written.md:") && /did not parse/.test(e)),
- `and the skip must be reported: ${JSON.stringify(built.errors)}`,
- );
- } finally {
- rmSync(dir, { recursive: true, force: true });
- }
-});
diff --git a/test/graph-incremental.test.ts b/test/graph-incremental.test.ts
index ebc21b2a..783478ce 100644
--- a/test/graph-incremental.test.ts
+++ b/test/graph-incremental.test.ts
@@ -296,29 +296,55 @@ test("with no extractor identity, nothing is memoized — and 'unknown' is never
assert.equal(stampDir(mkdtempSync(join(tmpdir(), "graft-empty-")), ".js"), null, "an empty dir has no identity");
});
-test("the ask sidecar lands before the graph, and lands atomically", async () => {
+test("an incremental rebuild leaves the ask sidecar agreeing with the graph", async () => {
const d = repo();
await buildGraph(d);
- const idxPath = join(outOf(d), ".cache", "ask-index.json");
- const before = statSync(idxPath).ino;
writeFileSync(join(d, "src", "math.ts"), `${MATH}export function mul(a: number): number {\n return a * 2;\n}\n`);
- await buildGraph(d);
-
- // Atomic: replaced by rename, not truncated in place. A reader that catches this
- // file mid-write gets a parse error, which `readAskIndex` can only report as "no
- // sidecar" — and the fallback is degraded, because wiring.json's nodes have had
- // `body_text` stripped, so body-only matches disappear.
- assert.notEqual(statSync(idxPath).ino, before);
- assert.deepEqual(readdirSync(join(outOf(d), ".cache")).filter((f) => f.includes(".tmp")), []);
+ await buildGraph(d); // warm: math.ts re-parsed, everything else replayed
- // Written first, so "new graph ⇒ matching sidecar" holds for anyone reading the
- // pair. mtime ordering is the observable proxy for the write order.
- assert.ok(
- statSync(idxPath).mtimeMs <= statSync(wiringPath(outOf(d))).mtimeMs,
- "the sidecar must not be newer than the graph it describes",
- );
+ // The sidecar is built from the in-memory graph, never from a re-read of
+ // wiring.json (whose nodes have had `body_text` stripped), so a replayed node
+ // has to arrive with its body intact for the pair to agree.
const idx = readAskIndex(outOf(d));
const g = readGraph(wiringPath(outOf(d))) as GraphV1;
- assert.equal(idx?.docs.length, g.nodes.length, "and the pair agrees");
+ assert.equal(idx?.docs.length, g.nodes.length, "the pair agrees on the node set");
+ assert.ok(idx!.docs.some((doc) => doc.id.endsWith("#mul")), "including the new symbol");
+});
+
+/**
+ * `graft check` re-reads and re-hashes every file; the builder must too. If the
+ * builder trusted `(size, mtimeMs)` the way the probe does, then on a filesystem with
+ * coarse mtime granularity a same-length edit inside one tick would leave `graft
+ * check` reporting drift that the `graft build` it recommends could not repair — the
+ * documented fix, doing nothing, forever.
+ */
+test("a build repairs an edit that leaves size and mtime untouched", async () => {
+ const d = repo();
+ await buildGraph(d);
+ const file = join(d, "src", "math.ts");
+ const size = statSync(file).size;
+
+ // A rename to a same-length name.
+ writeFileSync(file, readFileSync(file, "utf8").replace("export function add", "export function sum"));
+ assert.equal(statSync(file).size, size, "the edit is size-neutral");
+
+ // Now make the memo's record match the file's stat *as it is now* while keeping the
+ // pre-edit hash and nodes. That is precisely the state a 1s-granularity mount hands
+ // you for free, and it avoids `utimesSync`, whose float-seconds round-trip can't
+ // reproduce an mtimeMs exactly.
+ const memoPath = extractCachePath(outOf(d))!;
+ const memo = JSON.parse(readFileSync(memoPath, "utf8")) as {
+ files: Record<string, { size: number; mtimeMs: number }>;
+ };
+ const now = statSync(file);
+ memo.files["src/math.ts"].size = now.size;
+ memo.files["src/math.ts"].mtimeMs = now.mtimeMs;
+ writeFileSync(memoPath, JSON.stringify(memo));
+
+ const r = await buildGraph(d);
+ assert.equal(r.parsed, 1, "the file was re-parsed despite the identical stat");
+ const ids = (readGraph(wiringPath(outOf(d))) as GraphV1).nodes.map((n) => n.id);
+ assert.ok(ids.includes("src/math.ts#sum"), "and the graph reflects the rename");
+ assert.equal(ids.includes("src/math.ts#add"), false, "the old symbol is gone");
});
diff --git a/test/graph-refresh.test.ts b/test/graph-refresh.test.ts
index 358003a6..ef7b5e9c 100644
--- a/test/graph-refresh.test.ts
+++ b/test/graph-refresh.test.ts
@@ -144,7 +144,16 @@ test("a rebuild already in flight is waited out, then reported — never a hang"
assert.ok(waited >= 1000 && waited < 10000, `should wait out the lock briefly, waited ${waited}ms`);
});
-test("a refresh updates the statusline stats, but only where they already exist", async () => {
+/**
+ * The gate must leave `stats.json` completely alone, and this is load-bearing rather
+ * than merely tidy. `handleStop` only spawns the end-of-turn `graft build` when
+ * `stats.dirty` is set. A refresh writes the graph but deliberately not the markdown
+ * projections, so if it cleared `dirty` — which is exactly what "flip the statusline
+ * to ✓ synced mid-turn" would mean — the one thing that rebuilds `graft/`'s cards
+ * and INDEX.md would stop running, and the passive surface an agent greps would
+ * never catch up.
+ */
+test("a refresh leaves the statusline stats alone, so the Stop hook still fires", async () => {
const d = repo();
await buildGraph(d);
writeFileSync(join(d, "src", "math.ts"), `${MATH}export const X = 1;\n`);
@@ -153,16 +162,15 @@ test("a refresh updates the statusline stats, but only where they already exist"
await ensureFreshGraph(d);
assert.equal(readStats(d), null);
- // With one, the refresh clears the drift flags the edit hook set mid-turn —
- // that's what flips the statusline from `⚠ stale` to `✓ synced`.
writeStats(d, { ...emptyStats(), dirty: true, staleCount: 3 });
writeFileSync(join(d, "src", "math.ts"), `${MATH}export const Y = 2;\n`);
- await ensureFreshGraph(d);
+ const r = await ensureFreshGraph(d);
+ assert.equal(r.refreshed, true, "the graph itself was rebuilt");
+
const s = readStats(d);
- assert.equal(s?.dirty, false);
- assert.equal(s?.staleCount, 0);
- assert.ok((s?.nodeCount ?? 0) > 0, "and it refreshes the counts from the new graph");
- assert.ok(s?.syncedAt);
+ assert.equal(s?.dirty, true, "still dirty — the passive surface has not been rebuilt");
+ assert.equal(s?.staleCount, 3, "and the edit hook's count is not overwritten");
+ assert.equal(s?.syncedAt, null);
});
test("a failed rebuild still answers from the graph on disk", async (t) => {
@@ -173,14 +181,11 @@ test("a failed rebuild still answers from the graph on disk", async (t) => {
writeFileSync(join(d, "src", "math.ts"), `${MATH}export const X = 1;\n`);
// Make the graph write itself fail: the query must degrade to the old graph, not
- // start erroring because a rebuild couldn't happen. The *directory* is what has
- // to be blocked — `writeGraph` installs the new graph with tmp+rename now (see
- // `graph-write-atomic.test.ts`), and both the scratch write and the rename need
- // write permission on the directory, while the old file's own mode is irrelevant.
- const graphDir = dirname(wiringPath(outOf(d)));
- chmodSync(graphDir, 0o500);
+ // start erroring because a rebuild couldn't happen.
+ const graphFile = wiringPath(outOf(d));
+ chmodSync(graphFile, 0o400);
const r = await ensureFreshGraph(d);
- chmodSync(graphDir, 0o700);
+ chmodSync(graphFile, 0o600);
assert.equal(r.refreshed, false);
assert.match(r.note ?? "", /refresh skipped/);
@@ -259,17 +264,14 @@ test("a file that becomes readable again is picked up through the probe", async
assert.equal(hasSymbol(d, "src/hidden.ts#reachable"), true);
});
-test("the fingerprint is written even when the extract memo can't be", async (t) => {
+test("an unwritable cache costs reuse, not correctness", async (t) => {
if (process.getuid?.() === 0) return t.skip("root writes anywhere, so a read-only dir proves nothing");
const d = repo();
await buildGraph(d);
- // An unwritable memo costs the next build its reuse. It must not cost every future
- // query a full cold rebuild, which is what gating the fingerprint on it did.
- //
// The write has to be made to fail for real. An earlier version of this test
- // chmod'd extract.json itself — useless, because `writeExtractCache` goes through
- // `writeFileAtomic`, and rename(2) needs write permission on the *directory*, not
+ // chmod'd extract.json itself — useless, because the sidecars go out through
+ // `writeJsonAtomic`, and rename(2) needs write permission on the *directory*, not
// on the file. It returned true, the test passed, and it would have passed against
// the pre-fix code too.
const cache = join(outOf(d), ".cache");
@@ -279,56 +281,70 @@ test("the fingerprint is written even when the extract memo can't be", async (t)
writeFileSync(join(d, "src", "math.ts"), `${MATH}${MUL}`);
chmodSync(cache, 0o500);
- const built = await buildGraph(d);
+ await buildGraph(d);
chmodSync(cache, 0o700);
assert.equal(readFileSync(memo, "utf8"), before, "the memo really could not be written");
assert.ok(hasSymbol(d, "src/math.ts#mul"), "but the graph itself was rebuilt");
- // The fingerprint lives in the same unwritable dir, so it couldn't be written
- // either — the invariant that matters is that the NEXT build (with the dir
- // writable again) lays one down and the query path settles.
+ // Losing the memo and the fingerprint is a performance failure, not a correctness
+ // one: the next query rebuilds because it can't prove it doesn't need to. Once the
+ // directory is writable again the fast path comes back on its own.
await buildGraph(d);
const drift = probeDrift(d, outOf(d));
assert.ok(drift, "a fingerprint exists, so the probe has a fast path");
assert.ok(isClean(drift), "and it says the graph matches the tree");
assert.deepEqual((await ensureFreshGraph(d)).refreshed, false, "so a query stops rebuilding");
- // The memo is the only thing whose loss is silent (it costs reuse, nothing else).
- // The ask sidecar lives in the same directory and *is* worth reporting, because
- // losing it degrades ranking rather than just performance.
- assert.ok(
- built.errors.some((e) => e.startsWith("ask-index:")),
- `the sidecar failure is reported: ${JSON.stringify(built.errors)}`,
- );
});
-test("a failed projection is reported, and never becomes permanent drift", async (t) => {
- if (process.getuid?.() === 0) return t.skip("root writes anywhere, so a read-only file proves nothing");
+/**
+ * The query path writes the graph, the ask sidecar and the fingerprint — and stops.
+ * Cards and INDEX.md are what a human reads and what the agent greps; they are
+ * rebuilt by an explicit `graft build`, which is what the `Stop` hook runs at the
+ * end of a turn. Keeping them off the query path is what makes a refresh cheap, and
+ * it means a read-only card or an unparseable hand-written concept node can never be
+ * reached — let alone made permanent — by a retrieval call.
+ */
+test("a refresh rebuilds the graph but not the markdown projections", async () => {
const d = repo();
await buildGraph(d);
- // One unwritable file under graft/ — a dir you don't fully own, a read-only mount.
const index = join(outOf(d), "INDEX.md");
- assert.ok(existsSync(index));
- chmodSync(index, 0o400);
- // A new file changes INDEX.md's roster, so the write is actually attempted —
- // an unchanged render is skipped now, by design.
+ const card = join(outOf(d), "src", "math.md");
+ const newCard = join(outOf(d), "src", "extra.md");
+ assert.ok(existsSync(index) && existsSync(card), "an explicit build wrote both");
+ const indexBefore = readFileSync(index, "utf8");
+ const cardBefore = readFileSync(card, "utf8");
+
writeFileSync(join(d, "src", "extra.ts"), MUL);
+ const r = await ensureFreshGraph(d);
- // The graph must still get built, the failure must be told to the caller, and the
- // fingerprint must be laid down — otherwise every later query re-runs the whole
- // post-extraction pipeline (edges, enrichment, ask index, every card), throws
- // again, and answers from a graph that was already current. Forever.
- const first = await ensureFreshGraph(d);
- assert.equal(first.refreshed, true);
+ assert.equal(r.refreshed, true);
assert.equal(hasSymbol(d, "src/extra.ts#mul"), true, "the graph is current");
- assert.ok(first.errors?.length, "the projection failure is reported");
- assert.match(refreshNote(first) ?? "", /write error.* under graft\/: INDEX\.md/);
+ assert.equal(existsSync(newCard), false, "no card for it yet");
+ assert.equal(readFileSync(index, "utf8"), indexBefore, "INDEX.md untouched");
+ assert.equal(readFileSync(card, "utf8"), cardBefore, "existing cards untouched");
- const second = await ensureFreshGraph(d);
- chmodSync(index, 0o600);
- assert.equal(second.refreshed, false, "and it converges — no rebuild on the next query");
- assert.equal(refreshNote(second), null);
+ // An explicit build — the Stop hook's job — is what catches the surface up.
+ await buildGraph(d);
+ assert.equal(existsSync(newCard), true);
+});
+
+test("a refresh never writes the repo's .gitignore", async () => {
+ const d = repo();
+ await buildGraph(d); // an explicit build DOES self-ignore — that part is unchanged
+ const ignore = join(d, ".gitignore");
+ assert.match(readFileSync(ignore, "utf8"), /graft\//);
+
+ // A repo that excludes graft/ some other way (.git/info/exclude, a global
+ // core.excludesfile) and deliberately has no line here. A query is a read; it must
+ // not hand the user an unexplained modification to a tracked file.
+ rmSync(ignore);
+ writeFileSync(join(d, "src", "math.ts"), `${MATH}${MUL}`);
+ const r = await ensureFreshGraph(d);
+
+ assert.equal(r.refreshed, true, "the refresh still happened");
+ assert.equal(existsSync(ignore), false, "and it left .gitignore alone");
});
test("after waiting out another process's rebuild, the waiter does not rebuild too", async () => {
diff --git a/test/graph-write-atomic.test.ts b/test/graph-write-atomic.test.ts
deleted file mode 100644
index cf9357ba..00000000
--- a/test/graph-write-atomic.test.ts
+++ /dev/null
@@ -1,148 +0,0 @@
-/**
- * `wiring.json` must never be observable half-written.
- *
- * This stopped being theoretical when a query gained the ability to rebuild the
- * graph (`graph/refresh.ts`): the writer takes the build lock, but no reader does —
- * not the statusline's poll, not a second MCP call, not another graft process, not
- * `graft check` from the edit hook. A truncating write hands all of them a partial
- * document, and `readGraph` can only report that as null, i.e. "no graph — run
- * graft build" on a repo that has one.
- */
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { closeSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs";
-import { spawn } from "node:child_process";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { readGraph, wiringPath, writeGraph } from "../src/graph/write.js";
-import type { GraphV1, NodeV1 } from "../src/graph/types.js";
-
-/** A graph big enough that serializing it isn't instantaneous — the race window
- * has to be wide enough for a concurrent reader to land inside it. */
-function graph(nodeCount: number, marker: string): GraphV1 {
- const nodes: NodeV1[] = [];
- for (let i = 0; i < nodeCount; i++) {
- nodes.push({
- id: `src/m${i}.ts#fn${i}`,
- name: `fn${i}`,
- kind: "function",
- path: `src/m${i}.ts`,
- start_line: 1,
- end_line: 3,
- signature: `function fn${i}(a: number): number`,
- body_hash: `${marker}${i}`,
- summary: null,
- summary_state: "pending",
- // Padding, so the file is megabytes rather than kilobytes.
- doc: `${marker} `.repeat(40),
- } as unknown as NodeV1);
- }
- return {
- meta: { version: 1, nodeCount, edgeCount: 0, languages: ["ts"], scopes: [] },
- nodes,
- edges: [],
- } as unknown as GraphV1;
-}
-
-function outDir(): string {
- return join(mkdtempSync(join(tmpdir(), "graft-atomic-")), "graft");
-}
-
-test("writeGraph replaces the file instead of truncating it in place", () => {
- const out = outDir();
- writeGraph(graph(50, "a"), out);
- const path = wiringPath(out);
- const before = statSync(path).ino;
-
- writeGraph(graph(50, "b"), out);
-
- // A truncating `writeFileSync` keeps the same inode and empties it; a tmp+rename
- // installs a different one. This is the whole difference, and it needs no timing
- // to observe.
- assert.notEqual(statSync(path).ino, before, "the destination must be replaced, not modified in place");
- assert.equal(readGraph(path)?.nodes[0]?.body_hash, "b0");
-
- // And the scratch file must not be left lying around next to it.
- const strays = readdirSync(dirname(path)).filter((f) => f.includes(".tmp"));
- assert.deepEqual(strays, [], `left temp files behind: ${strays.join(", ")}`);
-});
-
-test("a reader holding the file open across a rewrite still reads a whole graph", () => {
- const out = outDir();
- writeGraph(graph(400, "a"), out);
- const path = wiringPath(out);
- const original = readFileSync(path, "utf8");
-
- // Exactly the statusline's position: it opened the file, and mid-read a query
- // rebuilt the graph underneath it.
- const fd = openSync(path, "r");
- try {
- const head = Buffer.alloc(64);
- readSync(fd, head, 0, 64, 0); // started reading...
- writeGraph(graph(400, "b"), out); // ...and the graph is rewritten now
-
- const size = statSync(path).size;
- const rest = Buffer.alloc(original.length);
- const n = readSync(fd, rest, 0, original.length, 0);
- const seen = rest.subarray(0, n).toString("utf8");
-
- // The open handle keeps the file it opened: complete, parseable, and the
- // version it started with. Under a truncating write this read would return the
- // new file's bytes at old offsets — a spliced document that parses to nothing.
- assert.equal(seen, original, "the reader must see the whole document it opened");
- assert.equal(JSON.parse(seen).nodes[0].body_hash, "a0");
- assert.ok(size > 0, "and the new file is fully on disk for the next reader");
- assert.equal(readGraph(path)?.nodes[0]?.body_hash, "b0");
- } finally {
- closeSync(fd);
- }
-});
-
-test("a concurrent reader never parses a torn graph", async () => {
- const out = outDir();
- writeGraph(graph(3000, "a"), out);
- const path = wiringPath(out);
- const bytes = statSync(path).size;
- assert.ok(bytes > 1_000_000, `fixture should be megabytes to widen the window, got ${bytes}`);
-
- // A separate process, because writes here are synchronous — nothing in this
- // process could observe a partial file even if one existed.
- const READ_MS = 600;
- const reader = spawn(
- process.execPath,
- [
- "-e",
- `const fs = require("fs");
- let ok = 0, bad = 0, empty = 0;
- const end = Date.now() + ${READ_MS};
- while (Date.now() < end) {
- let text;
- try { text = fs.readFileSync(process.argv[1], "utf8"); } catch { bad++; continue; }
- if (text.length === 0) { empty++; continue; }
- try { JSON.parse(text); ok++; } catch { bad++; }
- }
- process.stdout.write(JSON.stringify({ ok, bad, empty }));`,
- path,
- ],
- { stdio: ["ignore", "pipe", "inherit"] },
- );
- let stdout = "";
- reader.stdout.setEncoding("utf8");
- reader.stdout.on("data", (c: string) => (stdout += c));
-
- // Rewrite continuously for as long as it's reading.
- const deadline = Date.now() + READ_MS;
- let writes = 0;
- while (Date.now() < deadline) {
- writeGraph(graph(3000, writes % 2 === 0 ? "a" : "b"), out);
- writes++;
- }
-
- await new Promise<void>((resolve) => reader.on("close", () => resolve()));
- const r = JSON.parse(stdout) as { ok: number; bad: number; empty: number };
-
- assert.ok(writes > 1, `the writer should have rewritten the file repeatedly, did ${writes}`);
- assert.ok(r.ok > 0, `the reader should have read it repeatedly, got ${JSON.stringify(r)}`);
- assert.equal(r.empty, 0, "no reader may ever see a zero-length graph");
- assert.equal(r.bad, 0, `every read must parse; got ${JSON.stringify(r)} across ${writes} writes`);
-});