Add ArchitectureBlueprint.md as the structural backbone
Consolidates what this session established: the four orthogonal repo-family axes and the separation rule that keeps Forgejo orgs, State Hub domains and rapp contexts from being derived from each other; the stack levels plus the concerns that sit beside the stack; the self-evidencing thread and its two halves (evidence plane, now owned by railiance-telemetry, and the conformance loop, still unowned); verified repository status including the two superseded lineages; and the open placement decisions, each naming railiance-master as the decider rather than settling them here. Records that the railiance-forge retirement hypothesis was tested and rejected - it and helix-forge are different lineages, one operational and one methodological - so forge should be placed, not retired. Also notes for tooling that the bootstrap/cluster/hosts/infra repos have unrelated histories but near-identical content, so fleet inventories must deduplicate by origin URL rather than by directory. SCOPE.md gains the telemetry emission relationship and a pointer to the blueprint. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
codex
parent
3f586cfada
commit
20c5dc831e
2 changed files with 224 additions and 0 deletions
218
ArchitectureBlueprint.md
Normal file
218
ArchitectureBlueprint.md
Normal file
|
|
@ -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)
|
||||
6
SCOPE.md
6
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
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue