feat(vnext): add bounded node-sql-parser adapter (#177)

## Summary
- add an internal normalized node-sql-parser adapter for PostgreSQL,
BigQuery, and DuckDB compatibility evidence
- pin node-sql-parser 5.4.0 and load only dialect-specific builds
through a race-safe pure-Node loader
- keep all successful evidence non-conformant, retain ASTs privately,
and fail closed in browser/worker/DOM-shim realms pending
dedicated-worker support
- document the evidence, execution, resource, packaging, and
global-cleanup boundaries in ADR 0003
- add adversarial unit/browser coverage and validated warm parser
benchmarks

## Correctness policy
- PostgreSQL/BigQuery acceptance: parsed/compatibility with
partial-artifact
- PostgreSQL/BigQuery rejection: unsupported/uncovered-construct, never
invalid
- DuckDB acceptance: parsed/compatibility with dialect-compatibility +
partial-artifact
- DuckDB rejection: unsupported/compatibility-rejected
- Dremio: no adapter

## Validation
- 971 tests passed, 1 expected failure
- changed coverage: 99.13% statements, 99.35% branches, 100% functions,
99.12% lines
- full strict typecheck and non-mutating lint
- Chromium browser suite
- isolated package smoke and demo build
- test integrity check
- preflight-validated parser benchmark
- two independent adversarial review loops approved the final exact tree

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add an internal `node-sql-parser` adapter for PostgreSQL and BigQuery
with a DuckDB compatibility path that returns small, private artifacts
under strict bounds and pure-Node loading. Also fixes and documents a
test spelling false positive, and keeps the CI report spelling-clean.

- **New Features**
- Evidence policy: PostgreSQL/BigQuery accept -> parsed/compatibility
(partial); reject -> unsupported/uncovered-construct. DuckDB uses the
PostgreSQL build: accept -> parsed/compatibility (dialect-compatibility,
partial); reject -> unsupported/compatibility-rejected.
- Bounded artifacts: only statement kind + full range; backend ASTs kept
private.
- Resource/placement: 16 KiB statement limit; synchronous parse;
cancellation checked before/after load and after parse; not wired to
sessions.
- Execution realm safety: pure Node only with race-safe loader and
global cleanup; fails closed in window/worker/DOM-shim realms.
- Docs and tests: added ADR 0003, linked ADR 0002, and a vNext adapter
doc; Node and browser tests plus a warm parser benchmark and
`bench:parser-adapter` script; fixed spelling CI false positive and kept
`state/artifacts/reports/pr-177-spelling-ci.md` spelling-clean.

- **Dependencies**
- Pin `node-sql-parser` to `5.4.0` and load only `build/postgresql.js`
and `build/bigquery.js`.

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

<a
href="https://cubic.dev/pr/marimo-team/codemirror-sql/pull/177?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/0002-normalized-syntax-contract.md

@@ -179,6 +179,12 @@ 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.
 
+[ADR 0003](./0003-node-sql-parser-adapter.md) applies this contract
+conservatively: PostgreSQL, BigQuery, and DuckDB acceptance is compatibility
+evidence with explicit limitations; rejection is unsupported rather than
+invalid; and session wiring waits for an explicit
+synchronous-execution/worker decision.
+
 ## Non-goals
 
 This decision does not define:

docs/adr/0003-node-sql-parser-adapter.md

@@ -0,0 +1,202 @@
+# ADR 0003: Internal node-sql-parser Adapter
+
+Status: accepted
+Date: 2026-07-25
+
+## Context
+
+ADR 0002 defines an internal normalized syntax contract, but it deliberately
+does not decide how a concrete parser earns authority. The first adapter uses
+`node-sql-parser` because the dependency is already present and can provide a
+useful local AST in Node or an isolated worker. It must not turn the
+dependency's incomplete grammar,
+partial locations, synchronous execution, or packaging behavior into broader
+vNext guarantees.
+
+The installed `node-sql-parser` 5.4.0 package provides separate CommonJS
+bundles for PostgreSQL and BigQuery. The complete bundle is approximately
+2.5 MB uncompressed and 428 KiB compressed, while the PostgreSQL and BigQuery
+builds are approximately 59 KiB and 42 KiB compressed respectively. Loading
+the complete bundle would make consumers pay for unrelated grammars.
+
+The target-named grammars are not authoritative validators for their database
+engines. In local probes, the PostgreSQL build rejected valid `MERGE`,
+`FETCH FIRST`, `INSERT ... DEFAULT VALUES`, identity-column, and
+`FOR UPDATE SKIP LOCKED` statements. The BigQuery build rejected valid
+`QUALIFY`, `MERGE`, and `DECLARE` statements. A parse rejection therefore
+cannot establish that target-dialect SQL is invalid.
+
+The parser also runs synchronously. An `AbortSignal` can prevent work before
+the parse begins and suppress publication after it finishes, but it cannot
+interrupt `astify` while JavaScript is blocked.
+
+## Decision
+
+The adapter remains internal and is not exported from `/vnext`. This change
+does not connect it to document sessions, caches, diagnostics, completion, or
+any other feature. Session wiring requires a separate decision about worker
+isolation and cancellation.
+
+### Dependency and loading
+
+Pin `node-sql-parser` exactly to version `5.4.0`. The adapter depends on deep
+paths, CommonJS interop, AST shapes, and grammar behavior that are not stable
+enough for an unconstrained dependency range.
+
+Load only these extension-qualified paths:
+
+```text
+node-sql-parser/build/postgresql.js
+node-sql-parser/build/bigquery.js
+```
+
+After dynamically acquiring `createRequire` from `node:module`, the adapter
+revalidates the realm and synchronously requires the selected build. Module
+evaluation and global restoration therefore run in one JavaScript stack with
+no alias-mutation gap. The adapter does not load the all-dialect entry point
+and does not pass a `database` option to a dialect-specific build.
+
+Node ESM exposes these CommonJS builds through `default`/`module.exports` even
+though the declarations suggest a named `Parser` export. The module boundary
+is decoded from `unknown` and accepts only a runtime-validated constructor and
+`astify` method. No unchecked assertion compensates for the declaration/runtime
+mismatch.
+
+The parser receives fixed options:
+
+```ts
+{
+  trimQuery: false,
+  parseOptions: {
+    includeLocations: true,
+  },
+}
+```
+
+Disabling trimming is required to keep every backend offset relative to the
+exact untrimmed statement slice. Location inclusion is requested for future
+private semantic decoding, but location availability remains per node and is
+not promoted to a dialect-wide capability.
+
+The distributed UMD-style builds can assign `NodeSQLParser` and, in some
+environments, `global` on the global object while loading. The adapter refuses
+to load them whenever `window` or `self` exists, or `global` does not resolve
+exactly to `globalThis`. Only pure Node is currently eligible. This prevents
+global collisions, including DOM shims in Node, and accidental synchronous
+main-thread parsing. The Node loader captures the existing own-property
+descriptors for the affected names and restores them synchronously after module
+evaluation. A module that cannot be loaded and cleaned up safely permanently
+poisons loading and returns a non-retryable backend failure.
+
+### Evidence policy
+
+PostgreSQL and BigQuery acceptance is positive-only compatibility evidence. A
+successful target-specific parse produces `parsed/compatibility` with the
+`partial-artifact` limitation. It means only that the target-named backend
+produced a bounded normalized artifact. The adapter does not create a
+conformance identity because the grammar also accepts constructs that the
+target engines reject.
+
+Every PostgreSQL or BigQuery parse rejection produces:
+
+```text
+unsupported / uncovered-construct
+```
+
+It never produces `invalid`, even for input that appears obviously malformed.
+The same parser error is indistinguishable from rejection of valid syntax that
+the dependency does not implement. This adapter therefore creates no
+authoritative syntax diagnostics.
+
+DuckDB uses the PostgreSQL build only as a compatibility parser:
+
+- Acceptance produces `parsed/compatibility` with the
+  `dialect-compatibility` and `partial-artifact` limitations.
+- Rejection produces `unsupported/compatibility-rejected`.
+- The adapter performs no rewrites, success-without-AST shortcuts, bracket
+  quoting, comment stripping, or offset repair.
+
+Dremio has no node-sql-parser adapter. When a coordinator is added later, it
+will classify Dremio as `unavailable/dialect-not-supported` rather than silently
+selecting another grammar.
+
+Unexpected backend exceptions are failures, not syntax evidence. Invalid
+module shapes or malformed AST roots are `failed/malformed-output`; other
+unexpected parser exceptions are `failed/backend-failure`. Raw exceptions and
+backend messages do not cross the normalized boundary.
+
+### Input and artifacts
+
+The adapter imposes a 16 KiB statement limit, below the syntax contract's
+general 1 MiB ceiling. A larger statement returns
+`unsupported/resource-limit` before importing or invoking the backend.
+This conservative limit bounds work and temporary parser memory, but it does
+not satisfy the provisional active-statement latency envelope: warm local
+16 KiB parses already exceed that target. Placement measurements must set a
+lower interactive limit or move parsing off the main thread.
+
+The backend receives only the exact, untrimmed, code-bearing statement source.
+It receives no terminator, document coordinates, editor state, catalog, cursor,
+or host context.
+
+A successful result must contain exactly one object root with a string `type`.
+A direct object or one-element array is accepted. Zero or multiple roots are
+`unsupported/uncovered-construct`; malformed roots are
+`failed/malformed-output`.
+
+The public normalized artifact exposes only its closed statement kind and full
+statement-relative range. The backend AST is retained in a module-private
+`WeakMap` keyed by the authenticated artifact. It is neither enumerable nor
+returned through the syntax contract. Future relation extraction must decode
+and validate backend nodes inside the adapter boundary rather than exposing
+the raw AST to core features.
+
+### Cancellation and execution placement
+
+The callback checks cancellation before loading, after loading, and after
+parsing. These checks preserve the syntax runner's request-lifecycle behavior,
+but they cannot preempt synchronous parser execution.
+
+The adapter must not be wired into interactive session requests until a
+follow-up decision records one of:
+
+- Worker/process isolation with enforceable wall-clock and memory limits, or
+- Measured main-thread execution with an accepted adversarial-input risk and
+  explicit scheduling policy.
+
+That decision must include browser measurements, cancellation behavior,
+worker/module failure recovery, and the effect of many mounted editors.
+
+The current production loader supports pure Node only. A future browser
+integration must invoke parsing from a dedicated worker whose global object is
+not shared with application code, the legacy parser, or another installed copy.
+The unsupported-realm rejection remains until that isolated execution path
+exists.
+
+## Consequences
+
+- Local parsing can be evaluated without exposing a backend AST or
+  committing the language service to one parser.
+- PostgreSQL and BigQuery false negatives degrade to unsupported instead of
+  false invalid diagnostics.
+- PostgreSQL and BigQuery acceptance remains useful without claiming target
+  conformance.
+- DuckDB compatibility remains useful without pretending to be native
+  conformance.
+- Consumers do not load every node-sql-parser grammar.
+- The 16 KiB limit and lack of session wiring intentionally restrict initial
+  capability.
+- Authoritative invalidity requires a separately justified validator and an
+  owned dialect conformance corpus.
+
+## Non-goals
+
+This decision does not define:
+
+- Stable parser or provider APIs
+- Session cache keys or eviction
+- Document-level syntax diagnostics
+- Semantic relation, scope, column, or type models
+- A worker protocol
+- Native DuckDB or remote validation providers
+- Dremio parsing

docs/vnext/node-sql-parser-adapter.md

@@ -0,0 +1,116 @@
+# vNext node-sql-parser Adapter
+
+Status: internal and not wired to sessions
+
+The first concrete syntax adapter exercises the normalized contract from
+[ADR 0002](../adr/0002-normalized-syntax-contract.md) under the evidence and
+execution policy in
+[ADR 0003](../adr/0003-node-sql-parser-adapter.md). It is not exported from
+`/vnext` and does not currently power completion, diagnostics, hover,
+navigation, or any other editor feature.
+
+## Capability matrix
+
+| Dialect | Backend | Acceptance | Rejection |
+| --- | --- | --- | --- |
+| PostgreSQL | PostgreSQL-specific build | `parsed/compatibility` with `partial-artifact` | `unsupported/uncovered-construct` |
+| BigQuery | BigQuery-specific build | `parsed/compatibility` with `partial-artifact` | `unsupported/uncovered-construct` |
+| DuckDB | PostgreSQL-specific build | `parsed/compatibility` with `dialect-compatibility`, `partial-artifact` | `unsupported/compatibility-rejected` |
+| Dremio | None | Unavailable when coordinator wiring exists | `unavailable/dialect-not-supported` |
+
+This adapter never returns `direct` or `invalid`. The PostgreSQL and BigQuery
+grammars both reject valid target-dialect constructs and accept constructs the
+target engines reject. Acceptance therefore records only a partial
+compatibility artifact; rejection is not an authoritative syntax diagnostic.
+
+## Loading and packaging
+
+The implementation is tied to an exact `node-sql-parser` 5.4.0 pin and loads
+only:
+
+```text
+node-sql-parser/build/postgresql.js
+node-sql-parser/build/bigquery.js
+```
+
+The complete all-dialect entry point is not used. In pure Node, the adapter
+dynamically acquires `createRequire`, revalidates the realm, then synchronously
+requires the selected build so evaluation and cleanup cannot be interleaved
+with another task. Runtime module decoding handles the package's CommonJS shape
+rather than trusting its inaccurate named-export declarations.
+
+The adapter invokes `astify` with location collection enabled and query
+trimming disabled. Disabling trimming preserves offsets relative to the exact
+statement slice. Locations remain partial: PostgreSQL commonly omits root and
+identifier locations, while BigQuery provides broader but still incomplete
+coverage.
+
+Loading the distributed bundles may write `NodeSQLParser` or `global` on a
+global object. The adapter rejects parser loads whenever `window` or `self`
+exists, or `global` does not resolve exactly to `globalThis`, before loading a
+bundle. This blocks browser windows and Node DOM shims from exposing an
+unguarded secondary target. Pure Node loads restore the exact prior descriptors
+synchronously after module evaluation, including removing names that were
+previously absent. Cleanup failure permanently poisons loading. A
+dedicated-worker loader remains future work.
+
+Approximate local Node 24 arm64 measurements for the installed package were:
+
+| Build | Raw size | gzip size | Cold import |
+| --- | ---: | ---: | ---: |
+| PostgreSQL-specific | 308,145 B | 58,648 B | 19 ms |
+| BigQuery-specific | 208,264 B | 41,828 B | 14 ms |
+| All dialects | 2,505,457 B | 428,097 B | Not selected |
+
+These figures are investigation evidence, not cross-machine performance
+guarantees. Reproducible browser and bundle baselines are required before
+session integration.
+
+## Input and output rules
+
+The adapter accepts at most 16 KiB of statement text. Larger statements return
+`unsupported/resource-limit` before a backend import or parse.
+
+The input is the exact code-bearing normal statement source:
+
+- Leading and trailing trivia are retained.
+- A statement terminator is excluded.
+- The source is not trimmed or rewritten.
+- The backend receives no editor state, document offset, cursor, catalog, or
+  host context.
+
+A usable backend result has exactly one object root with a string `type`. The
+adapter accepts either that object directly or a one-element array containing
+it. Empty or multi-root output is uncovered; structurally malformed output is a
+backend contract failure.
+
+Normalized statement kinds are intentionally small:
+
+| Backend type | Normalized kind |
+| --- | --- |
+| `select`, `union` | `query` |
+| `insert`, `replace` | `insert` |
+| `update`, `delete`, `create`, `alter`, `drop`, `merge`, `transaction` | Same closed kind |
+| Any other string | `other` |
+
+Only the normalized kind and full statement-relative range appear in the
+syntax artifact. The raw AST stays in private weakly keyed storage for a future
+adapter-owned semantic decoder. Flat `tableList` and `columnList` output is not
+used as the semantic model.
+
+## Failure and cancellation behavior
+
+Expected PostgreSQL and BigQuery PEG rejections are uncovered capability, not
+failures. DuckDB rejection is compatibility rejection. Unexpected native
+exceptions, module-load failures, and malformed module or AST values remain
+explicit backend failures; raw exceptions are not retained in results.
+
+Cancellation is checked before and after asynchronous loading and after the
+parse. The parse itself is synchronous and cannot be interrupted by an
+`AbortSignal` while it blocks JavaScript. A late result can be discarded, but
+the CPU work has already occurred. Unsupported execution realms fail closed
+without importing a backend.
+
+For that reason, this adapter remains unwired. A worker-versus-main-thread ADR,
+with browser latency, memory, hostile-input, timeout, and recovery evidence, is
+required before interactive sessions may call it.

package.json

@@ -24,6 +24,7 @@
     "test:coverage:changed": "node ./scripts/changed-coverage.mjs",
     "test:browser": "vitest run --config vitest.browser.config.ts",
     "test:integrity": "node ./scripts/check-test-integrity.mjs",
+    "bench:parser-adapter": "vitest bench --run src/vnext/__tests__/node-sql-parser-adapter.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",
@@ -95,6 +96,6 @@
   },
   "module": "./dist/index.js",
   "dependencies": {
-    "node-sql-parser": "^5.3.13"
+    "node-sql-parser": "5.4.0"
   }
 }

pnpm-lock.yaml

@@ -0,0 +1,5 @@
+declare module "node:module" {
+  export function createRequire(
+    filename: string,
+  ): (specifier: string) => unknown;
+}