@spikedpunch/mast 0.1.0

package/dist/indexer/import-resolver.js.map

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

package/dist/indexer/index.d.ts

@@ -0,0 +1,249 @@
+import type { ResolvedConfig } from '../store/config.js';
+import type { LockMetricsSink } from '../store/lockMetrics.js';
+import { type ChunkStore } from '../store/sqliteChunkStore.js';
+import { type OpenDatabaseOptions } from '../graph/db.js';
+import type { WriteSpansMs } from '../graph/populate.js';
+import { extractFile } from '../ast/extract.js';
+import { type MiscasedImportReport } from './import-resolver.js';
+import type { IndexMeta, FreshnessCause } from '../ast/types.js';
+export interface IndexResult {
+    readonly filesIndexed: number;
+    readonly filesSkipped: number;
+    readonly chunksAdded: number;
+    readonly chunksRemoved: number;
+    readonly parseErrors: number;
+    /**
+     * Files whose chunk-store write failed. Distinct from `parseErrors` — the
+     * file parsed fine but its chunks/symbols/edges/imports/FTS rows were never
+     * written (GITNEXUS_COMPARISON.md §15.3 item 3: a storage failure must
+     * never be counted as a parse failure).
+     */
+    readonly writeErrors: number;
+    /**
+     * Files whose write was refused by `populateFile`'s monotonic write-guard
+     * (F12) because the stored row already carried a NEWER mtime than this
+     * run's parse — an older-stamped write losing a race against a fresher one
+     * (typically a concurrent JIT refresh, `mcp/staleness.ts`). The DB is
+     * correct in this case; this counter exists only so the rejection is
+     * visible instead of silently indistinguishable from an ordinary write
+     * (mirrors `writeErrors`'s precedent).
+     */
+    readonly staleWriteRejections: number;
+    /**
+     * Imports that resolved only because the filesystem ignored their casing.
+     *
+     * A defect in the INDEXED repository rather than in MAST: the specifier is
+     * spelled differently from the file on disk, which compiles on APFS/NTFS and
+     * fails on a case-sensitive filesystem. MAST resolves such an import to the
+     * on-disk path, so the edge is correct either way; this exists so the
+     * anomaly is visible rather than silent, on the same reasoning as
+     * `staleWriteRejections`.
+     */
+    readonly miscasedImports: MiscasedImportReport;
+    readonly durationMs: number;
+    /**
+     * The `cache_size` / `mmap_size` actually in force on this run's connection,
+     * read back from SQLite itself immediately before the handle is closed.
+     *
+     * Keyed by the pragma's own names rather than the codebase's camelCase
+     * because these are SQLite's values echoed verbatim, not a MAST-side model of
+     * them — the whole point is that nothing between the pragma and this field
+     * reinterprets anything. `cache_size` is negative when denominated in KiB.
+     *
+     * Exists so the E1-PHASE mechanism A/B can prove its arms differed. Both
+     * pragmas are connection-scoped, so they vanish when the process exits and
+     * cannot be recovered from the database file afterwards; if the run does not
+     * report them, no later inspection can. Same evidentiary role as Gate 0's
+     * `dist` content hash: it establishes WHICH configuration produced a timing,
+     * rather than leaving it to be assumed from the command line that was meant
+     * to be issued.
+     */
+    readonly appliedPragmas: {
+        readonly cache_size: number;
+        readonly mmap_size: number;
+    };
+    /**
+     * Cumulative wall-clock per phase, in ms. The phases tile the run: their sum is
+     * `durationMs` less a small unattributed remainder.
+     *
+     * The remainder is `db.destroy()` and the return — NOT `openDatabase`, which runs before
+     * the `walk` stamp and is therefore inside `walk` (and inside the calibration constant
+     * `c`, per A4-C1). This matters because `db.destroy()` closes the last connection, which
+     * triggers WAL's close-time checkpoint: the one size-coupled cost outside every phase.
+     * E1-PHASE reports the remainder as its own series rather than treating it as slack.
+     *
+     * Exists because E1 measured a growth exponent of ~1.75 on the nested ladder — ~1.90
+     * over its upper half — from `durationMs` alone, which localises the cost to the run and
+     * no further. The candidate mechanisms are distinguishable only by phase: a page-cache
+     * cliff loads `write` while `parse` stays linear; call/symbol resolution loads `edges`;
+     * FTS5 segment-merge cost loads `write` but scales with chunks rather than with database
+     * size. Reported so a scaling run can discriminate them instead of guessing.
+     *
+     * `write` and `edges` include the time spent waiting for `structure.lock`, which is
+     * correct for a scaling measurement (a cold build contends with nothing) but must not be
+     * read as pure I/O under concurrency.
+     */
+    readonly phaseMs: {
+        /** Project walk and manifest diff — everything before the first parse batch. */
+        readonly walk: number;
+        /** Pass 1, unlocked: tree-sitter extraction. Expected to be linear in bytes. */
+        readonly parse: number;
+        /** Pass 1, locked: `populateFile` — chunks + symbols + imports + FTS, per file. */
+        readonly write: number;
+        /** Pass 2, locked: edge and star-re-export insertion once every symbol row exists. */
+        readonly edges: number;
+        /** Final phase: re-stat, manifest write, `index.json`. */
+        readonly finalise: number;
+    };
+}
+export interface IndexOptions {
+    /** When true, only reindex files whose mtime changed since the last run. */
+    readonly incremental: boolean;
+    /** Called after each file is processed (parse phase) with running and total counts. */
+    readonly onProgress?: (processed: number, total: number) => void;
+    /**
+     * Test-only injection point (§4.4 DI): a fake `ChunkStore` used for chunk
+     * reads (`isFileUnchanged`, the final `chunkCount()`) and, via
+     * `populateFile`'s `chunkWriter` param, for the per-file chunk WRITE too —
+     * see `graph/populate.ts`'s `ChunkWriter` docstring for why a rejection
+     * from the override still rolls back the whole per-file transaction.
+     * Lets write-failure tests (`indexer/__tests__/write-failures.test.ts`)
+     * exercise write-failure handling without a real SQLite backend. `runIndex`
+     * never destroys an injected override — the caller owns its lifecycle.
+     */
+    readonly chunkStoreOverride?: ChunkStore;
+    /**
+     * Test-only injection point (§4.4 DI): overrides the per-file extraction
+     * step used in the parse phase. Lets tests simulate a slow parse (e.g. to
+     * create a deterministic multi-batch window for exercising the per-batch
+     * `structure.lock` scope — F1, GITNEXUS_COMPARISON.md §13.2) without
+     * sleeping the whole test suite. Defaults to the real `extractFile`.
+     */
+    readonly extractFileFn?: typeof extractFile;
+    /**
+     * Test-only injection point (§4.4 DI): routes this run's `structure.lock`
+     * acquire/release events to a fake sink instead of the default
+     * `<stateDir>/lock-metrics.jsonl` file (store/lockMetrics.ts), so tests can
+     * assert on lock-hold count/duration structurally without touching the
+     * filesystem. Production call sites omit this and get the default sink.
+     */
+    readonly lockMetricsSink?: LockMetricsSink;
+    /**
+     * Per-connection SQLite tuning for this run's `graph.db` handle
+     * (`OpenDatabaseOptions`, `graph/db.ts`). Omitted everywhere in product code;
+     * it exists so the E1-PHASE mechanism A/B can vary `cache_size` / `mmap_size`
+     * between arms without config or environment acting as a hidden lever.
+     */
+    readonly dbOptions?: OpenDatabaseOptions;
+    /**
+     * When supplied, every `populateFile` call in this run accumulates its four
+     * write regions into this record (`graph/populate.ts`'s {@link WriteSpansMs}).
+     *
+     * Omitted everywhere in product code. It exists so E1-FTS can decompose the
+     * `write` phase that E1-PHASE showed carries the growth exponent; passing
+     * nothing means no clock is read at all, so the production path is unchanged.
+     */
+    readonly writeSpans?: WriteSpansMs;
+    /**
+     * **Eval-only, and unsafe outside a cold build** — see
+     * {@link PopulateFileOptions.skipFtsDeletes} for what it does and why it
+     * corrupts an incremental index. E1-FTS's arm G.
+     */
+    readonly unsafeSkipFtsDeletes?: boolean;
+}
+/**
+ * Walk the project, parse changed files into chunks, populate the graph
+ * database and FTS indexes.
+ *
+ * F1 (GITNEXUS_COMPARISON.md §13.2, MAST_SPEC.md:822-826): `structure.lock`
+ * is acquired and released separately for each write phase — deleted-file
+ * cleanup, each `LANCE_BATCH`-sized write batch, each edge-insertion batch,
+ * and the final manifest/index.json write — instead of once for the whole
+ * run. The read-only walk and the CPU-bound parse phase never hold the lock
+ * at all. Before this change the lock was held for the run's full duration
+ * (measured max: 280,782 ms on a 1,335-file corpus — eval/baseline-locks.json),
+ * which starved the JIT re-parse path (mcp/staleness.ts:56, 3 retries x
+ * 100 ms) for minutes at a time — directly contradicting MAST_SPEC.md:822-826
+ * ("lock holding is per-file-parse (10-50ms), not per-tool-call").
+ *
+ * Narrowing the lock's scope means a JIT re-parse can now interleave BETWEEN
+ * phases of an in-flight run. Two invariants keep that safe:
+ *
+ * 1. **[F12, `GITNEXUS_COMPARISON.md` Stage 1]** The row's stamped mtime must
+ *    never be NEWER than the content it is stamped against — i.e.
+ *    `stamp <= mtime-at-content-read`. This is an ORDERING property, not a
+ *    mutual-exclusion one: no lock can enforce it, because a file's editor
+ *    never takes `structure.lock`. An earlier version of this invariant
+ *    re-stat'd each file AFTER `doExtract` (inside the locked write phase) to
+ *    stop `files.mtime` *regressing* below `entry.mtime` — but that opened
+ *    the real hazard: an edit landing in the (unlocked, seconds-wide under
+ *    §15.2's FTS growth) parse-to-write window would be stamped with a mtime
+ *    NEWER than the content that was actually parsed, permanently disarming
+ *    staleness detection for that file (`diskMtime <= storedMtime` reads
+ *    "fresh" forever — the exact P0 class this stage exists to eliminate).
+ *    The fix stats each file IMMEDIATELY BEFORE `doExtract`, in the parse
+ *    loop below (unlocked, same as `mcp/staleness.ts`'s JIT path, which has
+ *    always done this correctly), and carries that pre-parse stamp through to
+ *    the write untouched — no re-stat at write time. A post-stat edit then
+ *    leaves stamp < content, so staleness re-fires on the next check and the
+ *    system self-heals, the same property the JIT path already had.
+ * 2. **Monotonic write-guard, `graph/populate.ts`'s `populateFile`**: even
+ *    with (1), two writers (e.g. this run's batch write and a concurrent JIT
+ *    refresh of the same file) can still race to write the SAME row with
+ *    DIFFERENT stamps, and `structure.lock` only serializes the two writes —
+ *    it does not guarantee the one with the fresher stamp wins. `populateFile`
+ *    refuses to replace a row whose stored mtime already exceeds the incoming
+ *    stamp, so whichever write carries the NEWER stamp wins regardless of
+ *    which one reaches the lock first — fixing the reindex-vs-JIT race
+ *    *better* than the lock alone does (the lock only serializes; the guard
+ *    orders).
+ *
+ * Known limitation (not solved here): mtime-granularity blindness. An edit
+ * landing in the SAME mtime tick as the stamp compares equal, not greater,
+ * and reads as fresh (the git racy-lstat problem). Near-moot on APFS's
+ * nanosecond-resolution mtimes; real on coarse-mtime volumes (e.g. some
+ * shared/network filesystems), which is exactly the container-deployment
+ * case MAST_SPEC.md §7.6 targets. Solving it properly means content hashing,
+ * not mtime comparison, and is out of scope for F12.
+ *
+ * `file_manifest.json` (which drives the NEXT run's incremental diff, see
+ * `diffManifest`) is rebuilt from a fresh re-stat of every file under the
+ * FINAL lock acquisition (below), not from the run-start walk snapshot or
+ * from the parse-phase stamps above. This one does NOT need invariant 1's
+ * fix: it is a stat with no accompanying content read in this final phase, so
+ * there is no stamp/content pair to invert. If it ever disagrees with
+ * `files.mtime` for a file JIT touched concurrently, that disagreement
+ * self-heals on the next JIT check (`checkAndRefreshIfStale` compares disk
+ * mtime, not the manifest, against `files.mtime`) — the manifest only feeds
+ * the NEXT run's `diffManifest`, and a stale manifest entry there causes an
+ * extra, harmless re-parse, never a missed one.
+ *
+ * The two-pass edge-insertion structure (`insertEdges` needs every file's
+ * symbols already present) is preserved: ALL pass-1 batches — across the
+ * whole run, not just the current batch — complete before pass 2 starts, so
+ * cross-file edge targets are always resolvable regardless of how finely
+ * pass 1's own lock acquisitions are chunked.
+ */
+export declare function runIndex(config: ResolvedConfig, options: IndexOptions): Promise<IndexResult>;
+/**
+ * Derive the `freshness_cause` discriminator (§9 mast_status) from the stale
+ * file count. Stage 7.2 (IMPLEMENTATION_PLAN.md "Stage 7: Vector-store
+ * deletion") dropped the second parameter this used to take
+ * (`pendingEmbeddings`) along with the `'embedding_backlog'`/`'both'` cases —
+ * the Phase 2 embedder that could produce a backlog distinct from Phase 1
+ * staleness was excised in Stage 7.1, so a two-cause signature asserted a
+ * distinction the code could no longer draw.
+ */
+export declare function freshnessCause(staleFiles: number): FreshnessCause;
+/**
+ * Load `index.json` from the state directory, or return null if absent.
+ *
+ * Unvalidated cast, not a zod parse — an `index.json` written before Stage
+ * 7.2 (IMPLEMENTATION_PLAN.md "Stage 7: Vector-store deletion") may still
+ * carry the removed `model` field; it rides along as an untyped extra key
+ * and is simply never read, so old files load without error.
+ */
+export declare function loadIndexMeta(stateDir: string): IndexMeta | null;
+/** Write `index.json` to the state directory. */
+export declare function writeIndexMeta(stateDir: string, meta: IndexMeta): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/indexer/index.d.ts.map

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