railiance-telemetry/INTENT.md

# INTENT

> This file captures **why this repository exists**,
> the **direction it is moving toward**, and
> the **kind of system it is meant to become**.
> It is intentionally **aspirational and stable**, not a description of current implementation.

---

## One-liner

**The observability layer — turning the running system's behaviour into evidence, so every other layer's promise to be self-evidencing has somewhere to be proven.**

---

## Why This Exists

Railiance has an unusually consistent aspiration, declared independently across
five layers:

* `railiance-infra` — "self-evidencing, **auditable** provisioning"
* `railiance-cluster` — "self-evidencing, **auditable** runtime state"
* `railiance-platform` — "**self-healing and observable** platform services"
* `railiance-apps` — "self-evidencing, reviewable **application readiness**"
* `railiance-forge` — "self-evidencing forge **health and readiness** checks"

Five layers all want the system to **prove its own state rather than be
asserted correct**. None of them owned the place that evidence goes, and the
live cluster showed the consequence: no monitoring namespace, no metrics store,
no alerting path.

Without this layer:

* "self-evidencing" stays an adjective in five INTENT files,
* failures are discovered by a human noticing, not by the system reporting,
* the control loops that are supposed to keep the fleet consistent have no
  signal to close on,
* and drift is found by audit months later rather than by an alert in minutes.

This layer exists so that a claim about system state can be **checked against
observed reality** instead of trusted.

---

## The Mission

> *Where we are going.*

To become the **evidence plane of Railiance** — collecting, storing,
and surfacing metrics, logs, traces, and health signals from every layer, and
raising an alert when observed reality diverges from declared intent.

This means:

* Evidence is **collected by default**, not instrumented per incident
* Signals are **retained long enough to prove a trend**, not just a moment
* Alerts describe **a violated expectation**, not a raw threshold
* Every layer has a **standard way to emit** its readiness and health
* The control loop has a **signal to close on**, so consistency is maintained
  continuously rather than restored by periodic cleanup

---

## Core Principles

### 1. Evidence over Assertion

A claim about the system's state is worth what its evidence is worth. This
layer's job is to make evidence cheap enough that assertion stops being
tempting.

### 2. Observed, Not Reported

Signals are gathered from the running system, not from what a deployment
process believed it did.

### 3. One Emission Contract

Every layer emits health and readiness the same way. A per-layer bespoke
integration is a failure of this layer, not of that one.

### 4. Alerts Carry Meaning

An alert states which expectation was violated and what depends on it.
Thresholds without an owning expectation become noise, and noise trains people
to ignore alerts.

### 5. Retention Serves Proof

Signals are kept long enough to demonstrate that a restore worked, a rollout
held, or a drift began — not merely long enough to draw a dashboard.

### 6. Non-Custodial

Telemetry observes; it does not hold secrets, and it never becomes a side
channel for credential material or personal data.

---

## What This Is (Conceptually)

The **evidence plane** that sits beside the stack rather than inside one layer
of it:

* the metrics, logs, and trace substrate
* the alerting and notification path
* the dashboards and health surfaces operators and agents read
* the standard emission contract other layers implement
* the signal source that automated control loops close on

---

## What This Is Not

* **Not the checks themselves.** Conformance rules, declaration validation, and
  fleet-consistency checks belong to the layers and repos that own those
  concerns. This layer carries their signal; it does not define their meaning.
* **Not the packaged workload.** The monitoring stack as a deployable is
  managed-workload-package territory (`rapp-*`), not this repo.
* **Not an incident-management or on-call product.**
* **Not a data warehouse.** Business and cost analytics belong to their own
  homes; this layer covers operational evidence.
* **Not a secret store or an audit-custody system.** Immutable audit custody is
  a separate concern with separate guarantees.

---

## Open Placement Question

Railiance's stack dimension defines five levels (S1–S5). Observability is
cross-cutting: it draws signal from every level and is consumed by all of them.

Whether this repo is best modelled as an S3 platform capability (it runs
stateful services and is consumed by others), or as a concern on the Quality
dimension rather than the Stack dimension, is **not settled here**. It is a
decision for `railiance-master`, which owns the taxonomy.

This is stated explicitly because leaving placement undeclared is exactly how
`railiance-forge` ended up outside the stack model without anyone deciding it
should be.

---

## Direction of Evolution

This layer is expected to evolve toward:

* A **standard emission contract** every layer implements
* **Expectation-based alerting** tied to declared intent rather than bare thresholds
* Retention that can **prove restore drills and rollout holds** after the fact
* Signal that automated **control loops close on** without human relay
* Evidence surfaces that **agents can query**, not only humans read
* Self-evidencing telemetry — the observability layer proves its own health too

---

## Guiding Question

> *Would we find out from the system, or from a person noticing?*