# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## Data model Use the database in the `database` input. | Table | Columns | | --- | --- | | `audit_entries` | `log_id`, `seq`, `at`, `actor`, `action`, `target`, `data` (text), `ip`, `request_id`, `hash`; primary key on `log_id` and `seq` | | `audit_heads` | `log_id` (primary key), `seq`, `hash` | `log_id` is the workspace's id when the `scope` input is `workspace`, and a fixed value when it is `app`. `seq` starts at 1 in each log and has no gaps. `data` is stored as text, exactly as it was first written out, and never parsed and written again. The hash covers that text. ## Writing an entry In the caller's transaction: 1. Lock the log's row in `audit_heads`, creating it if this is the first entry. 2. Take `seq` as the stored one plus 1, and the stored hash as the one before. 3. Redact, write `data` out as JSON, work out the hash, insert the entry. 4. Store the new `seq` and hash in `audit_heads`. The lock is what keeps two entries from taking the same `seq`. It is held until the caller commits, so keep transactions that record entries short. ## The hash ``` line = seq | at | actor | action | target | data joined by the character | hash = SHA-256 of ( hash before, a line feed, line ) as UTF-8, in hexadecimal ``` `at` is written as `2026-01-02T03:04:05Z`. A missing target is an empty string. | | Entry 1 | Entry 2 | | --- | --- | --- | | `seq` | `1` | `2` | | `at` | `2026-01-02T03:04:05Z` | `2026-01-02T03:05:00Z` | | `actor` | `user:17` | `user:17` | | `action` | `member.invited` | `member.role_changed` | | `target` | `workspace:9` | `user:23` | | `data` | `{"email":"sam@example.com","role":"member"}` | `{"from":"member","to":"admin"}` | | Hash before | 64 zeros | Entry 1's hash | Entry 1's hash: ``` 04e07bea7c06897752773ff33cffead84421640c28e9eecfc79608d6a029878e ``` Entry 2's hash: ``` 6ff483be7c06c10095ea69986dfe29da2deeb2e74ac82a3484afc48ade971ae6 ``` ## Redaction Before `data` is written out, the value under any key whose lowercase name contains one of these is replaced by `[redacted]`, at any depth: `password`, `secret`, `token`, `authorization`, `api_key`, `card`. ## The trigger Reject `UPDATE` always. Reject `DELETE` unless the transaction has set a marker that only the job in R8 sets: a setting local to the transaction in Postgres, a row in a one-row table in SQLite. This stops mistakes and casual edits. Someone with full control of the database can still get past it, which is what the chain is for. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | ## Who is signed in The spec reaches the app's sign-in through one function, `current_user(request)`. It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session. When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production. ## Named here - A request for a workspace the person is not a member of, or that does not exist, gets 404. A member who is not an administrator gets 403. - The CSV columns, in order: `seq`, `at`, `actor`, `action`, `target`, `data`, `ip`, `request_id`, `hash`. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.