feat: define workspace diagnostic contracts

2026-08-03 23:16:23 +02:00
parent 25a85b972e
commit c5685f4962
11 changed files with 249 additions and 7 deletions
@@ -23,6 +23,8 @@ dwh:
 semantic_index:
  vector_store:
    engine: pgvector
+    database: postgres
+    schema: vectors
    collection: clinical_documents
    dimensions: 768
    distance: cosine
@@ -16,6 +16,8 @@ dwh:
 semantic_index:
  vector_store:
    engine: pgvector
+    database: postgres
+    schema: vectors
    collection: clinical_documents
    dimensions: 768
    distance: cosine
@@ -81,7 +83,8 @@ test("renders a direct PostgreSQL binding to the legacy harness shape", () => {
    },
    vector_db: {
      host: "vector.internal",
-      schema: "datawarehouse",
+      database: "postgres",
+      schema: "vectors",
      password_file: "/run/secrets/vector-password",
      ssl_ca_file: "/run/secrets/vector-ca.pem",
    },
@@ -18,6 +18,8 @@ dwh:
 semantic_index:
  vector_store:
    engine: pgvector
+    database: postgres
+    schema: vectors
    collection: clinical_documents
    dimensions: 768
    distance: cosine
@@ -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],
@@ -21,6 +21,8 @@ dwh:
 semantic_index:
  vector_store:
    engine: pgvector
+    database: postgres
+    schema: vectors
    collection: clinical_documents
    dimensions: 768
    distance: cosine
@@ -20,6 +20,8 @@ dwh:
 semantic_index:
  vector_store:
    engine: pgvector
+    database: postgres
+    schema: vectors
    collection: clinical_documents
    dimensions: 768
    distance: cosine
@@ -20,6 +20,8 @@ dwh:
 semantic_index:
  vector_store:
    engine: pgvector
+    database: postgres
+    schema: vectors
    collection: clinical_documents
    dimensions: 768
    distance: cosine
@@ -68,6 +70,57 @@ test("accepts optional connection ports and timeouts but rejects unsafe values",
    .toThrow(/timeout/i);
 });

+test("requires explicit vector database and schema identities with strict diagnostic declarations", () => {
+  const diagnosticWorkspace = validYaml.replace(
+    "    engine: pgvector\n    database: postgres",
+    "    engine: pgvector\n    database: vector_database",
+  ).replace(
+    "llm_policy:\n",
+    "diagnostics:\n"
+      + "  dwh_rest:\n"
+      + "    method: POST\n"
+      + "    path: /rpc/ping\n"
+      + "    auth: bearer\n"
+      + "    response:\n"
+      + "      database: database\n"
+      + "      schema: schema\n"
+      + "  vector_rest:\n"
+      + "    metadata:\n"
+      + "      method: GET\n"
+      + "      path: /metadata\n"
+      + "      auth: bearer\n"
+      + "      response:\n"
+      + "        collection: collection\n"
+      + "        dimensions: dimensions\n"
+      + "        distance: distance\n"
+      + "    reversible_probe:\n"
+      + "      method: POST\n"
+      + "      path: /rpc/diagnostic_vector_probe\n"
+      + "      auth: bearer\n"
+      + "  embedding:\n"
+      + "    method: GET\n"
+      + "    path: /models\n"
+      + "    auth: none\n"
+      + "    response:\n"
+      + "      model: model\n"
+      + "      dimensions: dimensions\n"
+      + "llm_policy:\n",
+  );
+
+  expect(parseWorkspaceYaml(diagnosticWorkspace).semantic_index.vector_store).toMatchObject({
+    database: "vector_database",
+    schema: "vectors",
+  });
+  expect(() => parseWorkspaceYaml(diagnosticWorkspace.replace("database: vector_database", 'database: " "')))
+    .toThrow(/database/i);
+  expect(() => parseWorkspaceYaml(diagnosticWorkspace.replace("schema: vectors", 'schema: " "')))
+    .toThrow(/schema/i);
+  expect(() => parseWorkspaceYaml(diagnosticWorkspace.replace("method: POST", "method: PATCH")))
+    .toThrow(/method/i);
+  expect(() => parseWorkspaceYaml(diagnosticWorkspace.replace("        distance: distance", "        distance: distance\n        extra: ignored")))
+    .toThrow(/unrecognized key/i);
+});
+
 test("serializes canonical YAML that parses back to the same workspace", () => {
  const workspace = parseWorkspaceYaml(validYaml);
  const serialized = serializeWorkspaceYaml(workspace);