feat(vnext): expose statement boundaries (#201)

## Summary

- expose synchronous, revision-stamped `statementBoundaryAt` and
`statementBoundariesIntersecting` session queries
- preserve exact/no-code/opaque lexical states without leaking the
private statement index
- add scanner-owned `code` spans that exclude separator trivia and form
a strict `hasCode` discriminated union
- validate request envelopes as own data properties without invoking
host accessors
- retain incremental index reuse and shift code spans with exact UTF-16
coordinates
- add public type, package smoke, hostile-input, affinity, opacity,
masking, intersection, and documentation coverage

## Verification

- 43 test files; 2,045 passed and 1 expected failure
- changed coverage: 97.92% statements, 96.12% branches, 100% functions,
98.07% lines
- all source/test/strict/loose/demo TypeScript configurations pass
- oxlint, test integrity, build, and runtime export smoke pass
- cold point lookup measured 3.59 ms at 1 MiB and 42.67 ms at the 16 MiB
source ceiling; warm viewport intersection measured 0.075–0.096 ms
- two independent exact-head adversarial reviews approve
`c901544ff41480bb1e7ea2ddcab3af477dc8103f`

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Expose synchronous, revision-stamped statement boundary queries in the
vNext session API so editors and runners can locate executable SQL
without re-lexing. Adds an exact/opaque boundary model with precise
UTF-16 ranges and a `code` span for execution.

- **New Features**
- Added `session.statementBoundaryAt({ affinity, position })` and
`session.statementBoundariesIntersecting({ from, to })`; results are
frozen and include the current `revision`.
- Exact boundaries expose `extent`, `source`, optional `terminator`,
lexical `endState`, and a `code` span that excludes separator trivia;
discriminated by `hasCode`.
- Opaque boundaries report a `reason` for non-executable regions
(procedural blocks, custom delimiters, resource limits).
- All ranges map to the original document’s UTF-16 positions and respect
masked embedded regions.
- Inputs are strictly validated (own data properties only); invalid
requests throw `SqlSessionError` with
`invalid-statement-boundary-request`.
- Exported new types via `@marimo-team/codemirror-sql/vnext`:
`SqlStatementBoundary*`, `SqlStatementAffinity`,
`SqlStatementLexicalEnd`, and related request/result shapes.

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

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

@@ -14,6 +14,47 @@ CodeMirror consumers should use the separate
 See [source coordinates](./source-coordinates.md) for the shared UTF-16 range
 contract and the internal immutable source-snapshot model.
 
+Statement boundaries are available as a synchronous structural query:
+
+```ts
+const result = session.statementBoundaryAt({
+  affinity: "left",
+  position: cursorOffset,
+});
+
+if (
+  session.isCurrent(result.revision) &&
+  result.boundary.boundaryQuality === "exact" &&
+  result.boundary.hasCode
+) {
+  executeRange(result.boundary.source);
+}
+```
+
+The immutable result carries the current session revision. Exact boundaries
+expose their full extent, source range, optional terminator, lexical end state,
+and a nullable range from the first through last SQL code token. Source ranges
+retain attached
+whitespace and comments; they are factual lexical boundaries, not pre-trimmed
+visual selections. The `code` range excludes leading and trailing separator
+trivia so presentation layers do not need to re-lex the document. Opaque
+procedural, custom-delimiter, and resource-limited
+regions expose only their extent and reason, so consumers cannot mistake them
+for safely executable SQL.
+
+Viewport consumers can retrieve every structural boundary in one half-open
+range without probing or re-lexing the document:
+
+```ts
+const visible = session.statementBoundariesIntersecting({
+  from: viewport.from,
+  to: viewport.to,
+});
+```
+
+The query runs in logarithmic lookup time plus the number of intersecting
+boundaries and returns a frozen, revision-stamped array.
+
 ## Example
 
 ```ts

scripts/package-smoke.mjs

@@ -207,6 +207,13 @@ session.update({
   baseRevision: session.revision,
   document: { kind: "replace", text: "SELECT * FROM {next_df}" },
 });
+const statement = session.statementBoundaryAt({ affinity: "left", position: 0 });
+if (
+  statement.boundary.boundaryQuality !== "exact" ||
+  !statement.boundary.hasCode
+) {
+  throw new Error("The packaged vNext statement boundary was unavailable");
+}
 service.dispose();
 `,
   );
@@ -229,6 +236,7 @@ import {
   duckdbDialect,
   type SqlDocumentContext,
   type SqlEmbeddedRegion,
+  type SqlStatementBoundaryAtResult,
   type SqlTextRange,
 } from "@marimo-team/codemirror-sql/vnext";
 import { sqlEditor } from "@marimo-team/codemirror-sql/vnext/codemirror";
@@ -265,12 +273,17 @@ session.update({
   baseRevision: session.revision,
   document: { kind: "changes", changes: [] },
 });
+const statement: SqlStatementBoundaryAtResult = session.statementBoundaryAt({
+  affinity: "left",
+  position: 0,
+});
 
 void extensions;
 void editorSupport.extension;
 void parser;
 void range;
 void session;
+void statement;
 void BigQueryDialect;
 void DremioDialect;
 void commonKeywords;
@@ -349,6 +362,20 @@ const updatedRevision = session.update({
 if (session.isCurrent(originalRevision) || !session.isCurrent(updatedRevision)) {
   throw new Error("The packaged vNext session violated revision identity");
 }
+const statement = session.statementBoundaryAt({ affinity: "left", position: 0 });
+const visible = session.statementBoundariesIntersecting({
+  from: 0,
+  to: 23,
+});
+if (
+  statement.revision !== updatedRevision ||
+  statement.boundary.boundaryQuality !== "exact" ||
+  !statement.boundary.hasCode ||
+  visible.revision !== updatedRevision ||
+  visible.boundaries.length !== 1
+) {
+  throw new Error("The packaged vNext statement boundary is invalid");
+}
 service.dispose();
 `,
   );