# Worker Implementation Documents

This directory is the implementation authority for the standalone RSMon worker.
It converts the worker-related plans formerly kept in the RSMon control-plane
repository into contracts tied to this repository's packages and tests.

These documents distinguish three states:

- **Implemented**: wired into `cmd/rsmon-worker` and covered by tests.
- **Partial**: code exists, but a named runtime path or acceptance criterion is
  missing.
- **Planned**: no production path exists yet. The document identifies the
  package, protocol, dependency, and tests required to implement it.

Plans do not override code. When a document and the current implementation
disagree, update both in the same change or mark the discrepancy explicitly.

## Implementation Index

| Document | Scope | Current state |
| --- | --- | --- |
| [architecture.md](architecture.md) | Process boundaries, ownership, runtime composition | Implemented with partial subsystems |
| [control-plane-protocol.md](control-plane-protocol.md) | WebSocket frames, leases, config, compatibility APIs | Implemented |
| [tasks-and-notifications.md](tasks-and-notifications.md) | Normal checks and delegated notification execution | Implemented with provider gaps |
| [web-console-and-observability.md](web-console-and-observability.md) | Local UI, auth, inventory view, host telemetry | Partial |
| [inventory.md](inventory.md) | Worker host discovery and control-plane inventory projection | Partial |
| [private-workers.md](private-workers.md) | Customer worker isolation, credentials, onboarding | Partial |
| [network-diagnostics.md](network-diagnostics.md) | Confirmation checks and dedicated diagnostic tasks | Partial |
| [critical-check-cluster.md](critical-check-cluster.md) | Raft-backed dispatchless critical checks | Scaffold only |
| [public-endpoint-and-identity.md](public-endpoint-and-identity.md) | One HTTPS origin, peer status, CA/mTLS, managed Raft topology | Planned; peer HTTPS partial |
| [source-installation.md](source-installation.md) | Go SSH source installer and Docker/OpenSSH test matrix | Partial: harness + planning landed, remote build pending |
| [implementation-roadmap.md](implementation-roadmap.md) | Ordered repository work packages and release gates | Active |
| [source-plan-migration.md](source-plan-migration.md) | Source-to-target conversion ledger and resolved conflicts | Complete mapping |

## Ownership Boundary

This repository owns:

- worker process startup, configuration, and graceful shutdown;
- the control-plane client and wire types;
- check and notification execution;
- local web console, local state, inventory collection, and host metrics;
- worker-to-worker transport and Raft state;
- Docker, Compose, systemd, source installation, and release-image packaging.

The RSMon control-plane repository owns:

- users, accounts, monitors, contacts, billing, and RBAC;
- PostgreSQL task production, selection, leasing, retry, and dead-letter state;
- worker registration and authorization policy;
- accepted-result application and VictoriaMetrics persistence;
- customer-facing fleet, inventory, diagnostics, and incident APIs.

The worker must not receive control-plane PostgreSQL, Valkey, or
VictoriaMetrics credentials. Normal results, host telemetry, inventory, and
diagnostics are reported over authenticated protocol messages for validation
and persistence by the control plane.

## Required Quality Gates

Run before merging worker changes:

```bash
make check
docker build -t rsmon-worker:test .
docker run --rm rsmon-worker:test --version
docker compose config
```

Features that alter protocol messages require compatibility tests in
`internal/wire` and runner protocol tests in `internal/distworker`. Raft work
requires deterministic FSM tests and a multi-node fault test. Security-sensitive
features require negative tests for account scope, arbitrary target rejection,
credential redaction, and unauthenticated access.