cayce
90e6cfcc19
Critical 1 (approval forgery): audit_log is now hash-chained (prev_hash/entry_hash, verify_audit_chain); executor approve REQUIRES a BIP-340 signature over sha256(cayce-ops:approve:<id>) when CAYCE_OPS_OPERATOR_PUBKEY is set; deploy/roles.sql ships least-privilege per-daemon DB roles. Critical 2 (threading dead): sends create real OUTBOUND rows (own Message-ID, In-Reply-To -> inbound); inbound message_id never overwritten; maild compose adds the first-contact path; _match_proposal falls back to inbound chains. Critical 3 (duplicate sends): per-message transactions in send path — SMTP failure on message N no longer resurrects 1..N-1; failures audited (send_failed) and the row stays queued. Critical 4 (classifier): negated approvals (cannot accept / not approved / not accepting) classify REJECTION at 0.95 before the bare-keyword rule; LLM prompt braces escaped (.format no longer KeyError into silent fallback). Critical 5 (systemd): every daemon has a run subcommand (maild run = poll+send, publisher run = publish-due, monitor run = build); deploy README documents the separate daily publisher plan timer. Mediums: approved_hash binds drafts/captions to the approved text (edited text refuses to send/publish until re-approved); risk_score renamed match_score (migration 0002) and auto-approve orders HIGHEST relevance first; compose binds postgres to 127.0.0.1; IMAP marks \\Seen only after commit (fetch returns (num, raw), mark post-commit); disabled channels are terminal (ContentStatus.SKIPPED) and publish failures burn a bounded attempt budget before abandonment; make hooks installs the pre-push gate. tests: 12 new — 56 total, all green; ruff 0 findings; gitleaks clean.
98 lines
5.3 KiB
Markdown
98 lines
5.3 KiB
Markdown
# Architectural decisions
|
|
|
|
Each entry: decision, why, and what it costs us. Newest last.
|
|
|
|
## D1 — uv + uv.lock as the lockfile
|
|
`uv` manages the pinned interpreter (3.12) and produces `uv.lock`. CI installs
|
|
with `uv sync --frozen`; nothing runs against unpinned trees.
|
|
*Cost:* contributors need uv (single static binary).
|
|
|
|
## D2 — Tests on SQLite; migrations authoritative for Postgres
|
|
Tests run on file-backed SQLite via `metadata.create_all` (fast, no service
|
|
dependency). The Alembic chain is the production schema path; `make
|
|
migrate-check` (CI job) smoke-runs `alembic upgrade head` on SQLite.
|
|
*Cost:* Postgres-specific features (e.g. JSONB, partial indexes) stay unused —
|
|
the schema uses portable `sa.JSON` instead.
|
|
|
|
## D3 — LLM behind an in-repo provider interface; null by default
|
|
`cayceops.llm.LLMProvider` is the only seam. `null` provider raises — components
|
|
fall back to deterministic rules. `openai-compat` uses stdlib `urllib` against
|
|
any OpenAI-shaped endpoint; no SDK dependency.
|
|
*Cost:* no retries/streaming/tool-calls — acceptable for classification and
|
|
draft drafting. Add providers by implementing `complete()`.
|
|
|
|
## D4 — Nostr client implemented in-repo (coincurve + websockets)
|
|
NIP-01 event build/sign/publish is ~150 auditable lines vs. a black-box SDK.
|
|
Keys accepted as 32-byte hex only. Relays are plain env config; publish is
|
|
fire-and-wait with a timeout; the event id is stored as `post_ref`.
|
|
*Cost:* no NIP-05, no retries across relay pools — fine for kind-1 notes.
|
|
|
|
## D5 — AUTONOMOUS_MODE semantics (the only non-human approval path)
|
|
Default **false**: only human-approved proposals execute, only
|
|
human-approved drafts are sendable/publishable.
|
|
**true** adds exactly one capability: the executor may auto-approve
|
|
`proposed` items whose `kind` is in `CAYCE_OPS_AUTONOMOUS_KINDS`, up to
|
|
`CAYCE_OPS_AUTONOMOUS_DAILY_CAP` per day, recording actor `auto:policy` in the
|
|
audit log. Everything else still requires a human. Auto-approval never touches
|
|
mail drafts or content items.
|
|
*Cost:* two code paths; both audited; the autonomous one is off by default and
|
|
cap-bounded.
|
|
|
|
## D6 — CI workflow files ship now; enforcement gate is `make check` until a runner exists
|
|
`.gitea/workflows/ci.yml` (Gitea Actions) and `.github/workflows/ci.yml`
|
|
(identical) run ruff, alembic smoke, pytest, gitleaks on every PR/push. The
|
|
current host runs no Gitea Actions runner, so until one is provisioned the
|
|
same gate is enforced locally: `scripts/pre-push` runs `make check` (lint +
|
|
tests + migration smoke + full-history secret scan) before every push, and the
|
|
audited commit hash in `AUDIT.md` is the one that passed it.
|
|
*Cost:* CI results are deferred on the current host; the gate itself is
|
|
identical to CI.
|
|
|
|
## D7 — gitleaks allowlist for test fixtures
|
|
`tests/` contains invented data (fake Nostr key, fake merchant mail). It is
|
|
allowlisted in `.gitleaks.toml` so the history scan stays signal-only.
|
|
*Cost:* a real secret committed under `tests/` would not trip the scanner —
|
|
compensating control: fixtures are reviewed in PRs, and no fixture ever reads
|
|
the environment.
|
|
|
|
## D8 — Proposal history kept when retiring the grant text
|
|
The repo began as a grant proposal; the retirement commit replaces it with the
|
|
project README (no grant references in the tree). The old commits stay — the
|
|
audit story ("this started as X, the operator mandated Y, here is the diff") is
|
|
more honest than a rewritten birth.
|
|
*Cost:* `git log` still shows the word "OpenSats" in old messages. The tree and
|
|
README carry none.
|
|
|
|
## D9 — Executor plugins are in-process registrations
|
|
An action plugin is a Python function registered in
|
|
`cayceops.components.executor.plugins.REGISTRY`, mapped by proposal `kind`.
|
|
`http_post` exists but is inert unless `CAYCE_OPS_ENABLE_HTTP_ACTIONS=true`.
|
|
*Cost:* no sandboxing of plugins — plugins are repo code, reviewed like
|
|
everything else.
|
|
|
|
## D10 — Audit chain is hash-chained; approval can require operator signature (post-audit)
|
|
`audit_log` rows chain sha256(prev_hash|fields); `verify_audit_chain` walks it,
|
|
the monitor can surface breaks. With `CAYCE_OPS_OPERATOR_PUBKEY` set,
|
|
`executor approve` REQUIRES a BIP-340 signature over
|
|
sha256("cayce-ops:approve:<id>") from the operator key — `--actor` becomes a
|
|
label, the key is the proof (the audit's "anyone can sign as anyone").
|
|
*Cost:* without a pubkey configured the gate degrades to the old free-text
|
|
actor; separate DB roles per daemon remain a deployment TODO (SQL to tighten
|
|
ships in deploy/roles.sql).
|
|
|
|
## D11 — Mail threading now has a real first-contact path (post-audit)
|
|
Sends create an OUTBOUND row (own Message-ID, In-Reply-To -> inbound);
|
|
inbound rows keep their original Message-ID. `maild compose` creates the
|
|
initial outreach draft for a proposal. Approval is bound to the draft text
|
|
via sha256 (`approved_hash`): an edited draft refuses to send until
|
|
re-approved. Each send commits in its own transaction — SMTP failure on
|
|
message N can no longer resurrect 1..N-1 as duplicates.
|
|
|
|
## D12 — IMAP \\Seen only after commit; content gates tighten (post-audit)
|
|
Messages are fetched unmarked and flagged \\Seen after the processing
|
|
transaction commits (crash mid-batch no longer loses mail). Publisher:
|
|
caption hash-bound at approval, disabled channels are terminal (`SKIPPED`),
|
|
publish failures burn a bounded attempt budget before abandonment.
|
|
`risk_score` renamed `match_score` (keyword relevance) and auto-approval
|
|
takes the HIGHEST score first.
|