Coherence review: Railiance uses one of six OAS dimensions
The central finding. OAS defines six canonical dimensions and states that each architecture description MUST use them. Railiance has modelled itself almost entirely on Stack. Everything that did not fit a stack level was treated as an anomaly - "unplaced", "beside the stack" - and accumulated as exceptions. They were never anomalies. They are concerns on dimensions Railiance was not using, and the Quality dimension's sub-levels map almost one-to-one onto the capability gaps this review found independently: Q2 Observability is railiance-telemetry, named in canon in exactly those words; Q7 Governance is the conformance loop; Q3 is restore proof; Q6 is cost attribution. The self-evidencing thread across five stack layers is five Stack repos each independently asking for Q2 and Q7 - what a missing dimension looks like from inside the one you are using. Also records four contradictions (C1-C4), of which C1 is actionable here: the hub attributes ~11 capabilities to this repo including Terraform, Ansible, k3s, CI/CD and app deployment, which S3 does not own. SCOPE.md declares four, all correctly S3, and is authoritative. ArgoCD decision closed: keep it, documentation stays accurate; relocating GitOps to Helix Forge noted as possible future cleanup. SCOPE.md: corrects the "five independent repos per OAS Stack layer" claim, records the ArgoCD deployment path, the telemetry emission relationship, and the hub capability drift. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
codex
parent
0ae7cdab92
commit
cbc961ca09
2 changed files with 111 additions and 34 deletions
|
|
@ -69,12 +69,63 @@ stack rather than inside it.
|
|||
| S4 | `railiance-enablement` | paved paths: CI/CD templates, SDKs, portal, promotion conventions |
|
||||
| S5 | `railiance-apps` | user-facing application workloads and release operations |
|
||||
|
||||
| Beside the stack | Repo | Owns |
|
||||
Repos that are not stack levels are **not homeless** — they belong to other OAS
|
||||
dimensions (§2.1):
|
||||
|
||||
| Repo | Dimension | Owns |
|
||||
| --- | --- | --- |
|
||||
| evidence plane | `railiance-telemetry` | metrics, logs, traces, alerting — the substrate other layers emit into (**OPEN** placement, §5.1) |
|
||||
| architecture | `railiance-master` | repo taxonomy, framework ADRs, boundary rules, vocabulary |
|
||||
| ecosystem graph | `railiance-fabric` | repo → service → capability → interface → dependency model |
|
||||
| forge | `railiance-forge` | source hosting, registries, automation runners — **being placed** (§5.2): workload → `rapp-forgejo`, layer responsibility → S4 |
|
||||
| `railiance-telemetry` | **Quality / Q2 Observability** | metrics, logs, traces, alerting — the substrate other layers emit into |
|
||||
| `railiance-bootstrap` | lifecycle (pre-stack) | the ignition sequence: bare VM → working Railiance, then handoff |
|
||||
| `railiance-master` | the architecture description itself | repo taxonomy, framework ADRs, boundary rules, vocabulary |
|
||||
| `railiance-fabric` | **Capability** | repo → service → capability → interface → dependency model |
|
||||
| `railiance-forge` | **being placed** (§5.2) | workload → `rapp-forgejo`; layer responsibility → S4 |
|
||||
|
||||
### 2.1 Railiance uses one of six canonical dimensions
|
||||
|
||||
**This is the central coherence finding of the 2026-08-11 review.**
|
||||
|
||||
OAS defines **six** canonical architecture dimensions, and states that *"Each
|
||||
architecture description MUST use these dimensions"*
|
||||
(`canon/standards/orthogonal-architecture_v1.0.md` §4):
|
||||
|
||||
| Dimension | Purpose | Railiance use |
|
||||
| --- | --- | --- |
|
||||
| Stack | technical hosting substrate | **used** — S1–S5, the whole model to date |
|
||||
| Logic | functional decomposition | unused |
|
||||
| Plane | operational responsibility | unused |
|
||||
| Quality | cross-cutting architecture properties | **unused — and this is where the gaps are** |
|
||||
| Capability | stable capability modeling | partial (`railiance-fabric`, capability registry) |
|
||||
| Intelligence | degree of intelligent automation | unused |
|
||||
|
||||
Railiance has modelled itself almost entirely on the Stack dimension. Anything
|
||||
that did not fit a stack level was treated as an anomaly — "unplaced", "beside
|
||||
the stack", "cross-cutting" — and accumulated as exceptions.
|
||||
|
||||
They were never anomalies. **They are concerns on dimensions Railiance was not
|
||||
using.** The Quality dimension's sub-levels map almost one-to-one onto the
|
||||
capability gaps found independently by this review:
|
||||
|
||||
| Quality sub-level | Canon definition | Railiance concern | State |
|
||||
| --- | --- | --- | --- |
|
||||
| Q1 Security and Compliance | — | credential custody, OpenBao lanes, CCR approval | **implemented** (S3), never named as Q1 |
|
||||
| Q2 Observability | "telemetry and monitoring: metrics, logs, traces" | `railiance-telemetry` | **seeded** 2026-08-11 |
|
||||
| Q3 Operability and Resilience | — | restore drills, rollback proof | split across S1/S3/S5, unowned |
|
||||
| Q4 Isolation and Tenancy | — | `rapp-postgres` ADR-0001, tenant keying | implemented per-consumer, not modelled |
|
||||
| Q5 Performance and Scalability | — | — | unaddressed |
|
||||
| Q6 Cost and Efficiency | — | `resource-control`, `fin-hub`, cost attribution keys | outside the family, boundary undeclared |
|
||||
| Q7 Governance and Change Management | "policies and architecture governance" | **the conformance loop** | unowned (§5.3) |
|
||||
|
||||
Two consequences worth stating plainly:
|
||||
|
||||
1. **`railiance-telemetry` is not an exception to the stack model** — it is Q2
|
||||
Observability, named in canon in exactly those words. Its placement question
|
||||
(§5.1) is effectively answered; `railiance-master` need only ratify it.
|
||||
2. **The conformance loop is Q7**, not a missing stack layer. That reframes
|
||||
§5.3 from "invent a home" to "implement the Quality dimension."
|
||||
|
||||
The recurring "self-evidencing" aspiration across five stack layers (§3) is, in
|
||||
OAS terms, five Stack-dimension repos each independently asking for Q2 and Q7.
|
||||
That is what a missing dimension looks like from inside the one you are using.
|
||||
|
||||
### The layering contract
|
||||
|
||||
|
|
@ -197,22 +248,16 @@ to `railiance-master` (`04c776c4`, amended `f88f938d`).
|
|||
- delete the local `~/railiance-bootstrap` directory, which is a mis-cloned copy
|
||||
of `railiance-cluster.git`
|
||||
|
||||
### 5.6 Does Railiance use ArgoCD at all? → **OPEN**, `railiance-master`
|
||||
### 5.6 Does Railiance use ArgoCD? → **DECIDED 2026-08-11: keep it**
|
||||
|
||||
Raised by the operator 2026-08-11: GitOps-by-ArgoCD may be Helix Forge tooling
|
||||
rather than a Railiance concern, or may not be needed at all.
|
||||
Briefly questioned as possibly Helix Forge tooling rather than a Railiance
|
||||
concern. Resolved on the evidence: S3 runs ArgoCD as its live deployment
|
||||
mechanism — four Application manifests (`external-secrets`, `issue-core`,
|
||||
`openbao-secretstore`, `target-revenue`), AppProjects under `argocd/bootstrap/`,
|
||||
`docs/argocd-gitops.md`, and its two most recent commits add Applications.
|
||||
|
||||
**This cannot be resolved by editing documentation.** S3 currently runs ArgoCD
|
||||
as its live deployment mechanism: four Application manifests
|
||||
(`external-secrets`, `issue-core`, `openbao-secretstore`, `target-revenue`),
|
||||
AppProjects under `argocd/bootstrap/`, `docs/argocd-gitops.md`, and the two most
|
||||
recent commits in this repo add ArgoCD Applications. Removing mentions while the
|
||||
Applications remain would make the documentation describe a system that does not
|
||||
exist.
|
||||
|
||||
The real question is an architecture decision — *should S3 deploy via ArgoCD?* —
|
||||
with a migration attached if the answer is no. Until it is taken, mentions stay
|
||||
because they are accurate.
|
||||
ArgoCD stays and its documentation stays accurate. Relocating GitOps tooling to
|
||||
Helix Forge is noted as possible future cleanup, not current work.
|
||||
|
||||
### 5.5 Rapp granularity and composition → decided, implementation open
|
||||
|
||||
|
|
@ -223,15 +268,31 @@ a stated purpose.
|
|||
|
||||
---
|
||||
|
||||
## 6. Known capability gaps
|
||||
## 6. Known gaps, mapped to dimensions
|
||||
|
||||
| Gap | State |
|
||||
| --- | --- |
|
||||
| Verification substrate | evidence half now owned by `railiance-telemetry` (seeded); conformance half **unowned** (§5.3) |
|
||||
| Observability | home created 2026-08-11; **no implementation**, no monitoring namespace in-cluster |
|
||||
| End-to-end restore proof | split across S1, S3, S5; no single owner; backing object-storage decision escalated and unresolved (`9c21c0e0`) |
|
||||
| Cost and resource attribution | `resource-control` and `fin-hub` hold it; no `railiance-*` INTENT declares the boundary |
|
||||
| Identity dependency declaration | `net-kingdom` referenced in prose; rarely declared structurally. `railiance-fabric` exists to fix this |
|
||||
Read with §2.1: most of these are not scattered omissions but **one unbuilt
|
||||
dimension**.
|
||||
|
||||
| Gap | Dimension | State |
|
||||
| --- | --- | --- |
|
||||
| Observability | Q2 | home created 2026-08-11; **no implementation**, no monitoring namespace in-cluster |
|
||||
| Conformance loop | Q7 | **unowned** (§5.3) |
|
||||
| End-to-end restore proof | Q3 | split across S1, S3, S5; no single owner; backing object-storage decision escalated and unresolved (`9c21c0e0`) |
|
||||
| Cost and resource attribution | Q6 | `resource-control` and `fin-hub` hold it; no `railiance-*` INTENT declares the boundary |
|
||||
| Performance and scalability | Q5 | unaddressed |
|
||||
| Identity dependency declaration | Capability | `net-kingdom` referenced in prose; rarely declared structurally. `railiance-fabric` exists to fix this |
|
||||
|
||||
## 6.1 Contradictions to resolve
|
||||
|
||||
Found by the 2026-08-11 coherence review. These are places where two parts of
|
||||
Railiance currently say different things.
|
||||
|
||||
| # | Contradiction | Resolution |
|
||||
| --- | --- | --- |
|
||||
| C1 | **Capability attribution crosses layer boundaries.** State Hub attributes ~11 capabilities to `railiance-platform`, including Terraform server provisioning and Ansible hardening (S1), k3s provisioning and cluster addons (S2), CI/CD automation (S4), and application workload deployment (S5). `SCOPE.md` declares only four, all correctly S3, and the repo's boundary rule disowns the rest. These are pre-split attributions the hub never dropped. | `SCOPE.md` is source of truth; the hub needs reconciliation. Until then, hub capability data for this repo is not trustworthy for boundary reasoning. |
|
||||
| C2 | **"Five independent repos per OAS Stack layer"** — stated in `SCOPE.md` — contradicts the four-axis model and the current inventory (§4). | Corrected in `SCOPE.md` 2026-08-11. |
|
||||
| C3 | **One dimension in use, six required** by ratified canon (§2.1). | Route to `railiance-master` and `the-custodian`; implement Quality first. |
|
||||
| C4 | **Ecosystem modelling is split four ways** — `railiance-fabric` (graph), State Hub (read model), `reuse-surface` (capability federation), `railiance-master` (vocabulary). Fabric draws the boundary crisply in prose but does not mention `reuse-surface`. | Needs an explicit statement of who owns what; `railiance-master` and `railiance-fabric` territory. |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
30
SCOPE.md
30
SCOPE.md
|
|
@ -14,12 +14,18 @@ S3 Platform Services layer of the Railiance OAS Stack — owns shared cluster se
|
|||
|
||||
## Core Idea
|
||||
|
||||
Railiance is structured as five independent repos per OAS Stack layer. This repo
|
||||
is S3 - the platform services that multiple applications share. The active
|
||||
migration is from Bitnami postgresql-ha (repmgr + pgpool, currently a Gitea
|
||||
subchart in S2) to CloudNative PG (cnpg operator, already deployed in the
|
||||
cnpg-system namespace) as the canonical database operator. Valkey cluster is
|
||||
also in scope for S3 extraction from S2.
|
||||
Railiance classifies repos along four orthogonal axes — `railiance-*`
|
||||
(ownership), `rail-*` (execution contract), `rapp-*` (managed workload package),
|
||||
`reef-*` (substrate boundary). This repo is `railiance-*`, at **S3** on the OAS
|
||||
Stack dimension: the platform services that multiple applications share. Five
|
||||
repos cover S1–S5; other `railiance-*` repos sit on other OAS dimensions rather
|
||||
than on the stack. See `ArchitectureBlueprint.md` for the full backbone.
|
||||
|
||||
The active migration is from Bitnami postgresql-ha (repmgr + pgpool, deployed
|
||||
historically as part of the Gitea subchart in S2 — the forge itself is now
|
||||
Forgejo) to CloudNative PG (cnpg operator, already deployed in the cnpg-system
|
||||
namespace) as the canonical database operator. Valkey cluster is also in scope
|
||||
for S3 extraction from S2.
|
||||
|
||||
OpenBao is a platform capability in this repo, but not every OpenBao-related
|
||||
file belongs in the long-term S3 ownership home. The deployable package surface
|
||||
|
|
@ -75,9 +81,19 @@ policy, and lane governance.
|
|||
- Implementation: CloudNative PG operator (cnpg) deployed; `databases` namespace active; OpenBao is live as the S3 secrets service; Valkey + legacy postgresql-ha extraction from S2 remain in progress
|
||||
- Stability: emerging — cnpg deployed but database cluster definitions not yet migrated from S2
|
||||
- Usage: shared database, cache, and secrets layer; cnpg-system, databases, and openbao namespaces are live
|
||||
- Deploys via ArgoCD: four Applications (`external-secrets`, `issue-core`,
|
||||
`openbao-secretstore`, `target-revenue`) plus AppProjects under
|
||||
`argocd/bootstrap/`; see `docs/argocd-gitops.md`
|
||||
- Emits to `railiance-telemetry` (Q2 Observability) once the evidence plane
|
||||
exists — seeded 2026-08-11, not yet implemented
|
||||
- Open work: Valkey and legacy postgresql-ha extraction remain active; the
|
||||
OpenBao package boundary and PAT consumer cutover are now documented and
|
||||
closed
|
||||
closed; `rapp-openbao`/`rapp-postgres` declaration conformance
|
||||
(`RAILIANCE-WP-0015-T02`) is held pending the `railiance-master` schema
|
||||
- Known drift: State Hub attributes ~11 capabilities to this repo, including
|
||||
S1/S2/S4/S5 concerns it does not own. The four `capability` blocks in this
|
||||
file are authoritative; the hub carries stale pre-split attributions
|
||||
(`ArchitectureBlueprint.md` C1)
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue