@aroman22/codegraph-vba 1.15.0 → 1.17.0

package/dist/extraction/vba/sql-wrapper.d.ts

@@ -1,7 +1,68 @@
-import { VbaExtractorContext } from './context';
-export declare function scanSqlInLine(ctx: VbaExtractorContext, line: string, lineNum: number, dedupe: Set<string>, sqlVariables: Map<string, string>): void;
+import { VbaExtractorContext, ProcInfo } from './context';
 /**
- * #13 fix: `sql = sql & "..."` (self-referential concatenation) must
+ * Issue #252 — `metadata.synthesizedBy` for a table reached through SQL
+ * assigned to a binding property at RUNTIME. Deliberately distinct from the
+ * `.form.txt` sweep's static `vba-row-source` so an audit can tell the two
+ * provenances apart: one is what the designer stored, the other is what the
+ * code actually binds.
+ */
+export declare const RUNTIME_BINDING_SYNTHESIZER = "vba-row-source-dynamic";
+/**
+ * Issue #244 — the wrapper list used when `codegraph.json` →
+ * `vba.sqlWrappers` is absent. A STRICT SUPERSET of the pre-#244 behaviour:
+ *
+ *   - `db` covers every receiver the old `…db\b` regex reached (see
+ *     {@link receiverMatches} for the suffix arm that preserves it) plus the
+ *     `db`-prefixed locals it missed (`dbUse`, `dbToUse`, `m_dbLanzadera`).
+ *   - `getdb` covers the per-backend accessor family (`getdbHPS()`,
+ *     `getdbExpedientes()`, `getdbLanzadera()`) the issue measured at 26-36%
+ *     of all execution sites.
+ *   - `CurrentDb` / `DBEngine` are the Access built-ins.
+ *   - `qd` / `qdf` are the conventional DAO `QueryDef` receivers.
+ *   - `DoCmd.RunSQL` is the Access statement form (both the literal and the
+ *     variable spelling, previously two dedicated regexes).
+ *   - `Connection.Execute` / `Recordset.Open` are the ADO pair.
+ *
+ * Project-specific accessors that do not fit these names are added through
+ * `vba.sqlWrappers`, which EXTENDS this list rather than replacing it.
+ */
+export declare const DEFAULT_SQL_WRAPPERS: readonly string[];
+/** One parsed wrapper entry. Both fields are lowercase — VBA is case-insensitive. */
+interface SqlWrapperMatcher {
+    /** Receiver name fragment, e.g. `getdb` from `"getdb"` or `cnn` from `"cnn.Execute"`. */
+    receiver: string;
+    /** Method name, or `null` for a bare entry (which implies {@link DEFAULT_WRAPPER_METHODS}). */
+    method: string | null;
+}
+/**
+ * The per-extractor compiled wrapper state. Built ONCE per `VbaExtractor`
+ * (see `vba-extractor.ts`) and cached on `VbaExtractorContext` — the two
+ * RegExps are stateful (`/g`) and `scanSqlInLine` runs on every line of every
+ * file, so re-compiling them per line (which is what the pre-#244 code did)
+ * is pure waste on the hottest path in VBA extraction.
+ */
+export interface CompiledSqlWrappers {
+    /** Literal form — `<receiver>[()].<method> "…"`. Stateful; reset before use. */
+    readonly literalRe: RegExp;
+    /** Variable form — `<receiver>[()].<method> <identifier>`. Stateful; reset before use. */
+    readonly varRe: RegExp;
+    /** Parsed entries, defaults first, project entries appended. */
+    readonly matchers: readonly SqlWrapperMatcher[];
+}
+/**
+ * Parse the plain-string wrapper entries into matchers and pair them with a
+ * fresh pair of scanning RegExps.
+ *
+ * `configured` entries are APPENDED to {@link DEFAULT_SQL_WRAPPERS}, never
+ * substituted for them: a project that names its own accessor must not lose
+ * `CurrentDb` in the trade. Entries are accepted in exactly two forms — a
+ * bare identifier fragment (`"getdb"`) or a `receiver.method` pair
+ * (`"cnn.Execute"`). Anything else is dropped here; `project-config.ts`
+ * already warned about it at load time.
+ */
+export declare function compileSqlWrappers(configured?: readonly string[]): CompiledSqlWrappers;
+/**
+ * Issue #13: `sql = sql & "..."` (self-referential concatenation) must
  * ACCUMULATE the new fragment onto whatever was already tracked for
  * `varName`, not overwrite it. Overwriting silently dropped earlier
  * fragments' tables — typically the initial `FROM <table>` in
@@ -14,4 +75,16 @@ export declare function scanSqlInLine(ctx: VbaExtractorContext, line: string, li
  * behavior is unchanged.
  */
 export declare function trackSqlVariableAssignment(lines: string[], lineIndex: number, sqlVariables: Map<string, string>): void;
+/**
+ * Issue #255: scan one line for domain-aggregate calls and emit the saved-query
+ * reference their second argument names.
+ *
+ * Deliberately NOT handled: a domain spelled as a full SQL statement
+ * (`DLookup("N", "SELECT Id FROM T")`), which Access also accepts. It is
+ * rejected by `looksLikeSavedQueryName`'s verb gate and produces nothing —
+ * the same silence T11 chose for every literal it cannot classify.
+ */
+export declare function scanDomainFunctionsInLine(ctx: VbaExtractorContext, line: string, lineNum: number, dedupe: Set<string>, caller: ProcInfo): void;
+export declare function scanSqlInLine(ctx: VbaExtractorContext, line: string, lineNum: number, dedupe: Set<string>, sqlVariables: Map<string, string>, caller?: ProcInfo): void;
+export {};
 //# sourceMappingURL=sql-wrapper.d.ts.map

package/dist/extraction/vba/text-utils.d.ts

@@ -11,8 +11,17 @@ export declare function foldVisibility(raw: string): 'public' | 'private';
  * call-site patterns inside `"..."` spans are invisible to CALL_RE and
  * the statement-form detectors.  Column positions are preserved (each
  * character is replaced 1-for-1) so any col-based metadata stays correct.
+ *
+ * Issue #265: `filler` selects the replacement character. The default `' '`
+ * is what every column-sensitive scanner wants — a masked literal reads as
+ * blank space. The statement-call detectors need the opposite: they must
+ * still be able to tell `MsgBox "x"` (an argument list, therefore
+ * unambiguously a call) from a bare `MsgBox` read, and a space-masked line
+ * collapses the two. Passing `'_'` keeps the literal *visible* as an opaque
+ * token while preserving both the 1-for-1 column mapping and the property
+ * that nothing inside the literal can be parsed as VBA syntax.
  */
-export declare function maskStringContent(line: string): string;
+export declare function maskStringContent(line: string, filler?: string): string;
 /**
  * #13 helper: escape a variable name for safe interpolation into the
  * self-reference RegExp built by `trackSqlVariableAssignment`. VBA
@@ -26,7 +35,6 @@ export declare function parseConstDeclarations(body: string): Array<{
     asType: string;
     value: string | null;
 }>;
-export declare function splitOutsideVbaStrings(value: string, separator: string): string[];
 /**
  * Issue #50 helper: return true iff `line.charAt(fromIndex..)` (after the
  * matched TempVars site, including any trailing whitespace) holds an `=`
@@ -65,4 +73,56 @@ export declare function parseEventHandlerName(name: string): {
     controlName: string;
     eventName: string;
 } | null;
+/**
+ * Issue #247 helper: parse a FORM-LEVEL Access event-handler Sub name.
+ *
+ * `parseEventHandlerName` above deliberately refuses `Form_*` because a
+ * form-level event fires on the form object, not on a control — routing it
+ * through the control path would synthesize a bogus `form-instance-control`
+ * node literally named `Form`. This helper is the other half of that
+ * decision: it recognises exactly the names the control parser rejects and
+ * hands them to the caller so they can be wired to the sibling
+ * `form-layout` / `report-layout` node instead.
+ *
+ * The owner segment must be exactly `Form` or `Report` (case-insensitive,
+ * matching VBA's case-insensitive identifiers), and the suffix must be a
+ * known Access event name. That second gate is what separates the real
+ * lifecycle handler `Form_Load` from an ordinary class method that merely
+ * happens to be called `Form_Helper`.
+ */
+export declare function parseFormLevelEventHandlerName(name: string): {
+    ownerName: string;
+    eventName: string;
+} | null;
+/**
+ * Sibling layout extension implied by an Access code-behind prefix.
+ * `Form_*` binds to a `.form.txt`; `Report_*` binds to a `.report.txt`.
+ */
+export type CodeBehindExt = '.form.txt' | '.report.txt';
+/**
+ * Issue #249 helper: the `Form_` / `Report_` code-behind prefix carried by a
+ * module's RESOLVED `Attribute VB_Name`, used as the fallback when the file
+ * on disk does not carry the prefix in its basename.
+ *
+ * Both binding sites (the event-handler synthesis in `procedures.ts` and the
+ * `Me.<Control>` sweep in `controls.ts`) keep their own basename check as the
+ * fast path and consult this only on a basename miss, so the common case —
+ * a Dysflow export whose filename and `VB_Name` agree — is byte-for-byte
+ * unchanged.
+ *
+ * `classNamePrefix` is `null` for `.bas` modules and holds the resolved
+ * `VB_Name` (or the extension-stripped basename when the module carries no
+ * `VB_Name`) for `.cls` modules, so this fallback can only ever fire for a
+ * class module. That is deliberate: the guard that keeps a plain service
+ * class such as `InformeRiesgoPDFServicio.cls` — whose methods
+ * (`GenerarHTML_Principal`, `GetEstilosCSS_PDF`) look like event handlers to
+ * a naive `<X>_<Y>` split — from synthesizing hundreds of spurious
+ * `form-instance-control` stubs is that NEITHER its filename NOR its
+ * `VB_Name` starts with `Form_` / `Report_`. Widening the prefix test would
+ * reopen exactly that hole, so the test stays the same canonical Access
+ * naming convention; only the string it is applied to widens.
+ *
+ * The trailing `.+` is load-bearing: a bare `Form_` names no form.
+ */
+export declare function codeBehindExtFromVbName(classNamePrefix: string | null): CodeBehindExt | null;
 //# sourceMappingURL=text-utils.d.ts.map

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

@@ -1,4 +1,5 @@
 import { ExtractionResult } from '../types';
+import type { VbaExtractionOptions } from './vba/options';
 import type { VbaExtractionRule } from './vba/rules';
 /**
  * Issue #152: per-file fanout cap for `RaiseEvent <EventName>` edges. An
@@ -62,7 +63,6 @@ export declare class VbaExtractor {
     private filePath;
     private source;
     private ctx;
-    private vbaTargets?;
     /**
      * Issue #152: per-file fanout cap for `RaiseEvent <EventName>` edges.
      * When a single event is raised more than this many times in one file,
@@ -72,6 +72,23 @@ export declare class VbaExtractor {
      * the orchestrator: callers that don't pass a value get the default.
      */
     private maxRaiseFanout;
+    /**
+     * Issue #243: the full options object, retained so classifiers that grow
+     * a new knob read it from one place instead of a new private field per
+     * knob. `targets`/`maxRaiseFanout` keep their dedicated fields because
+     * they are read on hot paths.
+     */
+    private options;
+    /**
+     * Issue #243 — the options-object form. Every in-repo call site uses this.
+     */
+    constructor(filePath: string, source: string, options?: VbaExtractionOptions);
+    /**
+     * @deprecated Pass a {@link VbaExtractionOptions} object instead:
+     * `new VbaExtractor(filePath, source, { targets, maxRaiseFanout })`.
+     * The positional 3rd/4th parameters are kept working for one release so
+     * out-of-repo callers are not broken by #243; they will be removed after.
+     */
     constructor(filePath: string, source: string, vbaTargets?: Record<string, boolean>, maxRaiseFanout?: number);
     extract(): ExtractionResult;
     /**

package/dist/extraction/vba-form-extractor.d.ts

@@ -17,6 +17,14 @@ export declare class VbaFormExtractor {
      * stays self-contained per the project's per-extractor state rule).
      */
     private synthClassNodeIds;
+    /**
+     * Issue #256: external-backend (`IN "<path>"`) node ids already emitted
+     * for this form. Same per-extractor de-dup discipline as
+     * `synthClassNodeIds`, keyed on the node id — which is derived from the
+     * NORMALIZED backend path, so two bindings naming the same `.accdb`
+     * share one node while each still emits its own edge.
+     */
+    private externalBackendNodeIds;
     constructor(filePath: string, source: string);
     extract(): ExtractionResult;
     private createFileNode;
@@ -63,23 +71,11 @@ export declare class VbaFormExtractor {
     private emitExpressionHandlers;
     private emitExpressionHandler;
     private emitSourceObjectReference;
-    /**
-     * Issue #49 — copy of `VbaExtractor.SQL_TABLE_RE`. Same source / flags:
-     * captures the table name that follows `FROM`/`JOIN`/`INTO`/`UPDATE`,
-     * tolerates bracketed `[Order Details]` identifiers and `\p{L}` Unicode
-     * identifiers, and allows an optional schema prefix (`[dbo].[tblA]`).
-     *
-     * We duplicate the regex (rather than exporting it from `VbaExtractor`)
-     * because `VbaExtractor.SQL_TABLE_RE` is `private static` and the
-     * project's per-extractor state rule keeps each extractor's helpers
-     * self-contained — see the file-level JSDoc on `VbaExtractor`.
-     */
-    private static readonly SQL_TABLE_RE;
     /**
      * Issue #49 — classify a RecordSource/RowSource value as SQL.
      * Anything starting with a SQL keyword (`SELECT`, `PARAMETERS`, `WITH`,
      * `UPDATE`, `INSERT`, `DELETE`) — case-insensitive — is treated as a
-     * SQL statement and run through `SQL_TABLE_RE`. Anything else is a
+     * SQL statement and run through `scanSqlTables`. Anything else is a
      * bare table-or-query name and emitted as a single reference.
      *
      * `WITH` is included because Access/JET supports CTE-style `WITH` queries
@@ -103,6 +99,20 @@ export declare class VbaFormExtractor {
      * name — same dual-match `vba-sql-impact`'s `extractFormBindings` does).
      */
     private emitTableReference;
+    /**
+     * Issue #256 — emit one `references` edge from `sourceNodeId` to the
+     * external database file an Access `IN "<path>"` clause points at.
+     *
+     * The target node is built by the shared `buildExternalBackendNode` so
+     * it is byte-identical to the node the in-code SQL sweep and the saved-
+     * query extractor emit for the same path: the graph ends up with ONE
+     * node per external backend, however many places name it. The edge
+     * carries only `synthesizedBy` — the `external` / `backendPath` facts
+     * describe the node, and live there.
+     *
+     * `backendPath` is already normalized by `scanSqlExternalBackends`.
+     */
+    private emitExternalBackendReference;
     /**
      * Link a bound control to its enclosing form/report's single bare table.
      * Expressions and SQL/absent RecordSource values stay metadata-only: column
@@ -112,7 +122,7 @@ export declare class VbaFormExtractor {
     private emitControlSourceReference;
     /**
      * Issue #49 — dispatch the value of a RecordSource/RowSource binding.
-     * If SQL, run `SQL_TABLE_RE` over the value and emit one edge per
+     * If SQL, run `scanSqlTables` over the value and emit one edge per
      * distinct table (within-value dedup so `FROM tblA JOIN tblA` emits a
      * single edge). If a bare name, emit a single edge with the name as-is
      * — the resolver handles the dual-match against `query` and `class`
@@ -122,6 +132,10 @@ export declare class VbaFormExtractor {
      * the regex capture already includes them as part of the value, so a
      * single `.replace(/""/g, '"')` collapses them — same technique the
      * `extractStringLiterals` helper uses for its emitted `text` field.
+     *
+     * Issue #203: `scanSqlTables` also drops SQL reserved-word captures
+     * (`WHERE`, `ORDER`, `SET`, …) so a malformed SQL string never
+     * poisons the graph with phantom `class` nodes.
      */
     private emitBinding;
 }

package/dist/extraction/vba-preprocess.d.ts

@@ -32,6 +32,7 @@
  *
  * Source unchanged guarantee: every helper treats `src` as read-only.
  */
+import type { ExtractionError } from '../types';
 /**
  * Collapse VBA line continuations: any line whose last non-newline character is
  * `_` (preceded by exactly one space, per VBA convention) is joined to the
@@ -93,8 +94,36 @@ export declare function stripVbaComments(src: string): string;
  * promote this evaluator to full integer arithmetic.
  *
  * Directives and inactive branch lines are replaced with empty strings so
- * downstream extraction keeps source-line parity. Unsupported/unsafe
- * expressions evaluate to false rather than throwing.
+ * downstream extraction keeps source-line parity.
+ *
+ * **Issue #206 contract change.** Previously the docstring read
+ * *"Unsupported/unsafe expressions evaluate to false rather than
+ * throwing"* — accurate, but it framed silent whole-branch source
+ * deletion as a safety property. It was not: false-negative extraction is
+ * indistinguishable from correct extraction to every downstream consumer
+ * (an `#If MODE = "DEBUG" Then` whose `"` throws silently blanks the
+ * branch and the symbol vanishes from the graph).
+ *
+ * The new contract:
+ *
+ *   1. **Unterminated `#If`/`#ElseIf`**: if the directive stack is
+ *      non-empty after the loop ends, an `ExtractionError` (severity
+ *      `warning`, code `unterminated_if`) is pushed onto the optional
+ *      `errors` array AND the un-blanked lines from the earliest
+ *      unclosed `#If` are re-emitted. An unterminated `#If` is far
+ *      more likely a typo than a genuinely dead file tail.
+ *   2. **Could-not-evaluate expressions**: `evaluateConditionalExpression`
+ *      now distinguishes `evaluated: false` (a definitive false — e.g.
+ *      `#If 0 Then`, unknown identifier falling through to 0) from
+ *      `could-not-evaluate` (the lexer/parser hit an unsupported token,
+ *      or `tokenize`/`parse` threw). On could-not-evaluate, the branch
+ *      is **kept active** (conservative for a code-intelligence tool —
+ *      a spurious symbol is recoverable, a missing one is invisible)
+ *      and a warning is emitted through the same `errors` channel.
+ *
+ * The `errors` channel is OPTIONAL — every existing call site (and
+ * existing test) continues to work without it. The orchestrator can
+ * supply it to surface the warnings through `ctx.errors`.
  */
 export declare function preprocessConditionalCompilation(src: string, customTargets?: Record<string, boolean>, 
 /**
@@ -106,7 +135,64 @@ export declare function preprocessConditionalCompilation(src: string, customTarg
  * inner sub-totals. Undefined → no-op, zero cost (just the
  * `if (timings)` null-check on every CC line).
  */
-timings?: Map<string, number> | null): string;
+timings?: Map<string, number> | null, 
+/**
+ * Issue #206: optional `ExtractionError` sink for diagnostics the
+ * preprocessor wants to surface to extraction callers:
+ *   - `unterminated_if` (warning) — `#If` / `#ElseIf` pushed but
+ *     never closed by `#End If` (a likely typo).
+ *   - `unparseable_expression` (warning) — a `#If` / `#ElseIf`
+ *     expression the lexer/parser could not handle (the branch is
+ *     still kept active under the conservative contract).
+ *
+ * Undefined → no-op, zero cost (the `if (errors)` null-check on
+ * every warning site). The orchestrator passes `this.ctx.errors` so
+ * the warnings route through `ExtractionResult.errors`.
+ */
+errors?: ExtractionError[], 
+/**
+ * Issue #206: optional file path included on every pushed error
+ * when the caller wants telemetry to know which file the warning
+ * came from. Independent of `errors` so a caller can attach the
+ * path even when collecting warnings elsewhere.
+ */
+filePath?: string): string;
+/**
+ * Issue #206 discriminated return value for `evaluateConditionalExpression`.
+ *
+ *   - `{ kind: 'evaluated', value }` — the lexer+parser produced a
+ *     definitive answer. `value` is the truthiness of the expression
+ *     under VBA semantics (non-zero = true).
+ *   - `{ kind: 'could-not-evaluate' }` — the lexer/parser threw
+ *     (unsupported token: string literal, floating-point literal,
+ *     unrecognized character, mismatched paren, etc.). The caller MUST
+ *     treat this as ACTIVE under the conservative contract from
+ *     Issue #206 — see `preprocessConditionalCompilation`.
+ */
+export type ConditionalEvaluation = {
+    readonly kind: 'evaluated';
+    readonly value: boolean;
+} | {
+    readonly kind: 'could-not-evaluate';
+};
+/**
+ * Issue #206: marker error class for explicitly-unsupported VBA
+ * conditional-compilation tokens. The legacy `throw new Error(...)`
+ * from `tokenize` was indistinguishable from a real bug
+ * (`Unexpected trailing token`, mismatched paren); both bubbled into
+ * the same `catch { return false }`. The new helper carries the
+ * specific reason so the caller can attribute warnings precisely and
+ * distinguish "the lexer simply cannot handle this token" from a
+ * legitimate parse failure (which is also routed to
+ * could-not-evaluate, but with the original message preserved).
+ */
+export declare class UnparseableExpressionError extends Error {
+    /** Coarse category: `string_literal`, `float_literal`, `unsupported_character`. */
+    readonly reason: string;
+    /** The verbatim fragment that triggered the throw (for diagnostics). */
+    readonly fragment: string;
+    constructor(reason: string, fragment: string);
+}
 export interface StringLiteralSpan {
     /** The literal content (no surrounding quotes; `""` collapsed to `"`). */
     text: string;

package/dist/extraction/vba-source.d.ts

@@ -45,14 +45,4 @@ export interface ReadVbaSourceResult {
  * @param opts optional dependencies; see {@link ReadVbaSourceOptions}.
  */
 export declare function readVbaSource(filePath: string, opts?: ReadVbaSourceOptions): ReadVbaSourceResult;
-/**
- * String-level BOM strip — survives when the upstream `fsp.readFile(path, 'utf-8')`
- * already decoded the bytes (it's the only way the `\uFEFF` char survives in
- * a string). Used as a defensive last resort when a read site has NOT gone
- * through `readVbaSource` and the source text starts with the BOM marker.
- *
- * Most call sites should prefer `readVbaSource` for fresh reads; this is
- * a string post-process for callers that already have a `string` in hand.
- */
-export declare function stripUtf8Bom(text: string): string;
 //# sourceMappingURL=vba-source.d.ts.map

package/dist/extraction/vba-test-manifest-extractor.d.ts

@@ -1,10 +1,4 @@
 import { ExtractionResult } from '../types';
-/**
- * Content-shape gate: is `parsed` a VBA test manifest — a top-level `tests`
- * array with at least one item carrying a string `procedure`? Pure; the file's
- * basename is gated separately by `isVbaTestManifestFile` in `grammars.ts`.
- */
-export declare function isVbaTestManifestShape(parsed: unknown): boolean;
 export declare class VbaTestManifestExtractor {
     private filePath;
     private source;

package/dist/graph/behavior-evidence.d.ts

@@ -0,0 +1,162 @@
+import { QueryBuilder } from '../db/queries';
+/**
+ * The consumer compatibility payload.
+ *
+ * Field types are fixed by the consumer that reads them (Dysflow's
+ * `CodeGraphBehaviorEvidence`) and must not be widened here.
+ */
+export interface CodeGraphBehaviorEvidence {
+    /** Name of the procedure the event is bound to. */
+    handler: string;
+    /**
+     * One root-to-leaf execution path, handler first, callees in the order the
+     * graph stores them (by node id, so the output is stable across runs).
+     * Distinct branches are separate entries — they are never concatenated into
+     * a single sequence the runtime would not take. A path that re-enters a
+     * procedure already on it ends there, repeating that name once.
+     */
+    callPath: string[];
+    /** Tables reached along this path, directly or through a saved query. */
+    tables?: string[];
+    /** See {@link BEHAVIOR_EFFECT_VOCABULARY}. */
+    effects?: string[];
+}
+/**
+ * The closed vocabulary of `effects` strings. Anything outside this list is a
+ * bug, not a new fact.
+ *
+ * - `read:<name>` / `write:<name>` — a data reference the extractor typed.
+ * - `data-access:<name>` — a data reference whose direction is unknown.
+ *   NOT a read and NOT a write; it means the index cannot say.
+ * - `opens-form:<Name>` / `opens-report:<Name>` — an Access object opened.
+ * - `raises-event:<Name>` — an event raised from the path.
+ */
+export declare const BEHAVIOR_EFFECT_VOCABULARY: readonly ["read:<name>", "write:<name>", "data-access:<name>", "opens-form:<Name>", "opens-report:<Name>", "raises-event:<Name>"];
+/** How a handler is bound to the thing it answers for. */
+export type BehaviorBindingScope = 
+/** `<Control>_<Event>` code-behind on a control. */
+'control'
+/** The form's or report's own lifecycle event. */
+ | 'form'
+/** An `=Expression()` property on the control or layout. */
+ | 'expression'
+/** The request named a procedure directly; no binding was involved. */
+ | 'direct';
+export interface BehaviorEvidenceRequest {
+    /** Stable node id. The unambiguous form — always prefer it. */
+    nodeId?: string;
+    /** Control, handler or layout name. Requires `layout` when not unique. */
+    name?: string;
+    /**
+     * Layout context for `name`: a form/report name or its layout file name.
+     * Without it an ambiguous name is REFUSED, never silently narrowed to the
+     * first match.
+     */
+    layout?: string;
+    /** Call-path depth budget. Default 5, clamped to 1..20. */
+    maxCallDepth?: number;
+    /** Maximum evidence entries. Default 50, clamped to 1..500. */
+    maxResults?: number;
+}
+export interface BehaviorEvidenceTarget {
+    id: string;
+    name: string;
+    kind: string;
+    filePath: string;
+    /** Owning form/report, from the layout's `contains` edge. */
+    layout: string | null;
+}
+export interface BehaviorHandlerContext {
+    handler: string;
+    handlerId: string;
+    /** Access event name (`Click`, `Load`, …), or null when not bound. */
+    event: string | null;
+    scope: BehaviorBindingScope;
+    provenance: string;
+    /** `file:line` of the wiring site. */
+    location: string;
+    /** `metadata.synthesizedBy` of the binding edge, when present. */
+    wiredBy: string | null;
+}
+export interface BehaviorDataEvidence {
+    /** Procedure the reference was attributed to. */
+    procedure: string;
+    name: string;
+    /** Node kind of the referenced object (`class`, `table`, `query`, …). */
+    targetKind: string;
+    access: 'read' | 'write' | 'unknown';
+    /** `metadata.synthesizedBy` of the reference edge. */
+    via: string | null;
+    /** Set when the table was reached through a saved query. */
+    throughQuery?: string;
+    /**
+     * `edge-source` — the reference edge starts at the procedure itself.
+     * `source-line` — it starts at the module node and was attributed to this
+     * procedure because the edge's line falls inside its range.
+     */
+    attributedBy: 'edge-source' | 'source-line';
+    location: string;
+}
+export interface BehaviorAmbiguity {
+    name: string;
+    matches: Array<{
+        id: string;
+        kind: string;
+        filePath: string;
+        layout: string | null;
+    }>;
+}
+export interface BehaviorUnresolvedReference {
+    /** Procedure the unresolved reference sits in, when it could be attributed. */
+    procedure: string | null;
+    referenceName: string;
+    referenceKind: string;
+    location: string;
+}
+export interface BehaviorEvidenceResult {
+    /** What the request resolved to, or null when it resolved to nothing. */
+    target: BehaviorEvidenceTarget | null;
+    /** The consumer compatibility payload. */
+    evidence: CodeGraphBehaviorEvidence[];
+    context: {
+        handlers: BehaviorHandlerContext[];
+        data: BehaviorDataEvidence[];
+        unresolved: BehaviorUnresolvedReference[];
+        /** Populated only when a name matched more than one node. */
+        ambiguous: BehaviorAmbiguity[];
+        truncated: {
+            /** A path hit `maxCallDepth` and was cut short. */
+            callDepth: boolean;
+            /** Entries were dropped at `maxResults`. */
+            results: boolean;
+            /** A path re-entered a procedure already on it. */
+            cycle: boolean;
+        };
+        /** See {@link BEHAVIOR_EVIDENCE_NOTES}. */
+        notes: string[];
+    };
+}
+/**
+ * The closed vocabulary of `context.notes`.
+ *
+ * - `MISSING_TARGET_SELECTOR` — neither `nodeId` nor `name` was given.
+ * - `TARGET_NOT_FOUND` — nothing in the index matches. A lookup miss, not
+ *   proof the control has no behavior.
+ * - `AMBIGUOUS_TARGET` — the name matches several nodes; see
+ *   `context.ambiguous`. No evidence is returned, and nothing is guessed.
+ * - `NO_HANDLER_BOUND` — the target exists but no handler is wired to it in
+ *   the index. Access macros and `[Event Procedure]` entries with no
+ *   code-behind land here.
+ * - `STATIC_SOURCE_EVIDENCE` — always present. The answer comes from indexed
+ *   exported source: it does not prove the code ran, and it says nothing
+ *   about whether the `.accdb` binary matches the export.
+ */
+export declare const BEHAVIOR_EVIDENCE_NOTES: readonly ["MISSING_TARGET_SELECTOR", "TARGET_NOT_FOUND", "AMBIGUOUS_TARGET", "NO_HANDLER_BOUND", "STATIC_SOURCE_EVIDENCE"];
+/**
+ * Assembles behavior evidence for one control, layout or handler.
+ *
+ * Pure read path over {@link QueryBuilder}: no new SQL, no second traversal
+ * implementation, no writes.
+ */
+export declare function buildBehaviorEvidence(queries: QueryBuilder, request: BehaviorEvidenceRequest): BehaviorEvidenceResult;
+//# sourceMappingURL=behavior-evidence.d.ts.map

package/dist/index.d.ts

@@ -5,6 +5,7 @@
  * knowledge graph from any codebase.
  */
 import { Node, Edge, FileRecord, ExtractionResult, Subgraph, TraversalOptions, SearchOptions, SearchResult, SegmentMatch, Context, GraphStats, TaskInput, TaskContext, BuildContextOptions, FindRelevantContextOptions } from './types';
+import { BehaviorEvidenceRequest, BehaviorEvidenceResult } from './graph/behavior-evidence';
 import { IndexProgress, IndexResult, SyncResult } from './extraction';
 import { ResolutionResult } from './resolution';
 import { WatchOptions, PendingFile } from './sync';
@@ -16,6 +17,7 @@ export { IndexProgress, IndexResult, SyncResult } from './extraction';
 export { detectLanguage, isLanguageSupported, isGrammarLoaded, getSupportedLanguages, initGrammars, loadGrammarsForLanguages, loadAllGrammars } from './extraction';
 export { ResolutionResult } from './resolution';
 export { CodeGraphError, FileError, ParseError, DatabaseError, SearchError, VectorError, ConfigError, Logger, setLogger, getLogger, silentLogger, defaultLogger, } from './errors';
+export { buildBehaviorEvidence, BEHAVIOR_EFFECT_VOCABULARY, BEHAVIOR_EVIDENCE_NOTES, CodeGraphBehaviorEvidence, BehaviorEvidenceRequest, BehaviorEvidenceResult, BehaviorEvidenceTarget, BehaviorHandlerContext, BehaviorDataEvidence, BehaviorAmbiguity, BehaviorUnresolvedReference, BehaviorBindingScope, } from './graph/behavior-evidence';
 export { Mutex, FileLock, processInBatches, debounce, throttle, MemoryMonitor } from './utils';
 export { FileWatcher, WatchOptions, PendingFile, LockUnavailableError } from './sync';
 export { MCPServer } from './mcp';
@@ -527,6 +529,26 @@ export declare class CodeGraph {
      * @returns Subgraph containing potentially impacted nodes
      */
     getImpactRadius(nodeId: string, maxDepth?: number): Subgraph;
+    /**
+     * Assemble bounded behavior evidence for an Access control, layout or
+     * handler (issue #299).
+     *
+     * Read-only: it joins facts that are already indexed — the event binding,
+     * the call paths under it, and the tables/effects those procedures reach —
+     * into one typed payload, so a consumer does not re-implement the graph
+     * semantics for itself. It never parses source, opens Access, or writes to
+     * the index.
+     *
+     * Identify the target by `nodeId` whenever you have one. A `name` needs a
+     * `layout` as soon as it is not unique: an ambiguous name is REFUSED with
+     * the candidates listed, never narrowed to an arbitrary first match.
+     *
+     * The answer is static evidence from exported source. An empty `tables` or
+     * `effects` list means the index holds no such fact — not that the code has
+     * no runtime effect. See {@link BehaviorEvidenceResult.context} for what
+     * could not be answered.
+     */
+    getBehaviorEvidence(request: BehaviorEvidenceRequest): BehaviorEvidenceResult;
     /**
      * Find the shortest path between two nodes
      *

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

@@ -52,6 +52,12 @@ export declare function getDaemonSocketCandidates(projectRoot: string): string[]
 export declare function getDaemonSocketPath(projectRoot: string): string;
 /** Absolute path to the daemon pid lockfile for `projectRoot`. */
 export declare function getDaemonPidPath(projectRoot: string): string;
+/** Root-scoped lease held while intentional release owns lifecycle cleanup. */
+export declare function getDaemonReleaseLeasePath(projectRoot: string): string;
+/** Exclusive marker for release-lease recovery/heartbeat publication. */
+export declare function getDaemonReleaseRecoveryPath(projectRoot: string): string;
+/** Short root-scoped arbitration lock shared by startup and release publication. */
+export declare function getDaemonLifecyclePath(projectRoot: string): string;
 /** Structured contents of the pid lockfile. */
 export interface DaemonLockInfo {
     pid: number;