Seed INTENT, SCOPE, README for the observability layer
Fills the gap identified in the 2026-08-11 Railiance architecture assessment: five layers declare they intend to be self-evidencing or auditable, and nothing owned the place that evidence goes. The live cluster has no monitoring namespace at all. Positions telemetry as the evidence plane - it owns the signal, not the meaning of the signal, so conformance rules stay with the repos that own them. Flags stack-dimension placement as an open question for railiance-master rather than asserting a level, so this repo does not repeat railiance-forge's unplaced state. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
parent
a4296e632d
commit
4ecf211524
4 changed files with 442 additions and 1 deletions
103
SCOPE.md
Normal file
103
SCOPE.md
Normal file
|
|
@ -0,0 +1,103 @@
|
|||
# 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
|
||||
- Open: stack-dimension placement is undecided (see `INTENT.md`, "Open
|
||||
Placement Question") and belongs to `railiance-master`
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue