feat: define workspace diagnostic contracts

backend/test/workspaces-contracts.test.ts

@@ -1,6 +1,8 @@
 import { expect, test } from "vitest";
+import { parse } from "yaml";
 import { buildInstallationContract, renderWorkspaceDocs } from "../src/workspaces/contracts.js";
 import { type CanonicalWorkspace, parseWorkspaceYaml } from "../src/workspaces/schema.js";
+import { renderRuntimeConfig, type RuntimeBindings } from "../src/workspaces/runtime-renderer.js";
 
 const validWorkspace = parseWorkspaceYaml(`workspace:
   schema_version: 1
@@ -17,6 +19,8 @@ dwh:
 semantic_index:
   vector_store:
     engine: pgvector
+    database: postgres
+    schema: vectors
     collection: clinical_documents
     dimensions: 768
     distance: cosine
@@ -64,9 +68,108 @@ test("renders English UI headings and workspace-language Italian prose", () => {
 
   expect(docs.markdown).toContain("# Installation requirements");
   expect(docs.markdown).toContain("Configurazione dell'installazione");
+  expect(docs.markdown).not.toContain("## Vector writer");
   expect(docs.envExample).toContain("THT_WS_PSD_CLINICAL_VECTOR_TRANSPORT=");
 });
 
+test("renders the vector store identity and creates writer credentials only when declared", () => {
+  const writerWorkspace = parseWorkspaceYaml(`workspace:
+  schema_version: 1
+  id: psd-clinical
+  name: Policlinico San Donato
+  language: it
+dwh:
+  engine: postgres
+  database: warehouse
+  schema: datawarehouse
+  supported_transports: [postgres_direct]
+semantic_index:
+  vector_store:
+    engine: pgvector
+    database: vector_database
+    schema: vectors
+    collection: clinical_documents
+    dimensions: 768
+    distance: cosine
+    supported_transports: [pgvector_direct]
+  vector_writer: {}
+  embedding:
+    provider: ollama_compatible
+    model: nomic-embed-text-v2-moe
+    dimensions: 768
+diagnostics:
+  dwh_rest:
+    method: POST
+    path: /rpc/ping
+    auth: bearer
+    response:
+      database: database
+      schema: schema
+  vector_rest:
+    metadata:
+      method: GET
+      path: /metadata
+      auth: bearer
+      response:
+        collection: collection
+        dimensions: dimensions
+        distance: distance
+  embedding:
+    method: GET
+    path: /models
+    auth: none
+    response:
+      model: model
+      dimensions: dimensions
+llm_policy:
+  allowed: [zai/glm-5.2]
+`);
+  const bindings: RuntimeBindings = {
+    dwh: {
+      transport: "postgres_direct",
+      missing: [],
+      values: {
+        THT_WS_PSD_CLINICAL_DWH_HOST: "dwh.internal",
+        THT_WS_PSD_CLINICAL_DWH_PORT: "5432",
+        THT_WS_PSD_CLINICAL_DWH_USER: "reader",
+        THT_WS_PSD_CLINICAL_DWH_PASSWORD_FILE: "/run/secrets/dwh",
+      },
+    },
+    vector: {
+      transport: "pgvector_direct",
+      missing: [],
+      values: {
+        THT_WS_PSD_CLINICAL_VECTOR_HOST: "vector.internal",
+        THT_WS_PSD_CLINICAL_VECTOR_PORT: "5432",
+        THT_WS_PSD_CLINICAL_VECTOR_USER: "vector-reader",
+        THT_WS_PSD_CLINICAL_VECTOR_PASSWORD_FILE: "/run/secrets/vector-reader",
+      },
+    },
+    embedding: {
+      transport: "rest_api",
+      missing: [],
+      values: { THT_WS_PSD_CLINICAL_EMBEDDING_BASE_URL: "https://embedding.internal" },
+    },
+  };
+
+  const writerVariables = buildInstallationContract(writerWorkspace).variables
+    .filter((variable) => variable.role === "VECTOR_WRITER");
+
+  expect(writerVariables).toEqual([expect.objectContaining({
+    name: "THT_WS_PSD_CLINICAL_VECTOR_WRITER_API_KEY_FILE",
+    role: "VECTOR_WRITER",
+    secret: true,
+  })]);
+  expect(buildInstallationContract(validWorkspace).variables.some((variable) => (
+    variable.role === "VECTOR_WRITER"
+  ))).toBe(false);
+  expect(parse(renderRuntimeConfig(writerWorkspace, bindings, {
+    sessions: "/data/sessions",
+    artifacts: "/data/artifacts",
+    indexes: "/data/indexes",
+  })).vector_db).toMatchObject({ database: "vector_database", schema: "vectors" });
+});
+
 function withTransports(
   dwhTransport: CanonicalWorkspace["dwh"]["supported_transports"][number],
   vectorTransport: CanonicalWorkspace["semantic_index"]["vector_store"]["supported_transports"][number],