TASK: implement first-class Zara daemon via RAGE #139

New issue

Closed

opened 2026-08-22 04:58:02 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-08-22 04:58:02 +00:00

(Migrated from github.com)

Task

Implement Zara's first-class long-lived server architecture using the RAGE workflow, starting from the current repository state and the existing daemon research/epic (#127 and #128-#134).

Mandatory RAGE contract

This task is also the bootstrap run that establishes the repository-local RAGE convention for Zara.

Record the exact commit where the RAGE run begins in rage/<work-log>.org before research/design/tests/implementation commits proceed.
Consume work from the GitHub Issues queue. Select the first open dependency-satisfied issue in the repository's declared ordering; for daemon epic #127, begin with #128.
Research comes first. It must be deep enough to challenge the existing design rather than merely restating PR #135.
Convert research into an explicit design with decisions, rejected alternatives, invariants, threat/failure analysis, acceptance criteria, and an exact gate plan. Map every acceptance criterion to tests before implementation.
Implement only the consumed issue's slice using TDD-first red/green/refactor. For each behavior or regression, write/update the smallest deterministic test first, prove it fails for the expected reason, implement the minimum coherent change, rerun to green, then refactor while green.
Maximize meaningful behavioral coverage across changed and adjacent paths: happy path, invalid/boundary input, lifecycle transitions, degraded/error recovery, cancellation/stale work/races/timeouts, resource bounds, security/identity/isolation boundaries, persistence/migration, packaging/entrypoints, and regressions. Do not game coverage with weak assertions, execution-only tests, exclusions, or trivial branches.
Run the full gate at the exact candidate head and inspect changed-code coverage gaps. Do not use stale CI as merge authority.
If the gate passes, merge and update/close the consumed issue.
If the gate fails in a way that invalidates the design/implementation attempt, preserve the evidence, trash that failed implementation attempt, and start another numbered RAGE iteration from research/design rather than cosmetically patching a bad architecture.
Keep an append-only Org work log in rage/ with iteration boundaries, starting commit(s), consumed issues, research evidence, design decisions, planned tests, significant red/green evidence, coverage gaps addressed, implementation commits, gate evidence, failures, and merge SHA.

Bootstrap requirements for this run

Before feature implementation:

document the permanent RAGE contract in AGENTS.md;
add a repository-local skills/ directory for Zara agent skills;
add a Zara-local RAGE skill/instructions that point agents to the work log and repository gates;
make the RAGE log state the first/start commit unambiguously;
do not revive Prolog-RLM as a Zara runtime dependency.

After Zara's bootstrap is in place, update or create the reusable RAGE skill in lost-rob0t/skills once. Do not run a RAGE loop on the skills repository itself.

Naming / ownership decision

zara remains the client-facing executable name.
zara-server is the long-lived daemon/service executable.
Do not make zara --daemon the canonical interface.
Establish a ZaraClient-facing service boundary so callers do not depend directly on RuntimeHost; #129 will later implement the ZeroMQ transport behind that boundary.

Target capability

Ship a canonical client/server architecture rather than treating --wake, desktop, helper threads, or STT subprocesses as the daemon.

Minimum intended direction, subject to research and issue ordering:

zara-server long-lived service owning canonical runtime lifecycle;
zara client-facing surfaces;
shared client abstraction for CLI/desktop/voice-facing clients;
versioned wire protocol in #129;
safe reconnect and request/event correlation in later slices;
authenticated principal-scoped state/isolation in #130/#131;
bounded queues/frames and explicit backpressure;
lifecycle/supervision suitable for Linux;
no direct client bypass into runtime internals;
compatibility with current RuntimeHost, Prolog, agent, MCP, memory/todo, and voice ownership boundaries.

Required gates

At minimum:

focused TDD tests for each behavior before its production change;
repository full regression suite;
deterministic regression gate;
packaged Nix build / flake checks used by current CI;
lifecycle tests for the consumed daemon/server slice;
duplicate ownership, shutdown/restart, stale-work, degraded-state, invalid-input, timeout, and principal-bookkeeping tests;
packaging/entrypoint tests for zara-server;
changed-code coverage review with additional meaningful tests for reachable uncovered paths;
later protocol/auth/isolation/backpressure gates when their owning issues are consumed;
exact-head GitHub Actions verification before merge.

Documentation

Update current-state docs when behavior actually lands. Design/research must remain clearly distinguished from shipped behavior until merge. Agent-facing documentation must preserve the TDD-first and maximum-meaningful-coverage contract.

Parent daemon epic: #127
Existing research PR: #135
Implementation children: #128-#134

# Task Implement Zara's first-class long-lived server architecture using the RAGE workflow, starting from the current repository state and the existing daemon research/epic (#127 and #128-#134). ## Mandatory RAGE contract This task is also the bootstrap run that establishes the repository-local RAGE convention for Zara. 1. Record the exact commit where the RAGE run begins in `rage/<work-log>.org` before research/design/tests/implementation commits proceed. 2. Consume work from the GitHub Issues queue. Select the first open dependency-satisfied issue in the repository's declared ordering; for daemon epic #127, begin with #128. 3. Research comes first. It must be deep enough to challenge the existing design rather than merely restating PR #135. 4. Convert research into an explicit design with decisions, rejected alternatives, invariants, threat/failure analysis, acceptance criteria, and an exact gate plan. Map every acceptance criterion to tests before implementation. 5. Implement only the consumed issue's slice using TDD-first red/green/refactor. For each behavior or regression, write/update the smallest deterministic test first, prove it fails for the expected reason, implement the minimum coherent change, rerun to green, then refactor while green. 6. Maximize meaningful behavioral coverage across changed and adjacent paths: happy path, invalid/boundary input, lifecycle transitions, degraded/error recovery, cancellation/stale work/races/timeouts, resource bounds, security/identity/isolation boundaries, persistence/migration, packaging/entrypoints, and regressions. Do not game coverage with weak assertions, execution-only tests, exclusions, or trivial branches. 7. Run the full gate at the exact candidate head and inspect changed-code coverage gaps. Do not use stale CI as merge authority. 8. If the gate passes, merge and update/close the consumed issue. 9. If the gate fails in a way that invalidates the design/implementation attempt, preserve the evidence, trash that failed implementation attempt, and start another numbered RAGE iteration from research/design rather than cosmetically patching a bad architecture. 10. Keep an append-only Org work log in `rage/` with iteration boundaries, starting commit(s), consumed issues, research evidence, design decisions, planned tests, significant red/green evidence, coverage gaps addressed, implementation commits, gate evidence, failures, and merge SHA. ## Bootstrap requirements for this run Before feature implementation: - document the permanent RAGE contract in `AGENTS.md`; - add a repository-local `skills/` directory for Zara agent skills; - add a Zara-local RAGE skill/instructions that point agents to the work log and repository gates; - make the RAGE log state the first/start commit unambiguously; - do not revive Prolog-RLM as a Zara runtime dependency. After Zara's bootstrap is in place, update or create the reusable RAGE skill in `lost-rob0t/skills` once. Do **not** run a RAGE loop on the skills repository itself. ## Naming / ownership decision - `zara` remains the client-facing executable name. - `zara-server` is the long-lived daemon/service executable. - Do not make `zara --daemon` the canonical interface. - Establish a `ZaraClient`-facing service boundary so callers do not depend directly on `RuntimeHost`; #129 will later implement the ZeroMQ transport behind that boundary. ## Target capability Ship a canonical client/server architecture rather than treating `--wake`, desktop, helper threads, or STT subprocesses as the daemon. Minimum intended direction, subject to research and issue ordering: - `zara-server` long-lived service owning canonical runtime lifecycle; - `zara` client-facing surfaces; - shared client abstraction for CLI/desktop/voice-facing clients; - versioned wire protocol in #129; - safe reconnect and request/event correlation in later slices; - authenticated principal-scoped state/isolation in #130/#131; - bounded queues/frames and explicit backpressure; - lifecycle/supervision suitable for Linux; - no direct client bypass into runtime internals; - compatibility with current RuntimeHost, Prolog, agent, MCP, memory/todo, and voice ownership boundaries. ## Required gates At minimum: - focused TDD tests for each behavior before its production change; - repository full regression suite; - deterministic regression gate; - packaged Nix build / flake checks used by current CI; - lifecycle tests for the consumed daemon/server slice; - duplicate ownership, shutdown/restart, stale-work, degraded-state, invalid-input, timeout, and principal-bookkeeping tests; - packaging/entrypoint tests for `zara-server`; - changed-code coverage review with additional meaningful tests for reachable uncovered paths; - later protocol/auth/isolation/backpressure gates when their owning issues are consumed; - exact-head GitHub Actions verification before merge. ## Documentation Update current-state docs when behavior actually lands. Design/research must remain clearly distinguished from shipped behavior until merge. Agent-facing documentation must preserve the TDD-first and maximum-meaningful-coverage contract. Parent daemon epic: #127 Existing research PR: #135 Implementation children: #128-#134

nsaspy referenced this issue

2026-08-28 03:31:14 +00:00

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

nsaspy referenced this issue

2026-08-28 03:31:14 +00:00

RAGE #129: implement ZARA/1 protocol and ZeroMQ client #142

nsaspy referenced this issue

2026-08-28 03:31:15 +00:00

RAGE #131: principal-scope conversations and memory #147

nsaspy commented

2026-09-02 17:27:56 +00:00

Owner

Closing as stale/completed bootstrap work. This task existed to establish the RAGE convention and drive the first-class daemon queue starting at #128. That architecture has since landed through the daemon/client slices (#128-#133), including zara-server, ZARA/1, CURVE/ZAP security, principal isolation, live voice transport, and ZaraClient migration. Remaining daemon work is tracked by #127/#134 and the voice release chain, so keeping this bootstrap task open only duplicates the active roadmap.

Closing as stale/completed bootstrap work. This task existed to establish the RAGE convention and drive the first-class daemon queue starting at #128. That architecture has since landed through the daemon/client slices (#128-#133), including `zara-server`, `ZARA/1`, CURVE/ZAP security, principal isolation, live voice transport, and ZaraClient migration. Remaining daemon work is tracked by #127/#134 and the voice release chain, so keeping this bootstrap task open only duplicates the active roadmap.

nsaspy closed this issue

2026-09-04 14:39:03 +00:00