railiance-telemetry/README.md

# railiance-telemetry

Observability for Railiance providing monitoring, metrics, alerting etc to
enable the self-organizing control loop.

**Status: private reference implementation.** A versioned signal contract,
SQLite receipt/inbox CLI and platform adapter are implemented and tested.
No monitoring runtime or notification schedule is installed by this work.
See [the contract and workflow](docs/signal-contract.md).

## Why this repo exists

Five Railiance layers independently declare that they intend to be
"self-evidencing" or "auditable" — infra, cluster, platform, apps, and forge.
None of them owned the place that evidence goes. This repo is that place.

It owns **the signal**, not **the meaning of the signal**: conformance rules and
consistency checks stay with the repos that own those concerns, and telemetry
carries and surfaces their output.

## Start here

1. [`INTENT.md`](INTENT.md) — why this exists and what it is becoming
2. [`SCOPE.md`](SCOPE.md) — in scope, out of scope, how it fits
3. [`AGENTS.md`](AGENTS.md) — session protocol
4. `workplans/`

## Placement and verification

Quality dimension, Q2 Observability, as recorded in INTENT/SCOPE. Monitoring
workload packaging remains outside this repo.

Run `python3 -m unittest discover -s tests -v` for the dependency-free core
suite (native receiver check is optional there). For the full core/runtime and
native owner-contract suite, run **`bash scripts/verify.sh`** with Python 3.11+,
uv, Go and sibling `audit-core` / `flex-auth` checkouts. The script installs the
hash-locked runtime dependencies in `.venv-verify`, builds Flex Auth into
`.cache/verify`, and fails if either native source is absent. Override checkout
locations with `RTEL_AUDIT_CORE_SOURCE` and `RTEL_FLEX_AUTH_SOURCE`. It reports
the tested owner revisions; those source checkouts are not fetched or changed.
This command tests local contracts, not live infrastructure or Prometheus rules.
Live acceptance is tracked by RTEL-WP-0002-T04; local receipts are not external
operator delivery proof.

## Managed production package

[rapp-telemetry](../rapp-telemetry/README.md) packages Prometheus, Alertmanager
and Grafana for railiance01, with telemetry.coulomb.social as the intended
Grafana hostname. This repo retains Q2 contracts and rule meaning. The local
receiver and activity candidates are reference tooling; do not enable them as
a second production monitoring plane. The package records private installation
and restore proof; delivery acceptance remains blocked in RTEL-WP-0002-T04.
The [Prometheus mapping](docs/prometheus-mapping.md) supplies a tested report
exporter and failure/absence rules for package integration.

The [email acknowledgment component](docs/alert-acknowledgment.md) records an
explicit Railiance admin confirmation with a durable audit-core outbox. It is
not activated. Identity/policy adapters are implemented; native package admission,
webhook/audit custody and audited alert confirmation remain under T04. SMTP
custody and delivery are verified, including Bernd’s confirmed inbox receipt
of the transport-test email.

[Maintenance and recovery](docs/acknowledgment-operations.md) covers private audit
metrics, explicit event requeue and verified backup/restore to a new database.