The trail is kept forever unless your Worker says otherwise. The retention block in its pithy.config.ts sets how long events are kept, by action prefix, with a default, and a prune in your own Worker removes what is past its window. The prune leaves a tombstone for every run it removes, so the hash chain still verifies across the gap.
The block also governs purge windows and inactive accounts, and a legal hold stops the prune: Retention and legal holds is the whole policy. This page is the trail’s part of it.
Say how long
retention: {
audit: { default: "2y", prefixes: { "support/": "180d", "controlplane/": "7y" } },
},default covers any action no prefix names, and absent or forever keeps it forever. prefixes sets a window by action prefix, and the longest match decides. A duration is whole days as a number, or 90d, 12w, 18m, 3y. With no audit key, nothing is pruned.
The kit holds a floor. No rule keeps controlplane/*, or a lifecycle action a composed capability records (a deletion, a purge, a suspension, a reinstatement, a restore), for less than 365 days. A prefix rule that would is refused when the Worker assembles, so it never deploys. A default under a year is allowed, and the floored actions are held at a year under it.
Until a window passes, every event you emit stays. By default that is forever, which makes two decisions matter more than they otherwise would.
What goes in metadata. It is a free-form bag, it is returned by the detail read, and it is kept as long as the event is. A resource name is fine. An email address is a choice you are making for the life of the window. A secret is a disclosure that lasts as long.
How often you emit. An action worth recording is worth recording every time. An action you emit on every request because it seemed harmless is a table you will eventually have to deal with by hand.
The prune runs in your own Worker
No route deletes a row, and none ever will, because a management credential that could erase an audit row could erase the evidence of its own use. The prune is a Workflow your Worker runs on its own schedule, and it reads the retention block that only that Worker resolves. Export the class beside createEntrypoint:
// apps/api/src/index.ts
import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
import { NonRetryableError } from "cloudflare:workflows";
import { runAuditPrune } from "@pithy-sh/audit/src/workflows/prune";
export class AuditPruneWorkflow extends WorkflowEntrypoint<Record<string, unknown>> {
override run(event: WorkflowEvent<unknown>, step: WorkflowStep) {
return runAuditPrune(this.env, event, step, NonRetryableError);
}
}Then bind it as AUDIT_PRUNE in that Worker’s workflows, beside the 0 2 * * * cron auth’s and organization’s purge passes already use. The binding is optional: until it is bound, nothing is pruned.
A pruned run leaves a tombstone, so the chain still verifies. Before deleting a row, the prune writes one object per run to the AUDIT_CHECKPOINTS bucket, under the chain’s checkpoint prefix, where the object lock covers it: the run’s positions, the link before it, and the hashes at either end. GET /audit/control-plane/verify and pithy audit verify bridge the gap with it and answer intact. The Worker’s verify also counts the events it crossed, as pruned. Without the bucket bound in that Worker, nothing chained is pruned.
- A run that does not verify stays. The prune never removes the evidence of a break.
- The head is never pruned. The next append links to it.
- An event kept longer stays where it is. Windows differ by action, so each run of consecutive events past their windows is pruned on its own.
- Rows from before the chain are removed on their own window, with nothing to tombstone.
- A legal hold on a tenant’s trail stops it at the next page, and the chain stays whole until the hold is released.
What still matters
Emit deliberately. The trail is for security-relevant actions: sign-ins, token refreshes, entitlement grants, admin changes, denials — logging is where the rest of what a run did belongs. It is not an application log, and the logging capability is where high-volume operational detail belongs.
Keep the metadata bag small and non-identifying. Codes and resource ids, not sentences and not addresses.
Watch the database. The trail defaults to DB — the reference names the binding and the table — the shared app database — so its growth is your application database’s growth, as far as your windows let it grow. Pointing it at its own binding is possible today.
Ask before you export. An exported trail carries project, environment and worker on each row precisely so an aggregate does not lose where a row came from — but it also carries whatever you put in metadata, to wherever you sent it.
Why it is a table and not a stream
An audit log is a query workload: by actor, by action, by time range, by resource, by outcome. KV is get-by-key only, and a log you cannot query is a log nobody reads.
Which is also why growth is a real consideration rather than a theoretical one — the value of the trail is in reading it, and a table too large to query has quietly stopped being an audit trail.