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?