generated from coulomb/repo-seed
140 lines
4.4 KiB
Markdown
140 lines
4.4 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## 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, 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
|
|
|
|
```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.
|