railiance-fabric/SCOPE.md

# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.

---

## One-liner

Defines the Railiance ecosystem graph model so repos can declare services,
capabilities, interfaces, dependencies, and bindings in source-controlled files.

---

## Core Idea

Railiance Fabric turns implicit cross-repo dependencies into a reviewable graph.
Participating repos remain the source of truth for what they provide and
consume; this repo owns the shared schema, validation rules, graph construction,
query tooling, seed examples, and export format that State Hub can ingest as a
read model.

---

## In Scope

- YAML declaration schemas for services, capabilities, interfaces,
  dependencies, and binding assertions.
- Capability and interface type catalogs for the Railiance ecosystem.
- Seed declarations for core Railiance providers and consumers.
- Local graph loading, validation, discovery queries, and export tooling.
- State Hub ingestion contract for graph exports.
- Adoption guidance for adding declarations to other repos.

---

## Out of Scope

- Deployment orchestration or GitOps ownership.
- Replacing State Hub workplans, tasks, decisions, or progress events.
- Replacing repo-scoping, SCOPE.md, ADRs, service meshes, secret managers, or
  authorization engines.
- Making State Hub the authoring surface for capability declarations.
- Runtime traffic discovery that bypasses repo-owned declarations.

---

## Relevant When

- You need to declare what a Railiance repo provides or consumes.
- You need to ask which services depend on a capability or interface.
- You need to validate missing providers, stale interfaces, or compatibility
  issues before sequencing work.
- You need a graph export that State Hub can display without owning the source
  declarations.

---

## Not Relevant When

- You are deploying infrastructure rather than modeling its ecosystem contract.
- You need to manage State Hub tasks, decisions, messages, or progress events.
- You need service-specific implementation details owned by another repo.
- You need an authorization, secret-management, or package-registry runtime.

---

## Current State

- Status: operational / evolving
- Implementation: registry service, graph validation and query tooling, graph
  explorer, State Hub export contract, financial-fabric reset flow, and local
  onboarding manifests are all present
- Stability: evolving but operational
- Usage: internal Railiance ecosystem modeling, registry onboarding, and graph
  export work

The current repo-family follow-on wave is `RAIL-FAB-WP-0026`, which projects
the first declaration-backed `rail-*`, `rapp-*`, and `reef-*` relations on top
of the compatibility-first groundwork from `RAIL-FAB-WP-0025`.

---

## How It Fits

- Upstream dependencies: repo-owned declarations in participating Railiance
  repos.
- Downstream consumers: State Hub read model, documentation, dashboards, and
  agent planning flows.
- Often used with: `repo-scoping`, `the-custodian/state-hub`,
  `railiance-platform`, `net-kingdom`, `flex-auth`, and `artifact-store`.

---

## Terminology

- Preferred terms: repository, service, capability, interface, dependency,
  binding.
- Also known as: ecosystem graph, capability graph, dependency graph.
- Potentially confusing terms: State Hub is the read/cache/index layer here,
  not the authoring source for declarations.

---

## Related / Overlapping Repositories

- `repo-scoping` — explains what a repo is useful for; Railiance Fabric models
  what repos provide and consume.
- `the-custodian/state-hub` — coordinates domains, workplans, tasks, and
  progress; it should ingest Fabric graph exports as a read model.
- `railiance-platform` — deploys shared platform services that should become
  graph provider nodes.
- `net-kingdom` — owns identity, credential, and security architecture that
  appears in capability/interface declarations.
- `flex-auth` — owns authorization policy and decision semantics that should be
  represented as graph capabilities and interfaces.

---

## Getting Oriented

- Start with: `README.md`, `INTENT.md`
- Key files / directories: `catalog/`, `fabric/`, `registry/`, `schemas/`,
  `workplans/`
- Entry points: `docs/registry-onboarding.md`,
  `docs/rail-rapp-reef-adaptation.md`,
  `workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md`

---

## Provided Capabilities

```capability
type: tooling
title: Railiance ecosystem graph model
description: Shared declaration schema, validation model, query tooling, and State Hub export contract for Railiance service/capability/dependency graphs.
keywords: [railiance, graph, capabilities, dependencies, interfaces, state-hub]
```

---

## Notes

Repos own declarations. Railiance Fabric owns graph semantics and validation.
State Hub owns coordination and display of ingested read models.