diff --git a/ArchitectureBlueprint.md b/ArchitectureBlueprint.md index 79da04b..a9b2d1e 100644 --- a/ArchitectureBlueprint.md +++ b/ArchitectureBlueprint.md @@ -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. | --- diff --git a/SCOPE.md b/SCOPE.md index 3bd4753..24ed9fd 100644 --- a/SCOPE.md +++ b/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) ---