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.