ledgrab/plans/activity-log/CONTEXT.md

CONTEXT — Activity / Audit Log

Living scratchpad for the feature. The orchestrator updates this between phases. Tier-2 context (survives across phases; graduates to CLAUDE.md only if it's a lasting project truth).

Config (from approval)

• Mode: Automated · Execution: Orchestrator · Strategy: Incremental
• Base/merge target: master · Branch: feature/activity-log · Branch point: 17dd2e0
• Final merge ALWAYS requires user approval (even in Automated mode).

Product decisions (locked)

• Placement: BOTH a top-level Activity tab AND a Dashboard Recent Activity widget, plus a Settings retention panel.
• Scope: all four categories — entity CRUD, auth, device connect/disconnect, capture & system.
• Detail: action metadata only (no before/after diffs).
• Durability: export on demand (CSV/JSON) + existing whole-DB backup. No separate backup subsystem.
• WebUI work uses the frontend-design skill (Phases 5–6).

Key codebase facts (verified during planning)

• fire_entity_event(entity_type, action, entity_id) @ api/dependencies.py:202 — central hook, called by every entity route synchronously in-request; has _deps store access.
• ProcessorManager.fire_event(dict) / subscribe_events() @ core/processing/processor_manager.py back /api/v1/events/ws (api/routes/output_targets_control.py:206). fire_event does put_nowait (no call_soon_threadsafe) — fine for the existing consumer; recorder marshals.
• Frontend realtime: core/events-ws.ts re-dispatches server:<type>; _ALLOWED_SERVER_EVENT_TYPES (line 39) is parity-checked by tests/test_events_ws_parity.py. Must add activity_logged.
• Actor: request.state.auth_label set in api/auth.py (129 authenticated, 83 anonymous).
• Storage: Database singleton (storage/database.py, single conn, RLock, WAL, synchronous=FULL, get_setting/set_setting). BaseSqliteStore loads ALL rows to memory → AVOID for the log. Migrations: storage/data_migrations.py (ALL_MIGRATIONS, idempotent).
• Backup/restore is whole-DB (Database.backup_to/restore_from, no STORE_MAP allowlist) → the new activity_log table is auto-covered. No system.py STORE_MAP edit needed.
• Background-engine pattern: core/backup/auto_backup.py (start/stop loop, _prune, settings).
• Thread-marshal precedent: utils/log_broadcaster.py (ensure_loop + call_soon_threadsafe).
• Device seams: device_health_changed (core/processing/device_health.py, on transition) + device_discovered/device_lost (core/devices/discovery_watcher.py, zeroconf thread).
• No API-key create/rotate/revoke routes exist (only GET /system/api-keys) → those auth events are DESCOPED.
• Existing Log Viewer (utils/log_broadcaster.py) = ephemeral debug-log tail; the audit log is a different, persistent, structured feature. Differentiate; do not duplicate.

Frozen contracts (fill as phases complete)

• ActivityLogEntry fields / dict shape: frozen — see phase-1-storage.md Handoff section. 11 fields: id, ts, category, action, severity, actor, message, entity_type, entity_id, entity_name, metadata. seq is DB-only (not on dataclass).
• ActivityLogFilters shape: frozen — 8 optional fields: categories, severities, actor, entity_type, entity_id, since, until, message_like. See phase-1-storage.md Handoff.
• recorder.record(...) signature + actor ContextVar import path: (Phase 2 handoff)
• API endpoints + query params + page envelope + settings bounds: (Phase 4 handoff)

Failed approaches / rejected designs

• Buffered async-writer subsystem (asyncio.Queue): REJECTED — unsafe from the zeroconf thread and adds a shutdown-flush ordering hazard. Using direct synchronous-on-loop writes with call_soon_threadsafe marshaling instead (simpler + correct).
• Using BaseSqliteStore for the log: REJECTED — loads all rows into memory.
• Separate activity-log backup subsystem: REJECTED — whole-DB backup already covers the table; export-on-demand is the portability story.

Deferred / open

• Setup-scaffold first-run noise suppression (batch/suppress flag) — deferred (nice-to-have).

Phase progress notes

Phase 1 landed (2026-06-09): activity_log.py (dataclass + enums + filters + codec), AddActivityLogTableMigration (002_add_activity_log) appended to ALL_MIGRATIONS, ActivityLogRepository (record/query/count/prune/clear/iter_export), 41 new tests — all green. Full suite 2226 passed, 0 failed. Schema and method signatures frozen in phase-1-storage.md Handoff. Gotcha: Database.execute takes a positional tuple — use ? placeholders (not :name), otherwise Python 3.14 will raise ProgrammingError.