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: seeded — INTENT.md written 2026-08-11, no implementation yet
• The live cluster has no monitoring namespace; this is greenfield
• Open: stack-dimension placement is undecided (see INTENT.md, "Open Placement Question") and belongs to railiance-master

---

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