feat(vnext): add namespace catalog completion

Author: Light2Dark

docs/vnext/namespace-catalog-authority.md

@@ -0,0 +1,37 @@
+# vNext Namespace Catalog Authority
+
+Status: integration-ready internal vertical slice
+
+Namespace completion searches catalog, schema, project, and dataset containers.
+One query site produces one bounded provider request containing its qualifier,
+prefix, search paths, result limit, dialect, scope, and expected catalog epoch.
+The API does not recursively walk a provider tree or issue one request per
+container.
+
+Each result has a stable container entity ID, a canonical role-tagged identifier
+path, provider-rendered insertion text, match quality, and immutable provenance.
+The hostile boundary rejects accessors, sparse arrays, extra properties,
+oversized data, invalid epochs, and conflicting duplicate identities. Identical
+duplicate identities are collapsed and results receive deterministic code-unit
+ordering.
+
+The composer applies the dialect's prefix matcher, deduplicates by authority
+identity, and produces deterministic completion edits. Unknown or throwing
+prefix comparison is reported as incomplete instead of guessing.
+
+## Epoch, cache, and lifecycle
+
+A cold request uses `expectedEpoch: null`; the returned epoch becomes the
+owner's observed epoch. Complete ready searches are held in a bounded LRU keyed
+by provider instance, scope, dialect, epoch, query site, search paths, and limit.
+Partial, loading, and failed responses remain visible but are never cached.
+
+A newer request supersedes and aborts prior work for the same owner. Explicit
+cancellation and owner/coordinator disposal abort pending work. Provider throws,
+rejections, malformed data, and late settlements are contained.
+
+Session integration should prepare one owner for each live scope/dialect and
+dispose it when catalog authority changes. Query-site integration calls
+`prepareSqlNamespaceCatalogSearch`, submits the result through the owner, and
+passes the outcome plus the site's replacement range and dialect prefix matcher
+to `composeSqlNamespaceCompletion`.

src/vnext/__tests__/namespace-catalog-boundary.test.ts

@@ -0,0 +1,265 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  captureSqlNamespaceCatalogProvider,
+  createSqlNamespaceCatalogSearchRequest,
+  decodeSqlNamespaceCatalogSearchResponse,
+  MAX_NAMESPACE_RESULTS,
+  resolveSqlNamespaceCatalogProvider,
+} from "../namespace-catalog-boundary.js";
+
+const epoch = Object.freeze({ generation: 1, token: "one" });
+
+function request(expectedEpoch = epoch) {
+  const result = createSqlNamespaceCatalogSearchRequest({
+    dialectId: "duckdb",
+    expectedEpoch,
+    limit: 10,
+    prefix: { quoted: false, value: "ma" },
+    qualifier: [{ quoted: false, value: "memory" }],
+    scope: "connection",
+    searchPaths: [[{ quoted: false, value: "main" }]],
+  });
+  if (result.status !== "accepted") throw new Error("request");
+  return result.value;
+}
+
+function captured(search: unknown = vi.fn()) {
+  const result = captureSqlNamespaceCatalogProvider({
+    id: "namespaces",
+    search,
+  });
+  if (result.status !== "accepted") throw new Error("provider");
+  return result.value;
+}
+
+function container(
+  id: string,
+  role: "catalog" | "dataset" | "project" | "schema",
+  value: string,
+) {
+  return {
+    canonicalPath: [{
+      quoted: false,
+      role,
+      value,
+    }],
+    containerEntityId: id,
+    detail: `${role} detail`,
+    insertText: value,
+    matchQuality: "exact",
+  };
+}
+
+describe("namespace catalog boundary", () => {
+  it("captures provider methods without exposing a receiver", () => {
+    const receivers: unknown[] = [];
+    const search = function (this: unknown) {
+      receivers.push(this);
+    };
+    const handle = captured(search);
+    const context = resolveSqlNamespaceCatalogProvider(handle);
+    expect(context?.id).toBe("namespaces");
+    context?.search(request(), new AbortController().signal);
+    expect(receivers).toEqual([undefined]);
+    expect(Object.isFrozen(handle)).toBe(true);
+  });
+
+  it("rejects hostile or invalid providers", () => {
+    const accessor = {};
+    Object.defineProperty(accessor, "id", { get: vi.fn() });
+    expect(captureSqlNamespaceCatalogProvider(accessor).status)
+      .toBe("malformed");
+    expect(captureSqlNamespaceCatalogProvider(null).status)
+      .toBe("malformed");
+    expect(captureSqlNamespaceCatalogProvider({
+      id: "",
+      search() {},
+    }).status).toBe("malformed");
+    expect(captureSqlNamespaceCatalogProvider({
+      id: "x",
+      search: 1,
+    }).status).toBe("malformed");
+    expect(captureSqlNamespaceCatalogProvider({
+      extra: true,
+      id: "x",
+      search() {},
+    }).status).toBe("malformed");
+    expect(captureSqlNamespaceCatalogProvider(
+      new Proxy({}, { ownKeys: () => { throw new Error("trap"); } }),
+    ).status).toBe("malformed");
+  });
+
+  it("normalizes and freezes one bounded query-site search", () => {
+    const value = request();
+    expect(value).toEqual({
+      dialectId: "duckdb",
+      expectedEpoch: epoch,
+      limit: 10,
+      prefix: { quoted: false, value: "ma" },
+      qualifier: [{ quoted: false, value: "memory" }],
+      scope: "connection",
+      searchPaths: [[{ quoted: false, value: "main" }]],
+    });
+    expect(Object.isFrozen(value)).toBe(true);
+    expect(Object.isFrozen(value.prefix)).toBe(true);
+    expect(Object.isFrozen(value.qualifier)).toBe(true);
+    expect(Object.isFrozen(value.searchPaths[0])).toBe(true);
+    expect(createSqlNamespaceCatalogSearchRequest({
+      ...value,
+      expectedEpoch: null,
+    }).status).toBe("accepted");
+  });
+
+  it("rejects malformed, sparse, accessor, and oversized requests", () => {
+    const valid = request();
+    const sparse: unknown[] = [];
+    sparse.length = 1;
+    const cases: unknown[] = [
+      null,
+      { ...valid, extra: true },
+      { ...valid, dialectId: "" },
+      { ...valid, scope: "" },
+      { ...valid, expectedEpoch: undefined },
+      { ...valid, expectedEpoch: { generation: -1, token: "x" } },
+      { ...valid, expectedEpoch: { generation: 1.5, token: "x" } },
+      { ...valid, expectedEpoch: { generation: 1, token: "" } },
+      { ...valid, limit: 0 },
+      { ...valid, limit: MAX_NAMESPACE_RESULTS + 1 },
+      { ...valid, limit: 1.5 },
+      { ...valid, prefix: { quoted: "no", value: "x" } },
+      { ...valid, prefix: { quoted: false, value: "x", extra: 1 } },
+      { ...valid, qualifier: sparse },
+      { ...valid, searchPaths: sparse },
+      { ...valid, qualifier: [{ quoted: false, value: "x".repeat(257) }] },
+      { ...valid, searchPaths: Array.from({ length: 33 }, () => []) },
+    ];
+    const accessor = { ...valid };
+    Object.defineProperty(accessor, "prefix", { get: vi.fn() });
+    cases.push(accessor);
+    for (const value of cases) {
+      expect(createSqlNamespaceCatalogSearchRequest(value).status)
+        .toBe("malformed");
+    }
+  });
+
+  it("decodes, deduplicates, orders, and freezes all container roles", () => {
+    const provider = captured();
+    const decoded = decodeSqlNamespaceCatalogSearchResponse(
+      provider,
+      request(),
+      {
+        containers: [
+          container("schema", "schema", "main"),
+          { ...container("schema", "schema", "main") },
+          container("project", "project", "alpha"),
+          container("dataset", "dataset", "events"),
+          container("catalog", "catalog", "memory"),
+        ],
+        coverage: "partial",
+        epoch,
+        status: "ready",
+      },
+    );
+    expect(decoded.status).toBe("accepted");
+    if (decoded.status !== "accepted" ||
+      decoded.value.status !== "ready") return;
+    expect(decoded.value.containers.map((value) =>
+      value.canonicalPath[0]?.role
+    )).toEqual(["catalog", "dataset", "project", "schema"]);
+    expect(decoded.value.containers[0]?.provenance).toEqual({
+      containerEntityId: "catalog",
+      epoch,
+      providerId: "namespaces",
+      scope: "connection",
+    });
+    expect(Object.isFrozen(decoded.value)).toBe(true);
+    expect(Object.isFrozen(decoded.value.containers)).toBe(true);
+    expect(Object.isFrozen(
+      decoded.value.containers[0]?.canonicalPath,
+    )).toBe(true);
+  });
+
+  it("decodes loading and normalized failures", () => {
+    const provider = captured();
+    expect(decodeSqlNamespaceCatalogSearchResponse(
+      provider,
+      request(),
+      { epoch, status: "loading" },
+    )).toMatchObject({
+      status: "accepted",
+      value: { status: "loading" },
+    });
+    expect(decodeSqlNamespaceCatalogSearchResponse(
+      provider,
+      request(),
+      {
+        code: "rate-limited",
+        epoch,
+        retry: "next-request",
+        status: "failed",
+      },
+    )).toMatchObject({
+      status: "accepted",
+      value: {
+        code: "rate-limited",
+        retry: "next-request",
+        status: "failed",
+      },
+    });
+  });
+
+  it("rejects malformed, conflicting, stale, and oversized responses", () => {
+    const provider = captured();
+    const valid = {
+      containers: [container("one", "schema", "main")],
+      coverage: "complete",
+      epoch,
+      status: "ready",
+    };
+    const conflicting = {
+      ...valid,
+      containers: [
+        container("same", "schema", "main"),
+        container("same", "schema", "other"),
+      ],
+    };
+    const malformedContainers = [
+      { ...container("x", "schema", "x"), canonicalPath: [] },
+      { ...container("x", "schema", "x"), canonicalPath: [{
+        quoted: false,
+        role: "table",
+        value: "x",
+      }] },
+      { ...container("x", "schema", "x"), containerEntityId: "" },
+      { ...container("x", "schema", "x"), insertText: "" },
+      { ...container("x", "schema", "x"), matchQuality: "bad" },
+      { ...container("x", "schema", "x"), detail: 1 },
+    ];
+    const cases: unknown[] = [
+      null,
+      { ...valid, extra: true },
+      { ...valid, epoch: { generation: 2, token: "two" } },
+      { ...valid, coverage: "unknown" },
+      { ...valid, containers: Array.from(
+        { length: 11 },
+        (_, index) => container(String(index), "schema", String(index)),
+      ) },
+      conflicting,
+      { epoch, extra: true, status: "loading" },
+      { code: "bad", epoch, retry: "never", status: "failed" },
+      { code: "unknown", epoch, retry: "bad", status: "failed" },
+      { code: "unknown", epoch, retry: "never", status: "failed", x: 1 },
+      ...malformedContainers.map((value) => ({
+        ...valid,
+        containers: [value],
+      })),
+    ];
+    for (const value of cases) {
+      expect(decodeSqlNamespaceCatalogSearchResponse(
+        provider,
+        request(),
+        value,
+      ).status).toBe("malformed");
+    }
+  });
+});

src/vnext/__tests__/namespace-catalog-coordinator.bench.ts

@@ -0,0 +1,69 @@
+import { bench, describe } from "vitest";
+import {
+  createSqlNamespaceCatalogCoordinator,
+} from "../namespace-catalog-coordinator.js";
+import type {
+  SqlNamespaceCatalogSearchRequest,
+} from "../namespace-catalog-types.js";
+
+const epoch = Object.freeze({ generation: 1, token: "bench" });
+
+function response(request: SqlNamespaceCatalogSearchRequest) {
+  return {
+    containers: Array.from({ length: 100 }, (_, index) => ({
+      canonicalPath: [
+        { quoted: false, role: "catalog", value: "memory" },
+        { quoted: false, role: "schema", value: `schema_${index}` },
+      ],
+      containerEntityId: `schema:${index}`,
+      insertText: `schema_${index}`,
+      matchQuality: "exact",
+    })),
+    coverage: "complete",
+    epoch: request.expectedEpoch ?? epoch,
+    status: "ready",
+  };
+}
+
+function owner() {
+  const created = createSqlNamespaceCatalogCoordinator({
+    provider: {
+      id: "benchmark",
+      search: (request: SqlNamespaceCatalogSearchRequest) =>
+        Promise.resolve(response(request)),
+    },
+  });
+  if (created.status !== "created") throw new Error("coordinator");
+  const prepared = created.coordinator.prepareOwner({
+    dialectId: "duckdb",
+    scope: "benchmark",
+  });
+  if (prepared.status !== "prepared") throw new Error("owner");
+  return prepared.owner;
+}
+
+const search = Object.freeze({
+  expectedEpoch: epoch,
+  limit: 100,
+  prefix: Object.freeze({ quoted: false, value: "schema" }),
+  qualifier: Object.freeze([
+    Object.freeze({ quoted: false, value: "memory" }),
+  ]),
+  searchPaths: Object.freeze([]),
+});
+
+describe("namespace catalog coordinator", () => {
+  bench("cold 100-container search", async () => {
+    const current = owner();
+    await current.request(search).result;
+    current.dispose();
+  });
+
+  const warm = owner();
+  const primed = warm.request(search).result;
+
+  bench("warm 100-container cache lookup", async () => {
+    await primed;
+    await warm.request(search).result;
+  });
+});