railiance-telemetry/SCOPE.md

# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.

---

## One-liner

Observability for Railiance — monitoring, metrics, logs, traces, and alerting that turn running behaviour into evidence and give the self-organizing control loop a signal to close on.

---

## Core Idea

Five Railiance layers independently declare that they intend to be
"self-evidencing" or "auditable". None of them owned the place that evidence
goes, and the live cluster has no monitoring namespace at all. This repo fills
that gap: it is the evidence plane the rest of the stack emits into.

The distinction that keeps this repo honest: it owns **the signal**, not
**the meaning of the signal**. Conformance rules and consistency checks belong
to the repos that own those concerns; telemetry carries and surfaces their
output.

---

## In Scope

- Metrics collection, storage, and query
- Log aggregation and retention
- Tracing substrate
- Alerting rules, routing, and notification paths
- Dashboards and operator/agent-facing health surfaces
- The standard emission contract other Railiance layers implement
- Retention policy sufficient to prove restore drills and rollout holds
- Signal exposure that automated control loops consume

---

## Out of Scope

- Conformance and declaration-validation *rules* — owned by the repos whose
  declarations they check (`railiance-master`, family declaration validator)
- The monitoring stack as a deployable package → `rapp-*` territory
- Immutable audit custody — a separate concern with separate guarantees
- Business, cost, and revenue analytics → `resource-control`, `fin-hub`
- Incident management, on-call rotation, paging policy
- Secret material of any kind (this layer is explicitly non-custodial)

---

## Relevant When

- A layer needs somewhere to emit health, readiness, or drift signal
- An expectation should raise an alert when violated
- A control loop needs a signal to close on
- Proving after the fact that a restore, rollout, or migration actually held

## Not Relevant When

- Defining what "correct" means for a declaration (that is the owning repo's job)
- Packaging the monitoring workload for deployment (that is `rapp-*`)
- Storing anything sensitive

---

## Current State

- Status: **private reference implementation** — contract, durable local inbox,
  platform adapter and missing-emission checks implemented September 6
- No deployed monitoring runtime or external delivery acceptance established;
  live work is tracked in RTEL-WP-0002-T04
- Placement: **Quality dimension, Q2 Observability** — canon defines Q2 as
  "telemetry and monitoring: metrics, logs, traces". Ratification sits with
  `railiance-master`; the question is answered, not open

---

## How It Fits

- Upstream dependencies: `railiance-cluster` (S2) for runtime,
  `railiance-platform` (S3) for any stateful backing services it needs
- Downstream consumers: every layer that declares itself self-evidencing, plus
  automated control loops and agent planning surfaces
- Often used with: `railiance-master` (which owns what the signals must prove),
  `railiance-fabric` (graph and blast-radius context for an alert)

---

## Terminology

- Preferred terms: evidence plane, emission contract, expectation-based alerting
- Potentially confusing: "self-evidencing" is a property *other* layers aspire
  to; this repo provides the substrate that makes it checkable, it does not
  make the claims on their behalf

---

## Getting Oriented

- Start with: `INTENT.md`
- Then: `SCOPE.md`, `AGENTS.md`, `workplans/`
- Context: `railiance-platform/history/2026-08-11-railiance-architecture-in-aspiration.md`
  records the assessment that identified this gap