ADR 0043 — Typed compiler snapshots for static Query Lab

Status: accepted design for LAB-SNAPSHOT / LAB-REPORT; acceptance remains tied to executed checks.

Query Lab consumes existing registered query evidence, V1 planning and V2 comparisons. It does not load/evaluate arbitrary C# source, implement another Cypher parser, own a second model or add a query executor. The final EF model and Fluent compiler determine bindings. The first UI remains a self-contained HTML report; the user-selected VS Code/TypeScript/React extension and optional MCP Apps adapter are subsequent FUT-19 work. No GUI dependencies enter provider or Tooling packages.

Provider inspection is explicit: CypherResultQuery.Inspect() returns the command plus an immutable typed Semantics snapshot. Prepare(true) retains that snapshot with the original compiled command/reader for evidence tied to execution. Normal ToCommand/Prepare/ToList paths do not allocate clause/pattern snapshots. Instrument existing successful rendering/binding; do not re-render expressions or re-evaluate projection factories, which could alter parameters or captured state. Source spans identify one-based lines in the generated command, not invented C# source positions.

Snapshots distinguish pattern occurrences, compiler alias identity, traversal direction and physically mapped source/target aliases for scalar relationships. Repeated/undirected paths retain outer endpoints, direction, named path and finite bounds but do not pretend each internal edge has those endpoints. Clauses preserve MATCH/OPTIONAL/WITH order and attached WHERE predicates; WITH records kept/dropped aliases and exact already-rendered aggregate expressions. RETURN switches to actual generated result-column names. Snapshot nodes represent query variables, never observed database entities.

The first snapshot handles the three required movie examples plus existing bounded paths and clause/paging shapes. Nested EXISTS lexical expansion is intentionally explicit as unavailable; its full query still compiles and remains visible without an invented partial graph. Cap snapshots at 256 clauses and 4,096 pattern elements; any exceeded bound omits all diagram clauses without rejecting/truncating the compiled query. Existing compilation errors remain errors. Extend nested-scope support only with faithful lexical identities and independent tests.

Snapshot names/expressions disclose mapped metadata. Shared GraphQueryEvidence retains them only with the existing explicit includeStatements disclosure; default Doctor/Verify exports and compilation costs remain unchanged. Disclosure triggers one factory invocation and one compilation for both command and typed snapshot. V2 prepares once and retains the same snapshot with actual execution. Parameter values, EF/CLR objects, context/execution delegates and exception text never become part of the snapshot. The renderer must HTML-escape all data and must not execute source text or external resources. No query work occurs merely by opening/rendering evidence.

Acceptance expectations: actual sample text/parameter equivalence with inspection disabled/enabled, correct incoming edge roles and repeated-edge identity, WITH counts versus physical rows, OPTIONAL WHERE versus post-WITH distinction, line spans and paging, bounded-path honesty, no transport, deterministic immutable snapshots, explicit omissions and dropped-alias failures. Verify shared default redaction and opt-in exact prepared evidence. Report acceptance later includes escaped self-contained HTML, no-JS/print use, all three real queries and actual V1/V2 observations.

LAB-SNAPSHOT accepted (12 October 2026): 258 Tooling units pass, including 11 new snapshot cases and one V2 prepared-snapshot case; 57 focused Fluent/native provider regressions pass. Actual three-movie source factories validate text/parameter equivalence, directions, clause ownership, counts, scopes and spans. This increment is offline instrumentation; it does not claim a fresh live server run or completed HTML renderer.

Static report implementation (289afc5): GraphQueryLab.RenderHtml consumes immutable Doctor, Verify V1 or V2 evidence directly. Embedded CSS/SVG and native HTML controls need no JavaScript/server. Optional source excerpts carry separate hashes and are escaped data, never evaluated code; the sample embeds its actual compiled source file. SVGs cap at 32 nodes/64 steps, with exact accessible tables retained beyond the visual bound. Statement/source/document limits fail explicitly. EXPLAIN displays only captured operator/parent identities; its hash identifies that redacted shape, not a complete plan or performance. Native/fixed and Fluent/native outcomes remain distinct; cleanup failure can override passing cases. No execution transport or GUI-framework dependency is added.

LAB-EXPLAIN accepted (12 October 2026): 265 Tooling units pass, including seven renderer cases and existing planning cancellation/limits; clean 289afc5 sample/integration builds and six snapshots pass. Two live Community cases pass actual V1/V2 HTML commands, all three independent movie cases, negative controls and graph/schema/transaction cleanup. Offline/inspection/semantic reports pass isolated Chrome with scripts disabled, valid clause links, desktop/mobile bounds, PDF/print and no network requests (21 screenshots/three PDFs). Owned fixture ba1dea3e69cf41f5a02ba5c13bad9119 and browsers removed. LAB-REPORT remains doing until the compiled OPTIONAL-to-WITH row-count contrast capture runs; NQW-08 independently requires code-first, Fluent and ontology/database-first adoption demos, not three Fluent-only screenshots.

LAB-REPORT accepted subsequently the same day: the added live contrast executes the existing FilteredOptionalMovies source factory against the unchanged optional reference/expectations. Native returns eight rows; changed Fluent returns six, with deliberate RowCount failure. Rendered WHERE belongs to WITH and the correct source method is named. A focused live rerun passes that assertion plus the existing controls/cleanup. All four report modes have SHA-bound browser receipts, 28 screenshots/four PDFs and pinned captures in strategy/media/query-lab/289afc5; the coactor and comparison images were inspected visually. Second owned fixture a577d8d58aef4aa7813f1be64912f699 removed. No production code change or fourth supported V2 contract is introduced by this deliberate negative demonstration.