@aroman22/codegraph-vba 1.5.2 → 1.6.0

package/README.md

@@ -281,7 +281,7 @@ The reliable, universal payoff is **surgical context and speed**: CodeGraph coll
 | **Full-Text Search** | Find code by name instantly across your entire codebase, powered by FTS5 |
 | **Impact Analysis** | Trace callers, callees, and the full impact radius of any symbol before making changes |
 | **Always Fresh** | File watcher uses native OS events (FSEvents/inotify/ReadDirectoryChangesW) with debounced auto-sync — the graph stays current as you code, zero config |
-| **20+ Languages** | TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Objective-C, Swift, Kotlin, Scala, Dart, Lua, Luau, R, Svelte, Vue, Astro, Liquid, Pascal/Delphi, **VBA / Access** |
+| **30+ Languages** | TypeScript, JavaScript, ArkTS, Python, Go, Rust, Java, C#, VB.NET, PHP, Ruby, C, C++, CUDA, Objective-C, Metal, Swift, Kotlin, Scala, Dart, Lua, Luau, R, Nix, Erlang, CFML, COBOL, Solidity, Terraform/OpenTofu, Svelte, Vue, Astro, Liquid, Pascal/Delphi, **VBA / Access** |
 | **Framework-aware Routes** | Recognizes web-framework routing files and links URL patterns to their handlers across 17 frameworks |
 | **Mixed iOS / React Native / Expo** | Closes cross-language flows that static parsing misses: Swift ↔ ObjC bridging, React Native legacy bridge + TurboModules + Fabric view components, native → JS event emitters, Expo Modules |
 | **VBA / Access + Dysflow** | Indexes the Dysflow-exported source tree (`.bas`/`.cls` + `.form.txt`/`.report.txt`) of Microsoft Access projects so agents can navigate VBA code the same way they navigate TypeScript or Python |

package/dist/bin/codegraph.d.ts

@@ -22,5 +22,5 @@
  *   codegraph affected [files]   Find test files affected by changes
  *   codegraph upgrade [version]  Update CodeGraph to the latest release
  */
-export {};
+import '../mcp/early-ppid';
 //# sourceMappingURL=codegraph.d.ts.map

package/dist/bin/command-supervision.d.ts

@@ -1,3 +1,34 @@
+/**
+ * Process supervision for long-running CLI commands (`index` / `init --index`).
+ *
+ * Indexing a large repo can run for a while on the main thread, and #999
+ * surfaced two ways that goes wrong when nothing is watching it:
+ *
+ *   1. **Orphaned worker.** `index` runs in a child re-exec'd with
+ *      `--liftoff-only` (the WASM-flag relaunch). Its parent blocks in
+ *      `spawnSync`, so when the parent shim is killed it cannot forward the
+ *      signal — the child keeps running, now orphaned, pinning a core. The PPID
+ *      watchdog (#277) notices the parent/host went away and exits the child.
+ *   2. **Wedged indexer.** The `#850` main-thread liveness watchdog — which
+ *      SIGKILLs a process whose event loop stops turning — was wired only into
+ *      the MCP `serve` path, so a wedged `index`/`init` was never auto-killed.
+ *
+ * Both reuse the exact mechanisms `serve` already uses; this just makes them
+ * available to a one-shot command. Best-effort and self-disabling: a missing
+ * watchdog never blocks the command from running. Both honour the same env
+ * switches as `serve` (`CODEGRAPH_NO_WATCHDOG`, `CODEGRAPH_PPID_POLL_MS=0`).
+ *
+ * Unlike the daemon — whose main thread only does fast, bounded work — the
+ * `index`/`init` path runs reference resolution and dynamic-edge synthesis
+ * SYNCHRONOUSLY on this thread, and on a large repo that is legitimately many
+ * seconds of work. So those spans yield cooperatively to the event loop
+ * (`src/resolution/cooperative-yield.ts`) to keep the heartbeat alive; without
+ * that the watchdog would SIGKILL a valid, in-progress index (#1091). The
+ * distinction it must preserve — kill a TRUE wedge, spare slow-but-progressing
+ * work — is exactly what cooperative yielding buys: a genuinely stuck span never
+ * reaches its next yield, so it still trips the timeout.
+ */
+import { WatchdogOptions } from '../mcp/liveness-watchdog';
 export interface CommandSupervision {
     /** Tear down both watchdogs. Idempotent; call when the command finishes. */
     stop(): void;
@@ -7,6 +38,12 @@ export interface CommandSupervision {
  * `label` is used in the shutdown notice (e.g. `"index"`). Returns a handle
  * whose `stop()` must be called when the command completes so neither watchdog
  * outlives it.
+ *
+ * Pass `watchdog.progressPaths` (the project's SQLite DB + `-wal`) so the
+ * liveness watchdog can tell a slow-but-progressing store on degraded storage
+ * (files advancing) from a true wedge (they aren't) — one long synchronous
+ * SQLite statement on a 150-IOPS disk otherwise gets a healthy index
+ * SIGKILLed (#1231).
  */
-export declare function installCommandSupervision(label: string): CommandSupervision;
+export declare function installCommandSupervision(label: string, watchdog?: WatchdogOptions): CommandSupervision;
 //# sourceMappingURL=command-supervision.d.ts.map

package/dist/db/index.d.ts

@@ -68,13 +68,51 @@ export declare class DatabaseConnection {
      * Get database file size in bytes
      */
     getSize(): number;
+    /**
+     * Size of the `-wal` sidecar file in bytes. 0 when it doesn't exist (non-WAL
+     * journal mode, in-memory DB, or no write since the last checkpoint+reset).
+     */
+    getWalSizeBytes(): number;
+    /** Current `wal_autocheckpoint` interval in pages (0 = disabled). */
+    getWalAutocheckpoint(): number;
+    /**
+     * Set the connection's `wal_autocheckpoint` interval (pages; 0 disables).
+     * Bulk indexing defers checkpoints entirely (#1231): the default 1000-page
+     * auto-checkpoint re-writes hot B-tree/FTS pages into the main DB file over
+     * and over — measured at ~95% of ALL disk I/O during a bulk index, and the
+     * difference between 45s and 19+ minutes on HDD-class storage. During
+     * deferral a {@link WalCheckpointValve} bounds WAL growth off-thread.
+     */
+    setWalAutocheckpoint(pages: number): void;
+    /**
+     * `PRAGMA wal_checkpoint(PASSIVE)` on a worker thread with its own
+     * connection. PASSIVE never blocks the writer, and running it off-thread
+     * means the main thread — and the #850 watchdog heartbeat — keep turning
+     * even when the backfill is minutes of I/O on slow storage (a synchronous
+     * checkpoint that exceeds the watchdog's 60s window gets a healthy index
+     * SIGKILLed — observed in the #1231 repro).
+     *
+     * Returns SQLite's checkpoint result row — `log === checkpointed` with
+     * `busy === 0` means the ENTIRE WAL was backfilled, so the writer's next
+     * commit restarts the WAL from the top and the file stops growing. The
+     * WAL valve needs that signal because a WAL file's SIZE never shrinks:
+     * after the first wrap, raw file size says nothing about the un-backfilled
+     * backlog. Best-effort: returns null on any failure (including worker
+     * threads being unavailable — a potentially minutes-long checkpoint must
+     * never run inline on the main thread).
+     */
+    checkpointWalPassive(): Promise<{
+        busy: number;
+        log: number;
+        checkpointed: number;
+    } | null>;
     /**
      * Optimize database (vacuum and analyze)
      */
     optimize(): void;
     /**
-     * Lightweight, non-blocking maintenance to run after bulk writes
-     * (indexAll, sync). Two operations:
+     * Lightweight maintenance to run after bulk writes (indexAll, sync).
+     * Two operations:
      *
      *   - `PRAGMA optimize` — incremental ANALYZE; SQLite only re-analyzes
      *     tables whose row counts changed materially since the last
@@ -86,10 +124,31 @@ export declare class DatabaseConnection {
      *     unboundedly between automatic checkpoints (auto-fires at 1000
      *     pages by default; large indexAll runs blow past that).
      *
-     * Both operations are silently swallowed on failure — they're a
-     * best-effort optimization, never load-bearing for correctness.
+     * Runs on a WORKER THREAD with its own connection: on a multi-GB index
+     * these pragmas are minutes of synchronous IO (a 95k-file kernel index
+     * left a 593MB WAL whose checkpoint alone blew the #850 watchdog's 60s
+     * window and got a COMPLETED index SIGKILLed at the finish line). WAL
+     * checkpointing from a second connection is standard SQLite; `PRAGMA
+     * optimize` persists its statistics in sqlite_stat tables, so the main
+     * connection benefits the same. The main thread just awaits a message,
+     * so the event loop — and the watchdog heartbeat — keep turning.
+     *
+     * Everything is silently swallowed on failure — best-effort
+     * optimization, never load-bearing for correctness. If worker threads
+     * are unavailable, falls back to a bounded in-line `PRAGMA optimize`
+     * and SKIPS the checkpoint (the final close() checkpoints after the
+     * CLI has already disarmed its watchdog).
+     */
+    runMaintenance(): Promise<void>;
+    /**
+     * Run pragmas on a worker thread against its own connection to this DB
+     * (shared machinery for {@link runMaintenance} and
+     * {@link checkpointWalPassive}). Each pragma is individually best-effort;
+     * the whole call is best-effort. `inlineFallback` (if any) runs on THIS
+     * connection only when worker threads are unavailable — keep it to pragmas
+     * that are safe to run synchronously on the main thread.
      */
-    runMaintenance(): void;
+    private runPragmasOffThread;
     /**
      * Close the database connection
      */
@@ -119,4 +178,24 @@ export declare const DATABASE_FILENAME = "codegraph.db";
  * Get the default database path for a project
  */
 export declare function getDatabasePath(projectRoot: string): string;
+/**
+ * Delete a database file and its WAL sidecars (`-wal`/`-shm`).
+ *
+ * This is how a FULL re-index discards an existing database — rather than
+ * opening the old graph and DELETE-ing every row. On a large or pre-fix
+ * poisoned index (e.g. an old graph that scanned an ignored gitlink corpus into
+ * ~1.6M nodes with a multi-GB WAL, #1065) the per-row `nodes_fts` delete-trigger
+ * churn blocks the main thread long enough to trip the #850 liveness watchdog
+ * before indexing even starts, so the rebuild could never recover the bad state
+ * (#1067). Unlinking is O(1) regardless of DB size and also reclaims the disk
+ * the bloated WAL would otherwise keep.
+ *
+ * POSIX removes the directory entry even while another process (a daemon/MCP
+ * server) still holds the file open; that holder heals via `reopenIfReplaced`
+ * (#925). On Windows a live holder can make the unlink fail with EBUSY/EPERM —
+ * that is thrown for the caller to surface ("stop the other process and retry").
+ * The `-wal`/`-shm` sidecars are best-effort: SQLite recreates them on the next
+ * open, so a leftover sidecar is harmless.
+ */
+export declare function removeDatabaseFiles(dbPath: string): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/db/migrations.d.ts

@@ -7,7 +7,7 @@ import { SqliteDatabase } from './sqlite-adapter';
 /**
  * Current schema version
  */
-export declare const CURRENT_SCHEMA_VERSION = 6;
+export declare const CURRENT_SCHEMA_VERSION = 9;
 /**
  * Migration definition
  */

package/dist/db/queries.d.ts

@@ -4,7 +4,7 @@
  * Prepared statements for CRUD operations on the knowledge graph.
  */
 import { SqliteDatabase } from './sqlite-adapter';
-import { Node, Edge, FileRecord, UnresolvedReference, NodeKind, EdgeKind, GraphStats, SearchOptions, SearchResult } from '../types';
+import { Node, Edge, FileRecord, UnresolvedReference, NodeKind, EdgeKind, Language, GraphStats, SearchOptions, SearchResult } from '../types';
 /**
  * Query builder for the knowledge graph database
  */
@@ -14,6 +14,8 @@ export declare class QueryBuilder {
     private nodeCache;
     private readonly maxCacheSize;
     private stmts;
+    private segmentedNames;
+    private static readonly MAX_SEGMENTED_NAMES;
     constructor(db: SqliteDatabase);
     /** Set the normalized project-name tokens used to down-weight non-discriminative
      * query words in path scoring (#720). Called once when the project opens. */
@@ -24,6 +26,12 @@ export declare class QueryBuilder {
      * Insert a new node
      */
     insertNode(node: Node): void;
+    /** Which node kinds contribute their name to the segment vocabulary — the
+     *  single gate shared by insertNode, updateNode, and the rebuild page query
+     *  (getDistinctNodeNames), so the write paths can't drift apart. */
+    private isSegmentableKind;
+    /** Write `name`'s segments into name_segment_vocab (idempotent). */
+    private insertNameSegments;
     /**
      * Insert multiple nodes in a transaction
      */
@@ -40,6 +48,44 @@ export declare class QueryBuilder {
      * Delete all nodes for a file
      */
     deleteNodesByFile(filePath: string): void;
+    /** Wipe the segment vocabulary. A full index calls this at its start; the
+     *  node write path repopulates it as files (re-)index, so the end state is
+     *  exactly the current names with no orphan rows. */
+    clearNameSegmentVocab(): void;
+    /** True when the vocab has no rows — an index built before the table existed.
+     *  `sync` uses this to heal such databases (see rebuildNameSegmentVocabFrom). */
+    isNameSegmentVocabEmpty(): boolean;
+    /** One page of distinct segmentable node names, for batched vocab rebuilds
+     *  (file basenames and import specifiers are excluded from the vocab — see
+     *  insertNode). */
+    getDistinctNodeNames(limit: number, offset: number): string[];
+    /** Insert segments for a batch of names in one transaction (vocab heal path). */
+    insertNameSegmentsBatch(names: string[]): void;
+    /**
+     * Names whose segments cover at least `minWords` distinct PROMPT WORDS —
+     * the co-occurrence probe behind the prompt hook's medium tier: the words
+     * "state" and "machine" both being segments of `OrderStateMachine` is strong
+     * evidence the prompt names that symbol in prose. Ordered by coverage.
+     *
+     * Takes (segment variant → original word) pairs and folds variants back to
+     * their word INSIDE the SQL: a name matching both `service` and `services`
+     * counts ONE word, not two. Counting raw variants let plural-variant pairs
+     * of a single word tie with genuine two-word matches and — because ORDER
+     * BY/LIMIT run here, before any JS-side re-check — crowd a real match past
+     * the LIMIT on vocab-heavy repos (#1146).
+     */
+    getSegmentCoOccurrence(variants: Array<{
+        segment: string;
+        word: string;
+    }>, minWords: number, limit: number): Array<{
+        name: string;
+        matches: number;
+    }>;
+    /** How many distinct names each segment appears in — the rarity signal that
+     *  separates a discriminative word ("checkout") from a ubiquitous one ("state"). */
+    getSegmentNameCounts(segments: string[]): Map<string, number>;
+    /** Names containing the given segment (rare-single-word tier). */
+    getNamesForSegment(segment: string, limit: number): string[];
     /**
      * Get a node by ID
      */
@@ -152,10 +198,32 @@ export declare class QueryBuilder {
      * Get all nodes in the database
      */
     getAllNodes(): Node[];
+    /**
+     * Stream nodes of one language whose `decorators` JSON array contains
+     * `decorator`. The LIKE on the JSON text is a cheap index-free pre-filter
+     * (a decorator name can appear as a substring of another), so callers must
+     * still exact-check `node.decorators.includes(decorator)`. Exists so the
+     * kotlin expect/actual synthesizer never materializes the whole node table
+     * the way `getAllNodes().filter(...)` did — that array alone OOM'd Node's
+     * default heap on a 2M-node graph (#1212).
+     */
+    iterateNodesByLanguageWithDecorator(language: Language, decorator: string): IterableIterator<Node>;
+    /**
+     * Distinct languages present in the files table. One indexed aggregate —
+     * lets the dynamic-edge synthesizers skip passes for languages the project
+     * doesn't contain at all (a Kotlin pass has no work on a pure-C repo), so
+     * their cost is zero rather than a full-graph scan that finds nothing (#1212).
+     */
+    getDistinctFileLanguages(): Set<string>;
     /**
      * Get nodes by exact name match (uses idx_nodes_name index)
      */
     getNodesByName(name: string): Node[];
+    /**
+     * Nodes whose name starts with `prefix`, by index range scan (a LIKE would
+     * skip idx_nodes_name under SQLite's default case-insensitive LIKE).
+     */
+    getNodesByNamePrefix(prefix: string, limit?: number): Node[];
     /**
      * Get nodes by exact qualified name match (uses idx_nodes_qualified_name index)
      */
@@ -326,6 +394,8 @@ export declare class QueryBuilder {
     getCrossFileIncomingEdgesWithTarget(filePath: string): Array<Edge & {
         targetName: string;
         targetKind: NodeKind;
+        sourceFilePath: string;
+        sourceLanguage: Language;
     }>;
     /**
      * Insert or update a file record
@@ -373,12 +443,18 @@ export declare class QueryBuilder {
      */
     getUnresolvedReferences(): UnresolvedReference[];
     /**
-     * Get the count of unresolved references without loading them into memory
+     * Get the count of PENDING (never-attempted) references without loading
+     * them into memory. Rows marked status='failed' — attempted by a completed
+     * pass, no match — are excluded: they are not outstanding work, only retry
+     * candidates for the #1240 sweep, so they must not trip the #1187 orphan
+     * sweep or the `status` pending-refs warning.
      */
     getUnresolvedReferencesCount(): number;
     /**
-     * Get a batch of unresolved references using LIMIT/OFFSET pagination.
-     * Used to process references in bounded memory chunks.
+     * Get a batch of PENDING unresolved references using LIMIT/OFFSET
+     * pagination. Used to process references in bounded memory chunks; failed
+     * rows are excluded so the batched drain loop terminates once every row
+     * has been attempted.
      */
     getUnresolvedReferencesBatch(offset: number, limit: number): UnresolvedReference[];
     /**
@@ -389,6 +465,13 @@ export declare class QueryBuilder {
      * Get all distinct node names (lightweight — just name strings for pre-filtering)
      */
     getAllNodeNames(): string[];
+    /**
+     * Stream the distinct node names one row at a time — the incremental
+     * counterpart to {@link getAllNodeNames} for callers that need to yield
+     * to the event loop mid-scan (resolver cache warm-up on multi-million-node
+     * indexes). Fresh statement per call: the iterator holds an open cursor.
+     */
+    iterateNodeNames(): IterableIterator<string>;
     /**
      * Get unresolved references scoped to specific file paths.
      * Uses the idx_unresolved_file_path index for efficient lookup.
@@ -411,6 +494,35 @@ export declare class QueryBuilder {
         referenceName: string;
         referenceKind: string;
     }>): void;
+    /**
+     * Mark refs a completed resolution pass could not resolve as status='failed'
+     * instead of deleting them (#1240). Failed rows are invisible to the pending
+     * count/batch readers (so drain loops and the #1187 orphan sweep still
+     * terminate) but stay queryable by name_tail so a later sync can retry them
+     * when a changed file introduces a symbol that could satisfy them. name_tail
+     * is (re)written here so rows inserted before the v8 migration get their
+     * tail the first time they're attempted.
+     */
+    markReferencesFailed(refs: Array<{
+        fromNodeId: string;
+        referenceName: string;
+        referenceKind: string;
+    }>): void;
+    /**
+     * Failed refs whose name tail matches one of the given symbol names — the
+     * candidates a sync should retry after files carrying those names changed
+     * (#1240). Names matching more than `perNameCeiling` failed refs are
+     * skipped entirely: at that population a name is external/builtin noise
+     * (`get`, `map`, …) that one new definition won't resolve — the same
+     * rationale as resolution's AMBIGUOUS_NAME_CEILING (#999) — and retrying an
+     * arbitrary subset would be both wasted work and incoherent coverage.
+     */
+    getRetryableFailedReferences(names: string[], perNameCeiling?: number): UnresolvedReference[];
+    /**
+     * Distinct node names present in the given files — the symbol names a sync
+     * pass uses to look up retryable failed refs after those files changed.
+     */
+    getNodeNamesByFiles(filePaths: string[]): string[];
     /**
      * Lightweight (nodes, edges) count snapshot. Used around an index/sync
      * run to compute true additions across extraction + resolution +

package/dist/db/wal-valve.d.ts

@@ -0,0 +1,106 @@
+/**
+ * WAL checkpoint valve — bounds WAL growth while auto-checkpointing is
+ * deferred during a bulk index (#1231).
+ *
+ * Why deferral: SQLite's default `wal_autocheckpoint` (1000 pages) re-writes
+ * hot B-tree/FTS pages into the main DB file over and over during a bulk
+ * index — measured at ~95% of ALL disk I/O, and the difference between 45s
+ * and 19+ minutes on HDD-class storage (150 random IOPS). Deferring
+ * checkpoints turns the store into pure sequential WAL appends; each backfill
+ * pass writes distinct pages once, in page order (≈ sequential).
+ *
+ * Why a valve: unbounded deferral is its own failure mode, both measured in
+ * the #1231 repro. The WAL duplicates hot pages per COMMIT, so it grows far
+ * faster than the DB (5.9GB WAL for a ~340MB DB on a 3.3k-file index) —
+ * filling the disk, and poisoning every subsequent read that must page
+ * through it (the first resolution-phase read blocked the main thread >60s
+ * and the #850 liveness watchdog killed the healthy index). The valve
+ * watches WAL growth on a timer and, past a soft threshold, backfills with
+ * `PRAGMA wal_checkpoint(PASSIVE)` on a worker-thread connection — PASSIVE
+ * never blocks the writer, and off-thread means the main thread (and the
+ * watchdog heartbeat) keep turning regardless of how long a backfill takes.
+ *
+ * The load-bearing subtlety: a WAL file's SIZE never shrinks. After a full
+ * backfill, the writer's next commit RESTARTS the WAL from the top and the
+ * frames recycle inside the same file — so raw size says nothing about the
+ * un-backfilled backlog, and a size-triggered valve degenerates into firing
+ * (and pausing the writer) forever once the file passes its threshold
+ * (measured: guava crawled at ~9min per 160 files). Instead the valve
+ * tracks `sizeAtLastFullBackfill` — refreshed whenever a checkpoint reports
+ * `log === checkpointed` (everything backfilled) — and triggers on GROWTH
+ * beyond that baseline, which only happens when genuinely un-backfilled
+ * frames push past the file's high-water mark.
+ *
+ * Backpressure: if the writer outruns the checkpointer past a hard cap of
+ * growth (2× soft), {@link backpressure} pauses the writer (at a safe,
+ * between-transactions boundary) until a FULL backfill lands. One in-flight
+ * pass is not enough: on a disk saturated by the writer, every concurrent
+ * PASSIVE pass is already stale by the time it finishes (the writer appended
+ * past its snapshot), so neither SQLite's WAL wrap nor the baseline ever
+ * trigger and the WAL grows without bound (measured: 5.9GB on guava at 150
+ * IOPS, then a >60s read stall and a watchdog kill). With the writer parked,
+ * the next pass covers everything, the WAL wraps on the following commit,
+ * and the pause is the disk's honest catch-up cost — the correct terminal
+ * mode when hardware genuinely can't keep up with the append rate.
+ */
+import type { DatabaseConnection } from './index';
+/**
+ * Resolve the valve's soft threshold from the `CODEGRAPH_WAL_VALVE_MB`
+ * override; non-numeric / non-positive values fall back to the default.
+ */
+export declare function resolveWalValveMb(envVal: string | undefined): number;
+export declare class WalCheckpointValve {
+    private readonly db;
+    private readonly intervalMs;
+    private readonly log;
+    private timer;
+    private inflight;
+    /** Writer pause in progress (hard cap breached): passes loop until a full backfill. */
+    private pause;
+    /**
+     * WAL file size observed when a checkpoint last reported the ENTIRE WAL
+     * backfilled. Growth is measured against this baseline — see the header
+     * comment for why absolute size cannot be used.
+     */
+    private sizeAtLastFullBackfill;
+    private readonly softBytes;
+    private readonly hardBytes;
+    constructor(db: DatabaseConnection, softMb?: number, intervalMs?: number, log?: (msg: string) => void);
+    private mb;
+    /** Un-backfilled growth estimate: bytes the WAL has grown past the last full backfill. */
+    private growthBytes;
+    /** Begin watching the WAL. Idempotent; the timer never holds the loop open. */
+    start(): void;
+    /** Stop watching. Any in-flight checkpoint keeps running — await drain(). */
+    stop(): void;
+    /** One poll: fire an off-thread passive checkpoint when growth passes the soft threshold. */
+    check(): void;
+    /**
+     * Writer-side backstop, called at a between-transactions boundary. Returns
+     * null (no wait) while growth is under the hard cap; past it, returns a
+     * promise that resolves only once a FULL backfill has landed — see the
+     * header comment for why a single pass is not enough on a saturated disk.
+     */
+    backpressure(): Promise<void> | null;
+    /** Await any in-flight checkpoint and writer pause. */
+    drain(): Promise<void>;
+    /**
+     * Phase-boundary fold: backfill the ENTIRE WAL now (off-thread, awaited).
+     * Called between bulk phases — e.g. after parsing, before resolution's
+     * first reads — so the next phase never pages a bulk-write-sized WAL on
+     * the main thread (the post-parse read against a multi-GB WAL is what
+     * blew the #850 watchdog's 60s window in the #1231 repro). The await
+     * keeps the event loop (and the watchdog heartbeat) turning.
+     */
+    foldNow(): Promise<void>;
+    /**
+     * With the writer parked on the returned promise, loop passive passes until
+     * one reports the entire WAL backfilled (typically the second: the first
+     * drains the pass that was already running against a stale snapshot). Gives
+     * up after a bounded number of passes — e.g. a reader pinning the WAL —
+     * because unbounded WAL growth degrades; a wedged writer never recovers.
+     */
+    private backfillFully;
+    private fire;
+}
+//# sourceMappingURL=wal-valve.d.ts.map

package/dist/directory.d.ts

@@ -86,10 +86,14 @@ export declare function findIndexedSubprojectRoots(root: string, opts?: {
     max?: number;
 }): string[];
 /**
- * Does `prompt` contain an explicit structural keyword (English or CJK)? A
- * keyword is a strong, self-contained signal, so the front-load hook fires on it
- * directly — no graph check needed. (A *code-token* match, by contrast, is only
- * a candidate the hook verifies against the graph first; see {@link extractCodeTokens}.)
+ * Does `prompt` contain an explicit structural keyword? A keyword is a strong,
+ * self-contained signal, so the front-load hook fires on it directly — no graph
+ * check needed. (A *code-token* match, by contrast, is only a candidate the
+ * hook verifies against the graph first; see {@link extractCodeTokens}.)
+ * Coverage is multilingual (#994, #1126): the ~29 languages with the largest
+ * developer populations, across Latin, Cyrillic, Greek, CJK, Hangul, Arabic,
+ * Hebrew, Thai, and Devanagari scripts. Languages beyond the keyword table
+ * still fire through the language-agnostic code-token path.
  */
 export declare function hasStructuralKeyword(prompt: string): boolean;
 /**
@@ -110,7 +114,7 @@ export declare function extractCodeTokens(prompt: string): string[];
 /**
  * Cheap, graph-free candidate gate for the front-load hook: could `prompt` be a
  * structural / flow / impact / "where-how" question worth front-loading context
- * for? True on an explicit keyword (English or CJK, issue #994) OR an
+ * for? True on an explicit keyword in any covered language (#994, #1126) OR an
  * identifier-shaped token. A keyword is sufficient to fire on its own; a
  * token-only match is only a candidate the hook then verifies against the graph
  * (a brand name like `JavaScript` is token-shaped but isn't a symbol). Every

package/dist/extraction/cfml-extractor.d.ts

@@ -0,0 +1,107 @@
+import { ExtractionResult, Language } from '../types';
+/**
+ * CfmlExtractor - Extracts code relationships from CFML source (.cfc/.cfm).
+ *
+ * tree-sitter-cfml splits CFML into two related grammars: `cfml` (tag-based —
+ * `<cfcomponent>`/`<cffunction>`/HTML) and `cfscript` (modern bare-script
+ * `component { ... }` syntax). The `cfml` grammar's own injections.scm treats
+ * bare-script content as an opaque blob meant to be re-parsed by `cfscript` —
+ * that re-parsing only happens at the editor/highlighting layer, not in the
+ * raw AST, so this extractor replicates it: a file whose first real token
+ * isn't `<` is delegated wholesale to the cfscript grammar (the dominant
+ * modern style); otherwise the file is walked tag-by-tag with the cfml
+ * grammar, delegating any `<cfscript>` tag bodies the same way.
+ */
+export declare class CfmlExtractor {
+    private filePath;
+    private source;
+    private language;
+    private nodes;
+    private edges;
+    private unresolvedReferences;
+    private errors;
+    /** `language` is the file's detected language — `'cfml'` for `.cfc`/`.cfm`, `'cfscript'` for `.cfs`. Both dialect-switch internally; this only controls the language tag stamped onto emitted nodes/refs. */
+    constructor(filePath: string, source: string, language?: Language);
+    extract(): ExtractionResult;
+    /** Modern bare-script `.cfc`/`.cfm`: delegate the whole file to the cfscript grammar. */
+    private extractBareScript;
+    /** Legacy tag-based CFML: walk `<cfcomponent>`/`<cffunction>`, delegating `<cfscript>` bodies. */
+    private extractTagBased;
+    /** Build the file's own `kind:'file'` node, spanning the whole source. Tag-based files need this explicitly — unlike `extractBareScript` (which delegates the whole file to `TreeSitterExtractor` and inherits its file node), `extractTagBased` walks the tree itself and has no other source of one. */
+    private createFileNode;
+    /**
+     * Walks `program`'s named children with a single forward cursor (not an
+     * index loop) — `extractComponent` consumes a variable run of FOLLOWING
+     * siblings as the component body (see its doc comment), so this must
+     * resume from whatever it last consumed rather than revisiting those same
+     * cffunction/cfscript siblings a second time as bogus top-level symbols.
+     */
+    private walkProgram;
+    /**
+     * `<cfcomponent extends="Base" implements="IFoo,IBar">...</cfcomponent>`.
+     * The grammar's implicit-end-tag scanner means component body content
+     * (cffunction tags, cfscript tags, etc.) appears as the open tag's FOLLOWING
+     * siblings in `program`, not nested children — walk forward to the matching
+     * cf_component_close_tag.
+     */
+    private extractComponent;
+    /**
+     * `<cffunction name="..." access="..." returntype="...">...</cffunction>`.
+     * `parentClassId` decides `method` vs top-level `function`; `containerId` is
+     * the `contains`-edge target (the class when inside one, otherwise the file
+     * node for a bare top-level cffunction) — kept separate so a top-level
+     * function still gets a containment edge without being misclassified as a
+     * method of the file. A method's qualifiedName is scoped under
+     * `parentClassName` (`TagService::save`, the same `Class::member` shape the
+     * generic extractor produces) so type-validated method resolution can match.
+     */
+    private extractFunctionTag;
+    /**
+     * Recursively delegates any `cf_script_tag`/`cf_query_tag` found within
+     * `node`'s subtree — e.g. a `<cfscript>`/`<cfquery>` nested inside
+     * `<cfif>`/`<cfloop>`/`<cftry>` control-flow tags, which (unlike
+     * `<cfcomponent>`'s body — see the implicit-end-tag note on `extractComponent`)
+     * ARE normal children, just possibly several levels deep, so a direct-children
+     * check misses them. Does not descend into a nested `cf_function_tag` — that
+     * has its own scope and is walked separately. `parentClassName` rides along
+     * so a `<cfscript>` at component scope classifies its functions as methods
+     * scoped under the component.
+     */
+    private delegateNestedTags;
+    /**
+     * Delegate a `<cfscript>...</cfscript>` tag body to the cfscript grammar.
+     * With `parentClassName` set (the block sits at component scope), functions
+     * declared at the script's top level are the component's methods
+     * (`<cfcomponent><cfscript>function configure(){}` — the standard ColdBox
+     * ModuleConfig shape): they're re-kinded `function` → `method`, and every
+     * merged symbol's qualifiedName is prefixed with the component scope
+     * (`configure` → `ModuleConfig::configure`) so type-validated method
+     * resolution can match them. Functions nested inside another function
+     * (closures) keep kind `function`.
+     */
+    private delegateScriptTag;
+    /**
+     * Delegate a `<cfquery>...</cfquery>` tag's SQL body to the `cfquery` grammar.
+     * `#hash#` expressions inside the SQL (e.g. `#getCurrentUser().getId()#` in a
+     * WHERE clause) are real CFML calls/references — tree-sitter-cfml's `cfquery`
+     * grammar parses them structurally (same `call_expression`/`member_expression`
+     * shape as cfscript), so without this delegation they're silently dropped as
+     * opaque SQL text. The grammar models no other symbols, so only call/reference
+     * extraction is relevant here — unlike `delegateScriptTag`, there are no nodes
+     * or contains-edges to merge.
+     */
+    private delegateQueryTag;
+    /** Read a `cf_attribute`'s value by name from a tag node's direct `cf_attribute`/`cf_tag_attributes` children. */
+    private tagAttr;
+    private componentNameFromPath;
+}
+/**
+ * Sniff whether CFML source is bare-script (`component { ... }`, modern style)
+ * vs tag-based (`<cfcomponent>`, `<cfif>`, HTML). Skips a leading UTF-8 BOM
+ * (endemic in CFML's Windows-editor history — 17% of ColdBox's files carry
+ * one; both grammars parse fine with it once routed correctly), whitespace,
+ * and `//`/`/* *\/` comments to find the first real token; tag-based files
+ * start with `<`, script-based files don't.
+ */
+export declare function isBareScriptCfml(source: string): boolean;
+//# sourceMappingURL=cfml-extractor.d.ts.map