fsylvain/RenewCMS
1
1 Fork 0
Code Issues Pull Requests Packages Projects Releases 19 Wiki Activity

feat: activity log producers

Browse Source
This commit is contained in:
fsylvain committed 2026-10-06 22:25:23 +02:00
1 parent 50b1649965
commit e37a46a027
93 files changed
+3396 -440
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

features/activity-log-producers.feature
+506
View File
@@ -0,0 +1,506 @@
Feature: Every real action of the back-office is recorded in the activity log from inside its use case
As the owner of a RenewCMS site
I want articles, media, users and invites, and system tasks to leave an activity event
So that the Activity screen shows who did what, and a failed attempt says why in plain words
Background:
Given the spec of record is docs/design/screens/activity.md ("What is recorded", "API contract") and the foundation slice features/activity-log-backend.feature
And this slice is backend only: no SPA, no new env var, no new table, no change to docs/design
And events are recorded by the use cases through audit.Recorder, never by handlers, middleware or GORM hooks
And every mutating use case method takes the request context as its first parameter and hands it to Recorder.Record, which fills actor, source, ip and user agent from the audit context
And system events set the system actor and source "system" themselves, with ip and user_agent null
And an event is recorded once, after the change was made (success) or after the use case decided to refuse or abort it (failed), never before
And no read is recorded: no GET, no list, no public article read, no status poll
And error responses are plain text from http.Error and success responses are JSON with snake_case fields, unchanged by this slice
And the layering rule holds: use cases see only domain interfaces, no comment is added anywhere
Rule: The audit context reaches every producing route
Scenario Outline: A producing route carries the origin of the request
When <request> is sent with <credentials>
Then the stored event has actor <actor>, source "<source>" and the request ip and user agent
Examples:
| request | credentials | actor | source |
| POST /v1/article | the owner's jwt cookie | the owner, named by display name | web |
| POST /v1/article | an API key "Deploy bot"| api_key id 7 named "Deploy bot" | api_key |
| POST /v1/media | an API key "Deploy bot"| api_key id 7 named "Deploy bot" | api_key |
| POST /v1/system/update/check | the owner's jwt cookie | the owner | web |
Rule: A failed audit write never changes the user's action
Scenario Outline: A failing or panicking repository leaves the response untouched
Given the audit repository <fault> on Append
When <request> succeeds
Then the response status and body equal those of the same request with a healthy repository
And the change itself was applied
And the process log names the failed audit write
Examples:
| fault | request |
| fails | POST /v1/article |
| fails | DELETE /v1/article/8 |
| panics | PATCH /v1/article/8/publish |
| fails | POST /v1/media |
| fails | POST /v1/media/merge |
| fails | POST /v1/user/invite |
| fails | POST /v1/system/update/restart |
Rule: Articles
Scenario: Creating an article is recorded
When the owner sends POST /v1/article with {"title": "Spring release", "body": "Hello"}
Then one event exists with action "article.create", category "articles", actor the owner, source "web", target {"type": "article", "id": "<new id>", "name": "Spring release"}, outcome "success", failure_reason null and no changes
And the stored event holds no article body
Scenario: Editing the body records a size delta and never the text
Given the article 8 "Spring release" has a body of 100 characters
When the owner sends PATCH /v1/article/8 with a body of 412 characters
Then one event exists with action "article.edit", target {"type": "article", "id": "8", "name": "Spring release"} and changes [{"field": "body", "kind": "body", "delta": 312}]
And no stored field and no /v1/activity response contains any text of either body
Scenario Outline: The delta is signed and counts characters
Given the article 8 has a body of <before> characters
When its body is replaced by one of <after> characters
Then the change delta is <delta>
Examples:
| before | after | delta |
| 100 | 412 | 312 |
| 412 | 100 | -312 |
| 5 | 5 | 0 |
Scenario: A body with multi-byte characters is counted in characters
Given the article 8 has the body "héllo"
When its body is replaced by "héllo wörld"
Then the change delta is 6
Scenario: Saving an identical body records nothing
Given the article 8 has the body "Same text"
When the owner sends PATCH /v1/article/8 with the body "Same text"
Then the response is 200 and no event is recorded
Scenario: A title change is recorded as a text diff when a title edit exists
Given a use case that changes an article's title from "Spring release" to "Spring release 2"
Then its event has action "article.edit" and changes [{"field": "title", "kind": "text", "before": "Spring release", "after": "Spring release 2"}]
And only the fields title, online and body can ever appear in an article event's changes
Scenario: Publishing is recorded with the publish state
Given the article 8 "Spring release" is offline
When the owner sends PATCH /v1/article/8/publish
Then one event exists with action "article.publish", category "articles" and changes [{"field": "online", "kind": "text", "before": "false", "after": "true"}]
Scenario: Unpublishing is recorded with the publish state
Given the article 8 is online
When the owner sends PATCH /v1/article/8/unpublish
Then one event exists with action "article.unpublish" and changes [{"field": "online", "kind": "text", "before": "true", "after": "false"}]
Scenario Outline: A publish state that does not change records nothing
Given the article 8 is <state>
When the owner sends PATCH /v1/article/8/<path>
Then the response is 200 and no event is recorded
Examples:
| state | path |
| online | publish |
| offline | unpublish |
Scenario: Deleting an article is recorded with its name snapshot
Given the article 8 "Spring release" exists
When the owner sends DELETE /v1/article/8
Then one event exists with action "article.delete", target {"type": "article", "id": "8", "name": "Spring release"} and outcome "success"
And GET /v1/activity shows that target with exists false
Scenario Outline: A refused article action is recorded as failed with a plain reason
Given <state>
When <request>
Then one event exists with action "<action>", outcome "failed" and failure_reason "<reason>"
And the response is unchanged
Examples:
| state | request | action | reason |
| no article has this title | POST /v1/article with a 2 character title | article.create | The title must be between 3 and 200 characters. |
| the repository fails with "db is locked" | POST /v1/article with a valid title | article.create | Something went wrong on our side. Please try again. |
| the repository fails with "db is locked" | PATCH /v1/article/8/publish | article.publish | Something went wrong on our side. Please try again. |
Scenario: An article that does not exist records nothing
When the owner sends DELETE /v1/article/99, PATCH /v1/article/99, PATCH /v1/article/99/publish and PATCH /v1/article/99/unpublish
Then every response is 404 and no event is recorded
Scenario: A request that fails validation records nothing
When the owner sends POST /v1/article with an empty body or a malformed id such as /v1/article/abc
Then the response is 400 and no event is recorded
Scenario Outline: Reads are never recorded
When <request> is sent
Then no event is recorded
Examples:
| request |
| GET /v1/article |
| GET /v1/article/8 |
| GET /v1/article/8 as the public |
Rule: Media
Scenario: Uploading an image is recorded
When the owner sends POST /v1/media with the PNG "spring-banner.png"
Then one event exists with action "media.upload", category "media", actor the owner, target {"type": "image", "id": "<new id>", "name": "spring-banner.png"} and outcome "success"
And the stored event holds no file content and no storage path
Scenario Outline: A refused upload is recorded as failed
When the owner uploads <file>
Then one event exists with action "media.upload", outcome "failed" and failure_reason "<reason>"
And the target name is the file name as sent, normalised the way a stored upload would be named, or empty when it is unusable
And the response is unchanged
Examples:
| file | reason |
| a GIF | The file must be a PNG, JPEG, WEBP or SVG image. |
| a PNG larger than the limit | The file is too large to upload. |
| a corrupt PNG | The image could not be read. |
Scenario: Renaming an image records the filename diff
Given the image 5 "banner.png"
When the owner sends PATCH /v1/media/5 with {"filename": "spring-banner"}
Then one event exists with action "media.rename", target {"type": "image", "id": "5", "name": "spring-banner.png"} and changes [{"field": "filename", "kind": "text", "before": "banner.png", "after": "spring-banner.png"}]
Scenario: Renaming to the same name records nothing
Given the image 5 "banner.png"
When the owner renames it to "banner"
Then no event is recorded
Scenario: A refused rename is recorded as failed
Given the image 5 "banner.png"
When the owner sends PATCH /v1/media/5 with an invalid filename
Then one event exists with action "media.rename", outcome "failed", failure_reason "That file name is not valid." and target {"type": "image", "id": "5", "name": "banner.png"}
Scenario: Deleting an image is recorded with its name snapshot
Given the image 5 "banner.png"
When the owner sends DELETE /v1/media/5
Then one event exists with action "media.delete", target {"type": "image", "id": "5", "name": "banner.png"} and outcome "success"
And GET /v1/activity shows that target with exists false
Scenario: Merging images is recorded once with its counts
Given the images 5 "banner.png", 6 "banner-copy.png" and 7 "banner-copy-2.png" share one content hash
And two articles reference the copies
When the owner sends POST /v1/media/merge keeping 5 and merging [6, 7]
Then one event exists with action "media.merge", target {"type": "image", "id": "5", "name": "banner.png"} and params {"merged": 2, "articles_updated": 2}
And no event names a removed copy as a separate action
Scenario Outline: A refused merge is recorded as failed
When the owner sends POST /v1/media/merge that fails with <error>
Then one event exists with action "media.merge", outcome "failed" and failure_reason "<reason>"
Examples:
| error | reason |
| ErrInvalidMergeRequest | The merge request is not valid. |
| ErrMergeCopyMissing | One of the copies no longer exists. |
| ErrMergeHashMismatch | The images are not identical copies.|
Scenario: A manual purge is recorded once and not as separate merges
Given a purge plan with 2 groups, 3 copies and 5 articles to update
When the owner sends POST /v1/media/purge
Then one event exists with action "media.purge", category "media", actor the owner, source "web", outcome "success" and params {"merged": 3, "articles_updated": 5}
And no "media.merge" event is recorded for its groups
Scenario: A partly failed manual purge is a success with the failed group count
Given a purge plan with 3 groups where 1 group fails
When the owner sends POST /v1/media/purge
Then one event exists with action "media.purge", outcome "success" and params that include "failed_groups": 1
Scenario Outline: A refused manual purge is recorded as failed
When the owner sends POST /v1/media/purge and the use case returns <error>
Then one event exists with action "media.purge", outcome "failed" and failure_reason "<reason>"
Examples:
| error | reason |
| ErrPurgeConflict | The library changed since the preview. Review it again. |
| ErrPurgeBusy | A purge is already running. |
Scenario: The scheduled purge is a system event
Given the purge is due and merges 3 copies and updates 5 articles
When PurgeSchedulerUseCase.Tick runs
Then one event exists with action "system.media_purge", category "system", actor type system named "System", source "system", ip null, user_agent null, outcome "success" and params {"merged": 3, "articles_updated": 5}
Scenario: A scheduled purge with a failed group records the failed group count
Given the purge is due and 1 group fails while others merge
When Tick runs
Then one event exists with action "system.media_purge", outcome "success" and params that include "failed_groups": 1
Scenario: A scheduled purge that is not due or merges nothing records nothing
Given the purge is not due, or is due and finds no duplicate
When Tick runs
Then no event is recorded
Scenario: A scheduled purge that cannot record its run is a failed system event
Given the purge is due and the run result cannot be saved
When Tick runs
Then one event exists with action "system.media_purge", outcome "failed" and failure_reason "Something went wrong on our side. Please try again."
Scenario: Browsing and the media usage lookup are never recorded
When the owner sends GET /v1/media, GET /v1/media/5/usage, GET /v1/media/purge-preview and GET /v1/media/purge-settings
Then no event is recorded
Rule: Users and invites
Scenario: Registering is recorded with the new account as actor
Given registration is open
When POST /v1/auth/register is sent with the username "marta"
Then one event exists with action "user.register", category "users", actor user "marta" with the new id, source "web", target {"type": "user", "id": "<new id>", "name": "marta"} and outcome "success"
And the stored event holds no password, no hash and no verification code
Scenario Outline: A refused registration is recorded as failed
When POST /v1/auth/register is sent and <cause>
Then one event exists with action "user.register", outcome "failed", failure_reason "<reason>", actor anonymous named by the attempted username and no target
And the response is unchanged
Examples:
| cause | reason |
| registration is closed | Registration is closed on this site. |
| the verification email cannot be sent | The verification email could not be sent. |
Scenario: Verifying an account is recorded
Given the unverified user 4 "lea" with a valid code
When user 4 sends POST /v1/auth/verify with that code
Then one event exists with action "user.verify", category "users", actor user 4, target {"type": "user", "id": "4", "name": "lea"} and outcome "success"
And the stored event does not hold the code or its hash
Scenario Outline: A refused verification is recorded as failed
Given the unverified user 4 "lea"
When user 4 sends POST /v1/auth/verify and the use case returns <error>
Then one event exists with action "user.verify", outcome "failed" and failure_reason "<reason>"
Examples:
| error | reason |
| ErrInvalidVerificationCode | The verification code is not valid. |
| ErrVerificationCodeExpired | The verification code has expired. |
Scenario: Changing the display name records a before and after
Given user 3 has the display name "Marta"
When user 3 sends PATCH /v1/user/me with {"display_name": "Marta Alves"}
Then one event exists with action "user.update_profile", category "users", target {"type": "user", "id": "3", "name": "Marta Alves"} and changes [{"field": "display_name", "kind": "text", "before": "Marta", "after": "Marta Alves"}]
And the actor snapshot name is the name held when the request began
Scenario Outline: Setting a display name that does not change records nothing
Given user 3 has the display name "<current>"
When user 3 sends PATCH /v1/user/me with {"display_name": "<sent>"}
Then no event is recorded
Examples:
| current | sent |
| Marta | Marta |
| Marta | Marta |
| | |
Scenario: A display name that is too long is recorded as failed
When user 3 sends PATCH /v1/user/me with a 61 character name
Then one event exists with action "user.update_profile", outcome "failed" and failure_reason "That display name is too long."
And the stored event holds no changes
Scenario: Creating an invite is recorded
When the owner sends POST /v1/user/invite with {"email": "new@example.com"}
Then one event exists with action "invite.create", category "users", actor the owner, target {"type": "invite", "id": "<invite id>", "name": "new@example.com"} and outcome "success"
And the stored event holds no invite code and no hash
Scenario Outline: A refused invite action is recorded as failed
When the owner <request> and the use case returns <error>
Then one event exists with action "<action>", outcome "failed" and failure_reason "<reason>"
Examples:
| request | error | action | reason |
| sends POST /v1/user/invite | ErrEmailHasAccount | invite.create | That email already has an account. |
| sends POST /v1/user/invite | ErrPendingInvite | invite.create | An invitation is already pending for that email. |
| sends POST /v1/user/invite | ErrInviteEmailNotSent | invite.create | The invitation email could not be sent. |
| sends POST /v1/user/invite/4/renew | ErrInviteEmailNotSent | invite.renew | The invitation email could not be sent. |
| sends POST /v1/user/invite/4/renew | ErrInviteAlreadyAccepted | invite.renew | That invitation was already accepted. |
| sends DELETE /v1/user/invite/4 | ErrInviteAlreadyAccepted | invite.cancel | That invitation was already accepted. |
Scenario: Cancelling an invite is recorded
Given the pending invite 4 for "new@example.com"
When the owner sends DELETE /v1/user/invite/4
Then one event exists with action "invite.cancel", target {"type": "invite", "id": "4", "name": "new@example.com"} and outcome "success"
Scenario: Renewing an invite is recorded
Given the pending invite 4 for "new@example.com"
When the owner sends POST /v1/user/invite/4/renew
Then one event exists with action "invite.renew", target {"type": "invite", "id": "4", "name": "new@example.com"} and outcome "success"
And a renewal whose email fails is rolled back and recorded only as failed
Scenario: Accepting an invite is recorded with the new account as actor
Given the pending invite 4 for "new@example.com"
When POST /v1/auth/invite/accept is sent with a valid code and the username "sam"
Then one event exists with action "invite.accept", category "users", actor user "sam" with the new id, source "web", target {"type": "invite", "id": "4", "name": "new@example.com"} and outcome "success"
And the stored event holds no code, no hash and no password
Scenario Outline: A refused acceptance is recorded as failed
When POST /v1/auth/invite/accept is sent and the use case returns <error>
Then one event exists with action "invite.accept", outcome "failed", failure_reason "<reason>" and actor anonymous named by the attempted username
And the stored event has no target when the invite could not be identified
Examples:
| error | reason |
| ErrInviteInvalid | That invitation is not valid. |
| ErrInviteExpired | That invitation has expired. |
| ErrInviteAlreadyAccepted | That invitation was already accepted. |
| ErrUsernameTaken | That username is already taken. |
| ErrEmailHasAccount | That email already has an account. |
Scenario: An invite or user that does not exist records nothing
When the owner sends DELETE /v1/user/invite/99 or POST /v1/user/invite/99/renew
Then every response is 404 and no event is recorded
Scenario Outline: Reads and checks are never recorded
When <request> is sent
Then no event is recorded
Examples:
| request |
| GET /v1/user |
| GET /v1/auth/me |
| GET /v1/auth/invite?code=<code> |
| GET /v1/auth/registration |
Rule: System tasks
Scenario: Checking for an update is recorded
Given the release feed answers v1.4.0 while the running version is v1.3.2
When the owner sends POST /v1/system/update/check
Then one event exists with action "system.update_checked", category "system", actor the owner, source "web", target {"type": "release", "id": "v1.4.0", "name": "v1.4.0"}, outcome "success" and params {"update_available": true}
Scenario Outline: A failed update check is recorded with a plain reason
When the owner sends POST /v1/system/update/check and the use case returns <error>
Then one event exists with action "system.update_checked", outcome "failed", failure_reason "<reason>" and no target
Examples:
| error | reason |
| ErrFeedUnavailable | The release feed could not be reached. |
| ErrNoRelease | No release was found. |
Scenario: The status poll is never recorded
When the owner sends GET /v1/system/update
Then no event is recorded
Scenario: A download that completes is recorded when the job is ready
Given a newer release v1.4.0 is available and the update helper is installed
When the owner sends POST /v1/system/update/download
Then the response is returned before the job ends and no event exists yet
And when the job reaches the ready state one event exists with action "system.update_downloaded", actor the owner, source "web", target {"type": "release", "id": "v1.4.0", "name": "v1.4.0"} and outcome "success"
And the origin (actor, ip, user agent) is the one captured at request time
Scenario Outline: A download that fails is recorded with a reason that hides the cause
Given a newer release v1.4.0 is available and the job fails with the error kind "<kind>"
Then one event exists with action "system.update_downloaded", outcome "failed" and failure_reason "<reason>"
And the stored event holds no url, no path and no raw error text
Examples:
| kind | reason |
| download | The update could not be downloaded. |
| verification | The downloaded update failed its integrity check. |
Scenario Outline: A download refused at the start is recorded as failed
When the owner sends POST /v1/system/update/download and the use case returns <error>
Then one event exists with action "system.update_downloaded", outcome "failed" and failure_reason "<reason>"
And the response is unchanged
Examples:
| error | reason |
| ErrNotPrepared | This server cannot apply updates. |
| ErrJobInProgress | An update is already being downloaded. |
| ErrRestartPending | A restart is already pending. |
| ErrNothingToUpdate | There is nothing to update. |
| ErrPreflightRefused | The update cannot be downloaded. |
Scenario: A restart request is recorded
Given the update helper is installed and no job is running
When the owner sends POST /v1/system/update/restart
Then one event exists with action "system.restart_requested", category "system", actor the owner, source "web", outcome "success" and params {"kind": "restart"}
Scenario: A restart that applies a downloaded update records the kind and version
Given a downloaded update v1.4.0 is ready
When the owner sends POST /v1/system/update/restart
Then the event has params {"kind": "update", "tag": "v1.4.0"}
Scenario Outline: A refused restart is recorded as failed
When the owner sends POST /v1/system/update/restart and the use case returns <error>
Then one event exists with action "system.restart_requested", outcome "failed" and failure_reason "<reason>"
Examples:
| error | reason |
| ErrNotPrepared | This server cannot apply updates. |
| ErrJobInProgress | An update is still being downloaded. |
| ErrRestartPending | A restart is already pending. |
| ErrRestartKindMismatch | The requested restart does not match the server state. |
Rule: A failed outcome never exposes more than the plain-language reason
Scenario: Failure reasons are mapped from domain sentinels
Given a table that maps each domain Err sentinel above to a fixed sentence
When a use case fails with an error that wraps one of them
Then failure_reason is that sentence, matched with errors.Is
Scenario Outline: Unmapped errors become the generic sentence
When a use case fails with <error>
Then failure_reason is "Something went wrong on our side. Please try again."
And neither the event, the activity API nor the CSV export holds the text of the error
Examples:
| error |
| errors.New("db is locked") |
| an error carrying an SMTP host and password |
| an error carrying a file system path |
| an error wrapping a sentinel and a raw cause |
Scenario: Every failure reason fits the stored limit
Then every mapped sentence is at most 255 characters
Scenario: A failed event keeps its target when the target is known
Given the image 5 "banner.png" exists
When a rename of image 5 is refused
Then the failed event keeps the target snapshot of image 5
Rule: Secrets and bodies never reach the log
Scenario Outline: Sensitive values are absent everywhere
Given the action <action> handled <secret>
When it is recorded, listed through GET /v1/activity and exported through GET /v1/activity/export
Then no stored field, no params, no change, no response, no CSV cell and no process log line contains <secret>
Examples:
| action | secret |
| user.register | the password, its hash and the verification code |
| user.verify | the verification code and its hash |
| invite.create | the invite code and its hash |
| invite.accept | the invite code, its hash and the password |
| article.edit | the old and the new article body |
| media.upload | the file bytes and the storage path |
| system.update_downloaded | the asset url and the staging path |
Scenario: Only allowlisted fields appear in changes
Then the only change fields any producer emits are title, online, body, filename and display_name
And the only change kinds are text and body
Rule: The recorded events read back through the existing API
Scenario: Producer events are listed with their documented shape
Given an article was created, edited, published and deleted by the owner
When the owner sends GET /v1/activity?category=articles
Then the four events are listed newest first, with category "articles", the documented item shape and the article target exists false after the delete
Scenario Outline: Categories filter the producers
Given one event of each producer was recorded
When the owner sends GET /v1/activity?category=<category>
Then the items are exactly the events listed in <actions>
Examples:
| category | actions |
| articles | article.create, article.edit, article.publish, article.unpublish, article.delete |
| media | media.upload, media.rename, media.delete, media.merge, media.purge |
| users | user.register, user.verify, user.update_profile, invite.create, invite.cancel, invite.renew, invite.accept |
| system | system.media_purge, system.update_checked, system.update_downloaded, system.restart_requested |
Scenario: A failed producer event is filterable
Given a refused merge and a successful rename were recorded
When the owner sends GET /v1/activity?outcome=failed
Then only the refused merge is listed with its failure_reason
features/activity-log-producers.qa.md
+67
View File
@@ -0,0 +1,67 @@
# QA procedure: activity-log-producers
Go only, no SPA. Package `test` (black-box). New files: `test/activity_producers_articles_test.go`, `test/activity_producers_media_test.go`, `test/activity_producers_users_test.go`, `test/activity_producers_system_test.go`, `test/activity_producers_reasons_test.go`. Reuse the foundation helpers in `test/activity_support_test.go` (`mockAuditRepo`, `fakeAuditClock`, `seedEvents`). Extend the existing hand-written fakes (`mockArticleRepo`, the image, user, invite, purge, update and status fakes) with failure switches and call counters. New fake type names must be unique across the package. No live server, no real SMTP, no real SQLite file, no real sleeping, no `time.Ticker`. Secrets in tests are fixed test strings only.
## Setup shared by every case
1. `validator.InitValidator()` once. `jwtauth.New("HS256", []byte("test-secret"), nil)` stands in for `JWT_SECRET`.
2. One `auditing.NewRecorder(mockAuditRepo, fakeAuditClock.Now, logger)` shared by every use case. `logger` writes to a `bytes.Buffer` (restore with `t.Cleanup`).
3. Users: owner 1, admin 2, verified user 3 "Marta", unverified user 4 "lea" (with a hashed code). API key 7 "Deploy bot" in the fake key repo.
4. A fresh `chi.NewRouter()` per test that mirrors `api/router.go` for the article, user, media, system and auth routers, with `middleware.AuditContext(getUser, trustedProxies)` placed exactly where the router wires it (after `apiKeyAuth()` on the article, user and media routers). Cookies are real signed `jwt` cookies with `user_id` and `token_version`. `httptest.NewRecorder` per request.
5. Helpers: `eventsOf(repo)`, `onlyEvent(t, repo)` (fails unless exactly one event), `assertNoEvent(t, repo)`.
6. Each mutating use case method takes `ctx context.Context` first. A method called with a context holding no origin still works.
## A. Origin and routing
7. Table (feature rule 1): each request with the cookie or the API key yields the expected actor type, id, name and source, plus the request ip and user agent. Proves `AuditContext` is mounted on the article, user, media and system routers.
8. A route without credentials, or answered 401/403/429, records nothing.
## B. Articles
9. Create: one `article.create` event, target id string, name as typed, no changes, no body anywhere (marshal the event and assert absence).
10. Edit: table `(before, after, delta)`: 100 to 412 (312), 412 to 100 (-312), 5 to 5 with different content (0, still recorded), `héllo` to `héllo wörld` (6, characters not bytes). Identical body records nothing. Change kind `body`, `Delta` set, `Before` and `After` nil.
11. Publish and unpublish: `online` text change (`"false"`/`"true"`). Repeating the same state records nothing and returns 200.
12. Delete: event keeps the name snapshot. After it, `GET /v1/activity` shows `target.exists` false.
13. Title diff: unit-test the change builder with title, online and body only; any other field name is rejected.
14. Failure table: 2 character title, repository failing with `errors.New("db is locked")` (generic reason). 404 on delete, edit, publish, unpublish of id 99 and 400 on malformed id or body record nothing.
15. Reads (list, get, public get) record nothing.
## C. Media
16. Upload: in-memory PNG, target name equals the normalised filename, no bytes and no path. Failed upload table: GIF, oversize, corrupt PNG, each with its mapped reason.
17. Rename: `filename` text change `banner.png` to `spring-banner.png`. Same name records nothing. Invalid stem records a failed event keeping the target. Missing image records nothing (404).
18. Delete: event with name snapshot. Missing image records nothing.
19. Merge: three images with one hash, two articles referencing the copies. One `media.merge` event with `{"merged":2,"articles_updated":2}`, target the kept image. Failure table: `ErrInvalidMergeRequest`, `ErrMergeCopyMissing`, `ErrMergeHashMismatch`.
20. Manual purge: plan with 2 groups, 3 copies, 5 articles. Exactly one `media.purge` event with `{"merged":3,"articles_updated":5}` and zero `media.merge` events. A plan with one failing group: outcome success with `failed_groups` 1. `ErrPurgeConflict` and `ErrPurgeBusy` give failed events. Preview, usage, list and settings GETs record nothing.
21. Scheduled purge: drive `PurgeSchedulerUseCase.Tick(now)` with the fake purge repo and clock. Due and merging 3: one `system.media_purge` event with system actor, source system, ip nil, user agent nil. Due with a failed group: success with `failed_groups`. Not due, or no duplicates: none. A fake `SaveLastRun` failure: failed event with the generic reason.
22. Manual purge after the scheduler in the same test yields two events with sources `web` and `system`.
## D. Users and invites
23. Register: open registration records `user.register` with the new account as actor and target. Closed registration and a failing mailer (error carrying a fake SMTP password) record failed events with the mapped reason, anonymous actor named by the attempted username, no raw text. Marshal the event and assert password, hash and code are absent.
24. Verify: success, invalid code, expired code.
25. Display name: before/after diff, trimmed no-op records nothing, empty to empty records nothing, 61 characters records a failed event with no changes. Actor snapshot name is the pre-change name.
26. Invites: create, cancel, renew, accept each record the documented event with the invited email as target name. Failure table covers every error in the feature. A renew whose mail fails is rolled back and records one failed event only. Unknown ids (404) record nothing.
27. Accept: actor is the new account, source `web`; failed accept actor is anonymous with the attempted username.
28. Reads (`GET /v1/user`, `/v1/auth/me`, `/v1/auth/invite`, `/v1/auth/registration`) record nothing.
## E. System tasks
29. Check: success event with `{"update_available":true}` and a release target. `ErrFeedUnavailable` and `ErrNoRelease` give failed events without target. Status `GET` records nothing.
30. Download: fakes complete the job through a hand-fed channel (no `time.Sleep`). No event before the job ends, one after `ready`; actor, ip and user agent are those captured at request time even though the request context was cancelled. Failure kinds `download` and `verification` give the two reasons, no URL or path. Start-time refusals give failed events. Run with `-race`.
31. Restart: `{"kind":"restart"}` and `{"kind":"update","tag":"v1.4.0"}`. Refusals for `ErrNotPrepared`, `ErrJobInProgress`, `ErrRestartPending`, `ErrRestartKindMismatch`.
## F. Reasons, secrets and recorder faults
32. Reason table: wrap each sentinel with `fmt.Errorf("%w: %w", sentinel, errors.New("secret detail"))`, assert the sentence equals the table and the extra text is absent. Unmapped errors give the generic sentence. Every sentence is at most 255 characters.
33. Recorder fault: for each producer row of the fault table, run with failing, panicking and healthy `mockAuditRepo`. Identical status and body, change applied, log line naming the failed write.
34. Secret sweep: after exercising every producer, marshal every stored event, the `/v1/activity` response and the `/v1/activity/export` file; assert none contains the password, hash, verification code, invite code, raw API key, article body, file bytes, asset URL or staging path. The log buffer is free of them too.
35. Allowlist: every `Change.Field` is in `{title, online, body, filename, display_name}` and every kind is `text` or `body`.
36. Read-back: list by `category=articles|media|users|system` and `outcome=failed`; compare action sets with the feature tables.
## G. Mutation guard (gremlins stays clean)
37. `task mutate` scope is `./internal/infrastructure/useCases`. Each new branch needs a killing assertion: every no-op guard (body, online, filename, display name) with equal and differing values; delta sign and rune-versus-byte count; success versus failed outcome and recorded once after the change (event count and order against the repository call); every `errors.Is` row of the reason map plus the generic fallback; every `ctx` forwarding; the system-actor defaults. Bare-bool conditions produce no mutant, so cover both branches with tests regardless.
## H. Layering and hygiene
38. Touched use cases import no `gorm`, `persistence`, `mailer`, `net/http`, chi or `api/...`; handlers only pass `r.Context()`; `internal/domain/audit` imports only stdlib and domain packages.
39. No comments in new or edited Go files, test files and docs, except tool directives.
40. Docs (`docs/api.md`, `docs/architecture.md`) list the action catalogue, target types, reason sentences and the rule that no read is recorded.
## Manual (not automated)
41. Real boot with `task dev:api` and SMTP: register, verify, invite, renew, accept and cancel an invite, change display name, create/edit/publish/unpublish/delete an article, upload/rename/merge/delete images, manual purge; read `/v1/activity` and the CSV export and read every sentence.
42. Real update helper on Linux systemd (or the Docker QA flow): check, download until `ready`, restart; one event each, real asset names absent. Skip in a container.
43. Leave the scheduled purge due and wait for the hourly tick: a single `system.media_purge` event, source `system`, no ip or user agent.
44. Remove the database file's write access during one article edit: edit result unchanged, process log names the audit write failure.