feat(vnext): define normalized syntax contract

[Light2Dark]

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.

---

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.

^{Written for commit ed58bac. Summary will update on new commits.}

[Light2Dark]

@cubic-dev-ai review please

[cubic-dev-ai]

@cubic-dev-ai review please

@Light2Dark I have started the AI code review. It will take a few minutes to complete.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	97.9% (🎯 91%)	280 / 286
🔵	Statements	97.91% (🎯 91%)	282 / 288
🔵	Functions	100% (🎯 90%)	45 / 45
🔵	Branches	95.16% (🎯 85%)	177 / 186

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/vnext/syntax.ts	97.91%	95.16%	100%	97.9%	650-653, 680-683, 688-691, 965-968, 1194-1197, 1240-1242

Generated in workflow #687 for commit ed58bac by the Vitest Coverage Report Action

[cubic-dev-ai]

All reported issues were addressed across 5 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[Copilot]

Pull request overview

Defines a new internal vNext “normalized syntax” contract for SQL statement parsing, with runtime-authenticated artifacts/diagnostics/analyses and a single parser runner that validates and normalizes backend behavior. This fits the codebase’s vNext direction by tightening the boundary between lexical eligibility (statement indexing) and parser evidence, while keeping stable vNext exports unchanged.

Changes:

• Adds src/vnext/syntax.ts: branded/opaque identities, statement-relative ranges, normalized artifact + diagnostic + analysis constructors, and runSqlStatementParser to authenticate/normalize parser output.
• Adds comprehensive runtime tests (vitest) and compile-time type tests (d.ts) to enforce the contract’s invariants and impossible-state exclusions.
• Documents the boundary via ADR 0002 and links it from ADR 0001.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/vnext-types/syntax.test-d.ts	Type-level assertions ensuring the normalized syntax contract types can’t be fabricated and impossible combinations are rejected.
src/vnext/syntax.ts	Core implementation of the normalized syntax contract (brands, identities, constructors, authenticated runner, and bounded inputs/collections).
src/vnext/tests/syntax.test.ts	Runtime unit tests validating invariants, rejection behavior, and runner normalization/authentication semantics.
docs/adr/0002-normalized-syntax-contract.md	New ADR specifying the internal contract, invariants, and non-goals.
docs/adr/0001-language-service-and-session.md	References ADR 0002 as the first internal syntax boundary.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.