Appearance
0033: An activity log of proposals, decisions and writes
Context
On 2026-10-06 an entry Claude prepared coded an insurance premium at 20% VAT, and nobody could see when it was made, what Claude proposed, why, or who approved it. write_preview holds a preview only while it is live (a statement-text preview is cleared when it ends, ADR 0032), and ledger_write (ADR 0016, audit M6) holds only what was written, not what was proposed, the reason, or who pressed Approve or Decline. SPEC-010 adds the log.
Decision
- One table,
activity_log(migration0011-activity-log.sql):id,entity_id,principal_id(who acted),at(defaultnow()),kind(preview,approved,declinedoroutcome),preview_id(nullable),toolanddetail(jsonb). Indexed on(entity_id, at desc). - What is stored. For a preview: each proposed line's bank line ID, date, amount in pence, the contact as sent to Xero, the description only when Claude gave it (one that would default to the bank's own text is marked
descriptionFrom: "bank_line"and kept on the outcome row once it is in Xero), account code and name, tax type, the VAT worked out by code (SPEC-001's box mapping), the receipt's fileId and Claude's short reason (at most 200 characters, control characters removed); lines held back for a receipt (SPEC-003 S42) with why, and lines whose receipt cannot be attached, with a fixed code. For a decision: Approve or Decline and whether it was recorded. For an outcome: the Xero record IDs created, posted or attached (with each created entry's description, now in Xero), and each failure's reason. A failure that can name a file is kept as a fixed code (already_attached,file_not_foundand so on) with the file ID, never as text, since a name can change after the preview. A row's detail over 64 KB is replaced by a marker with its size. - What is never stored. Statement text (ADR 0032): the raw description or reference read from a statement file or text. Contact, description and reference are kept only as written to Xero, where they are anyway. A bank line ID that is built from a statement row's text (an Amex row with no reference,
amex-row:…) is kept only as an HMAC-SHA256 (16 hex characters) underACTIVITY_LOG_HASH_KEY, a 32-byte key in Dopplerprd(openssl rand -hex 32) that the web server requires at start. Without the key nobody can test a guessed description against the log. A local stdio server and the tests use a fixed development key. Never email content, file content or file names, tokens or secrets. - Visibility. Row-level security like every other table (ADR 0003): a row is read or added only where
entity_idis the session's entity and the principal has anentity_accessgrant for it, and a new row must name the signed-in principal. Everyone with access to a company sees its whole log, each row naming who acted; nobody on another company sees any of it. There is no update or delete policy andbootstrap.sqlrevokes both from the app role: the log is append-only. - Never in the money path. No reply waits for the log: each insert is started and not awaited. The row's detail is built inside the log's own try, so a fault building it, or an insert that fails or never finishes, leaves the preview, decision or write exactly as without the log. A failure goes to the server log with the entity, the kind and the error's name and code only, never the row or the error text. Each row's
atis taken when the call is made, so rows keep their order. - Retention, proposed: 6 years, matching HMRC record keeping and
ledger_write(ADR 0026, "Proposed retention"). Deleting rows is out of scope for now: like the other periods there, it needs a scheduled delete run by the owner role, under its own decision (QD-35). A row is a few KB at most (64 KB cap); FEAW makes tens of previews a month, so the table stays in the megabytes for years. - Reading.
activity_logpages newest first by(at, id)with a cursor (before), 50 rows a page. Search looks only at contacts, descriptions, accounts, tax types and Xero record IDs in a row's detail. Every string in its JSON is cleaned as the summary's text is.
Consequences
- A mistake can be traced from Xero back to the preview, its reason and the person who approved it, through the
activity_logread tool. - A preview costs one more insert, not waited for, in its own transaction after the preview is saved; a failed insert costs nothing else.
- The log holds names as written to Xero (contacts, descriptions) and who acted. ADR 0026's personal-data table gains a row for it when that ADR is next amended.
- Outcomes are logged where the write is made (the card's Approve and each
*_confirmtool), so both routes log the same way.