@cstart/coldstart 2.0.0

package/README.md

@@ -0,0 +1,236 @@
+# coldstart
+
+Codebase navigation **and a codebase notebook** for AI agents.
+
+Two layers, one tool:
+
+- **The notebook** (`coldstart kb`) — durable, agent-written notes about how *this* codebase actually works: what a file is for, how a flow spans files, which invariants hold. Captured after real tasks, recalled when a later task matches, and kept honest by the index — every note is anchored to real files, and a note whose evidence drifted is flagged, not served as truth.
+- **Navigation** (`coldstart find` / `coldstart gs`) — a fast static index over file paths, symbol names, exports, and the import/call graph. It answers "which files are relevant to this task?" in milliseconds, with checkable evidence instead of a similarity score.
+
+No embeddings, no model to run, no service to babysit. Agents are already good at reading and reasoning about code; what they waste tokens on is *finding* the right file and *re-deriving* what the last session already figured out. coldstart does those two parts and gets out of the way.
+
+---
+
+## The notebook
+
+A repo-local knowledge base written and read by agents, in `.coldstart/notebook/`:
+
+```bash
+coldstart kb search tile save lifecycle   # plain task words, symbols, or file names
+coldstart kb lookup src/models.py Tile    # everything known at one exact address
+coldstart kb write spec.json              # the write gate (two-phase dedup)
+coldstart kb commit                       # publish notes to git, nothing else rides along
+coldstart kb view                         # open a single-file HTML browser of the notebook
+coldstart kb status / lint / render / init / migrate
+```
+
+**What a note is.** Three shapes: a **file note** (what a file is for — a single summary, or per-symbol facets for hub files), a **flow note** (a cross-file story: ordered steps, invariants), and a **lesson** (a trap, rule, bug-cause, rationale, or confirmed absence). Every note carries **anchors** — concrete file paths and symbols its claims rest on.
+
+**Where notes reach the agent.** Three surfaces, no new habits required:
+
+1. **`Summary:` lines on `find` results** — a past agent's verified overview of a file, right where the file ranks. `[fresh]` means the file is byte-identical to when the summary was verified — the agent can rely on it without re-reading the file.
+2. **Recall at prompt time** (optional hook) — notes whose titles, aliases, or anchors match the incoming prompt are surfaced as a compact title + gist + path block, hard-capped, framed as reference data. Nothing matches → nothing injected.
+3. **`kb search` / `kb lookup`** — a search engine over the notebook for mid-task vocabulary changes, and an exact-address lookup (`path [symbol]`) before editing a file.
+
+**Why it can be trusted.** This is the part that took the design work:
+
+- **Freshness is mechanical, not hoped-for.** Every anchor is stamped with a content hash at write time; the index re-checks stamps as the code changes. A drifted note renders `[evidence changed: <path>]` and the guidance says re-verify — stale knowledge degrades into a labeled hypothesis instead of a confident lie.
+- **The log is the truth.** Notes live in an append-only `.raw` event log (commit it — merges are unions, so parallel branches of notes reconcile without conflicts). The Markdown notes are derived, regenerated mechanically, and gitignored.
+- **Writes go through a gate.** A new note's concept is first searched against existing notes — the agent must explicitly merge into a match (`--into <id>`) or declare it new (`--new`). Duplicates are gated at write time, not cleaned up later.
+- **Concurrent sessions are safe.** Multiple agents can write at once: per-note append-only logs, exclusive creation for new note ids (a same-moment duplicate becomes two visible notes, never a silent merge), lossless merging for shared file notes, and atomic renders (a reader never sees a half-written note).
+- **Corrections happen in-session.** If an agent finds a note wrong while the evidence is in its context, the guidance tells it to fix or retract the note right then — no better-placed future agent exists.
+
+**Setup:** `coldstart kb init` creates the notebook skeleton, sets union-merge for the logs, and (on Claude Code) wires the two optional hooks — capture at session end, recall at prompt time. Other hosts can drive the notebook without the hooks: via the full `kb` CLI, or — for no-shell clients — the `kb_search` / `kb_lookup` / `kb_write` / `kb_status` MCP tools.
+
+**Language-agnostic.** The notebook's freshness machinery is content-hash based, so it works on any codebase — including languages the navigation index doesn't parse. Where the index does parse, notes additionally get symbol-level freshness.
+
+The notebook is young. What's verified today: notes written by agents in real sessions checked out accurate against the code; the stale-note loop closes end-to-end (flag → re-read → correction); capture, recall, and concurrent writes hold up under stress. The bet — stated as a bet — is that a corpus like this compounds over a repo's lifetime: the second time any question comes up, the answer is one `Read` away instead of a re-derivation.
+
+---
+
+## Navigation: the two operations
+
+| | What it answers | Replaces |
+|---|---|---|
+| **`find <terms>`** | "Which files are about this?" — ranks files by how many of your query terms they cover (filenames, path segments, exported symbols, plus a repo-wide name-reference pass). | a flurry of `grep`/`glob` while orienting |
+| **`gs <file>`** | "What is this file?" — top-level symbols with line ranges, who imports it, who calls each symbol, and name-related neighbors. | reading a whole file just to learn its shape and usage |
+
+The intended flow: **`find`** a concept → pick the best path → **`gs`** that file for its shape and who uses it → `Read` only for the implementation inside a method body. Notebook summaries ride along on `find` results, so often the orientation step answers itself.
+
+### `find` — locate the files for a concept
+
+```bash
+coldstart find auth session cookie
+```
+
+Pass **every salient identifier** from your task — the symbol, the domain noun, the rare token you half-remember — not one distilled keyword. `find` ranks files by how many of your terms each one covers and shows, per file, which terms it defines vs. imports and a preview of the lines where they cluster. Often that's enough to answer without opening anything.
+
+Speed-wise, `find` competes with raw grep: its repo-wide reference pass runs on **ripgrep** — yours from PATH, the bundled copy, or an editor's (`COLDSTART_RG` overrides) — with `git grep`/`grep` fallbacks, and the ranked page comes from the pre-built index, not a scan.
+
+**Flags:** `--path GLOB` (scope; comma-combine, `!` excludes) · `--tests` (include test files) · `--via` (show name-reference relations) · `--json`
+
+### `gs` — drill into one file
+
+```bash
+coldstart gs src/auth/service.ts
+```
+
+Returns the file's symbols (with line ranges), its 1-hop internal imports, who imports it, and per-symbol cross-file callers — in one call. This is the answer to **"who uses this file / who calls this symbol"**; it is not a grep.
+
+**Flags:** `--symbol a,b` (deliver named method bodies inline) · `--match TERM` (filter a god-file to one area; `a|b` = OR, `/regex/` = regex) · `--view symbols|imports|importers|callers` · `--json`
+
+### Batch independent lookups in one shell call
+
+```bash
+coldstart find auth; coldstart find 'session cookie'; coldstart gs src/auth/service.ts
+```
+
+---
+
+## Two ways to call it, identical output
+
+coldstart ships as one binary with two front doors:
+
+- **CLI (primary)** — `coldstart find …` / `coldstart gs …` / `coldstart kb …`. For any shell-capable agent (Claude Code, Cursor, terminal use). This is the fast path.
+- **MCP (for no-shell clients)** — the `find` and `gs` tools, plus the notebook as `kb_search` / `kb_lookup` / `kb_write` / `kb_status`, all byte-identical to the CLI. For clients like Claude Desktop that have no shell. (`kb commit` stays CLI/human-only — publishing notes to git is never an agent action.)
+
+Same engine, same index, same results. Pick whichever your agent can reach.
+
+It works best with **Claude Code**, **Codex**, and **Cursor**: all three get platform-specific find/gs hooks and notebook recall/capture hooks from `coldstart init`. Any other client gets `coldstart.md` plus printed wiring directions.
+
+---
+
+## Bring your own semantics
+
+coldstart has no embeddings, no generated summaries, no semantic layer computed at index time — **on purpose. The semantic layer is the agent.** Every consumer is already a frontier model; pre-computing meaning at index time only duplicates that, worse and stale. So the index keeps what's cheap to keep *exact* — paths, symbols, exports, the import/call graph — and returns *why* each file ranked.
+
+The notebook is the same philosophy applied to memory: coldstart still computes no meaning of its own. It stores, anchors, and freshness-checks the meaning **agents** author — written at task time, by the reasoner that had the full context, about the question that actually mattered. The full argument is in **[PHILOSOPHY.md](./PHILOSOPHY.md)**.
+
+---
+
+## Install
+
+Requires Node.js 18+.
+
+```bash
+npm install -g @cstart/coldstart --legacy-peer-deps
+cd your-project
+coldstart init      # navigation: coldstart.md + client wiring + background index warm-up
+coldstart kb init   # notebook: skeleton + capture/recall hooks (optional but recommended)
+```
+
+`init` asks two things — the **experience** (`cli`, recommended, or `mcp`) and the **client** — then writes a single `coldstart.md` at your repo root (the agent-facing guidance) and wires it in. Pass `--experience` / `--client` to skip the prompts. The client is never auto-detected; you always pick it.
+
+- **Claude Code** → ensures `CLAUDE.md` imports it via `@coldstart.md`, and registers the find/gs search hooks in `.claude/settings.json` (a PostToolUse nudge + a PreToolUse find-dedup guard — merged into any existing settings, never overwriting them). The `mcp` experience also writes `.mcp.json`.
+- **Codex** → adds a coldstart section to `AGENTS.md` and registers Codex-specific navigation plus notebook hooks in `.codex/hooks.json`. The capture hook understands Codex rollout and subagent transcripts. The `mcp` experience also writes `[mcp_servers.coldstart]` into `.codex/config.toml`.
+- **Cursor** → writes `.cursor/rules/coldstart.mdc` (an always-applied rule referencing `@coldstart.md`) and registers Cursor-specific navigation plus notebook hooks in `.cursor/hooks.json` (a `preToolUse` find-dedup guard, a `postToolUse` nudge, `beforeSubmitPrompt` recall, and `stop`/`subagentStop` capture — merged into any existing hooks). The capture hook parses Cursor's own conversation transcript. The `mcp` experience also writes `.cursor/mcp.json`.
+- **Other** → writes `coldstart.md` only, and prints the wiring directions (plus the MCP server entry for the `mcp` experience).
+
+`init` then warms the index in the background, so your first lookup is instant. Re-running either init is safe — they never duplicate entries.
+
+> **Why `--legacy-peer-deps`?** The tree-sitter grammar packages under-declare their peer-dep ranges (some say `^0.21.x`, others `^0.22.x`). Without the flag npm's strict resolver enters a long retry loop on a cold cache and can appear to hang. The flag tells npm to use our tested versions as-is. We can't set it from inside the package — npm reads install config only from your environment.
+
+### Upgrading
+
+```bash
+npm install -g @cstart/coldstart@latest --legacy-peer-deps
+coldstart init   # re-run in each project to refresh coldstart.md
+```
+
+A version stamp in the keeper's lockfile makes the old background keeper shut down on the next lookup; a fresh one spawns from the new binary. No manual restart needed.
+
+> **Migrating from `coldstart-mcp`:** the package was renamed `coldstart-mcp` → **`coldstart`** at 2.0.0 (the CLI is now the primary surface). `coldstart-mcp` is deprecated but still installs; switch with `npm uninstall -g coldstart-mcp && npm install -g coldstart --legacy-peer-deps && coldstart init`. The `coldstart-mcp` binary name is kept as an alias, so existing MCP configs keep working.
+
+---
+
+## How the index stays fresh
+
+coldstart is **one keeper, thin readers**:
+
+```
+            ┌─────────────────────────────────────────────┐
+            │  keeper  (coldstart --daemon)                │
+            │  watches repo → patch/rebuild → save cache   │   ← keeps the cache fresh, serves nothing
+            └───────────────────────┬─────────────────────┘
+                                    │ on-disk cache
+        ┌───────────────────────────┼───────────────────────────┐
+        │                           │                           │
+  coldstart find            coldstart gs                  MCP server
+  (reads cache, prints)     (reads cache, prints)   (reads cache, stdio to client)
+```
+
+- A single **keeper** process per repo watches the filesystem and keeps the on-disk cache current. It does **not** answer queries.
+- The CLI readers (`find`/`gs`) and the MCP server are **stateless readers** over that cache. The first reader for a repo lazily spawns the keeper, so even uncommitted edits stay live.
+- **Readers never build the index.** On a cache miss they wait for the keeper's build (progress to stderr) instead of silently kicking off a multi-minute build inline — or three of them concurrently.
+- No HTTP, no ports, no bridge. The keeper logs to `~/.coldstart/daemon/<root>.log` and exits when its lockfile is removed.
+
+**There is no cache TTL.** The index is never discarded for being old — it's kept *correct* instead:
+
+- **While the keeper runs:** edits are debounced (400 ms), then **patched incrementally** (~2–5 ms/file, up to 30 files or 20% of the repo, whichever is larger) or trigger a **background full rebuild** above that (served from the last good index until the swap). The cache re-saves ~5 s after edits settle, in **atomic generations** — a reader can never load a half-written mix of old and new.
+- **When the keeper starts:** it **reconciles** — stat-checks every indexed file against its stored fingerprint (~150 ms even at 16k files) plus a git diff against the indexed HEAD — and patches exactly what changed while nothing was watching. A branch switch that used to force a 96-second rebuild on a 16k-file repo is now a ~3-second patch.
+- **As a backstop:** every patch is lint-checked against index invariants (a violation triggers an automatic rebuild and lands in a repair log that `status` shows), and a rotating fingerprint audit after each save catches watcher-missed events.
+
+The keeper also stamps the notebook's anchor freshness (a small sidecar, derived single-flight) — the notebook never loads the code index to answer a query.
+
+### Lifecycle commands
+
+```bash
+coldstart status              # keepers on this machine: alive? fresh? last patch/rebuild/save? repairs?
+coldstart restart             # kill the current repo's keeper (respawns on next lookup)
+coldstart restart --root DIR  # kill a specific repo's keeper from anywhere
+coldstart restart --all       # kill every keeper
+coldstart index               # build + save the cache once, up front (single-writer prep)
+```
+
+`restart` is the right move whenever anything feels stale — a fresh keeper reconciles on start, so it comes back *correct*, not just alive. `status` answers "is my index fresh, and why?": liveness, cache age, the keeper's last reconcile/patch/rebuild/save stamps, and the tail of the repair log — no network probe.
+
+---
+
+## Supported languages
+
+Navigation index: TypeScript, JavaScript, JSX/TSX, Vue, Svelte, Astro, AngularJS 1.x, Java, Kotlin, Ruby (Rails-aware: `has_many`/`belongs_to` associations, `routes.rb` resources, controller↔view edges), Python (Django convention edges), Go, Rust, C#, PHP (Laravel convention edges), C++, Groovy (incl. Gradle DSL), GraphQL, YAML, TOML, XML, and `.env` files.
+
+**Not indexed:** Swift, Dart — no extension mapping; these files are not walked or parsed.
+
+The **notebook works regardless** — its freshness stamps are content-hash based, so notes on a Swift repo are as trustworthy as notes on a TypeScript one (they just lack symbol-level freshness detail).
+
+---
+
+## When *not* to reach for it
+
+- A literal string / phrase / regex inside file bodies → **Grep**.
+- Reading an implementation → **Read**, after `gs` gives you the shape.
+- `find` says *"no indexed file contains any of […]"* → those identifiers aren't in the repo. Don't grep spelling variants.
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+
+# run a query from your build:
+node dist/index.js find auth --root .
+
+# run the MCP server in a single process (no background keeper) for debugging:
+node dist/index.js --root . --no-daemon
+```
+
+See [PHILOSOPHY.md](./PHILOSOPHY.md) for why coldstart computes no semantics of its own, [ARCHITECTURE.md](./ARCHITECTURE.md) for the index pipeline, process model, and notebook internals, and [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for recovery procedures.
+
+---
+
+## Limitations
+
+1. It's a routing layer plus an agent-written notebook — no semantic analysis or generated code summaries. This is deliberate: the consuming agent is the semantic layer (see [PHILOSOPHY.md](./PHILOSOPHY.md)).
+2. `gs` callers are one-hop and file-scoped. Member-expression calls (`this.method()`, `api.method()`) aren't cross-file resolved; named function/constant calls are. Chase further hops by calling `gs` on the caller files.
+3. Dynamic/computed imports (`import(variable)`) and runtime-DSL references (polymorphic associations, gem/reflection-backed models) stay unresolved.
+4. Hidden directories and files over 1 MB are skipped by the index.
+5. The keeper is per-repo and per-machine — no sharing across projects or hosts. The notebook *does* travel: its `.raw` logs are committed and union-merge across branches and machines.
+6. Notebook quality is bounded by what writing agents actually read — notes are accurate about what they state, but a note is not a proof of completeness.
+
+## License
+
+MIT

package/dist/cache/disk-cache.d.ts

@@ -0,0 +1,14 @@
+import type { CodebaseIndex } from '../types.js';
+export type LoadProfile = 'find' | 'gs' | 'full';
+export declare function getCacheDir(rootDir: string, baseCacheDir?: string): string;
+/**
+ * Refresh ONLY the gitHead/timestamp in meta.json — for the reconcile-fresh
+ * case where HEAD moved but every indexed file is unchanged (e.g. committing
+ * files the keeper already patched). Without this the stored head lags
+ * forever and every reader pays the full HEAD-drift wait on every query.
+ * The mtime bump doubles as the "cache advanced" signal those readers poll.
+ */
+export declare function updateCachedGitHead(rootDir: string, gitHead: string, baseCacheDir?: string): Promise<void>;
+export declare function saveCachedIndex(index: CodebaseIndex, baseCacheDir?: string): Promise<void>;
+export declare function loadCachedIndex(rootDir: string, baseCacheDir?: string, profile?: LoadProfile): Promise<CodebaseIndex | null>;
+//# sourceMappingURL=disk-cache.d.ts.map

package/dist/cache/disk-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk-cache.d.ts","sourceRoot":"","sources":["../../src/cache/disk-cache.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EACV,aAAa,EAEd,MAAM,aAAa,CAAC;AASrB,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;AASjD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAG1E;AA4DD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,aAAa,EACpB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAyJf;AAMD,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,GAAE,WAAoB,GAC5B,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CA4H/B"}

package/dist/cache/disk-cache.js

@@ -0,0 +1,371 @@
+/**
+ * On-disk index cache, format v18 — consumer-scoped gzipped segments.
+ *
+ * The old format stored one giant JSON blob (132MB on a 16k-file repo) that
+ * every reader parsed in full (~900ms) even though `find` needs a fraction of
+ * it. v18 splits the index by CONSUMER and interns every file path once:
+ *
+ *   meta.json          version + gitHead + counts. Written LAST (commit marker).
+ *   table.json.gz      fileTable: relativePaths[]. Everything else refers to a
+ *                      file by its integer index in this table ("fileRef").
+ *   core-<n>.json.gz   find+gs: slim per-file tuples (language, line counts,
+ *                      import counts, flags, slim symbols WITHOUT calls[],
+ *                      contentTokens), chunked 5000 files per segment.
+ *   graph.json.gz      find+gs: file edges, out/in adjacency, contentToken
+ *                      postings — all int-ref encoded, SERIALIZED (no longer
+ *                      rebuilt on every load).
+ *   callgraph.json.gz  gs only: symbolEdges, int-ref encoded.
+ *   build-<n>.json.gz  keeper only: domainMap, exports, raw imports, hash,
+ *                      per-symbol calls[], resolver fields — the data needed
+ *                      to PATCH the index, never to query it.
+ *   buildmeta.json.gz  keeper only: tokenDocFreq.
+ *   fingerprints.json  per-file [mtimeMs, size] aligned to fileTable — the
+ *                      stat-walk reconcile backstop.
+ *
+ * Load profiles: 'find' (table+core+graph) · 'gs' (+callgraph) · 'full'
+ * (+build+fingerprints). A partial load fills the untouched fields with
+ * empties and stamps index.profile; saveCachedIndex refuses to persist a
+ * partial index so a reader can never clobber the keeper's full cache.
+ *
+ * No TTL: cache validity = format version + git HEAD (checked by callers) +
+ * the keeper's live watcher. Time never invalidates a correct index.
+ */
+import { readFile, writeFile, mkdir, readdir, rm, rename } from 'node:fs/promises';
+import { join, resolve, basename, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { gzip as gzipCb, gunzip as gunzipCb } from 'node:zlib';
+import { promisify } from 'node:util';
+import { CACHE_VERSION } from '../constants.js';
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+const DEFAULT_CACHE_DIR = join(homedir(), '.coldstart', 'indexes');
+const FILES_CHUNK_SIZE = 5000;
+/** Compute a stable cache key for a root directory path. */
+function cacheKey(rootDir) {
+    const abs = resolve(rootDir);
+    const hash = createHash('sha256').update(abs).digest('hex').slice(0, 16);
+    return `${basename(abs)}-${hash}`;
+}
+export function getCacheDir(rootDir, baseCacheDir) {
+    const base = baseCacheDir ?? DEFAULT_CACHE_DIR;
+    return join(base, cacheKey(rootDir));
+}
+const SYMBOL_EDGE_TYPES = ['calls', 'extends', 'implements', 'exports'];
+const RESOLVER_FIELDS = [
+    'constantReferences', 'partialDeclarations', 'eloquentRelations',
+    'containerResolutions', 'djangoConventionRefs', 'submoduleImportCandidates',
+];
+// ---------------------------------------------------------------------------
+// Save
+// ---------------------------------------------------------------------------
+async function writeGz(path, data) {
+    const buf = await gzip(Buffer.from(JSON.stringify(data)));
+    // temp + rename: a reader never sees a half-written segment
+    const tmp = path + '.tmp';
+    await writeFile(tmp, buf);
+    await rename(tmp, path);
+}
+async function readGz(path) {
+    const buf = await gunzip(await readFile(path));
+    return JSON.parse(buf.toString('utf8'));
+}
+/** meta.json is the commit marker — its write must be atomic too. */
+async function writeMetaAtomic(dir, meta) {
+    const path = join(dir, 'meta.json');
+    const tmp = path + '.tmp-meta';
+    await writeFile(tmp, JSON.stringify(meta, null, 2));
+    await rename(tmp, path);
+}
+/**
+ * Refresh ONLY the gitHead/timestamp in meta.json — for the reconcile-fresh
+ * case where HEAD moved but every indexed file is unchanged (e.g. committing
+ * files the keeper already patched). Without this the stored head lags
+ * forever and every reader pays the full HEAD-drift wait on every query.
+ * The mtime bump doubles as the "cache advanced" signal those readers poll.
+ */
+export async function updateCachedGitHead(rootDir, gitHead, baseCacheDir) {
+    const dir = getCacheDir(rootDir, baseCacheDir);
+    const meta = JSON.parse(await readFile(join(dir, 'meta.json'), 'utf-8'));
+    meta.gitHead = gitHead;
+    meta.timestamp = Date.now();
+    await writeMetaAtomic(dir, meta);
+}
+export async function saveCachedIndex(index, baseCacheDir) {
+    if (index.profile && index.profile !== 'full') {
+        throw new Error(`refusing to save a partial index (profile=${index.profile}) — it would clobber the keeper's full cache`);
+    }
+    const dir = getCacheDir(index.rootDir, baseCacheDir);
+    await mkdir(dir, { recursive: true });
+    // Generations: segments are NEVER overwritten in place. Each save writes a
+    // fresh `g<N>-` set, commits it by writing meta.json (which names the gen)
+    // LAST, then sweeps older generations — keeping the previous one so a
+    // reader that grabbed the old meta moments ago still finds every segment
+    // it needs. Without this, a save racing a load could serve a mixed-
+    // generation index (new file table + old chunk = silently misaligned data).
+    let gen = 1;
+    try {
+        const old = JSON.parse(await readFile(join(dir, 'meta.json'), 'utf-8'));
+        if (typeof old.gen === 'number' && Number.isFinite(old.gen))
+            gen = old.gen + 1;
+    }
+    catch { /* no prior cache */ }
+    const seg = (name) => join(dir, `g${gen}-${name}`);
+    // --- file table + per-file refs -----------------------------------------
+    const paths = [];
+    const refOf = new Map();
+    for (const id of index.files.keys()) {
+        refOf.set(id, paths.length);
+        paths.push(id);
+    }
+    // symbol name → index per file, for symbolEdge encoding
+    const symIdx = new Map();
+    for (const [id, f] of index.files) {
+        const m = new Map();
+        f.symbols.forEach((s, i) => { if (!m.has(s.name))
+            m.set(s.name, i); });
+        symIdx.set(id, m);
+    }
+    const encodeSymRef = (ref) => {
+        const fileRef = refOf.get(ref);
+        if (fileRef !== undefined)
+            return fileRef;
+        const hash = ref.indexOf('#');
+        if (hash > 0) {
+            const fr = refOf.get(ref.slice(0, hash));
+            const si = fr !== undefined ? symIdx.get(ref.slice(0, hash)).get(ref.slice(hash + 1)) : undefined;
+            if (fr !== undefined && si !== undefined)
+                return [fr, si];
+        }
+        return ref; // unresolvable — keep verbatim
+    };
+    // --- core + build chunks (aligned to the file table) ---------------------
+    const writes = [];
+    const fps = [];
+    for (let start = 0; start < paths.length; start += FILES_CHUNK_SIZE) {
+        const core = [];
+        const build = [];
+        for (let i = start; i < Math.min(start + FILES_CHUNK_SIZE, paths.length); i++) {
+            const f = index.files.get(paths[i]);
+            const flags = (f.isBarrel ? 1 : 0) | (f.isTestFile ? 2 : 0) | (f.hasDefaultExport ? 4 : 0);
+            core.push([
+                f.language, f.lineCount, f.tokenEstimate, f.importedByCount, f.transitiveImportedByCount,
+                flags,
+                f.symbols.map((s) => [
+                    s.name, s.kind, s.startLine, s.endLine, s.isExported ? 1 : 0,
+                    s.extendsName ?? 0, s.implementsNames.length ? s.implementsNames : 0,
+                ]),
+                f.contentTokens ?? 0,
+            ]);
+            const extras = {};
+            for (const k of RESOLVER_FIELDS)
+                if (f[k] !== undefined)
+                    extras[k] = f[k];
+            build.push({
+                d: f.domainMap, e: f.exports, i: f.imports, h: f.hash,
+                s: f.symbols.map((s) => [
+                    s.calls.map((c) => [c.name, c.line]),
+                    s.annotations?.length ? s.annotations : 0,
+                ]),
+                ...(f.reexportRatio !== undefined ? { rr: f.reexportRatio } : {}),
+                ...(f.packageName !== undefined ? { pn: f.packageName } : {}),
+                ...(Object.keys(extras).length ? { x: extras } : {}),
+            });
+        }
+        const n = start / FILES_CHUNK_SIZE;
+        writes.push(writeGz(seg(`core-${n}.json.gz`), core));
+        writes.push(writeGz(seg(`build-${n}.json.gz`), build));
+    }
+    for (const id of paths) {
+        const f = index.files.get(id);
+        fps.push([f.mtimeMs ?? 0, f.sizeBytes ?? 0]);
+    }
+    // --- graph (find+gs) ------------------------------------------------------
+    const adj = (m) => {
+        const out = paths.map(() => []);
+        for (const [k, list] of m) {
+            const r = refOf.get(k);
+            if (r === undefined)
+                continue;
+            out[r] = list.map((t) => refOf.get(t)).filter((x) => x !== undefined);
+        }
+        return out;
+    };
+    const postings = {};
+    for (const [tok, ids] of index.contentTokenPostings) {
+        postings[tok] = ids.map((t) => refOf.get(t)).filter((x) => x !== undefined);
+    }
+    writes.push(writeGz(seg('graph.json.gz'), {
+        edges: index.edges
+            .filter((e) => refOf.has(e.from) && refOf.has(e.to))
+            .map((e) => [refOf.get(e.from), refOf.get(e.to), e.type, e.specifier]),
+        out: adj(index.outEdges),
+        in: adj(index.inEdges),
+        postings,
+    }));
+    // --- callgraph (gs) -------------------------------------------------------
+    writes.push(writeGz(seg('callgraph.json.gz'), {
+        symbolEdges: index.symbolEdges.map((e) => [
+            encodeSymRef(e.from), encodeSymRef(e.to),
+            SYMBOL_EDGE_TYPES.indexOf(e.type), e.line ?? 0,
+        ]),
+    }));
+    // --- keeper-only leftovers + table + fingerprints -------------------------
+    writes.push(writeGz(seg('buildmeta.json.gz'), {
+        tokenDocFreq: Object.fromEntries(index.tokenDocFreq),
+    }));
+    writes.push(writeGz(seg('table.json.gz'), { paths }));
+    writes.push(writeFile(seg('fingerprints.json'), JSON.stringify(fps)));
+    await Promise.all(writes);
+    // meta last = commit marker
+    const meta = {
+        rootDir: index.rootDir,
+        gitHead: index.gitHead,
+        fileCount: index.files.size,
+        timestamp: index.indexedAt,
+        version: CACHE_VERSION,
+        gen,
+    };
+    await writeMetaAtomic(dir, meta);
+    // Sweep AFTER the commit: drop generations older than the previous one,
+    // plus any pre-generation / legacy-format files. keeper-state.json,
+    // repair.jsonl, kb-notes.json and meta.json never match.
+    try {
+        const existing = await readdir(dir);
+        const toDelete = existing.filter((f) => {
+            const m = /^g(\d+)-/.exec(f);
+            if (m)
+                return Number(m[1]) <= gen - 2;
+            return f === 'index.json' || f === 'graph.json' || f.startsWith('files-')
+                || f.endsWith('.gz') || f.endsWith('.gz.tmp') || f.endsWith('.tmp-meta')
+                || f === 'fingerprints.json';
+        });
+        await Promise.all(toDelete.map((f) => rm(join(dir, f), { force: true })));
+    }
+    catch { /* ignore */ }
+}
+// ---------------------------------------------------------------------------
+// Load
+// ---------------------------------------------------------------------------
+export async function loadCachedIndex(rootDir, baseCacheDir, profile = 'full') {
+    const dir = getCacheDir(rootDir, baseCacheDir);
+    let meta;
+    try {
+        meta = JSON.parse(await readFile(join(dir, 'meta.json'), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (meta.version !== CACHE_VERSION)
+        return null;
+    // gen-prefixed segment names (absent on pre-generation v18 caches).
+    const seg = (name) => join(dir, typeof meta.gen === 'number' ? `g${meta.gen}-${name}` : name);
+    try {
+        const { paths } = await readGz(seg('table.json.gz'));
+        const chunkCount = Math.ceil(paths.length / FILES_CHUNK_SIZE);
+        // Kick off every segment read for this profile concurrently.
+        const coreP = Promise.all(Array.from({ length: chunkCount }, (_v, n) => readGz(seg(`core-${n}.json.gz`))));
+        const graphP = readGz(seg('graph.json.gz'));
+        const callgraphP = profile !== 'find'
+            ? readGz(seg('callgraph.json.gz'))
+            : null;
+        const buildP = profile === 'full'
+            ? Promise.all(Array.from({ length: chunkCount }, (_v, n) => readGz(seg(`build-${n}.json.gz`))))
+            : null;
+        const buildMetaP = profile === 'full'
+            ? readGz(seg('buildmeta.json.gz'))
+            : null;
+        const fpP = profile === 'full'
+            ? readFile(seg('fingerprints.json'), 'utf-8').then((raw) => JSON.parse(raw))
+            : null;
+        const [coreChunks, graph, callgraph, buildChunks, buildMeta, fps] = await Promise.all([
+            coreP, graphP, callgraphP, buildP, buildMetaP, fpP,
+        ]);
+        const rootAbs = meta.rootDir;
+        const files = new Map();
+        for (let n = 0; n < chunkCount; n++) {
+            const core = coreChunks[n];
+            const build = buildChunks?.[n];
+            for (let j = 0; j < core.length; j++) {
+                const idx = n * FILES_CHUNK_SIZE + j;
+                const rel = paths[idx];
+                const [language, lineCount, tokenEstimate, importedByCount, transitiveImportedByCount, flags, slimSymbols, contentTokens] = core[j];
+                const b = build?.[j];
+                const symbols = slimSymbols.map((s, si) => ({
+                    id: `${rel}#${s[0]}`,
+                    name: s[0], kind: s[1], startLine: s[2], endLine: s[3],
+                    isExported: s[4] === 1,
+                    calls: b ? b.s[si][0].map(([name, line]) => ({ name, line })) : [],
+                    ...(s[5] !== 0 ? { extendsName: s[5] } : {}),
+                    implementsNames: s[6] === 0 ? [] : s[6],
+                    ...(b && b.s[si][1] !== 0 ? { annotations: b.s[si][1] } : {}),
+                }));
+                const file = {
+                    id: rel,
+                    path: rootAbs + sep + rel,
+                    relativePath: rel,
+                    language,
+                    domainMap: b ? b.d : {},
+                    exports: b ? b.e : [],
+                    hasDefaultExport: (flags & 4) !== 0,
+                    imports: b ? b.i : [],
+                    hash: b ? b.h : '',
+                    lineCount, tokenEstimate, importedByCount, transitiveImportedByCount,
+                    isBarrel: (flags & 1) !== 0,
+                    isTestFile: (flags & 2) !== 0,
+                    symbols,
+                    ...(b?.rr !== undefined ? { reexportRatio: b.rr } : {}),
+                    ...(b?.pn !== undefined ? { packageName: b.pn } : {}),
+                    ...(contentTokens !== 0 ? { contentTokens } : {}),
+                    ...(fps?.[idx]?.[0] ? { mtimeMs: fps[idx][0], sizeBytes: fps[idx][1] } : {}),
+                };
+                if (b?.x)
+                    Object.assign(file, b.x);
+                files.set(rel, file);
+            }
+        }
+        const outEdges = new Map();
+        const inEdges = new Map();
+        graph.out.forEach((list, r) => { if (list.length)
+            outEdges.set(paths[r], list.map((t) => paths[t])); });
+        graph.in.forEach((list, r) => { if (list.length)
+            inEdges.set(paths[r], list.map((t) => paths[t])); });
+        const edges = graph.edges.map(([f, t, type, specifier]) => ({
+            from: paths[f], to: paths[t], type, specifier,
+        }));
+        const contentTokenPostings = new Map();
+        for (const [tok, refs] of Object.entries(graph.postings)) {
+            contentTokenPostings.set(tok, refs.map((r) => paths[r]));
+        }
+        const decodeSymRef = (ref) => {
+            if (typeof ref === 'number')
+                return paths[ref];
+            if (typeof ref === 'string')
+                return ref;
+            const [fr, si] = ref;
+            return `${paths[fr]}#${files.get(paths[fr]).symbols[si].name}`;
+        };
+        const symbolEdges = (callgraph?.symbolEdges ?? []).map(([f, t, ty, line]) => ({
+            from: decodeSymRef(f), to: decodeSymRef(t),
+            type: SYMBOL_EDGE_TYPES[ty],
+            ...(line !== 0 ? { line } : {}),
+        }));
+        return {
+            rootDir: meta.rootDir,
+            indexedAt: meta.timestamp,
+            gitHead: meta.gitHead,
+            files,
+            edges,
+            symbolEdges,
+            outEdges,
+            inEdges,
+            tokenDocFreq: new Map(Object.entries(buildMeta?.tokenDocFreq ?? {})),
+            contentTokenPostings,
+            ...(profile !== 'full' ? { profile } : {}),
+        };
+    }
+    catch {
+        return null; // missing/corrupt segment — caller rebuilds
+    }
+}
+//# sourceMappingURL=disk-cache.js.map