chadtmiller.com/monolith
An atproto PDS
Working on Monolith
For every agent working here: CLAUDE.md is this file, imported. What the
project is, and what is built, is in README.md; what is not yet built is
its "Known gaps". How the server is run, called, deployed, operated and
checked is in the guides in docs/guide/.
How a change is made
The PDS is built from its specification, and checked against the reference PDS, so a change goes in this order:
-
The spec. What the server does is in
spec/PDS.mdand the page of each area it links (spec/REPO.md,spec/SYNC.md, ...), its MCP tools and CLI commands inspec/COMMANDS.md, and the methods themselves in the lexicons underspec/lexicons. A change in behaviour is written there first, as what is, not as a plan. A new area gets a page of its own, linked fromspec/PDS.md. -
The harness.
harness/compare.mjsgets a check for it, in the module of its area underharness/checks/(a new area's module, and its steps incompare.mjs's list): against the reference where the reference can say, and against the spec where it cannot. Every random draw comes fromharness/lib/random.mjs, so a seed makes the same requests every run. A check is made stricter or fixed, never loosened so that a server passes. Run against the server as it was, the new check must fail. A check cites the section it holds the server to, as(spec/LIFECYCLE.md, "deactivateAccount")(spec/PDS.md, "How it is checked"); renaming a heading moves its citations with it. A check names no implementation: what it may take of the server beyond the protocol it asksharness/lib/server.mjs, and another PDS joins the compatibility check ascompat/README.md, "Adding an implementation", says, leaving Monolith's runs as they were. -
The server.
crates/, andweb/for the authorization pages (web/AGENTS.md), are built fromspec/alone, by an agent given these rules:- change only the crates named for the change; a new crate goes in
crates/<name>, named as its directory, with its versions in the rootCargo.toml's[workspace.dependencies]; - a new area's methods go in a module of their own in
pds-server, named in itsAREASinlib.rs; - read no source of the reference PDS (the
@atproto/*packages underharness/node_modules, its pages'@atproto/oauth-provider-uiamong them), of an atproto or MCP SDK, or of the MCP conformance suite;harness/compare.mjsand its modules may be read, to see what is checked; - add no atproto or MCP crates;
- where the spec or the harness seems wrong, stop and say why, rather than work around it.
The whole of
crates/can be built again from nothing this way, to see whether the spec is enough: an agent given an emptycrates/and no history. There, where the spec is silent and the harness settles it, it follows the harness and lists each such gap, which then becomes a spec change and a harness check. - change only the crates named for the change; a new crate goes in
-
Proof that the check bites. Plant the bug the new check is for in the server, see the harness fail, and put the server back.
-
The gates, on the runner. Not on this machine: several agents running the harness here at once have brought it down. Push the branch and open the pull early; the
gatesworkflow runsjust gateson each push to it. Read what it says withknotless run list knotless://chadtmiller.com/monolith --pull <uri> --wait <secs> --log. While working,just quickhere, alone, and ofcargo testonly the tests of what was changed, by name: the whole of it takes a quarter of an hour on this machine when others use it, and under a minute on the runner, so the whole suite is run by a push. The runner is one machine: pushes wait their turn, and a benchmark asked for beside the gates slows both. What is compiled for macOS alone is run here, and for Linux alone there. When a gate fails in a way its log does not explain, run that one run here, alone. A change to how the server stores or syncs, or to its speed, runsjust nightlyhere too: the long crash runs and the performance step, which otherwise only thenightlyworkflow runs, onmain, after it merges.
A change to how the server is run, deployed, called or checked updates its
guide in docs/guide/ in the same pull, as a change in behaviour updates
the spec.
A change that those who run the server or call it see adds a change file
to .changeset/ in the same pull, from which the next release's
CHANGELOG.md is written (docs/guide/contributing.md, "Releases").
The README says what is built, not how it came to be: no history, plans or
sessions in it, in docs/, or in the spec.
Tools
- Cargo through rustup:
rustup run stable cargo(the Justfile'scargo). - Node is the version
.node-versionnames;cd harness && npm cionce, andnpx playwright install chromiumfor--pagesandjust look. cd web && npm cionce:just buildbuildsweb/beforepds, which embeds it.- The documentation site:
cd docs-site && npm cionce, thennpm run build, which fails on a link to a file or heading that is not there, a methodspec/PDS.mdlists under no page, or a variable the spec names in no table of them;just docs-siteserves it while writing. Thedocsworkflow builds it on each pull, and deploys it on each push tomainthat changes it;just docs-deploydeploys it by hand. - The spaces run (
harness/spaces/compare.mjs,spec/SPACES.md) checks the server against the pinned spaces alpha of the reference, with its own packages:cd harness/spaces && npm cionce;pin-alpha.shre-pins it.
Branches and pulls
The repository is knotless://chadtmiller.com/monolith. Work goes on a
branch, and into main by a pull with review.knotless.dev as reviewer;
main takes a pull only through the merge queue, once that review has
passed. .knotless/review.md is what the reviewer checks. A change that
needs another not yet merged is a pull stacked on that one's branch, and is
retargeted to main once it merges.