~ 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.