# 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`.

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.