diff --git a/ArchitectureBlueprint.md b/ArchitectureBlueprint.md new file mode 100644 index 0000000..0dfbb98 --- /dev/null +++ b/ArchitectureBlueprint.md @@ -0,0 +1,218 @@ +# Railiance Architecture Blueprint + +> The structural backbone of Railiance: the axes along which repositories are +> classified, the layers of the stack, and the rules that keep them from +> collapsing into each other. +> +> **Status:** working blueprint, established 2026-08-11. Structural claims here +> are verified; items marked **OPEN** are undecided and name their deciding +> repo. This file records structure, not runtime state — for what is currently +> deployed, see each repo's `SCOPE.md`. +> +> **Authority note:** `railiance-master` owns the repo-family model and +> `the-custodian` owns canon. This blueprint consolidates and applies them from +> the S3 perspective; where the two disagree, they win. + +--- + +## 1. Four classification axes + +Railiance classifies repositories along four **orthogonal** axes. They are +complementary, not competing — a workload has a position on all four. + +| Prefix | Axis | Unit | Answers | +| --- | --- | --- | --- | +| `railiance-*` | ownership and responsibility | one architectural responsibility area | who owns this capability or layer? | +| `rail-*` | execution contract | one workload execution architecture | how does a workload run here? | +| `rapp-*` | managed workload package | one Railiance-managed workload | what exactly is packaged and operated? | +| `reef-*` | substrate boundary | one durable substrate reality | where does this run, and what is bound there? | + +Source: `railiance-master/docs/repository-axes.md`. + +### The separation rule + +Independent perspectives stay in separate dimensions. This is **normative**, +not stylistic — OAS P1, `canon/standards/orthogonal-architecture_v1.0.md`: +*"Architecture descriptions MUST separate independent perspectives into +orthogonal dimensions."* + +Three groupings are routinely confused and must not be derived from each other: + +| Grouping | Answers | Cardinality to repos | Changes | +| --- | --- | --- | --- | +| Forgejo org | who may push; what is discoverable together | 1:many | slowly (renames break clone URLs, CI, GitOps sources) | +| State Hub domain | which strand of work, for attention and priority | 1:many | occasionally | +| **Rapp context** | what deploys, versions and rolls back together | **many:many** | often | + +A repo lives in exactly one Forgejo org — it is a path segment in the clone URL. +A repo may contribute to several rapps. **A many:many grouping cannot be derived +from a 1:many one.** Decision `d07ee5f9`. + +**The cardinality that makes enforcement possible:** repos are many:many with +rapps, but **deployables are 1:1** — each running deployable has exactly one +rapp owning its rollout. That is what makes the coverage check well-formed: +*does every live deployable belong to exactly one rapp?* + +--- + +## 2. The stack + +The OAS Stack dimension defines five levels. Railiance implements them as +responsibility repos, plus cross-cutting and meta concerns that sit beside the +stack rather than inside it. + +| Level | Repo | Owns | +| --- | --- | --- | +| S1 | `railiance-infra` | OS provisioning, hardening, server baseline, at-rest bootstrap secrets | +| S2 | `railiance-cluster` | k3s, Helm, ingress, CNI, admission controllers, operators, kubeconfig | +| S3 | `railiance-platform` | shared stateful services: data, cache, secrets, object storage, messaging | +| 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 | +| --- | --- | --- | +| 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 (**OPEN** placement, §5.2) | + +### The layering contract + +Each layer hands the next a **verified** substrate and does not reach past its +neighbours. The handoffs are declared from both sides — S4 names its forge +contract for runner labels and registry endpoints; S5 names backup and +data-ownership handoffs with S3. Preserve this property when editing any +`INTENT.md`: a handoff stated by only one side is a latent boundary dispute. + +--- + +## 3. The self-evidencing thread + +Five layers independently declare the same aspiration in their +`Direction of Evolution`: + +- S1 — "self-evidencing, auditable provisioning" +- S2 — "self-evidencing, auditable runtime state" +- S3 — "self-healing and observable platform services" +- S5 — "self-evidencing, reviewable application readiness" +- forge — "self-evidencing forge health and readiness checks" + +**This is the architectural through-line of Railiance**: the system should prove +its own state rather than be asserted correct. It reached five INTENT files +independently and was never named as a fleet-wide quality dimension. + +It has two halves, and they belong to different repos: + +| Half | Question | Home | +| --- | --- | --- | +| **Evidence plane** | is the running system behaving as expected? | `railiance-telemetry` | +| **Conformance loop** | do declarations match reality and each other? | **OPEN** (§5.3) | + +Both are required. Observability without conformance checking finds outages but +not drift; conformance checking without observability finds drift but not +outages. + +--- + +## 4. Repository status + +Not every `railiance-*` directory is a canonical repository. Verified +2026-08-11 by comparing remotes, HEADs, and working trees. + +| Repo | Status | Evidence | +| --- | --- | --- | +| `railiance-infra` | **canonical S1** | active; strict content superset of `hosts` | +| `railiance-hosts` | **superseded** | distinct remote, unrelated history, byte-identical `INTENT.md`, **zero unique files**; quiet since 2026-07-30 | +| `railiance-cluster` | **canonical S2** | active; has `install/` and rail-kubernetes extraction docs | +| `railiance-bootstrap` | **superseded as S2; repurpose candidate** | distinct remote, unrelated history, declares itself S2 verbatim; frozen 2026-07-08. Carries `QUICKSTART.md` (newcomer path) — candidate home for *seeding a new Railiance* | +| `railiance-platform` | canonical S3 | active | +| `railiance-enablement` | canonical S4, **aspiration-only** | 25 commits, 0 workplans; widest aspiration-to-reality gap in the family | +| `railiance-apps` | canonical S5 | active | +| `railiance-telemetry` | **seeded** 2026-08-11 | `INTENT.md`/`SCOPE.md` written; no implementation | +| `railiance-master` | canonical meta | active | +| `railiance-fabric` | canonical meta | quiet since 2026-07-30; non-standard `INTENT.md` format | +| `railiance-forge` | canonical, **unplaced** | active workplan; not on any stack level | + +### The duplication pattern + +`bootstrap`, `cluster`, `hosts`, `infra` have **mutually unrelated git +histories but near-identical content**. They were created by copying working +trees into fresh repos as the S1/S2 layering idea emerged — not by forking. +Two lineages, each with a frozen elder and an active successor. + +Consequence for tooling: **fleet inventories built by scanning directories +overcount.** Deduplicate by origin URL, not by directory name. + +--- + +## 5. Open decisions + +Each names the repo that decides it. None should be settled in `railiance-platform`. + +### 5.1 Where does `railiance-telemetry` sit? → `railiance-master` + +Observability is cross-cutting: it draws signal from every level and is consumed +by all of them. Is it an S3 platform capability (it runs stateful services and +is consumed by others), or a Quality-dimension concern outside the Stack +dimension? Stated explicitly at seeding so it does not drift into §5.2's state. + +### 5.2 Where does `railiance-forge` sit? → `railiance-master` + +It calls itself "the forge layer", but the stack has five levels and forge is +not one. Options: part of S4, a sixth level, or cross-cutting. + +Note the retirement hypothesis was **tested and rejected**: `railiance-forge` +and `helix-forge` are different lineages. `helix-forge` is methodological +(capability-first ecosystem, OAS dimensions, VSM vocabulary); `railiance-forge` +is operational (`helm/`, `manifests/`, `releases/`, `runner/`, live workplan on +Forgejo resource economics). Retiring it would orphan runner placement, registry +retention, and artifact lifecycle. **Place it, do not retire it.** The likely +resolution: the Forgejo *workload* becomes `rapp-forgejo`; the *layer* +responsibility folds into S4, which already declares the handoff contract. + +### 5.3 Who owns the conformance loop? → `railiance-master` + +Candidates: S4 (the paved-path layer), `railiance-master` (the definition home), +or a new responsibility repo. Related: the family declaration validator proposed +to `railiance-master` (`04c776c4`, amended `f88f938d`). + +### 5.4 Retirement and repurposing → `railiance-master`, then the repos + +- retire `railiance-hosts` (content-safe; **check git history before deletion**, + and move its live hub goal "Secure Single-Server Bootstrap at HostEurope" to + `railiance-infra` first, or it resurfaces as unstarted S1 work) +- repurpose `railiance-bootstrap` as the seed-a-new-Railiance repo, consolidating + the newcomer path that currently exists in both it and `railiance-cluster` +- delete the local `~/railiance-bootstrap` directory, which is a mis-cloned copy + of `railiance-cluster.git` + +### 5.5 Rapp granularity and composition → decided, implementation open + +Grouped by bounded context; members declared explicitly; grouping legitimate +only where members share rollout and rollback fate (`7a1f7a7e`). A rapp declares +a **composition**: first-party member repos plus pinned upstream components plus +a stated purpose. + +--- + +## 6. Known capability gaps + +| 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 | + +--- + +## 7. Sources + +- `railiance-master/docs/repository-axes.md` — the four families +- `railiance-master/docs/repo-family-bootstrap-contract.md` — required declarations +- `railiance-master/docs/rapp-first-wave-candidates.md` — extraction criteria and sequencing +- `the-custodian/canon/standards/orthogonal-architecture_v1.0.md` — OAS, P1 +- `railiance-platform/docs/rapp-platform-service-pattern.md` — S3 platform-service pattern +- `railiance-platform/history/2026-08-11-railiance-architecture-in-aspiration.md` — the INTENT-based assessment behind this blueprint +- decisions `7a1f7a7e` (rapp granularity), `d07ee5f9` (dimensional separation) diff --git a/SCOPE.md b/SCOPE.md index 590252e..3bd4753 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -86,6 +86,12 @@ policy, and lane governance. - Upstream dependencies: railiance-cluster (S2) — k3s running, Helm available, smoke tests passing - Downstream consumers: railiance-enablement (S4), railiance-apps (S5) — all depend on platform services - Often used with: net-kingdom (identity services integration), railiance-cluster (prior layer) +- Emits to: railiance-telemetry (evidence plane) — S3 services are expected to + emit health and readiness through the standard emission contract rather than + per-service bespoke integrations +- Structural backbone: `ArchitectureBlueprint.md` in this repo records the four + repo-family axes, the stack, repository status, and the open placement + decisions that `railiance-master` owns ---