feat(vnext): expose session relation completion

[Light2Dark]

Summary

• expose one framework-independent completion lifecycle through SqlDocumentSession.complete() and onDidChange()
• compose visible CTEs with one bounded catalog page using deterministic ranking, proven shadowing, original-document UTF-16 edits, and closed incomplete reasons
• share catalog scheduling/cache/epoch ownership at service scope while keeping request, refresh intent, and terminal-loading lifecycle session-local
• make the public completion result extensible with a kind: "relation" item discriminant
• document the consumer contract and add cold/warm local plus cold/cached catalog benchmarks

Why

The lower catalog scheduler and parser-independent query-site work were not yet usable through the public session. This slice connects those layers without exposing coordinator identities, epochs, timers, or CodeMirror state. It gives adapters a bounded local-first response and an explicit revision event when catalog evidence becomes usable.

Catalog scope is treated as a live connection incarnation. Loading, partial, paginated, failed, overloaded, and timed-out evidence remains explicit, so unresolved marimo metadata cannot be mistaken for a complete empty catalog.

Evidence

• 1,989 unit tests pass with one expected failure
• changed production files: 98.02% statements, 95.13% branches, 100% functions, 98.23% lines
• strict and loose-optional vNext type fixtures pass
• source, test, and demo typechecks pass
• oxlint and test-integrity checks pass
• 10 KiB completion benchmark: cold p99 about 1.5 ms; warm p99 below 0.8 ms
• two independent exact-head reviews approved the final lifecycle, API, timer, and consumer semantics

---

Summary by cubic

Exposes a session-based, framework-independent relation completion API with deterministic CTE + catalog suggestions and clear change events. Aligns CI bundle budgets for both the core and the worker fixture to match the new relation service.

• New Features

  • SqlDocumentSession.complete(request) returns SqlCompletionResult with kind: "relation" items.
  • SqlDocumentSession.onDidChange(listener) emits SqlSessionChangeEvent when catalog evidence becomes usable.
  • Deterministic ranking for local CTEs plus a bounded catalog page; supports cancellation and response budgets.
  • createSqlLanguageService({ catalog, completion: { catalogResponseBudgetMs } }) to configure a catalog and timing.
  • Docs updated in @marimo-team/codemirror-sql/vnext; added unit tests and a 10 KiB session completion benchmark.
  • CI: set core bundle allocation to 48 KiB gzip (180 KiB raw) and raised worker fixture ceiling to 160 KiB gzip (700 KiB raw); updated worker README and capability charter.

• Migration

  • Rename SqlRelationCompletionItem → SqlCompletionItem and SqlRelationCompletionList → SqlCompletionList.
  • Update CodeMirror resolver signatures to accept SqlCompletionItem.

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

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	98.23% (🎯 91%)	781 / 795
🔵	Statements	98.02% (🎯 91%)	795 / 811
🔵	Functions	100% (🎯 90%)	73 / 73
🔵	Branches	95.13% (🎯 85%)	606 / 637

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/vnext/index.ts	0%	0%	0%	0%
src/vnext/relation-completion-types.ts	0%	0%	0%	0%
src/vnext/relation-completion.ts	98.46%	95.74%	100%	99.19%	174, 286
src/vnext/session.ts	97.91%	95.02%	100%	98.03%	130, 602, 645, 851, 887, 943, 1190-1193, 1285-1288, 1297-1303, 1310-1313, 1317-1321, 1382-1385, 1871-1874
src/vnext/types.ts	100%	100%	100%	100%
src/vnext/codemirror/relation-completion-types.ts	0%	0%	0%	0%

Generated in workflow #754 for commit c66cffc by the Vitest Coverage Report Action