@spikedpunch/mast 0.1.0

package/dist/mcp/server.js

@@ -0,0 +1,177 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { openDatabase } from '../graph/db.js';
+import { SqliteChunkStore } from '../store/sqliteChunkStore.js';
+import { runIndex, loadIndexMeta } from '../indexer/index.js';
+import { startWatchMode } from '../indexer/watcher.js';
+import { bootstrapState } from './startup.js';
+import { registerAllTools } from './register-tools.js';
+// ---------------------------------------------------------------------------
+// M6 Part A (eval/GITNEXUS_COMPARISON.md §13.8 item 4): refuse to serve only
+// where nothing can EVER fill the index — see assertServableIndex below.
+// ---------------------------------------------------------------------------
+/**
+ * Thrown by {@link assertServableIndex} when `mast serve --no-startup-reindex`
+ * targets a state directory that has never completed an index run. Extends
+ * `Error` per project convention (never throw a plain string/object) —
+ * mirrors `cli/query.ts`'s `QueryError` precedent for a typed, CLI-surfaced
+ * failure mode.
+ */
+export class NeverIndexedError extends Error {
+}
+/**
+ * True when `config.resolved_state_dir` has never completed an index run:
+ * either `graph.db` itself is absent (nothing has ever opened the database),
+ * or `index.json` reports zero chunks AND a null/absent `last_indexed` (the
+ * database was opened — e.g. by a prior aborted run — but no index write
+ * ever landed). Read via `loadIndexMeta` (`indexer/index.ts`), the same
+ * unvalidated `JSON.parse` reader every other `index.json` consumer uses.
+ *
+ * Deliberately NOT "chunk_count === 0" alone — a state dir indexed over a
+ * genuinely empty file set (no matching files) still writes a live
+ * `graph.db` and `index.json` with `last_indexed` set. That is Part B's
+ * territory
+ * (`mcp/tools/_helpers.ts`'s `isIndexEmpty`), not Part A's: the index CAN be
+ * queried honestly (with `index_empty: true`), it just has nothing in it.
+ * This function only fires for the state that will NEVER produce anything
+ * different, because nothing (that this server process controls) is ever
+ * going to index it.
+ *
+ * MUST be called before `openDatabase` runs (`serve()`'s Step 2, below):
+ * `openDatabase` creates `graph.db` with an empty schema as a side effect of
+ * opening a missing file (`graph/db.ts`), which would flip this check to
+ * "not absent" a moment later — the same ordering hazard `cli/query.ts`'s
+ * `runQuery` already documents for its own graph.db existence check.
+ */
+function isNeverIndexed(config) {
+    const graphDbPath = join(config.resolved_state_dir, 'graph.db');
+    if (!existsSync(graphDbPath))
+        return true;
+    const meta = loadIndexMeta(config.resolved_state_dir);
+    return (meta?.chunk_count ?? 0) === 0 && (meta?.last_indexed ?? null) === null;
+}
+/**
+ * Refuse to start serving when nothing can ever fill the index (M6 Part A).
+ *
+ * A blanket "refuse whenever the state dir is empty" is wrong: §7.4's
+ * startup ladder LEGITIMATELY serves from an empty state dir while Step 4's
+ * background reindex fills it in — that window is the designed SDD
+ * container flow and must keep working untouched. This function is a no-op
+ * whenever the startup reindex is enabled (the default) — see the early
+ * return below — so it can never gate or delay that path.
+ *
+ * The refusal fires only for the one combination where an empty index can
+ * NEVER be filled by this server process: `--no-startup-reindex` disables
+ * the one mechanism that would have filled it, permanently pinning every
+ * query at `{"results":[]}` — indistinguishable from "symbol doesn't exist",
+ * the exact ambiguity M6 (`eval/GITNEXUS_COMPARISON.md` §13.8 item 4) names.
+ * Part B (`mcp/tools/_helpers.ts`'s `isIndexEmpty`, consumed by every read
+ * tool) covers the legitimate empty window this function deliberately
+ * leaves alone.
+ *
+ * @throws NeverIndexedError naming the state dir and suggesting `mast init`
+ * / `mast index`, or dropping `--no-startup-reindex`.
+ */
+export function assertServableIndex(config, options) {
+    if (options.noStartupReindex !== true)
+        return;
+    if (!isNeverIndexed(config))
+        return;
+    throw new NeverIndexedError(`mast serve: state directory "${config.resolved_state_dir}" has never been indexed, and ` +
+        '--no-startup-reindex disables the startup reindex that would normally fill it — every ' +
+        'query would return {"results":[]} forever, indistinguishable from "symbol doesn\'t exist". ' +
+        'Run `mast init` or `mast index` against this state directory first, or drop --no-startup-reindex.');
+}
+/**
+ * Run the MAST MCP server.
+ *
+ * Implements the startup ladder from §7.4 (Step 4's embed half was excised in
+ * Stage 7.1, IMPLEMENTATION_PLAN.md "Stage 7: Vector-store deletion"):
+ *   Step 1 — bootstrap state directory (< 1s)
+ *   Step 2 — schema version check + open DB (< 2s)
+ *   Step 3 — open MCP transport, register tools, accept connections (< 1s)
+ *   Step 4 — background incremental reindex (async)
+ */
+export async function serve(options) {
+    const { config } = options;
+    // ── Steps 1–2: bootstrap state dir + schema-version guard ─────────────────
+    // On a schema-version change this wipes all derived state (graph.db,
+    // file_manifest.json, plus any orphaned lance/embed_cache/ left behind by a
+    // pre-Stage-7 state dir) before any of it is opened. See §7.4.
+    const { needsFullReindex } = await bootstrapState(config);
+    // M6 Part A: refuse before openDatabase (which would create graph.db as a
+    // side effect and mask the never-indexed state this check exists to catch)
+    // — see assertServableIndex's docstring above for the full ordering hazard.
+    assertServableIndex(config, { noStartupReindex: options.noStartupReindex });
+    const db = openDatabase(config.resolved_state_dir);
+    // M1 (eval/GITNEXUS_COMPARISON.md §15.1): chunks live in graph.db's
+    // `chunks` table — `SqliteChunkStore` wraps the same `db` connection every
+    // tool below already uses.
+    const chunkStore = new SqliteChunkStore(db);
+    // ── Step 3: open MCP transport and register tools ─────────────────────────
+    const ctx = {
+        db,
+        chunkStore,
+        config,
+        sessionId: randomUUID(),
+    };
+    const server = new McpServer({ name: 'mast', version: '0.1.0' });
+    registerAllTools(server, ctx);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // ── Optional --watch mode (§11.4) ──────────────────────────────────────────
+    // Started after the transport so a watcher failure can never block serving.
+    // Each batch is one incremental Phase 1 (same structure.lock path as
+    // mast_reindex). JIT staleness handling (§9.0) already guarantees read
+    // correctness; watch mode only keeps the FTS/graph index fresh between reads.
+    const startWatchIfRequested = () => {
+        if (options.watch !== true)
+            return;
+        let watchHandle = null;
+        try {
+            watchHandle = startWatchMode({
+                config,
+                runBatch: async (paths) => {
+                    process.stderr.write(`[mast] watch: reindexing after ${paths.length} change(s)\n`);
+                    await runIndex(config, { incremental: true });
+                },
+                onWarn: (message) => process.stderr.write(`${message}\n`),
+            });
+        }
+        catch (err) {
+            // Degrade gracefully (EMFILE, permissions, …) — serve without watch.
+            process.stderr.write(`[mast] watch: failed to start watcher, continuing without --watch: ${String(err)}\n`);
+            return;
+        }
+        // Clean shutdown: chokidar's persistent watcher would otherwise keep the
+        // process alive after the MCP client disconnects (stdin close) or on
+        // SIGTERM/SIGINT.
+        const closeWatcher = () => {
+            const handle = watchHandle;
+            watchHandle = null;
+            if (handle !== null)
+                void handle.close().catch(() => { });
+        };
+        process.stdin.on('close', closeWatcher);
+        process.once('SIGTERM', closeWatcher);
+        process.once('SIGINT', closeWatcher);
+    };
+    // ── Step 4: background reindex ────────────────────────────────────────────
+    if (options.noStartupReindex) {
+        startWatchIfRequested();
+        return;
+    }
+    void (async () => {
+        try {
+            await runIndex(config, { incremental: !needsFullReindex });
+        }
+        catch (err) {
+            process.stderr.write(`[mast] startup indexing failed: ${String(err)}\n`);
+        }
+    })();
+    startWatchIfRequested();
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

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

package/dist/mcp/staleness.d.ts

@@ -0,0 +1,72 @@
+import type { Db } from '../graph/db.js';
+import type { ResolvedConfig } from '../store/config.js';
+import { populateFile } from '../graph/populate.js';
+/**
+ * Stat each of `filePaths` (deduplicated by the caller — see below) and
+ * compare disk mtime against the `files` table's stored mtime, WITHOUT
+ * acquiring `structure.lock` or re-parsing anything.
+ *
+ * `mast_search` and `mast_implementors` deliberately do NOT get the
+ * JIT-refresh treatment `checkAndRefreshIfStale` gives single-file tools
+ * (`mast_signature`, `mast_exports`, ...): both can return results spanning
+ * dozens of files, and a naive per-result JIT refresh would mean up to ~50
+ * `structure.lock` acquisitions on one call PLUS re-parsing files whose
+ * content change could invalidate the ranking that already selected these
+ * results (a result re-parsed mid-response could shift rank, gain/lose a
+ * match, or change chunk boundaries entirely — `eval/GITNEXUS_COMPARISON.md`
+ * §13.7). Stat-and-flag reports the discrepancy honestly without paying
+ * that cost or contaminating the ranking: the agent is told the coordinates
+ * may be off and can decide whether to re-verify.
+ *
+ * Returns the subset of `filePaths` to flag with `stale: true` (C1 split
+ * this signal off the JIT-refresh tools' `file_busy_returning_stale_cache`
+ * — no lock is ever taken here, so nothing is ever "busy" in that sense):
+ * disk mtime newer than the indexed mtime, OR the stat failed (file
+ * deleted/renamed — its coordinates are definitely untrustworthy). A path
+ * absent from the `files` table is left out of the returned set entirely —
+ * there is nothing indexed to be stale against, so no signal is invented.
+ */
+export declare function findStaleFiles(db: Db, config: ResolvedConfig, filePaths: readonly string[]): Promise<ReadonlySet<string>>;
+export interface StalenessCheckResult {
+    /** True if a JIT re-parse was successfully performed. */
+    readonly refreshed: boolean;
+    /**
+     * True when the file was stale but the lock could not be acquired (file is
+     * mid-write). Callers should set `file_busy_returning_stale_cache: true` on
+     * affected result objects rather than throwing.
+     */
+    readonly busy: boolean;
+}
+/**
+ * Check `filePath` for staleness by comparing disk mtime against
+ * `storedMtime`. If stale, re-parse and persist it via {@link populateFile}
+ * (10–50ms per spec §9.0).
+ *
+ * **F11 (`IMPLEMENTATION_PLAN.md` "Replace fail-fast advisory locking")
+ * removed `structure.lock` from this path entirely.** Before F11, this
+ * function acquired the lock (`maxRetries: 3, retryIntervalMs: 100`) before
+ * re-parsing — but `structure.lock` was a single lock per state dir with no
+ * file component (`store/lock.ts`'s `markerPath`), so a JIT re-parse of file
+ * A blocked a JIT re-parse of file B despite touching disjoint rows. E7
+ * measured this as 35–88.5% JIT failure rates under pure reader-vs-reader
+ * concurrency (zero reindex running), which only gets worse as more agents
+ * work concurrently. That contention class disappears by construction once
+ * this path stops taking a lock at all: two JIT refreshes of different files
+ * now run their (dominant-cost, per E7-r2) parse step fully in parallel, and
+ * only briefly serialize on `populateFile`'s own short `BEGIN IMMEDIATE`
+ * write (see that function's doc comment) — which also correctly governs the
+ * ONE thing `structure.lock` was still protecting on this path: real
+ * cross-connection SQLite contention (a concurrent reindex batch, or another
+ * `mast serve` process). `structure.lock` itself is not deleted — coarse
+ * writers (`mast index`, `mast_reindex`, the manifest/`index.json` phase, the
+ * checker-resolver flush) still acquire it unchanged, because SQLite cannot
+ * coordinate the plain-JSON manifest writes those callers also make.
+ *
+ * On a genuinely contended write (`populateFile`'s `BEGIN IMMEDIATE` losing
+ * its own short `busy_timeout` wait, or a mid-write parse failure) returns
+ * `{ busy: true }` so the caller can fall back to the TOCTOU policy — return
+ * the stale chunk with `file_busy_returning_stale_cache: true`. Never throws
+ * for these expected contention outcomes (§9.0).
+ */
+export declare function checkAndRefreshIfStale(db: Db, config: ResolvedConfig, filePath: string, storedMtime: number, populateFileImpl?: typeof populateFile): Promise<StalenessCheckResult>;
+//# sourceMappingURL=staleness.d.ts.map

package/dist/mcp/staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.d.ts","sourceRoot":"","sources":["../../src/mcp/staleness.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AA+DpD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,EAAE,EACN,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAqB9B;AAMD,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,EAAE,EACN,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EAKnB,gBAAgB,GAAE,OAAO,YAA2B,GACnD,OAAO,CAAC,oBAAoB,CAAC,CAwE/B"}

package/dist/mcp/staleness.js

@@ -0,0 +1,213 @@
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { extractFile } from '../ast/extract.js';
+import { populateFile } from '../graph/populate.js';
+function hasSqliteCode(err) {
+    return err instanceof Error && 'code' in err && typeof err.code === 'string';
+}
+/**
+ * `SQLITE_BUSY_SNAPSHOT` (and plain `SQLITE_BUSY`) are the only codes this
+ * function treats as recoverable.
+ *
+ * Originally (F13): F12's monotonic-guard `SELECT` turned `populateFile`'s
+ * transaction into a read-then-write shape, which — under Kysely's deferred
+ * `BEGIN` (`sqlite-driver.js:32-34`) — could make the transaction's snapshot
+ * go stale if another writer committed in between; a fresh transaction takes
+ * a fresh snapshot and usually succeeds (E7-r2, `eval/e7-round2.json`, 52
+ * occurrences across 23/32 real runs).
+ *
+ * F11 moved `populateFile` to `BEGIN IMMEDIATE` (`graph/populate.ts`), which
+ * eliminates that specific `SQLITE_BUSY_SNAPSHOT` failure mode at the source
+ * — it takes the write reservation up front instead of discovering
+ * contention on commit. This retry-then-map loop stays as the backstop §9.0
+ * requires regardless: `populateFile`'s own short `busy_timeout`
+ * (`IMMEDIATE_WRITE_BUSY_TIMEOUT_MS`) can still be legitimately exhausted
+ * under real contention (surfacing as plain `SQLITE_BUSY`), and a retry with
+ * a fresh transaction is still the correct response to either code. Any
+ * other `SQLITE_*` code (constraint violation, corruption, disk full, ...)
+ * is a genuinely unexpected failure, not TOCTOU noise — conflating it with
+ * "busy" would repeat the parse_errors/write_errors misclassification this
+ * codebase already fixed once (`indexer/__tests__/write-failures.test.ts`),
+ * so it is deliberately excluded here and left to propagate.
+ */
+function isRetryableBusySnapshot(err) {
+    return hasSqliteCode(err) && (err.code === 'SQLITE_BUSY_SNAPSHOT' || err.code === 'SQLITE_BUSY');
+}
+/**
+ * Bounded retry count for `populateFile` under a busy snapshot. Chosen small
+ * (1 retry = 2 attempts total) because each retry opens a brand-new
+ * transaction — either the contention has cleared and the retry succeeds
+ * immediately, or the file is under sustained concurrent write pressure and
+ * further retries just delay the `busy: true` fallback the TOCTOU policy
+ * (§9.0) already exists to handle. No sleep between attempts: a stale
+ * `SQLITE_BUSY_SNAPSHOT` needs a fresh transaction, not time, to resolve;
+ * `SQLITE_BUSY` already got its own bounded wait inside `populateFile`'s own
+ * `busy_timeout` (`IMMEDIATE_WRITE_BUSY_TIMEOUT_MS`, F11) before it ever
+ * reaches this retry loop, so adding a second wait here would double-count
+ * the same contention.
+ */
+const MAX_POPULATE_RETRIES = 1;
+// ---------------------------------------------------------------------------
+// F7 — stat-and-flag staleness for mast_search / mast_implementors (§9.0)
+// ---------------------------------------------------------------------------
+/**
+ * Stat each of `filePaths` (deduplicated by the caller — see below) and
+ * compare disk mtime against the `files` table's stored mtime, WITHOUT
+ * acquiring `structure.lock` or re-parsing anything.
+ *
+ * `mast_search` and `mast_implementors` deliberately do NOT get the
+ * JIT-refresh treatment `checkAndRefreshIfStale` gives single-file tools
+ * (`mast_signature`, `mast_exports`, ...): both can return results spanning
+ * dozens of files, and a naive per-result JIT refresh would mean up to ~50
+ * `structure.lock` acquisitions on one call PLUS re-parsing files whose
+ * content change could invalidate the ranking that already selected these
+ * results (a result re-parsed mid-response could shift rank, gain/lose a
+ * match, or change chunk boundaries entirely — `eval/GITNEXUS_COMPARISON.md`
+ * §13.7). Stat-and-flag reports the discrepancy honestly without paying
+ * that cost or contaminating the ranking: the agent is told the coordinates
+ * may be off and can decide whether to re-verify.
+ *
+ * Returns the subset of `filePaths` to flag with `stale: true` (C1 split
+ * this signal off the JIT-refresh tools' `file_busy_returning_stale_cache`
+ * — no lock is ever taken here, so nothing is ever "busy" in that sense):
+ * disk mtime newer than the indexed mtime, OR the stat failed (file
+ * deleted/renamed — its coordinates are definitely untrustworthy). A path
+ * absent from the `files` table is left out of the returned set entirely —
+ * there is nothing indexed to be stale against, so no signal is invented.
+ */
+export async function findStaleFiles(db, config, filePaths) {
+    if (filePaths.length === 0)
+        return new Set();
+    const rows = await db
+        .selectFrom('files')
+        .select(['path', 'mtime'])
+        .where('path', 'in', filePaths)
+        .execute();
+    const stale = new Set();
+    for (const row of rows) {
+        try {
+            const stat = statSync(join(config.resolved_project_root, row.path));
+            if (stat.mtimeMs / 1_000 > row.mtime)
+                stale.add(row.path);
+        }
+        catch {
+            // File deleted/renamed since indexing — coordinates are definitely
+            // untrustworthy, flag rather than silently omit.
+            stale.add(row.path);
+        }
+    }
+    return stale;
+}
+/**
+ * Check `filePath` for staleness by comparing disk mtime against
+ * `storedMtime`. If stale, re-parse and persist it via {@link populateFile}
+ * (10–50ms per spec §9.0).
+ *
+ * **F11 (`IMPLEMENTATION_PLAN.md` "Replace fail-fast advisory locking")
+ * removed `structure.lock` from this path entirely.** Before F11, this
+ * function acquired the lock (`maxRetries: 3, retryIntervalMs: 100`) before
+ * re-parsing — but `structure.lock` was a single lock per state dir with no
+ * file component (`store/lock.ts`'s `markerPath`), so a JIT re-parse of file
+ * A blocked a JIT re-parse of file B despite touching disjoint rows. E7
+ * measured this as 35–88.5% JIT failure rates under pure reader-vs-reader
+ * concurrency (zero reindex running), which only gets worse as more agents
+ * work concurrently. That contention class disappears by construction once
+ * this path stops taking a lock at all: two JIT refreshes of different files
+ * now run their (dominant-cost, per E7-r2) parse step fully in parallel, and
+ * only briefly serialize on `populateFile`'s own short `BEGIN IMMEDIATE`
+ * write (see that function's doc comment) — which also correctly governs the
+ * ONE thing `structure.lock` was still protecting on this path: real
+ * cross-connection SQLite contention (a concurrent reindex batch, or another
+ * `mast serve` process). `structure.lock` itself is not deleted — coarse
+ * writers (`mast index`, `mast_reindex`, the manifest/`index.json` phase, the
+ * checker-resolver flush) still acquire it unchanged, because SQLite cannot
+ * coordinate the plain-JSON manifest writes those callers also make.
+ *
+ * On a genuinely contended write (`populateFile`'s `BEGIN IMMEDIATE` losing
+ * its own short `busy_timeout` wait, or a mid-write parse failure) returns
+ * `{ busy: true }` so the caller can fall back to the TOCTOU policy — return
+ * the stale chunk with `file_busy_returning_stale_cache: true`. Never throws
+ * for these expected contention outcomes (§9.0).
+ */
+export async function checkAndRefreshIfStale(db, config, filePath, storedMtime, 
+// Test-only injection point (§4.4 DI), mirroring `populateFile`'s own
+// `ChunkWriter` seam (`graph/populate.ts`) — lets F13's regression tests
+// (`mcp/__tests__/staleness.test.ts`) induce a genuine SQLITE_BUSY_SNAPSHOT
+// via a second real connection instead of mocking `populateFile` wholesale.
+populateFileImpl = populateFile) {
+    const absPath = join(config.resolved_project_root, filePath);
+    let diskMtime;
+    try {
+        const stat = statSync(absPath);
+        diskMtime = stat.mtimeMs / 1_000;
+    }
+    catch {
+        // File deleted — nothing to refresh; callers handle missing results.
+        return { refreshed: false, busy: false };
+    }
+    if (diskMtime <= storedMtime)
+        return { refreshed: false, busy: false };
+    // File is stale — re-parse and persist it. No lock acquisition here (F11,
+    // see this function's doc comment) — `populateFile`'s own `BEGIN IMMEDIATE`
+    // transaction is what now bounds and serializes the write.
+    let result;
+    try {
+        result = extractFile(absPath, config.resolved_project_root, config.context_lines, config.chunk_split_threshold, config.markdown_heading_depth);
+    }
+    catch {
+        // TOCTOU: file mid-write, first parse attempt failed.
+        await new Promise((res) => setTimeout(res, 50));
+        try {
+            result = extractFile(absPath, config.resolved_project_root, config.context_lines, config.chunk_split_threshold, config.markdown_heading_depth);
+        }
+        catch {
+            // Second attempt also failed — signal busy to caller.
+            return { refreshed: false, busy: true };
+        }
+    }
+    // populateFile writes chunks + FTS5 + graph rows in ONE SQLite transaction
+    // (M1, §15.1) — no separate chunk-store call needed here any more (the
+    // pre-M1 code wrote chunks to Lance in a step of its own, which — once
+    // SQLite became the default chunk store — would have left a JIT refresh's
+    // new chunk content invisible to every reader).
+    //
+    // F13: this call used to be unwrapped, so a SQLITE_BUSY_SNAPSHOT thrown
+    // here escaped uncaught — bypassing the busy flag below and violating
+    // §9.0's "do not throw" TOCTOU policy (52 real occurrences, E7-r2). F11's
+    // `BEGIN IMMEDIATE` (`graph/populate.ts`) eliminates that specific failure
+    // class at the source, but this retry-then-map loop stays as the backstop
+    // §9.0 requires: `populateFile`'s own short `busy_timeout` can still be
+    // legitimately exhausted under real contention, and that must map to
+    // `{ busy: true }`, never propagate as a raw throw. A non-busy error is NOT
+    // retried and NOT reclassified — it propagates immediately.
+    const totalAttempts = MAX_POPULATE_RETRIES + 1;
+    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+        try {
+            await populateFileImpl(db, {
+                filePath,
+                language: result.language,
+                mtime: diskMtime,
+                chunks: result.chunks,
+                imports: result.imports,
+                symbols: result.symbols,
+                identifierRows: result.identifierRows,
+            });
+            return { refreshed: true, busy: false };
+        }
+        catch (err) {
+            if (!isRetryableBusySnapshot(err))
+                throw err; // not busy — surface distinctly, do not retry
+            if (attempt === totalAttempts)
+                return { refreshed: false, busy: true }; // retries exhausted
+            // Retries remain — loop immediately, no sleep (see
+            // MAX_POPULATE_RETRIES's WHY-comment: a stale snapshot needs a fresh
+            // transaction, not time).
+        }
+    }
+    // Unreachable: the loop above always returns or throws on its final
+    // iteration. TypeScript can't prove that from a `for` bound by a runtime
+    // constant, so an explicit busy fallback keeps `noImplicitReturns`
+    // satisfied without an `as never`.
+    return { refreshed: false, busy: true };
+}
+//# sourceMappingURL=staleness.js.map

package/dist/mcp/staleness.js.map

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

package/dist/mcp/startup.d.ts

@@ -0,0 +1,40 @@
+import type { ResolvedConfig } from '../store/config.js';
+/**
+ * Remove all index-derived state from `stateDir`, keeping `config.json` and the
+ * advisory lock markers. Used on a schema-version change (§7.4 Step 2) so a
+ * stale on-disk shape can never be read by code expecting the new schema.
+ */
+export declare function wipeDerivedState(stateDir: string): void;
+/**
+ * Best-effort delete orphaned vector-store state from `stateDir`.
+ *
+ * Stage 7 (decision 3) deliberately did NOT bump `CURRENT_SCHEMA_VERSION` —
+ * nothing the new code READS changed shape, so `bootstrapState`'s schema
+ * guard never fires for a pre-Stage-7 state dir and never runs
+ * {@link wipeDerivedState} on its behalf. Without this, `lance/`/`embed_cache/`/
+ * `vectors.lock` would sit on disk forever after an upgrade. Runs
+ * unconditionally on every startup (not gated on the schema check), and never
+ * throws: a permission error or a race with another process must not block
+ * serving over a directory nothing reads any more.
+ */
+export declare function cleanupOrphanedVectorState(stateDir: string): void;
+export interface BootstrapResult {
+    /** True when a full (non-incremental) reindex must run, e.g. after a wipe. */
+    readonly needsFullReindex: boolean;
+}
+/**
+ * Startup steps 1–2 of §7.4.
+ *
+ * Step 1 — bootstrap the state directory: copy the Docker-baked seed when the
+ *   state dir is empty, ensure lock markers exist, persist the resolved
+ *   config, and best-effort remove orphaned pre-Stage-7 vector-store state
+ *   (IMPLEMENTATION_PLAN.md "Stage 7: Vector-store deletion", decision 3).
+ * Step 2 — enforce the schema-version guard: if the on-disk `index.json` was
+ *   written by a different `schema_version` (including a seed baked against an
+ *   old schema, §13.8.2), wipe ALL derived state and request a full rebuild.
+ *
+ * `seedPath` is injectable so tests can point at a fixture or a path that does
+ * not exist (the common test case).
+ */
+export declare function bootstrapState(config: ResolvedConfig, seedPath?: string): Promise<BootstrapResult>;
+//# sourceMappingURL=startup.d.ts.map

package/dist/mcp/startup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup.d.ts","sourceRoot":"","sources":["../../src/mcp/startup.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAsBzD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAIvD;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAejE;AAED,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,QAAQ,GAAE,MAA0B,GACnC,OAAO,CAAC,eAAe,CAAC,CA2B1B"}

package/dist/mcp/startup.js

@@ -0,0 +1,114 @@
+import { existsSync, rmSync } from 'node:fs';
+import { cp } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CURRENT_SCHEMA_VERSION, writeStateConfig } from '../store/config.js';
+import { initLockMarkers } from '../store/lock.js';
+import { loadIndexMeta, writeIndexMeta } from '../indexer/index.js';
+/** Default location of the Docker-baked seed index (§13.8). */
+const DEFAULT_SEED_PATH = '/opt/mast-seed';
+/**
+ * All index-derived state under the state directory. Everything here is rebuilt
+ * from source by a reindex; `config.json` and the lock marker files are NOT in
+ * this set and are preserved.
+ */
+const DERIVED_STATE_ENTRIES = [
+    'lance', // chunks + vectors tables
+    'graph.db', // knowledge graph + FTS
+    'graph.db-wal', // SQLite WAL sidecar
+    'graph.db-shm', // SQLite shared-memory sidecar
+    'file_manifest.json', // mtime snapshot
+    'embed_cache', // per-content-hash embedding cache
+];
+/**
+ * Remove all index-derived state from `stateDir`, keeping `config.json` and the
+ * advisory lock markers. Used on a schema-version change (§7.4 Step 2) so a
+ * stale on-disk shape can never be read by code expecting the new schema.
+ */
+export function wipeDerivedState(stateDir) {
+    for (const entry of DERIVED_STATE_ENTRIES) {
+        rmSync(join(stateDir, entry), { recursive: true, force: true });
+    }
+}
+// ---------------------------------------------------------------------------
+// Orphaned vector-store state (IMPLEMENTATION_PLAN.md "Stage 7: Vector-store
+// deletion", decision 3)
+// ---------------------------------------------------------------------------
+/**
+ * State a pre-Stage-7 install can leave behind: `lance/` (the retired chunk +
+ * vector tables), `embed_cache/` (per-content-hash embedding cache), and
+ * `vectors.lock` (proper-lockfile's own `<marker>.lock` artifact for the
+ * 'vectors' lock type, which Stage 7.1 removed — `store/lock.ts`'s
+ * `LockType` union of one).
+ */
+const ORPHANED_VECTOR_STATE_ENTRIES = ['lance', 'embed_cache', 'vectors.lock'];
+/**
+ * Best-effort delete orphaned vector-store state from `stateDir`.
+ *
+ * Stage 7 (decision 3) deliberately did NOT bump `CURRENT_SCHEMA_VERSION` —
+ * nothing the new code READS changed shape, so `bootstrapState`'s schema
+ * guard never fires for a pre-Stage-7 state dir and never runs
+ * {@link wipeDerivedState} on its behalf. Without this, `lance/`/`embed_cache/`/
+ * `vectors.lock` would sit on disk forever after an upgrade. Runs
+ * unconditionally on every startup (not gated on the schema check), and never
+ * throws: a permission error or a race with another process must not block
+ * serving over a directory nothing reads any more.
+ */
+export function cleanupOrphanedVectorState(stateDir) {
+    const removed = [];
+    for (const entry of ORPHANED_VECTOR_STATE_ENTRIES) {
+        const entryPath = join(stateDir, entry);
+        try {
+            if (!existsSync(entryPath))
+                continue;
+            rmSync(entryPath, { recursive: true, force: true });
+            removed.push(entry);
+        }
+        catch (err) {
+            process.stderr.write(`[mast] startup: failed to remove orphaned vector state "${entry}": ${String(err)}\n`);
+        }
+    }
+    if (removed.length > 0) {
+        process.stderr.write(`[mast] startup: removed orphaned vector state: ${removed.join(', ')}\n`);
+    }
+}
+/**
+ * Startup steps 1–2 of §7.4.
+ *
+ * Step 1 — bootstrap the state directory: copy the Docker-baked seed when the
+ *   state dir is empty, ensure lock markers exist, persist the resolved
+ *   config, and best-effort remove orphaned pre-Stage-7 vector-store state
+ *   (IMPLEMENTATION_PLAN.md "Stage 7: Vector-store deletion", decision 3).
+ * Step 2 — enforce the schema-version guard: if the on-disk `index.json` was
+ *   written by a different `schema_version` (including a seed baked against an
+ *   old schema, §13.8.2), wipe ALL derived state and request a full rebuild.
+ *
+ * `seedPath` is injectable so tests can point at a fixture or a path that does
+ * not exist (the common test case).
+ */
+export async function bootstrapState(config, seedPath = DEFAULT_SEED_PATH) {
+    // Step 1.
+    if (!existsSync(config.resolved_state_dir) && existsSync(seedPath)) {
+        await cp(seedPath, config.resolved_state_dir, { recursive: true });
+    }
+    initLockMarkers(config.resolved_state_dir);
+    writeStateConfig(config.resolved_state_dir, config);
+    // Runs on every startup, independent of the schema-version guard below —
+    // Stage 7 deliberately did not bump CURRENT_SCHEMA_VERSION (decision 3), so
+    // the guard's wipe path never fires for a pre-Stage-7 state dir and this is
+    // the only thing that ever clears these orphans.
+    cleanupOrphanedVectorState(config.resolved_state_dir);
+    // Step 2.
+    const meta = loadIndexMeta(config.resolved_state_dir);
+    if (meta !== null && meta.schema_version !== CURRENT_SCHEMA_VERSION) {
+        wipeDerivedState(config.resolved_state_dir);
+        writeIndexMeta(config.resolved_state_dir, {
+            schema_version: CURRENT_SCHEMA_VERSION,
+            last_indexed: null,
+            file_count: 0,
+            chunk_count: 0,
+        });
+        return { needsFullReindex: true };
+    }
+    return { needsFullReindex: false };
+}
+//# sourceMappingURL=startup.js.map

package/dist/mcp/startup.js.map

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