tegwick
53165d2a50
The placement question seeded as open is answered by canon rather than by a new decision. OAS section 8 defines Q2 Observability as 'telemetry and monitoring: metrics, logs, traces' - this repo in canon's own words. The 2026-08-11 coherence review found 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 not in use. Notes Q7 Governance as the sibling concern - the conformance loop, the other half of the self-evidencing aspiration this repo serves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
104 lines
3.6 KiB
Markdown
104 lines
3.6 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, and the live cluster has no monitoring namespace at all. This repo fills
|
|
that gap: it is the evidence plane the rest of the stack emits into.
|
|
|
|
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: **seeded** — `INTENT.md` written 2026-08-11, no implementation yet
|
|
- The live cluster has no monitoring namespace; this is greenfield
|
|
- 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
|