feat(vnext): add atomic document sessions (#172)

## Summary

- add the framework-independent `@marimo-team/codemirror-sql/vnext`
entry point
- implement immutable dialect registration, one session per document,
opaque revision identity/metadata, discriminated atomic updates, and
terminal disposal
- validate and own bounded plain-data contexts; normalize hostile
JavaScript inputs and guard reentrant update/open lifecycle races
- add compile-only API tests, 83 runtime invariant tests, current-API
documentation, and packed isolation smoke coverage without CodeMirror or
node-sql-parser available

## Evidence

- `pnpm run typecheck`
- `pnpm exec oxlint`
- `pnpm run test:coverage` (670 passed, 1 governed expected failure)
- changed vNext runtime coverage: 99% statements, 98.47% branches, 100%
functions, 98.99% lines
- `pnpm run test:browser`
- `pnpm run test:package`
- `pnpm run test:integrity`
- `pnpm run demo`

## Adversarial review

Two independent reviewers challenged correctness and API design. The
first loop found and reproduced reentrant revision overwrite,
service-open disposal, dialect TOCTOU, variance, and optional-property
issues. The implementation and tests were redesigned; both reviewers now
approve with no blocker/high findings.

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds vNext atomic document sessions in
`@marimo-team/codemirror-sql/vnext` with immutable dialects,
per-document sessions, and strict revision/lifecycle invariants.
Strengthens smoke tests with dependency isolation and rollback checks,
and exports `./vnext` for consumers.

- **New Features**
- Public service/session operations are exposed as readonly, bound
function fields to remain safe when passed as callbacks or destructured.
- Packaging/docs/tests: new session primitives guide, `package.json`
`./vnext` subpath export, and smoke tests that run without `@codemirror`
or `node-sql-parser`, verify `vnext` exports, revision identity, and
validate isolation rollback.

- **Bug Fixes**
- Hardened API invariants: reentrant-update guard, early stale-revision
checks before context inspection, idempotent terminal disposal for
session/service, stricter optional-field handling
(`exactOptionalPropertyTypes`), and consistent `SqlSessionError` codes
when normalizing accessors/proxies.

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

<a
href="https://cubic.dev/pr/marimo-team/codemirror-sql/pull/172?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/adr/0001-language-service-and-session.md

@@ -125,8 +125,10 @@ The session updates text and context atomically:
 
 ```ts
 session.update({
+  kind: "document",
   baseRevision: session.revision,
   document: {
+    kind: "changes",
     changes: [{ from: 14, to: 19, insert: "customers" }],
   },
   context: nextContext,
@@ -147,13 +149,15 @@ update without partial mutation.
 The public revision is an opaque immutable service-generated token. Callers
 cannot construct one or supply their own version number.
 
-Internally, the revision records:
+Internally, the session snapshot associated with the revision tracks:
 
-- Session identity
 - Monotonic sequence
 - Document revision
 - Context and template revision
-- Relevant environment/catalog epoch
+
+Relevant environment/catalog epochs will join that snapshot when those
+subsystems are implemented. The revision token itself remains only an opaque
+immutable identity; it does not duplicate snapshot metadata.
 
 The public model is deliberately global per session: any accepted text,
 context, template, relevant catalog, or provider-configuration invalidation
@@ -251,34 +255,34 @@ Explicit methods are preferred over one generic `request({ kind })` API:
 interface SqlDocumentSession<Context extends SqlDocumentContext> {
   readonly revision: SqlRevision;
 
-  update(update: SqlDocumentUpdate<Context>): SqlRevision;
+  readonly update: (update: SqlDocumentUpdate<Context>) => SqlRevision;
 
-  complete(
+  readonly complete: (
     request: SqlCompletionRequest,
-  ): Promise<SqlRequestResult<SqlCompletionList>>;
+  ) => Promise<SqlRequestResult<SqlCompletionList>>;
 
-  diagnostics(
+  readonly diagnostics: (
     request?: SqlDiagnosticsRequest,
-  ): Promise<SqlRequestResult<SqlDiagnosticSet>>;
+  ) => Promise<SqlRequestResult<SqlDiagnosticSet>>;
 
-  hover(
+  readonly hover: (
     request: SqlPositionRequest,
-  ): Promise<SqlRequestResult<SqlHover | null>>;
+  ) => Promise<SqlRequestResult<SqlHover | null>>;
 
-  definition(
+  readonly definition: (
     request: SqlPositionRequest,
-  ): Promise<SqlRequestResult<readonly SqlLocation[]>>;
+  ) => Promise<SqlRequestResult<readonly SqlLocation[]>>;
 
-  references(
+  readonly references: (
     request: SqlPositionRequest,
-  ): Promise<SqlRequestResult<readonly SqlLocation[]>>;
+  ) => Promise<SqlRequestResult<readonly SqlLocation[]>>;
 
-  format(
+  readonly format: (
     request?: SqlFormatRequest,
-  ): Promise<SqlRequestResult<readonly SqlTextEdit[]>>;
+  ) => Promise<SqlRequestResult<readonly SqlTextEdit[]>>;
 
-  isCurrent(revision: SqlRevision): boolean;
-  dispose(): void;
+  readonly isCurrent: (revision: SqlRevision) => boolean;
+  readonly dispose: () => void;
 }
 ```
 

docs/vnext/session-primitives.md

@@ -0,0 +1,78 @@
+# vNext Session Primitives
+
+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.
+
+## Example
+
+```ts
+import {
+  createSqlLanguageService,
+  defineSqlDialect,
+  type SqlDocumentContext,
+} from "@marimo-team/codemirror-sql/vnext";
+
+interface AppSqlContext extends SqlDocumentContext {
+  readonly engine: string;
+}
+
+const service = createSqlLanguageService<AppSqlContext>({
+  dialects: [
+    defineSqlDialect({ id: "duckdb", displayName: "DuckDB" }),
+  ],
+});
+
+const session = service.openDocument({
+  text: "SELECT * FROM users",
+  context: { dialect: "duckdb", engine: "local" },
+});
+
+const revision = session.update({
+  kind: "document",
+  baseRevision: session.revision,
+  document: {
+    kind: "changes",
+    changes: [{ from: 14, to: 19, insert: "customers" }],
+  },
+});
+
+if (session.isCurrent(revision)) {
+  // Results produced for this revision may still be applied.
+}
+
+session.dispose();
+service.dispose();
+```
+
+Use `{ kind: "replace", text }` for full replacement and
+`{ kind: "context", baseRevision, context }` for a context-only update.
+
+## Contract
+
+- Every accepted update creates a new frozen, service-issued revision.
+- `baseRevision` is checked by identity and cannot come from another session.
+- Incremental ranges are ordered, non-overlapping, half-open UTF-16 offsets in
+  the pre-update document.
+- Text and context are validated completely before the session snapshot changes.
+- Context is structured-cloned and recursively frozen. Accepted values are
+  finite primitives, arrays, and string-keyed plain objects. Cycles and shared
+  references are retained. Accessors, symbols, functions, class instances,
+  typed collections, and non-finite numbers are rejected.
+- Public service and session operations remain bound when passed as callbacks
+  or destructured.
+- Session and service disposal are idempotent and terminal.
+- Synchronous public failures use `SqlSessionError` and a stable `code`; caught
+  platform errors are not exposed as causes.
+
+The safety envelope currently permits at most 10,000 changes in one update, a
+16 Mi-code-unit document, 1,000 registered dialects, and bounded context graph
+depth, size, properties, and string data. These are defensive walking-skeleton
+limits, not release performance claims.
+
+The `/vnext` name is provisional until the packaging ADR fixes the next-major
+subpath layout.

implementation.md

@@ -590,6 +590,19 @@ disposition. Validate them through a protected reusable workflow from the base
 branch so a PR cannot approve itself. Maintainers approve classification
 overrides and rejected blocking findings.
 
+Request GitHub Copilot review on every medium or large PR after the head commit
+is ready for review:
+
+```bash
+gh pr edit <number> --add-reviewer @copilot
+```
+
+Copilot is an additional advisory review, not one of the two independent
+commit-bound adversarial attestations and not a substitute for human approval.
+Resolve or explicitly disposition its actionable comments in the finding
+ledger. Re-request review after a material rewrite when the prior comments no
+longer cover the current head.
+
 ## CI architecture
 
 ### Required fast PR lane
@@ -801,10 +814,11 @@ Before semantic implementation:
 12. Add the invariant registry and test-suite integrity checks.
 13. Add PR risk template and review-packet generation.
 14. Add protected, commit-bound two-reviewer checks.
-15. Add verified-artifact provenance to release CI.
-16. Add nightly mutation, fuzz, cross-browser, leak, and performance workflows.
-17. Add expiring scheduled-health and deduplicated failure issues.
-18. Define the supported runtime and dependency matrix.
+15. Automate GitHub Copilot review requests for medium and large PRs.
+16. Add verified-artifact provenance to release CI.
+17. Add nightly mutation, fuzz, cross-browser, leak, and performance workflows.
+18. Add expiring scheduled-health and deduplicated failure issues.
+19. Define the supported runtime and dependency matrix.
 
 ## Final recommendation
 

package.json

@@ -78,6 +78,12 @@
         "default": "./dist/dialects/index.js"
       }
     },
+    "./vnext": {
+      "import": {
+        "types": "./dist/vnext/index.d.ts",
+        "default": "./dist/vnext/index.js"
+      }
+    },
     "./data/common-keywords.json": "./src/data/common-keywords.json",
     "./data/duckdb-keywords.json": "./src/data/duckdb-keywords.json"
   },