fix(vnext): bound auxiliary catalog refresh

Author: Light2Dark

docs/vnext/column-catalog-authority.md

@@ -5,8 +5,8 @@ Status: internal vertical-slice contract
 Column discovery is lazy, provider-owned, and batched. A completion request
 sends every unresolved relation reference in one provider invocation. Each
 reference carries a caller-local `requestKey`, a decoded identifier path, and
-an optional previously authenticated relation entity ID. The provider resolves
-paths against the supplied catalog scope, search paths, and dialect.
+no unauthenticated entity identity. The provider resolves paths against the
+supplied catalog scope, search paths, and dialect.
 
 The provider returns stable relation and column entity IDs. Every accepted
 column contains:
@@ -37,11 +37,11 @@ entries from another epoch. The cache is LRU-bounded by relation entries.
 Only complete ready results are cached. Partial, loading, and failed results
 remain visible to the caller but are eligible for another provider request.
 
-The initial coordinator does not subscribe to catalog invalidations. Until it
-is connected to the relation catalog's private epoch coordinator, a host must
-supersede or dispose the column owner when catalog authority changes. Session
-integration must not treat a cached complete result as current across a known
-catalog revision.
+Relation-catalog subscription events invalidate the session's relation, column,
+and namespace observations together. Hosts without a subscribed relation
+provider call `session.invalidateCatalog()` when schema authority changes. The
+method advances the session revision, cancels retained completion work, rebuilds
+all catalog owners, and emits one `catalog` change event.
 
 ## Lifecycle
 
@@ -55,3 +55,8 @@ cannot publish or populate the cache.
 The coordinator batches a request once, never once per relation. Cache hits and
 misses are composed deterministically while only misses are sent to the
 provider.
+
+Provider-declared loading receives at most one automatic retry for the same
+document, context, and completion position. A persistent loading response is
+then returned without a refresh token; hosts resume it through catalog
+invalidation instead of an unbounded polling loop.

docs/vnext/namespace-catalog-authority.md

@@ -36,3 +36,10 @@ disposes it when catalog authority changes. Query-site integration calls
 passes the outcome plus the site's replacement range and dialect prefix matcher
 to `composeSqlNamespaceCompletion`. Namespace items are merged with local and
 relation-catalog items under the same bounded completion response budget.
+Relation-catalog subscription events invalidate namespace observations.
+Namespace-only hosts, and hosts whose relation provider has no subscription,
+call `session.invalidateCatalog()` after a schema-authority change.
+
+Provider-declared loading receives at most one automatic retry for a stable
+document, context, and completion position. Further loading responses do not
+schedule polling; a host-provided catalog invalidation resumes discovery.

src/vnext/__tests__/session.test.ts

@@ -1463,6 +1463,64 @@ describe("column completion session integration", () => {
     }
   });
 
+  it("bounds provider-declared column loading to one automatic retry", async () => {
+    vi.useFakeTimers();
+    try {
+      let calls = 0;
+      const service = serviceWithColumns(async (request) => {
+        calls += 1;
+        return {
+          epoch: { generation: 1, token: "epoch-1" },
+          relations: request.relations.map((relation) => ({
+            requestKey: relation.requestKey,
+            status: "loading",
+          })),
+        };
+      });
+      const text = "SELECT u. FROM users u";
+      const session = service.openDocument({
+        context: {
+          catalog: { scope: "connection:columns-loading" },
+          dialect: "duckdb",
+          engine: "local",
+        },
+        text,
+      });
+      const events: SqlSessionChangeEvent[] = [];
+      session.onDidChange((event) => events.push(event));
+      const result = await session.complete({
+        position: "SELECT u.".length,
+        trigger: { kind: "invoked" },
+      });
+      if (result.status !== "ready" || result.refreshToken === null) {
+        throw new Error("Expected retained column loading");
+      }
+
+      await vi.advanceTimersByTimeAsync(100);
+      expect(events).toMatchObject([{
+        reason: "catalog-availability",
+        refreshToken: result.refreshToken,
+      }]);
+      const retry = await session.complete({
+        position: "SELECT u.".length,
+        trigger: { kind: "invoked" },
+      });
+      expect(retry).toMatchObject({
+        refreshToken: null,
+        sources: [{
+          feature: "column-catalog",
+          outcome: "loading",
+        }],
+      });
+      await vi.advanceTimersByTimeAsync(500);
+      expect(calls).toBe(2);
+      expect(events).toHaveLength(1);
+      service.dispose();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("emits readiness when a timed-out column batch settles", async () => {
     vi.useFakeTimers();
     try {
@@ -1812,10 +1870,14 @@ describe("namespace completion session integration", () => {
   it("polls a provider-declared loading namespace with token correlation", async () => {
     vi.useFakeTimers();
     try {
-      const service = serviceWithNamespaces(async () => ({
-        epoch: { generation: 1, token: "epoch-1" },
-        status: "loading",
-      }));
+      let calls = 0;
+      const service = serviceWithNamespaces(async () => {
+        calls += 1;
+        return {
+          epoch: { generation: 1, token: "epoch-1" },
+          status: "loading",
+        };
+      });
       const text = "SELECT * FROM ma";
       const session = service.openDocument({
         context: {
@@ -1846,6 +1908,24 @@ describe("namespace completion session integration", () => {
         reason: "catalog-availability",
         refreshToken: result.refreshToken,
       }]);
+
+      const retry = await session.complete({
+        position: text.length,
+        trigger: { kind: "invoked" },
+      });
+      expect(retry).toMatchObject({
+        refreshToken: null,
+        sources: [
+          { feature: "relation-catalog" },
+          {
+            feature: "namespace-catalog",
+            outcome: "loading",
+          },
+        ],
+      });
+      await vi.advanceTimersByTimeAsync(500);
+      expect(calls).toBe(2);
+      expect(events).toHaveLength(1);
       service.dispose();
     } finally {
       vi.useRealTimers();
@@ -1987,6 +2067,97 @@ describe("namespace completion session integration", () => {
     });
     service.dispose();
   });
+
+  it("manually invalidates auxiliary-only catalog authority", async () => {
+    let generation = 1;
+    let columnCalls = 0;
+    let namespaceCalls = 0;
+    const service = createSqlLanguageService<TestContext>({
+      columns: {
+        id: "columns",
+        loadColumns: async (request) => {
+          columnCalls += 1;
+          return {
+            epoch: { generation, token: `epoch-${generation}` },
+            relations: request.relations.map((relation) => ({
+              columns: [],
+              coverage: "complete",
+              relationEntityId: relation.requestKey,
+              requestKey: relation.requestKey,
+              status: "ready",
+            })),
+          };
+        },
+      },
+      dialects: [duckdb],
+      namespaces: {
+        id: "namespaces",
+        search: async () => {
+          namespaceCalls += 1;
+          return {
+            containers: [],
+            coverage: "complete",
+            epoch: { generation, token: `epoch-${generation}` },
+            status: "ready",
+          };
+        },
+      },
+    });
+    const columns = service.openDocument({
+      context: {
+        catalog: { scope: "connection:manual-invalidate" },
+        dialect: "duckdb",
+        engine: "local",
+      },
+      text: "SELECT u. FROM users u",
+    });
+    const namespaces = service.openDocument({
+      context: {
+        catalog: { scope: "connection:manual-invalidate" },
+        dialect: "duckdb",
+        engine: "local",
+      },
+      text: "SELECT * FROM ma",
+    });
+    const completeColumns = () =>
+      columns.complete({
+        position: "SELECT u.".length,
+        trigger: { kind: "invoked" },
+      });
+    const completeNamespaces = () =>
+      namespaces.complete({
+        position: "SELECT * FROM ma".length,
+        trigger: { kind: "invoked" },
+      });
+
+    await completeColumns();
+    await completeNamespaces();
+    await completeColumns();
+    await completeNamespaces();
+    expect({ columnCalls, namespaceCalls }).toEqual({
+      columnCalls: 1,
+      namespaceCalls: 1,
+    });
+
+    generation = 2;
+    const columnRevision = columns.invalidateCatalog();
+    const namespaceRevision = namespaces.invalidateCatalog();
+    expect(columns.revision).toBe(columnRevision);
+    expect(namespaces.revision).toBe(namespaceRevision);
+    await completeColumns();
+    await completeNamespaces();
+    expect({ columnCalls, namespaceCalls }).toEqual({
+      columnCalls: 2,
+      namespaceCalls: 2,
+    });
+
+    columns.dispose();
+    expect(() => columns.invalidateCatalog()).toThrow(
+      "SQL document session is disposed",
+    );
+    namespaces.dispose();
+    service.dispose();
+  });
 });
 
 describe("statement-index session cache", () => {

src/vnext/codemirror/__tests__/sql-editor.test.ts

@@ -161,6 +161,10 @@ function fakeService(
           disposed = true;
           sessionDisposalCount += 1;
         },
+        invalidateCatalog: () => {
+          revision = createSqlRevisionToken();
+          return revision;
+        },
         isCurrent: (candidate) => !disposed && candidate === revision,
         onDidChange: (nextListener) => {
           listener = nextListener;