fix: harden workspace schema contracts

backend/src/workspaces/contracts.ts

@@ -1,3 +1,4 @@
+import { validateCanonicalWorkspace } from "./schema.js";
 import type { CanonicalWorkspace, DwhTransport, VectorTransport } from "./schema.js";
 
 export type InstallationRole = "DWH" | "VECTOR" | "EMBEDDING";
@@ -34,15 +35,24 @@ export interface InstallationContract {
   variables: InstallationVariable[];
 }
 
-const CONNECTOR_SUFFIXES: readonly InstallationSuffix[] = [
-  "TRANSPORT",
+const DIRECT_SUFFIXES: readonly InstallationSuffix[] = [
   "HOST",
   "PORT",
-  "BASE_URL",
   "USER",
   "PASSWORD_FILE",
+  "TLS_CA_FILE",
+];
+
+const REST_SUFFIXES: readonly InstallationSuffix[] = [
+  "BASE_URL",
   "API_KEY_FILE",
   "TLS_CA_FILE",
+];
+
+const SSH_SUFFIXES: readonly InstallationSuffix[] = [
+  "USER",
+  "PASSWORD_FILE",
+  "TLS_CA_FILE",
   "SSH_HOST",
   "SSH_PORT",
   "SSH_USER",
@@ -82,21 +92,46 @@ function connectorVariables(
   role: "DWH" | "VECTOR",
   transports: readonly ConnectorTransport[],
 ): InstallationVariable[] {
-  return CONNECTOR_SUFFIXES.map((suffix) => createVariable(namespace, role, suffix, transports));
+  const suffixTransports = new Map<InstallationSuffix, ConnectorTransport[]>();
+  const add = (suffixes: readonly InstallationSuffix[], transport: ConnectorTransport) => {
+    for (const suffix of suffixes) {
+      const applicable = suffixTransports.get(suffix) ?? [];
+      applicable.push(transport);
+      suffixTransports.set(suffix, applicable);
+    }
+  };
+
+  for (const transport of transports) {
+    if (transport === "postgres_direct" || transport === "pgvector_direct") {
+      add(DIRECT_SUFFIXES, transport);
+    } else if (transport === "rest_api") {
+      add(REST_SUFFIXES, transport);
+    } else {
+      add(SSH_SUFFIXES, transport);
+    }
+  }
+
+  return [
+    createVariable(namespace, role, "TRANSPORT", transports),
+    ...[...suffixTransports.entries()].map(([suffix, applicable]) => (
+      createVariable(namespace, role, suffix, applicable)
+    )),
+  ];
 }
 
 export function buildInstallationContract(workspace: CanonicalWorkspace): InstallationContract {
-  const namespace = namespaceFor(workspace);
+  const canonical = validateCanonicalWorkspace(workspace);
+  const namespace = namespaceFor(canonical);
 
   return {
-    workspaceId: workspace.workspace.id,
+    workspaceId: canonical.workspace.id,
     namespace,
     variables: [
-      ...connectorVariables(namespace, "DWH", workspace.dwh.supported_transports),
+      ...connectorVariables(namespace, "DWH", canonical.dwh.supported_transports),
       ...connectorVariables(
         namespace,
         "VECTOR",
-        workspace.semantic_index.vector_store.supported_transports,
+        canonical.semantic_index.vector_store.supported_transports,
       ),
       ...EMBEDDING_SUFFIXES.map((suffix) => createVariable(namespace, "EMBEDDING", suffix)),
     ],
@@ -110,7 +145,8 @@ function localizedIntroduction(workspace: CanonicalWorkspace): string {
 }
 
 export function renderWorkspaceDocs(workspace: CanonicalWorkspace): { envExample: string; markdown: string } {
-  const contract = buildInstallationContract(workspace);
+  const canonical = validateCanonicalWorkspace(workspace);
+  const contract = buildInstallationContract(canonical);
   const variablesByRole = new Map<InstallationRole, InstallationVariable[]>();
   for (const variable of contract.variables) {
     const variables = variablesByRole.get(variable.role) ?? [];
@@ -119,7 +155,7 @@ export function renderWorkspaceDocs(workspace: CanonicalWorkspace): { envExample
   }
 
   const envExample = [
-    `# Generated installation bindings for ${workspace.workspace.id}`,
+    `# Generated installation bindings for ${canonical.workspace.id}`,
     "# Provide secret file paths only; never paste secret values here.",
     ...contract.variables.map((variable) => `${variable.name}=`),
     "",
@@ -128,16 +164,18 @@ export function renderWorkspaceDocs(workspace: CanonicalWorkspace): { envExample
   const markdown = [
     "# Installation requirements",
     "",
-    `**Workspace:** ${workspace.workspace.name}`,
+    `**Workspace:** ${canonical.workspace.name}`,
     "",
-    localizedIntroduction(workspace),
+    localizedIntroduction(canonical),
     "",
     "Use the following UI fields as installation bindings. Secret fields always contain file paths, never secret values.",
     "",
     ...(["DWH", "VECTOR", "EMBEDDING"] as const).flatMap((role) => [
       `## ${role === "DWH" ? "Data warehouse" : role === "VECTOR" ? "Vector store" : "Embedding service"}`,
       "",
-      ...(variablesByRole.get(role) ?? []).map((variable) => `- \`${variable.name}\``),
+      ...(variablesByRole.get(role) ?? []).map((variable) => (
+        `- \`${variable.name}\`${variable.transports ? ` (for: ${variable.transports.join(", ")})` : ""}`
+      )),
       "",
     ]),
   ].join("\n");