[CHORE] Integration head: merge the programme, then audit the API and recount the trackers

.config/nextest.toml

@@ -21,17 +21,51 @@ slow-timeout = { period = "60s", terminate-after = 3 }
 [profile.ci.junit]
 path = "junit.xml"
 
-# The container group is **empty as of `S-C59`**, and the declaration stays.
+# The container group holds the adapter suites that stand up a real backing service.
 #
 # It existed for the retired Salvo auth crate, whose integration tests spun up shared Postgres
 # and Valkey containers and shared a tracing `Once` — running them concurrently was the main
-# flakiness source, so the group was pinned to one thread with retries as the backstop. The
-# rebuilt server has no container test at all: every port has a deterministic in-memory adapter
-# and Kynos's `TestClient` drives a built service in-process, which is why `mise run test-rust`
-# now needs no podman for anything above the storage ports.
+# flakiness source, so the group was pinned to one thread with retries as the backstop. It was
+# then empty for the length of the Kynos rebuild, kept rather than deleted because the first
+# real adapter would need exactly it and rediscovering the one-thread rule by watching CI flake
+# is the expensive way to learn it. Every port still has a deterministic in-memory adapter and
+# Kynos's `TestClient` drives a built service in-process, which is why `mise run test-rust` needs
+# no podman — the container suites below are env-gated and pass as skipped without their variable.
 #
-# The group is kept rather than deleted because the first Postgres or Valkey *adapter* will need
-# exactly it, and rediscovering the one-thread rule by watching CI flake is the expensive way to
-# learn it. An empty test group costs nothing.
+# The Postgres adapters (#402) are that first adapter. Every container-backed case lives under a
+# test module named `postgres_conformance`, so the filterset below is mechanical rather than a
+# list somebody has to remember to extend — a new port's suite joins the group by being named
+# like the others. Each of those cases starts its **own** container (nextest runs a process per
+# test, so a shared one would buy nothing), which is why one thread matters: five Postgres
+# instances racing to bind ports and warm up is the flakiness the group exists to prevent.
+#
+# **These tests skip themselves without `CAPSULE_TEST_POSTGRES=1`**, printing one line each that
+# says so — see `capsule_server::postgres::testing`. The default `cargo nextest run` is green on
+# a machine with no container runtime, which is the acceptance gap design/module-map.md sets.
+#
+# `capsule-server/tests/valkey.rs` (#403) is the second, and joins by binary rather than by test
+# name because the whole binary is container-backed. It runs the store and counter conformance
+# suites against a `valkey/valkey` container when `CAPSULE_TEST_VALKEY=1`. One thread, for the
+# same reason and one more: each test starts its own container and the eviction view is one
+# global sorted set.
 [test-groups.containers]
 max-threads = 1
+
+[[profile.default.overrides]]
+filter = 'test(postgres_conformance)'
+test-group = 'containers'
+
+[[profile.ci.overrides]]
+filter = 'test(postgres_conformance)'
+test-group = 'containers'
+# A container that loses a port race or is still warming up is the transient failure the `ci`
+# profile's retries exist for; nextest reports flaky separately from failed, so a retry that
+# succeeds is still visible.
+
+[[profile.default.overrides]]
+filter = 'package(capsule-server) and binary(valkey)'
+test-group = 'containers'
+
+[[profile.ci.overrides]]
+filter = 'package(capsule-server) and binary(valkey)'
+test-group = 'containers'

.github/dependabot.yml

@@ -11,16 +11,22 @@ updates:
     directory: "/capsule-web"
     schedule:
       interval: "weekly"
+  # The workspace root: `Cargo.toml` and `Cargo.lock` live here and cover every member. This
+  # pointed at `/capsule-api` until the Salvo tree moved to `legacy-review/` in `S-C59`, so it
+  # had been watching a directory that no longer exists — and therefore watching nothing.
   - package-ecosystem: "cargo"
-    directory: "/capsule-api"
-    schedule:
-      interval: "weekly"
-  - package-ecosystem: "docker"
-    directory: "/capsule-api"
+    directory: "/"
     schedule:
       interval: "weekly"
+  # The server's local service images (Postgres, Valkey). Same story: `/capsule-api/compose.yaml`
+  # went with the Salvo tree, and `capsule-server/compose.yaml` is the live file (issue #401).
+  #
+  # There is no `docker` entry any more. It watched `/capsule-api/Containerfile`, and no
+  # Containerfile exists anywhere in the active tree — an OCI image for the rebuilt server is
+  # not written yet, and an ecosystem pointed at an absent file is a permanent dashboard error
+  # rather than a dependency update. Add it back in the change that adds the Containerfile.
   - package-ecosystem: "docker-compose"
-    directory: "/capsule-api"
+    directory: "/capsule-server"
     schedule:
       interval: "weekly"
   - package-ecosystem: "github-actions"

.github/workflows/build-ios.yml

@@ -53,13 +53,6 @@ jobs:
           working_directory: capsule-swift
           install_args: tuist xcbeautify
 
-      # capsule-sdk's build script compiles the capsule.sync.v1 proto with
-      # prost-build, which shells out to protoc; the macOS image does not carry it.
-      - name: Install protoc
-        uses: arduino/setup-protoc@v3
-        with:
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
-
       - name: Build Rust FFI xcframework
         run: bash capsule-swift/Scripts/build-rust-ffi.sh
 
@@ -123,13 +116,6 @@ jobs:
           working_directory: capsule-swift
           install_args: tuist xcbeautify
 
-      # capsule-sdk's build script compiles the capsule.sync.v1 proto with
-      # prost-build, which shells out to protoc; the macOS image does not carry it.
-      - name: Install protoc
-        uses: arduino/setup-protoc@v3
-        with:
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
-
       - name: Build Rust FFI xcframework
         run: bash capsule-swift/Scripts/build-rust-ffi.sh
 

.github/workflows/ci.yml

@@ -51,20 +51,51 @@ jobs:
               - 'hk.pkl'
               - '.cargo/**'
               - 'capsule-server/**'
-              - 'capsule-wire/**'
               - 'capsule-i18n/**'
               - 'capsule-cli/**'
+              - 'capsule-e2e/**'
               - 'capsule-core/**'
               - 'capsule-sdk/**'
+              - 'capsule-core-ffi/**'
+              - 'capsule-wasm/**'
               - 'xtask/**'
+              # `check-rust` reads the catalogs directly: `i18n-check` and
+              # `i18n-guard` are `cargo run -p xtask -- i18n …` over `locales/`,
+              # so a catalog-only change must still pay the Rust gate. The
+              # `swift` filter already lists it for the same reason.
+              #
+              # `i18n-check` compares `locales/` against its *generated* outputs,
+              # and drift is drift whichever side moved — a hand-edit to a
+              # generated catalog is the case it exists to catch. `check-rust` is
+              # the only task that runs it and the `rust` job is the only job that
+              # runs `check-rust`, so these four globs are what makes the CI gate
+              # at least as wide as the local one — hk.pkl's `i18n-check` step
+              # lists the same generated targets (the two remaining entries of
+              # that glob, `capsule-i18n/src/**` and `xtask/src/i18n.rs`, are
+              # already covered here by `capsule-i18n/**` and `xtask/**`). Keep
+              # the two in step.
+              - 'locales/**'
+              - 'capsule-web/src/i18n/messages/**'
+              - 'capsule-swift/Generated/**'
+              - 'capsule-android/src/androidMain/res/values*/strings.xml'
               - '.github/workflows/ci.yml'
             web:
               - 'capsule-web/**'
               - 'mise.toml'
               - 'mise-tasks/**'
               - '.github/workflows/ci.yml'
+            # Every artifact the docs build reads, not just `capsule-docs/**` — the
+            # generator turns two committed description artifacts into the `/reference/`
+            # pages, so a filter that names only the site lets a stale reference page
+            # publish on a change to the surface it describes. See
+            # design/developer-docs.md, "Artifacts cross the boundary, not toolchains".
             docs:
               - 'capsule-docs/**'
+              - 'capsule-cli/cli-surface.json'
+              - 'capsule-server/openapi.json'
+              # `capsule-docs/biome.jsonc` extends the root one, so a change there can fail
+              # this job's format and lint steps from outside `capsule-docs/**`.
+              - 'biome.jsonc'
               - 'mise.toml'
               - 'mise-tasks/**'
               - '.github/workflows/ci.yml'
@@ -81,11 +112,32 @@ jobs:
               - 'capsule-docs/endpoint-census-allowlist.txt'
               - 'capsule-docs/planned-modules.txt'
               - 'capsule-server/openapi.json'
+              # No check reads this one today; it is here because the cross-links check
+              # resolves any repo-relative path a document names, and the reference prose
+              # now names this artifact. Cheap: the job installs nothing.
+              - 'capsule-cli/cli-surface.json'
               - 'capsule-*/src/**'
               - '**/*.md'
               - '**/*.mdx'
               - 'LICENSE'
               - 'NOTICE'
+              # For the `roadmap` check, which arrives with `#422` together with
+              # the ROADMAP.md it reads — neither is in the tree at this commit.
+              # It will resolve that file's rows against the manifests below,
+              # which declare what actually exists, so a pull request that adds
+              # or removes a package without touching Markdown must still run the
+              # job — otherwise the gate would be advisory for exactly the change
+              # it exists to catch. Listed ahead of the check so the filter is
+              # correct the moment `#422` lands; until then these globs only
+              # widen when `docs-truth` runs, which is harmless.
+              - 'Cargo.toml'
+              - 'settings.gradle.kts'
+              - 'capsule-swift/Project.swift'
+              - '**/Package.swift'
+              - '**/package.json'
+              - '**/pyproject.toml'
+              - '.gitmodules'
+              - 'legacy-review/**'
               - 'mise.toml'
               - '.github/workflows/ci.yml'
             vision:
@@ -240,13 +292,6 @@ jobs:
             tier2: true
     steps:
       - uses: actions/checkout@v4
-      # capsule-sdk's build script compiles the capsule.sync.v1 proto with
-      # prost-build, which shells out to protoc. The hosted images do not carry
-      # it, so every leg of this matrix fails in the SDK build script without it.
-      - name: Install protoc
-        uses: arduino/setup-protoc@v3
-        with:
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
       - name: Install Rust toolchain
         run: |
           rustup toolchain install
@@ -470,7 +515,11 @@ jobs:
 
   # Single aggregated status check. Mark THIS ("CI / required") as the required
   # check in branch protection — path-filtered jobs report "skipped", which this
-  # treats as a pass. rust-test is non-blocking and intentionally excluded.
+  # treats as a pass. Every job in `needs` is verified below: the loop covers the
+  # eleven gates (`rust-test` included — it became blocking with `S-C59`, see the
+  # note on that job), and `changes` is checked ahead of it under a stricter rule,
+  # because "skipped" is only trustworthy when the filter that skipped it ran.
+  # A job in `needs` but absent from both checks is a gate that cannot fail.
   required:
     name: required
     if: always()
@@ -479,7 +528,21 @@ jobs:
     steps:
       - name: Verify required jobs succeeded
         run: |
-          for r in "${{ needs.commit-lint.result }}" "${{ needs.rust.result }}" "${{ needs.rust-cross.result }}" \
+          # `changes` must have SUCCEEDED, not merely "not failed". Every filtered
+          # job's `if:` reads needs.changes.outputs.*; if that job dies (a checkout
+          # hiccup, a paths-filter error) those outputs are empty, so every gate
+          # evaluates false and reports "skipped" — and `if: always()` still runs
+          # this one. Treating those skips as passes would green-light a merge with
+          # zero toolchain gates executed, which is the failure mode this whole job
+          # exists to prevent. It is the one `needs` entry that cannot be skipped:
+          # unlike `commit-lint` (push events) or the filtered gates, it has no `if:`.
+          if [ "${{ needs.changes.result }}" != "success" ]; then
+            echo "The path-filter job did not succeed (result: ${{ needs.changes.result }})."
+            echo "Every filtered gate would report skipped, so this aggregate proves nothing."
+            exit 1
+          fi
+          for r in "${{ needs.commit-lint.result }}" "${{ needs.rust.result }}" \
+                   "${{ needs.rust-test.result }}" "${{ needs.rust-cross.result }}" \
                    "${{ needs.web.result }}" \
                    "${{ needs.docs.result }}" "${{ needs.docs-truth.result }}" "${{ needs.vision.result }}" \
                    "${{ needs.markdown.result }}" "${{ needs.kotlin.result }}" "${{ needs.swift.result }}"; do

.github/workflows/release.yml

@@ -1,9 +1,16 @@
 name: Release
 
 # Fires when a release commit (`chore(release): vX.Y.Z`, produced by prepare-release.yml
-# and merged via its PR) lands on master. It builds the `capsule` CLI for each target and
-# publishes a GitHub Release. `gh release create` also creates the tag, so the whole
-# build+publish happens in this one run — no PAT or tag-push re-trigger needed.
+# and merged via its PR) lands on master. It builds the `capsule` CLI and the `capsule-server`
+# binary for each target and publishes a GitHub Release. `gh release create` also creates the
+# tag, so the whole build+publish happens in this one run — no PAT or tag-push re-trigger
+# needed.
+#
+# Both binaries ride in the one per-target archive rather than two: an operator running a
+# self-hosted deployment wants the server and the CLI that talks to it at the same version, and
+# two downloads is two chances to mix versions. The server is Unix-only here — Windows is
+# already best-effort for the CLI, and adding a server build to a job that is allowed to fail
+# would make "did the Windows CLI ship" harder to answer, not easier.
 on:
   push:
     branches: [master]
@@ -41,7 +48,7 @@ jobs:
           fi
 
   build:
-    name: Build capsule (${{ matrix.target }})
+    name: Build binaries (${{ matrix.target }})
     needs: detect
     if: ${{ needs.detect.outputs.release == 'true' }}
     runs-on: ${{ matrix.os }}
@@ -74,8 +81,11 @@ jobs:
         uses: Swatinem/rust-cache@v2
         with:
           key: release-${{ matrix.target }}
-      - name: Build release binary
+      - name: Build the CLI
         run: cargo build -p capsule-cli --release --target ${{ matrix.target }}
+      - name: Build the server
+        if: runner.os != 'Windows'
+        run: cargo build -p capsule-server --release --target ${{ matrix.target }}
       - name: Package (unix)
         if: runner.os != 'Windows'
         shell: bash
@@ -84,6 +94,11 @@ jobs:
           dist="capsule-v${{ needs.detect.outputs.version }}-${{ matrix.target }}"
           mkdir -p "$dist"
           cp "target/${{ matrix.target }}/release/capsule" "$dist/"
+          cp "target/${{ matrix.target }}/release/capsule-server" "$dist/"
+          # The operator's starting point: every setting the server reads, with what it defaults
+          # to and why. A release without it is a binary that refuses to start and an operator
+          # reading GitHub to find out which variables it wanted.
+          cp capsule-server/.env.example "$dist/"
           cp README.md LICENSE NOTICE CHANGELOG.md "$dist/"
           tar -czf "${dist}.tar.gz" "$dist"
           echo "ASSET=${dist}.tar.gz" >> "$GITHUB_ENV"

.markdownlint-cli2.jsonc

@@ -26,6 +26,16 @@
         // submodules, so without this the gate passes there and fails on any dev machine
         // that has run `git submodule update`.
         "rawshift/**",
+        // Generated reference pages (capsule-docs/scripts/gen-reference.mjs). Gitignored
+        // build output whose formatting comes from the generator, not from a contributor:
+        // a finding here is fixed in the generator, and the file it points at may not
+        // exist on the machine reading the report.
+        "capsule-docs/src/content/docs/reference/cli/**",
+        "capsule-docs/src/content/docs/reference/api/**",
+        // The same two directories reached through the repo-root `docs` symlink, which
+        // this glob walker follows (unlike the docs-truth walk, which skips symlinks).
+        "docs/reference/cli/**",
+        "docs/reference/api/**",
         "CLAUDE.md", // symlink to AGENTS.md
         "CHANGELOG.md" // generated by convco; not hand-formatted
     ]