generated from coulomb/repo-seed
143 lines
5.0 KiB
Markdown
143 lines
5.0 KiB
Markdown
# 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.
|
|
|
|
For accountability-root discovery, start from the current root manifest:
|
|
|
|
```text
|
|
fabric/discovery/railiance-accountability-roots.yaml
|
|
```
|
|
|
|
The manifest schema is documented in `docs/accountability-root-manifest.md`.
|
|
|
|
To collect raw evidence from those roots without promoting graph state:
|
|
|
|
```bash
|
|
railiance-fabric discover-roots --max-items-per-root 200
|
|
```
|
|
|
|
To inspect normalized identity candidates or persist a local evidence run:
|
|
|
|
```bash
|
|
railiance-fabric discover-roots --identity-projection
|
|
railiance-fabric discover-roots --store-db .railiance-fabric/accountability-evidence.sqlite3
|
|
```
|
|
|
|
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.
|