~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
109 lines · 6.0 KB Raw History
# 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.