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, rapps, 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 rapps?
• 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, rapps, 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 rapps 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 rapps

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 rapps
• 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, rapps, 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