Contributing
Workbus is one package, packages/workbus, and one template, templates/factory. To work on it: install, run a board, and run the checks below. Verify a claim with a real run, and break the code a test covers once to see the test fail.
npx pnpm@11.23.0 installcd packages/workbusnpx tsc --noEmit -p . # TS2589 "excessively deep" is known noisenpx vitest run # the workerd suite: the real Ledger, Relay, Mailbox, and Inbox Test Files 10 passed (10) Tests 40 passed (40) Start at 15:21:24 Duration 36.25s (tests 83%, transform 15%, import 2%)Where things are
Section titled “Where things are”Directorypackages/workbus/src
Directoryledger/
- ledger.ts the Ledger:
call(), the alarm, rings, dispatch - ops.ts
op(name, fn, { read }),hooks,Ctx, timers - core.ts principals, callers, access, actors, the log, views
- messages.ts, feed.ts, tasks.ts, grants.ts, schemas.ts, schedules.ts, files.ts, watchers.ts, sync.ts
- archive.ts sealed segments, cold threads, frozen pages
- schema.ts the tables
- ledger.ts the Ledger:
Directoryprotocol/ the routes and their zod schemas, per domain;
rpc.ts(Cap’n Web),mcp.ts(MCP)- …
Directorygateway/ routing,
auth.ts, held waits, SSE- …
Directorysync/ GitHub, Slack, Linear, and Notion providers,
inbox.ts,courier.ts,docfiles.ts,secrets.ts- …
- binding.ts the
Workbusentrypoint and theBoard,Tasks, andClaimcapabilities - relay.ts, mailbox.ts
- index.ts
defineWorkbus
Directorypackages/workbus/cli/ the
wbCLI and its tests- …
Directorypackages/workbus/scripts/ the issuer, benchmarks, and archival checks
- …
Directorypackages/workbus/test/ the workerd suite and the external checks
- …
Directorytemplates/factory/
- …
An operation is a function registered with op(name, fn). It gets a Ctx (the board, the caller, what it may do, and now), runs in one synchronous transaction, and throws a WorkbusError to refuse. A domain that extends messages or reads sets a hooks entry. A route is route({ name, method, path, query | body }) in protocol/, and the Gateway and the Board capability both check inputs against it. The Ledger explains why.
Code is erasable TypeScript only (erasableSyntaxOnly is on): no parameter properties, enums, or namespaces.
Run a board
Section titled “Run a board”cd packages/workbusnode scripts/issuer.mjs key # .issuer.json and .dev.vars, oncenpx wrangler dev --port 8787 --ip 127.0.0.1node scripts/issuer.mjs token jared http://127.0.0.1:8787/b/dev # a person's token, 12 hoursThen use it with the CLI from source:
export WORKBUS_URL=http://127.0.0.1:8787/b/dev WORKBUS_TOKEN=<token>node cli/workbus.mjs whoamiThe checks
Section titled “The checks”| Check | Command | What it covers |
|---|---|---|
| Types | npx tsc --noEmit -p . |
the package |
| The workerd suite | npx vitest run |
the Ledger, Relay, Mailbox, and Inbox on real SQLite storage, with the Gateway in front |
| The CLI | WORKBUS_TEST_ORIGIN=http://127.0.0.1:8787 node --test cli/test/ |
36 end-to-end tests against a running board |
| Webhook verification | node --test test/sync/providers.node-test.ts |
each provider’s signatures and mapping |
| Archival | node scripts/archive-check.mjs http://127.0.0.1:8787 |
every answer the same on a board archived before each request |
| Slack and Linear | test/providers-worker/check.mjs |
signed requests, each delivery twice, recording stand-ins; setup at its top |
| The service binding | test/binding-client/ |
narrowing, pinning, forged props, no principal; setup at its top |
| Cap’n Web | node test/capnweb-client.mjs <board url> <token> |
WebSocket and HTTP batch sessions |
| The Factory’s GitHub sync | templates/factory/test/github-check.mjs |
issues, comments, and replies, with GitHub’s API stood in |
Runs of the first four and the archival check while these docs were written:
$ WORKBUS_TEST_ORIGIN=http://127.0.0.1:8823 node --test cli/test/ℹ tests 36ℹ suites 8ℹ pass 36ℹ fail 0
$ node --test test/sync/providers.node-test.ts✔ Slack: the bot's own reaction is the courier's echo, a person's is an event (0.059708ms)ℹ tests 13ℹ pass 13ℹ fail 0
$ node scripts/archive-check.mjs http://127.0.0.1:8823{ "compared": 317, "coldReads": 304, "differences": 0,The workerd suite gets a fresh issuer key each run and runs with archival off (ARCHIVE: 'off' in vitest.config.ts).
The conformance kit: an outside check
Section titled “The conformance kit: an outside check”The protocol’s conformance kit checks a board as a black box, over HTTP, with no knowledge of how it’s built. Run its conformance --json with BOARD_URL set to a fresh board’s URL and BOARD_TOKEN to a token for it. The board serves its routes at /b/<name>/openapi.json.
On wrangler dev and on the live deployment it passes 85 and skips 6 as an owner, and passes 86 and skips 5 as a member. A change to behavior that the protocol describes should keep it there.
Changing Workbus
Section titled “Changing Workbus”- Prove it with a real run. A claim in a doc, a commit, or a status line is backed by a test or a run you can paste.
- Break it once. A new test fails when you break the code it covers, before you trust it.
- Keep a write one transaction. An operation never awaits. If it needs something in R2, it faults and runs again (see Archival tiers).
- Keep provenance server-side. Who wrote something comes from the verified caller, never from a request body.
- Never commit secrets.
.dev.varsand.issuer*.jsonare gitignored.
AGENTS.md is the same guide for agents working in the repo, and Status is what’s built and how it’s verified.