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, using Go 1.26 and the remote default branch;
• document immutable SHA and release tags as production defaults.

Source-install foundations landed:

• 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);
• 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;
• 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);
• atomic service activation, rollback, and failure-preservation tests over SSH (source-install work package 4);
• 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;
• validate full HTTP config, including the accepted PUBLIC_URL, in main startup (milestone 1 of public-endpoint-and-identity.md: origin shape, production HTTPS, legacy WORKER_URL fallback);
• reconnect in memory on token rotation without stopping the runner;
• 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.

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 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.