coulomb/railiance-fabric
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: finish financial fabric reset guidance

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-24 01:37:05 +02:00
parent 9717b18b02
commit f4aa4aa996
16 changed files with 304 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/canon-alignment-review.md
View File

@@ -65,7 +65,7 @@ Consumer purposes:
| Canon category | Current Fabric source | Fit | Target action |
| --- | --- | --- | --- |
| source-repository | `Repository` candidates and registered repos | direct | Keep as source of truth for repo-owned declarations and scans. |
| source-repository | `Repository` candidates and registered repos | direct | Keep as source evidence for repo-local declarations and scans. |
| service | `ServiceDeclaration` | direct | Keep as logical/deployable service boundary. |
| software-system | `CapabilityDeclaration`, `Library`, `ExternalLibrary` | partial | Keep as transitional mapping; later split capability semantics from system/component boundaries. |
| endpoint | `InterfaceDeclaration`, `ApplicationEndpoint`, `NetworkPort`, `DomainName` | partial/direct | Prefer explicit endpoint nodes for network reachability; preserve interface contract attributes. |

2
docs/canon-interface-card.yaml
View File

@@ -5,7 +5,7 @@ consumer:
repo: railiance-fabric
domain: railiance
owner: codex
intent: Make the Railiance ecosystem understandable, discoverable, and evolvable through repo-owned graph declarations and discovery output.
intent: Make the Railiance ecosystem understandable, discoverable, and evolvable through accepted Fabric snapshots, accountability-root discovery, and repo-local evidence.
scope: Shared schemas, validation, graph construction, registry projections, scanner output, and State Hub export contracts for repository, service, capability, interface, dependency, binding, and runtime discovery data.
purposes:
- id: purpose/graph-refactor

14
docs/declaration-schema.md
View File

@@ -1,12 +1,18 @@
# Declaration Schema
Railiance Fabric declarations are small YAML documents owned by the repository
that provides or consumes the declared thing. The first schema version is
Railiance Fabric declarations are small YAML documents that capture repo-local
self-description evidence. The first schema version is
`railiance.fabric/v1alpha1`.
These declarations are still supported for bootstrap and compatibility, but
they are not the long-term authority for external deployment realities,
financial fabric boundaries, tenant subfabrics, or cross-boundary utility
relations. The financial Fabric model starts from accountability roots as
described in `docs/FabricDiscoveryAndUpdate.md`.
## File Layout
Participating repositories should use this layout:
Participating repositories that publish local evidence should use this layout:
```text
fabric/
@@ -56,7 +62,7 @@ begin with the owning repo slug when possible:
| `kind` | Declaration kind: service, capability, interface, dependency, or binding assertion. |
| `metadata.id` | Stable graph identifier used for references and bindings. |
| `metadata.name` | Human-readable display name. |
| `metadata.owner` | Owning team, repo, or domain owner. |
| `metadata.owner` | Local evidence owner for the declaration; financial Fabric ownership is resolved separately. |
| `metadata.repo` | Repo slug that owns the declaration. |
| `metadata.domain` | Domain slug, such as `railiance` or `custodian`. |
| `metadata.source_links` | Optional source pointers to docs, code, manifests, ADRs, or workplans. |

14
docs/discovery-queries.md
View File

@@ -1,7 +1,7 @@
# Discovery Queries And Exports
Railiance Fabric includes a first CLI surface for inspecting local declaration
graphs.
graphs and projecting them into the current financial Fabric baseline.
All commands accept a repo root, `fabric/` directory, or declaration files. When
paths are omitted, commands read `./fabric`.
@@ -84,6 +84,12 @@ Export the graph as the manifest-compatible graph explorer payload:
railiance-fabric export --format graph-explorer
```
Export the graph as the financial Fabric baseline projection:
```bash
railiance-fabric export --format financial
```
The JSON export has two top-level arrays:
- `nodes`: service, capability, interface, dependency, and binding nodes
@@ -99,3 +105,9 @@ The graph explorer payload wraps those nodes and edges as Cytoscape-compatible
elements with stable keys, layers, display state, visual facets, source
references, and deep links. The registry service exposes the same projection at
`GET /exports/graph-explorer`.
The financial export emits `railiance.fabric/v1alpha2` /
`financial-fabric-v1`. It combines the current legacy graph evidence with
`fabric/financial/railiance-netkingdom.yaml`, assigning inherited ownership and
fabric containment for the current single Railiance fabric. Use it as the reset
contract and State Hub vNext handoff artifact.

14
docs/ecosystem-registry-service.md
View File

@@ -7,12 +7,16 @@ services, capabilities, interfaces, and dependencies.
## Recommendation
Build a small Railiance Ecosystem Registry service as the API and indexed read
model over repo-owned Fabric declarations.
model over accepted Fabric graph snapshots, discovery evidence, and supporting
inventory.
The registry should not replace the `fabric/` files in each repo. Repositories
remain the source of truth. The service validates, snapshots, queries, and
projects that model so agents, humans, and State Hub can interact with the
ecosystem graph without cloning every repo or rerunning the local CLI.
The registry should not become the authoring surface for Fabric ownership or
boundaries. Repo-local `fabric/` files remain useful evidence, while financial
fabric membership, tenant boundaries, ownership, and cross-boundary utility
relations are resolved from accountability roots and accepted snapshots. The
service validates, snapshots, queries, and projects that model so agents,
humans, and State Hub can interact with the ecosystem graph without cloning
every repo or rerunning the local CLI.
The closest external model to compare against is CNCF xRegistry. xRegistry is
specifically about metadata registries, with both file/document and API views.

121
docs/financial-fabric-operator-guide.md Normal file
View File

@@ -0,0 +1,121 @@
# Financial Fabric Operator Guide
This guide is the operator path for the financial Fabric reset described in
`docs/FabricDiscoveryAndUpdate.md`.
## Current Baseline
Railiance currently has one effective fabric because one actor pays for the
infrastructure. The accepted baseline lives at:
```text
fabric/financial/railiance-netkingdom.yaml
```
It defines:
- `railiance.netkingdom` as the netkingdom root;
- `actor.railiance.king` as the king with recovery, secrets, backup, and
termination authority;
- `actor.railiance.primary-lord` as the lord who pays for the current fabric;
- `fabric.railiance.primary` as the current active fabric;
- inherited ownership for accepted nodes until a more specific owner is
discovered or approved;
- a future subfabric template for tenant modeling.
The baseline is not a security-zone model. Do not introduce realm, domain, or
identity-zone language into the Fabric core when updating it.
## Refresh Loop
Run these checks from the `railiance-fabric` repo after changing declarations,
baseline ownership, discovery inputs, or export code:
```bash
railiance-fabric validate .
railiance-fabric export --format json
railiance-fabric export --format financial
python3 -m pytest tests/test_registry.py -q
```
Use the legacy JSON export for compatibility with existing `STATE-WP-0050`
State Hub behavior. Use the financial export to verify the vNext contract and
the ownership/fabric projection.
The financial export must satisfy these invariants:
- every accepted node has resolvable ownership;
- every accepted node has fabric containment;
- cost/profit center fields are optional accounting attribution, not fabric
boundaries;
- cross-boundary utility edges carry provider and consumer owner context when
known;
- unresolved ownership or containment remains explicit rather than invented by
State Hub.
## Registry Reset Rebuild
After a guarded registry reset, rebuild from durable roots in this order:
1. Confirm the baseline still reflects who pays for the infrastructure.
2. Validate the repo evidence with `railiance-fabric validate .`.
3. Emit `railiance-fabric export --format financial` and review the ownership
projection.
4. Start the registry and sync this repo:
```bash
railiance-fabric-registry --db .railiance-fabric/registry.sqlite3 --port 8765
railiance-fabric registry sync --repo-slug railiance-fabric .
```
5. Sync broader known repos with `registry/local-repos.yaml` or
`registry/railiance-repos.yaml` when their local checkouts exist.
6. Compare snapshot diffs before promoting new discovery output.
Repo-local `fabric/` declarations are evidence during this rebuild. The
replacement discovery loop should start from the netkingdom, king, lords,
tenants, deployment automation, service manifests, endpoints, backups, and
secret roots rather than asking each repo to own all external relations.
## State Hub Handoff
State Hub is a read model for Fabric topology. It should ingest Fabric exports,
link them to repos/workstreams/tasks, and expose dashboard/search views. It
should not author ownership, fabric membership, or utility boundaries.
Until `STATE-WP-0051` is implemented:
- continue importing or syncing the legacy `v1alpha1` graph for existing State
Hub graph views;
- keep the `v1alpha2` financial export as the contract artifact for State Hub
implementation and review;
- update file-backed workplan state through State Hub consistency after
workplan edits:
```bash
cd ~/state-hub
make fix-consistency REPO=railiance-fabric
```
After `STATE-WP-0051`, the financial export should become the preferred State
Hub graph import. The importer must preserve netkingdom, actors, fabrics,
containment, ownership, accounting attribution, cross-boundary utility context,
and unresolved gaps.
## Discovery Work Handoff
The next discovery/update-loop work should replace the baseline projection with
durable evidence collection:
- discover repos from State Hub and Gitea;
- discover deployment realities from automation and infrastructure manifests;
- discover services, machines, endpoints, backup roots, and secret roots;
- normalize identities across repo URLs, host paths, image names, service
names, and endpoint contracts;
- resolve owner and containment from the baseline, explicit evidence, or
review decisions;
- emit deltas for ownership, containment, nodes, edges, and cross-boundary
utility changes.
The baseline projection is therefore a safe bridge, not the final discovery
engine.

10
docs/first-rollout.md
View File

@@ -2,8 +2,9 @@
The first rollout is represented by the seed declarations under `fabric/`.
Those files are intentionally centralized in Railiance Fabric for bootstrap;
the long-term target is for each owning repo to carry its own `fabric/`
declarations.
the long-term target is for each owning repo to contribute local evidence while
financial Fabric ownership and boundary decisions come from accountability-root
discovery.
## Seeded Repos
@@ -28,8 +29,9 @@ For each owning repo:
4. Validate the owning repo together with `railiance-fabric` and other
providers/consumers it depends on.
5. Export the multi-repo graph for State Hub ingestion.
6. Once repo-local declarations are authoritative, remove or mark the central
seed declarations as bootstrap-only.
6. Once accountability-root discovery can reproduce the graph, mark the
central seed declarations as bootstrap evidence and keep only the repo-local
facts that remain useful self-description.
## Suggested Order

17
docs/registry-api.md
View File

@@ -1,7 +1,10 @@
# Registry API
The Railiance Fabric registry is a small HTTP API over repo-owned Fabric
declarations and supporting inventory.
The Railiance Fabric registry is a small HTTP API over accepted Fabric graph
snapshots, discovery evidence, reset archives, and supporting inventory.
Legacy repo-local declarations can still produce snapshots, but they are
evidence for the graph rather than the long-term authority for external
deployment, ownership, tenant, or utility relations.
## Health And Status
@@ -27,7 +30,9 @@ GET /repositories/{repo_slug}/snapshots/diff
```
Snapshot ingestion accepts a `FabricGraphExport` under `graph` plus `commit`
and optional `generated_at`.
and optional `generated_at`. The registry accepts both legacy
`railiance.fabric/v1alpha1` graph exports and the financial
`railiance.fabric/v1alpha2` / `financial-fabric-v1` export contract.
## Discovery Snapshots
@@ -102,6 +107,12 @@ GET /exports/graph-explorer
GET /exports/reset-archive
```
`GET /exports/state-hub` currently serves the accepted combined graph for the
State Hub read model. During the financial reset, keep using the legacy shape
for existing State Hub views until `STATE-WP-0051` materializes v1alpha2
fields. Use `railiance-fabric export --format financial` and
`examples/exports/financial-fabric-v1.json` as the vNext contract references.
## Guarded Reset
```text

16
docs/registry-onboarding.md
View File

@@ -1,9 +1,15 @@
# Registry Onboarding
Multi-repo onboarding uses a repo-owned manifest to register ecosystem
Multi-repo onboarding uses an operator-owned manifest to register ecosystem
repositories with a running Railiance Fabric registry and to push graph and
library inventory when the local checkout has the required inputs.
Repo-local declarations remain useful self-description evidence. They should
not be treated as the default authority for external fabric membership,
ownership, tenant boundaries, or cross-boundary utility relations. Those belong
to the accountability-root discovery model described in
`docs/FabricDiscoveryAndUpdate.md`.
## Run The Railiance Manifest
Start the registry:
@@ -57,7 +63,7 @@ registration.
Each repository entry is registered first. If the checkout is unavailable or has
no Fabric declarations yet, the command leaves the repo registered and reports a
warning. This lets the registry represent known repos before every repo has
adopted local declarations.
published local evidence.
When declarations exist, the command validates them, builds a graph snapshot,
and posts it to:
@@ -67,9 +73,9 @@ POST /repositories/{repo_slug}/snapshots
```
The first Railiance manifest keeps the seed ecosystem graph in
`railiance-fabric` and registers adjacent repos as known sources. As those repos
adopt repo-local `fabric/` declarations, they can be synced without changing the
registry API.
`railiance-fabric` and registers adjacent repos as known sources. As discovery
roots mature, adjacent repos can contribute local evidence without making each
repo responsible for the whole external fabric relation model.
`registry/local-repos.yaml` is a broader local-host manifest. It is generated
from active State Hub repo records whose local path exists on the current WSL

14
docs/registry-reset-operations.md
View File

@@ -44,8 +44,18 @@ from the known repo list.
The archive is a JSON evidence bundle, not an automatic SQLite restore. Use it
to inspect or manually reinsert prior registry data if needed. After reset, the
intended source of truth is a fresh scan and acceptance pass over registered and
local repositories using the canon-aligned model.
intended source of truth is a fresh scan and acceptance pass from accountability
roots using the financial Fabric model. The current bridge is the Railiance
baseline projection:
```bash
railiance-fabric validate .
railiance-fabric export --format financial
railiance-fabric registry sync --repo-slug railiance-fabric .
```
Use repo-local declarations as evidence during reingest, not as the authority
for all external ownership, tenant, or utility relations.
Do not run the reset until the replacement scanner/projection path has passed
validation and a sample reingest review.

30
docs/repo-reality-scanner.md
View File

@@ -2,8 +2,10 @@
The repo reality scanner discovers Fabric entities from repository evidence and
turns them into candidate graph facts. It is a discovery layer, not a new
authoring surface. Repo-owned declarations remain the highest-trust source for
accepted Fabric graph data.
authoring surface. Repo-owned declarations remain high-trust self-description
evidence, but financial Fabric ownership, tenant boundaries, and cross-boundary
utility relations must be resolved from accountability roots or review
decisions before they become accepted graph data.
## Contract
@@ -76,9 +78,10 @@ returns malformed JSON, the scanner records a `review_artifacts` entry and keeps
the discovery snapshot schema-valid.
The LLM never receives the whole repository. The scanner first builds a compact
evidence bundle from deterministic candidates, prioritizing repo-owned Fabric
declarations, services, capabilities, interfaces, libraries, deployments, and
small README/INTENT/SCOPE signals. The prompt asks for strict JSON:
evidence bundle from deterministic candidates, prioritizing durable local
evidence such as Fabric declarations, services, capabilities, interfaces,
libraries, deployments, and small README/INTENT/SCOPE signals. The prompt asks
for strict JSON:
```json
{"nodes": [], "edges": [], "attributes": []}
@@ -162,7 +165,9 @@ candidate stable keys. Existing accepted graph nodes win over discovery nodes
with the same graph id, so repo-owned declarations are preserved. Projected
nodes carry discovery stable key, origin, review state, confidence, provenance,
and source anchors in graph attributes; the graph explorer payload exposes
those fields for review.
those fields for review. For financial Fabric fields, accepted discovery still
needs an accountability-root, baseline inheritance rule, or explicit review
decision.
## Connector Follow-Up
@@ -198,8 +203,9 @@ with status, source, message, and candidate counts.
Connector-derived facts should be treated this way:
- accepted: only when the connector reads explicit repo-owned declarations or a
catalog already governed as authoritative for that field
- accepted: only when the connector reads explicit repo-owned evidence,
accountability-root evidence, or a catalog already governed as authoritative
for that field
- candidate: stable local registry facts such as onboarding manifest entries,
declared remote URLs, State Hub ids, and declaration paths
- review-only: missing catalogs, rate limits, connector failures, ambiguous
@@ -408,9 +414,11 @@ precedence:
6. `manual`
Manual review can override local candidate state, but it should not silently
rewrite repo-owned declarations. If accepted discoveries should become
authoritative, the safer next step is to generate a repo-owned declaration patch
for human review.
rewrite repo-owned declarations. If accepted discoveries should become durable
repo-local evidence, generate a repo-owned declaration patch for human review.
If they affect financial ownership, fabric containment, tenancy, or utility
value boundaries, generate a baseline or accountability-root review item
instead.
## Duplicate Handling

27
docs/state-hub-integration.md
View File

@@ -36,6 +36,7 @@ The CLI and registry emit `FabricGraphExport` JSON:
```bash
railiance-fabric export --format json
railiance-fabric export --format financial
```
Schema: `schemas/state-hub-export.schema.yaml`
@@ -135,6 +136,32 @@ Additional edge fields:
Example payload: `examples/exports/financial-fabric-v1.json`.
## Operator Refresh During Reset
For the current reset, operators should produce both export families:
```bash
railiance-fabric validate .
railiance-fabric export --format json
railiance-fabric export --format financial
```
The `json` export remains the compatibility payload for State Hub graph views
implemented by `STATE-WP-0050`. The `financial` export is the vNext contract
artifact for `STATE-WP-0051` and should be reviewed whenever the baseline,
discovery inputs, ownership model, or registry materialization changes.
After workplan file changes, refresh State Hub's file-backed index from the
State Hub repo:
```bash
make fix-consistency REPO=railiance-fabric
```
Graph import and workplan consistency are separate. The consistency command
does not author Fabric graph topology; it only keeps State Hub's workplan cache
aligned with repo files.
## Proposed State Hub Read Model
Add a State Hub ingestion endpoint or job that stores the latest graph export