AD1–AD13 — Original architecture¶
The original cross-cutting architectural decisions (AD). They are retained as
historical design context; the current product contract lives in
../overview.md and the topic documentation.
These records explain why choices were made and may describe superseded behavior. For the supported interface, follow the current-state page linked above.
This is the one file that holds more than a single decision, and deliberately: the thirteen ADs never had individual bodies — they are one historical table, written as one, every row already superseded by the current documentation. Splitting them into thirteen files each holding one table row would add navigation without adding anything to read.
| ID | Decision | Details in |
|---|---|---|
| AD1 | Two profiles: local Core (v1, single-user, stdio) + Server (opt-in add-on, multi-KB, HTTP+OAuth) | Original design; superseded by the unified runtime described in overview.md |
| AD2 | General purpose + multi-KB; no assumed domain; separate git repos per KB | overview.md, data-plane.md |
| AD3 | Authentication via token/OAuth; sync via git; per-KB scopes in the token; access is non-enforced metadata until the scope is active |
transport-auth.md, loop.md |
| AD4 | Server CLI-only (administrative only); TUI only in the multi-provider configurator | interoperability.md, deployment.md |
| AD5 | Canonical transport = Streamable HTTP + OAuth 2.1; stdio for local; mcp-remote for OpenCode; stateless-friendly |
transport-auth.md |
| AD6 | Single-writer on a working branch (never on main); Core → fast-forward on light gate; Server → PR with rebase+gate; if_match anchored to main at PR opening |
concurrency.md |
| AD7 | Optimistic concurrency: per-KB mutex + git rebase/retry; if_match on normalized per-section content-hash; per-dossier lock with lease/TTL |
concurrency.md |
| AD8 | needs-resolution unblocked via conflict_resolve (gated tool/CLI, no deadlock); writes rejected with Retry-After |
concurrency.md |
| AD9 | Hybrid contradictions: Contradiction node for HARD (gate on resolution_status: open), edge for SOFT; bi-temporal supersession with mandatory reason |
control-plane.md, data-plane.md |
| AD10 | Ingest via concept_write with light gate in Core, PR in Server; OKF validation and absence of PII are blocking |
loop.md, data-plane.md |
| AD11 | Semantic search active from the start in the Server profile (Ollama + in-memory vector store); keyword always available | control-plane.md |
| AD12 | User-defined types; Service and Contradiction have a formal schema verified by validate() in strict mode |
data-plane.md |
| AD13 | Skills/services/secrets in the KB: signed+pinned SKILL.md, type:Service, SOPS with mandatory break-glass |
skills-services-secrets.md |