# Railiance Architecture in Aspiration — an INTENT-based assessment Date: 2026-08-11 Author: Claude (session with Bernd Worsch) Method: read the `INTENT.md` of all ten local `railiance-*` repositories, plus git history, remotes, and the live cluster, and assess what Railiance *says it is trying to become* — not what it currently implements. Status: assessment for discussion. No decisions taken here. --- ## 1. What the ten repos declare `INTENT.md` is explicitly aspirational by its own header ("intentionally aspirational and stable, not a description of current implementation"), so this reads them as a statement of intended architecture. | Repo | Declared role | OAS stack level | | --- | --- | --- | | `railiance-infra` | infrastructure substrate — bare machines to hardened, verified servers | S1 | | `railiance-hosts` | *(identical declaration to infra)* | S1 | | `railiance-cluster` | cluster runtime — hardened servers to orchestration platform | S2 | | `railiance-bootstrap` | *(identical declaration to cluster)* | S2 | | `railiance-platform` | shared platform services — data, cache, secrets, object storage, messaging | S3 | | `railiance-enablement` | developer enablement — paved paths for build, test, package, promote | S4 | | `railiance-apps` | application workloads — platform capabilities to user-facing services | S5 | | `railiance-forge` | forge layer — source hosting, registries, automation runners | **unplaced** | | `railiance-master` | architecture-definition home — vocabulary and boundary model | meta | | `railiance-fabric` | ecosystem graph — repo → service → capability → interface → dependency | meta | Ten repositories, **eight distinct declared intents**, **five OAS stack levels covered**, one layer unplaced, two meta repos. ### The aspiration is coherent Read as a set, the stack tells one clean story: each layer hands the next a *verified* substrate, and each layer refuses to reach past its neighbours. The handoffs are stated from both sides — `railiance-enablement` names a handoff contract with `railiance-forge` for runner labels and registry endpoints; `railiance-apps` names backup and data-ownership handoffs with S3. That is better boundary hygiene than most systems this age have. --- ## 2. The strongest shared thread: **self-evidencing** This was not designed as a cross-cutting principle, but it is the single phrase that recurs across nearly every layer's *Direction of Evolution*: - `railiance-infra` — "Self-evidencing, **auditable** provisioning" - `railiance-cluster` — "Self-evidencing, **auditable** runtime state" - `railiance-platform` — "**Self-healing and observable** platform services" - `railiance-apps` — "Self-evidencing, reviewable **application readiness**" - `railiance-forge` — "Self-evidencing forge **health and readiness** checks" Five layers independently aspire to the same property: *the system should prove its own state rather than be asserted correct*. That is the most important finding in this assessment, for two reasons. First, it is a genuine architectural through-line that no document names as such. It appears five times as a per-layer aspiration and zero times as a Railiance-wide quality dimension. Second, **it is the same principle as the enforcement control loop discussed this session**. The drift found across the rapp family — no schema, a stale reef binding registry, three incompatible declaration shapes — is precisely what happens when "self-evidencing" stays an aspiration in five separate INTENTs and never becomes one implemented verification substrate. The architecture already knows what it wants to be. It has not yet built the thing that would make it true. --- ## 3. Defects found ### 3.1 `railiance-bootstrap` is not a repository It is a **second local clone of `railiance-cluster`** — identical HEAD (`007df2b`), identical commit count (2132), and the same origin (`coulomb/railiance-cluster.git`). It is a stale working copy under a legacy name, not an architectural entity. This has a consequence beyond tidiness: **fleet inventories built by scanning `~` overcount.** The "112 repos under `coulomb/`" figure recorded in `prj-forgejo-org-refactor` counts local directories, not distinct remotes, and is therefore an upper bound rather than a count. The org-refactor inventory task (`ORGREF-WP-0001-T01`) must deduplicate by origin URL, not by directory. ### 3.2 `railiance-hosts` and `railiance-infra` both claim S1 Two **distinct remotes** (`coulomb/railiance-hosts.git`, `coulomb/railiance-infra.git`) with **unrelated git histories** — neither one's HEAD exists in the other — but **byte-identical `INTENT.md`** and near-identical content. This is not a fork; it is a re-creation. `railiance-hosts` has been quiet since 2026-07-30; `railiance-infra` is current. The evidence says hosts was superseded and never retired, but its INTENT still asserts it *is* the infrastructure substrate. Two repos cannot both be the canonical S1 home. Note also that both still carry live hub goals: the domain summary lists "Secure Single-Server Bootstrap at HostEurope" against `railiance-hosts` as a goal needing a workplan — so the fleet is still being asked to do S1 work in the superseded repo. ### 3.3 S4 is aspiration-only `railiance-enablement` has **25 commits, zero workplans**, and has been quiet since 2026-07-30 — while carrying the **most elaborate Direction of Evolution of any layer** (pipeline templates, image promotion conventions, GitOps review and rollback, forge handoff contracts, self-service templates, SDKs, release evidence). This is the widest aspiration-to-reality gap in the family. It matters more than it looks: S4 is the layer that would naturally host the paved path for *verifying* things — the control loop's likely home. ### 3.4 `railiance-forge` is unplaced in the stack dimension It declares itself "the forge layer", but OAS defines exactly five stack levels and forge is not one of them. It is not clear whether forge is: - part of S4 (developer enablement), which its handoff contract suggests, or - a sixth stack level, or - a cross-cutting capability that sits outside the stack dimension entirely. Undeclared placement is how layer boundaries erode. This should be settled explicitly in `railiance-master`. ### 3.5 `railiance-fabric` diverges in form and may be dormant It is the only `railiance-*` repo whose `INTENT.md` does not follow the family template — different headings, a date stamp, no One-liner in the standard shape. It has been quiet since 2026-07-30. Its content is *good* — the boundary it draws is unusually crisp ("repositories own declarations, Railiance Fabric owns the graph model, State Hub owns the read model"). But its concept set (repo → service → capability → interface → dependency) overlaps the capability registry, `reuse-surface` federation, and State Hub, and its relationship to `railiance-master` needs stating: master owns the *vocabulary and boundaries*, fabric owns the *graph model of the same entities*. That split is defensible but currently only implicit. --- ## 4. What we may be missing The question was explicitly asked, so these are gaps in the *aspiration*, not just in the implementation. ### 4.1 Nobody owns the verification substrate Five layers aspire to be self-evidencing. **No repo declares ownership of the mechanism** that would evaluate those claims — no INTENT names a verification, conformance, or control-loop responsibility. This is the structural cause of the drift found earlier this session. Each layer is expected to prove itself, individually, by convention. Candidates for the home: S4 (`railiance-enablement`, as the paved-path layer), `railiance-master` (as the definition home), or a new responsibility repo. This is the single most consequential gap in the family. ### 4.2 No observability home `railiance-platform` aspires to "observable" services and `railiance-cluster` to "continuous health verification", but **no repo owns monitoring, metrics, alerting, or dashboards** as a declared responsibility. The live cluster confirms the gap: no monitoring namespace exists (`kubectl get ns` shows no prometheus, grafana, or equivalent). A system whose central aspiration is self-evidencing has no place to send the evidence. ### 4.3 Restore proof is split three ways with no owner Backup and recovery appear in `railiance-infra` (at-rest secret material), `railiance-platform` (durability, backup, disaster recovery), and `railiance-apps` (backup/restore/data-ownership handoffs). The seed concepts document lists "Restore Drill" as a first-class Railiance concept. But no repo owns *proving a restore works* end to end, and the backing object storage decision is still unresolved and escalated (`9c21c0e0`). Split responsibility plus an unmade procurement decision is how restore drills stay theoretical. ### 4.4 Cost and resource attribution sit outside the family `resource-control` and `fin-hub` carry cost evidence and billing basis workplans, and `rapp-postgres` already emits a `cost_attribution_key` per consumer. No `railiance-*` INTENT declares a boundary with them. The platform generates the cost; the accounting lives elsewhere; the interface is undeclared. ### 4.5 Identity is depended on but rarely declared `net-kingdom` owns identity, credentials, and security architecture, and is referenced in prose across the family — but most `railiance-*` INTENTs do not declare it as a dependency in a structured way. `railiance-fabric` is the exception and the one repo built to fix exactly this. --- ## 5. Bearing on "where do Railiance contexts live?" The question that prompted this assessment. The `railiance-*` family **is** the ownership-and-responsibility axis of the four-axis model. So a "Railiance context" for these repos is not a new grouping to invent — it is the **stack level each repo occupies**, plus a category for the meta repos that sit outside the stack. That suggests: - the natural declaring home is **`railiance-master`**, which already owns repository taxonomy and boundary definitions; - the mapping is nearly mechanical for eight of ten repos (S1–S5 plus two meta); - but it **cannot be completed** until three things are settled: where `forge` sits (§3.4), which of `hosts`/`infra` is canonical S1 (§3.2), and whether `bootstrap` is deleted as a local artifact (§3.1). Those three are small, and settling them makes the railiance-family context assignment fall out almost for free — which is a good argument for doing this family first, as proposed. --- ## 6. Summary **The aspiration is in better shape than the inventory.** Eight coherent, well-bounded declared intents with explicitly stated handoffs is a genuinely good architectural statement. The problems are not conceptual confusion: - two duplicate identities (one a local clone artifact, one a superseded repo still asserting canonical status), - one layer unplaced in the stack dimension, - one layer (S4) that is almost entirely aspiration, - and four capability gaps — verification substrate, observability, restore proof, cost interface — of which **the verification substrate is the one that matters most**, because five separate layers already declare they want it and none of them owns it.