railiance-fabric/workplans/RAIL-FAB-WP-0018-accountability-root-discovery-update-loop.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
RAIL-FAB-WP-0018	workplan	Accountability Root Discovery And Update Loop	railiance	railiance-fabric	finished	codex	railiance	2026-05-23	2026-05-24	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

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

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

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

id: RAIL-FAB-WP-0018-T04
status: done
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.

Result:

• Added schemas/accountability-ownership-review.schema.yaml for ownership resolution and review-blocker payloads.
• Added build_ownership_review() to resolve explicit owners, inherit owners from fabric/subfabric containment, flag unresolved ownership, flag unknown or ambiguous containment, and surface ambiguous owner evidence.
• Extended AccountabilityEvidenceStore with durable review decisions keyed by stable identity candidate key.
• Added railiance-fabric discover-roots --ownership-review and railiance-fabric review-identity so operators can inspect blockers and persist accept/needs-review/reject decisions across rescans.
• Added tests proving ambiguous ownership is visible, review decisions can accept a stable identity, decisions survive a later ownership-review run, and accepted items cannot silently lack a resolved owner.
• Documented ownership review and reviewer decisions in the manifest and 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 --ownership-review --store-db /tmp/railiance-root-ownership.sqlite3, and full python3 -m pytest.

T05 - Implement Snapshot Deltas And Freshness Triggers

id: RAIL-FAB-WP-0018-T05
status: done
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.

Result:

• Added schemas/accountability-update-delta.schema.yaml for AccountabilityUpdateDelta payloads.
• Added build_update_delta() to compare current and previous identity projections plus ownership reviews.
• Deltas distinguish candidate graph node additions/changes/removals, candidate graph edge additions/changes/removals, ownership changes, containment changes, review-state changes, blocker changes, and unchanged nodes/edges.
• Added railiance-fabric discover-roots --delta with optional --previous-identity-projection and --previous-ownership-review inputs.
• Added tests proving unchanged runs do not require promotion and ownership review changes are highlighted.
• Documented update deltas in the manifest and operator docs.
• Verified with python3 -m pytest tests/test_accountability_root_adapters.py -q, python3 -m railiance_fabric.cli discover-roots --max-items-per-root 5 --delta, and full python3 -m pytest.

T06 - Bootstrap The Current Railiance Rebuild

id: RAIL-FAB-WP-0018-T06
status: done
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.

Result:

• Tightened deployable identity normalization so generic filenames such as Dockerfile no longer create false ambiguous identity blockers.
• Filtered dependency-cache deployment matches from accountability-root deployable/config evidence.
• Aligned repository inventory, Gitea, host-path, and deployment roots to use actor.railiance.primary-lord as the default financial owner for discovered candidates.
• Saved the 2026-05-24 bootstrap artifacts: 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, and exports/state-hub/2026-05-24-railiance-financial-fabric-v1.json.
• The bootstrap ownership review produced 96 candidates, zero unresolved ownership items, zero ambiguous containment items, and four explicit duplicate repository identity blockers.
• Created RAIL-FAB-WP-0019 to resolve those duplicate repository identities instead of hiding them.
• Imported the financial Fabric export into State Hub after applying the STATE-WP-0051 migration; State Hub accepted the export as valid with 2 actors, 1 fabric, 49 nodes, 58 edges, and 0 unresolved items.
• Added generated_at stamping for financial bridge exports so saved snapshot files carry export time.
• Verified with focused accountability/registry tests, artifact schema validation, State Hub import/readback, and full python3 -m pytest.

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.