docs(vnext): accept parser-independent relation completion

[Light2Dark]

Summary

• accept ADR 0005 for parser-independent relation completion
• keep the first completion slice independent of parser acceptance and parser-worker startup
• define a bounded partial-SELECT query-site recognizer and narrow CTE visibility model
• define one provider-owned catalog boundary, canonical suffix rendering, epochs, cache identity, deadlines, cancellation, and deterministic composition
• define atomic text/context/embedded-region transactions and service-originated revision notifications
• define CodeMirror ownership, rich-info decoration, loading refresh intent, and marimo 1/10/50-view acceptance evidence
• keep provider/completion declarations provisional until the vertical slice, two provider shapes, packed marimo integration, and hostile lifecycle suites pass

Key decisions

• incomplete relation completion does not depend on node-sql-parser
• catalog matching/addressability belongs to the provider and scope; dialect runtime owns SQL decoding and role-aware rendering
• catalog edits replace the authenticated whole typed path with a provider-proven canonical suffix
• arbitrary embedded regions are grammar barriers; recovered sites remain explicitly heuristic and incomplete
• one atomic shared-work owner set covers request consumers and refresh observers
• hard safety deadlines are separate from the 40 ms default interactive catalog response budget
• terminal and soft loading results carry bounded one-shot completion-intent leases
• higher epochs discovered by responses or invalidations preserve active/menu/no-menu completion intent exactly once
• completion search misses never prove unknown-object diagnostics; authoritative resolution is separate

Validation

• patch rebased onto merged executor checkpoint 873c926
• all TypeScript configurations pass
• oxlint passes with zero findings
• test integrity passes
• 1,248 Node tests pass plus 1 expected negative
• three specialist adversarial review loops covered SQL/API correctness, marimo ergonomics, and concurrency/performance
• final exact-head approvals are recorded for d66ea25

Follow-up

The first implementation change is the runtime-free marimo-shaped type fixture. No production completion slice starts until that fixture compiles.

---

Summary by cubic

Accepts ADR 0005 to provide parser‑independent relation completion with clear catalog/provider contracts, CTE visibility, and deterministic lifecycle. Completion now works for incomplete FROM/JOIN without waiting for node-sql-parser or worker startup, and keeps CodeMirror integration separate.

• New Features

  • Decoupled relation completion from parser/worker; added bounded partial-SELECT site and CTE-visibility recognizers.
  • Defined catalog provider boundary: scope/search paths in; canonical paths with completionPathStart, epochs, and coverage out.
  • Added atomic text/context/embedded-region transactions and onDidChange session notifications for service-originated revisions.
  • Clarified dialect-owned identifier decoding/quoting and role-aware rendering; no generic folding/dedup in the service.
  • Specified deterministic ranking, latest-wins cancellation, deadlines (queue/exec), cache identity, and one-shot refresh intent.
  • Documented CodeMirror adapter boundary, safe coalesced refresh on catalog-availability, and no worker construction for this slice.

• Migration

  • Pass a complete embedded-region set on open/update; regions, text, and context update atomically.
  • Implement the new catalog provider contract (or use createInMemoryRelationCatalog); do not emit SQL text—return decoded paths and roles.
  • Do not gate completion on parser readiness; keep the parser worker and scoped semantics for future slices.
  • Subscribe to session.onDidChange and coalesce refresh on catalog-availability; respect the provided completion-intent lease.

^{Written for commit d66ea25. Summary will update on new commits.}

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	Unknown% (🎯 91%)	0 / 0
🔵	Statements	Unknown% (🎯 91%)	0 / 0
🔵	Functions	Unknown% (🎯 90%)	0 / 0
🔵	Branches	Unknown% (🎯 85%)	0 / 0

File Coverage

No changed files found.

Generated in workflow #705 for commit d66ea25 by the Vitest Coverage Report Action

[cubic-dev-ai]

No issues found across 5 files

_{Re-trigger cubic}