Define typed domain models and strategy interfaces #47

Merged

lost-rob0t merged 48 commits from agent/issue-5-domain-contracts into main

2026-07-18 04:21:56 +00:00

lost-rob0t commented

2026-07-18 03:44:44 +00:00

(Migrated from github.com)

What changed

Added immutable domain models for lifecycle state, capture authorization, raw and redacted frames, OCR, metadata provenance, redaction findings, encrypted record envelopes, model-provider capabilities, routing decisions, retrieval results, citations, and typed messages/events.
Added runtime-checkable backend-neutral protocols for capture, metadata, policy, redaction, OCR, encryption, keys, encrypted storage, embedding, generation, model routing, and deterministic clocks.
Made security-sensitive stage ordering explicit:
- capture backends accept ApprovedCaptureRequest only;
- redaction accepts RawFrame and returns RedactedRecord;
- encryption accepts EncryptionRequest[RedactedRecord];
- storage accepts EncryptedRecordEnvelope only.
Added explicit privacy classifications and provider locations/capabilities.
Required remote routing decisions to include an explicit egress-authorization identifier.
Hid pixels, OCR text, prompts, model output, excerpts, answers, nonces, wrapped keys, and ciphertext from object representations.
Added reusable contract-test suites for capture, metadata, embedding, generation, and storage implementations.
Added docs/domain-contracts.md and linked it from the README.
Added contract suites as required CI steps on both supported Ubuntu runners.

TDD evidence

Observed red result:

python -m pytest tests/unit/domain/test_lifecycle.py -q

Collection failed non-zero with ModuleNotFoundError: No module named 'local_recall.domain' before the domain package existed.

Focused green result:

python -m pytest tests/unit tests/contract -q
34 issue-focused tests passed during the development loop.
Ruff 0.15.22 passed formatting and lint checks.
Pyright 1.1.411 passed with zero errors against the Python 3.14 target.
Bandit and the baseline-driven secret scan passed without security suppressions.

Python 3.14 CI validation

Final workflow run #32 passed:

Ubuntu 22.04: formatting, Ruff lint, ShellCheck, strict Pyright, unit tests, contract tests, and security checks passed.
Ubuntu 24.04: formatting, Ruff lint, ShellCheck, strict Pyright, unit tests, contract tests, and security checks passed.
Independent eight-mode failure propagation passed.

Acceptance criteria

Interfaces contain no backend-specific SDK, transport, desktop, or database assumptions.
Distinct immutable types make invalid capture/redaction/encryption/storage ordering statically visible and runtime validated.
Provider capabilities, locality, privacy classifications, and remote egress authorization are explicit.
Reusable contract suites are exercised against synthetic implementations and run in required CI.
Tests and fixtures use synthetic values only.

Closes #5

## What changed - Added immutable domain models for lifecycle state, capture authorization, raw and redacted frames, OCR, metadata provenance, redaction findings, encrypted record envelopes, model-provider capabilities, routing decisions, retrieval results, citations, and typed messages/events. - Added runtime-checkable backend-neutral protocols for capture, metadata, policy, redaction, OCR, encryption, keys, encrypted storage, embedding, generation, model routing, and deterministic clocks. - Made security-sensitive stage ordering explicit: - capture backends accept `ApprovedCaptureRequest` only; - redaction accepts `RawFrame` and returns `RedactedRecord`; - encryption accepts `EncryptionRequest[RedactedRecord]`; - storage accepts `EncryptedRecordEnvelope` only. - Added explicit privacy classifications and provider locations/capabilities. - Required remote routing decisions to include an explicit egress-authorization identifier. - Hid pixels, OCR text, prompts, model output, excerpts, answers, nonces, wrapped keys, and ciphertext from object representations. - Added reusable contract-test suites for capture, metadata, embedding, generation, and storage implementations. - Added `docs/domain-contracts.md` and linked it from the README. - Added contract suites as required CI steps on both supported Ubuntu runners. ## TDD evidence **Observed red result:** `python -m pytest tests/unit/domain/test_lifecycle.py -q` Collection failed non-zero with `ModuleNotFoundError: No module named 'local_recall.domain'` before the domain package existed. **Focused green result:** - `python -m pytest tests/unit tests/contract -q` - 34 issue-focused tests passed during the development loop. - Ruff 0.15.22 passed formatting and lint checks. - Pyright 1.1.411 passed with zero errors against the Python 3.14 target. - Bandit and the baseline-driven secret scan passed without security suppressions. ## Python 3.14 CI validation Final workflow run #32 passed: - Ubuntu 22.04: formatting, Ruff lint, ShellCheck, strict Pyright, unit tests, contract tests, and security checks passed. - Ubuntu 24.04: formatting, Ruff lint, ShellCheck, strict Pyright, unit tests, contract tests, and security checks passed. - Independent eight-mode failure propagation passed. ## Acceptance criteria - Interfaces contain no backend-specific SDK, transport, desktop, or database assumptions. - Distinct immutable types make invalid capture/redaction/encryption/storage ordering statically visible and runtime validated. - Provider capabilities, locality, privacy classifications, and remote egress authorization are explicit. - Reusable contract suites are exercised against synthetic implementations and run in required CI. - Tests and fixtures use synthetic values only. Closes #5

lost-rob0t (Migrated from github.com) reviewed

2026-07-18 04:21:45 +00:00

lost-rob0t (Migrated from github.com) left a comment

Nice use of the Policy Pattern like i requested.