feat(vnext): prepare local relation evidence (#191)

## Summary

- add a package-private prepared statement handle that composes
authenticated query-site and CTE-visibility evidence
- preserve qualified, inactive, ambiguous, opaque, and resource-limited
states without inventing local candidates
- authenticate complete CTE layout results so active-statement resource
failures survive orchestration
- add four-dialect integration coverage and cold/warm performance
baselines

## Why

The relation-completion session needs one immutable artifact it can
cache per
source, statement slot, and dialect. Keeping preparation separate from
position projection avoids rebuilding CTE layout state as the cursor
moves,
while the opaque handle prevents stale or independently mixable evidence
from
crossing sessions.

This remains package-private until the catalog and end-to-end completion
slice
prove the public API described by ADR 0005.

## Evidence

- 1,691 passing unit tests plus one governed expected failure
- all five TypeScript configurations, oxlint, integrity, package smoke,
worker placement, and browser suites pass
- changed coverage: 97.05% statements, 95.77% branches, 100% functions,
97.04% lines
- warm projection: approximately 0.65 ms for a 10 KiB statement and 0.32
ms for 256 CTEs

Roadmap: #169


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Introduce a package-private prepared statement that authenticates
query-site and CTE visibility to power local relation completion. It
preserves qualified/inactive/opaque/ambiguous/resource-limited states
and adds four-dialect coverage; supports #169.

- **New Features**
- Added `prepareSqlLocalRelationStatement` and
`analyzeSqlLocalRelationSite` for deterministic, cacheable local
evidence (results are frozen).
- Propagated authenticated CTE layout through `relation-query-site`,
including active-statement resource failures.
- Added `isSqlStatementSlotSnapshotFor` and authenticated layout
registration/lookup to validate provenance.
- Added `bench:local-relation-site` plus tests and benches across
PostgreSQL, DuckDB, BigQuery, and Dremio.

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

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

package.json

@@ -26,6 +26,7 @@
     "test:browser": "vitest run --config vitest.browser.config.ts",
     "test:worker-placement": "node ./scripts/worker-placement.mjs",
     "test:integrity": "node ./scripts/check-test-integrity.mjs",
+    "bench:local-relation-site": "vitest bench --run src/vnext/__tests__/local-relation-site.bench.ts",
     "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",

src/vnext/__tests__/local-relation-site.bench.ts

@@ -0,0 +1,134 @@
+import { bench, describe } from "vitest";
+import { MAX_CTE_DECLARATIONS } from "../cte-layout.js";
+import {
+  analyzeSqlLocalRelationSite,
+  prepareSqlLocalRelationStatement,
+  type SqlLocalRelationStatement,
+} from "../local-relation-site.js";
+import { DUCKDB_SQL_RELATION_DIALECT } from "../relation-dialect.js";
+import { createIdentitySqlSource } from "../source.js";
+import {
+  buildSqlStatementIndex,
+  findSqlStatementSlot,
+} from "../statement-index.js";
+
+interface Fixture {
+  readonly index: ReturnType<typeof buildSqlStatementIndex>;
+  readonly position: number;
+  readonly slot: ReturnType<typeof findSqlStatementSlot>;
+  readonly source: ReturnType<typeof createIdentitySqlSource>;
+  readonly statement: SqlLocalRelationStatement;
+}
+
+function fixture(text: string): Fixture {
+  const source = createIdentitySqlSource(text);
+  const index = buildSqlStatementIndex(
+    source.analysisText,
+    DUCKDB_SQL_RELATION_DIALECT.querySite.lexicalProfile,
+  );
+  const position = text.length;
+  const slot = findSqlStatementSlot(index, position, "left");
+  const preparation = prepareSqlLocalRelationStatement(
+    source,
+    index,
+    slot,
+    DUCKDB_SQL_RELATION_DIALECT,
+  );
+  if (preparation.status === "unavailable") {
+    throw new Error("Local relation benchmark must prepare");
+  }
+  return {
+    index,
+    position,
+    slot,
+    source,
+    statement: preparation.statement,
+  };
+}
+
+function coldAnalyze(value: Fixture) {
+  const preparation = prepareSqlLocalRelationStatement(
+    value.source,
+    value.index,
+    value.slot,
+    DUCKDB_SQL_RELATION_DIALECT,
+  );
+  if (preparation.status === "unavailable") {
+    throw new Error("Cold local relation benchmark must prepare");
+  }
+  return analyzeSqlLocalRelationSite(
+    preparation.statement,
+    value.position,
+  );
+}
+
+const tenKibibytes = 10 * 1_024;
+const withPrefix = "WITH local_cte AS (SELECT 1) SELECT ";
+const withSuffix = " FROM target";
+const projectionLength =
+  tenKibibytes - withPrefix.length - withSuffix.length;
+const withText = `${withPrefix}${"x,".repeat(
+  Math.floor((projectionLength - 1) / 2),
+)}x${withSuffix}`;
+const paddedWithText = `${withText.slice(
+  0,
+  -withSuffix.length,
+)}${" ".repeat(tenKibibytes - withText.length)}${withSuffix}`;
+if (paddedWithText.length !== tenKibibytes) {
+  throw new Error("Local relation benchmark must be exactly 10 KiB");
+}
+const withFixture = fixture(paddedWithText);
+
+const maximumCteText = `WITH ${Array.from(
+  { length: MAX_CTE_DECLARATIONS },
+  (_, index) => `c${index} AS (SELECT ${index})`,
+).join(", ")} SELECT * FROM target`;
+const maximumCteFixture = fixture(maximumCteText);
+
+const withPreflight = analyzeSqlLocalRelationSite(
+  withFixture.statement,
+  withFixture.position,
+);
+const maximumCtePreflight = analyzeSqlLocalRelationSite(
+  maximumCteFixture.statement,
+  maximumCteFixture.position,
+);
+if (
+  withPreflight.status !== "ready" ||
+  withPreflight.local.kind !== "unqualified" ||
+  withPreflight.local.cteVisibility.ctes.length !== 1
+) {
+  throw new Error("10 KiB benchmark must expose one visible CTE");
+}
+if (
+  maximumCtePreflight.status !== "ready" ||
+  maximumCtePreflight.local.kind !== "unqualified" ||
+  maximumCtePreflight.local.cteVisibility.ctes.length !==
+    MAX_CTE_DECLARATIONS
+) {
+  throw new Error("Maximum benchmark must expose every CTE");
+}
+
+describe("local relation site", () => {
+  bench("cold 10 KiB WITH statement", () => {
+    coldAnalyze(withFixture);
+  });
+
+  bench("warm 10 KiB WITH statement", () => {
+    analyzeSqlLocalRelationSite(
+      withFixture.statement,
+      withFixture.position,
+    );
+  });
+
+  bench("cold 256-CTE statement", () => {
+    coldAnalyze(maximumCteFixture);
+  });
+
+  bench("warm 256-CTE statement", () => {
+    analyzeSqlLocalRelationSite(
+      maximumCteFixture.statement,
+      maximumCteFixture.position,
+    );
+  });
+});