Define system architecture and component boundaries #44

Merged

lost-rob0t merged 8 commits from agent/issue-3-architecture into main

2026-07-18 01:43:12 +00:00

lost-rob0t commented

2026-07-18 01:40:35 +00:00

(Migrated from github.com)

What changed

Added docs/architecture.md as the authoritative v0.1 component and data-flow specification.
Defined a single local daemon with supervised actor-style components over bounded AnyIO memory streams.
Made LifecycleActor the sole authority for capture state and generation changes.
Added a type-state pipeline from CaptureIntent through EncryptedEnvelope, with storage and remote-provider interfaces structurally unable to accept raw capture types.
Added component, supervision, capture, stop/cancellation, denied-context, and explicit-query Mermaid diagrams.
Defined commit-time generation validation as the final stale-work barrier.
Specified actor responsibilities, ports, failure classes, mailbox/backpressure policy, configuration snapshots, observability schemas, test seams, source layout, and implementation dependency order.
Selected a minimal SQLite routing catalog plus opaque encrypted blob files and encrypted coarse-time-partitioned vector shards.
Defined local/remote provider routing as policy separate from provider strategy, with an explicit central egress gate.
Added five accepted ADRs covering runtime, concurrency, storage, encryption, and extension boundaries.
Added an ADR index and linked the architecture documents from README.md.

Core decisions

Runtime: Python 3.13+, uv, AnyIO, Pydantic, Typer, pytest/Hypothesis, Ruff, Pyright, and Nix.
Concurrency: supervised actor-style components with bounded in-memory mailboxes; no RabbitMQ, Kafka, or persistent job broker.
Lifecycle: one actor owns state and capture generations; cancellation is backed by a final storage commit check.
Storage: SQLite contains only minimized routing/transaction metadata; all content, exact timestamps, summaries, embeddings, and citations remain in authenticated-encrypted blobs.
Encryption: random per-artifact DEKs with XChaCha20-Poly1305; configurable key providers; GPG is explicit and never a silent fallback.
Extensions: reviewed built-in strategy registry with narrow capabilities; no arbitrary module import or shell-command plugins in v0.1.
Models: provider mechanics are separate from privacy routing; remote access requires an AuthorizedEgressPayload created by the egress gate.
Portability: Xorg implements generic capture/session ports so Wayland portals can be added later without changing the privacy pipeline.

Why

Issue #3 must turn the requirements and threat model into an implementable structure before feature code starts. The architecture makes the hard-off switch, stale-work rejection, redaction ordering, encrypted-only persistence, remote-egress control, and bounded execution explicit component contracts rather than conventions developers could accidentally bypass.

Security impact

Raw pixels, OCR, and metadata remain memory-only.
Storage accepts EncryptedEnvelope only.
Remote adapters receive only AuthorizedEgressPayload plus a restricted network capability.
Policy, redaction, encryption, lifecycle, and generation uncertainty fail closed.
Daemon restart always returns to off.
Actor/mailbox overload cannot create an unbounded plaintext backlog.
Third-party dynamic plugins and generic script execution are excluded from v0.1.
Embeddings are treated as content-bearing and stored in encrypted shards rather than a plaintext vector database.

TDD and validation

This PR is architecture/specification work and introduces no production runtime code.
Confirmed the branch is based on merged PR #43 and is eight commits ahead of main with no unrelated changes.
Confirmed every required component has a narrow responsibility and explicit port or message boundary.
Confirmed the architecture documents the complete lifecycle from pixels in memory through redaction, encryption, persistence, retrieval, and deletion.
Confirmed requirement and threat-boundary traceability for lifecycle, policy, storage, encryption, IPC, providers, observability, provenance, and deletion.
Issue #4 must establish the executable test harness before implementation; the architecture specifies contract, failure-injection, security, and non-zero propagation test seams.

Closes #3

## What changed - Added `docs/architecture.md` as the authoritative v0.1 component and data-flow specification. - Defined a single local daemon with supervised actor-style components over bounded AnyIO memory streams. - Made `LifecycleActor` the sole authority for capture state and generation changes. - Added a type-state pipeline from `CaptureIntent` through `EncryptedEnvelope`, with storage and remote-provider interfaces structurally unable to accept raw capture types. - Added component, supervision, capture, stop/cancellation, denied-context, and explicit-query Mermaid diagrams. - Defined commit-time generation validation as the final stale-work barrier. - Specified actor responsibilities, ports, failure classes, mailbox/backpressure policy, configuration snapshots, observability schemas, test seams, source layout, and implementation dependency order. - Selected a minimal SQLite routing catalog plus opaque encrypted blob files and encrypted coarse-time-partitioned vector shards. - Defined local/remote provider routing as policy separate from provider strategy, with an explicit central egress gate. - Added five accepted ADRs covering runtime, concurrency, storage, encryption, and extension boundaries. - Added an ADR index and linked the architecture documents from `README.md`. ## Core decisions 1. **Runtime:** Python 3.13+, `uv`, AnyIO, Pydantic, Typer, pytest/Hypothesis, Ruff, Pyright, and Nix. 2. **Concurrency:** supervised actor-style components with bounded in-memory mailboxes; no RabbitMQ, Kafka, or persistent job broker. 3. **Lifecycle:** one actor owns state and capture generations; cancellation is backed by a final storage commit check. 4. **Storage:** SQLite contains only minimized routing/transaction metadata; all content, exact timestamps, summaries, embeddings, and citations remain in authenticated-encrypted blobs. 5. **Encryption:** random per-artifact DEKs with XChaCha20-Poly1305; configurable key providers; GPG is explicit and never a silent fallback. 6. **Extensions:** reviewed built-in strategy registry with narrow capabilities; no arbitrary module import or shell-command plugins in v0.1. 7. **Models:** provider mechanics are separate from privacy routing; remote access requires an `AuthorizedEgressPayload` created by the egress gate. 8. **Portability:** Xorg implements generic capture/session ports so Wayland portals can be added later without changing the privacy pipeline. ## Why Issue #3 must turn the requirements and threat model into an implementable structure before feature code starts. The architecture makes the hard-off switch, stale-work rejection, redaction ordering, encrypted-only persistence, remote-egress control, and bounded execution explicit component contracts rather than conventions developers could accidentally bypass. ## Security impact - Raw pixels, OCR, and metadata remain memory-only. - Storage accepts `EncryptedEnvelope` only. - Remote adapters receive only `AuthorizedEgressPayload` plus a restricted network capability. - Policy, redaction, encryption, lifecycle, and generation uncertainty fail closed. - Daemon restart always returns to `off`. - Actor/mailbox overload cannot create an unbounded plaintext backlog. - Third-party dynamic plugins and generic script execution are excluded from v0.1. - Embeddings are treated as content-bearing and stored in encrypted shards rather than a plaintext vector database. ## TDD and validation - This PR is architecture/specification work and introduces no production runtime code. - Confirmed the branch is based on merged PR #43 and is eight commits ahead of `main` with no unrelated changes. - Confirmed every required component has a narrow responsibility and explicit port or message boundary. - Confirmed the architecture documents the complete lifecycle from pixels in memory through redaction, encryption, persistence, retrieval, and deletion. - Confirmed requirement and threat-boundary traceability for lifecycle, policy, storage, encryption, IPC, providers, observability, provenance, and deletion. - Issue #4 must establish the executable test harness before implementation; the architecture specifies contract, failure-injection, security, and non-zero propagation test seams. Closes #3