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. This repo owns the signal contract; rapp-telemetry owns the privately deployed monitoring package the stack consumes.

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
• The monitoring package is privately deployed under rapp-telemetry. Integration and external delivery acceptance for this repo's signal contract remain 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

Provided Capabilities

type: operations
title: Private assurance signal contract and Prometheus mapping
description: Validate bounded producer-owned assurance states and observation times, with a local SQLite reference receiver and scripts/prometheus_export.py plus rules/platform-assurance.json for the selected Prometheus package. See docs/prometheus-mapping.md. Package transport, rule loading and acknowledged external delivery are not established by local exporter tests; do not deploy the SQLite reference as a parallel monitoring plane.
keywords: [telemetry, assurance, prometheus, signal, freshness, alerting, contract]

Generated work-record index

This repository opts into staged-source WORK-RECORDS.md generation through .generated-work-records.json and the isolated .generated-work-records.mk recipe. make generated-work-records reuses the State Hub renderer through the Custodian adapter; make generated-work-records-check verifies byte-exact agreement with staged Markdown. The pre-commit hook uses the isolated recipe, preserves unstaged index edits by refusing them, and retains the generated-only commit guard and existing security checks. It does not contact the hub, alter workplan statuses or grant deployment authority. This consumes shared tooling; it does not make this repository the provider of the generator capability.

Local orientation brief policy — 2026-10-19

.custodian-brief.md is a local, ignored State Hub orientation snapshot. Its existing bytes remain available for offline session startup; refreshing it does not require a Git commit. Authored workplans and the generated WORK-RECORDS index retain their existing source and staged-generation contracts. No runtime or credential change follows from this repository hygiene policy.