railiance-platform/history/2026-08-11-railiance-architecture-in-aspiration.md

# 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.