railiance-fabric/docs/financial-fabric-operator-guide.md

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:

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.

Deployment Overlay Baseline

Fabric membership is not the same as deployment environment. Use these current Railiance deployment overlays when interpreting discovery evidence:

Scenario	Environment	Access zone baseline	Notes
bernd-laptop	dev	private-dev	Local machine used by one developer. Its loopback ports and local tools are useful evidence for debugging, but are not shared truth for other developers.
coulombcore	test	collaborator-test, early-access	Central test-stage server for collaborating developers and friendly early-access users.
railiance01	prod	production-public, production-admin	Production host. Developer access exists during alpha, but production should be able to move toward restricted operator access and applicable security and data-privacy controls.

The routing authority is the source that maps names or ports to services in a scenario. For local dev this may be a Makefile, script, process launcher, or loopback binding. For test and production this should usually come from Kubernetes Service and Ingress, Traefik/nginx/Caddy/HAProxy configuration, DNS, and TLS automation.

Fabric should discover those routes and visualize the resulting zones. It should not allocate ports, author reverse-proxy config, or define the access policy. The policy authority is external evidence, such as NetKingdom IAM, ingress policy, network policy, or local-only loopback binding.

Refresh Loop

Run these checks from the railiance-fabric repo after changing declarations, baseline ownership, discovery inputs, or export code:

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:

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:

railiance-fabric discover-roots --max-items-per-root 200

To inspect normalized identity candidates or persist a local evidence run:

railiance-fabric discover-roots --identity-projection
railiance-fabric discover-roots --store-db .railiance-fabric/accountability-evidence.sqlite3

To inspect ownership blockers and apply review decisions:

railiance-fabric discover-roots --ownership-review \
  --store-db .railiance-fabric/accountability-evidence.sqlite3

railiance-fabric review-identity <stable-key> \
  --store-db .railiance-fabric/accountability-evidence.sqlite3 \
  --decision accept \
  --owner-actor-id actor.railiance.primary-lord \
  --fabric-id fabric.railiance.primary

To compare a new run with saved review outputs:

railiance-fabric discover-roots --delta \
  --previous-identity-projection previous-identities.json \
  --previous-ownership-review previous-ownership.json

The current bootstrap artifacts live at:

fabric/discovery/snapshots/2026-05-24-railiance-bootstrap-identities.json
fabric/discovery/snapshots/2026-05-24-railiance-bootstrap-ownership-review.json
fabric/discovery/snapshots/2026-05-24-railiance-bootstrap-update-delta.json
exports/state-hub/2026-05-24-railiance-financial-fabric-v1.json

To refresh the same artifact set:

railiance-fabric discover-roots --include-remote --max-items-per-root 200 \
  --identity-projection > fabric/discovery/snapshots/YYYY-MM-DD-railiance-bootstrap-identities.json
railiance-fabric discover-roots --include-remote --max-items-per-root 200 \
  --ownership-review > fabric/discovery/snapshots/YYYY-MM-DD-railiance-bootstrap-ownership-review.json
railiance-fabric discover-roots --include-remote --max-items-per-root 200 \
  --delta > fabric/discovery/snapshots/YYYY-MM-DD-railiance-bootstrap-update-delta.json
railiance-fabric export --format financial . \
  > exports/state-hub/YYYY-MM-DD-railiance-financial-fabric-v1.json

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:

   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:

  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.

To import a saved financial export into State Hub:

curl -s -X POST \
  "http://127.0.0.1:8000/fabric/graph-exports?source_repo_slug=railiance-fabric" \
  -H "Content-Type: application/json" \
  --data-binary @exports/state-hub/2026-05-24-railiance-financial-fabric-v1.json

If the /fabric/graph-exports endpoints return 500 while ordinary State Hub routes work, run the State Hub migrations and retry:

cd ~/state-hub
make migrate
# or, when uv is not on PATH:
.venv/bin/alembic upgrade head

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.