62. One history with actions and actors
Date: 2026-10-26
Status
Accepted
Supersedes ADR 0007 and the job history part of ADR 0057. Spec: history.
Context
bikesched_job_historyrecorded the state of a job or step after each change, with a prosedetail. It answered “what state was the job in”, not “what happened, and who did it”: aSCHEDULEDrow could be a new job, a failed attempt, a retry, a release or a postponement.- Published events, nodes registering, stopping and being removed, and what users do in the admin UI were not recorded at all.
- A deleted job’s or step’s history lost its name: the step was identified by its name, the job only by its id.
- Alternatives considered: a job history plus a separate event table (two tables, two clean-ups, a
union allfor a feed), an audit table written by the admin (a second write path, the same fact stored twice), database triggers (rejected in ADR 0007, and they cannot know the user), typed columns for every specific instead of JSON (a migration per new specific).
Decision
- One opt-in table
bikesched_historyfor jobs, their steps, events and nodes, keyed by (subject_id,id), written by the stores in the transaction of the change as before (history(retention)on the builder; a clean-up deletes entries after the retention). No foreign keys: entries outlive their subjects. - Every entry has an
action, an enum per subject type and for steps (JobAction,StepAction,EventAction,NodeAction, sealed underHistoryAction), next to the resultingstateof a job or step. The step is referenced bystep_id. - Every entry has an actor:
actor_type(NODE,APPLICATION,JOB,USER) and, for users only,actor_name.node_idstays the node that wrote the entry, set once the node registered. The user goes only on the entry of the action itself; its consequences in the same transaction carry the code path’s actor and acaused_by_idnaming the event, job or node that caused them, never another entry. - Names and an action’s specifics go into
data, a JSON object built in SQL by the one recording statement from the rows the transaction just wrote, so the names survive deleting the subject. Texts are cut to 4000 characters. Core returnsdataas JSON text and parses nothing. - Entries are ordered by (
created_atfromclock_timestamp(),id): one clock for all nodes, UUIDv7 ids only break ties. No stored sequence and no lock. - The public API is the package
org.bikesched.history: a sealedHistoryEntrywith a record per subject (JobEntry,StepEntry,EventEntry,NodeEntry).findJobHistoryreturns the job and step entries;JobHistoryEntryis removed.StepStatebecomes public inorg.bikesched.job. - The plain write methods of
Bikesched(cancel,retry,removeRecurringJob) stay and recordAPPLICATION. A user is named withactor(Actor.user(name))on the job and event builders and on the write builders underbikesched.admin()(cancelJob,retryJob,removeRecurringJob), which the admin UI uses with the signed-in user. - Idempotency duplicates and no-ops are not recorded: nothing changed.
Consequences
- One history answers “what happened, and who did it” across jobs, events, nodes and users, and
feeds a History tab in the admin UI without a
union. - A new specific is a code change in one statement, not a migration;
datais never filtered or indexed. - Rows grow from about 98 to 185 bytes on average (100k job and step rows), indexes from 5.4 to 8.4 MB.
- Nodes without the history still leave gaps, also for user actions; it should be enabled on all nodes.
- Breaking: the table, the
jobHistory(…)settings andJobHistoryEntryare replaced (history(…),HistoryEntry). Before the first release, the change goes intoV001in place. - Recurring jobs are not a subject (no stable id), and a separate retention for user entries is deferred.