feat(vnext): expose session relation completion (#197)

## 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

<!-- This is an auto-generated description by cubic. -->
---
## 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`.

<sup>Written for commit c66cffc.
Summary will update on new commits.</sup>

<a
href="https://cubic.dev/pr/marimo-team/codemirror-sql/pull/197?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>

<!-- End of auto-generated description by cubic. -->

Author: Light2Dark

docs/vnext/capability-charter.md

@@ -239,6 +239,7 @@ count and estimated retained bytes.
 
 Provisional compressed bundle budgets:
 
+- Framework-independent core with relation completion: 48 KiB
 - Core plus CodeMirror adapter, excluding parser and dialect data: 75 KiB
 - Each ordinary dialect module: 25 KiB
 - Optional `node-sql-parser` chunk: no regression from its recorded baseline

docs/vnext/session-primitives.md

@@ -3,10 +3,10 @@
 Status: experimental walking skeleton  
 Import: `@marimo-team/codemirror-sql/vnext`
 
-This entry point currently provides document ownership, atomic text/context
-updates, opaque revisions, dialect registration, and lifecycle management. It
-does not yet provide parsing, completion, diagnostics, hover, or navigation.
-Those methods will be added only with working vertical slices.
+This entry point provides document ownership, atomic text/context updates,
+opaque revisions, dialect registration, lifecycle management, and
+parser-independent relation completion. Diagnostics, hover, navigation, and
+general expression completion are not yet available.
 
 See [source coordinates](./source-coordinates.md) for the shared UTF-16 range
 contract and the internal immutable source-snapshot model.
@@ -56,6 +56,73 @@ Use `{ kind: "replace", text }` for full replacement and
 also supplies the complete embedded-region set for its resulting text. A
 region-only transaction can replace or clear that set without a fake text edit.
 
+## Relation completion
+
+Completion works without a catalog for visible CTEs. A service can also own one
+shared asynchronous relation-catalog provider:
+
+```ts
+const service = createSqlLanguageService<AppSqlContext>({
+  catalog: {
+    id: "app-catalog",
+    search: async (request, signal) => {
+      signal.throwIfAborted();
+      return {
+        coverage: { kind: "complete" },
+        epoch: { generation: 0, token: "initial" },
+        relations: [],
+        status: "ready",
+      };
+    },
+  },
+  completion: { catalogResponseBudgetMs: 40 },
+  dialects: [duckdbDialect()],
+});
+
+const session = service.openDocument({
+  context: {
+    dialect: "duckdb",
+    engine: "local",
+    catalog: { scope: "connection-incarnation:1" },
+  },
+  text: "SELECT * FROM ",
+});
+
+const subscription = session.onDidChange(({ reason }) => {
+  if (reason === "catalog" || reason === "catalog-availability") {
+    // Ask the editor adapter to request completion again.
+  }
+});
+
+const result = await session.complete({
+  position: 14,
+  trigger: { kind: "invoked" },
+});
+
+if (result.status === "ready" && session.isCurrent(result.revision)) {
+  for (const item of result.value.items) {
+    // Apply item.edit in the original document's UTF-16 coordinates.
+  }
+}
+
+subscription.dispose();
+session.dispose();
+service.dispose();
+```
+
+The catalog `scope` identifies a live connection incarnation, not a reusable
+display name. Search responses distinguish complete, partial, paginated,
+loading, and failed evidence. A ready result can therefore be incomplete; its
+closed `issues` explain why, while `sources` reports catalog outcomes without
+exposing provider errors or internal epochs.
+
+The interactive catalog wait is bounded from the start of `complete()`. When
+the budget expires, the session returns local evidence with a
+`catalog-loading` issue and a checked remaining intent lease. Compatible
+readiness advances the session revision and emits `catalog-availability`;
+higher provider epochs emit `catalog`. Consumers must request completion again
+and apply only results whose revision remains current.
+
 ## Dialect registration
 
 `duckdbDialect()`, `postgresDialect()`, `bigQueryDialect()`, and

package.json

@@ -31,6 +31,7 @@
     "bench:local-relation-site": "vitest bench --run src/vnext/__tests__/local-relation-site.bench.ts",
     "bench:parser-adapter": "vitest bench --run src/vnext/__tests__/node-sql-parser-adapter.bench.ts",
     "bench:query-site": "vitest bench --run src/vnext/__tests__/query-site.bench.ts",
+    "bench:session-completion": "vitest bench --run src/vnext/__tests__/session-completion.bench.ts",
     "bench:statement-index": "vitest bench --run src/vnext/__tests__/statement-index.bench.ts",
     "test:package": "node ./scripts/clean.mjs && tsc && node ./scripts/package-smoke.mjs",
     "demo": "vite build",

scripts/worker-placement.mjs

@@ -35,11 +35,11 @@ const PARSER_MARKERS = [
   "tableList",
 ];
 const BIGQUERY_GZIP_LIMIT = 50 * 1024;
-const CORE_TOTAL_GZIP_LIMIT = 16 * 1024;
-const CORE_TOTAL_RAW_LIMIT = 52 * 1024;
+const CORE_TOTAL_GZIP_LIMIT = 48 * 1024;
+const CORE_TOTAL_RAW_LIMIT = 180 * 1024;
 const POSTGRESQL_GZIP_LIMIT = 68 * 1024;
-const WORKER_TOTAL_GZIP_LIMIT = 128 * 1024;
-const WORKER_TOTAL_RAW_LIMIT = 570 * 1024;
+const WORKER_TOTAL_GZIP_LIMIT = 160 * 1024;
+const WORKER_TOTAL_RAW_LIMIT = 700 * 1024;
 const MIME_TYPES = new Map([
   [".css", "text/css; charset=utf-8"],
   [".html", "text/html; charset=utf-8"],