railiance-fabric/docs/accountability-root-manifest.md

# Accountability Root Manifest

The accountability root manifest is the handoff between the financial Fabric
model and the discovery/update loop.

It answers where discovery starts. A manifest names the netkingdom, actors,
fabric boundaries, and durable roots that can prove repositories, deployment
realities, service configuration, endpoint contracts, backup/recovery evidence,
and secret-root metadata. It does not collect live telemetry and it does not
make State Hub the authoring surface for topology.

Schema:

```text
schemas/accountability-root-manifest.schema.yaml
```

Current Railiance manifest:

```text
fabric/discovery/railiance-accountability-roots.yaml
```

Tenant/subfabric example:

```text
examples/discovery/accountability-root-manifest.yaml
```

Raw evidence run schema:

```text
schemas/accountability-root-evidence.schema.yaml
```

Identity projection schema:

```text
schemas/accountability-identity-projection.schema.yaml
```

Ownership review schema:

```text
schemas/accountability-ownership-review.schema.yaml
```

Update delta schema:

```text
schemas/accountability-update-delta.schema.yaml
```

## Required Sections

- `netkingdom`: root id, name, and king actor.
- `actors`: king, lord, tenant, operator, or steward actors.
- `fabrics`: fabric and subfabric boundaries.
- `discovery_roots`: durable roots such as State Hub repo inventory, Gitea
  organizations, registry manifests, host paths, repo checkouts, deployment
  automation, endpoint contracts, backup/recovery evidence, and secret-root
  metadata.
- `refresh`: cadence and trigger hints for the future update loop.

## Boundary Rules

The current Railiance manifest has one active fabric:
`fabric.railiance.primary`. Future tenant subfabrics are added under that
fabric by adding a tenant actor, a `Subfabric`, and subfabric-scoped discovery
roots. This does not change the root fabric criterion: the fabric boundary
still rests on financial and operational accountability.

`owner_actor_id` on a discovery root describes the default owner to attach to
identity candidates discovered through that root. For ordinary repositories,
deployment files, and host-path evidence this should be the lord who pays for
the fabric. King authority remains modeled on the netkingdom and on roots that
represent recovery, secret, backup, or termination authority.

Discovery roots should state `safe_discovery` explicitly. Secret and backup
roots should use `metadata_only` or `explicit_review`; adapters must never read
secret values or operational telemetry while building Fabric graph evidence.

## Collecting Root Evidence

The first adapter slice emits raw evidence without promoting it into accepted
graph snapshots:

```bash
railiance-fabric discover-roots \
  --manifest fabric/discovery/railiance-accountability-roots.yaml \
  --max-items-per-root 200
```

The command covers manifest-backed repository inventory, repository checkout
identity, host-path evidence, deployment automation and infrastructure files,
State Hub/Gitea metadata roots, endpoint/service-config roots, and safe
metadata-only backup or secret roots. Remote HTTP reads are disabled by default;
pass `--include-remote` only when the operator intentionally wants configured
remote roots such as State Hub inventory endpoints to be fetched.

The output is an `AccountabilityRootEvidenceRun`. Every evidence item carries
provenance, source, fingerprint, `durable: true`, and
`live_telemetry: false`, preserving the boundary between Fabric evidence and
operational telemetry.

To normalize raw evidence into reviewable identity candidates:

```bash
railiance-fabric discover-roots \
  --identity-projection \
  --max-items-per-root 200
```

To persist raw evidence and identity candidates in a local SQLite store:

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

The store is intentionally separate from accepted registry graph snapshots. It
keeps raw evidence runs, evidence items, and identity candidates available for
inspection before any candidate is promoted.

## Ownership Review

To resolve ownership and containment from the normalized identities:

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

The ownership review inherits owners from fabric/subfabric containment when
possible, applies explicit owner evidence from discovery roots, and marks
unresolved or ambiguous candidates as `needs_review`. Accepted candidates must
have a resolved owner and containment unless they are actors or the netkingdom
root.

To persist a reviewer decision for a stable identity candidate:

```bash
railiance-fabric review-identity identity:repository:example-repo \
  --store-db .railiance-fabric/accountability-evidence.sqlite3 \
  --decision accept \
  --owner-actor-id actor.railiance.primary-lord \
  --fabric-id fabric.railiance.primary \
  --reviewer operator \
  --note "accepted from reviewed checkout evidence"
```

Reviewer decisions are keyed by stable identity key. Later rescans apply the
latest decision for that key, so ordinary evidence refreshes do not lose
reviewed ownership choices.

## Update Deltas

To compare the current run with previous identity and ownership-review outputs:

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

The delta separates candidate graph node changes, candidate graph edge changes,
ownership changes, containment changes, review-state changes, and blocker
changes. When `summary.promotion_needed` is `false`, the update loop can skip
promotion because the durable evidence produced no meaningful Fabric change.