feat(vnext): define normalized syntax contract (#176)

## Summary

- define the internal normalized syntax state and parser-analysis
contracts
- bind every artifact, diagnostic, analysis, conformance claim, and
parser to exact source plus authenticated backend/configuration/dialect
authority
- add one mandatory parser runner that normalizes failures and returns
runner-created analyzed state
- add runtime and compile-time invariant tests plus ADR 0002
- keep the stable vNext export surface unchanged

## Safety and correctness

- direct invalidity requires matching conformance authority
- compatibility rejection cannot become authoritative invalid SQL
- malformed locations fail closed instead of becoming unavailable
- parser input is capped at 1 MiB; messages, diagnostics, and
limitations are bounded
- hostile custom iterators cannot bypass collection limits
- full AbortSignal runtime validation matches the declared callback
surface
- raw ASTs and backend payloads remain private

## Validation

- 875 unit tests passed, with 1 governed expected failure
- changed syntax.ts coverage: 97.68% statements, 95.42% branches, 100%
functions, 97.66% lines
- full typecheck and oxlint passed
- browser tests passed
- test integrity passed
- packed-consumer smoke passed
- demo build passed
- two independent adversarial reviewers approved exact commit db43409
after four fix/review loops

## Scope

Internal contract only. This PR does not add a parser adapter,
cache/session wiring, catalog types, or stable public exports.

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Defines an internal normalized SQL syntax contract with a single parser
runner that authenticates outputs and separates lexical eligibility from
parser analysis. Strengthens cancellation: preserves the exact
`AbortSignal` reason, rejects pre-aborted requests without invoking the
backend, and races cancellation vs. backend completion correctly; public
vNext exports stay the same and ADR 0002 documents the boundary.

- New Features
  - Normalized statement states and parser analyses.
- Branded statement-relative ranges; parser receives only exact
statement text and an AbortSignal.
- Parser, authority, and conformance identities; artifacts/diagnostics
bound to exact source and authority; backend data stays private.
- Runner validates identities, normalizes sync/async failures, handles
cancellation races, and returns authenticated analyzed state. Adds ADR
0002 and tests; no change to stable exports.

- Safety
- 1 MiB input cap; bounded messages and collections; hostile iterators
contained.
- `AbortSignal` surface validated (cross-realm supported); preserves
exact abort reason; pre-aborted requests skip backend; late aborts don’t
override completed backend outcomes.
- Malformed locations and fabricated results fail closed as
malformed-output.
- Compatibility rejection is never treated as invalid; invalidity
requires matching conformance and authority identities.

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

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

@@ -91,7 +91,8 @@ service.dispose();
 `syntax` is an opaque module accepted by the stable service factory. Its parser
 and semantic-model SPI is not stable in this ADR. Official adapters can use an
 experimental subpath until two materially different backends validate the
-normalized artifacts.
+normalized artifacts. The first internal boundary is specified by
+[ADR 0002](./0002-normalized-syntax-contract.md).
 
 ## Document context
 

docs/adr/0002-normalized-syntax-contract.md

@@ -0,0 +1,195 @@
+# ADR 0002: Internal Normalized Syntax Contract
+
+Status: accepted
+Date: 2026-07-24
+
+## Context
+
+The legacy parser API accepts a complete CodeMirror `EditorState`, mutates
+offset bookkeeping, exposes backend-specific AST shapes, and can report success
+without a usable tree. Dialect support and location quality are also easy to
+overstate: a compatibility grammar rejecting input is not evidence that the
+target dialect is invalid.
+
+The vNext statement index already separates exact, incomplete, and opaque
+lexical boundaries. The next layer needs a narrow parser boundary that can
+support multiple backends without making the first backend's AST public or
+mixing lexical eligibility, parser evidence, and request cancellation into one
+ambiguous result.
+
+This contract is internal. It must be exercised by a real adapter and semantic
+consumer before any part is considered for the stable `/vnext` API.
+
+## Decision
+
+Syntax processing has three separate state machines:
+
+1. Lexical eligibility decides whether a statement is empty, incomplete,
+   opaque, unavailable, or eligible for an analyzed result.
+2. Parser analysis reports parsed, invalid, unsupported, or failed evidence.
+3. The session request lifecycle owns caller cancellation, supersession,
+   disposal, revision applicability, and timeouts.
+
+Parser outcomes never contain `empty`, `incomplete`, `opaque`, `cancelled`, or
+`superseded`. Keeping those layers separate prevents a parser failure from
+being mistaken for invalid SQL and prevents an incomplete lexical construct
+from being sent to a backend.
+
+The parser runner transports cancellation without classifying it: a
+pre-aborted request does not invoke the backend, and an in-flight abort rejects
+with the signal's exact reason if it wins the race with backend completion.
+Late backend rejection remains handled. The session decides whether that
+rejection represents cancellation, supersession, disposal, or another request
+lifecycle event.
+
+### Eligibility
+
+| State | Meaning | Parser invoked |
+| --- | --- | --- |
+| `empty` | Exact slot has no code | No |
+| `incomplete` | Exact slot ends inside a known lexical construct | No |
+| `opaque` | Statement boundaries are not trustworthy | No |
+| `unavailable` | No parser is configured for the resolved dialect | No |
+| `analyzed` | The parser returned authenticated normalized evidence | Yes |
+
+Incomplete and opaque states preserve the scanner's closed construct/reason
+unions and a statement-relative location. They do not accept arbitrary strings.
+
+### Parser analysis
+
+`parsed` has two mutually exclusive modes:
+
+- `direct` carries a conformance identity. The backend is configured for the
+  target grammar and may make authoritative syntax claims within that grammar.
+- `compatibility` carries one or more explicit limitations. It may provide a
+  useful artifact, but it does not claim target-dialect conformance.
+
+`invalid` requires a direct conformance identity and at least one normalized
+syntax diagnostic. Compatibility rejection is therefore `unsupported` with
+reason `compatibility-rejected`, never `invalid`.
+
+`unsupported` is an expected capability boundary: backend capability,
+compatibility rejection, uncovered construct, or resource limit. `failed`
+means the backend failed or violated its output contract; it carries a bounded
+safe message and explicit retryability.
+
+Parser-reported locations are either an exact statement-relative range or
+explicitly `unavailable/not-reported`. An adapter that claims a malformed
+location returns `failed/malformed-output`; it must not erase the defect by
+turning the location into `unavailable`.
+
+### Coordinates and input
+
+The parser receives only:
+
+- The exact code-bearing normal slot's `source` slice
+- An `AbortSignal`
+
+The slice excludes the statement terminator and is not trimmed. It contains no
+editor state, document offsets, cursor, catalog, focus, or host context.
+Parser requests are package-created and frozen. Input is bounded to 1 MiB; a
+larger statement is an explicit coordinator resource limit and is not passed to
+the backend. Abort signals are checked by their cross-realm-compatible
+`AbortSignal` surface instead of `instanceof`; adapters may safely use every
+member declared by that interface.
+
+All artifact and diagnostic ranges are branded half-open UTF-16 offsets
+relative to that exact slice:
+
+```text
+0 <= from <= to <= statementText.length
+```
+
+Absolute document ranges and statement-relative ranges are not assignable.
+This lets an unchanged statement artifact move with an edited prefix without
+rewriting its coordinates.
+
+### Artifacts and identity
+
+The normalized artifact initially exposes only a closed statement kind and its
+full statement-relative range. It exposes no generic AST, facts bag, backend
+node, source text, or mutable payload.
+
+Package-private metadata binds every artifact, diagnostic, and analysis to its
+exact immutable statement text. This text is not exposed or copied into the
+artifact, but exact equality provides collision-free reuse for identical
+statements and prevents same-length text from sharing evidence.
+
+Artifacts, diagnostics, analyses, states, ranges, and identities are created by
+package constructors, frozen, and authenticated through package-owned weak
+identity sets. Structural copies and fabricated objects are rejected at
+runtime. Future official adapters may key private `WeakMap` payloads by the
+artifact so relation extraction can reuse a parse without exposing backend
+data.
+
+Cache authority requires three distinct package-owned identities:
+
+- Backend/module identity
+- Parser-configuration identity
+- Dialect-syntax identity
+
+One frozen package-owned parser-authority handle captures that exact tuple.
+Parsers, artifacts, diagnostics, analyses, and future private backend payloads
+all retain the handle in private metadata. The runner rejects every outcome
+whose handle differs from its parser, including compatibility, unsupported, and
+failed outcomes. A conformance identity is scoped to the same handle, so direct
+or invalid evidence cannot pair one backend's artifact with another backend's
+authority.
+
+Direct validity also carries a conformance identity. String dialect IDs never
+substitute for these authorities. A conformance identity is created for and
+retains the exact backend, parser-configuration, and dialect-syntax identity
+tuple; a parser cannot use another tuple's conformance to make an authoritative
+claim.
+
+Parsers are also package-created frozen descriptors. Their callback stays in
+private metadata and can be invoked only through the contract runner. The
+runner:
+
+- Accepts only authentic parser and request objects
+- Normalizes synchronous throws and rejected promises without retaining raw
+  errors
+- Rejects fabricated results
+- Verifies that every authentic artifact or diagnostic was constructed for the
+  exact request text
+- Verifies direct/invalid conformance against the parser's exact authority
+  tuple
+
+The runner returns the authenticated `analyzed` lexical state directly; there
+is no separately callable analyzed-state constructor. This prevents authentic
+evidence created for one statement from being replayed against another.
+
+Compatibility limitations are a unique, non-empty subset of the three closed
+values and are capped accordingly. Diagnostic collections, messages, parser
+input, and retained strings are likewise bounded before backend-controlled work
+can cause unbounded copying.
+
+## Consequences
+
+- Impossible result combinations are rejected by TypeScript and constructor
+  validation.
+- Backends can be changed without exposing their AST as API.
+- Unsupported dialect coverage remains honest.
+- Parser artifacts can be cached independently of catalog generations.
+- The contract has more explicit result variants, but consumers narrow on
+  stable discriminants instead of interpreting nullable fields or exceptions.
+
+The initial `node-sql-parser` adapter will lazy-load dialect-specific builds,
+request locations, retain backend data privately, and normalize every boundary
+before constructing these results. Cache/session wiring follows only after the
+adapter passes the contract suite.
+
+## Non-goals
+
+This decision does not define:
+
+- A public parser plugin SPI
+- A universal SQL AST
+- Semantic relations, scopes, types, or catalog lookup
+- Recovery-node semantics
+- Document-level validation
+- Session cancellation or stale-result publication
+- Parser cache sizing and eviction
+
+Those layers depend on this contract but remain independently reviewable
+decisions.