feat(vnext): correlate completion refresh intent (#198)

## Summary

- add an opaque completion refresh token that correlates loading
results, follow-up catalog events, and the originating completion task
- make completion tasks expose their refresh token synchronously so
CodeMirror consumers can safely latch intent before caller-controlled
reentrancy
- define precise token lifetimes for soft and terminal catalog-loading
leases, including expiry, cancellation, update, and disposal
- harden `AbortSignal` handling against reentrant and throwing
getters/listener methods without allowing an older invocation to erase
newer work

## Why

The upcoming CodeMirror adapter must refresh completion only for the
request that originally produced a loading result. Revision checks alone
cannot distinguish multiple requests at the same document revision, and
asynchronous token publication leaves a race where catalog events can
arrive before the consumer knows what to match. This contract makes that
identity explicit and keeps latest-request-wins behavior correct across
hostile caller boundaries.

## Validation

- 2,003 tests pass; 1 intentional expected failure
- changed-file coverage: 97.92% statements, 96.01% branches, 100%
functions, 98.01% lines
- all strict and loose-optional TypeScript configurations pass
- oxlint and test-integrity checks pass
- session completion benchmarks remain within budget
- two independent exact-commit adversarial reviews approved `a0522c4`


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds an opaque completion refresh token to correlate loading results,
follow-up catalog events, and the originating request.
`session.complete()` now returns a `SqlCompletionTask` that exposes the
token synchronously, and `onDidChange` events include the token when
relevant.

- **New Features**
- Introduced `SqlCompletionRefreshToken` and `SqlCompletionTask`
(`complete()` returns a task with `refreshToken`).
  - `SqlSessionChangeEvent` now carries `refreshToken`:
- `catalog-availability`: always includes the exact token for the active
soft intent.
- `catalog`: includes the matching token during an active intent lease,
otherwise `null`.
    - `provider-configuration`: `refreshToken` is always `null`.
- Ready results include `refreshToken` when a `catalog-loading` lease is
active; otherwise `null`.
- Hardened `AbortSignal` and timer handling to avoid reentrancy issues
and prevent stale callbacks from erasing newer work.

- **Migration**
  - Update callers to use the new task:
    - `const task = session.complete(...); const result = await task;`
    - Use `task.refreshToken` immediately to latch intent.
  - Update `onDidChange` listeners:
- Compare `event.refreshToken` to the latched `task.refreshToken` before
refreshing.
- Treat `catalog` events with `refreshToken: null` as unrelated to the
current intent.
  - Adjust types:
    - `complete()` now returns `SqlCompletionTask` (still awaitable).
- Handle the refined `SqlSessionChangeEvent` union with per-reason
`refreshToken` semantics.
  - Do not serialize or introspect tokens; compare by identity only.

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

<a
href="https://cubic.dev/pr/marimo-team/codemirror-sql/pull/198?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/session-primitives.md

@@ -88,18 +88,25 @@ const session = service.openDocument({
   text: "SELECT * FROM ",
 });
 
-const subscription = session.onDidChange(({ reason }) => {
-  if (reason === "catalog" || reason === "catalog-availability") {
+let completionRefreshToken: SqlCompletionRefreshToken | null = null;
+const subscription = session.onDidChange(({ refreshToken }) => {
+  if (
+    refreshToken !== null &&
+    refreshToken === completionRefreshToken
+  ) {
     // Ask the editor adapter to request completion again.
   }
 });
 
-const result = await session.complete({
+const completionTask = session.complete({
   position: 14,
   trigger: { kind: "invoked" },
 });
+completionRefreshToken = completionTask.refreshToken;
+const result = await completionTask;
 
 if (result.status === "ready" && session.isCurrent(result.revision)) {
+  completionRefreshToken = result.refreshToken;
   for (const item of result.value.items) {
     // Apply item.edit in the original document's UTF-16 coordinates.
   }
@@ -118,10 +125,21 @@ 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.
+`catalog-loading` issue, a checked remaining intent lease, and an opaque
+`refreshToken`. Compatible readiness advances the session revision and emits
+`catalog-availability` with that exact token. A higher provider epoch emits
+`catalog` with the token only while the same soft or terminal loading intent
+remains leased; otherwise its token is `null`.
+
+Consumers compare refresh tokens by identity. A matching token is necessary,
+not sufficient, to request completion again: the document, selection, context,
+and adapter-owned intent must also remain unchanged. Tokens are in-process,
+non-serializable control identities; they expose no provider epoch, query, or
+work identity. The completion task exposes its token synchronously before
+provider work starts, so consumers can latch a matching catalog event that
+races the result. Ready results retain that token only while
+`catalog-loading` has an unexpired lease; all other ready results use `null`.
+Consumers apply only results whose revision remains current.
 
 ## Dialect registration