Goal

One command brings up a local stack able to host integration tests for every later phase: Stalwart OSS 0.16.x @ rev 2add611e (built from source, true OSS feature set), spaces-alpha reference PDS, both as Nix-built OCI containers following the ../rtw/services pattern, orchestrated by devenv up (no Justfile for lifecycle).

Revisions 2026-08-24: SQLite replaces Postgres everywhere (ADR-0002); service containers are built with Nix (rtw pattern) instead of upstream images where possible.

Layout

sovrn/
├── flake.nix              # packages: stalwart, pds-spaces; images: image-stalwart, image-pds
├── nix/
│   ├── lib.nix            # mkImage adapted from rtw (nonroot uid1000, /data,/var/log)
│   ├── pkgs/
│   │   ├── stalwart.nix   # buildRustPackage @ 2add611e; --no-default-features -enterprise
│   │   ├── pds-spaces.nix # buildNpmPackage @atproto/pds@alpha
│   │   └── pds-spaces-service/{package.json,index.mjs}   (+ package-lock.json, one-time)
│   ├── vendor/stalwart-Cargo.lock    # pinned from rev (git-dep outputHashes inline)
│   ├── images/{stalwart,pds}.nix
│   └── scripts/{serve-stalwart.sh,serve-pds-spaces.sh}
├── devenv.nix             # processes: stalwart, pds, health; sovrn-reset helper
└── data/dev/{stalwart,pds}/          # gitignored state

Implementation notes

Stalwart packaging (nix/pkgs/stalwart.nix)

• fetchFromGitHub @ 2add611ee42303c5cef8870b261339a7979e688e (0.16.19), src hash verified.
• buildNoDefaultFeatures = true; buildFeatures = ["sqlite" "rocks"]; — the crate’s DEFAULT features include enterprise; this is how we get a true OSS build.
• nixpkgs’ stalwart-mail is 0.15.5 → disqualified (pre-Registry architecture).
• Cargo.lock vendored at nix/pkgs/stalwart-Cargo.lock; git deps pinned via cargoLock.outputHashes:
  • hickory-dns @ e645086f… = sha256-kF/AyYZH7To15a5dmzGOcTwBIm7rThDRH02C3h81dxQ=
  • opentelemetry-rust @ 274b4d32… = sha256-6qbfRpD3Q0Q942V/MuxFb8hyseIgdXjEMAwyqtIxlRI=

Bootstrap automation (nix/scripts/serve-stalwart.sh)

Reverse-engineered from crates/common/src/manager/boot.rs + crates/jmap/src/registry/mapping/bootstrap.rs: 1. CONFIG_PATH=/data/config.json missing ⇒ server enters bootstrap mode on :8080. 2. Auth via STALWART_RECOVERY_ADMIN=user:pass env (Basic ⇒ AccessToken::new_admin()); dev secret generated once and persisted to /data/service-secret. This same credential model feeds C3. 3. x:Bootstrap/get (capability urn:stalwart:jmap, accountId “a”) returns singleton id. 4. x:Bootstrap/set update patches: sqlite dataStore (/data/stalwart.db), serverHostname=mail.sovrn.test, defaultDomain=sovrn.test, requestTlsCertificate=false, tracer→/data/logs/. 5. Response updated.<id> carries auto-created admin credentials ([email protected]) → written to /data/admin-credentials.txt (chmod 600). 6. Wait for CONFIG_PATH write, restart binary into normal mode.

PDS packaging (nix/pkgs/pds-spaces.nix) — BLOCKED on lockfile

buildNpmPackage over vendored package.json pinning @atproto/[email protected]. npm exits(1) silently during resolution under node 26/npm12 AND node24/npm11 in this environment, and direct npm execution is outside agent permissions. Manual step required:

cd nix/pkgs/pds-spaces-service && npm install --package-lock-only --ignore-scripts

then set npmDepsHash via first-build error. Until then devenv automatically falls back to pulling ghcr.io/bluesky-social/atproto:pds-spaces-alpha.

devenv bring-up (devenv.nix)

• processes.stalwart / processes.pds: ensure-image (podman load, idempotent by ref existence) → podman run --rm foreground, volumes into ./data/dev/*, ENV=development.
• processes.health: polls /healthz/ready (:8080) and describeServer (:3000).
• sovrn-reset helper wipes state + containers.
• Upstream-image fallback wired automatically when the Nix PDS build isn’t available.

Tasks

• [x] flake.nix + nix/lib.nix + image derivations
• [x] stalwart.nix w/ verified hashes; OSS feature set
• [x] serve-stalwart.sh bootstrap flow (reverse-engineered wire format)
• [x] serve-pds-spaces.sh (adapted rtw dev-secret pattern)
• [x] devenv processes + reset helper + .gitignore
• [ ] Stalwart image builds green (in progress: full rust compile running)
• [ ] PDS lockfile generated (manual) → pds-spaces build green
• [ ] devenv up fresh-stack acceptance pass (< 5 min, idempotent second boot)
• [ ] CI headless job

Acceptance criteria

• Fresh clone → devenv up → both services healthy < 5 min, zero manual UI steps; re-run performs no re-bootstrap
• Stalwart answers authenticated Registry requests using persisted service credential; SQLite file present in mount
• PDS describeServer + jetstream WS reachable; test account creatable (invite requirement off in dev)
• No enterprise license key anywhere (grep gate)

Risks this surfaces

• Bootstrap API shape vs source reading (serve-stalwart.sh fails loud if divergent)
• @atproto/pds@alpha npm resolution failure (already observed — documented manual path)
• Rootless podman quirks inside devenv shell