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