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?