CI

ci.d/10-gate is the only CI this repo has. It runs on every push to the amadan remote, and it is the same script you can run locally — one definition rather than two that drift.

It requires a Rust toolchain with the wasm32-unknown-unknown target and the rustfmt component, Go with CGO_ENABLED=0, and Node with npm on PATH. The gate sources ~/.cargo/env itself and checks every tool up front, so a missing dependency fails on the first line with its own name rather than fifty lines in as cargo: command not found.

The runner clones a fresh worktree per branch, so fixtures/node_modules never carries over — the gate runs npm ci itself, against fixtures/package-lock.json, so the installed yjs is always exactly 13.6.27 rather than whatever a bare npm install would resolve.

Known tradeoff: that npm ci needs the npm registry reachable at run time. It is the right fix for the fresh-worktree-per-branch problem above, and the lockfile is committed so the version resolved never drifts, but it does mean the gate is not fully offline-capable the way the Rust and Go steps are once their caches are warm. If the registry is ever unreachable from the runner, that is the failure this line produces — not a bug in the gate itself.

The runner

Jobs are claimed by an amadan runner on the machine that has one. Two things about it were wrong when this repo was created, and both fail silently rather than loudly:

• The runner must be told to serve this repo. amadan runner -repo … is an allowlist. A repo nobody listed gets amadan ci status exit 3 forever — "no status recorded", which reads like the gate has not run yet rather than like nothing will ever run it.
• The runner's PATH is the systemd unit's, not your shell's. ~/.cargo/bin is not on it by default.

Both were fixed on DOCS-T1 on 2026-08-30 by editing ~/.config/systemd/user/amadan-runner.service and restarting. A restart abandons any job already running, so check it is idle first.

The gate fails if internal/core/testdata/docs_core.wasm differs from a fresh build, because go:embed will otherwise embed a stale module and the tests will pass against it.

It also fails if regenerating the Yjs fixtures changes them. Fixtures are the wire contract, not an output: a deliberate rule change regenerates them in the same commit as the change.

The app, not just the core

go vet ./... and go test ./... already cover cmd/docs and internal/docs — the rastrillo app built on top of internal/core — but neither one proves the app actually links into a runnable binary. The gate also runs CGO_ENABLED=0 go build ./... for that.

There used to be a further step here: a separate -tags release build, run with -dev-auth on its command line, asserting it refused to start — proving a release binary had no code path that could turn a development-only stand-in identity on. That identity (internal/docs/devauth.go) had zero readers once rastrillo/auth's RequireSession started guarding every document route unconditionally (a fix round on Task 1, once real per-person sign-in existed), so it was deleted rather than kept as dead code — and the release build tag it was the only user of went with it. There is no release/non-release distinction left for this gate to hold apart; go test covers the fail-closed properties that matter now (TestNewRefusesMissingInstanceKeyOutsideDevelopment, TestNewRefusesMissingMailOutsideDevelopment, TestSignInRequiredForEverything — all internal/docs/auth_test.go). scripts/run-dev.sh builds and runs the ordinary binary with -env development, a fixed port, and a scratch database — one command to see the app in a browser, signed in for real via a magic link logged to the terminal instead of mailed.

The embedded WASM is built on Linux amd64 using fixed /work, /usr/local/cargo and /usr/local/rustup paths. Rust/Cargo's crate identities otherwise change code ordering across hosts, even with remapped source paths. Linux amd64 uses unprivileged bubblewrap when available; other hosts use the pinned Rust Docker image. Install Docker on development Macs. Both the artifact builder and containment tests use this path; the freshness comparison remains byte-for-byte. Docker caches and writable targets are separate from source.