RFC-027: Live semantic resolution (LSP-assisted incremental Phase B)

[Abhishek5517]

Closes #794.

What this is

Draft RFC-027, proposing a live semantic resolution lane that closes the between-commits "mid-edit degradation" gap without regressing the commit-gated Phase B guarantee. Documentation only; no code changes.

File: docs/rfcs/RFC-027-live-semantic-resolution.md

Why

Phase B (SCIP) is commit-gated by deliberate decision, so between commits only Tree-sitter updates the graph. It sees that a reference exists but not which symbol it resolves to, so get_callers, get_blast_radius, and find_references degrade on the exact code being edited. This was hit repeatedly while dogfooding Travsr on itself.

The model

A strict separation of responsibilities:

Tree-sitter  ->  DETECTS      a reference exists            (live, cheap, always on)
SCIP graph   ->  OWNS         node identity (Kythe VName)   (durable ground truth)
LSP          ->  DISAMBIGUATES a specific position          (live, type-aware, optional)
Commit SCIP  ->  RATIFIES     the region, heals drift       (deterministic convergence)

LSP is used only as a disambiguation oracle over SCIP-identified candidates, never as a symbol or identity source. This is the key distinction from earlier LSP proposals that failed on identity: SCIP already gives every node a stable VName, so LSP is asked for a location, and SCIP owns location-to-node. When no server is present, behavior is exactly today's commit-gated path (zero regression).

What the RFC covers

• Four-lane responsibility model and the resolution flow (local scope check -> candidate set -> unambiguous-lexical OR LSP-disambiguate -> map to node OR abstain).
• Inline mermaid sequence diagram for both the live path and the commit ratification path.
• Edit classification (body vs interface) and the reverse-dependency closure invalidation model, including the incoming/outgoing edge asymmetry.
• The dirty-file span-mapping nuance for location_to_node (current Tree-sitter spans for dirty files, SCIP ranges for clean).
• Correctness contract: precision-first / fail-closed, the ADR-009 Rule 4 fencing rule, the Invariant Build(deps): Update rusqlite requirement from 0.31 to 0.39 #4 convergence proof, and the determinism fence.
• Schema deltas: new live provenance value (ADR-002 Rule 1) and a ref_resolution_state for pending references.
• MCP surface impact (provenance labeling plus a live_overlay freshness note; no new tool).
• LSP settle/consistency protocol, a continuous precision meter (diff live vs SCIP at commit, gate >= 0.99, SCIP wins ties), security/threat notes, a phased delivery plan, alternatives considered, and a risk register.

Correctness guarantees (the load-bearing ones)

• Zero structural hallucination preserved. Fail-closed emission; abstention is surfaced honestly as pending, never as a fabricated edge.
• Invariant Build(deps): Update rusqlite requirement from 0.31 to 0.39 #4 (incremental == full reindex) preserved. Every live edge is deleted and replaced by SCIP at commit, so the committed graph contains no live edges.
• VName uniqueness (Invariant Bump actions/setup-node from 4 to 6 #1) and the corpus invariant (RFC-005) preserved. The live lane never mints identity and never enters the bridge registry.

Revisions since first push (commit f9d1d62)

Before sending this out for the sign-off reviews below, I fact-checked the draft's own citations against the codebase and the referenced ADRs/RFCs and tightened a few things. No external review yet; these are author corrections. All doc-only:

• ADR-002 citation corrected. The provenance-tag requirement is Rule 1 (the provenance NOT NULL column), not Rule 5 (which is the SQL-upsert rule). Fixed in section 4 and section 9.1.
• Provenance value list reconciled. Section 9.1 now notes the shipped store's de-facto enum (tree-sitter/lsif/scip) already diverged from ADR-002's originally written list (tree-sitter/lsif/merged); live extends the de-facto set and does not reinstate merged.
• Schema field renamed. The proposed reference field resolution_state is renamed ref_resolution_state to avoid colliding with the daemon's existing record_dart_resolution_state bookkeeping (an unrelated Dart Phase B concept).
• Phantom citation replaced. project_phase_b_commit_gated_decision was not a real artifact; section 2.2 now cites the real source, the commit-gated comments in travsr-daemon/src/lib.rs. (The commit-gated premise itself is confirmed in that code.)
• Convergence hardened (pre-empts my own ask 1). Section 8.3 now ratifies by insert-SCIP-first (it wins by ADR-002 precedence), then delete leftover live edges, all in one WAL transaction, closing the transient-gap window. The sequence diagram is updated to match.
• Graded-confidence path noted (pre-empts my own ask 3). Section 16.4 notes the edges table already carries a confidence column, so graded confidence can ride that field without touching the boolean provenance enum.

Status

Draft. Not for merge-to-ship of behavior; this PR lands the design doc for review. Sign-offs required before the RFC moves to Accepted: Principal Architect (schema + convergence proof), Principal Security Engineer (spawn path + IDE-piggyback trust), Solution Architect (MCP surface).

[github-actions]

Benchmark comparison (master → PR)

no benchmark comparisons to show

Threshold: p95 regression ≥ +10% fails this check.