fix(vnext): close final completion review gaps

Author: Light2Dark

docs/vnext/marimo-sql-migration.md

@@ -38,8 +38,9 @@ reproduce
 The same shared service configures one `SqlColumnCatalogProvider`. Each
 `loadColumns` call forwards the complete relation request array to one
 DataTable metadata batch operation. It does not fetch once per relation.
-Relation IDs are the stable IDs emitted by the relation provider. Column IDs
-are stable within that relation and connection incarnation.
+The column authority resolves each canonical relation path within the same
+scope and search paths as relation completion. Column IDs and returned relation
+IDs are stable within that connection incarnation.
 
 Each column supplies a canonical identifier and provider-rendered
 `insertText`; these are intentionally separate so quoted or dialect-sensitive

src/vnext/__tests__/column-catalog-batch-coordinator.test.ts

@@ -38,8 +38,7 @@ function ready(
         ordinal: 0,
       }],
       coverage: "complete",
-      relationEntityId:
-        relation.relationEntityId ?? `relation-${relation.requestKey}`,
+      relationEntityId: `relation-${relation.requestKey}`,
       requestKey: relation.requestKey,
       status: "ready",
     })),

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

@@ -22,7 +22,6 @@ function request() {
       { path, requestKey: "users" },
       {
         path: [{ quoted: false, value: "events" }],
-        relationEntityId: "relation-events",
         requestKey: "events",
       },
     ],
@@ -162,7 +161,7 @@ describe("column catalog batch request boundary", () => {
       expectedEpoch: epoch,
       relations: [
         { path, requestKey: "z" },
-        { path, relationEntityId: "stable-a", requestKey: "a" },
+        { path, requestKey: "a" },
       ],
       scope: "scope",
       searchPaths: [[{ quoted: true, value: "Main" }]],
@@ -171,7 +170,7 @@ describe("column catalog batch request boundary", () => {
       status: "accepted",
       value: {
         relations: [
-          { relationEntityId: "stable-a", requestKey: "a" },
+          { requestKey: "a" },
           { requestKey: "z" },
         ],
       },
@@ -476,22 +475,6 @@ describe("column catalog response boundary", () => {
         ],
       },
     },
-    {
-      name: "conflicting known entity",
-      value: {
-        epoch,
-        relations: [
-          readyResponse().relations[0],
-          {
-            columns: [],
-            coverage: "complete",
-            relationEntityId: "wrong-events-id",
-            requestKey: "events",
-            status: "ready",
-          },
-        ],
-      },
-    },
     {
       name: "conflicting duplicate column",
       value: {

src/vnext/__tests__/column-completion.test.ts

@@ -200,7 +200,18 @@ describe("column completion", () => {
       dialect: POSTGRESQL_SQL_RELATION_DIALECT,
       outcome: usable([
         {
-          columns: [column("id", "users", 0)],
+          columns: [
+            column("id", "users", 0),
+            Object.freeze({
+              ...column("id", "users", 1),
+              columnEntityId: "users:id-alternate",
+              insertText: "id_alternate",
+              provenance: Object.freeze({
+                ...column("id", "users", 1).provenance,
+                columnEntityId: "users:id-alternate",
+              }),
+            }),
+          ],
           coverage: "partial",
           relationEntityId: "users",
           requestKey: "binding:0",
@@ -390,6 +401,11 @@ describe("column completion", () => {
     expect(result).toMatchObject({
       sources: [{
         coverage: "partial",
+        failures: [{
+          code: "unavailable",
+          requestKey: "binding:1",
+          retry: "next-request",
+        }],
         outcome: "ready",
       }],
       value: {
@@ -415,6 +431,81 @@ describe("column completion", () => {
         providerId: "columns",
         site: current,
       })?.sources[0],
-    ).toMatchObject({ outcome: "failed" });
+    ).toMatchObject({
+      failures: [{
+        code: "unavailable",
+        requestKey: "binding:0",
+        retry: "next-request",
+      }],
+      outcome: "failed",
+    });
+  });
+
+  it("uses deterministic code-unit ordering", () => {
+    const current = site();
+    const prepared = prepareSqlColumnCatalogRelations(
+      current,
+      POSTGRESQL_SQL_RELATION_DIALECT,
+    );
+    const result = composeSqlColumnCompletion({
+      dialect: POSTGRESQL_SQL_RELATION_DIALECT,
+      outcome: usable([{
+        columns: [
+          column("ä_value", "users", 0),
+          column("z_value", "users", 1),
+        ],
+        coverage: "complete",
+        relationEntityId: "users",
+        requestKey: "binding:0",
+        status: "ready",
+      }]),
+      prepared,
+      providerId: "columns",
+      site: current,
+    });
+
+    expect(result?.value.items.map((item) => item.label)).toEqual([
+      "z_value",
+      "ä_value",
+    ]);
+  });
+
+  it("uses relation detail to order columns with equal labels", () => {
+    const current = site();
+    const prepared = prepareSqlColumnCatalogRelations(
+      current,
+      POSTGRESQL_SQL_RELATION_DIALECT,
+    );
+    const result = composeSqlColumnCompletion({
+      dialect: POSTGRESQL_SQL_RELATION_DIALECT,
+      outcome: usable([
+        {
+          columns: [column("id", "users", 0)],
+          coverage: "complete",
+          relationEntityId: "users",
+          requestKey: "binding:0",
+          status: "ready",
+        },
+        {
+          columns: [column("id", "orders", 0)],
+          coverage: "complete",
+          relationEntityId: "orders",
+          requestKey: "binding:1",
+          status: "ready",
+        },
+      ]),
+      prepared,
+      providerId: "columns",
+      site: current,
+    });
+
+    expect(result?.value.items.map((item) => item.detail)).toEqual([
+      "VARCHAR — o",
+      "VARCHAR — u",
+    ]);
+    expect(result?.value.items.map((item) => item.edit.insert)).toEqual([
+      "id",
+      "id",
+    ]);
   });
 });

src/vnext/__tests__/column-query-site.test.ts

@@ -111,6 +111,31 @@ describe("recognizeSqlColumnQuerySite", () => {
     );
   });
 
+  it("keeps set-operation arms and JOIN visibility isolated", () => {
+    const firstArm = ready(
+      analyze("SELECT | FROM users UNION SELECT x FROM secrets"),
+    );
+    expect(firstArm.relations.map((relation) =>
+      relation.path.at(-1)?.value
+    )).toEqual(["users"]);
+
+    const secondArm = ready(
+      analyze("SELECT x FROM users UNION SELECT | FROM secrets"),
+    );
+    expect(secondArm.relations.map((relation) =>
+      relation.path.at(-1)?.value
+    )).toEqual(["secrets"]);
+
+    const joinCondition = ready(
+      analyze(
+        "SELECT * FROM users u JOIN orders o ON o.user_id = u.| JOIN payments p ON true",
+      ),
+    );
+    expect(joinCondition.relations.map((relation) =>
+      relation.alias?.value
+    )).toEqual(["u", "o"]);
+  });
+
   it("supports BigQuery quoted multipart bindings", () => {
     const result = ready(
       analyze("SELECT t.| FROM `project.dataset.table` AS t", {

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

@@ -513,7 +513,11 @@ describe("namespace completion composer", () => {
         status: "usable",
       },
     })).toMatchObject({
-      source: { outcome: "failed" },
+      source: {
+        code: "unknown",
+        outcome: "failed",
+        retry: "never",
+      },
       value: { issues: ["namespace-catalog-failed"] },
     });
     expect(composeSqlNamespaceCompletion({