refactor(vnext): extract realm-neutral parser backend

[Light2Dark]

Summary

• extract module decoding, parser invocation, result validation, and error normalization into an internal realm-neutral backend
• preserve Node-specific realm validation, module loading, cleanup, parser authority, and private AST ownership in the existing adapter
• add exhaustive backend contract tests covering bounds, cancellation checkpoints, retry caching, hostile values, and ambient neutrality
• document the host/engine responsibility boundary

No public export, session wiring, worker protocol, or user-visible API is added.

Validation

• 1,041 unit tests passed; 1 intentional expected failure
• vNext coverage: 98.54% statements, 97.06% branches, 100% functions, 98.53% lines
• new backend coverage: 100% statements, branches, functions, and lines
• source and test TypeScript checks
• oxlint and test-integrity checks
• Chromium browser tests
• exact packed-consumer smoke test
• isolated worker placement and bundle-budget harness
• demo production build
• parser adapter benchmark
• git diff check

Independent review

Two independent adversarial reviewers approved exact commit 96bd2ce with zero actionable findings.

---

Summary by cubic

Extracted a new internal backend for node-sql-parser and rewired the Node adapter to call it. No public API changes.

• Refactors

  • New node-sql-parser-backend: decodes module, runs astify, validates output, and normalizes errors; no Node/window/worker refs.
  • Node adapter now only handles realm checks, require loading, cleanup, parser authority, and private AST ownership; uses backend outcomes.
  • Unified backend outcomes; concurrent load de‑dup and retry cache; enforces MAX_NODE_SQL_PARSER_STATEMENT_LENGTH.
  • Accepts constructor/default/module.exports/named Parser; ignores accessors/proxies and redacts private data.
  • Added backend tests (bounds, cancellation, retry, hostile values, ambient neutrality) and documented the host/engine boundary.

• Bug Fixes

  • Validate AST array lengths, rejecting spoofed or non‑integer length descriptors.

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

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	98.37% (🎯 91%)	242 / 246
🔵	Statements	98.39% (🎯 91%)	245 / 249
🔵	Functions	100% (🎯 90%)	46 / 46
🔵	Branches	98.8% (🎯 85%)	166 / 168

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/vnext/node-sql-parser-adapter.ts	96.33%	96.22%	100%	96.26%	74, 101, 146, 238-242
src/vnext/node-sql-parser-backend.ts	100%	100%	100%	100%

Generated in workflow #697 for commit 08a9d67 by the Vitest Coverage Report Action

[Copilot]

Pull request overview

This PR refactors the vNext node-sql-parser integration by extracting module decoding, parser invocation, output validation, and error normalization into a new internal realm-neutral backend, while keeping Node-specific realm validation and module loading in the existing adapter.

Changes:

• Added createNodeSqlParserBackend as a realm-neutral engine with standardized outcomes, retry caching, and cancellation checkpoints.
• Rewired the Node adapter to delegate parsing to the backend while preserving Node-only responsibilities (realm validation, module loading/cleanup, authority, and AST ownership).
• Added comprehensive backend contract tests and expanded docs to clarify the host/engine responsibility boundary.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
src/vnext/node-sql-parser-backend.ts	New realm-neutral backend implementing module decoding, parsing, validation, normalized outcomes, and retry caching.
src/vnext/node-sql-parser-adapter.ts	Refactor to delegate parsing to the new backend while retaining Node-specific realm checks and module loading.
src/vnext/tests/node-sql-parser-backend.test.ts	New exhaustive tests covering backend contract behavior, hostile values, caching, and ambient neutrality.
docs/vnext/node-sql-parser-adapter.md	Documentation update describing the new backend/adapter responsibility split.

---

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

[cubic-dev-ai]

1 issue found and verified against the latest diff

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/vnext/node-sql-parser-backend.ts">

<violation number="1" location="src/vnext/node-sql-parser-backend.ts:110">
P3: Hostile-property decoding now has two independent implementations in the backend and adapter, so fixes to descriptor/proxy handling can drift between their module boundaries. A shared realm-neutral property-reader utility would preserve the same behavior in both paths.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: Hostile-property decoding now has two independent implementations in the backend and adapter, so fixes to descriptor/proxy handling can drift between their module boundaries. A shared realm-neutral property-reader utility would preserve the same behavior in both paths.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/vnext/node-sql-parser-backend.ts, line 110:

<comment>Hostile-property decoding now has two independent implementations in the backend and adapter, so fixes to descriptor/proxy handling can drift between their module boundaries. A shared realm-neutral property-reader utility would preserve the same behavior in both paths.</comment>

<file context>
@@ -0,0 +1,427 @@
+  return typeof value === "object" && value !== null;
+}
+
+function readOwnDataProperty(
+  value: object,
+  key: PropertyKey,
</file context>

[Light2Dark]

Cubic P3 disposition: no code change. The two descriptor readers are deliberately boundary-owned and do not share one semantic contract. The Node adapter inspects inherited realm aliases (window, self, global) to reject unsafe execution environments, while the realm-neutral backend accepts only own data for third-party module/AST/error decoding and separately walks prototypes only for astify. Sharing a generic hostile-value utility would couple distinct trust policies and make accidental policy reuse easier. Both paths have dedicated proxy/accessor/descriptor-trap tests; we will revisit extraction if a third boundary establishes a genuinely common contract.