railiance-master/docs/fabric-state-hub-adaptation.md

# 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