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.

---

## Placement: Quality dimension, Q2 Observability

This repo is **not** a stack level and not an exception to the stack model. It
is a concern on the **Quality dimension**, sub-level **Q2 Observability**, whose
canon definition (`canon/standards/orthogonal-architecture_v1.0.md` §8) is:

> *Telemetry and monitoring. Examples: metrics, logs, traces.*

That is this repo, in canon's own words.

The question was originally raised as open — S3 platform capability, or Quality
concern? — and answered by the 2026-08-11 coherence review, which found that
Railiance had been modelling itself on one of OAS's six required dimensions and
treating everything else as unplaced. Observability was never homeless; the
dimension it belongs to was simply not in use.

Ratification sits with `railiance-master`, which owns the taxonomy. Related:
the conformance loop is **Q7 Governance and Change Management** — a sibling
concern on the same dimension, and the other half of the self-evidencing
aspiration this repo exists to serve.

---

## 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?*