@spikedpunch/mast 0.1.0

package/dist/search/scope.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The scope a `mast_search` call is restricted to — `file_pattern` and
+ * `language` — compiled once and applied identically by every ranker.
+ *
+ * This module exists because the two filters used to be implemented in exactly
+ * one of the two rankers `fusedSearch` unions together: `searchFts` pushed
+ * them into SQL, `searchRankerD` applied none, and RRF then merged D's
+ * unscoped declaration hits into a scoped result set. That is this package's
+ * severity-zero shape (`docs/defects/LEDGER.md`) reached through the filter a
+ * caller supplied precisely to be sure of the answer's boundaries — so scope
+ * is defined here, once, rather than at each ranker's own SQL.
+ *
+ * Glob semantics come from {@link globToRegex}, the walker's own translation —
+ * the same function `mast_project_skeleton` already uses for its `file_pattern`
+ * and the same one that decides which files get indexed at all. A pattern
+ * therefore selects the same files at query time as it does at index time,
+ * which was not true of the SQL `LIKE` translation this replaces: under `LIKE`,
+ * `*` crossed `/`, a literal `_` acted as a single-character wildcard, and
+ * matching was case-insensitive against a case-sensitive index (the same three
+ * faults recorded in `docs/defects/D004-like-prefix-match.md`, whose four-site
+ * sweep did not reach here).
+ */
+import type { Db } from '../graph/db.js';
+/**
+ * The SQL-level filters `SearchInput` carries, in this module's own naming.
+ *
+ * `undefined` is spelled out alongside `null` because `exactOptionalPropertyTypes`
+ * is on: callers forward `SearchInput.file_pattern` (itself `string | null |
+ * undefined`) straight through, and an optional-only property would reject the
+ * explicit `undefined` that forwarding produces.
+ */
+export interface SearchScope {
+    readonly filePattern?: string | null | undefined;
+    readonly language?: string | null | undefined;
+}
+/** Predicate over one indexed row's `(file_path, language)` pair. */
+export type ScopeMatcher = (filePath: string, language: string) => boolean;
+/**
+ * Compile a scope into a single predicate, or `null` when the scope restricts
+ * nothing — callers branch on `null` to skip filtering entirely rather than
+ * running an always-true predicate over every candidate.
+ *
+ * The `RegExp` is built once here, not per row: `globToRegex` compiles a
+ * pattern, and doing that inside a filter callback would recompile it for
+ * every chunk in the candidate pool.
+ */
+export declare function compileScopeMatcher(scope: SearchScope): ScopeMatcher | null;
+/**
+ * The indexed paths inside `scope`, or `null` when the scope restricts nothing.
+ *
+ * Used by the callers that can only filter by path — FTS5 (whose `MATCH` query
+ * applies its `LIMIT` in SQL, so the restriction has to be an `IN` list rather
+ * than a post-filter) and the zero-result assist (two of whose three passes
+ * return only a symbol and a file). An empty array is a real answer, not an
+ * absent one: the scope matched no indexed file, so the search has nothing to
+ * return.
+ *
+ * `files` is scanned in full rather than filtered in SQL because the glob is
+ * not expressible as a SQL predicate without reintroducing `LIKE`. The table
+ * holds one row per indexed file, and the query it replaced —
+ * `path LIKE ?` against a `BINARY` index with `case_sensitive_like` OFF —
+ * could not use the index either (`graph/path-range.ts`), so this is not a
+ * plan regression.
+ */
+export declare function resolveScopedPaths(db: Db, scope: SearchScope): Promise<string[] | null>;
+//# sourceMappingURL=scope.d.ts.map

package/dist/search/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/search/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAC/C;AAED,qEAAqE;AACrE,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;AAE3E;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,GAAG,IAAI,CAW3E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAM7F"}

package/dist/search/scope.js

@@ -0,0 +1,71 @@
+/**
+ * The scope a `mast_search` call is restricted to — `file_pattern` and
+ * `language` — compiled once and applied identically by every ranker.
+ *
+ * This module exists because the two filters used to be implemented in exactly
+ * one of the two rankers `fusedSearch` unions together: `searchFts` pushed
+ * them into SQL, `searchRankerD` applied none, and RRF then merged D's
+ * unscoped declaration hits into a scoped result set. That is this package's
+ * severity-zero shape (`docs/defects/LEDGER.md`) reached through the filter a
+ * caller supplied precisely to be sure of the answer's boundaries — so scope
+ * is defined here, once, rather than at each ranker's own SQL.
+ *
+ * Glob semantics come from {@link globToRegex}, the walker's own translation —
+ * the same function `mast_project_skeleton` already uses for its `file_pattern`
+ * and the same one that decides which files get indexed at all. A pattern
+ * therefore selects the same files at query time as it does at index time,
+ * which was not true of the SQL `LIKE` translation this replaces: under `LIKE`,
+ * `*` crossed `/`, a literal `_` acted as a single-character wildcard, and
+ * matching was case-insensitive against a case-sensitive index (the same three
+ * faults recorded in `docs/defects/D004-like-prefix-match.md`, whose four-site
+ * sweep did not reach here).
+ */
+import { globToRegex } from '../indexer/walker.js';
+/**
+ * Compile a scope into a single predicate, or `null` when the scope restricts
+ * nothing — callers branch on `null` to skip filtering entirely rather than
+ * running an always-true predicate over every candidate.
+ *
+ * The `RegExp` is built once here, not per row: `globToRegex` compiles a
+ * pattern, and doing that inside a filter callback would recompile it for
+ * every chunk in the candidate pool.
+ */
+export function compileScopeMatcher(scope) {
+    const pattern = scope.filePattern ?? null;
+    const language = scope.language ?? null;
+    if (pattern === null && language === null)
+        return null;
+    const rx = pattern === null ? null : globToRegex(pattern);
+    return (filePath, rowLanguage) => {
+        if (rx !== null && !rx.test(filePath))
+            return false;
+        if (language !== null && rowLanguage !== language)
+            return false;
+        return true;
+    };
+}
+/**
+ * The indexed paths inside `scope`, or `null` when the scope restricts nothing.
+ *
+ * Used by the callers that can only filter by path — FTS5 (whose `MATCH` query
+ * applies its `LIMIT` in SQL, so the restriction has to be an `IN` list rather
+ * than a post-filter) and the zero-result assist (two of whose three passes
+ * return only a symbol and a file). An empty array is a real answer, not an
+ * absent one: the scope matched no indexed file, so the search has nothing to
+ * return.
+ *
+ * `files` is scanned in full rather than filtered in SQL because the glob is
+ * not expressible as a SQL predicate without reintroducing `LIKE`. The table
+ * holds one row per indexed file, and the query it replaced —
+ * `path LIKE ?` against a `BINARY` index with `case_sensitive_like` OFF —
+ * could not use the index either (`graph/path-range.ts`), so this is not a
+ * plan regression.
+ */
+export async function resolveScopedPaths(db, scope) {
+    const matcher = compileScopeMatcher(scope);
+    if (matcher === null)
+        return null;
+    const rows = await db.selectFrom('files').select(['path', 'language']).execute();
+    return rows.filter((r) => matcher(r.path, r.language)).map((r) => r.path);
+}
+//# sourceMappingURL=scope.js.map

package/dist/search/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/search/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAmBnD;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAkB;IACpD,MAAM,OAAO,GAAG,KAAK,CAAC,WAAW,IAAI,IAAI,CAAC;IAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC;IACxC,IAAI,OAAO,KAAK,IAAI,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvD,MAAM,EAAE,GAAG,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC1D,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE;QAC/B,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QACpD,IAAI,QAAQ,KAAK,IAAI,IAAI,WAAW,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAChE,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EAAM,EAAE,KAAkB;IACjE,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACjF,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAC5E,CAAC"}

package/dist/store/config.d.ts

@@ -0,0 +1,57 @@
+import type { MastConfig } from '../ast/types.js';
+export declare const CURRENT_SCHEMA_VERSION = "1.3.0";
+export interface ResolvedConfig extends MastConfig {
+    /** Absolute path to the state directory. */
+    readonly resolved_state_dir: string;
+    /** Absolute path to the project root. */
+    readonly resolved_project_root: string;
+}
+export interface ResolveConfigOptions {
+    /** Absolute or relative path to project root (default: cwd). */
+    projectRoot?: string;
+    /**
+     * Overrides state_dir from config file.
+     * Falls back to MAST_STATE_DIR env var, then mast.config.json, then default.
+     */
+    stateDirOverride?: string;
+    /**
+     * Explicit override for `file_extensions` (F9, `mast init --extensions`).
+     * Highest priority in the config merge — wins over `mast.config.json` and
+     * any persisted `<state_dir>/config.json`.
+     */
+    extensions?: readonly string[];
+    /**
+     * Explicit override for `exclude_patterns` (F9, `mast init --exclude`).
+     * Same priority as `extensions`.
+     */
+    excludePatterns?: readonly string[];
+}
+/**
+ * Resolve the active MAST configuration.
+ *
+ * State-directory priority order (highest to lowest) — unchanged by F9,
+ * because the state dir must be resolved BEFORE the persisted state config
+ * can be loaded from inside it:
+ * 1. `stateDirOverride` (CLI `--state-dir` flag)
+ * 2. `MAST_STATE_DIR` environment variable
+ * 3. `state_dir` key in `mast.config.json`
+ * 4. Built-in default (`.mast`)
+ *
+ * Priority order for every other config key (highest to lowest):
+ * 1. Explicit overrides passed to this function (`extensions`/`excludePatterns`
+ *    — CLI `mast init --extensions`/`--exclude`, F9)
+ * 2. `mast.config.json` in `projectRoot`
+ * 3. Persisted `<resolved_state_dir>/config.json` (F9 — previously write-only
+ *    dead state; see `pickStateConfigCustomization` for why only the
+ *    customisation keys are taken from it, never the path keys)
+ * 4. Built-in defaults
+ */
+export declare function resolveConfig(options?: ResolveConfigOptions): ResolvedConfig;
+/**
+ * Load a previously-written config.json from the state directory.
+ * Returns null if the file does not exist.
+ */
+export declare function loadStateConfig(stateDir: string): Partial<MastConfig> | null;
+/** Write the resolved config to `<stateDir>/config.json`. */
+export declare function writeStateConfig(stateDir: string, config: ResolvedConfig): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/store/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/store/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA4BlD,eAAO,MAAM,sBAAsB,UAAU,CAAC;AA+B9C,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,4CAA4C;IAC5C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,yCAAyC;IACzC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;OAGG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAgFD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,cAAc,CA0ChF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAI5E;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAG/E"}

package/dist/store/config.js

@@ -0,0 +1,208 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { ConfigEnvSchema } from '../env.js';
+// 1.3.0 (F5, Stage 3): identifier_fts rows now carry QUALIFIED compound
+// strings ("Class.method") appended after the bare-identifier bag — see
+// ast/extractors/typescript.ts's `appendQualifiedCompounds` and MAST_SPEC.md
+// §6.3. This is a CONTENT-format change to an already-existing column, not a
+// new column, so a schema-diff check would not catch it: an old index's
+// identifier_fts rows lack the compounds entirely, and `searchIdentifiers`'
+// phrase query for a qualified method name would silently keep returning []
+// against that stale state — exactly the class of wrong-version hazard §7.4's
+// migration guard exists for (a confidently-empty answer, not an error).
+// Bumping forces the §7.4 Step 2 wipe-and-full-reindex path, verified by
+// mcp/__tests__/startup.test.ts's schema-mismatch coverage; the Docker seed
+// (§7.4) picks up the new format automatically on its next build since it
+// reindexes from a version-tagged image rather than reusing a mounted volume.
+//
+// 1.2.0: chunks moved from chunks.lance to a `chunks` table inside graph.db
+// (M1, eval/GITNEXUS_COMPARISON.md §15.1) — the on-disk shape changed (a new
+// SQLite table plus the retired Lance chunk table) so old state must not be
+// read by code expecting the new layout. Per the never-shipped constraint
+// (no customers, no migration data to preserve) the §7.4 Step 2 wipe-and-full-
+// reindex path is the correct and sufficient handling, verified by
+// mcp/__tests__/startup.test.ts's schema-mismatch coverage.
+//
+// 1.1.0: vectors.lance gained a `content_hash` column so re-embedding is keyed
+// on chunk content, not just chunk_id (H1). A bump forces the §7.4 Step 2 wipe
+// so an old vectors table (without the column) is rebuilt rather than read.
+export const CURRENT_SCHEMA_VERSION = '1.3.0';
+const DEFAULTS = {
+    state_dir: '.mast',
+    project_root: '.',
+    // `.md` rides the existing exclude_patterns for vendored noise — dependency
+    // READMEs live under node_modules/** which is already excluded; no
+    // markdown-specific exclusion logic is applied.
+    file_extensions: ['.ts', '.tsx', '.js', '.jsx', '.md'],
+    // Build output, dependencies, and tests. `.mast/**` excludes this tool's own
+    // state directory, which is the one path guaranteed to exist in every project
+    // that runs it. (`.kluster/**` sat here until 2026-08-19 — a leftover from the
+    // repository mast was extracted from, meaningless to any other consumer.)
+    exclude_patterns: [
+        '**/node_modules/**',
+        '**/dist/**',
+        '**/build/**',
+        '**/coverage/**',
+        '**/.next/**',
+        '**/.turbo/**',
+        '.mast/**',
+        '**/*.test.ts',
+        '**/*.spec.ts',
+    ],
+    rrf_k: 60,
+    declaration_exact_ranker: true,
+    chunk_split_threshold: 100,
+    context_lines: 3,
+    markdown_heading_depth: 2,
+};
+// F9 (Stage 3.5, eval/GITNEXUS_COMPARISON.md M3): the keys a caller may
+// customise, as opposed to the path keys (`state_dir`, `project_root`,
+// `resolved_state_dir`, `resolved_project_root`) that describe WHERE this
+// resolution is running, not WHAT it configures. Used by
+// `pickStateConfigCustomization` below to build an explicit picked-keys
+// merge — never a spread-minus-deletes — so a path key can never leak in
+// through this list by omission.
+const CUSTOMIZATION_KEYS = [
+    'file_extensions',
+    'exclude_patterns',
+    'rrf_k',
+    'declaration_exact_ranker',
+    'chunk_split_threshold',
+    'context_lines',
+    'markdown_heading_depth',
+];
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+/**
+ * Picks ONLY the customisation keys out of a persisted `<state_dir>/config.json`
+ * — never `state_dir`/`project_root`/`resolved_state_dir`/`resolved_project_root`.
+ *
+ * WHY this matters (path-portability hazard): `writeStateConfig` persists a
+ * full `ResolvedConfig`, including ABSOLUTE paths resolved in a PREVIOUS
+ * process. The SDD pipeline mounts the same workspace volume at different
+ * container paths across runs, so an absolute path loaded back from a
+ * previous container would silently resolve `resolved_state_dir` /
+ * `resolved_project_root` to a location that doesn't exist (or worse, exists
+ * but belongs to an unrelated project) in THIS container. Every path field
+ * in the returned `ResolvedConfig` must always come from the CURRENT
+ * resolution — never from disk.
+ *
+ * Unlike `mast.config.json` (see the precedent comment on `resolveConfig`
+ * below, which trusts a plain `JSON.parse` cast because that file is
+ * developer-authored and colocated with source control), a state
+ * config.json is machine-written but crosses a trust boundary of its own —
+ * an arbitrary file on disk that could be stale, foreign, or hand-edited.
+ * Each picked key is minimally validated by shape (string array / number /
+ * boolean) rather than trusted on cast; a key that fails validation is
+ * dropped so DEFAULTS (or a lower-priority layer) fills it in instead of a
+ * malformed value silently propagating.
+ */
+function pickStateConfigCustomization(source) {
+    if (source === null)
+        return {};
+    // `MastConfig`'s fields are `readonly` (immutable once constructed), but
+    // this function BUILDS one field at a time — a mutable local view keeps
+    // the assignments below straightforward. The returned value still exposes
+    // the standard `Partial<MastConfig>` (readonly) shape to callers.
+    const picked = {};
+    if (isStringArray(source.file_extensions))
+        picked.file_extensions = source.file_extensions;
+    if (isStringArray(source.exclude_patterns))
+        picked.exclude_patterns = source.exclude_patterns;
+    if (typeof source.rrf_k === 'number')
+        picked.rrf_k = source.rrf_k;
+    if (typeof source.declaration_exact_ranker === 'boolean') {
+        picked.declaration_exact_ranker = source.declaration_exact_ranker;
+    }
+    if (typeof source.chunk_split_threshold === 'number')
+        picked.chunk_split_threshold = source.chunk_split_threshold;
+    if (typeof source.context_lines === 'number')
+        picked.context_lines = source.context_lines;
+    if (typeof source.markdown_heading_depth === 'number') {
+        picked.markdown_heading_depth = source.markdown_heading_depth;
+    }
+    // Safety net for the path-portability rule above: fails loudly if a future
+    // edit to this function ever assigns a key outside CUSTOMIZATION_KEYS (e.g.
+    // a path key re-added by accident) instead of silently reintroducing the
+    // shared-volume hazard this function exists to prevent.
+    for (const key of Object.keys(picked)) {
+        if (!CUSTOMIZATION_KEYS.includes(key)) {
+            throw new Error(`pickStateConfigCustomization: unexpected key "${key}" outside CUSTOMIZATION_KEYS`);
+        }
+    }
+    return picked;
+}
+/**
+ * Resolve the active MAST configuration.
+ *
+ * State-directory priority order (highest to lowest) — unchanged by F9,
+ * because the state dir must be resolved BEFORE the persisted state config
+ * can be loaded from inside it:
+ * 1. `stateDirOverride` (CLI `--state-dir` flag)
+ * 2. `MAST_STATE_DIR` environment variable
+ * 3. `state_dir` key in `mast.config.json`
+ * 4. Built-in default (`.mast`)
+ *
+ * Priority order for every other config key (highest to lowest):
+ * 1. Explicit overrides passed to this function (`extensions`/`excludePatterns`
+ *    — CLI `mast init --extensions`/`--exclude`, F9)
+ * 2. `mast.config.json` in `projectRoot`
+ * 3. Persisted `<resolved_state_dir>/config.json` (F9 — previously write-only
+ *    dead state; see `pickStateConfigCustomization` for why only the
+ *    customisation keys are taken from it, never the path keys)
+ * 4. Built-in defaults
+ */
+export function resolveConfig(options = {}) {
+    const resolvedProjectRoot = resolve(options.projectRoot ?? process.cwd());
+    const configFile = join(resolvedProjectRoot, 'mast.config.json');
+    // Never-shipped ⇒ no back-compat (IMPLEMENTATION_PLAN.md Stage 7 decision
+    // 2): a `mast.config.json` written before Stage 7.2 may still carry the
+    // removed embedding-model / Transformers.js cache-dir config keys. Nothing
+    // here validates the parsed shape (plain JSON.parse + cast, no zod) — this
+    // file is developer-authored and colocated with source control, unlike the
+    // machine-written state config.json below which DOES get minimal shape
+    // validation (see `pickStateConfigCustomization`). Those extra keys just
+    // ride along on `fileConfig`/`merged` unread — the spread below never looks
+    // them up, and `writeStateConfig` re-persisting `merged` via
+    // `JSON.stringify` carries them along harmlessly too.
+    let fileConfig = {};
+    if (existsSync(configFile)) {
+        const raw = readFileSync(configFile, 'utf-8');
+        fileConfig = JSON.parse(raw);
+    }
+    // State dir chain is resolved first and independently of the customisation
+    // merge below — see the priority-order doc comment above.
+    const { MAST_STATE_DIR: envStateDir } = ConfigEnvSchema.parse(process.env);
+    const stateDir = options.stateDirOverride ?? envStateDir ?? fileConfig.state_dir ?? DEFAULTS.state_dir;
+    const resolvedStateDir = resolve(resolvedProjectRoot, stateDir);
+    const stateConfig = pickStateConfigCustomization(loadStateConfig(resolvedStateDir));
+    const cliOverrides = {
+        ...(options.extensions !== undefined ? { file_extensions: options.extensions } : {}),
+        ...(options.excludePatterns !== undefined ? { exclude_patterns: options.excludePatterns } : {}),
+    };
+    const merged = { ...DEFAULTS, ...stateConfig, ...fileConfig, ...cliOverrides };
+    return {
+        ...merged,
+        state_dir: stateDir,
+        project_root: resolvedProjectRoot,
+        resolved_state_dir: resolvedStateDir,
+        resolved_project_root: resolvedProjectRoot,
+    };
+}
+/**
+ * Load a previously-written config.json from the state directory.
+ * Returns null if the file does not exist.
+ */
+export function loadStateConfig(stateDir) {
+    const configPath = join(stateDir, 'config.json');
+    if (!existsSync(configPath))
+        return null;
+    return JSON.parse(readFileSync(configPath, 'utf-8'));
+}
+/** Write the resolved config to `<stateDir>/config.json`. */
+export function writeStateConfig(stateDir, config) {
+    mkdirSync(stateDir, { recursive: true });
+    writeFileSync(join(stateDir, 'config.json'), JSON.stringify(config, null, 2));
+}
+//# sourceMappingURL=config.js.map

package/dist/store/config.js.map

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

package/dist/store/lock.d.ts

@@ -0,0 +1,101 @@
+import { type LockMetricsSink } from './lockMetrics.js';
+export type LockType = 'structure';
+/**
+ * Thrown when the lock was taken away while this process still believed it
+ * held it — another process judged it stale and stole it, or the lock
+ * directory was removed underneath us.
+ *
+ * It is thrown at RELEASE, not when the compromise is detected, because
+ * proper-lockfile detects it inside an `fs.stat` callback on a timer: there is
+ * no caller on the stack to receive it there, which is exactly why the
+ * library's default handler (`onCompromised: (err) => { throw err; }`,
+ * `lib/lockfile.js`) reached the process as an uncaught exception and killed
+ * it — measured: `ECOMPROMISED ENOENT`, exit code 7, with no
+ * `uncaughtException` handler anywhere in `src`.
+ *
+ * **What this does and does not fix.** It converts a process kill into a
+ * failed operation the caller can retry, and it stops a run that was not
+ * exclusive from reporting success. It does NOT stop the work already in
+ * flight: by the time the compromise is detected, `fn` is mid-execution and
+ * nothing here can interrupt it. Doing that needs an `AbortSignal` threaded
+ * through `withLock` and honoured by every write phase, which is a design
+ * change, not a patch. The exposure is bounded: SQLite writes go through
+ * `populateFile`'s `BEGIN IMMEDIATE` transaction and stay serialised whatever
+ * this advisory lock believes, so what is actually at risk is the plain-JSON
+ * `file_manifest.json` / `index.json` writes this lock exists to coordinate —
+ * and a run that fails here is re-run, which rewrites both.
+ */
+export declare class LockCompromisedError extends Error {
+    /** The underlying proper-lockfile error (`ECOMPROMISED`). */
+    readonly reason: unknown;
+    constructor(type: LockType, reason: unknown);
+}
+/**
+ * Ensure the marker files required by proper-lockfile exist in `stateDir`.
+ * Must be called during `mast init` before any lock can be acquired.
+ */
+export declare function initLockMarkers(stateDir: string): void;
+export interface AcquireOptions {
+    /** Number of additional retries after the first attempt (default: 5). */
+    maxRetries?: number;
+    /** Milliseconds between retries (default: 1000). */
+    retryIntervalMs?: number;
+    /**
+     * Label identifying the calling workflow in lock metrics (e.g.
+     * `'index-run'`, `'jit-staleness'`) — the signal that distinguishes a
+     * whole-run hold from a per-file JIT re-parse. Defaults to `'unknown'`.
+     */
+    caller?: string;
+    /**
+     * Injection seam (§4.4) for lock metrics — tests pass an in-memory fake so
+     * they can assert on recorded events without touching the filesystem.
+     * Production call sites omit this and get the default JSONL sink for
+     * `stateDir` (see {@link createFileLockMetricsSink}).
+     */
+    sink?: LockMetricsSink;
+    /**
+     * Override the staleness window (default {@link STALE_MS}). proper-lockfile
+     * derives its refresh interval as `stale / 2`, so this is the only way to
+     * make a compromise observable inside a test's patience — production call
+     * sites never set it.
+     */
+    staleMs?: number;
+}
+/**
+ * Acquire an advisory write lock for the given lock type.
+ *
+ * Returns a release function. Always `await release()` in a finally block.
+ * The returned function is wrapped to record hold-duration lock metrics on
+ * release — this covers direct callers as well as callers that go through
+ * {@link withLock}.
+ *
+ * Per spec §7.6:
+ * - CLI commands: maxRetries=1, retryIntervalMs=2000 (2s total)
+ * - mast_reindex / mast serve startup: maxRetries=5, retryIntervalMs=1000
+ *
+ * **F11 (`IMPLEMENTATION_PLAN.md` "Replace fail-fast advisory locking")
+ * narrowed this lock's role**: the JIT re-parse path (`mcp/staleness.ts`'s
+ * `checkAndRefreshIfStale`) no longer calls `acquireLock` at all — it relies
+ * on `populateFile`'s own `BEGIN IMMEDIATE` transaction
+ * (`graph/populate.ts`) plus a dedicated short `busy_timeout` instead. This
+ * lock is now acquired only by coarse writers: `mast index` / the startup
+ * reindex, `mast_reindex`, and the manifest/`index.json` phase (plain-JSON
+ * `writeFileSync`, which SQLite can never coordinate) — see `populateFile`'s
+ * doc comment for the full design rationale.
+ *
+ * @throws if the lock cannot be acquired after all retries.
+ */
+export declare function acquireLock(stateDir: string, type: LockType, options?: AcquireOptions): Promise<() => Promise<void>>;
+/**
+ * Run `fn` while holding the given lock.
+ *
+ * The lock's directory is tracked in a process-wide registry that a single
+ * SIGTERM/SIGINT handler cleans up on shutdown, so an interrupted process does
+ * not leave `<type>.lock` behind for every lock it held.
+ *
+ * @throws {LockCompromisedError} if the lock was taken away while `fn` ran.
+ *   `fn` still completed — see that error's doc for what is and is not
+ *   guaranteed. If `fn` itself threw, that error is thrown instead.
+ */
+export declare function withLock<T>(stateDir: string, type: LockType, options: AcquireOptions, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=lock.d.ts.map

package/dist/store/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/store/lock.ts"],"names":[],"mappings":"AAGA,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAMnF,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC;AAInC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO;CAQ5C;AAOD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAKtD;AAED,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAiD9B;AAyBD;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,cAAc,EACvB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CA4BZ"}