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;
- add the Docker/OpenSSH source-install matrix for Alpine, Ubuntu, and Arch from
  [source-installation.md](source-installation.md), using Go 1.26 and the
  remote default branch;
- document immutable SHA and release tags as production defaults.

Source-install foundations landed:

- [x] reusable Docker/OpenSSH harness and distro fixtures for Alpine, Ubuntu,
      and Arch (`internal/installer/harness`) with real SSH readiness and
      reliable teardown, gated behind `RSMON_TEST_DOCKER` (`make test-ssh`);
- [x] pure distro/toolchain/source-install planning (`internal/sshinstall`):
      os-release detection, package-manager/init resolution, pinned Go 1.26
      toolchain with published SHA-256, and a plan the executor runs;
- [x] remote package install, Go download, clone, and build execution through
      the SSH transport (`installer.SourceInstall`): prerequisite install,
      SHA-256-verified Go toolchain, clone/update of the public repo, resolved
      branch/commit record, and a staging build. Running service/config is not
      touched (source-install work package 3);
- [x] atomic service activation, rollback, and failure-preservation tests over
      SSH (source-install work package 4);
- [x] run the full source-install E2E matrix in CI (source-install work
      package 5).

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;
- [x] validate full HTTP config, including the accepted `PUBLIC_URL`, in main
  startup (milestone 1 of
  [public-endpoint-and-identity.md](public-endpoint-and-identity.md): origin
  shape, production HTTPS, legacy `WORKER_URL` fallback);
- [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;
- mandatory production mTLS client identity and control-plane-owned topology as
  defined in [public-endpoint-and-identity.md](public-endpoint-and-identity.md).

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, CA lifecycle, mTLS identity, and one-origin HTTPS transport;
- 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;
- three-node external-HTTPS 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.