This file documents the audit log subsystem. Claude Code auto-loads it when a file under `devplacepy/services/audit/` is read or edited.

## Audit log (`services/audit/`)

**Admin-only, append-only** record of every state-changing action. The authoritative event catalogue is `events.md` (its storage model, relation vocabulary, and per-event specs are authoritative); the catalogue currently spans 293 keys across 43 domains.

### Package layout

- `store.py` - the `audit_log` + `audit_log_links` tables, `ensure_tables`, `insert_event`/`insert_links`/`get_event`/`get_links`/`sweep`.
- `categories.py` - `category_for(event_key)` (longest-prefix map).
- `record.py` - the recorder + link builders.
- `query.py` - `list_events`/`filter_options`/`get_event_with_links` for the admin UI (admin list/detail).
- `service.py` - `AuditService` (retention sweep).

`ensure_tables()` + the 11 indexes are wired into `database.py` `init_db()` via a **local import** (audit modules import `database`/`utils`, so the import is deferred to avoid the cycle). `AuditService` is registered in `main.py`.

### Two recorder entrypoints (the reuse keystone)

`record(request, event_key, *, user=_UNSET, actor_kind=None, target_type/uid/label, old_value, new_value, summary, metadata, result="success", origin, via_agent, links, category)` is for HTTP/WebSocket handlers - `request` may be a Starlette `Request` OR `WebSocket` (both expose `.headers`/`.url`/`.client`). It auto-derives the actor from `get_current_user(request)` (or an explicit `user=`), the request fields, and the **`X-Devii-Agent`** header (-> `origin=devii`, `via_agent=1`), and auto-appends the `actor` link.

`record_system(event_key, *, actor_kind, actor_uid, actor_username, actor_role, origin, via_agent, ...)` is for request-less contexts (rewards, notifications, the AI gateway ledger, the news/container services, Devii turns/tasks, job services, the CLI).

**Both are best-effort: wrapped in try/except, they NEVER raise into the caller** - the audited action is never blocked by a logging failure. `summary` is HTML-stripped and capped at 140 chars; `metadata` is JSON-serialised. Link builders (`audit.target`, `audit.parent`, `audit.author`, `audit.recipient`, `audit.project`, `audit.instance`, `audit.setting`, `audit.job`, `audit.poll`, `audit.option`, `audit.task`, ...) keep call sites terse.

### Emission convention

Emission is **explicit per mutation** - `audit.record(...)` / `record_system(...)` calls placed after the mutation succeeds, or on the guard branch with `result="denied"`/`"failure"`. DRY choke points:

- Posts/projects/gists create/edit/delete record inside `content.py` (`create_content_item`/`edit_content_item`/`delete_content_item`, the latter two derive the key from `target_type`).
- Project file ops record via the `_audit_file`/`_edit`/`_fail` helpers in `project_files.py` (read-only guard -> `result="denied"`).
- Services via `_audit_service`.
- Containers via `audit_instance` (in `routers/projects/containers/_shared.py`) for the HTTP path, and in the Devii `actions/dispatcher.py` `_audit_mechanic` hook (after a successful `_run`) for the agent path - the two paths are disjoint (Devii calls `api.py` directly, never the routes), so there is no double counting. The dispatcher hook also emits the `devii.*` self-config mechanics (behavior/tools/tasks/lessons/customization) from one place.

The dispatcher's **authorization guard** (before `_run`) mirrors this with `_audit_denied`: a tool call refused for `requires_auth`/`requires_admin`/`requires_primary_admin` records a `security.authz.denied` event (`origin="devii"`, `via_agent=1`, `result="denied"`, `metadata.tool`/`reason`) so an agent-driven escalation attempt is visible in the admin Audit Log, not just the app log. This is what surfaces a non-admin's Devii probe of `admin_*`/`db_*` tools (the tool schemas are already withheld from non-admins by `tool_schemas_for`, so this fires only when the model invents a name it never received).

### Failures and denials are events

`auth.login.failure`, `auth.password.forgot_request` (unknown email), `security.rate_limit.block`, `security.maintenance.block`, `security.authz.denied` (emitted inside `require_user`/`require_admin` on the HTTP side, and inside the Devii dispatcher's `_audit_denied` for a refused agent tool call), self-role-change and self-disable denials, **admin-seniority denials** (a junior admin managing a senior admin), read-only write attempts, and `ai.quota.exceeded` all record with `result` set to `failure`/`denied`. Auth failures, authz denials (in `require_user`/`require_admin`), rate-limit/maintenance blocks, self-role-change/self-disable denials, and quota blocks are recorded with `result` set.

### Admin UI

`GET /admin/audit-log` (paginated, filterable list, `admin_section="audit-log"`) and `GET /admin/audit-log/{uid}` (detail + links) in the `routers/admin/` package, both `require_admin`, both negotiate via `respond(..., model=AuditLogOut|AuditEventOut)`. Templates `admin_audit_log.html` / `admin_audit_event.html` reuse `admin.css` + a small `audit.css`; `_pagination.html` gained an optional backward-compatible `pagination_query` prefix (default empty) so filters survive paging. Sidebar link sits last, before Settings.

### Devii access (read-only)

Admins query the same two routes conversationally via the admin-only Devii tools `audit_log` (GET `/admin/audit-log`) and `audit_event` (GET `/admin/audit-log/{uid}`) (`services/devii/actions/catalog.py`, `handler="http"`, `requires_admin=True`) - no new endpoint, since the `respond(...)` routes already serve JSON to Devii's `Accept: application/json` client (like `admin_list_users`). `audit_log` forwards every filter as a query param (`page`, `event_key`, `category`, `actor_role`, `actor_uid`, `origin`, `result`, `q`, `date_from`, `date_to`) and returns `AuditLogOut`, whose `options` object lists the valid values for each filter so the agent can discover them in one call. `audit_event` returns `AuditEventOut` (the row + related links). A system-prompt steer in `agent.py` (the AGGREGATES block) routes audit/history/"who did X" questions to these tools.

### Deferred persistence

`record`/`record_system` do all the cheap prep (actor resolve, sanitize, `json.dumps`, link assembly) on the request thread, then hand the two DB inserts to the **background task queue** (`services/background.py`, `background.submit(_persist, row, links)`) so the request returns without waiting on SQLite. The `uid`/`created_at` are generated eagerly at record time (so the return value and the audit timestamp reflect the action, not the flush). Under `DEVPLACE_DISABLE_SERVICES=1` (tests) the queue runs inline, so audit rows are visible immediately. See CLAUDE.md -> "Background task queue".

### Retention

`AuditService` (the `audit` service, daily) prunes rows older than `audit_log_retention_days` (default 90; `0` disables) via `store.sweep`. Configurable on the Services page like any other service.

### Adding an event

Pick/extend a key in `events.md`, add the `category_for` prefix if it is a new domain, then call `audit.record`/`record_system` at the mutation point with the right links and `result`. Never gate the audited action on the recording.
