pithy add auditNo prerequisites, no secrets, no account. It is one of the few capabilities in the kit that composes on its own.
What lands in your repo
apps/<worker>/pithy.config.ts gains the registration:
audit({
database: "DB",
basePath: "/audit",
}),apps/<worker>/wrangler.jsonc gains one binding, in every environment stanza: the DB it writes to. If your project already composes anything else, that binding is already there and nothing changes.
Two more are optional, so pithy add writes neither. AUDIT_CHECKPOINTS is the R2 bucket the hash chain’s checkpoints go to, and AUDIT_CHECKPOINT the checkpoint Workflow that writes them, hosted by a prebuilt audit Worker that pithy deploy ships. pithy upgrade writes the optional bindings the composed Worker declares, and pithy provision creates the bucket, <project>-<env>-audit-checkpoints. Until the bucket exists every event is still recorded and chained, and a verify checks the links alone and says so. Once it does, lock it with pithy audit lock --env <name>.
The retention prune is a third, and it is yours to bind. AUDIT_PRUNE is a Workflow your own Worker exports and binds in its workflows, beside the 0 2 * * * cron, because only that Worker resolves the retention block it reads. pithy add writes none of it, and until it is bound nothing is pruned. Retention has the class to export.
Two queues appear only when you ship the trail. Declare a sink under sinks and the Worker binds AUDIT_SHIP, with its queues.consumers entry and dead-letter queue, and AUDIT_SHIP_DLQ; pithy upgrade writes both and pithy provision creates them. A Worker that ships also composes secrets, where each sink’s token is read. Cloudflare Queues needs the Workers Paid plan, so a project with no sink binds no queue. Shipping the trail has the setup.
What runs
Six migrations, and two tables: pithy_audit_events, the trail, and pithy_audit_sinks, shipping’s delivery state. 0001_init creates the trail. 0002_actor_kind adds actor_kind, which names the kind of client behind a control-plane event, and marks a user event agent when an MCP client acted as that user. 0003_call_index and 0004_request_index add the two indexes a management client’s reads stand on: one over action, connection and time, one over the request id. 0005_chain adds the four chain columns and a unique index per kind of chain. It back-fills nothing: a row already in the table stays marked as before the chain. 0006_sinks creates pithy_audit_sinks, one row per declared sink, which the shipping health keys read. Nothing in it is the trail.
It is one Zod object — the whole table, with every field described. The app shape and the SQLite row shape are derived from the same definition, and every conversion between them goes through a codec.
The three config options
| Option | Default | What it decides |
|---|---|---|
database | DB | The D1 binding the table and its migrations target. KV is not an option — an audit log is a query workload and KV is get-by-key only |
basePath | /audit | Where the control-plane routes that read the trail mount. Reads only: the trail is append-only and this surface never writes |
sinks | {} | Where the trail is shipped as it is written, by name. Declared here and nowhere else. Empty ships nothing and binds no queue. pithy add does not scaffold it |
Point database at a separate binding if you want the trail in its own D1. Two Workers that both declare that binding still share one database, which is what lets a multi-Worker project keep one trail. A Worker that lists the binding in ownBindings gets a database of its own, and with it a trail of its own, checkpointed by an audit host of its own, <project>-<env>-<worker>---audit, into a bucket of its own. So it lists AUDIT_CHECKPOINTS in ownBindings too: owning one of the pair and sharing the other is refused by pithy provision, pithy deploy and pithy dev, naming the binding to add (a Worker’s own kit hosts).
pithy add records nothing
No pithy add writes a row, the first pithy add audit included. An add writes config and local D1 and changes nothing shared, so its capability/added event goes to dev, whose emitter is inert, and it reads no Cloudflare credentials to send it. What the CLI records is what reaches an account: a deploy, a provision, a deployed environment’s schema reset, a feature teardown, a pithy remove --drop against a deployed environment.
Nothing else has to change
This is the part worth stating, because it is unusual. No capability needs rewiring, and no route needs editing.
The event contract lives in @pithy-sh/core, so every capability already calls c.var.emit(...). Before you composed audit, that call resolved to a no-op recorder. After, it resolves to this package. The capabilities that were already emitting start writing rows immediately:
| Capability | Records |
|---|---|
auth | Sign-in, token refresh, device revocation, and every in-Worker MCP tool call |
secrets | Every set, rotation and removal — naming the secret and the environments reached, never the value |
payments | Entitlement grants and revocations |
consent | Every grant and withdrawal, and a visitor merged into an account at sign-in |
| The CLI | Deploys, a deployed environment’s schema resets, token mints, feature teardowns, and capability removals that drop a deployed environment’s tables |
The consequence: composing audit late gives you a trail that starts today. There is no back-fill, because there is nothing to back-fill from.
Emitting your own events
One call, from any route:
await c.var.emit({
action: "app/report_exported",
outcome: "success",
actorType: "user",
actorId: c.var.auth.userId,
tenant: organizationId,
});action is namespaced by convention — your own capability’s name as the domain, so your events and the kit’s cannot collide. outcome is recorded truthfully on failure too: an attempt that was refused is often the row you most want.
The project, environment and Worker are stamped for you by the recorder, from that Worker’s own vars. You cannot set them, which is what makes them trustworthy.
Reading the trail
Two ways, and they are for different people.
SQL. The table is in your database, so it joins against your own tables with no export step. A staff member’s id resolves to a name because your users table is in the same query.
The control-plane surface. Three scopes — read the events, read one event’s detail, and verify or export the hash chain — all default-denied until a management client is connected and granted them. Reading an audit trail is itself a privileged act, and it is audited: a management client walking your event log leaves rows saying so.
Check it worked
pithy doctor reports audit under the Worker’s health. Sign in locally and the first row appears — pithy dev, then a query against pithy_audit_events, is the whole verification. For every environment but dev, pithy doctor also asks the account whether the checkpoint bucket exists and is locked, and names the command that fixes it when it is not.