feat(vnext): recognize bounded relation query sites (#186)

## Summary

- add a private parser-independent partial `SELECT` relation-site
recognizer
- authenticate full relation paths and statement-relative UTF-16
replacement ranges
- enforce dialect-owned identifier/path decoding and path depth under a
global safety ceiling
- recognize base `FROM`, qualified prefixes, aliases, joins, same-depth
commas, nested queries, and dialect-owned `NATURAL` joins
- authenticate the bounded `USING(identifier [, identifier ...])`
grammar before crossing a join constraint
- deliberately fail closed on `ON` until a parser-backed or separately
specified expression recognizer can prove its boundary
- preserve frame-local nested-query recognition after proven relation
transitions and valid `USING` clause exits

## Safety and performance

- active statement: 65,536 UTF-16 units
- lexemes: 16,384
- nesting: 128
- path: dialect limit under global 32
- decoded identifier segment: 256 UTF-16 units
- exact 10 KiB statement: about 0.56 ms mean
- 1,000 classified aliases: about 0.36 ms mean
- 1,000 authenticated `USING` columns: about 0.21 ms mean
- recognizer state remains bounded per query frame and per active
`USING` constraint

## Verification

- 1,537 tests passed plus 1 expected failure
- changed coverage: 96.84% statements, 95.76% branches, 100% functions,
96.83% lines
- repository coverage: 95.31% statements, 92.04% branches, 96.14%
functions, 95.30% lines
- source, test, loose-optional, and demo typechecks pass
- repository oxlint, test-integrity, and diff checks pass
- browser, package, worker-placement, demo, and benchmark gates pass
- three independent adversarial reviewers approved exact commit
`01cd8d29bf99a7c07f6a72ca746da328847c6dfb`

Part of #169.

Author: Light2Dark

docs/adr/0005-parser-independent-relation-completion.md

@@ -97,12 +97,20 @@ embedded region are unavailable or inactive according to the closed result.
 CTE visibility is the one narrow scope-semantics exception; general
 parser-derived scope semantics remain deferred.
 
+The recognizer may cross a `USING` join constraint only after authenticating
+the complete bounded grammar `USING(identifier [, identifier ...])` with
+dialect-owned identifier validation. It does not interpret `ON` expressions:
+encountering `ON` makes the query site unavailable until a future
+parser-backed or separately specified expression recognizer can prove the
+boundary.
+
 The conformance corpus includes positive base `FROM`, qualified prefix,
-aliased `JOIN`, same-depth comma, and nested supported-query cases. It includes
+aliased `JOIN`, authenticated `USING`, same-depth comma, and nested
+supported-query cases. It includes
 negative `IS DISTINCT FROM`, `substring(... FROM ...)`, `extract(... FROM
-...)`, `DELETE FROM`, `COPY ... FROM`, set-operation, `QUALIFY`, `WINDOW`, join
-constraint, DML, and expression cases. A keyword match alone never creates a
-site.
+...)`, `DELETE FROM`, `COPY ... FROM`, set-operation, `QUALIFY`, `WINDOW`,
+`ON`, malformed `USING`, DML, and expression cases. A keyword match alone
+never creates a site.
 
 The result distinguishes:
 
@@ -518,7 +526,7 @@ The initial checked limits are:
 | Lexical tokens | 16,384 |
 | Parenthesis/query depth | 128 |
 | CTE declarations | 256 |
-| Identifier path segments | 4 |
+| Identifier path segments | 32 global ceiling; dialect runtime sets the checked limit |
 | Identifier segment | 256 UTF-16 units |
 | Catalog scope | 512 UTF-16 units |
 | Search paths | 32 |

package.json

@@ -27,6 +27,7 @@
     "test:worker-placement": "node ./scripts/worker-placement.mjs",
     "test:integrity": "node ./scripts/check-test-integrity.mjs",
     "bench:parser-adapter": "vitest bench --run src/vnext/__tests__/node-sql-parser-adapter.bench.ts",
+    "bench:query-site": "vitest bench --run src/vnext/__tests__/query-site.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",

src/vnext/__tests__/query-site.bench.ts

@@ -0,0 +1,106 @@
+import { bench, describe } from "vitest";
+import {
+  recognizeSqlRelationQuerySite,
+  type SqlQuerySiteDialect,
+} from "../query-site.js";
+import { createIdentitySqlSource } from "../source.js";
+import {
+  buildSqlStatementIndex,
+  DUCKDB_SQL_LEXICAL_PROFILE,
+  findSqlStatementSlot,
+} from "../statement-index.js";
+
+const dialect: SqlQuerySiteDialect = {
+  classifyIdentifierToken: (rawIdentifier) => ({
+    status: "identifier",
+    value: rawIdentifier,
+  }),
+  decodeRelationPath: (rawPath, cursorOffset) => ({
+    finalSegment: { from: 0, to: rawPath.length },
+    prefix: {
+      quoted: false,
+      value: rawPath.slice(0, cursorOffset),
+    },
+    qualifier: [],
+    quality: "exact",
+    status: "decoded",
+  }),
+  lexicalProfile: DUCKDB_SQL_LEXICAL_PROFILE,
+  maximumPathDepth: 16,
+  supportsNaturalJoin: true,
+};
+const TEN_KIBIBYTES = 10 * 1_024;
+const queryPrefix = "SELECT ";
+const querySuffix = " FROM schema_prefix";
+const projectedListLength =
+  TEN_KIBIBYTES - queryPrefix.length - querySuffix.length;
+const projectedList = `${"x,".repeat(
+  Math.floor((projectedListLength - 1) / 2),
+)}x`;
+const tenKilobyteQuery = `${queryPrefix}${projectedList}${" ".repeat(
+  projectedListLength - projectedList.length,
+)}${querySuffix}`;
+if (tenKilobyteQuery.length !== TEN_KIBIBYTES) {
+  throw new Error("Query benchmark fixture must be exactly 10 KiB");
+}
+const source = createIdentitySqlSource(tenKilobyteQuery);
+const index = buildSqlStatementIndex(
+  source.analysisText,
+  dialect.lexicalProfile,
+);
+const position = tenKilobyteQuery.length;
+const slot = findSqlStatementSlot(index, position, "left");
+const aliasHeavyQuery = `SELECT * FROM ${Array.from(
+  { length: 1_000 },
+  (_, aliasIndex) => `table_name alias_${aliasIndex}`,
+).join(", ")}, `;
+const aliasHeavySource = createIdentitySqlSource(aliasHeavyQuery);
+const aliasHeavyIndex = buildSqlStatementIndex(
+  aliasHeavySource.analysisText,
+  dialect.lexicalProfile,
+);
+const aliasHeavyPosition = aliasHeavyQuery.length;
+const aliasHeavySlot = findSqlStatementSlot(
+  aliasHeavyIndex,
+  aliasHeavyPosition,
+  "left",
+);
+const usingHeavyQuery = `SELECT * FROM first_table JOIN second_table USING(${Array.from(
+  { length: 1_000 },
+  (_, columnIndex) => `column_${columnIndex}`,
+).join(", ")}) JOIN target`;
+const usingHeavySource = createIdentitySqlSource(usingHeavyQuery);
+const usingHeavyIndex = buildSqlStatementIndex(
+  usingHeavySource.analysisText,
+  dialect.lexicalProfile,
+);
+const usingHeavyPosition = usingHeavyQuery.length;
+const usingHeavySlot = findSqlStatementSlot(
+  usingHeavyIndex,
+  usingHeavyPosition,
+  "left",
+);
+
+describe("query-site recognizer", () => {
+  bench("10 KiB active statement", () => {
+    recognizeSqlRelationQuerySite(source, slot, position, dialect);
+  });
+
+  bench("1,000 classified aliases", () => {
+    recognizeSqlRelationQuerySite(
+      aliasHeavySource,
+      aliasHeavySlot,
+      aliasHeavyPosition,
+      dialect,
+    );
+  });
+
+  bench("1,000 authenticated USING columns", () => {
+    recognizeSqlRelationQuerySite(
+      usingHeavySource,
+      usingHeavySlot,
+      usingHeavyPosition,
+      dialect,
+    );
+  });
+});