tegwick
95a862bd5d
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a15374-f59f-7a31-86d2-d23b5d2ed181
117 lines
4.4 KiB
Markdown
117 lines
4.4 KiB
Markdown
# SCOPE
|
|
|
|
> This file helps you quickly understand what this repository is about,
|
|
> when it is relevant, and when it is not.
|
|
> It is intentionally lightweight and may be incomplete.
|
|
|
|
---
|
|
|
|
## One-liner
|
|
|
|
Observability for Railiance — monitoring, metrics, logs, traces, and alerting that turn running behaviour into evidence and give the self-organizing control loop a signal to close on.
|
|
|
|
---
|
|
|
|
## Core Idea
|
|
|
|
Five Railiance layers independently declare that they intend to be
|
|
"self-evidencing" or "auditable". None of them owned the place that evidence
|
|
goes. This repo owns the signal contract; `rapp-telemetry` owns the privately
|
|
deployed monitoring package the stack consumes.
|
|
|
|
The distinction that keeps this repo honest: it owns **the signal**, not
|
|
**the meaning of the signal**. Conformance rules and consistency checks belong
|
|
to the repos that own those concerns; telemetry carries and surfaces their
|
|
output.
|
|
|
|
---
|
|
|
|
## In Scope
|
|
|
|
- Metrics collection, storage, and query
|
|
- Log aggregation and retention
|
|
- Tracing substrate
|
|
- Alerting rules, routing, and notification paths
|
|
- Dashboards and operator/agent-facing health surfaces
|
|
- The standard emission contract other Railiance layers implement
|
|
- Retention policy sufficient to prove restore drills and rollout holds
|
|
- Signal exposure that automated control loops consume
|
|
|
|
---
|
|
|
|
## Out of Scope
|
|
|
|
- Conformance and declaration-validation *rules* — owned by the repos whose
|
|
declarations they check (`railiance-master`, family declaration validator)
|
|
- The monitoring stack as a deployable package → `rapp-*` territory
|
|
- Immutable audit custody — a separate concern with separate guarantees
|
|
- Business, cost, and revenue analytics → `resource-control`, `fin-hub`
|
|
- Incident management, on-call rotation, paging policy
|
|
- Secret material of any kind (this layer is explicitly non-custodial)
|
|
|
|
---
|
|
|
|
## Relevant When
|
|
|
|
- A layer needs somewhere to emit health, readiness, or drift signal
|
|
- An expectation should raise an alert when violated
|
|
- A control loop needs a signal to close on
|
|
- Proving after the fact that a restore, rollout, or migration actually held
|
|
|
|
## Not Relevant When
|
|
|
|
- Defining what "correct" means for a declaration (that is the owning repo's job)
|
|
- Packaging the monitoring workload for deployment (that is `rapp-*`)
|
|
- Storing anything sensitive
|
|
|
|
---
|
|
|
|
## Current State
|
|
|
|
- Status: **private reference implementation** — contract, durable local inbox,
|
|
platform adapter and missing-emission checks implemented September 6
|
|
- The monitoring package is privately deployed under `rapp-telemetry`.
|
|
Integration and external delivery acceptance for this repo's signal contract
|
|
remain tracked in RTEL-WP-0002-T04.
|
|
- Placement: **Quality dimension, Q2 Observability** — canon defines Q2 as
|
|
"telemetry and monitoring: metrics, logs, traces". Ratification sits with
|
|
`railiance-master`; the question is answered, not open
|
|
|
|
---
|
|
|
|
## How It Fits
|
|
|
|
- Upstream dependencies: `railiance-cluster` (S2) for runtime,
|
|
`railiance-platform` (S3) for any stateful backing services it needs
|
|
- Downstream consumers: every layer that declares itself self-evidencing, plus
|
|
automated control loops and agent planning surfaces
|
|
- Often used with: `railiance-master` (which owns what the signals must prove),
|
|
`railiance-fabric` (graph and blast-radius context for an alert)
|
|
|
|
---
|
|
|
|
## Terminology
|
|
|
|
- Preferred terms: evidence plane, emission contract, expectation-based alerting
|
|
- Potentially confusing: "self-evidencing" is a property *other* layers aspire
|
|
to; this repo provides the substrate that makes it checkable, it does not
|
|
make the claims on their behalf
|
|
|
|
---
|
|
|
|
## Getting Oriented
|
|
|
|
- Start with: `INTENT.md`
|
|
- Then: `SCOPE.md`, `AGENTS.md`, `workplans/`
|
|
- Context: `railiance-platform/history/2026-08-11-railiance-architecture-in-aspiration.md`
|
|
records the assessment that identified this gap
|
|
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
type: operations
|
|
title: Private assurance signal contract and Prometheus mapping
|
|
description: Validate bounded producer-owned assurance states and observation times, with a local SQLite reference receiver and scripts/prometheus_export.py plus rules/platform-assurance.json for the selected Prometheus package. See docs/prometheus-mapping.md. Package transport, rule loading and acknowledged external delivery are not established by local exporter tests; do not deploy the SQLite reference as a parallel monitoring plane.
|
|
keywords: [telemetry, assurance, prometheus, signal, freshness, alerting, contract]
|
|
```
|