docs: verify structured semantic contracts

This commit is contained in:
2026-08-08 21:14:17 +02:00
parent b84d4db946
commit bed43c747e
6 changed files with 219 additions and 46 deletions
+15
View File
@@ -5,6 +5,15 @@ The application image is read-only, secrets are mounted read-only, and sessions
Git-validated snapshots. Expose the application only behind an authenticated same-origin reverse
proxy; never publish the core port directly.
## Architecture ownership contract
| Component | Ownership | Operator contract |
| --- | --- | --- |
| DWH | External | Approved installation/server endpoint; not part of the private semantic Compose stack. |
| LLM | External | Approved installation/server endpoint or provider policy outside the semantic stack. |
| Qdrant | Internal | Mandatory private Compose semantic service; persistent `qdrant-data` volume. |
| Ollama embedding | Internal | Mandatory private Compose semantic service for `qwen3-embedding:0.6b`. |
## Service account, storage, and firewall
Create a dedicated host service account and an operator root such as `/srv/thothii`. The core
@@ -230,6 +239,12 @@ Schema-v3 is the only operational descriptor contract. Schema-v1/v2 descriptors
`migration_required` until an explicit reviewed migration writes version 3. One workspace owns one Qdrant collection; schema, Evidence, and Memory records share it and stay separated by payload
`kind`.
## Semantic index ownership contract
| Scope | Ownership rule | Isolation rule |
| --- | --- | --- |
| Workspace semantic index | Each workspace reserves a single Qdrant collection. | Schema, Evidence, and Memory share that one collection and stay separated by payload `kind`. |
After valid bootstrap, Git outage retains the active snapshot with `degraded: true`. Repair
egress/DNS/CA/credentials, pull, and confirm healthy status. Roll back a bad descriptor through a
reviewed Git revert/release branch, advance the remote through normal policy, pull it, and confirm