---
id: RAIL-FAB-WP-0018
type: workplan
title: "Accountability Root Discovery And Update Loop"
domain: railiance
repo: railiance-fabric
status: active
owner: codex
topic_slug: railiance
created: "2026-05-23"
updated: "2026-05-23"
state_hub_workstream_id: "651185b5-83fe-4aef-b29d-617b2bc48c7a"
---

# RAIL-FAB-WP-0018 - Accountability Root Discovery And Update Loop

## Goal

Build the discovery and update mechanism that keeps Fabric current from durable
accountability roots and deployment automation, rather than from repo-owned
external relation declarations.

This workplan depends on the semantic direction from
`RAIL-FAB-WP-0017-financial-fabric-model-reset.md`.

## Background

Fabric should be able to rebuild the Railiance graph from scratch by starting
with the netkingdom, king/lord/tenant actors, fabric/subfabric boundaries,
State Hub attached repositories, Gitea URLs, deployment automation, service
configuration, infrastructure manifests, secret/backup evidence, and endpoint
contracts.

The update loop must stay below live telemetry. It should track durable
configuration and automation changes that alter topology, ownership, deployment,
interfaces, or cross-boundary utility.

## T01 - Define Discovery Root Manifest

```task
id: RAIL-FAB-WP-0018-T01
status: done
priority: high
state_hub_task_id: "38ae49fb-ce21-489c-ba67-7f76ab4febc9"
```

Define a manifest format for accountability-root discovery.

The manifest should be able to register:

- netkingdom root;
- king, lord, and tenant actors;
- fabric and subfabric boundaries;
- State Hub attached repo inventory roots;
- Gitea organization or repository roots;
- deployment automation roots;
- known host paths;
- infrastructure, backup, recovery, and secret-root evidence sources;
- refresh cadence or trigger hints.

Done when:

- manifest schema and examples exist;
- the current Railiance one-fabric baseline can be represented;
- the format can add future tenant subfabrics without changing the top-level
  fabric criterion.

Result:

- Added `schemas/accountability-root-manifest.schema.yaml` for
  `railiance.fabric/v1alpha2` accountability-root manifests.
- Added `fabric/discovery/railiance-accountability-roots.yaml` to represent
  the current Railiance one-fabric baseline, State Hub/Gitea/repo/host roots,
  deployment automation roots, and safe metadata-only secret/backup roots.
- Added `examples/discovery/accountability-root-manifest.yaml` to show how a
  tenant subfabric can be added without changing the parent fabric criterion.
- Added `docs/accountability-root-manifest.md` and linked the manifest from the
  financial Fabric operator guide.
- Added schema/baseline coverage in `tests/test_accountability_roots.py`.
- Verified with `python3 -m pytest tests/test_accountability_roots.py -q`,
  `python3 -m railiance_fabric.cli validate .`,
  `python3 -m railiance_fabric.cli export --format financial .`, and full
  `python3 -m pytest`.

## T02 - Implement Durable Evidence Discovery Adapters

```task
id: RAIL-FAB-WP-0018-T02
status: done
priority: high
state_hub_task_id: "09246f06-10db-4c6c-9cb3-f2808fdbaa38"
```

Implement or adapt scanners for durable evidence sources.

Initial adapters should cover:

- State Hub attached repositories and host paths;
- local/Gitea repository identity;
- Dockerfiles and Compose files;
- Kubernetes, systemd, reverse proxy, and service config where present;
- deployment scripts and CI/CD references;
- API specs and endpoint contracts;
- backup, recovery, and secret-management evidence where safely discoverable.

Done when:

- each adapter emits provenance-rich raw evidence;
- evidence distinguishes durable existence/configuration from live operational
  state;
- adapters can run against the current local Railiance workspace.

Result:

- Added `railiance_fabric/accountability_roots.py` to load and validate the
  accountability root manifest and collect raw evidence from registered roots.
- Added `schemas/accountability-root-evidence.schema.yaml` for
  `AccountabilityRootEvidenceRun` payloads.
- Added `railiance-fabric discover-roots` with `--manifest`,
  `--max-items-per-root`, and opt-in `--include-remote`.
- Implemented initial adapters for registry manifests, repository checkouts,
  host paths, deployment/infrastructure/service/endpoint file roots, State Hub
  metadata roots, Gitea metadata roots, and metadata-only backup/secret roots.
- Raw evidence carries source, provenance, fingerprints, durable evidence
  state, and `live_telemetry: false` without promoting candidates into accepted
  graph state.
- Added adapter coverage in `tests/test_accountability_root_adapters.py` and
  documented the evidence command in the manifest/operator docs.
- Verified with
  `python3 -m pytest tests/test_accountability_roots.py tests/test_accountability_root_adapters.py -q`,
  `python3 -m railiance_fabric.cli discover-roots --max-items-per-root 5`,
  and full `python3 -m pytest`.

## T03 - Build Evidence Store And Identity Normalization

```task
id: RAIL-FAB-WP-0018-T03
status: done
priority: high
state_hub_task_id: "2a79938f-13e2-41b4-b692-74420d31bec4"
```

Persist discovery output and normalize identities before graph promotion.

Requirements:

- scanner run metadata;
- source paths, URLs, timestamps, scanner versions, and content hashes;
- stable identity candidates for repos, deployables, services, machines,
  endpoints, fabrics, subfabrics, and actors;
- duplicate/ambiguous identity detection;
- candidate graph generation separate from accepted graph snapshots.

Done when:

- raw evidence can be inspected independently from accepted graph state;
- identity normalization produces reviewable candidates;
- repeated scans produce deterministic identities for unchanged sources.

Result:

- Added `schemas/accountability-identity-projection.schema.yaml` for
  normalized `AccountabilityIdentityProjection` payloads.
- Extended `railiance_fabric/accountability_roots.py` with deterministic
  identity normalization for netkingdoms, actors, fabrics, subfabrics,
  repositories, deployables, endpoint/service/config roots, host paths,
  catalog roots, secret roots, and backup/recovery roots.
- Added duplicate/ambiguous alias marking on identity candidates and a
  candidate graph section that remains separate from accepted registry graph
  snapshots.
- Added `AccountabilityEvidenceStore`, a SQLite store for raw evidence runs,
  evidence items, and identity candidates.
- Extended `railiance-fabric discover-roots` with `--identity-projection` and
  `--store-db`.
- Added focused tests for deterministic identity keys, schema validation,
  persistence, CLI output, and store inspection.
- Verified with
  `python3 -m pytest tests/test_accountability_roots.py tests/test_accountability_root_adapters.py -q`,
  `python3 -m railiance_fabric.cli discover-roots --max-items-per-root 5 --identity-projection --store-db /tmp/railiance-root-evidence.sqlite3`,
  and full `python3 -m pytest`.

## T04 - Add Ownership Resolution And Review Flow

```task
id: RAIL-FAB-WP-0018-T04
status: todo
priority: high
state_hub_task_id: "670be2c2-6bec-4534-ae6a-ab0186ce0a8d"
```

Resolve ownership for discovered nodes and flag gaps.

Requirements:

- inherit owner from containing fabric/subfabric when evidence is sufficient;
- support explicit owner evidence from manifests or deployment automation;
- flag nodes with unresolved ownership;
- flag ambiguous fabric/subfabric containment;
- expose review/accept operations for candidates;
- preserve reviewer decisions across rescans when evidence identity is stable.

Done when:

- no accepted node can silently lack ownership;
- unresolved or ambiguous nodes are visible before promotion;
- review decisions survive ordinary rescans.

## T05 - Implement Snapshot Deltas And Freshness Triggers

```task
id: RAIL-FAB-WP-0018-T05
status: todo
priority: medium
state_hub_task_id: "c2f28b34-de32-4090-8782-5d00541b9018"
```

Add an update loop that detects meaningful Fabric changes.

Triggers should include:

- deployment automation changes;
- infrastructure manifest changes;
- State Hub attached repository inventory changes;
- repository changes affecting deployables, APIs, service names, ports,
  endpoint contracts, images, or deployment configuration;
- lord, tenant, cost/profit center, backup, recovery, or secret-root changes;
- manual operator rebuilds;
- scheduled periodic rescans.

Done when:

- scanner runs can compare against the previous accepted snapshot;
- deltas distinguish added/changed/removed nodes and edges;
- ownership, containment, accounting attribution, and cross-boundary utility
  changes are highlighted;
- unchanged sources are not needlessly promoted.

## T06 - Bootstrap The Current Railiance Rebuild

```task
id: RAIL-FAB-WP-0018-T06
status: todo
priority: high
state_hub_task_id: "0d05ee40-0823-473f-9c87-0ed964e8900c"
```

Run the new discovery/update loop against the current Railiance workspace.

Requirements:

- rebuild from the accountability root manifest;
- produce a reviewable candidate graph;
- accept the baseline into a versioned Fabric snapshot;
- export the snapshot for State Hub;
- document unresolved gaps as follow-up workplans rather than hiding them.

Done when:

- the current Railiance graph can be rebuilt from durable roots;
- ownership is resolved or explicitly flagged for every node;
- State Hub can import the resulting export after `STATE-WP-0051`;
- operator docs explain how to rerun the rebuild and update loop.

## Acceptance

- Fabric discovery starts from accountability roots and deployment automation.
- Raw evidence, candidate graph state, and accepted graph snapshots are
  separated.
- The update loop detects durable topology, ownership, deployment, interface,
  and cross-boundary utility changes.
- Live telemetry remains out of scope.
- The current Railiance baseline can be rebuilt from scratch and exported.