Contributing
A change goes spec first, then the harness, then the server. AGENTS.md says how, and lists the rules an agent building the server is given. Here you’ll set up a clone of the repository, see the checks a change has to meet, and see how a release is made. You don’t need a clone to run Monolith. Getting started starts from its image or its download.
Working from a clone
Section titled “Working from a clone”git clone knotless://chadtmiller.com/monolithThe clone needs:
- Rust, through rustup. The Justfile runs cargo as
rustup run stable cargo. - Node, at the version
.node-versionnames (24). - just, which runs the
Justfile’s targets, and
jqfor the sign-in below. - The harness’s and the pages’ packages, installed once:
cd harness && npm ci && cd ..cd web && npm ci && cd ..- Chromium, but only for the harness’s
--pagesrun andjust look:
cd harness && npx playwright install chromiumjust buildThis builds the authorization pages in web/ into web/dist, then builds
pds into target/release/pds, which embeds them. The
Dockerfile builds the image the same way:
docker build -t monolith .Run a server to try
Section titled “Run a server to try”just dev --seedjust dev builds pds, then runs
harness/dev.mjs. That starts the server at
http://localhost:2583, with its own PLC directory in memory and an
AppView that points nowhere. What the server serves itself, such as
preferences, works, but anything it would forward to an AppView fails. Its
URL is localhost, not an IP address, so a browser will make and use
passkeys there (Passkeys).
pds passkey add gives you a link to open, and the authorization page
then offers the passkey.
Its files go in target/dev/: the data in target/dev/data, the
server’s log in target/dev/server.log, and mail in target/dev/mail.
Each start makes target/dev/ afresh.
It prints where the server and its PLC directory are, the export lines
the CLI needs, and where MCP is, then runs until Ctrl-C.
The flags:
--seedmakesalice.test,bob.testandcarol.test, each with the passwordpassword, if they aren’t there already.--keepcarries on from the last run: the same data, the same rotation key, and the DIDs’ operations, given to the new PLC directory again. Each stop saves them intarget/dev/plc.json.--port <n>listens on another port.-- <command...>runs another server command instead of../target/release/pds serve.
The admin’s password is admin, and handles end in .test.
Put target/release/pds on your PATH and paste the export lines it
printed. Then you’re alice.test:
export PDS_URL=http://localhost:2583 PDS_ADMIN_PASSWORD=adminexport PDS_TOKEN=$(pds server create-session --identifier alice.test --password password | jq -r .accessJwt)pds repo create-record --collection com.example.note --record '{"text":"hi"}'pds repo list-records --collection com.example.note --limit 5just dev sets no SMTP server, so no mail leaves the machine. Each email
the server would send, such as a confirmation or password reset token,
goes to target/dev/mail/ as its own JSON file, {"to", "kind", "token"} (Email).
Ctrl-C stops it. The server shuts down and the PLC directory’s operations
get saved, so just dev --keep carries on from there.
The just targets
Section titled “The just targets”The Justfile holds them:
just test # the crates' own testsjust quick # a short harness run of each kind, for while workingjust code # the code gates (below)just perf # the performance stepjust gates # the code gates, the tests and the harness runsjust nightly # the long crash runs, then the performance stepjust look consent # an authorization page drawn, desktop light and phone dark, in target/lookjust dev --seed # a server to try by hand (above)just docs-site # the documentation site, served while you write (below)just docs-deploy # the documentation site, deployed by its owner (below)While you work, run just quick by itself, with nothing else running.
Push the branch and open the pull early, since the gates run on the
runner.
The gates
Section titled “The gates”just gates runs the code gates, the tests and the harness side by side
(harness/gates.mjs). The harness does several
runs at once (GATES_JOBS sets how many), and one of them is a short run
with the server killed every 15 steps.
The gates workflow
(.knotless/workflows/gates.yml)
runs them on every pull into main, and on every push to it, that changes
what they check. That’s the server’s source and build, the pages it
embeds (web/), the data and lexicons it reads from spec/, and the
harness the gates run. A change that touches none of those, such as the
README, docs/, the spec’s prose, the benchmark or the compatibility
check, is filed as skipped, and the merge queue takes that as passing.
Nightly
Section titled “Nightly”just nightly runs the long crash runs, which kill the server every 15
steps over runs of 1000. Then it runs the performance step on its own. That
measures the server’s speed against the reference’s and against its
baseline, and what it holds once subscribers have come and gone, with its
whole output in the log. Last comes the scale run, which measures the
server’s starts.
The nightly workflow
(.knotless/workflows/nightly.yml)
runs them on main’s tip every night at 10:00 UTC. The owner can also ask
for it on main or on a branch, for example for a pull that changes how
the server stores its data:
knotless run rerun --ref main --workflow nightlyknotless run rerun --ref refs/heads/<branch> --workflow nightlyThe code gates
Section titled “The code gates”Besides the harness and the tests, the source itself has to pass these,
the code gates. They’re part of what just gates and the gates
workflow run. just code runs only them, and so does node gates.mjs code
in harness/, with CARGO naming the cargo to run.
cargo fmt --all --check: the code is formatted the way rustfmt formats it.cargo clippy --workspace --all-targets -- -D warnings: there’s no clippy or rustc warning in any target.cargo deny check(deny.toml): every dependency is under a licence on the allowlist, and they’re all permissive. There’s no advisory from the RustSec database, unmaintained and unsound crates included, no yanked version and no wildcard version. Crates come only from crates.io.#![forbid(unsafe_code)]sits at the root of every crate and each of its targets, andharness/code.mjschecks it. Anything that needs the operating system goes through a crate that wraps it safely.- Every citation of the spec in the harness, such as
(spec/LIFECYCLE.md, "deactivateAccount"), names a section its page has. Every section of every page is cited by some check, except the few thatharness/spec-coverage.mjslists as unchecked, each with why (spec/PDS.md, “How it is checked”). Thecitationsworkflow runs only this check on every pull that changes a spec page or the harness. So a pull of the spec’s prose, which the gates skip, still has to pass it. - The pages’ source (web/AGENTS.md) has its own
checks. Each component uses only its own layer and those below it
(
harness/layers.mjs), and every text colour reaches 4.5:1 on what it’s drawn on in light and dark (harness/contrast.mjs).svelte-checkgives no warning.
The pages, by eye
Section titled “The pages, by eye”just look draws an authorization page in a browser, in any state, and
saves pictures of it in target/look for you to open:
just look consent --scope 'atproto repo:*'The documentation site
Section titled “The documentation site”docs-site/ builds the site from these guides, the spec’s pages, the
lexicons, and compat/ and bench/. Its landing page,
docs-site/src/pages/index.astro, holds the photograph, a headline, one
sentence and two buttons. Its words follow
the landing skill, and its one
figure is read from the last benchmark, bench/results.json. Build it
with:
cd docs-site && npm ci && npm run buildThe build fails on a link to a file or heading that isn’t there, a method
spec/PDS.md lists under no page, or a variable the spec names in no
table. The docs workflow builds it on each pull that
changes what it’s made from. just docs-site serves it at
http://localhost:4321/ while you write.
The site is at https://chadtmiller-com.knotless.page/monolith/. The docs
workflow deploys it on each push to main that changes what it’s made
from, signed in with the owner’s app password (RELEASE_PASSWORD). The
owner can also deploy it by hand after knotless login:
just docs-deployReleases
Section titled “Releases”A pull that changes what people running or calling the server see (its
behaviour, its settings, its CLI, its image) adds a change file to
.changeset/. knope document-change asks for the bump (patch,
minor or major) and a summary, or you can write it by hand like the
ones already there. Its heading and text become that change’s entry in
CHANGELOG.md, so write them for those readers rather than for us. A
change they don’t see, such as a test or the harness, adds none.
A release is main with the workspace’s version raised and tagged
v<version>. Two workflows make it:
release-pull.ymlruns each day whenmainhas change files. It runsknope releaseonmain’s tip, which raises the version, writes the version’s section ofCHANGELOG.mdand removes the change files. The result is the one open pull,Release <version>, kept up to date as change files land. Queueing that pull is the release. On 0.x,minorraises the minor version, where knope by itself would raise the patch.knotless run rerun knotless://chadtmiller.com/monolith --ref refs/heads/main --workflow release-pullmakes the pull at once.release.ymlruns once that pull lands and the gates pass at it. It builds the pages andpdsthe way the Dockerfile does, and makes the image from the binary with no container engine (.knotless/image.sh, since the runner’s jobs have none). It publishes both, each with the version’s changelog as its notes: the image as the packagemonolith, andpds-<version>-x86_64-linux.tar.gzwith its.sha256as the packagepds. Then it tags the commit. When you ask for it on a branch, it builds both and publishes nothing.
Both run on runner.knotless.dev with RELEASE_PASSWORD, an app password
of the owner’s, sealed to it only for pushes to main.
Once the release is tagged, write harness/upgrade/ again with its binary
and commit it:
git worktree add ../pds-release v<version> && (cd ../pds-release/web && npm ci) && (cd ../pds-release && just build)cd harness && node compare.mjs --upgrade-write -- ../../pds-release/target/release/pds serveThat binary is then the previous version every later build must start on
(compare.mjs --upgrade, in Comparing).