docs(spec): allinea §5.1 workspace YAML al Config reale (decisione B, post Task A2)

La prima stesura usava una struttura 'ideale' (relational/vector_db.collection/ embeddings.provider) che non combaciava col modello Config portato da ChironeWp3. Allineato alla struttura reale (database/rest/vector_rest/vector_write_rest/ vector_db top-level). Aggiunta nota di allineamento + modello delle key D11.
2026-06-26 22:27:05 +02:00
parent 6ba3336775
commit 2e34ba33e0
1 changed files with 24 additions and 57 deletions
@@ -463,68 +463,35 @@ Questa sezione specifica D16. Il requisito: ogni passaggio deve dare al modello

 ### 5.1 Workspace — `harness/workspaces/<name>.yaml`

+> **Nota di allineamento (post-brainstorming):** la prima stesura di questa sezione usava una struttura "ideale" (`relational:`, `vector_db.collection`, `embeddings.provider`) che non corrispondeva al modello `Config` reale portato da ChironeWp3. Durante il Task A2 del piano harness si è scelto (decisione B) di **allineare spec e codice alla struttura reale di `Config`**, perché è uno dei pochi pezzi riusati quasi tal quali e ristrutturarlo avrebbe propagato il cambio a tutti i moduli che lo leggono. La struttura canonica verificata è `harness/workspaces/chirone.example.yaml`; il blocco YAML sotto è un estratto che riflette `nsp/config.py` fedelmente (sezioni `database`/`rest`/`vector_db`/`vector_rest`/`vector_write_rest`/`embeddings`/`evidence`/`execution`, tutte top-level; nessun `relational:` o `vector_db.collection`). Per l'esempio completo fare riferimento al file `chirone.example.yaml`.
+
 ```yaml
-name: chirone
-description: "Datawarehouse Policlinico San Donato"
-
-relational:
-  db_type: postgres          # postgres|mariadb|sqlserver|informix|sqlite
-  transport: rest            # direct|rest (rest=PostgREST, direct=nativo)
-  # --- per transport: direct ---
-  host: ${CHIRONE_DB_HOST}
-  port: 5432
-  database: datawarehouse
-  schema: datawarehouse
-  user: ${CHIRONE_DB_USER}
-  password: ${CHIRONE_DB_PASSWORD}
-  # --- per transport: rest (PostgREST) ---
-  # rest: { base_url: ${CHIRONE_REST_URL}, api_key: ${CHIRONE_REST_KEY}, ssl_ca: ... }
-  # --- eventuale tunnel ssh (pattern thoth_sqldb2) ---
-  # ssh: { enabled: true, host: ..., username: ..., auth: private_key, key_path: ... }
-
-vector_db:
-  collection: chirone_docs   # tabella pgvector target (schema_records|evidence|memory)
-  dim: 768
-  # --- LOADING diretto (server-only, come ChironeWp3 vector_db): ricostruzione distruttiva ---
-  # local:
-  #   host: localhost
-  #   port: 5438
-  #   database: postgres
-  #   schema: vectors
-  # --- LETTURA via REST remota (rpc search_similar, key reader) ---
-  rest:
-    base_url: ${THOTH_VEC_REST_URL}      # es. https://host/vector/v1/
-    api_key: ${THOTH_VEC_API_KEY}        # header X-API-Key, read-only
-    ssl_ca: ${THOTH_SSL_CA}              # opzionale, CA interna
-  # --- SCRITTURA via REST remota (upsert/hash via RPC allowlist, key writer) ---
-  # OPZIONALE: assente o key vuota = scrittura non abilitata (solo lettura).
-  # Abilita nsp memory save-one / vector index-schema su postazione remota.
-  write_rest:
-    base_url: ${THOTH_VEC_REST_URL}      # stessa URL del reader
-    api_key: ${THOTH_VEC_WRITE_API_KEY}  # key SEPARATA, ruolo vector_writer
-    ssl_ca: ${THOTH_SSL_CA}
-
-evidence:
-  source_root: ${EVIDENCE_ROOT}
-  evidence_dir: evidence/chirone
-
+# Estratto — struttura reale del Config (vedi chirone.example.yaml per il completo).
+database:                       # DWH relazionale
+  host: ${THOTH_DB_HOST}
+  transport: rest               # direct | rest
+rest:                           # richiesto se transport=rest
+  base_url: ${THOTH_DWH_REST_URL}
+  api_key: ${THOTH_DWH_API_KEY}     # ruolo dwh_reader
+vector_rest:                    # LETTURA pgvector (rpc search_similar), key reader
+  base_url: ${THOTH_VEC_REST_URL}
+  api_key: ${THOTH_VEC_API_KEY}
+vector_write_rest:              # SCRITTURA pgvector (upsert/hash), key writer SEPARATA, opzionale
+  base_url: ${THOTH_VEC_REST_URL}
+  api_key: ${THOTH_VEC_WRITE_API_KEY}
+vector_db:                      # LOADING diretto pgvector, server-only
+  host: ${THOTH_VEC_HOST}
 embeddings:
-  provider: ollama           # interfaccia embed(texts)→vectors; 1 impl nell'MVP
-  base_url: ${OLLAMA_URL}    # http://localhost:11434
-  model: nomic-embed-text-v2-moe
-  dim: 768
-  batch_size: 64
-
-execution:                   # fonte di verità read-only (D7 rischio)
+  base_url: ${THOTH_OLLAMA_URL}
+evidence:
+  source_root: ${THOTH_DOCS_ROOT}
+execution:                      # fonte verità read-only (D7)
  allow: [cte_test, explain, preview, aggregate, export]
-  max_preview_rows: 10
-  max_export_rows: 10000
-  statement_timeout_ms: 5000
-  # esempio: funzioni che permettono side-effect o escalation privilegi
-  forbidden_functions: [set_config, dblink, dblink_exec, lo_import]
 ```

-Il modulo `workspace.py` carica + valida + espande `${VAR}` dal `.env`. Una sola fonte di verità per `execution.allow`, condivisa tra `nsp` (validazione durante il workflow) e backend (SQL finale read-only).
+Il modulo `workspace.py` (confine D3) carica + valida + espande `${VAR}` dal `.env`, delegando a `load_config` (portato da ChironeWp3). Una sola fonte di verità per `execution.allow`, condivisa tra `nsp` (validazione durante il workflow) e backend (SQL finale read-only).
+
+**Modello delle key (D11, vedi §5.4):** il `Config` ha tre sezioni `RestConfig` indipendenti con key distinte — `rest.api_key` (DWH reader), `vector_rest.api_key` (pgvector reader), `vector_write_rest.api_key` (pgvector writer). Nel deployment Chirone reale la key del DWH reader e quella del pgvector reader **condividono lo stesso valore** (key unica validata da Nginx), ma restano campi separati nella config per chiarezza e flessibilità.

 ### 5.2 Session — `harness/sessions/<id>/`