fix: gate workspace diagnostic migration

This commit is contained in:
2026-08-03 23:30:15 +02:00
parent c5685f4962
commit 450d7ab07f
14 changed files with 430 additions and 145 deletions
@@ -114,7 +114,7 @@ The initial canonical shape is:
```yaml
workspace:
schema_version: 1
schema_version: 2
id: psd-clinical
name: Policlinico San Donato
description: Clinical data warehouse workspace
@@ -132,6 +132,8 @@ dwh:
semantic_index:
vector_store:
engine: pgvector
database: postgres
schema: vectors
collection: clinical_documents
dimensions: 768
distance: cosine
@@ -153,7 +155,20 @@ llm_policy:
The exact machine schema is maintained by `WorkspaceSchema` and versioned with explicit migrations. Unknown keys are rejected by default so misspellings do not silently change runtime behavior.
### 6.1 Semantic-index invariant
### 6.1 Version migration and operational state
Schema version 2 makes `semantic_index.vector_store.database` and `.schema` mandatory. They
identify the vector service independently of the DWH, even when both happen to use the same
PostgreSQL instance.
Version 1 descriptors remain readable and listable so operators can discover legacy Git content.
They are marked `migration_required` and may not generate installation bindings, runtime
configuration, diagnostics, or publication artifacts. Migration is an explicit UI/transformer
action that supplies the vector database/schema; it must never infer either value from the DWH.
The resulting descriptor is written as schema version 2 and then passes normal operational
validation.
### 6.2 Semantic-index invariant
`semantic_index` is atomic. The vector collection, vector dimensions, distance metric, embedding provider, embedding model, and embedding dimensions describe one index contract.