feat: establish zara-server lifecycle boundary via RAGE #140

Merged

lost-rob0t merged 30 commits from rage/139-daemon into master

2026-08-22 06:43:47 +00:00

lost-rob0t commented

2026-08-22 05:26:41 +00:00

(Migrated from github.com)

RAGE issue

Consumes #128 under TASK #139 and daemon epic #127.

Immutable RAGE start commit: 12d28bcb28a2b48750875050ad7c21ebbbd636d8.

Architecture

zara remains the client-facing executable.
zara-server is the long-lived service executable.
ZaraClient is the transport-neutral client seam.
RuntimeSupervisor owns principal-explicit RuntimeHost slots.
server ownership uses a held flock in an owner-private runtime directory.
no ZeroMQ/auth/hard multi-user persistence claims in #128; those remain #129-#131.

RAGE evidence

rage/daemon-128-research.org
rage/daemon-128-design.org
rage/daemon-139.org

TDD evidence

The TDD/maximum-meaningful-coverage policy was strengthened during this already-running iteration. The initial implementation scaffold predates that instruction and is not used as completion evidence by itself.

Observed red gates include:

2bf98ace0629c0ece015ef53aea7f5f0ebe39e63: 6 failed / 737 passed, proving the new principal-whitespace and close-before-start requirements; one unrelated test assumption was corrected without changing production behavior.
45cf53d8f2afa6b104f6579f211710ba6ae6322b: 1 failed / 743 passed, with the sole failure proving that flake.nix lacked the required zara-server package/app contract.
9a46128da4d84a549f421ba14841e8cd35b25905: canonical scripts/test-all.sh passed (744 passed; server lifecycle 37 passed), but CI #233 exposed one pre-existing hermetic Nix-check defect in the real MCP Streamable HTTP regression: FileNotFoundError because the isolated pytest derivation did not provide the system CA path required by MCP v2/httpx2.

The MCP regression was not skipped or weakened. 5d141ae456e7edef219bd3e21061d828855650c1 wires Nix cacert into the isolated pytest check and exports the explicit CA bundle path.

Production changes for feature behavior were made only after their red tests were observed. Coverage exercises success, startup/degraded paths, explicit principal ownership/mismatch/caps, shutdown and timeout/failure paths, late-result suppression, lease ownership/duplicate/symlink behavior, real SIGTERM process shutdown, client event isolation, wheel entrypoints, and Nix packaging/wrapper behavior.

Packaging and gate integrity

Python wheel exposes zara-server=zara.server:main.
Nix exposes packages.zara-server and apps.zara-server and includes it in the aggregate environment.
the Nix wrapper check executes zara-server --help.
scripts/test-server-lifecycle.sh is part of the canonical scripts/test-all.sh gate.
CI runs the repository-required nix flake check before the packaged nix build.

Exact-head merge gate

Current head: 0a961fa21dbc339affdd87b46831ee94c5871d7b.

CI #235 is the authoritative exact-head run and must pass all of:

full scripts/test-all.sh
nix flake check
nix build
packaged zara-server wrapper/app checks
Ubuntu and Arch shared-mic regression jobs

The PR remains draft and must not merge unless all required checks are green for this exact head.

## RAGE issue Consumes #128 under TASK #139 and daemon epic #127. Immutable RAGE start commit: `12d28bcb28a2b48750875050ad7c21ebbbd636d8`. ## Architecture - `zara` remains the client-facing executable. - `zara-server` is the long-lived service executable. - `ZaraClient` is the transport-neutral client seam. - `RuntimeSupervisor` owns principal-explicit `RuntimeHost` slots. - server ownership uses a held `flock` in an owner-private runtime directory. - no ZeroMQ/auth/hard multi-user persistence claims in #128; those remain #129-#131. ## RAGE evidence - `rage/daemon-128-research.org` - `rage/daemon-128-design.org` - `rage/daemon-139.org` ## TDD evidence The TDD/maximum-meaningful-coverage policy was strengthened during this already-running iteration. The initial implementation scaffold predates that instruction and is not used as completion evidence by itself. Observed red gates include: - `2bf98ace0629c0ece015ef53aea7f5f0ebe39e63`: 6 failed / 737 passed, proving the new principal-whitespace and close-before-start requirements; one unrelated test assumption was corrected without changing production behavior. - `45cf53d8f2afa6b104f6579f211710ba6ae6322b`: 1 failed / 743 passed, with the sole failure proving that `flake.nix` lacked the required `zara-server` package/app contract. - `9a46128da4d84a549f421ba14841e8cd35b25905`: canonical `scripts/test-all.sh` passed (744 passed; server lifecycle 37 passed), but CI #233 exposed one pre-existing hermetic Nix-check defect in the real MCP Streamable HTTP regression: `FileNotFoundError` because the isolated pytest derivation did not provide the system CA path required by MCP v2/httpx2. The MCP regression was not skipped or weakened. `5d141ae456e7edef219bd3e21061d828855650c1` wires Nix `cacert` into the isolated pytest check and exports the explicit CA bundle path. Production changes for feature behavior were made only after their red tests were observed. Coverage exercises success, startup/degraded paths, explicit principal ownership/mismatch/caps, shutdown and timeout/failure paths, late-result suppression, lease ownership/duplicate/symlink behavior, real SIGTERM process shutdown, client event isolation, wheel entrypoints, and Nix packaging/wrapper behavior. ## Packaging and gate integrity - Python wheel exposes `zara-server=zara.server:main`. - Nix exposes `packages.zara-server` and `apps.zara-server` and includes it in the aggregate environment. - the Nix wrapper check executes `zara-server --help`. - `scripts/test-server-lifecycle.sh` is part of the canonical `scripts/test-all.sh` gate. - CI runs the repository-required `nix flake check` before the packaged `nix build`. ## Exact-head merge gate Current head: `0a961fa21dbc339affdd87b46831ee94c5871d7b`. CI #235 is the authoritative exact-head run and must pass all of: - full `scripts/test-all.sh` - `nix flake check` - `nix build` - packaged `zara-server` wrapper/app checks - Ubuntu and Arch shared-mic regression jobs The PR remains draft and must not merge unless all required checks are green for this exact head.