@spikedpunch/mast 0.1.0

package/dist/graph/local-type-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-type-env.d.ts","sourceRoot":"","sources":["../../src/graph/local-type-env.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;;;;;;;;;;;GAaG;AACH,qBAAa,oBAAoB;IAC/B,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuC;IACrE,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqE;IAEnG,gFAAgF;IAChF,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrC,8EAA8E;IAC9E,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIxC;;;;OAIG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAItF;;;;;;;;OAQG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,gBAAgB,CAAA;KAAE,GAAG,IAAI;CAS9G"}

package/dist/graph/local-type-env.js

@@ -0,0 +1,59 @@
+/**
+ * Synchronous heuristic resolver for `POTENTIAL_CALL` edges (§10.3.1).
+ *
+ * Built up per function/method scope during the AST walk, then queried for
+ * each call site. It resolves a call's receiver to a callee *symbol name* using
+ * a small set of high-frequency, statically-decidable patterns. It does NOT
+ * touch the database — whether the resolved name corresponds to a real indexed
+ * symbol is decided later, in `insertEdges`' name→id resolution (an unknown
+ * name simply yields no edge).
+ *
+ * Intentionally conservative: false negatives (missed edges) are acceptable;
+ * false positives (wrong edges) are not, as they would poison the
+ * `verified_callers` contract in `mast_callers`.
+ */
+export class LocalTypeEnvironment {
+    /** Named imports and same-file top-level symbols, by bare name. */
+    bareCallables = new Map();
+    /** Receiver expression (`repo`, `this.repo`) → its resolved type name. */
+    receiverTypes = new Map();
+    /** `import { handleLogin } from './h'` → bare call `handleLogin()` resolves. */
+    recordImport(localName) {
+        if (!this.bareCallables.has(localName))
+            this.bareCallables.set(localName, 'import');
+    }
+    /** A top-level function/const in the same file → bare call resolves to it. */
+    recordSameFileSymbol(name) {
+        if (!this.bareCallables.has(name))
+            this.bareCallables.set(name, 'same_file');
+    }
+    /**
+     * A typed receiver binding. `receiver` is the literal receiver expression as
+     * it appears before the method call — e.g. `repo` (local/param) or
+     * `this.repo` (class field / constructor parameter property).
+     */
+    recordReceiverType(receiver, type, resolution) {
+        if (!this.receiverTypes.has(receiver))
+            this.receiverTypes.set(receiver, { type, resolution });
+    }
+    /**
+     * Resolve a call to `{ callee, resolution }`, or null when the receiver
+     * cannot be statically linked.
+     *
+     * @param receiver - the receiver expression (`repo`, `this.repo`), or null
+     *   for a bare call (`foo()`).
+     * @param method - the called identifier (the function name for a bare call,
+     *   the member name for a receiver call).
+     */
+    resolveCall(receiver, method) {
+        if (receiver === null) {
+            const resolution = this.bareCallables.get(method);
+            return resolution === undefined ? null : { callee: method, resolution };
+        }
+        const binding = this.receiverTypes.get(receiver);
+        if (binding === undefined)
+            return null;
+        return { callee: `${binding.type}.${method}`, resolution: binding.resolution };
+    }
+}
+//# sourceMappingURL=local-type-env.js.map

package/dist/graph/local-type-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-type-env.js","sourceRoot":"","sources":["../../src/graph/local-type-env.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,oBAAoB;IAC/B,mEAAmE;IAClD,aAAa,GAAG,IAAI,GAAG,EAA4B,CAAC;IACrE,0EAA0E;IACzD,aAAa,GAAG,IAAI,GAAG,EAA0D,CAAC;IAEnG,gFAAgF;IAChF,YAAY,CAAC,SAAiB;QAC5B,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACtF,CAAC;IAED,8EAA8E;IAC9E,oBAAoB,CAAC,IAAY;QAC/B,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC/E,CAAC;IAED;;;;OAIG;IACH,kBAAkB,CAAC,QAAgB,EAAE,IAAY,EAAE,UAA4B;QAC7E,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IAChG,CAAC;IAED;;;;;;;;OAQG;IACH,WAAW,CAAC,QAAuB,EAAE,MAAc;QACjD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAClD,OAAO,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAC1E,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACjD,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACvC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;IACjF,CAAC;CACF"}

package/dist/graph/path-range.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Half-open range bounds for "this path starts with P" queries.
+ *
+ * The obvious spelling, `path LIKE P || '%'`, is wrong three ways:
+ *
+ *  - **`_` and `%` inside P act as wildcards.** Paths are not escaped before
+ *    interpolation, so `src/my_util.ts` also matches `src/my.util.ts`. With
+ *    `ORDER BY path` that returns the wrong row, because `.` (0x2E) sorts
+ *    before `_` (0x5F).
+ *  - **LIKE is case-insensitive for ASCII.** `case_sensitive_like` is OFF by
+ *    default, so `src/Foo.ts` matches `src/FOO.ts` — and `FOO` sorts first.
+ *  - **It cannot use the index.** SQLite's LIKE optimization requires either
+ *    `case_sensitive_like=ON` or a NOCASE-collated index; `files.path`'s
+ *    implicit UNIQUE index is BINARY. The plan degrades to `SCAN files USING
+ *    COVERING INDEX sqlite_autoindex_files_1` — the only scan among the
+ *    resolver's five lookups (FINDINGS.md §2.3).
+ *
+ * A half-open range on the BINARY collation fixes all three at once: it is
+ * literal, case-sensitive, and a plain two-sided index seek.
+ *
+ * Exactness: for any suffix S, `P <= P||S < P||U+10FFFF` holds, and any row in
+ * `[P, P||U+10FFFF)` must start with P — a row differing from P at some
+ * position inside P is either below P or at/above the bound. The single
+ * excluded case is a path whose character immediately after P is U+10FFFF, the
+ * highest code point, a permanently-unassigned noncharacter that cannot appear
+ * in a filename.
+ */
+/**
+ * The exclusive upper bound for paths beginning with `prefix`.
+ *
+ * Pair with a `>= prefix` lower bound:
+ * `.where('path', '>=', p).where('path', '<', pathPrefixUpperBound(p))`.
+ *
+ * The bound is only ordered correctly under SQLite's BINARY collation, which
+ * is `memcmp` over UTF-8. JavaScript's `<` compares UTF-16 code units, under
+ * which U+FFFF sorts ABOVE the surrogate pair for U+10FFFF — so this value is
+ * for SQL comparison only. Do not use it to filter paths in JS.
+ */
+export declare function pathPrefixUpperBound(prefix: string): string;
+//# sourceMappingURL=path-range.d.ts.map

package/dist/graph/path-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-range.d.ts","sourceRoot":"","sources":["../../src/graph/path-range.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/graph/path-range.js

@@ -0,0 +1,42 @@
+/**
+ * Half-open range bounds for "this path starts with P" queries.
+ *
+ * The obvious spelling, `path LIKE P || '%'`, is wrong three ways:
+ *
+ *  - **`_` and `%` inside P act as wildcards.** Paths are not escaped before
+ *    interpolation, so `src/my_util.ts` also matches `src/my.util.ts`. With
+ *    `ORDER BY path` that returns the wrong row, because `.` (0x2E) sorts
+ *    before `_` (0x5F).
+ *  - **LIKE is case-insensitive for ASCII.** `case_sensitive_like` is OFF by
+ *    default, so `src/Foo.ts` matches `src/FOO.ts` — and `FOO` sorts first.
+ *  - **It cannot use the index.** SQLite's LIKE optimization requires either
+ *    `case_sensitive_like=ON` or a NOCASE-collated index; `files.path`'s
+ *    implicit UNIQUE index is BINARY. The plan degrades to `SCAN files USING
+ *    COVERING INDEX sqlite_autoindex_files_1` — the only scan among the
+ *    resolver's five lookups (FINDINGS.md §2.3).
+ *
+ * A half-open range on the BINARY collation fixes all three at once: it is
+ * literal, case-sensitive, and a plain two-sided index seek.
+ *
+ * Exactness: for any suffix S, `P <= P||S < P||U+10FFFF` holds, and any row in
+ * `[P, P||U+10FFFF)` must start with P — a row differing from P at some
+ * position inside P is either below P or at/above the bound. The single
+ * excluded case is a path whose character immediately after P is U+10FFFF, the
+ * highest code point, a permanently-unassigned noncharacter that cannot appear
+ * in a filename.
+ */
+/**
+ * The exclusive upper bound for paths beginning with `prefix`.
+ *
+ * Pair with a `>= prefix` lower bound:
+ * `.where('path', '>=', p).where('path', '<', pathPrefixUpperBound(p))`.
+ *
+ * The bound is only ordered correctly under SQLite's BINARY collation, which
+ * is `memcmp` over UTF-8. JavaScript's `<` compares UTF-16 code units, under
+ * which U+FFFF sorts ABOVE the surrogate pair for U+10FFFF — so this value is
+ * for SQL comparison only. Do not use it to filter paths in JS.
+ */
+export function pathPrefixUpperBound(prefix) {
+    return `${prefix}\u{10FFFF}`;
+}
+//# sourceMappingURL=path-range.js.map

package/dist/graph/path-range.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-range.js","sourceRoot":"","sources":["../../src/graph/path-range.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,OAAO,GAAG,MAAM,YAAY,CAAC;AAC/B,CAAC"}

package/dist/graph/populate.d.ts

@@ -0,0 +1,263 @@
+import { type Db } from './db.js';
+import type { Chunk, Language, SymbolRecord, ImportRecord, EdgeRecord } from '../ast/types.js';
+import type { IdentifierRow, StarReExportRecord } from '../ast/extractor.js';
+export type { SymbolRecord, ImportRecord, EdgeRecord };
+export interface FileIndexData {
+    readonly filePath: string;
+    readonly language: Language;
+    readonly mtime: number;
+    readonly chunks: readonly Chunk[];
+    readonly imports: readonly ImportRecord[];
+    readonly symbols: readonly SymbolRecord[];
+    /**
+     * Pre-extracted identifier tokens per chunk, produced by the language
+     * extractor — what counts as an "identifier" is a language-level judgment
+     * (markdown contributes none). This layer only persists them.
+     */
+    readonly identifierRows: readonly IdentifierRow[];
+    /** Populated on the second pass after all symbols are inserted. */
+    readonly edges: readonly EdgeRecord[];
+}
+/**
+ * Result of {@link populateFile}: the new `files` row id, plus how many
+ * previously-stored chunks were replaced (for `IndexResult.chunksRemoved`
+ * accounting — mirrors the removed-count `SqliteChunkStore.replaceChunksForFile`
+ * used to report directly before chunks moved into this transaction).
+ */
+export interface PopulateFileResult {
+    readonly fileId: number;
+    readonly chunksRemoved: number;
+    /**
+     * False when the monotonic write-guard (F12, see {@link populateFile}'s
+     * doc) refused this write because the stored row's mtime already exceeds
+     * `data.mtime` — this call lost a race against a fresher write. The row is
+     * left completely unchanged: `fileId` is the EXISTING row's id and
+     * `chunksRemoved` is 0. Callers must surface this (count it, log it) rather
+     * than treat it as an ordinary successful write — a skipped write must
+     * never be indistinguishable from a completed one (the `writeErrors`
+     * precedent this mirrors).
+     */
+    readonly written: boolean;
+}
+/**
+ * Test-only injection point (§4.4 DI): when provided, `populateFile` calls
+ * this instead of writing the `chunks` table inline. Lets write-failure tests
+ * (`indexer/__tests__/write-failures.test.ts`) inject a chunk-store failure
+ * with an in-memory fake — since the call happens INSIDE this function's own
+ * `BEGIN IMMEDIATE` transaction, a rejection here still rolls back everything
+ * else the transaction already wrote (symbols/imports/chunk_fts/identifier_fts),
+ * proving the same atomicity the production (no-override) path gets from
+ * writing straight to the shared `chunks` table. Structurally compatible with
+ * `ChunkStore.replaceChunksForFile` (store/sqliteChunkStore.js) without this
+ * module importing that type — graph/ stays independent of store/'s DI seam,
+ * only its method shape.
+ */
+export type ChunkWriter = (filePath: string, chunks: readonly Chunk[]) => Promise<number>;
+/**
+ * Cumulative wall-clock, in ms, for the four regions that tile a file's write.
+ *
+ * Eval instrument (E1-FTS, IMPLEMENTATION_PLAN.md § E1-FTS PRE-REGISTRATION,
+ * 2026-08-14). E1-PHASE localised the super-linear growth exponent to the
+ * `write` phase (`b_write = 1.9685`, 94.01% of T9's run) but no further; these
+ * four decompose that phase.
+ *
+ * Mutable by design — it is an accumulator summed across every `populateFile`
+ * call in a run, in the same shape and for the same reason as `runIndex`'s own
+ * `phase` record. Data, not behaviour (§4.2), so it is a record and not a class.
+ *
+ * **Every region is timed by its own start and end. None is computed by
+ * subtraction.** A `rest` derived as `write − fts` would silently absorb any
+ * cost the other timers missed, which is precisely how this experiment's first
+ * draft would have produced a false null: FTS5 flushes its segments at COMMIT
+ * (`fts5SyncMethod`, `sqlite3.c:262278`; `xCommit` is a no-op at `:262302`),
+ * not inside the INSERT, so a naive `fts_ms` around the inserts misses them.
+ * Because the regions are timed independently they need not tile exactly, and
+ * the shortfall is the point: unattributed work shows up as a tiling gap the
+ * harness's ≥ 0.95 gate can see, instead of being absorbed in silence.
+ */
+export interface WriteSpansMs {
+    /** The two `DELETE FROM *_fts WHERE file_path = ?` statements. */
+    fts_del: number;
+    /** The two batched `INSERT INTO *_fts` loops. */
+    fts_ins: number;
+    /** The per-file `COMMIT`, where FTS5's segment flush actually happens. */
+    commit: number;
+    /** The monotonic guard, the `files` row, and the chunks/symbols/imports writes. */
+    rest: number;
+    /**
+     * Per-file transaction machinery: connection checkout, the two `busy_timeout`
+     * pragmas, and `BEGIN IMMEDIATE`.
+     *
+     * AMENDMENT 1 to the registration (2026-08-14, pre-run, no data collected).
+     * The four registered spans left this unattributed, and it is a per-FILE
+     * constant — measured at 0.72 ms/file, which is ~33% of T1's write phase and
+     * ~2% of T9's. Two consequences, both bad, both caught by running the
+     * instrument before the experiment: the registered tiling gate would have
+     * voided the cheapest rung, the one that anchors the exponent, while passing
+     * the rung where the answer is least in doubt; and folding it into `rest`
+     * instead would have contaminated `b_rest` — the PARTIAL condition — with a
+     * per-file constant that pulls any exponent toward 1.0, biasing PARTIAL
+     * toward not firing.
+     */
+    txn: number;
+    /**
+     * `structure.lock` acquisition and release, once per 16-file write batch.
+     *
+     * The only span not accumulated by {@link populateFile} — the indexer owns it,
+     * because the lock is per-BATCH and wraps the whole file loop (F1,
+     * `indexer/index.ts`). Named separately rather than folded in because the
+     * `phaseMs` docblock already warns that `write` includes lock wait and "must
+     * not be read as pure I/O under concurrency"; with this span that caveat
+     * becomes a number instead of a warning.
+     *
+     * AMENDMENT 1, same provenance as {@link WriteSpansMs.txn}.
+     */
+    lock: number;
+}
+/** A zeroed {@link WriteSpansMs} accumulator. */
+export declare function newWriteSpans(): WriteSpansMs;
+/**
+ * Optional per-call knobs for {@link populateFile}.
+ *
+ * An options object rather than more positional parameters: `chunkWriter` was
+ * the third argument, and the two additions here are both eval instruments that
+ * would otherwise have to be threaded past it in a fixed order.
+ */
+export interface PopulateFileOptions {
+    /** See {@link ChunkWriter} — test-only chunk-write substitution. */
+    readonly chunkWriter?: ChunkWriter;
+    /** When supplied, this call's four write regions are accumulated into it. */
+    readonly spans?: WriteSpansMs;
+    /**
+     * **Eval-only, and unsafe outside a cold build.** Skips the two
+     * `DELETE FROM *_fts WHERE file_path = ?` statements.
+     *
+     * This is E1-FTS's arm G — the causal test for whether those deletes carry
+     * the write phase's exponent, and a rehearsal of the fix (guarding them on
+     * whether the file was previously indexed, which the monotonic-guard SELECT
+     * below already knows).
+     *
+     * On a **cold** build the skipped deletes match zero rows, so the finished
+     * database is byte-identical to the control's — that identity is what makes
+     * arm G confound-free, and it is asserted both by
+     * `__tests__/write-spans.test.ts` and by a per-rung gate in the harness. On
+     * **any other** path it corrupts the index, leaving the previous version's
+     * FTS rows behind alongside the new ones while the ordinary tables replace
+     * correctly. The CLI therefore refuses to combine it with `--incremental`.
+     */
+    readonly skipFtsDeletes?: boolean;
+}
+/**
+ * Dedicated `busy_timeout` (ms) for {@link populateFile}'s own transaction —
+ * distinct from `graph.db`'s shared 5000ms connection default
+ * (`openDatabase`, `graph/db.ts`).
+ *
+ * F11 (`IMPLEMENTATION_PLAN.md` "Replace fail-fast advisory locking") moves
+ * this transaction from Kysely's deferred `BEGIN` to `BEGIN IMMEDIATE` (see
+ * `populateFile`'s doc comment for why) so it takes the write reservation up
+ * front instead of discovering contention via `SQLITE_BUSY_SNAPSHOT` on its
+ * own commit (F13). That makes the busy_timeout wait live for the first time
+ * on this path — under the inherited 5000ms default, ANY genuine contention
+ * would block better-sqlite3's synchronous busy-wait for up to 5 seconds,
+ * freezing the ENTIRE `mast serve` process (its native busy-wait blocks the
+ * whole event loop, not just the calling promise chain — measured directly in
+ * `eval/eventloop-probe.json`, see IMPLEMENTATION_PLAN.md's "HARD CONSTRAINT
+ * ON F11"). 200ms keeps that freeze window in the same neighbourhood as the
+ * 3x100ms `structure.lock` retry budget the JIT path used to pay instead of
+ * ever reaching SQLite's own wait (`mcp/staleness.ts`, pre-F11), rather than
+ * inheriting the 25x-longer 5000ms shared default. Set and restored only
+ * around this transaction's own exclusive connection window (see
+ * `populateFile`) so no unrelated statement on the shared connection ever
+ * inherits the short value.
+ */
+export declare const IMMEDIATE_WRITE_BUSY_TIMEOUT_MS = 200;
+/**
+ * Delete all rows for `filePath` from files, symbols, edges, imports,
+ * re_export_files (cascaded via FK), chunks, and FTS5 tables, then re-insert
+ * everything from `data` — all within a single SQLite transaction.
+ *
+ * M1 (`eval/GITNEXUS_COMPARISON.md` §15.1): chunk rows join this SAME
+ * transaction instead of being written by a separate chunk-store call before
+ * this function runs. That closes the consistency seam the spike deliberately
+ * left open — a chunk-store write succeeding while the graph write then fails
+ * (or vice versa) can no longer leave the two out of sync, because there is
+ * only one commit/rollback boundary for both.
+ *
+ * The two-pass structure (insert all symbols first, then insert all edges
+ * via `insertEdges`) is required for cross-file POTENTIAL_CALL resolution.
+ *
+ * **Monotonic write-guard (F12, `GITNEXUS_COMPARISON.md` Stage 1)**: refuses
+ * to replace a row whose stored `mtime` already exceeds `data.mtime`. Two
+ * writers can legitimately race to write the same file — a reindex batch and
+ * a concurrent JIT refresh (`mcp/staleness.ts`) both call this function.
+ * Without this guard, whichever writer commits LAST wins even if it parsed
+ * OLDER content — silently regressing the row. With it, the write carrying
+ * the NEWER stamp always wins, independent of arrival order, which is what
+ * actually makes the ordering guarantee in `runIndex`'s WHY-comment
+ * (`indexer/index.ts`) hold. This is strictly subject to mtime-granularity
+ * blindness (see that WHY-comment) — two writes landing in the same tick
+ * compare equal, not ordered, and whichever call happens second wins; that is
+ * a known, documented limitation, not something this guard claims to solve.
+ *
+ * **`BEGIN IMMEDIATE`, not a plain `db.transaction()` (F11)**: Kysely's
+ * better-sqlite3 driver only ever issues a deferred `BEGIN`
+ * (`sqlite-driver.js`'s `beginTransaction` — `CompiledQuery.raw('begin')`,
+ * hardcoded), and there is no config knob to change that. A deferred-BEGIN
+ * read-then-write (this function's own monotonic-guard SELECT, followed by
+ * its writes) can fail `SQLITE_BUSY_SNAPSHOT` in 1-2ms against ANY competing
+ * holder — even one that never commits — which `busy_timeout` cannot wait
+ * out, because the snapshot is already stale, not merely locked (F13,
+ * `eval/e7-round2.json`, 52 real occurrences). `BEGIN IMMEDIATE` takes the
+ * write reservation up front instead, eliminating that failure class and
+ * falling back to an honest bounded `busy_timeout` wait when genuinely
+ * contended (`eval/eventloop-probe.json` Phase 2/3). Since Kysely cannot be
+ * asked for `BEGIN IMMEDIATE` via `db.transaction()`, this function instead
+ * checks out the underlying connection exclusively via `db.connection()` and
+ * issues `begin immediate` / `commit` / `rollback` as raw statements around
+ * the same statement sequence a `db.transaction()` callback would have run.
+ * Kysely's SQLite adapter reports `supportsMultipleConnections: false`, so
+ * `RuntimeDriver` (`runtime-driver.js`) guards every connection acquisition
+ * on a given `Db` instance with one `ConnectionMutex` — verified by reading
+ * that source AND empirically (20 independently-staggered concurrent
+ * `db.connection().execute()` calls against one shared `Db`: zero
+ * interleaving errors, all 20 rows landed, in submission order). That means
+ * no OTHER statement issued through the SAME `Db` instance — chiefly a
+ * same-process concurrent JIT refresh of a different file, now that F11
+ * removes `structure.lock` from that path — can interleave into this
+ * transaction's raw `begin immediate` / ... / `commit` window. A genuinely
+ * different connection (reindex's own `openDatabase()` call in
+ * `indexer/index.ts`, or another `mast serve` process) is real SQLite-level
+ * concurrency, correctly governed by `BEGIN IMMEDIATE`'s write-reservation
+ * semantics and this transaction's own short `busy_timeout`
+ * ({@link IMMEDIATE_WRITE_BUSY_TIMEOUT_MS}), not by this in-process mutex.
+ */
+export declare function populateFile(db: Db, data: Omit<FileIndexData, 'edges'>, options?: PopulateFileOptions): Promise<PopulateFileResult>;
+/**
+ * Second-pass edge insertion. Run after ALL files' symbols have been inserted
+ * so cross-file references resolve correctly.
+ *
+ * Each `EdgeRecord` uses symbol names, which are resolved to IDs here.
+ * Unresolved names are silently skipped (external or not-yet-indexed).
+ */
+export declare function insertEdges(db: Db, filePath: string, edges: readonly EdgeRecord[]): Promise<void>;
+/**
+ * Second-pass star re-export insertion (`export * from './x'` → one
+ * `re_export_files` row per resolved target). Runs after all files' rows
+ * exist, like `insertEdges`, because the target file may be indexed later in
+ * the same run. Unresolved or unindexed targets are silently skipped.
+ */
+export declare function insertReExportFiles(db: Db, filePath: string, stars: readonly StarReExportRecord[]): Promise<void>;
+/**
+ * Remove all data for files that were present in the previous manifest but
+ * are absent from the current filesystem scan (deleted files). Returns the
+ * number of `chunks` rows removed (§ `IndexResult.chunksRemoved`).
+ *
+ * `chunks` (M1, §15.1) and the FTS5 virtual tables (chunk_fts, identifier_fts)
+ * do not participate in SQLite FK cascades, so all three must be cleaned up
+ * explicitly before the files row is deleted. Wrapped in one transaction so a
+ * deleted-file cleanup is atomic the same way `populateFile` is — a failure
+ * partway through cannot leave chunks/FTS rows orphaned from a `files` row
+ * that was (or wasn't) removed.
+ */
+export declare function removeDeletedFiles(db: Db, deletedPaths: readonly string[]): Promise<number>;
+//# sourceMappingURL=populate.d.ts.map

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

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