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.}