chadtmiller.com/monolith
An atproto PDS
0
0
# 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:
1. **The spec.** What the server does is in `spec/PDS.md` and the page of
each area it links (`spec/REPO.md`, `spec/SYNC.md`, ...), its MCP tools
and CLI commands in `spec/COMMANDS.md`, and the methods themselves in the
lexicons under `spec/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 from `spec/PDS.md`.
2. **The harness.** `harness/compare.mjs` gets a check for it, in the module
of its area under `harness/checks/` (a new area's module, and its steps
in `compare.mjs`'s list): against the reference where the reference can
say, and against the spec where it cannot. Every random draw comes from
`harness/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
asks `harness/lib/server.mjs`, and another PDS joins the compatibility
check as `compat/README.md`, "Adding an implementation", says, leaving
Monolith's runs as they were.
3. **The server.** `crates/`, and `web/` for the authorization pages
(`web/AGENTS.md`), are built from `spec/` 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 root
`Cargo.toml`'s `[workspace.dependencies]`;
- a new area's methods go in a module of their own in `pds-server`,
named in its `AREAS` in `lib.rs`;
- read no source of the reference PDS (the `@atproto/*` packages under
`harness/node_modules`, its pages' `@atproto/oauth-provider-ui`
among them), of an atproto or MCP SDK, or of the MCP conformance
suite; `harness/compare.mjs` and 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 empty `crates/` 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.
4. **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.
5. **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 `gates` workflow runs `just gates` on each
push to it. Read what it says with `knotless run list
knotless://chadtmiller.com/monolith --pull <uri> --wait <secs> --log`.
While working, `just quick` here, alone, and of `cargo test` only 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, runs `just nightly` here too:
the long crash runs and the performance step, which otherwise only the
`nightly` workflow runs, on `main`, 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's `cargo`).
- Node is the version `.node-version` names; `cd harness && npm ci` once,
and `npx playwright install chromium` for `--pages` and `just look`.
- `cd web && npm ci` once: `just build` builds `web/` before `pds`, which
embeds it.
- The documentation site: `cd docs-site && npm ci` once, then `npm run
build`, which fails on a link to a file or heading that is not there, a
method `spec/PDS.md` lists under no page, or a variable the spec names in
no table of them; `just docs-site` serves it while writing. The `docs`
workflow builds it on each pull, and deploys it on each push to `main`
that changes it; `just docs-deploy` deploys 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 ci` once; `pin-alpha.sh` re-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.