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:

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

## 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:

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

To inspect ownership blockers and apply review decisions:

```bash
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:

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

The current bootstrap artifacts live at:

```text
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:

```bash
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:

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

To import a saved financial export into State Hub:

```bash
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:

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