worker/docs/implementation-roadmap.md

# Worker Implementation Roadmap

This roadmap orders work by dependency and risk. A package existing does not
make a work package complete; its release gate must pass in a wired process.

## R0: Distribution Reliability

State: active.

Worker repository:

- publish valid Harbor references after normalizing a configured registry URL;
- use local `/healthz` for container liveness;
- verify amd64 and arm64 image startup, Chromium availability, and version
  metadata;
- add a package/install smoke test for Docker and systemd artifacts;
- document immutable SHA and release tags as production defaults.

Gate: a push publishes `sha-<12>` and `latest` manifests for both platforms,
and a container remains healthy when the control plane is unavailable.

## R1: Runtime Correctness

State: partial.

Worker repository:

- wire local inventory and metrics collector lifecycle into web server start
  and shutdown;
- validate full HTTP config, including `WORKER_URL`, in main startup;
- [x] reconnect in memory on token rotation without stopping the runner;
- [x] resend bounded check/notification results after websocket reconnect;
- define process policy when the web listener exits unexpectedly;
- add process-exit, bounded final-drain, duplicate-frame, and backpressure
  coverage.

Gate: collectors populate real pages, rotation preserves all subsystems, result
resend remains bounded and idempotent, and SIGTERM leaves no listener,
collector, task, or SQLite goroutine behind.

## R2: Protocol And Credential Hardening

State: partial.

Worker repository:

- complete frame conformance tests;
- add signed config version/account identity;
- enforce task account and credential scope locally;
- add bounded delegated-delivery audit to the local console;
- support per-account webhook/Mattermost credentials after control-plane wire
  support exists.

Control-plane dependency:

- signed config producer and key rotation;
- persisted account-scoped webhook/Mattermost credentials;
- lease/task account fields treated as immutable during result application.

Gate: cross-account fixtures fail before network execution and no credential
appears in worker logs, SQLite, snapshots, or protocol error payloads.

## R3: Private-Worker Lifecycle

State: planned beyond scheduler isolation.

Worker repository:

- one-time bootstrap exchange and atomic secret storage;
- token handoff and revocation handling;
- stale/expired signed-config behavior;
- clear disabled/revoked UI state;
- optional mTLS client identity.

Control-plane dependency:

- customer worker CRUD and billing entitlement;
- one-time bootstrap token state;
- immutable account binding and signed config;
- audit and revocation acknowledgement.

Gate: a customer can install, connect, execute only their work, rotate, disable,
revoke, and uninstall without an operator admin secret.

## R4: Host Inventory And Console

State: partial.

Worker repository:

- extract `internal/inventory` and start process/host collection;
- add typed bounded inventory report;
- add Docker/Compose, nginx, systemd, and address collectors in stages;
- add read-only Compose status/logs before mutation;
- correct local interval metrics and add optional hardware sections.

Control-plane dependency:

- worker inventory report ingestion and source-aware reconciliation;
- server/worker/account ownership validation;
- deploymentd comparison and monitor suggestion UI.

Gate: partial failures cannot delete inventory, worker and deploymentd sources
coexist, and reports contain no environment or credential values.

## R5: Dedicated Network Diagnostics

State: planned; normal confirmation is already partial.

Worker repository:

- add diagnostic wire branch and `internal/netdiag`;
- ship HTTP GET/HEAD and unauthenticated SSH handshake first;
- add TCP/DNS, then separately gate traceroute/MTR;
- implement SSRF, redirect, timeout, output, and rate protections.

Control-plane dependency:

- monitor-bound target normalization and signed target hash;
- diagnostic task production, storage, RBAC, rate limits, and UI;
- private-worker source eligibility.

Gate: no task can probe outside its authorized monitor target and all results
are bounded, structured, and credential-free.

## R6: Public Check Economy

State: planned.

Depends on R2, R3, and diagnostic-grade target protection. Public work uses a
separate signed grant and safe HTTP methods, never widened account scope.

Gate: private targets and credential-bearing requests are impossible under DNS
rebinding and redirects; accounting remains idempotent under result replay.

## R7: Critical-Check Cluster

State: Raft scaffold only.

Worker repository:

- secure bootstrap and mTLS identity;
- signed config adoption and observer-set versioning;
- deterministic scheduler and check executor bridge;
- deterministic incident/quorum FSM;
- encrypted snapshots and restore;
- metadata outbox, witness, replay, and metrics;
- 3/5-node fault campaigns.

Control-plane dependency:

- critical-check config/signing service;
- credential-envelope service;
- witness and replay endpoints;
- customer incident projection and audit.

Gate: all release gates in
[critical-check-cluster.md](critical-check-cluster.md) pass while normal tasks
continue without behavioral change.

## Documentation Rule

Every completed work package updates:

- the relevant implementation document's current-state section;
- this roadmap state and gate evidence;
- root configuration examples when environment or deployment changes;
- the source migration ledger if a control-plane plan is superseded.