diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 9eae32e..3d20668 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -17,6 +17,7 @@ | workplan | RAILIANCE-WP-0013 | finished | — | workplans/RAILIANCE-WP-0013-forgejo-admin-pat-openbao-cutover.md | | workplan | RAILIANCE-WP-0014 | finished | — | workplans/RAILIANCE-WP-0014-credential-change-suite-stabilization.md | | workplan | RAILIANCE-WP-0015 | active | — | workplans/RAILIANCE-WP-0015-platform-rapp-consistency.md | +| workplan | RAILIANCE-WP-0016 | ready | — | workplans/RAILIANCE-WP-0016-apps-pg-resource-evidence.md | | task | RAILIANCE-WP-0005-T01 | done | — | workplans/RAILIANCE-WP-0005-credential-request-and-lease-broker.md | | task | RAILIANCE-WP-0005-T02 | done | — | workplans/RAILIANCE-WP-0005-credential-request-and-lease-broker.md | | task | RAILIANCE-WP-0005-T03 | done | — | workplans/RAILIANCE-WP-0005-credential-request-and-lease-broker.md | @@ -68,3 +69,6 @@ | task | RAILIANCE-WP-0015-T04 | done | — | workplans/RAILIANCE-WP-0015-platform-rapp-consistency.md | | task | RAILIANCE-WP-0015-T05 | done | — | workplans/RAILIANCE-WP-0015-platform-rapp-consistency.md | | task | RAILIANCE-WP-0015-T06 | todo | — | workplans/RAILIANCE-WP-0015-platform-rapp-consistency.md | +| task | RAILIANCE-WP-0016-T01 | todo | — | workplans/RAILIANCE-WP-0016-apps-pg-resource-evidence.md | +| task | RAILIANCE-WP-0016-T02 | todo | — | workplans/RAILIANCE-WP-0016-apps-pg-resource-evidence.md | +| task | RAILIANCE-WP-0016-T03 | todo | — | workplans/RAILIANCE-WP-0016-apps-pg-resource-evidence.md | diff --git a/history/2026-08-11-railiance-architecture-in-aspiration.md b/history/2026-08-11-railiance-architecture-in-aspiration.md new file mode 100644 index 0000000..9fea4d0 --- /dev/null +++ b/history/2026-08-11-railiance-architecture-in-aspiration.md @@ -0,0 +1,240 @@ +# 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. diff --git a/workplans/RAILIANCE-WP-0016-apps-pg-resource-evidence.md b/workplans/RAILIANCE-WP-0016-apps-pg-resource-evidence.md new file mode 100644 index 0000000..3524d39 --- /dev/null +++ b/workplans/RAILIANCE-WP-0016-apps-pg-resource-evidence.md @@ -0,0 +1,78 @@ +--- +id: RAILIANCE-WP-0016 +type: workplan +title: "Publish apps-pg resource and recovery evidence" +domain: financials +repo: railiance-platform +status: ready +owner: codex +topic_slug: railiance +created: "2026-08-11" +updated: "2026-08-11" +related: + - RAILIANCE-WP-0003 + - RESOURCE-WP-0003 +state_hub_workstream_id: "49084fb8-de63-4f32-a4a9-3a42d4e708ac" +--- + +# RAILIANCE-WP-0016 — apps-pg resource evidence + +## Goal + +Provide platform-owned evidence for `resource:railiance:apps-pg`: demand, +utilization, recovery, operations labor, and consumer allocation. Origin: +`RESOURCE-WP-0003-T04` delegated evidence gap. + +## T01 — Publish database capacity and utilization + +```task +id: RAILIANCE-WP-0016-T01 +status: todo +priority: high +state_hub_task_id: "c772bcea-7ae0-4532-b434-31f75c905431" +``` + +Record instance count, CPU/memory requests and observed use, provisioned and +used storage, database growth, connections, I/O or other available saturation +proxies, and consumer database attribution with timestamps and provenance. + +Done when resource-control can forecast database capacity without reading +application data or credentials. + +## T02 — Publish recovery and operational evidence + +```task +id: RAILIANCE-WP-0016-T02 +status: todo +priority: high +state_hub_task_id: "4eafebd5-0434-42a2-a126-c292c29c1f21" +``` + +Record backup coverage, restore-test results, recovery objectives, upgrade and +maintenance cadence, incidents, and setup/recurring operator labor. Keep +service procedures and execution in railiance-platform. + +Done when the portfolio can distinguish verified recovery, unresolved local +storage risk, and platform labor cost. + +## T03 — Define shared database allocation drivers + +```task +id: RAILIANCE-WP-0016-T03 +status: todo +priority: medium +state_hub_task_id: "fc329443-a2fc-4409-b670-dfb103df2794" +``` + +Publish candidate consumer drivers such as database storage GB-month, +connections, transactions, or measured I/O. Include shared overhead, +unattributed residual, method version, and uncertainty. + +Done when resource-control can allocate a referenced apps-pg cost without +making railiance-platform a financial ledger. + +## Acceptance + +- [ ] Capacity and utilization evidence is consumer-aware and non-secret. +- [ ] Recovery and labor evidence is timestamped and verifiable. +- [ ] Shared allocation drivers reconcile with explicit residuals.