docs: verify structured semantic contracts
This commit is contained in:
@@ -10,6 +10,15 @@ bindings, credentials, and session data are local, while internal Qdrant/Ollama
|
||||
Compose stack. Never put credentials in workspace YAML, Git, browser drafts, diagnostics, or
|
||||
`.env.example`.
|
||||
|
||||
## Architecture ownership contract
|
||||
|
||||
| Component | Ownership | Operator contract |
|
||||
| --- | --- | --- |
|
||||
| DWH | External | Installation-local endpoint/binding; never bundled into the Compose semantic stack. |
|
||||
| LLM | External | Installation-local endpoint/policy choice outside the internal semantic services. |
|
||||
| Qdrant | Internal | Mandatory private Compose semantic service; persistent `qdrant-data` volume. |
|
||||
| Ollama embedding | Internal | Mandatory private Compose semantic service for `qwen3-embedding:0.6b`. |
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- macOS: Docker Desktop, Git, and sufficient volume disk space. Git Credential Manager is useful
|
||||
@@ -179,6 +188,12 @@ Schema-v3 is the only operational descriptor format. Schema-v1/v2 descriptors re
|
||||
`migration_required` until an explicit reviewed migration writes schema version 3. One workspace owns one Qdrant collection; schema, Evidence, and Memory records share that collection and remain
|
||||
isolated 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 stay in that one collection and remain isolated by payload `kind`. |
|
||||
|
||||
To migrate an existing legacy descriptor, create/clone an empty private remote, set the absolute
|
||||
`THT_SOURCE_ROOT`, transform with absolute paths, review the schema-v1 result, explicitly produce
|
||||
the reviewed schema-v3 contract, then commit/push. The transformer never imports `${ENV}` values
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user