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 workstreams, 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: active planning
Implementation: intent and first workplan present
Stability: evolving
Usage: internal Railiance ecosystem modeling

The first workplan is RAIL-FAB-WP-0001, which establishes vocabulary, schema, seed examples, validator/query tooling, and State Hub integration.

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.

repo-scoping — explains what a repo is useful for; Railiance Fabric models what repos provide and consume.
the-custodian/state-hub — coordinates domains, workstreams, 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: INTENT.md
Key files / directories: workplans/
Entry points: workplans/RAIL-FAB-WP-0001-ecosystem-graph-model.md

Provided Capabilities

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.

4.4 KiB Raw Blame History