@aroman22/codegraph-vba 1.15.0 → 1.17.0

package/dist/mcp/daemon-registry.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Global daemon registry + stop/list control — the discovery layer behind
+ * `codegraph list` and `codegraph stop [--all]`.
+ *
+ * Every per-project daemon already writes an authoritative lockfile at
+ * `<root>/.codegraph/daemon.pid`. That's enough to stop ONE daemon you can name,
+ * but there's no central place to find them ALL — which `list` and `stop --all`
+ * need. So each daemon also drops a tiny record under `~/.codegraph/daemons/` on
+ * start and removes it on graceful shutdown.
+ *
+ * The registry is a DISCOVERY index, never a source of truth: the live pid is.
+ * A SIGKILL'd daemon can't remove its own record, so readers prune any record
+ * whose pid is dead (`isProcessAlive`). Every write/read is best-effort — a
+ * registry hiccup must never break the daemon or a command; worst case `list`
+ * momentarily misses or over-lists one, which the next liveness prune corrects.
+ *
+ * Cross-platform by construction: only files + `process.kill(pid, signal)`,
+ * which behave consistently on macOS/Linux (real signals) and Windows (mapped to
+ * TerminateProcess). Validated live on all three.
+ */
+import * as fs from 'fs';
 export interface DaemonRecord {
     /** Realpath'd project root the daemon serves. */
     root: string;
@@ -32,16 +53,70 @@ export declare function listDaemons(opts?: {
 export interface StopResult {
     root: string;
     pid: number | null;
-    /** 'term' graceful, 'kill' force, 'not-running' stale lock, 'no-daemon' none found. */
-    outcome: 'term' | 'kill' | 'not-running' | 'no-daemon';
+    outcome: 'released' | 'not-running' | 'no-daemon' | 'identity-mismatch' | 'unreachable' | 'termination-failed';
+    failure?: string;
+}
+export interface ExpectedDaemon {
+    root: string;
+    pid: number;
+    version: string;
+    socketPath: string;
+    startedAt: number;
+}
+export interface DaemonReleaseDeps {
+    isAlive?: (pid: number) => boolean;
+    waitForDeath?: (pid: number, timeoutMs: number) => Promise<boolean>;
+    requestControl?: (expected: ExpectedDaemon) => Promise<'releasing' | 'identity-mismatch' | 'unreachable'>;
+    beforeArtifactDelete?: () => void;
+    leaseLinkSync?: typeof fs.linkSync;
+    afterLifecycleAcquired?: () => void;
+    afterReleaseLeasePublished?: (expected: ExpectedDaemon) => void;
+}
+export declare const DAEMON_RELEASE_LEASE_TTL_MS = 30000;
+export interface DaemonLifecycleLock {
+    token: string;
+    ownerPid: number;
+    createdAt: number;
+    expiresAt: number;
+}
+/** Atomically acquire the shared startup/release publication arbiter. */
+export declare function tryAcquireDaemonLifecycleLock(root: string, options?: {
+    now?: number;
+    linkSync?: typeof fs.linkSync;
+}): DaemonLifecycleLock | null;
+export declare function releaseDaemonLifecycleLock(root: string, lock: DaemonLifecycleLock): void;
+export interface DaemonReleaseLease {
+    token: string;
+    ownerPid: number;
+    createdAt: number;
+    heartbeatAt: number;
+    expiresAt: number;
+    generation: Pick<ExpectedDaemon, 'pid' | 'startedAt' | 'socketPath'>;
 }
+/** True while intentional release exclusively owns this root's lifecycle. */
+export declare function hasActiveDaemonReleaseLease(root: string, now?: number, hooks?: {
+    afterRecoveryRead?: () => void;
+}): boolean;
+/** Atomically claim release/cleanup ownership for one daemon generation. */
+export declare function tryAcquireDaemonReleaseLease(root: string, expected: ExpectedDaemon, options?: {
+    now?: number;
+    linkSync?: typeof fs.linkSync;
+}): DaemonReleaseLease | null;
+/** Publish a complete renewed generation atomically under the recovery marker. */
+export declare function refreshDaemonReleaseLease(root: string, lease: DaemonReleaseLease, now?: number): boolean;
+/** Resolve an explicit project root to the same canonical form daemons use. */
+export declare function canonicalDaemonRoot(root: string): string;
+/** Stable map/set key for aliases of the same canonical root. */
+export declare function canonicalDaemonRootKey(root: string): string;
+/** Project-scoped, idempotent release contract shared by CLI and MCP. */
+export declare function releaseDaemonAt(root: string, deps?: DaemonReleaseDeps): Promise<StopResult>;
 /**
- * Stop the daemon serving `root`: SIGTERM, wait, then SIGKILL if it won't go,
- * then sweep its artifacts. `root` must be realpath'd (match how the daemon
- * keys its socket/lockfile). Resolves the pid from the authoritative lockfile,
- * falling back to the registry.
+ * Release the daemon serving `root` through its authenticated socket handshake,
+ * wait for confirmed process death, then sweep ownership artifacts. Never sends
+ * a signal based only on pidfile/registry liveness. `root` must be realpath'd.
  */
-export declare function stopDaemonAt(root: string): Promise<StopResult>;
+export declare function stopDaemonAt(root: string, deps?: DaemonReleaseDeps): Promise<StopResult>;
+export declare function requestDaemonRelease(expected: ExpectedDaemon): Promise<'releasing' | 'identity-mismatch' | 'unreachable'>;
 /** Stop every registered, live daemon. */
 export declare function stopAllDaemons(): Promise<StopResult[]>;
 //# sourceMappingURL=daemon-registry.d.ts.map

package/dist/mcp/daemon-watchdog.d.ts

@@ -16,6 +16,7 @@
  * Spawned detaches (own session/process group) so closing the MCP process
  * does not take the watchdog down with it.
  */
+import { type StopResult } from './daemon-registry';
 export interface DaemonWatchdogOptions {
     /** Poll interval (ms). Default 30s. */
     intervalMs?: number;
@@ -33,6 +34,10 @@ export interface DaemonWatchdogOptions {
         windowsHide?: boolean;
         stdio?: 'ignore' | ['ignore', number, number];
     }) => boolean;
+    /** Release seam for deterministic overlap/failure tests. */
+    releaseFn?: (root: string) => Promise<StopResult>;
+    /** Async boundary before spawn; defaults to one microtask for release ordering. */
+    beforeSpawn?: () => Promise<void>;
 }
 /**
  * Per-project daemon liveness watchdog. Registers roots; polls every
@@ -40,16 +45,23 @@ export interface DaemonWatchdogOptions {
  */
 export declare class DaemonWatchdog {
     private readonly roots;
+    private readonly releasing;
     private interval;
     private readonly intervalMs;
     private readonly scriptPath;
     private readonly nodePath;
     private readonly spawnFn;
+    private readonly releaseFn;
+    private readonly beforeSpawn;
     constructor(opts?: DaemonWatchdogOptions);
     /** Watch a project root: if its daemon dies, respawn it. Idempotent. */
     watch(root: string): void;
+    /** Begin a new lifecycle for an intentionally released root. */
+    resume(root: string): void;
     /** Stop watching a root. Idempotent. */
     unwatch(root: string): void;
+    /** Intentionally release one project without allowing the next tick to respawn it. */
+    release(root: string): Promise<StopResult>;
     /** Number of roots currently being watched. */
     size(): number;
     /**

package/dist/mcp/daemon.d.ts

@@ -63,8 +63,17 @@ export interface DaemonHello {
     codegraph: string;
     pid: number;
     socketPath: string;
+    root: string;
+    startedAt: number;
     protocol: 1;
 }
+export interface DaemonReleaseControl {
+    codegraph_control: 1;
+    action: 'release';
+    root: string;
+    pid: number;
+    startedAt: number;
+}
 /**
  * Optional reverse-handshake line a proxy sends right after it verifies the
  * daemon hello, carrying its own pids so the daemon can reap the client if its
@@ -112,9 +121,16 @@ export declare class Daemon {
     private stopping;
     private socketPath;
     private pidPath;
+    private startedAt;
+    private acquiredGeneration;
+    private listenSocket;
+    private exit;
     constructor(projectRoot: string, opts?: {
         idleTimeoutMs?: number;
         maxIdleMs?: number;
+        generation?: DaemonLockInfo;
+        listenSocket?: (socketPath: string, onConnection: (socket: net.Socket) => void) => Promise<net.Server>;
+        exit?: (code: number) => void;
     });
     /**
      * Bind the socket, kick off engine init, and register signal handlers. The
@@ -222,7 +238,9 @@ export type AcquireResult = {
  * widened). The race's worst case is two daemons briefly; on a single external
  * drive that's strictly better than the daemon never starting at all.
  */
-export declare function tryAcquireDaemonLock(projectRoot: string): AcquireResult;
+export declare function tryAcquireDaemonLock(projectRoot: string, options?: {
+    afterLifecycleAcquired?: () => void;
+}): AcquireResult;
 /**
  * Exclusive-create the pidfile (O_CREAT|O_EXCL via the `wx` flag) and write the
  * full record through the same fd — the hard-link-free fallback used by
@@ -285,6 +303,7 @@ export declare function peerIsDead(peers: {
     pid: number | null;
     hostPid: number | null;
 }, isAlive: (pid: number) => boolean): boolean;
+export declare function parseReleaseControlLine(line: string): DaemonReleaseControl | null;
 /** Exported for test stubs that need to bound the hello-line read. */
 export { MAX_HELLO_LINE_BYTES };
 //# sourceMappingURL=daemon.d.ts.map

package/dist/mcp/proxy.d.ts

@@ -58,6 +58,35 @@ export declare function runProxy(socketPath: string, expectedVersion?: string):
  * owns the socket. Used by the local-handshake proxy's background connect.
  */
 export declare function connectWithHello(socketPath: string, expectedVersion?: string): Promise<net.Socket | 'version-mismatch' | null>;
+type JsonRpc = Record<string, unknown>;
+type ProxyWrite = (obj: JsonRpc | string) => void;
+/** Tracks request order across the proxy's pending-before-connect and in-flight phases. */
+export declare class ProxyRequestBarrier {
+    private readonly pending;
+    private readonly inflight;
+    private readonly drainWaiters;
+    private track;
+    private requestId;
+    private resolveDrain;
+    buffer(line: string): void;
+    forward(line: string, send: (line: string) => void): void;
+    flush(send: (line: string) => void): void;
+    settle(id: unknown): void;
+    settleLine(line: string): void;
+    inflightLines(): string[];
+    pendingCount(): number;
+    inflightCount(): number;
+    drain(): Promise<void>;
+}
+/** Per-proxy barrier for intentional release of the project this session owns. */
+export declare class ProxyReleaseCoordinator {
+    private readonly drainEarlierRequests;
+    private readonly entries;
+    private readonly sessionKey;
+    constructor(sessionRoot: string, drainEarlierRequests?: () => Promise<void>);
+    getState(root?: string): 'active' | 'releasing' | 'released';
+    handle(msg: JsonRpc, enabled: boolean, releaseProject: ((root: string) => Promise<unknown>) | undefined, write: ProxyWrite): boolean;
+}
 /** Dependencies the local-handshake proxy needs, injected by MCPServer (which
  *  owns the daemon-spawn machinery and the engine factory). */
 export interface LocalHandshakeDeps {
@@ -69,6 +98,8 @@ export interface LocalHandshakeDeps {
     makeEngine(): MCPEngine;
     /** Project root for the fallback engine's lazy init. */
     root: string;
+    /** Release one root locally so the proxy can suppress watchdog respawn first. */
+    releaseProject?(root: string): Promise<unknown>;
 }
 /**
  * Local-handshake proxy (the cold-start fix).
@@ -84,4 +115,5 @@ export interface LocalHandshakeDeps {
  * never costs the old fall-back-to-direct robustness.
  */
 export declare function runLocalHandshakeProxy(deps: LocalHandshakeDeps): Promise<void>;
+export {};
 //# sourceMappingURL=proxy.d.ts.map

package/dist/mcp/server-instructions.d.ts

@@ -17,7 +17,7 @@
  * tools (node/search/callers/…) stay defined and are re-enablable via
  * CODEGRAPH_MCP_TOOLS, but they are NOT listed to agents, so don't name them.
  */
-export declare const SERVER_INSTRUCTIONS = "# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\nCodegraph is a SQLite knowledge graph of every symbol, edge, and file in\nthe workspace \u2014 pre-computed structure you would otherwise re-derive by\nreading files (cached intelligence: thousands of parse/trace decisions you\ndon't pay to re-reason each run). Reads are sub-millisecond; the index lags\nwrites by ~1s through the file watcher. Reach for it BEFORE *and* while\nwriting or editing code \u2014 not just for questions: one call returns the\nverbatim source PLUS who calls it and what it affects, so you edit with the\nblast radius in view. More accurate context, in far fewer tokens and\nround-trips than reading files yourself.\n\n## One tool: codegraph_explore \u2014 use it instead of reading files\n\nThere is a single tool, `codegraph_explore`, and it is Read-equivalent. It\ntakes either a natural-language question or a bag of symbol/file names and\nreturns the **verbatim, line-numbered source** of the relevant symbols\ngrouped by file \u2014 the same `<n>\\t<line>` shape `Read` gives you, safe to\n`Edit` from \u2014 PLUS the call path among them (including dynamic-dispatch hops\nlike callbacks, React re-render, and JSX children that grep can't follow) and\na blast-radius summary of what depends on them.\n\nWhether you're answering \"how does X work\" or implementing a change (fixing a\nbug, adding a feature), call `codegraph_explore` before you Read. ONE call\nusually answers the whole question. Codegraph IS the pre-built search index \u2014\nso running your own grep + read loop, or delegating the lookup to a separate\nfile-reading sub-task/agent, repeats work codegraph already did and costs more\nfor the same answer. A direct codegraph answer is typically one to a few\ncalls; a grep/read exploration is dozens.\n\n## How to query\n\n- **Almost any question \u2014 \"how does X work\", architecture, a bug, \"what/where is X\", or surveying an area** \u2192 `codegraph_explore` with a natural-language question or the relevant names. ONE capped call returns the verbatim source grouped by file; most often the ONLY call you need.\n- **\"How does X reach/become Y? / the flow / the path from X to Y\"** \u2192 `codegraph_explore`, naming the symbols that span the flow (e.g. `mutateElement renderScene`) \u2014 it surfaces the call path among them, riding dynamic-dispatch hops, and returns their source.\n- **Reading or editing a file/symbol you can name** \u2192 put its name or file path in the `codegraph_explore` query \u2014 it returns that current line-numbered source (safe to `Edit` from) with the call path and blast radius attached, so you don't Read it separately. For an overloaded name it returns every matching definition's body in one call.\n- **Need more?** Call `codegraph_explore` again with more specific names \u2014 treat the source it returns as already Read.\n\n## Anti-patterns\n\n- **Trust codegraph's results \u2014 don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.\n- **Don't grep or Read first** to find or understand indexed code \u2014 ONE `codegraph_explore` returns the relevant symbols' source together in a single round-trip. Reach for raw `Read`/`Grep` only to confirm a specific detail codegraph didn't cover, or for what codegraph doesn't index (configs, docs).\n- **Don't reconstruct a flow by hand** \u2014 name the endpoints in one `codegraph_explore` and it surfaces the path between them, dynamic-dispatch hops included.\n- **After editing, check the staleness banner.** When a tool response starts with \"\u26A0\uFE0F Some files referenced below were edited since the last index sync\u2026\", the listed files are pending re-index \u2014 Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust codegraph. A different, rarer banner \u2014 \"\u26A0\uFE0F CodeGraph auto-sync is DISABLED\u2026\" \u2014 means live watching stopped entirely (the whole index is frozen, not just a few files); until it's resolved, Read files directly to confirm anything that may have changed.\n\n## Limitations\n\n- If a tool reports a project isn't indexed (no `.codegraph/`), stop calling codegraph tools for that project for the rest of the session and use your built-in tools there instead. Indexing is the user's decision \u2014 mention they can run `codegraph init` if it comes up, but don't run it yourself.\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.\n\n## Supported Languages\n\nThe indexer recognizes a fixed set of languages; if you ask about symbols in a\nfile with an unsupported extension, codegraph will report the project isn't\nindexed for that file and you should fall back to Read/Grep. The fork-specific\naddition beyond upstream codegraph is **VBA / Access** (Dysflow export\nformat):\n\n- **VBA / Access** - Dysflow exports Access/VBA source as `.bas`/`.cls`/\n  `.form.txt`/`.report.txt`. Codegraph extracts `.bas`/`.cls` as `module`/\n  `class`/`function` nodes with `calls`/`implements`/`references` edges\n  (procedural-level; regex-based, not full AST). Cross-module calls, qualified\n  `Dim As`, `WithEvents`, and SQL table references inside string literals\n  emit synthesized edges tagged `metadata.synthesizedBy` (`vba-name-resolution`,\n  `vba-withevents`, `vba-sql-table`). `.form.txt` and `.report.txt` are\n  extracted as a `module` plus one `property` per Access control - **no**\n  `function`/`sub`/`class` nodes come from form files; the canonical code\n  lives in the sibling `.cls`, parsed by the same extractor on that file.\n  Dysflow test manifests (`tests.*.json`) link each registered `Test_*`\n  procedure to its manifest with a `references` edge tagged\n  `vba-test-manifest` carrying the test name + tags, so `getCallers` of a\n  production symbol reaches its covering test atoms with the manifest and tags\n  to run.\n  Pass `projectPath` to a codegraph index that includes VBA files.\n- **VBA unresolved refs carry syntactic shape** (v1.7+). `unresolved_refs.reference_kind` is no longer the literal string `\"references\"` \u2014 it reports what the syntactic shape actually was. Values: `call` (paren-form or statement-form call site), `qualified-call` (`obj.Foo(...)` with runtime receiver), `property-get` / `property-set` (`Me.Name`, `obj.Prop = value`), `bang-get` / `bang-set` (`Me!SubCtl`, `obj!Field = value`), `unqualified-ident` (bare identifier like `HayErrorEnRiesgo` in an `If` condition), `member-with` (`.Member` inside a `With` block), `dao-query` (`DoCmd.OpenQuery \"X\"` argument). The legacy value `references` is retained on any path the round did not reclassify, so older SQL filters that key on it keep working. To find real missing callees, filter `WHERE reference_kind IN ('call','qualified-call','unqualified-ident','member-with','bang-get')` \u2014 that set has <10% false positives (DAO-field accesses, form-property reads, and bang refs no longer pollute the bucket).\n- **Post-extraction stub resolver** (v1.7+). Edges with `metadata.synthesizedBy='vba-name-resolution'` start life pointing at a synthetic function node; the resolver at `src/resolution/index.ts:resolveVbaCallStubs` (invoked from `indexAll` and `sync`) walks them and repoints each `target` to the real `nodes.id` when one exists. Runtime-object calls (`DAO.*`, `fso.*`, `ListBox.*`, `Collection.*`, `err.*`, `VBA.*`, `Application.*`, `Screen.*`, `DoCmd.*`, `CurrentDb.*`, `Forms`, `Reports`, `Debug`, `Modules`, `References`, `CommandBars`, `SysCmd`, `CreateObject`, `GetObject`, `Fields`) are explicitly declined \u2014 they remain `stub:true` because they can never link to user code. Shadow user classes (e.g. a user class actually named `DAO` with an `Execute` method) are preserved and linked normally. Every stub edge carries `metadata.repointDecision` with one of `reponted-to-real` (linked to a real `nodes.id`), `declined-runtime` (runtime object \u2014 never user code, filter OUT), `declined-ambiguous` (multiple real candidates \u2014 investigate), or `declined-not-found` (genuinely missing callee \u2014 this is the actionable signal). Consumers detecting \"missing callees\" MUST filter on `repointDecision='declined-not-found'`, NOT on the raw `stub=true` count \u2014 the raw count is dominated by runtime-object noise. See `docs/vba-stub-repoint-decision.md` for the full contract.\n";
+export declare const SERVER_INSTRUCTIONS = "# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\nCodegraph is a SQLite knowledge graph of every symbol, edge, and file in\nthe workspace \u2014 pre-computed structure you would otherwise re-derive by\nreading files (cached intelligence: thousands of parse/trace decisions you\ndon't pay to re-reason each run). Reads are sub-millisecond; the index lags\nwrites by ~1s through the file watcher. Reach for it BEFORE *and* while\nwriting or editing code \u2014 not just for questions: one call returns the\nverbatim source PLUS who calls it and what it affects, so you edit with the\nblast radius in view. More accurate context, in far fewer tokens and\nround-trips than reading files yourself.\n\n## One tool: codegraph_explore \u2014 use it instead of reading files\n\nThere is a single tool, `codegraph_explore`, and it is Read-equivalent. It\ntakes either a natural-language question or a bag of symbol/file names and\nreturns the **verbatim, line-numbered source** of the relevant symbols\ngrouped by file \u2014 the same `<n>\\t<line>` shape `Read` gives you, safe to\n`Edit` from \u2014 PLUS the call path among them (including dynamic-dispatch hops\nlike callbacks, React re-render, and JSX children that grep can't follow) and\na blast-radius summary of what depends on them.\n\nWhether you're answering \"how does X work\" or implementing a change (fixing a\nbug, adding a feature), call `codegraph_explore` before you Read. ONE call\nusually answers the whole question. Codegraph IS the pre-built search index \u2014\nso running your own grep + read loop, or delegating the lookup to a separate\nfile-reading sub-task/agent, repeats work codegraph already did and costs more\nfor the same answer. A direct codegraph answer is typically one to a few\ncalls; a grep/read exploration is dozens.\n\n## How to query\n\n- **Almost any question \u2014 \"how does X work\", architecture, a bug, \"what/where is X\", or surveying an area** \u2192 `codegraph_explore` with a natural-language question or the relevant names. ONE capped call returns the verbatim source grouped by file; most often the ONLY call you need.\n- **\"How does X reach/become Y? / the flow / the path from X to Y\"** \u2192 `codegraph_explore`, naming the symbols that span the flow (e.g. `mutateElement renderScene`) \u2014 it surfaces the call path among them, riding dynamic-dispatch hops, and returns their source.\n- **Reading or editing a file/symbol you can name** \u2192 put its name or file path in the `codegraph_explore` query \u2014 it returns that current line-numbered source (safe to `Edit` from) with the call path and blast radius attached, so you don't Read it separately. For an overloaded name it returns every matching definition's body in one call.\n- **Need more?** Call `codegraph_explore` again with more specific names \u2014 treat the source it returns as already Read.\n\n## Anti-patterns\n\n- **Trust codegraph's results \u2014 don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.\n- **Don't grep or Read first** to find or understand indexed code \u2014 ONE `codegraph_explore` returns the relevant symbols' source together in a single round-trip. Reach for raw `Read`/`Grep` only to confirm a specific detail codegraph didn't cover, or for what codegraph doesn't index (configs, docs).\n- **Don't reconstruct a flow by hand** \u2014 name the endpoints in one `codegraph_explore` and it surfaces the path between them, dynamic-dispatch hops included.\n- **After editing, check the staleness banner.** When a tool response starts with \"\u26A0\uFE0F Some files referenced below were edited since the last index sync\u2026\", the listed files are pending re-index \u2014 Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust codegraph. A different, rarer banner \u2014 \"\u26A0\uFE0F CodeGraph auto-sync is DISABLED\u2026\" \u2014 means live watching stopped entirely (the whole index is frozen, not just a few files); until it's resolved, Read files directly to confirm anything that may have changed.\n\n## Limitations\n\n- If a tool reports a project isn't indexed (no `.codegraph/`), stop calling codegraph tools for that project for the rest of the session and use your built-in tools there instead. Indexing is the user's decision \u2014 mention they can run `codegraph init` if it comes up, but don't run it yourself.\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.\n\n## Supported Languages\n\nThe indexer recognizes a fixed set of languages; if you ask about symbols in a\nfile with an unsupported extension, codegraph will report the project isn't\nindexed for that file and you should fall back to Read/Grep. The fork-specific\naddition beyond upstream codegraph is **VBA / Access** (Dysflow export\nformat):\n\n- **VBA / Access** - Dysflow exports Access/VBA source as `.bas`/`.cls`/\n  `.form.txt`/`.report.txt`. Codegraph extracts `.bas`/`.cls` as `module`/\n  `class`/`function` nodes with `calls`/`implements`/`references` edges\n  (procedural-level; regex-based, not full AST). Cross-module calls, qualified\n  `Dim As`, `WithEvents`, and SQL table references inside string literals\n  emit synthesized edges tagged `metadata.synthesizedBy` (`vba-name-resolution`,\n  `vba-withevents`, `vba-sql-table`). A `.form.txt` / `.report.txt` emits a\n  `form-layout` / `report-layout` container, one\n  `form-instance-control` per named control, a `property` node per control\n  type, and a placeholder node per table/query it binds - but **no\n  procedures**: no `function`/`sub` node, and no class node for the form's\n  own code, comes from a layout file. The canonical code lives in the sibling\n  `.cls`, parsed by the same extractor on that file.\n- **Access event wiring has ONE direction: handler -> control/layout.** The\n  `event-handler` edge is stored from the handler procedure to the\n  `form-instance-control` it is named for (`btnSave_Click` -> `btnSave`), or\n  to the sibling layout node for a form/report lifecycle event\n  (`Form_Load` -> `Form_Orders`, carrying `metadata.scope: 'form'`). An\n  `=Expression()` event property resolves to the same direction, tagged\n  `vba-expression-handler`. There is no reverse edge: to answer \"what runs on\n  this control\", follow the edge BACKWARDS from the control. Scope every\n  control lookup by its layout - the same control name usually exists on\n  several forms, and a layout owns its controls through `contains`.\n- **A VBA call is not always a `calls` edge.** `Call Foo` and `Foo 1, 2` are\n  `calls`; a bare `Foo` on its own line could also be a `Const` read, so it\n  stays an ambiguous identifier and resolves to a `references` edge onto the\n  procedure. That bare form is the dominant call style in Access code-behind,\n  so a trace that follows only `calls` stops at the handler.\n- **Codegraph indexes the exported source tree, not the live `.accdb`.** It is\n  static evidence: it never proves a handler ran, and it says nothing about\n  whether the binary matches the export (Dysflow owns that round-trip). A\n  missing edge is missing evidence, not proof of no runtime effect.\n  Dysflow test manifests (`tests.*.json`) link each registered `Test_*`\n  procedure to its manifest with a `references` edge tagged\n  `vba-test-manifest` carrying the test name + tags, so `getCallers` of a\n  production symbol reaches its covering test atoms with the manifest and tags\n  to run.\n  Pass `projectPath` to a codegraph index that includes VBA files.\n- **VBA unresolved refs carry syntactic shape** (v1.7+). `unresolved_refs.reference_kind` is no longer the literal string `\"references\"` \u2014 it reports what the syntactic shape actually was. Values: `call` (paren-form or statement-form call site), `qualified-call` (`obj.Foo(...)` with runtime receiver), `property-get` / `property-set` (`Me.Name`, `obj.Prop = value`), `bang-get` / `bang-set` (`Me!SubCtl`, `obj!Field = value`), `unqualified-ident` (bare identifier like `HayErrorEnRiesgo` in an `If` condition), `member-with` (`.Member` inside a `With` block), `dao-query` (`DoCmd.OpenQuery \"X\"` argument). The legacy value `references` is retained on any path the round did not reclassify, so older SQL filters that key on it keep working. To find real missing callees, filter `WHERE reference_kind IN ('call','qualified-call','unqualified-ident','member-with','bang-get')` \u2014 that set has <10% false positives (DAO-field accesses, form-property reads, and bang refs no longer pollute the bucket).\n- **Post-extraction stub resolver** (v1.7+). Edges with `metadata.synthesizedBy='vba-name-resolution'` start life pointing at a synthetic function node; the resolver at `src/resolution/index.ts:resolveVbaCallStubs` (invoked from `indexAll` and `sync`) walks them and repoints each `target` to the real `nodes.id` when one exists. Runtime-object calls (`DAO.*`, `fso.*`, `ListBox.*`, `Collection.*`, `err.*`, `VBA.*`, `Application.*`, `Screen.*`, `DoCmd.*`, `CurrentDb.*`, `Forms`, `Reports`, `Debug`, `Modules`, `References`, `CommandBars`, `SysCmd`, `CreateObject`, `GetObject`, `Fields`) are explicitly declined \u2014 they remain `stub:true` because they can never link to user code. Shadow user classes (e.g. a user class actually named `DAO` with an `Execute` method) are preserved and linked normally. Every stub edge carries `metadata.repointDecision` with one of `reponted-to-real` (linked to a real `nodes.id`), `declined-runtime` (runtime object \u2014 never user code, filter OUT), `declined-ambiguous` (multiple real candidates \u2014 investigate), or `declined-not-found` (genuinely missing callee \u2014 this is the actionable signal). Consumers detecting \"missing callees\" MUST filter on `repointDecision='declined-not-found'`, NOT on the raw `stub=true` count \u2014 the raw count is dominated by runtime-object noise. See `docs/vba-stub-repoint-decision.md` for the full contract.\n";
 /**
  * Instructions variant sent when the server's own root has NO codegraph index.
  *

package/dist/mcp/tools.d.ts

@@ -382,6 +382,18 @@ export declare class ToolHandler {
      * NotIndexed/PathRefusal, which {@link executeReadTool} classifies.
      */
     private dispatchTool;
+    /**
+     * Access/VBA behavior evidence (issue #299) — a thin adapter over
+     * {@link CodeGraph.getBehaviorEvidence}. The assembly lives in
+     * `src/graph/behavior-evidence.ts`; this only validates argument shapes and
+     * serializes the typed result, so the MCP surface and a library consumer
+     * can never drift into two different answers.
+     *
+     * A request with no selector is NOT an error: the payload comes back with
+     * `MISSING_TARGET_SELECTOR` in `context.notes`, the same success-shaped
+     * guidance every other recoverable condition uses here.
+     */
+    private handleBehaviorEvidence;
     /** Run the CLI-only query command and preserve its JSON stdout verbatim. */
     private handleQuery;
     /**

package/dist/project-config.d.ts

@@ -46,6 +46,39 @@ export interface ProjectConfig {
          * `true`.
          */
         dysflowExport?: boolean;
+        /**
+         * Extra receiver names that execute SQL, so table references inside the
+         * SQL they run are still found (#244). Two entry forms are accepted:
+         *
+         *   - a bare identifier fragment — `"getdb"` reaches `getdb()`,
+         *     `getdbHPS()` and `getdbExpedientes()`;
+         *   - an explicit `receiver.method` pair — `"cnn.Execute"`.
+         *
+         * Raw regular expressions are deliberately NOT accepted: these patterns
+         * run against every line of every VBA file, where a user-supplied regex
+         * is a catastrophic-backtracking hazard. Entries EXTEND the built-in
+         * list (`db`, `getdb`, `CurrentDb`, `DBEngine`, the DAO `QueryDef`
+         * receivers, `DoCmd.RunSQL` and the ADO pair) — they never replace it.
+         * A non-array value, or an entry that is not one of the two forms,
+         * warns and is ignored.
+         */
+        sqlWrappers?: string[];
+        /**
+         * Issue #261 — extra module-level variable names this project uses as its
+         * error channel: the field a failing procedure writes and its caller
+         * reads, which is how an error message actually travels in an Access
+         * codebase of this shape (VBA's own mechanism unwinds one frame and is
+         * used for that, not for the message).
+         *
+         * Bare VBA identifiers only, matched as WHOLE names — `"lastFailure"`
+         * flags `lastFailure` and never `lastFailureCount`. Raw regular
+         * expressions are deliberately NOT accepted, for the same reason
+         * `sqlWrappers` refuses them: these names are tested against every
+         * identifier of every line of every VBA file. Entries EXTEND the built-in
+         * list (`m_Error`, `p_Error`, `g_Error`, `Error`) — they never replace
+         * it. A non-array value, or a non-identifier entry, warns and is ignored.
+         */
+        errorChannel?: string[];
     };
     /**
      * Gitignore-style patterns for first-party source to force INTO the index even
@@ -62,11 +95,19 @@ export interface ProjectConfig {
      */
     include?: string[];
 }
-export declare function loadVbaConfig(rootDir: string): {
+/**
+ * Parsed, validated view of the `vba` block. Named (rather than repeated
+ * inline at each of its five use sites) so adding a knob — `sqlWrappers` in
+ * #244 — is one edit instead of five that can silently drift apart.
+ */
+export interface VbaConfig {
     targets?: Record<string, boolean>;
     maxRaiseFanout?: number;
     dysflowExport?: boolean;
-};
+    sqlWrappers?: string[];
+    errorChannel?: string[];
+}
+export declare function loadVbaConfig(rootDir: string): VbaConfig;
 /**
  * Load the validated `vba.dysflowExport` flag for a project, mtime-cached
  * (issue #154). Returns `true` when the flag is absent — the default keeps

package/dist/resolution/index.d.ts

@@ -302,10 +302,55 @@ export declare class ReferenceResolver {
      * (enum, class, interface, struct, type_alias). Exactly one match →
      * repoint; zero or 2+ → decline (leave the stub as-is).
      *
-     * Duplicate `(source, target, 'references')` rows after repointing are
-     * collapsed the same way `resolveVbaCallStubs` handles F1 duplicates.
+     * Duplicate `(source, target, kind)` rows after repointing are collapsed the
+     * same way `resolveVbaCallStubs` handles F1 duplicates.
+     *
+     * Issue #257: `type_of` edges are repointed alongside `references` ones.
+     * They share the stub by construction (`emitTypeOf` and `emitReference` both
+     * go through `ensureSynthTypeNode`), and the stub is DELETED at the end of
+     * each iteration — with `ON DELETE CASCADE` on both endpoint columns, an
+     * un-repointed `type_of` edge would be silently destroyed rather than
+     * resolved. The de-duplication key carries the edge kind so a module's
+     * `references` edge and its parameter's `type_of` edge onto the same type
+     * cannot collapse into each other.
      */
     resolveVbaReferenceStubs(): number;
+    /**
+     * Promote Access ERD table declarations to canonical and repoint the
+     * SQL-derived placeholders onto them (#257, half B).
+     *
+     * Two extractors already synthesize a `class` placeholder for every table
+     * name they see in SQL text (`vba-sql-table` from in-code SQL,
+     * `sql-query-table` from a saved query), each keyed on the REFERENCING file.
+     * `AccessErdExtractor` emits its own table node keyed on the ERD document.
+     * Left alone, `TbAnexos` from the ERD and `TbAnexos` from a `SELECT` in a
+     * `.cls` are two unrelated nodes — the fields land on one, the references on
+     * the other, and the whole feature buys nothing.
+     *
+     * This pass is the convergence step, and it reuses the mechanism
+     * `resolveVbaCallStubs` already proved: repoint the incoming edges onto the
+     * canonical node, collapse would-be duplicates, delete the emptied
+     * placeholder, and stamp `metadata.repointDecision` on every edge it touched
+     * so the outcome is auditable (same vocabulary as `docs/vba-stub-repoint-
+     * decision.md`).
+     *
+     * Three deliberate declines:
+     *  - **No ERD declares this name** → leave the placeholder exactly as it is.
+     *    That is the no-ERD project, and its behavior must not change at all.
+     *  - **Two ERD files declare the same name** (two backends, same table) →
+     *    `declined-ambiguous`. Repoint nothing and keep both declarations; which
+     *    backend a bare `SELECT` meant is not something to guess.
+     *  - **The placeholder still has other edges** → keep the node. Only a
+     *    placeholder whose every edge has moved is deleted.
+     *
+     * Runs BEFORE `resolveVbaReferenceStubs` so this explicit, decision-stamping
+     * pass owns the outcome rather than the generic stub resolver silently
+     * arriving at half of it. Idempotent: a repointed placeholder is gone, so a
+     * second pass finds nothing to do.
+     *
+     * @returns the number of edges repointed onto an ERD table node.
+     */
+    resolveAccessErdTableNodes(): number;
     /**
      * Resolve a single VBA call-stub node to its real target, or `null` when
      * unresolvable/ambiguous. See `resolveVbaCallStubs` for the two-step

package/dist/resolution/name-matcher.d.ts

@@ -7,6 +7,31 @@ import { Node } from '../types';
 import { UnresolvedRef, ResolvedRef, ResolutionContext } from './types';
 /** Resolve Me.<Control> only inside the extractor-declared sibling layout. */
 export declare function matchVbaMeControl(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+/**
+ * Resolve a module-level variable read/write to that variable's node in
+ * the SAME file (issue #251).
+ *
+ * The binding is file-scoped and never falls through to global name
+ * matching. `m_count`, `strSQL` and `blnOk` are declared privately in
+ * dozens of modules of a typical Access project; a global match would
+ * pick one of them at random and claim a coupling between two modules
+ * that never reference each other. The extractor only emits these refs
+ * for names it already registered as module-level variables of the file
+ * being scanned, so the answer, when there is one, is always in that file.
+ */
+export declare function matchVbaModuleVariable(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+/**
+ * Issue #253: resolve a saved-query name to the `query` node that
+ * `SqlQueryExtractor` builds from `queries/<Name>.sql`.
+ *
+ * Query-kind only, and a miss DECLINES rather than falling through to global
+ * name matching. That is the whole point of the gate: a name matching neither
+ * a query nor a table must stay a `failed` reference, because a fallback that
+ * invented a table placeholder would turn "this query does not exist" into a
+ * confident, wrong answer — and a fallback to generic name matching could bind
+ * the name to an unrelated same-named class or procedure.
+ */
+export declare function matchVbaQueryName(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
 /** Resolve Access SourceObject embeddings only to a unique real layout node. */
 export declare function matchVbaSourceObject(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
 /** Keep a layout's sibling-code binding from resolving back to the layout. */

package/dist/resolution/vba-runtime-objects.d.ts

@@ -1,3 +1,4 @@
+import { isRuntimeObject as canonicalIsRuntimeObject } from '../extraction/vba/runtime-objects';
 /**
  * Canonical list of VBA/Access runtime objects and singletons whose
  * `Receiver.Member` calls are NEVER user-defined code — DAO, FileSystemObject
@@ -18,14 +19,15 @@
  * only falls back to this list when no real target exists, so a shadow
  * declaration is repointed exactly like any other real symbol (FR-2.1).
  *
- * NOTE — this is complementary to, NOT a duplicate of, the VBA extractor's
- * own `RUNTIME_RECEIVER_BLACKLIST` (`src/extraction/vba/constants.ts`). That
- * set is case-sensitive PascalCase and suppresses stub SYNTHESIS for the
- * common receivers at extraction time; this set is lowercased and catches the
- * runtime-object stubs that still reached the graph (lowercase receivers,
- * `Dim x As DAO.*` typed locals whose receiver survives as raw text, etc.).
- * The extractor blacklist deliberately stays untouched (AC-4: `src/extraction`
- * has 0 diff); the two layers are independent by design.
+ * Issue #245 — this used to be a SECOND literal, complementary to the VBA
+ * extractor's `RUNTIME_RECEIVER_BLACKLIST`. The two drifted: the extractor
+ * list omitted `VBA`, `fso`, `Collection` and `ListBox`, so those receivers
+ * kept synthesizing stub function NODES even though the resolver already
+ * declined their edges. Both sets now derive from one literal in
+ * `src/extraction/vba/runtime-objects.ts` (a leaf module — `src/extraction`
+ * must not import from `src/resolution`, so the canonical set lives on the
+ * extraction side and is re-exported here). Every existing
+ * `from '../src/resolution/vba-runtime-objects'` import keeps working.
  *
  * Entries are lowercased so matching is case-insensitive against a stub's
  * receiver.
@@ -36,9 +38,7 @@ export declare const RUNTIME_OBJECTS: ReadonlySet<string>;
  * Leading/trailing brackets and surrounding whitespace are stripped
  * defensively so a bracketed receiver (`[DAO]`) still matches.
  */
-export declare function isRuntimeObject(receiver: string | null | undefined): boolean;
-/** Canonical VBA and Access built-in functions that never resolve to project code. */
-export declare const VBA_STDLIB_FUNCTIONS: ReadonlySet<string>;
+export declare const isRuntimeObject: typeof canonicalIsRuntimeObject;
 export declare function isVbaStdlibFunction(name: string | null | undefined): boolean;
 /**
  * Issue #188 — VBA intrinsic constants and DAO enum values reach

package/dist/types.d.ts

@@ -10,12 +10,12 @@
  * of truth backs both the TS type and any runtime validation
  * (e.g. the search query parser).
  */
-export declare const NODE_KINDS: readonly ["file", "module", "class", "struct", "interface", "trait", "protocol", "function", "method", "property", "field", "variable", "constant", "enum", "enum_member", "event", "type", "type_member", "declare", "type_alias", "namespace", "parameter", "import", "export", "route", "component", "query", "form-layout", "form-instance-control", "report-layout"];
+export declare const NODE_KINDS: readonly ["file", "module", "class", "struct", "interface", "trait", "protocol", "function", "method", "property", "field", "variable", "constant", "enum", "enum_member", "event", "type", "type_member", "declare", "type_alias", "namespace", "parameter", "import", "export", "route", "component", "query", "form-layout", "form-instance-control", "report-layout", "label"];
 export type NodeKind = (typeof NODE_KINDS)[number];
 /**
  * Types of edges (relationships) between nodes
  */
-export type EdgeKind = 'contains' | 'calls' | 'imports' | 'exports' | 'extends' | 'implements' | 'references' | 'type_of' | 'returns' | 'instantiates' | 'overrides' | 'decorates' | 'event-handler' | 'opens-form' | 'opens-report' | 'raises-event' | 'subscribes-event' | 'type-member';
+export type EdgeKind = 'contains' | 'calls' | 'imports' | 'exports' | 'extends' | 'implements' | 'references' | 'type_of' | 'returns' | 'instantiates' | 'overrides' | 'decorates' | 'event-handler' | 'opens-form' | 'opens-report' | 'raises-event' | 'subscribes-event' | 'type-member' | 'handles-error';
 /**
  * Supported programming languages. See NODE_KINDS for why this is a
  * runtime-iterable const array.
@@ -175,7 +175,11 @@ export interface ExtractionError {
  * layer. The legacy `EdgeKind` literal `'references'` is preserved as
  * `references` here via `EdgeKind` — back-compat for any push site this
  * round does not reclassify (e.g. the Implements emitter). New literals:
- *   - `calls`            paren-form `Name(...)` or statement-form Sub call
+ *   - `calls`            paren-form `Name(...)`, or a statement-form Sub call
+ *                        whose syntax rules out a `Const` read (issue #265):
+ *                        `Call Escribir` (the `Call` keyword is only valid on
+ *                        a procedure) and `Escribir 1, 2` (a constant takes no
+ *                        argument list)
  *   - `qualified-call`   `Receiver.Member(...)` (qualified-paren) or
  *                        `Receiver.Member args` (qualified-statement)
  *   - `property-get`     `Me.Name` (dot access, read)
@@ -183,9 +187,13 @@ export interface ExtractionError {
  *   - `bang-get`         `Me!SubCtl` (bang read) or
  *                        `Forms!FormX!Ctl` / `Forms("FormX")!Ctl` (cross-form)
  *   - `bang-set`         `Me!SubCtl = value` (bang assignment)
- *   - `unqualified-ident` bare identifier without `(` after; default for
+ *   - `unqualified-ident` bare identifier with no `(` after it, no `Call`
+ *                        keyword and no argument list; default for
  *                        `HayErrorEnRiesgo`-style hits — Const-read takes
- *                        priority via FR-3.1 disambiguation
+ *                        priority via FR-3.1 disambiguation. That shape is
+ *                        genuinely ambiguous between a no-argument Sub call
+ *                        and a `Const` read, which is why it stays here while
+ *                        the two unambiguous statement forms are `calls`
  *   - `member-with`      `.Member` inside a `With <receiver>` block
  *   - `dao-query`        `DoCmd.OpenQuery "X"` argument
  * `dao-field-get` / `dao-field-set` are deliberately deferred to round-4.

package/dist/utils/backtrace-helpers.d.ts

@@ -28,8 +28,20 @@ export interface TraversalResult {
     warnings: string[];
 }
 /**
- * Traverses VBA call/relationship graphs starting from a specific node ID,
- * tracking cycles and capping search depth.
+ * Traverses the VBA execution graph from a node id, following the semantics
+ * the production extractor actually stores.
+ *
+ * Two directions are involved, which is the whole point of this helper:
+ *
+ * - An `event-handler` edge is stored HANDLER -> UI object (both for the
+ *   `<Control>_<Event>` code-behind convention and for `=Expression()`
+ *   wiring, which the resolver repoints the same way). So reaching a
+ *   handler from its control or layout means following that edge BACKWARDS.
+ * - A `calls` edge is stored CALLER -> CALLEE, so the rest of the path is
+ *   followed forwards.
+ *
+ * Starting from a handler still works: it simply has no incoming
+ * `event-handler` edge to expand, and its callees are found the usual way.
  */
 export declare function traverseGraph(db: SqliteDatabase, startNodeId: string, maxDepth?: number): TraversalResult;
 //# sourceMappingURL=backtrace-helpers.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aroman22/codegraph-vba",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Local-first code intelligence for AI agents (MCP). Self-contained — bundles its own runtime.",
   "bin": {
     "codegraph-vba": "npm-shim.js"
@@ -15,12 +15,12 @@
     "./package.json": "./package.json"
   },
   "optionalDependencies": {
-    "@aroman22/codegraph-vba-darwin-arm64": "1.15.0",
-    "@aroman22/codegraph-vba-darwin-x64": "1.15.0",
-    "@aroman22/codegraph-vba-linux-arm64": "1.15.0",
-    "@aroman22/codegraph-vba-linux-x64": "1.15.0",
-    "@aroman22/codegraph-vba-win32-arm64": "1.15.0",
-    "@aroman22/codegraph-vba-win32-x64": "1.15.0"
+    "@aroman22/codegraph-vba-darwin-arm64": "1.17.0",
+    "@aroman22/codegraph-vba-darwin-x64": "1.17.0",
+    "@aroman22/codegraph-vba-linux-arm64": "1.17.0",
+    "@aroman22/codegraph-vba-linux-x64": "1.17.0",
+    "@aroman22/codegraph-vba-win32-arm64": "1.17.0",
+    "@aroman22/codegraph-vba-win32-x64": "1.17.0"
   },
   "files": [
     "npm-shim.js",