@nanonets/graft 0.8.0 → 0.8.2

package/dist/graph/extract-cache.d.ts

@@ -0,0 +1,96 @@
+import type { RawEdge } from "./extract.js";
+import type { NodeV1 } from "./types.js";
+export interface ExtractEntry {
+    size: number;
+    mtimeMs: number;
+    /** sha256 of the file's bytes — the same value as its `kind:"file"` node's `body_hash`. */
+    hash: string;
+    nodes: NodeV1[];
+    rawEdges: RawEdge[];
+    /** Set when this file couldn't be read or parsed. The entry exists anyway so the
+     * freshness probe doesn't flag the file as new on every query; replaying it
+     * re-reports the same error and contributes no nodes, exactly as a cold build
+     * would. */
+    error?: string;
+}
+export interface ExtractCache {
+    version: number;
+    /** Identity of the extractor that produced these entries. */
+    extractor: string;
+    /** repo-relative source path → its last parse. */
+    files: Record<string, ExtractEntry>;
+}
+/**
+ * Where this graft's memo lives: `<outDir>/.cache/extract.<stamp>.json`.
+ *
+ * The stamp is in the *filename*, not just inside the file, so two grafts working
+ * on one repo keep separate memos instead of evicting each other. That is the
+ * default install, not an exotic case: `graft init` wires the MCP server as
+ * `npx -y @nanonets/graft` (which resolves the latest published version) while the
+ * Claude Code hooks run the locally installed one. The moment those two versions
+ * differ, a single shared file means the prompt hook and every MCP retrieval take
+ * turns rejecting each other's entries and cold-re-parsing the whole repo — the memo
+ * would never help anyone.
+ *
+ * Null stamp → null path → no memo at all. See {@link extractorStamp}.
+ */
+export declare function extractCachePath(outDir: string): string | null;
+/** Keep `.cache/` from growing a file per version forever: after writing, drop all
+ * but the newest `keep` files sharing a prefix. Best-effort and never fatal — this
+ * is a cache directory, and a failure here costs disk, not correctness. */
+export declare function pruneSidecars(cacheDir: string, prefix: string, keep?: number): void;
+/**
+ * Identity of the code that produces the cached parses. Both sidecars key on it,
+ * so *anything* that can change extraction output has to change this string.
+ *
+ * Content-hashed over every sibling module in this directory, plus the package
+ * version. Two earlier instincts are deliberately rejected:
+ *
+ * - **Not a timestamp.** This was `mtime:size` of `extract.js` alone, which is
+ *   wrong in both directions. Too loose: the parse of `db.count()` depends on
+ *   `bindings.ts` deciding that `db` is a `UserRepo` (that answer is stored *in*
+ *   the cached entry, as an edge's `recvType`), and fixing a binding bug leaves
+ *   `extract.js`'s emitted bytes untouched — so any build that skips rewriting
+ *   unchanged output keeps the old stamp and silently replays pre-fix edges. Too
+ *   tight: a rebuild that rewrites identical content moves the mtime and throws
+ *   away the whole memo for nothing.
+ * - **Not a hand-kept list of modules.** A list is correct exactly until someone
+ *   moves parse logic into a module nobody added to it, and the failure is silent.
+ *
+ * Hashing the directory over-invalidates a little — editing any `graph/` module
+ * costs one cold rebuild — which is no more often than a version bump already
+ * costs, and always in the safe direction. The package version is folded in so a
+ * tree-sitter grammar upgrade (which changes parse output without changing any of
+ * graft's own files) invalidates too.
+ *
+ * Measured at ~0.5ms for 21 files / 556KB, paid once per process.
+ *
+ * **Null when no identity can be established at all**, and that is deliberately not
+ * a string. It used to return `"unknown"` on failure — but `"unknown"` was then
+ * *written into the sidecars as a real identity*, and every later run compared equal
+ * to it, so any environment where stamping fails (a `pkg`/`bun-compile` single-file
+ * build, an asar-style read, a directory that can't be listed) permanently lost the
+ * ability to notice an extractor change. A sentinel that doubles as a valid value
+ * silently disables the whole mechanism. Null forces callers to decide instead, and
+ * {@link extractCachePath} decides not to have a memo.
+ */
+export declare function extractorStamp(): string | null;
+/**
+ * Hash every `ext` file in `dir`, plus `version`. Null when the directory holds no
+ * such file. Separated from {@link extractorStamp} so a test can prove the property
+ * that matters: a change to *any* module in the directory moves the stamp, not just
+ * the one the old implementation happened to watch.
+ */
+export declare function stampDir(dir: string, ext: string, version?: string): string | null;
+export declare function emptyExtractCache(): ExtractCache;
+/** The cache for `outDir`, or an empty one when it's absent, unparseable, written by
+ * a different cache version, or when this graft has no identity to key on (then
+ * every build is cold, which is slow but never wrong). The stamp is in the filename,
+ * so the `extractor` field is a second check rather than the only one. */
+export declare function readExtractCache(outDir: string): ExtractCache;
+/** Best-effort write — a full graph is already on disk by the time this runs, so an
+ * unwritable cache dir must never fail the build (it only costs the next build its
+ * reuse). Returns false when nothing was written, including the deliberate case of
+ * having no extractor identity: a parse we can't attribute must never be replayed. */
+export declare function writeExtractCache(outDir: string, cache: ExtractCache): boolean;
+//# sourceMappingURL=extract-cache.d.ts.map

package/dist/graph/extract-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-cache.d.ts","sourceRoot":"","sources":["../../src/graph/extract-cache.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAMzC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB;;;gBAGY;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9D;AAED;;2EAE2E;AAC3E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,SAAI,GAAG,IAAI,CAa9E;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAG9C;AAoBD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,SAAK,GAAG,MAAM,GAAG,IAAI,CAU9E;AAYD,wBAAgB,iBAAiB,IAAI,YAAY,CAEhD;AAED;;;0EAG0E;AAC1E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAS7D;AAED;;;sFAGsF;AACtF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAU9E"}

package/dist/graph/extract-cache.js

@@ -0,0 +1,199 @@
+/**
+ * Per-file memo for Tier-1 extraction — `<outDir>/.cache/extract.json`.
+ *
+ * `extractFile` is pure and file-local (`rel`, `source`, `lang` → `{nodes,
+ * rawEdges}`), which is the whole trick: an unchanged file's parse result can be
+ * replayed from disk instead of re-running tree-sitter. That turns
+ * {@link buildGraph} from "always re-parse the repo" (~4.6ms/file) into "re-parse
+ * only what moved", which is what makes a rebuild cheap enough to run *before*
+ * every query (see `graph/refresh.ts`).
+ *
+ * Everything downstream of extraction (edge resolution, enrichment, the graph
+ * write, the ask sidecar, cards) still runs over the whole merged node set, so no
+ * other invariant changes — an incremental build must produce a byte-identical
+ * `wiring.json` to a cold one.
+ *
+ * Crucially the cached nodes keep `body_text`: `writeGraph` strips it before
+ * serializing, so `wiring.json` can never be the reuse source — the ask sidecar
+ * needs a body for every node, including the ones we didn't re-parse.
+ *
+ * Lives under `.cache/` (gitignored, regenerate-anytime) next to `ask-index.json`
+ * and `summaries.json`. Two things invalidate the whole file: a bump of
+ * {@link CACHE_VERSION} for a change of on-disk shape, and a change to the
+ * extraction code itself, caught by content-hashing it — see
+ * {@link extractorStamp}. Neither asks anyone to remember to bump anything.
+ */
+import { readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { dirname, extname, join } from "node:path";
+import { CACHE_DIR } from "../context/node-file.js";
+import { readJson, writeJsonAtomic } from "../util/state.js";
+/** Bump when the on-disk shape below changes. */
+const CACHE_VERSION = 1;
+const EXTRACT_CACHE_PREFIX = "extract";
+/**
+ * Where this graft's memo lives: `<outDir>/.cache/extract.<stamp>.json`.
+ *
+ * The stamp is in the *filename*, not just inside the file, so two grafts working
+ * on one repo keep separate memos instead of evicting each other. That is the
+ * default install, not an exotic case: `graft init` wires the MCP server as
+ * `npx -y @nanonets/graft` (which resolves the latest published version) while the
+ * Claude Code hooks run the locally installed one. The moment those two versions
+ * differ, a single shared file means the prompt hook and every MCP retrieval take
+ * turns rejecting each other's entries and cold-re-parsing the whole repo — the memo
+ * would never help anyone.
+ *
+ * Null stamp → null path → no memo at all. See {@link extractorStamp}.
+ */
+export function extractCachePath(outDir) {
+    const stamp = extractorStamp();
+    return stamp === null ? null : join(outDir, CACHE_DIR, `${EXTRACT_CACHE_PREFIX}.${stamp}.json`);
+}
+/** Keep `.cache/` from growing a file per version forever: after writing, drop all
+ * but the newest `keep` files sharing a prefix. Best-effort and never fatal — this
+ * is a cache directory, and a failure here costs disk, not correctness. */
+export function pruneSidecars(cacheDir, prefix, keep = 2) {
+    try {
+        const mine = readdirSync(cacheDir)
+            .filter((f) => f.startsWith(`${prefix}.`) && f.endsWith(".json"))
+            .map((f) => {
+            const full = join(cacheDir, f);
+            return { full, mtimeMs: statSync(full).mtimeMs };
+        })
+            .sort((a, b) => b.mtimeMs - a.mtimeMs);
+        for (const f of mine.slice(keep))
+            rmSync(f.full, { force: true });
+    }
+    catch {
+        /* nothing here is load-bearing */
+    }
+}
+/** Computed once per process — this can't change under a running process without
+ * the module graph itself being swapped, and a long-lived MCP server holding the
+ * identity of the code it actually loaded is the correct answer anyway.
+ * `undefined` = not computed yet; `null` = computed, and there is no identity. */
+let memoizedStamp;
+/**
+ * Identity of the code that produces the cached parses. Both sidecars key on it,
+ * so *anything* that can change extraction output has to change this string.
+ *
+ * Content-hashed over every sibling module in this directory, plus the package
+ * version. Two earlier instincts are deliberately rejected:
+ *
+ * - **Not a timestamp.** This was `mtime:size` of `extract.js` alone, which is
+ *   wrong in both directions. Too loose: the parse of `db.count()` depends on
+ *   `bindings.ts` deciding that `db` is a `UserRepo` (that answer is stored *in*
+ *   the cached entry, as an edge's `recvType`), and fixing a binding bug leaves
+ *   `extract.js`'s emitted bytes untouched — so any build that skips rewriting
+ *   unchanged output keeps the old stamp and silently replays pre-fix edges. Too
+ *   tight: a rebuild that rewrites identical content moves the mtime and throws
+ *   away the whole memo for nothing.
+ * - **Not a hand-kept list of modules.** A list is correct exactly until someone
+ *   moves parse logic into a module nobody added to it, and the failure is silent.
+ *
+ * Hashing the directory over-invalidates a little — editing any `graph/` module
+ * costs one cold rebuild — which is no more often than a version bump already
+ * costs, and always in the safe direction. The package version is folded in so a
+ * tree-sitter grammar upgrade (which changes parse output without changing any of
+ * graft's own files) invalidates too.
+ *
+ * Measured at ~0.5ms for 21 files / 556KB, paid once per process.
+ *
+ * **Null when no identity can be established at all**, and that is deliberately not
+ * a string. It used to return `"unknown"` on failure — but `"unknown"` was then
+ * *written into the sidecars as a real identity*, and every later run compared equal
+ * to it, so any environment where stamping fails (a `pkg`/`bun-compile` single-file
+ * build, an asar-style read, a directory that can't be listed) permanently lost the
+ * ability to notice an extractor change. A sentinel that doubles as a valid value
+ * silently disables the whole mechanism. Null forces callers to decide instead, and
+ * {@link extractCachePath} decides not to have a memo.
+ */
+export function extractorStamp() {
+    if (memoizedStamp === undefined)
+        memoizedStamp = computeStamp();
+    return memoizedStamp;
+}
+function computeStamp() {
+    try {
+        const self = fileURLToPath(import.meta.url);
+        // `.js` when running from `dist/`, `.ts` under tsx — take the extension from
+        // our own filename rather than guessing which layout we're in.
+        const dir = dirname(self);
+        const hashed = stampDir(dir, extname(self), packageVersion(dir) ?? "");
+        if (hashed)
+            return hashed;
+        // Couldn't read the modules (bundled into one file, say). The version alone is
+        // a weaker identity — it can't see a local edit — but it still turns over on
+        // every upgrade, which is the case that ships broken parses to users.
+        const v = packageVersion(dir);
+        return v ? `v${v}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Hash every `ext` file in `dir`, plus `version`. Null when the directory holds no
+ * such file. Separated from {@link extractorStamp} so a test can prove the property
+ * that matters: a change to *any* module in the directory moves the stamp, not just
+ * the one the old implementation happened to watch.
+ */
+export function stampDir(dir, ext, version = "") {
+    const files = readdirSync(dir).filter((f) => f.endsWith(ext)).sort();
+    if (!files.length)
+        return null;
+    const h = createHash("sha256");
+    h.update(version);
+    for (const f of files) {
+        h.update(f); // a rename is a change, even at identical content
+        h.update(readFileSync(join(dir, f)));
+    }
+    return h.digest("hex").slice(0, 16);
+}
+/** graft's own version, or null when it can't be read. */
+function packageVersion(graphDir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(graphDir, "..", "..", "package.json"), "utf8"));
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function emptyExtractCache() {
+    return { version: CACHE_VERSION, extractor: extractorStamp() ?? "", files: {} };
+}
+/** The cache for `outDir`, or an empty one when it's absent, unparseable, written by
+ * a different cache version, or when this graft has no identity to key on (then
+ * every build is cold, which is slow but never wrong). The stamp is in the filename,
+ * so the `extractor` field is a second check rather than the only one. */
+export function readExtractCache(outDir) {
+    const path = extractCachePath(outDir);
+    const stamp = extractorStamp();
+    if (path === null || stamp === null)
+        return emptyExtractCache();
+    const c = readJson(path);
+    if (!c || c.version !== CACHE_VERSION || c.extractor !== stamp || typeof c.files !== "object") {
+        return emptyExtractCache();
+    }
+    return { version: c.version, extractor: c.extractor, files: c.files ?? {} };
+}
+/** Best-effort write — a full graph is already on disk by the time this runs, so an
+ * unwritable cache dir must never fail the build (it only costs the next build its
+ * reuse). Returns false when nothing was written, including the deliberate case of
+ * having no extractor identity: a parse we can't attribute must never be replayed. */
+export function writeExtractCache(outDir, cache) {
+    const path = extractCachePath(outDir);
+    if (path === null)
+        return false;
+    try {
+        writeJsonAtomic(path, cache, true);
+        pruneSidecars(join(outDir, CACHE_DIR), EXTRACT_CACHE_PREFIX);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=extract-cache.js.map

package/dist/graph/extract-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-cache.js","sourceRoot":"","sources":["../../src/graph/extract-cache.ts"],"names":[],"mappings":"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"}

package/dist/graph/fingerprint.d.ts

@@ -0,0 +1,70 @@
+import { type ExtractEntry } from "./extract-cache.js";
+/** `[size, mtimeMs, hash]` — positional to keep the file small. */
+type Print = [number, number, string];
+export interface Fingerprint {
+    version: number;
+    /** The extractor that produced the graph these prints describe — the same stamp
+     * `extract.json` carries. Without it the two sidecars can disagree about whether
+     * the graph is current: an extractor change correctly drops every memo entry,
+     * yet the prints still match the tree byte-for-byte, so the probe would report
+     * clean and queries would keep answering from nodes the old extractor built. */
+    extractor: string;
+    files: Record<string, Print>;
+}
+/** What moved since the last build. Empty in all three arrays = nothing to do. */
+export interface Drift {
+    /** Recorded files whose bytes differ now. */
+    changed: string[];
+    /** Source files with no record — new, or never indexed. */
+    added: string[];
+    /** Recorded files that are gone from disk. */
+    removed: string[];
+}
+/** `<outDir>/.cache/fingerprint.<stamp>.json` — keyed by extractor identity for the
+ * same reason the memo is (see {@link extractCachePath}): two grafts on one repo,
+ * typically an `npx` MCP server and a locally installed hook binary, must not keep
+ * invalidating each other's prints and forcing a cold rebuild on every call. */
+export declare function fingerprintPath(outDir: string): string;
+export declare function readFingerprint(outDir: string): Fingerprint | null;
+/** Project the extraction cache's entries into the probe sidecar. Best-effort:
+ * the graph is already on disk when this runs, so a failed write costs the next
+ * probe its fast path and nothing more. */
+export declare function writeFingerprint(outDir: string, entries: Record<string, ExtractEntry>): boolean;
+/** `GRAFT_REFRESH=hash` — never trust a stat, confirm every file by its bytes. */
+export declare function alwaysHash(): boolean;
+/**
+ * May a recorded `(size, mtimeMs, hash)` be trusted for the file `f` as it is on
+ * disk now, without reading it?
+ *
+ * **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
+ * bytes that failed to parse yesterday just fails to parse again.
+ */
+export declare function statUnchanged(rec: {
+    size: number;
+    mtimeMs: number;
+    hash: string;
+}, f: {
+    size: number;
+    mtimeMs: number;
+}): boolean;
+export declare function isClean(d: Drift): boolean;
+export declare function driftCount(d: Drift): number;
+/**
+ * Diff the working tree against the last build's fingerprint. Returns null when
+ * there is no fingerprint to compare against (never built, or built by a version
+ * that didn't write one) — callers should treat that as "unknown", not "clean".
+ *
+ * `GRAFT_REFRESH=hash` skips the stat fast path and hashes every file, for the
+ * rare tooling that rewrites content while preserving size and mtime.
+ */
+export declare function probeDrift(root: string, outDir: string): Drift | null;
+export {};
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/graph/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/graph/fingerprint.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAiC,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AActF,mEAAmE;AACnE,KAAK,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEtC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB;;;;oFAIgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC9B;AAED,kFAAkF;AAClF,MAAM,WAAW,KAAK;IACpB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;gFAGgF;AAChF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAKlE;AAED;;2CAE2C;AAC3C,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,OAAO,CAU/F;AAED,kFAAkF;AAClF,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACpD,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnC,OAAO,CAIT;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,GAAG,OAAO,CAEzC;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAE3C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAqCrE"}

package/dist/graph/fingerprint.js

@@ -0,0 +1,147 @@
+/**
+ * The cheap "has the working tree moved?" probe that gates the pre-query rebuild.
+ *
+ * Every graft retrieval call runs this, so it has to be ~free on the common
+ * unchanged path: a walk + one `stat` per source file, no reads, no parsing.
+ * Measured at ~3ms for 280 files. Only files whose `(size, mtimeMs)` disagree
+ * with the last build's record get read and hashed, which is what keeps a `touch`
+ * or a `git checkout` of identical bytes from triggering a pointless rebuild.
+ *
+ * Note graft has no notion of git here (it never shells out to git, never reads
+ * `.git`): drift is measured against the bytes in the working tree, so an
+ * uncommitted, staged, or committed edit all look the same — which is the point.
+ *
+ * `<outDir>/.cache/fingerprint.json` is a projection of the extraction cache
+ * (`extract-cache.ts`) minus the parse results, written by the same build. Keeping
+ * it separate means the probe reads ~10KB instead of the multi-MB parse cache. The
+ * two can only ever disagree by one sidecar going missing, and both directions
+ * degrade safely: no fingerprint → "unknown, rebuild"; no parse cache → the
+ * rebuild is just cold.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CACHE_DIR } from "../context/node-file.js";
+import { contentHash } from "../util/id.js";
+import { readJson, writeJsonAtomic } from "../util/state.js";
+import { extractorStamp, pruneSidecars } from "./extract-cache.js";
+import { listSourceStats } from "./source-files.js";
+const FINGERPRINT_PREFIX = "fingerprint";
+const FINGERPRINT_VERSION = 1;
+/** The identity this graft's prints are filed under. Unlike the extract memo, a
+ * missing extractor identity is *not* disqualifying here: freshness is a claim about
+ * source bytes, and a build with no memo is merely cold, never wrong. So stamp what
+ * we can and fall back to a shared bucket. */
+function stamp() {
+    return extractorStamp() ?? "nostamp";
+}
+/** `<outDir>/.cache/fingerprint.<stamp>.json` — keyed by extractor identity for the
+ * same reason the memo is (see {@link extractCachePath}): two grafts on one repo,
+ * typically an `npx` MCP server and a locally installed hook binary, must not keep
+ * invalidating each other's prints and forcing a cold rebuild on every call. */
+export function fingerprintPath(outDir) {
+    return join(outDir, CACHE_DIR, `${FINGERPRINT_PREFIX}.${stamp()}.json`);
+}
+export function readFingerprint(outDir) {
+    const f = readJson(fingerprintPath(outDir));
+    if (!f || f.version !== FINGERPRINT_VERSION || typeof f.files !== "object" || !f.files)
+        return null;
+    if (f.extractor !== stamp())
+        return null; // different extractor — re-extract, don't trust these prints
+    return f;
+}
+/** Project the extraction cache's entries into the probe sidecar. Best-effort:
+ * the graph is already on disk when this runs, so a failed write costs the next
+ * probe its fast path and nothing more. */
+export function writeFingerprint(outDir, entries) {
+    const files = {};
+    for (const [rel, e] of Object.entries(entries))
+        files[rel] = [e.size, e.mtimeMs, e.hash];
+    try {
+        writeJsonAtomic(fingerprintPath(outDir), { version: FINGERPRINT_VERSION, extractor: stamp(), files }, true);
+        pruneSidecars(join(outDir, CACHE_DIR), FINGERPRINT_PREFIX);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `GRAFT_REFRESH=hash` — never trust a stat, confirm every file by its bytes. */
+export function alwaysHash() {
+    return process.env.GRAFT_REFRESH === "hash";
+}
+/**
+ * May a recorded `(size, mtimeMs, hash)` be trusted for the file `f` as it is on
+ * disk now, without reading it?
+ *
+ * **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
+ * bytes that failed to parse yesterday just fails to parse again.
+ */
+export function statUnchanged(rec, f) {
+    if (alwaysHash())
+        return false;
+    if (!rec.hash)
+        return false;
+    return rec.size === f.size && rec.mtimeMs === f.mtimeMs;
+}
+export function isClean(d) {
+    return d.changed.length === 0 && d.added.length === 0 && d.removed.length === 0;
+}
+export function driftCount(d) {
+    return d.changed.length + d.added.length + d.removed.length;
+}
+/**
+ * Diff the working tree against the last build's fingerprint. Returns null when
+ * there is no fingerprint to compare against (never built, or built by a version
+ * that didn't write one) — callers should treat that as "unknown", not "clean".
+ *
+ * `GRAFT_REFRESH=hash` skips the stat fast path and hashes every file, for the
+ * rare tooling that rewrites content while preserving size and mtime.
+ */
+export function probeDrift(root, outDir) {
+    const fp = readFingerprint(outDir);
+    if (!fp)
+        return null;
+    const drift = { changed: [], added: [], removed: [] };
+    const seen = new Set();
+    for (const f of listSourceStats(root, outDir)) {
+        seen.add(f.rel);
+        const print = fp.files[f.rel];
+        if (!print) {
+            drift.added.push(f.rel);
+            continue;
+        }
+        const [size, mtimeMs, hash] = print;
+        if (statUnchanged({ size, mtimeMs, hash }, f))
+            continue;
+        // Suspect: confirm by bytes, so a touch (or a checkout that restores the
+        // same content) doesn't cost a rebuild. An entry with an empty hash lands
+        // here every time by design — that's a file the last build couldn't read, and
+        // the only way to learn it's readable again is to try.
+        let now;
+        try {
+            now = contentHash(readFileSync(f.abs, "utf8"));
+        }
+        catch {
+            continue; // unreadable right now — leave it to the next probe
+        }
+        if (now !== hash)
+            drift.changed.push(f.rel);
+    }
+    for (const rel of Object.keys(fp.files)) {
+        if (!seen.has(rel))
+            drift.removed.push(rel);
+    }
+    drift.changed.sort();
+    drift.added.sort();
+    drift.removed.sort();
+    return drift;
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/graph/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../src/graph/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAqB,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,kBAAkB,GAAG,aAAa,CAAC;AACzC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B;;;8CAG8C;AAC9C,SAAS,KAAK;IACZ,OAAO,cAAc,EAAE,IAAI,SAAS,CAAC;AACvC,CAAC;AA0BD;;;gFAGgF;AAChF,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,OAAO,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,kBAAkB,IAAI,KAAK,EAAE,OAAO,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,CAAC,GAAG,QAAQ,CAAc,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;IACzD,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,KAAK,mBAAmB,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACpG,IAAI,CAAC,CAAC,SAAS,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,CAAC,6DAA6D;IACvG,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;2CAE2C;AAC3C,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAqC;IACpF,MAAM,KAAK,GAA0B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACzF,IAAI,CAAC;QACH,eAAe,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QAC5G,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,kBAAkB,CAAC,CAAC;QAC3D,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,MAAM,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAoD,EACpD,CAAoC;IAEpC,IAAI,UAAU,EAAE;QAAE,OAAO,KAAK,CAAC;IAC/B,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,CAAQ;IAC9B,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,CAAQ;IACjC,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;AAC9D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,MAAc;IACrD,MAAM,EAAE,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAErB,MAAM,KAAK,GAAU,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAC7D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,KAAK,MAAM,CAAC,IAAI,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;QAC9C,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAChB,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACxB,SAAS;QACX,CAAC;QACD,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC;QACpC,IAAI,aAAa,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;YAAE,SAAS;QACxD,yEAAyE;QACzE,0EAA0E;QAC1E,8EAA8E;QAC9E,uDAAuD;QACvD,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,oDAAoD;QAChE,CAAC;QACD,IAAI,GAAG,KAAK,IAAI;YAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;QACxC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IACrB,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACnB,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IACrB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/graph/load.d.ts

@@ -15,4 +15,15 @@ export declare function loadGraphCached(outDir: string): GraphV1 | null;
 /** Cached `readAskIndex(outDir)` — same semantics, keyed on the sidecar file.
  * Returns a shared cached reference; callers must not mutate the returned index. */
 export declare function loadAskIndexCached(outDir: string): AskIndex | null;
+/**
+ * Drop the cached graph + sidecar for `outDir`, forcing the next load to re-read.
+ *
+ * The `(mtimeMs, size)` key above is a good invalidator for a build that happened
+ * in *another* process, but not for one this process just performed: the
+ * pre-query auto-refresh (`refresh.ts`) rewrites the graph and then immediately
+ * queries it, and on a filesystem with coarse mtime resolution a same-tick rewrite
+ * of the same size would be served from the stale entry. Callers that rebuild must
+ * therefore invalidate explicitly rather than trust the clock.
+ */
+export declare function invalidateGraphCaches(outDir: string): void;
 //# sourceMappingURL=load.d.ts.map

package/dist/graph/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/graph/load.ts"],"names":[],"mappings":"AA2BA,OAAO,EAA8B,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAW1C;6EAC6E;AAC7E,eAAO,MAAM,YAAY;;;CAA4B,CAAC;AAEtD,+EAA+E;AAC/E,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAmCD;;oFAEoF;AACpF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAK9D;AAED;oFACoF;AACpF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAKlE"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/graph/load.ts"],"names":[],"mappings":"AA2BA,OAAO,EAA8B,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAW1C;6EAC6E;AAC7E,eAAO,MAAM,YAAY;;;CAA4B,CAAC;AAEtD,+EAA+E;AAC/E,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAmCD;;oFAEoF;AACpF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAK9D;AAED;oFACoF;AACpF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAKlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAG1D"}

package/dist/graph/load.js

@@ -80,4 +80,18 @@ export function loadAskIndexCached(outDir) {
         __parseCount.askIndex++;
     });
 }
+/**
+ * Drop the cached graph + sidecar for `outDir`, forcing the next load to re-read.
+ *
+ * The `(mtimeMs, size)` key above is a good invalidator for a build that happened
+ * in *another* process, but not for one this process just performed: the
+ * pre-query auto-refresh (`refresh.ts`) rewrites the graph and then immediately
+ * queries it, and on a filesystem with coarse mtime resolution a same-tick rewrite
+ * of the same size would be served from the stale entry. Callers that rebuild must
+ * therefore invalidate explicitly rather than trust the clock.
+ */
+export function invalidateGraphCaches(outDir) {
+    graphCache.delete(wiringPath(outDir));
+    askIndexCache.delete(askIndexPath(outDir));
+}
 //# sourceMappingURL=load.js.map

package/dist/graph/load.js.map

@@ -1 +1 @@
-{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/graph/load.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAiB,MAAM,sBAAsB,CAAC;AASjF,MAAM,UAAU,GAAG,IAAI,GAAG,EAA+B,CAAC;AAC1D,MAAM,aAAa,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE9D;6EAC6E;AAC7E,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AAEtD,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB;IAChC,YAAY,CAAC,KAAK,GAAG,CAAC,CAAC;IACvB,YAAY,CAAC,QAAQ,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,MAAM,CAAC,IAAY;IAC1B,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CACjB,KAAiC,EACjC,IAAY,EACZ,KAAqB,EACrB,OAAmB;IAEnB,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IACxB,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,sEAAsE;QACtE,sEAAsE;QACtE,+CAA+C;QAC/C,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,MAAM,IAAI,MAAM,CAAC,OAAO,KAAK,EAAE,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC;QACvE,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IACD,OAAO,EAAE,CAAC;IACV,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC;IACtB,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/D,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;oFAEoF;AACpF,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAChC,OAAO,UAAU,CAAC,UAAU,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE;QAC9D,YAAY,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;oFACoF;AACpF,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAClC,OAAO,UAAU,CAAC,aAAa,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE;QACtE,YAAY,CAAC,QAAQ,EAAE,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/graph/load.ts"],"names":[],"mappings":"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"}

package/dist/graph/refresh.d.ts

@@ -0,0 +1,49 @@
+import { type Drift } from "./fingerprint.js";
+export interface RefreshResult {
+    /** True when the graph on disk was rebuilt by this call. */
+    refreshed: boolean;
+    /** What the probe found, when it ran and found something. */
+    drift?: Drift;
+    /** One-line explanation for the agent/user, when there's something worth saying. */
+    note?: string;
+}
+export interface RefreshOptions {
+    contextDir?: string;
+    /** Skip everything (the `--no-refresh` flag). */
+    disabled?: boolean;
+}
+/**
+ * Release the lock if this process is asked to die while holding it. Returns the
+ * un-hook.
+ *
+ * Not hypothetical: the Claude Code prompt hook runs `graft ask` with a timeout, and
+ * `execFileSync` enforces it with SIGTERM. Node's default disposition for SIGTERM is
+ * to exit without unwinding, so the `finally` below never runs and the lock outlives
+ * the process — after which the background sync is blocked and every query waits and
+ * then answers stale until the lock ages out. Ctrl-C on a CLI query is the same story
+ * with SIGINT.
+ *
+ * Adding a listener replaces that default disposition, so re-raise it explicitly
+ * afterwards: remove ourselves, then `process.kill(process.pid, sig)`, so the exit
+ * status still says "terminated by signal" for whoever is waiting on us.
+ */
+export declare function releaseOnSignal(cache: string): () => void;
+/**
+ * Rebuild `root`'s structural graph if the working tree has moved since the last
+ * build. Cheap and side-effect-free when nothing changed, which is the usual case.
+ *
+ * `root` is the repository root (the same value the query itself is given), not
+ * the context dir.
+ */
+export declare function ensureFreshGraph(root: string, opts?: RefreshOptions): Promise<RefreshResult>;
+/**
+ * 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
+ * sequence — a fan-out of concurrent tree-sitter builds would spike CPU on the
+ * very path that's supposed to feel free.
+ */
+export declare function ensureFreshChildren(root: string, children: string[], opts?: RefreshOptions): Promise<RefreshResult>;
+/** 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 declare function refreshNote(r: RefreshResult): string | null;
+//# sourceMappingURL=refresh.d.ts.map

package/dist/graph/refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.d.ts","sourceRoot":"","sources":["../../src/graph/refresh.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAmC,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAU/E,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAcD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI,CAWzD;AAYD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAwDtG;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAAE,EAClB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,aAAa,CAAC,CAsBxB;AAED;wEACwE;AACxE,wBAAgB,WAAW,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAK3D"}