Establish Railiance architecture home

docs/fabric-state-hub-adaptation.md

@@ -0,0 +1,187 @@
+# Fabric And State Hub Adaptation For `rail-*`, `rapp-*`, And `reef-*`
+
+Date: 2026-07-25
+
+## Purpose
+
+List the minimum adaptation requirements so rails, `rapp`s, and reefs become
+visible ecosystem entities rather than only naming conventions.
+
+This is a requirements document, not an implementation plan for one repo.
+
+## Current Gaps
+
+The current ecosystem tooling still reflects the older repo shape.
+
+Observed gaps:
+
+- `railiance-fabric/registry/railiance-repos.yaml` does not yet onboard
+  `railiance-master` or `railiance-forge`.
+- Fabric has a `kubernetes-runtime` capability type, but no first-class
+  vocabulary for execution rails, managed workload packages, or substrate
+  boundaries.
+- `railiance-apps` is modeled as one aggregate S5 release surface rather than a
+  future set of `rapp-*` package repos.
+- State Hub registration and generated repo summaries do not expose repo family
+  or rail/rapp/reef-specific metadata.
+
+If left unchanged, Git will know the new taxonomy before the coordination and
+graph systems do.
+
+## Minimum Questions The Systems Must Answer
+
+After adaptation, the systems should be able to answer at least:
+
+- which `rail-*` repos exist?
+- which rail is the default base rail?
+- which `rapp-*` packages support which rails?
+- which reefs host which rails?
+- which reefs bind or approve which `rapp`s?
+- which ownership repo remains responsible for a given rail, `rapp`, or reef?
+
+## Minimal State Hub Requirements
+
+State Hub does not need a second work-tracking model, but it does need better
+repo metadata.
+
+### Required repo metadata
+
+Add or derive the following repo-level concepts:
+
+- `repo_family`: `ownership` | `rail` | `rapp` | `reef`
+- `ownership_repo`: canonical owning `railiance-*` repo when the repo family is
+  not `ownership`
+- `primary_rail`: for reefs or workloads where one rail is the declared default
+- `supported_rails`: for `rapp-*` repos
+- `substrate_kind`: for `reef-*` repos, such as `server`, `cluster`,
+  `workstation-group`, or `edge`
+
+These fields may start in `.repo-classification.yaml` or a repo-local
+companion metadata file if the classification schema should stay smaller.
+
+### Required indexing behavior
+
+- State Hub should index `rail-*`, `rapp-*`, and `reef-*` repos like any other
+  repo for workplans, tasks, and progress.
+- Generated repo briefs should display repo family and any declared ownership
+  repo or primary rail when available.
+- Repo search and inventory views should be filterable by repo family.
+
+### Not required
+
+- no separate workplan model for rails, `rapp`s, or reefs
+- no special task state machine
+- no custom approval workflow just because a repo uses one of the new prefixes
+
+## Minimum Fabric Requirements
+
+Fabric needs enough typed vocabulary to model the new repo families without
+waiting for a perfect new object taxonomy.
+
+### Immediate onboarding requirements
+
+- add `railiance-master` to `registry/railiance-repos.yaml`
+- add `railiance-forge` to `registry/railiance-repos.yaml`
+- be ready to add future `rail-*`, `rapp-*`, and `reef-*` repos as first-class
+  registered repositories
+
+### Immediate modeling requirements
+
+Fabric should add typed representation for:
+
+- execution rails
+- managed workload packages
+- substrate boundaries
+
+The minimum viable way to do that is:
+
+- add repo-family-aware metadata in registration and graph export
+- add new `service_type` values:
+  - `execution-rail`
+  - `managed-workload-package`
+  - `substrate-boundary`
+- add one new capability type for rails:
+  - `workload-execution-contract`
+
+This keeps the first rail queryable as a provider-like ecosystem object without
+forcing `rapp`s and reefs into the wrong provider/consumer semantics.
+
+### Relation requirements
+
+Fabric needs explicit relations for:
+
+- `supports_rail`: `rapp` -> `rail`
+- `hosts_rail`: reef -> `rail`
+- `binds_rapp`: reef -> `rapp`
+- `governed_by`: rail/`rapp`/reef -> ownership repo
+
+These relations may begin as projected registry edges even if the declaration
+schema evolves later.
+
+The important part is that the graph can answer the topology questions above.
+
+## Minimum Repo-Local Declaration Requirements
+
+Every future repo family needs a small, obvious declaration surface.
+
+### `rail-*`
+
+Minimum declaration concepts:
+
+- rail id
+- owning repo
+- execution architecture
+- substrate prerequisites
+- supported rollout modes
+- compatibility notes for participating `rapp`s
+
+### `rapp-*`
+
+Minimum declaration concepts:
+
+- workload package id
+- upstream or source workload identity
+- owning repo
+- supported rails
+- runtime dependencies
+- rollout, smoke, and rollback contract
+
+### `reef-*`
+
+Minimum declaration concepts:
+
+- substrate id
+- substrate kind
+- lifecycle and criticality
+- hosted rails
+- bound or approved `rapp`s
+- primary rail, if one exists
+
+These declarations may begin as repo-local YAML files or be projected from
+existing source files. The key requirement is that they are source-controlled
+and ingestible.
+
+## Compatibility Guidance
+
+Do not block the repo-family rollout on a perfect Fabric redesign.
+
+Recommended compatibility-first path:
+
+1. register the repos and family metadata
+2. add the minimum new service and relation vocabulary
+3. let the first `rail-*`, `rapp-*`, and `reef-*` repos publish small
+   declaration files
+4. ingest those declarations into Fabric and State Hub projections
+5. only then decide whether stronger first-class schema kinds are needed
+
+This avoids waiting for a large graph refactor before the architecture can move.
+
+## Outcome
+
+The minimal adaptation target is:
+
+- State Hub understands which repo family a repo belongs to
+- Fabric can show rails, `rapp`s, and reefs as typed ecosystem entities
+- the graph can answer rail/package/substrate placement questions
+- new repo families are coordinated by the same workplan and progress system as
+  the existing Railiance repos