generated from coulomb/repo-seed
Archive closed workplans to workplans/archived/ (ADR-001)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
39
workplans/archived/260702-ADHOC-2026-05-21.md
Normal file
39
workplans/archived/260702-ADHOC-2026-05-21.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
id: ADHOC-2026-05-21
|
||||
type: workplan
|
||||
title: "Ad Hoc Fixes 2026-05-21"
|
||||
domain: railiance
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-05-21"
|
||||
updated: "2026-05-21"
|
||||
state_hub_workstream_id: "c5126722-3b6c-4a6a-b687-bc2ebfce5d58"
|
||||
---
|
||||
|
||||
# ADHOC-2026-05-21 - Ad Hoc Fixes
|
||||
|
||||
## Collapse Duplicate Repository Icons
|
||||
|
||||
```task
|
||||
id: ADHOC-2026-05-21-T01
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "8af02b06-b9a4-457a-bbdc-fa97543944a4"
|
||||
```
|
||||
|
||||
After projecting all discovery candidates into the local registry graph, the
|
||||
graph explorer rendered each repository twice: once as the canonical registry
|
||||
repository node and once as the discovered `Repository` candidate node.
|
||||
|
||||
The graph explorer now collapses discovered `Repository` nodes into the
|
||||
canonical `repo:<slug>` node and rewires source graph edges to that canonical
|
||||
node, preserving relationships without duplicate repo icons.
|
||||
|
||||
Verification:
|
||||
|
||||
- `python3 -m pytest tests/test_graph_explorer.py -q` passed.
|
||||
- `python3 -m pytest` passed with 34 tests.
|
||||
- Restarted the local registry and confirmed the graph explorer export now has
|
||||
35 repository nodes instead of 69.
|
||||
46
workplans/archived/260702-ADHOC-2026-05-25.md
Normal file
46
workplans/archived/260702-ADHOC-2026-05-25.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
id: ADHOC-2026-05-25
|
||||
type: workplan
|
||||
title: "Ad Hoc Fixes 2026-05-25"
|
||||
domain: railiance
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-05-25"
|
||||
updated: "2026-05-25"
|
||||
state_hub_workstream_id: "77e80432-9548-4ac8-9654-7beb931741e4"
|
||||
---
|
||||
|
||||
# ADHOC-2026-05-25 - Ad Hoc Fixes
|
||||
|
||||
## Add Zone Layout Algorithm Control
|
||||
|
||||
```task
|
||||
id: ADHOC-2026-05-25-T01
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "f0b4fdfa-9c26-4f8a-9372-90242eeec5d8"
|
||||
```
|
||||
|
||||
The graph explorer now lays zone subgraphs out as a grid inside each zone
|
||||
container. Add an operator-facing control that can switch the zone-local layout
|
||||
algorithm while keeping stable zone containers intact.
|
||||
|
||||
Expected result: the map controls expose a zone layout selector, the selected
|
||||
algorithm applies to each zone subgraph, and the setting persists in saved or
|
||||
copied view state.
|
||||
|
||||
Result: Added a `Zone Layout` selector with Grid and Circle algorithms. The
|
||||
selected algorithm is stored in nested zone view state, reflected by the
|
||||
`zoneLayout` URL alias for non-default layout, and reapplies zone-local node
|
||||
placement without moving stable zone containers.
|
||||
|
||||
Verification:
|
||||
|
||||
- `python3 -m pytest tests/test_graph_explorer.py tests/test_zone_view.py -q`
|
||||
passed.
|
||||
- Generated graph explorer JavaScript passed `node --check`.
|
||||
- `python3 -m railiance_fabric.cli validate .` passed.
|
||||
- `python3 -m pytest -q` passed with 72 tests.
|
||||
- Headless Edge screenshots confirmed Grid and Circle zone layouts render.
|
||||
46
workplans/archived/260702-ADHOC-2026-06-03.md
Normal file
46
workplans/archived/260702-ADHOC-2026-06-03.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
id: ADHOC-2026-06-03
|
||||
type: workplan
|
||||
title: "Ad Hoc Fixes 2026-06-03"
|
||||
domain: railiance
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-06-03"
|
||||
updated: "2026-06-03"
|
||||
state_hub_workstream_id: "c39b02dd-8074-4efd-ad18-add5595bf646"
|
||||
---
|
||||
|
||||
# ADHOC-2026-06-03 - Ad Hoc Fixes
|
||||
|
||||
## Add Graph Explorer Make Target
|
||||
|
||||
```task
|
||||
id: ADHOC-2026-06-03-T01
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "5605e418-95f4-4658-8021-9ee6f00de537"
|
||||
```
|
||||
|
||||
The graph explorer is served by the registry HTTP service, but starting it
|
||||
currently requires remembering the full registry command and database path.
|
||||
|
||||
Add a Makefile target that starts the registry-backed graph explorer from the
|
||||
repo root with defaults for the local database, host, and port. Calling `make`
|
||||
without an explicit target should list available targets rather than start a
|
||||
long-running service. Document the target and available overrides.
|
||||
|
||||
Result: Added `make graph-explorer`, with `registry` as an alias, defaulting to
|
||||
`.railiance-fabric/registry.sqlite3`, `127.0.0.1`, and port `8765`. Plain
|
||||
`make` now prints the available targets instead of starting the service. The
|
||||
target uses `python3 -m railiance_fabric.server`, so it works from the checkout
|
||||
without requiring an installed console script. Updated the README and graph
|
||||
explorer operations guide with the target and override examples.
|
||||
|
||||
Verification:
|
||||
|
||||
- Confirmed plain `make` lists available targets.
|
||||
- Started `make graph-explorer PORT=9877 REGISTRY_DB=/tmp/railiance-fabric-make-test.sqlite3`.
|
||||
- Confirmed `GET http://127.0.0.1:9877/status` returned `status: ok`.
|
||||
- Stopped the temporary verification server on port `9877`.
|
||||
34
workplans/archived/260702-ADHOC-2026-06-06.md
Normal file
34
workplans/archived/260702-ADHOC-2026-06-06.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
id: ADHOC-2026-06-06
|
||||
type: workplan
|
||||
title: "Ad Hoc Fixes 2026-06-06"
|
||||
domain: railiance
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-06-06"
|
||||
updated: "2026-06-06"
|
||||
state_hub_workstream_id: "02426929-e247-4fbf-8072-ea05cac41e93"
|
||||
---
|
||||
|
||||
# ADHOC-2026-06-06 - Ad Hoc Fixes
|
||||
|
||||
## Document Semantic Attractors
|
||||
|
||||
```task
|
||||
id: ADHOC-2026-06-06-T01
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "982d1571-128c-40de-bedf-5d70b2ffd586"
|
||||
```
|
||||
|
||||
Refine the concept of semantic attractors for the graph explorer: topic-like
|
||||
view entities such as `security`, `development`, and `operations` that pull
|
||||
repositories or other entities based on semantic closeness, initially scored
|
||||
from repo `SCOPE.md` files and mapped into spring-layout strength.
|
||||
|
||||
Result: Added `docs/semantic-attractors.md` with the concept model, SCOPE.md
|
||||
scoring approach, score semantics, layout mapping, payload shape, operator
|
||||
workflow, relationship to zones, initial presets, implementation path, and open
|
||||
questions. Linked the concept from the README and graph explorer contract.
|
||||
@@ -0,0 +1,319 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0001
|
||||
type: workplan
|
||||
title: "Railiance Ecosystem Graph Model"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 1
|
||||
state_hub_workstream_id: "bd190990-8e68-49a3-9ce4-0ba89103ea54"
|
||||
created: "2026-05-17"
|
||||
updated: "2026-05-17"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0001 - Railiance Ecosystem Graph Model
|
||||
|
||||
## Goal
|
||||
|
||||
Define and implement the first useful version of the Railiance ecosystem
|
||||
graph: a repo-owned declaration model for services, capabilities, interfaces,
|
||||
and dependencies, plus tooling to validate, inspect, and export that graph.
|
||||
|
||||
The first outcome should be small but real: Railiance can declare that
|
||||
OpenBao provides runtime secrets, NetKingdom provides identity/security
|
||||
architecture, flex-auth provides authorization decisions, CNPG provides
|
||||
PostgreSQL, and consumers can declare the exact capability/interface
|
||||
requirements they rely on.
|
||||
|
||||
## Context
|
||||
|
||||
Railiance is moving from independent service setup into a connected ecosystem.
|
||||
Platform services, identity, authorization, object storage, app workloads,
|
||||
automation, and observability are starting to interact.
|
||||
|
||||
The current risk is that dependencies remain implicit: in docs, deployment
|
||||
scripts, assumptions, and agent memory. That makes blast radius hard to see and
|
||||
capability discovery fragile.
|
||||
|
||||
This workplan creates the foundation for a flexible ecosystem graph where:
|
||||
|
||||
- repos declare what they provide and consume
|
||||
- capabilities are stable semantic contracts
|
||||
- interfaces describe concrete integration surfaces
|
||||
- dependencies capture consumer requirements
|
||||
- bindings connect consumers to providers
|
||||
- State Hub can ingest the result as a read model
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- define vocabulary for repo, service, capability, interface, dependency, and
|
||||
binding
|
||||
- define YAML schemas for repo-owned declarations
|
||||
- create examples for current Railiance services and cross-domain integrations
|
||||
- implement a local graph loader and validator
|
||||
- implement basic discovery queries and graph export
|
||||
- define State Hub ingestion shape without making State Hub the authoring
|
||||
surface
|
||||
- document adoption guidance for other repos
|
||||
|
||||
Out of scope:
|
||||
|
||||
- replacing State Hub workstream/task/capability catalog ownership
|
||||
- deployment orchestration or GitOps
|
||||
- service mesh runtime traffic discovery
|
||||
- enforcing production rollout gates before the model is proven
|
||||
- complete static code analysis across all repos
|
||||
|
||||
## Initial Model
|
||||
|
||||
Suggested declaration layout inside each participating repo:
|
||||
|
||||
```text
|
||||
fabric/
|
||||
services/*.yaml
|
||||
capabilities/*.yaml
|
||||
interfaces/*.yaml
|
||||
dependencies/*.yaml
|
||||
```
|
||||
|
||||
Suggested edge model:
|
||||
|
||||
```text
|
||||
Repository
|
||||
produces Service
|
||||
provides Capability
|
||||
exposes Interface
|
||||
consumes Dependency
|
||||
|
||||
Dependency
|
||||
requires Capability
|
||||
optionally constrains Interface, version, environment, auth, tenant,
|
||||
data_class, criticality, and fallback
|
||||
|
||||
Binding
|
||||
resolves Dependency -> Capability/Interface
|
||||
```
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Intent And Vocabulary Baseline
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "7a74b4cf-6e0e-468c-8426-7dd85c027a21"
|
||||
```
|
||||
|
||||
Create `INTENT.md` and establish the initial vocabulary: repository, service,
|
||||
capability, interface, dependency, and binding.
|
||||
|
||||
Done when the repo has a clear intent document that distinguishes repo-owned
|
||||
declarations from State Hub's read-model role.
|
||||
|
||||
### T02 - Declaration Schema Design
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "eb4be5b3-7440-43ce-8af3-8da371cab8a5"
|
||||
```
|
||||
|
||||
Define the first YAML schema set:
|
||||
|
||||
- `ServiceDeclaration`
|
||||
- `CapabilityDeclaration`
|
||||
- `InterfaceDeclaration`
|
||||
- `DependencyDeclaration`
|
||||
- `BindingOverride` or `BindingAssertion`
|
||||
|
||||
Include fields for:
|
||||
|
||||
- id, name, owner, repo, domain
|
||||
- lifecycle status: planned, active, deprecated, retired
|
||||
- environment: dev, staging, prod, all
|
||||
- interface type and version
|
||||
- auth method
|
||||
- data classification
|
||||
- criticality
|
||||
- compatibility constraints
|
||||
- source links
|
||||
|
||||
Done when schemas are documented and have example valid/invalid fixtures.
|
||||
|
||||
### T03 - Core Capability Type Catalog
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "070098b9-53b6-42d2-a041-e98b5c5ddcc7"
|
||||
```
|
||||
|
||||
Define the first catalog of capability and interface types.
|
||||
|
||||
Initial capabilities:
|
||||
|
||||
- runtime secrets
|
||||
- IAM Profile issuer
|
||||
- authorization decision service
|
||||
- PostgreSQL database service
|
||||
- Redis-compatible cache
|
||||
- object storage
|
||||
- object-storage credential vending
|
||||
- audit/event sink
|
||||
- scope generation
|
||||
|
||||
Initial interface types:
|
||||
|
||||
- HTTP API
|
||||
- OIDC discovery
|
||||
- Kubernetes Secret
|
||||
- Kubernetes CRD
|
||||
- Helm release
|
||||
- CLI
|
||||
- database connection
|
||||
- object-storage bucket
|
||||
- event stream
|
||||
- policy package
|
||||
- OpenBao KV v2 mount
|
||||
- OpenBao dynamic credential role
|
||||
|
||||
Done when the type catalog is explicit enough for examples to avoid ad hoc
|
||||
strings.
|
||||
|
||||
### T04 - Example Declarations For Core Services
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "cfbc8d6e-58a3-4359-baf4-369d3357f6f5"
|
||||
```
|
||||
|
||||
Create seed declarations for known Railiance ecosystem capabilities:
|
||||
|
||||
- OpenBao as `runtime-secrets`
|
||||
- NetKingdom IAM Profile as identity contract
|
||||
- key-cape as lightweight IAM Profile implementation
|
||||
- flex-auth as authorization decision control plane
|
||||
- Topaz as delegated PDP runtime
|
||||
- CloudNativePG as PostgreSQL service
|
||||
- Valkey as Redis-compatible cache
|
||||
- object storage and STS credential vending as planned capabilities
|
||||
- State Hub as coordination/read-model service
|
||||
- repo-scoping as scope-generation provider
|
||||
|
||||
Done when the first graph has real provider nodes and at least a few consumer
|
||||
requirements.
|
||||
|
||||
### T05 - Graph Loader And Validator
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T05
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "59e46f73-04ba-464c-acbb-767169525d43"
|
||||
```
|
||||
|
||||
Implement a local tool that loads declarations from one or more repo roots,
|
||||
validates schema conformance, and builds an in-memory graph.
|
||||
|
||||
Validation should catch:
|
||||
|
||||
- duplicate ids
|
||||
- missing provider capability for required dependencies
|
||||
- unknown interface or capability types
|
||||
- incompatible environment/status constraints
|
||||
- missing source links for active production dependencies
|
||||
- circular dependency warnings where relevant
|
||||
|
||||
Done when `railiance-fabric validate <repo...>` can run against the seed
|
||||
examples and produce useful diagnostics.
|
||||
|
||||
### T06 - Discovery Queries And Exports
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "ee50217c-8cdc-4c18-bb15-9fed35599d6c"
|
||||
```
|
||||
|
||||
Add initial query commands:
|
||||
|
||||
- list providers for a capability
|
||||
- list consumers of a capability/interface
|
||||
- show dependency path for a service
|
||||
- show missing or unresolved dependencies
|
||||
- show blast radius for an interface version change
|
||||
- export graph as JSON
|
||||
- export graph as Mermaid for documentation
|
||||
|
||||
Done when a human or agent can answer "who consumes OpenBao?" and "what
|
||||
capabilities are missing?" from local files.
|
||||
|
||||
### T07 - State Hub Integration Contract
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T07
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "32587d7a-565d-4457-a7ed-61e6f16f781a"
|
||||
```
|
||||
|
||||
Define how State Hub ingests Railiance Fabric graph exports.
|
||||
|
||||
The integration contract must preserve the source-of-truth boundary:
|
||||
|
||||
- repo declarations are authoritative
|
||||
- Railiance Fabric validates and exports
|
||||
- State Hub stores or displays the read model
|
||||
- State Hub links graph nodes to topics, repos, workstreams, tasks, and
|
||||
progress events where useful
|
||||
|
||||
Done when there is a documented export shape and a proposed ingestion path for
|
||||
State Hub.
|
||||
|
||||
### T08 - Adoption Guide And First Repo Rollout
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T08
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "c13b29a7-053c-4f16-ab71-75fba966897e"
|
||||
```
|
||||
|
||||
Write an adoption guide and apply the first declarations to a small set of
|
||||
repos.
|
||||
|
||||
Suggested first rollout:
|
||||
|
||||
- `railiance-platform`
|
||||
- `net-kingdom`
|
||||
- `flex-auth`
|
||||
- `artifact-store`
|
||||
- `repo-scoping`
|
||||
- `the-custodian/state-hub`
|
||||
|
||||
Done when another repo can add declarations without reading Railiance Fabric
|
||||
source code.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `INTENT.md` clearly defines why Railiance Fabric exists.
|
||||
- The repo contains a documented schema for services, capabilities,
|
||||
interfaces, dependencies, and bindings.
|
||||
- Seed declarations represent at least OpenBao, NetKingdom IAM, flex-auth,
|
||||
CNPG, object storage, and State Hub.
|
||||
- A local validation command can detect missing providers and type mistakes.
|
||||
- A local query can list providers and consumers for a capability.
|
||||
- A graph export can be consumed by State Hub without making State Hub the
|
||||
authoring surface.
|
||||
- Adoption guidance exists for adding declarations to other repos.
|
||||
@@ -0,0 +1,193 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0002
|
||||
type: workplan
|
||||
title: "Railiance Ecosystem Registry Service"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 2
|
||||
state_hub_workstream_id: "eab084f2-b71e-45c7-ae9c-8528b69f8dec"
|
||||
created: "2026-05-17"
|
||||
updated: "2026-05-17"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0002 - Railiance Ecosystem Registry Service
|
||||
|
||||
## Goal
|
||||
|
||||
Create the first service interface for registering repositories and interacting
|
||||
with the Railiance ecosystem model across repos.
|
||||
|
||||
The service should make Fabric declarations queryable without requiring every
|
||||
agent or dashboard to clone every repo and run the local CLI. It should remain
|
||||
an indexed read model over repo-owned declarations, not a central editor for
|
||||
those declarations.
|
||||
|
||||
## Context
|
||||
|
||||
RAIL-FAB-WP-0001 created the repo-owned graph declaration model, validator,
|
||||
query CLI, and State Hub export contract.
|
||||
|
||||
The next useful step is a service that can:
|
||||
|
||||
- register participating repos
|
||||
- ingest validated graph snapshots by repo and commit
|
||||
- expose providers, consumers, unresolved dependencies, dependency paths, and
|
||||
blast-radius queries over the combined ecosystem graph
|
||||
- attach supporting artifacts such as CycloneDX SBOMs, OpenAPI contracts,
|
||||
AsyncAPI contracts, and Score workload intent
|
||||
- project graph data to State Hub and, later, Backstage or xRegistry-compatible
|
||||
views
|
||||
|
||||
## Direction
|
||||
|
||||
Use `docs/ecosystem-registry-service.md` as the design baseline.
|
||||
|
||||
The closest external comparison point is CNCF xRegistry because it defines an
|
||||
extensible metadata registry model with document/API views, versioned resources,
|
||||
filtering, import/export, and endpoint/schema/message extensions. Railiance
|
||||
should keep an xRegistry-compatible projection path, while preserving the
|
||||
Fabric graph model as the repo-native source of truth.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- define the registry service API and storage model
|
||||
- implement repository registration
|
||||
- implement snapshot ingestion for `FabricGraphExport`
|
||||
- reuse the existing Fabric loader, validator, graph builder, and query logic
|
||||
- store validation results per repo and commit
|
||||
- expose initial HTTP query endpoints matching current CLI queries
|
||||
- expose State Hub export data from the latest accepted snapshots
|
||||
- support artifact attachment metadata for OpenAPI, AsyncAPI, and CycloneDX
|
||||
- document Backstage and xRegistry projection strategy
|
||||
|
||||
Out of scope:
|
||||
|
||||
- editing repo-owned `fabric/` declarations through the service
|
||||
- provisioning or binding live infrastructure
|
||||
- replacing State Hub planning, task, progress, or workplan state
|
||||
- building a full developer portal
|
||||
- runtime service mesh discovery
|
||||
- mandatory Score adoption
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Service API And Storage Design
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0002-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "e3c219cf-1b81-4209-9f11-a79a78e1bb52"
|
||||
```
|
||||
|
||||
Define the API surface, storage tables, validation semantics, and snapshot
|
||||
replacement rules.
|
||||
|
||||
Done when the repo contains an implementation-ready service design that
|
||||
identifies request/response shapes and storage ownership.
|
||||
|
||||
### T02 - Service Scaffold
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0002-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "ef7363a1-afae-4ac2-a977-6d162b3714e6"
|
||||
```
|
||||
|
||||
Create a lightweight HTTP service that reuses the existing Python loader,
|
||||
validator, graph builder, and export model.
|
||||
|
||||
Done when the service can start locally and expose a health endpoint.
|
||||
|
||||
### T03 - Repository Registration
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0002-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "59323dfe-4702-4b8a-bd60-86d2caea4618"
|
||||
```
|
||||
|
||||
Add endpoints and storage for repository slug, repo URL, default branch,
|
||||
optional State Hub repo id, and ingest configuration.
|
||||
|
||||
Done when repos can be registered, listed, and fetched by slug.
|
||||
|
||||
### T04 - Snapshot Ingestion
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0002-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "807fcb38-839f-43fd-9f45-ad5cd1f70d8f"
|
||||
```
|
||||
|
||||
Add atomic ingestion for `FabricGraphExport` payloads keyed by repo and commit.
|
||||
|
||||
Done when a valid export is accepted, invalid exports are rejected with useful
|
||||
errors, and the latest accepted snapshot is queryable.
|
||||
|
||||
### T05 - Ecosystem Query Endpoints
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0002-T05
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "f3dd0aba-b83c-4066-b0eb-efb07284a7ac"
|
||||
```
|
||||
|
||||
Expose providers, consumers, unresolved dependencies, dependency paths, and
|
||||
blast-radius queries over the latest accepted snapshots.
|
||||
|
||||
Done when HTTP responses match the local CLI answers for the same graph.
|
||||
|
||||
### T06 - Artifact Attachment
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0002-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "95e4e60b-9d32-407e-83d4-c2a532047775"
|
||||
```
|
||||
|
||||
Support artifact metadata for CycloneDX SBOMs, OpenAPI contracts, AsyncAPI
|
||||
contracts, and Score workload files.
|
||||
|
||||
Done when artifacts can be linked to repos, services, or interfaces and surfaced
|
||||
in graph node details.
|
||||
|
||||
### T07 - State Hub Export
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0002-T07
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "5ef7ccea-fd79-498b-99ce-b6bacb00d46d"
|
||||
```
|
||||
|
||||
Expose State Hub export data from the registry's latest accepted snapshots.
|
||||
|
||||
Done when State Hub can fetch the same graph shape documented in
|
||||
`docs/state-hub-integration.md`.
|
||||
|
||||
### T08 - Projection Strategy
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0002-T08
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "285215e6-6018-44be-abea-56eb79c5d349"
|
||||
```
|
||||
|
||||
Document and, if small enough, prototype Backstage and xRegistry projections.
|
||||
|
||||
Done when it is clear which Fabric nodes map to Backstage entities and which
|
||||
parts of the registry can be exposed through xRegistry-style groups, resources,
|
||||
and versions.
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0003
|
||||
type: workplan
|
||||
title: "Registry Feed And Library Inventory"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 3
|
||||
state_hub_workstream_id: "f48f65fb-55a3-48a9-97d5-9ecdac8ba03a"
|
||||
created: "2026-05-17"
|
||||
updated: "2026-05-17"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0003 - Registry Feed And Library Inventory
|
||||
|
||||
## Goal
|
||||
|
||||
Make the local ecosystem registry easy to feed from a repo checkout and make
|
||||
repo library inventory queryable instead of only attaching SBOM files as opaque
|
||||
artifacts.
|
||||
|
||||
## Context
|
||||
|
||||
RAIL-FAB-WP-0002 established the first registry service with repository
|
||||
registration, graph snapshot ingestion, graph queries, artifact attachment, and
|
||||
projection endpoints.
|
||||
|
||||
The next local gap is operability: agents need a simple command to push the
|
||||
current repo graph into a running registry, and CycloneDX SBOMs should become
|
||||
queryable library records.
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Registry Sync Command
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0003-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "b6f34fd2-78e6-4c10-9abd-b7ba547c9b6f"
|
||||
```
|
||||
|
||||
Add a CLI command that validates the current repo, registers it with a running
|
||||
registry service, and pushes the current graph export as a snapshot.
|
||||
|
||||
### T02 - CycloneDX Library Inventory
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0003-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "fdcb5e68-e884-4592-8da7-751b0507d3b0"
|
||||
```
|
||||
|
||||
Add storage, API endpoints, and CLI support for ingesting CycloneDX components
|
||||
as queryable repo library records.
|
||||
|
||||
### T03 - Local Verification And Docs
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0003-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "5fb1c3b9-9e9f-4d50-bb02-b5a74d097cbe"
|
||||
```
|
||||
|
||||
Document the new feed commands and extend registry tests for the library
|
||||
inventory endpoints.
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0004
|
||||
type: workplan
|
||||
title: "Registry Inventory And Drift Views"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 4
|
||||
state_hub_workstream_id: "1c23693e-2288-48bd-81e8-9eedd8ce33e2"
|
||||
created: "2026-05-17"
|
||||
updated: "2026-05-17"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0004 - Registry Inventory And Drift Views
|
||||
|
||||
## Goal
|
||||
|
||||
Make the registry useful as an inspection surface, not only an ingestion
|
||||
surface.
|
||||
|
||||
Agents and humans should be able to ask what a registered repo currently
|
||||
contains, search across graph/library/artifact data, and compare graph snapshots
|
||||
to see what changed.
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Repository Inventory View
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0004-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "13668f00-bdc1-4817-88b4-634388194d78"
|
||||
```
|
||||
|
||||
Add a repo inventory view that returns repository metadata, latest snapshot
|
||||
summary, graph nodes/edges from that snapshot, artifacts, libraries, and counts.
|
||||
|
||||
### T02 - Snapshot Listing And Drift
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0004-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "5f295559-193c-4156-842e-f940633a0d85"
|
||||
```
|
||||
|
||||
Expose snapshot listing and graph drift between two snapshots. By default, drift
|
||||
compares the latest snapshot with the previous snapshot for the same repo.
|
||||
|
||||
### T03 - Registry Search
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0004-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "5d9c630a-29ff-40fb-a630-4870911cd757"
|
||||
```
|
||||
|
||||
Add a simple search endpoint across repositories, graph nodes, artifacts, and
|
||||
libraries.
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0005
|
||||
type: workplan
|
||||
title: "Registry Hardening"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: medium
|
||||
planning_order: 5
|
||||
state_hub_workstream_id: "75c64655-9062-46a3-a706-78ad09852cd6"
|
||||
created: "2026-05-17"
|
||||
updated: "2026-05-17"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0005 - Registry Hardening
|
||||
|
||||
## Goal
|
||||
|
||||
Clean up the registry service for continued local use by removing noisy schema
|
||||
validation warnings, documenting the API contract, and adding a richer
|
||||
diagnostic endpoint.
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Schema Resolver Cleanup
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0005-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "178900ba-a2a4-4f93-a1dd-a626c14e8d66"
|
||||
```
|
||||
|
||||
Replace deprecated `jsonschema.RefResolver` usage with the modern referencing
|
||||
registry API.
|
||||
|
||||
### T02 - Registry Status Endpoint
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0005-T02
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "523f9a35-2285-4b71-915c-9f06698dcc3a"
|
||||
```
|
||||
|
||||
Add a registry `/status` endpoint that reports database path, table counts, and
|
||||
latest accepted snapshots.
|
||||
|
||||
### T03 - API Contract Documentation
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0005-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "d84ebf13-b90b-4296-8987-fc00ba6183ad"
|
||||
```
|
||||
|
||||
Document the current registry HTTP API surface in one focused reference file.
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0006
|
||||
type: workplan
|
||||
title: "Multi-Repo Registry Onboarding"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 6
|
||||
state_hub_workstream_id: "1b8328d9-dc5e-4d3f-957d-5b6b5e9eb1b4"
|
||||
created: "2026-05-17"
|
||||
updated: "2026-05-17"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0006 - Multi-Repo Registry Onboarding
|
||||
|
||||
## Goal
|
||||
|
||||
Make the registry useful with real ecosystem data by registering available
|
||||
Railiance repositories, feeding their graph snapshots and library inventory, and
|
||||
documenting the operating loop agents should use before inspecting the combined
|
||||
model.
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Onboarding Manifest
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0006-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "4a17b588-daa2-4b79-b17a-b5806d96a111"
|
||||
```
|
||||
|
||||
Define the repo onboarding manifest and expected local path, remote, graph,
|
||||
artifact, and SBOM inputs for registry sync.
|
||||
|
||||
### T02 - Multi-Repo Sync Command
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0006-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "d993b52a-d253-4869-9de5-a7e1f1b268ce"
|
||||
```
|
||||
|
||||
Add a local command that can register and sync multiple available Railiance
|
||||
repositories into the registry service.
|
||||
|
||||
### T03 - Verification And Operating Notes
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0006-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "e256b295-eacd-4321-b386-a08c143cdc77"
|
||||
```
|
||||
|
||||
Verify the multi-repo registry loop and document how agents should run it before
|
||||
inspecting the ecosystem model.
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0007
|
||||
type: workplan
|
||||
title: "All Local Repo Onboarding"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: medium
|
||||
planning_order: 7
|
||||
state_hub_workstream_id: "80aba270-4d1d-49b7-8649-61594eed2fcb"
|
||||
created: "2026-05-18"
|
||||
updated: "2026-05-18"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0007 - All Local Repo Onboarding
|
||||
|
||||
## Goal
|
||||
|
||||
Onboard every active State Hub repository with an available local checkout into
|
||||
the local Railiance Fabric registry.
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Local Repo Inventory Manifest
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0007-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "29f4527c-e69b-4a2b-90ac-5a78d4e96095"
|
||||
```
|
||||
|
||||
Generate and commit the all-local State Hub repo onboarding manifest.
|
||||
|
||||
### T02 - Registry Onboarding Run
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0007-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "4890ecac-3199-4684-9262-c5775e4f3ec9"
|
||||
```
|
||||
|
||||
Run the all-local manifest against the local Fabric registry.
|
||||
|
||||
### T03 - Verification And Documentation
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0007-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "dffa7d56-875f-4198-a59b-f6ab0ef3d82e"
|
||||
```
|
||||
|
||||
Verify registry counts and document how to rerun the all-local onboarding.
|
||||
@@ -0,0 +1,269 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0008
|
||||
type: workplan
|
||||
title: "Interactive Fabric Map"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 8
|
||||
state_hub_workstream_id: "0018ee65-dd90-4162-8837-c72d71f0dc9e"
|
||||
created: "2026-05-18"
|
||||
updated: "2026-05-18"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0008 - Interactive Fabric Map
|
||||
|
||||
## Goal
|
||||
|
||||
Build a clever interactive auto-layouting map over the registered Fabric
|
||||
entities so humans and agents can orient inside the infrastructure graph, while
|
||||
keeping the visualization layer reusable enough to serve other graph-producing
|
||||
repos.
|
||||
|
||||
The current repo has static graph exports through JSON and Mermaid. That is
|
||||
useful for snapshots and docs, but it does not yet provide a navigable
|
||||
orientation surface for the registered ecosystem.
|
||||
|
||||
Repo-scoping has already implemented the first serious local graph explorer
|
||||
shape through RREG-WP-0010 and RREG-WP-0011. Fabric should reuse those lessons
|
||||
instead of building a parallel one-off map.
|
||||
|
||||
Reference implementation inputs:
|
||||
|
||||
- `repo-scoping/docs/adr-dependency-graph-visualization-framework.md` selects
|
||||
Cytoscape.js for graph-native pan, zoom, selection, styling, filtering, and
|
||||
path exploration.
|
||||
- `repo-scoping/docs/dependency-visualization-exploration.md` defines the
|
||||
layered graph model, display states, filter rules, manual overrides, and view
|
||||
profiles.
|
||||
- `repo-scoping/src/repo_scoping/core/service.py` exposes Cytoscape-compatible
|
||||
graph payloads with stable keys, metadata-rich nodes and edges, deterministic
|
||||
show/blur/hide visibility evaluation, profile application, hidden element
|
||||
recovery data, and visual sizing hints.
|
||||
- `repo-scoping/src/repo_scoping/web_ui/views.py` provides the current
|
||||
interactive shell: profile controls, filter controls, manual overrides,
|
||||
focus-by-depth, hover popups, selection details, and a layered preset layout.
|
||||
- `repo-scoping/tests/test_web_api.py` verifies the graph endpoint, ad hoc
|
||||
filters, profile CRUD and duplicate behavior, latest-profile defaulting, and
|
||||
UI wiring.
|
||||
|
||||
## Design Direction
|
||||
|
||||
The first Fabric map should be an operational tool, not a landing page. It
|
||||
should open directly into the graph and make the current infrastructure legible
|
||||
through stable grouping, filtering, drill-down, and saved perspectives.
|
||||
|
||||
The map should support:
|
||||
|
||||
- force, cose, concentric, or layered auto-layout with stable seeded positions
|
||||
- grouping by domain, repo, service, capability, interface, dependency, and
|
||||
unresolved status
|
||||
- search across repo slugs, graph ids, names, capabilities, interfaces, and
|
||||
library names
|
||||
- quick filters for review state, active services, external interfaces, missing
|
||||
declarations, unresolved dependencies, blast radius, and dependency path
|
||||
- display states of `show`, `blur`, and `hide`, with deterministic rule
|
||||
precedence and manual overrides
|
||||
- hover and selection detail panels with links back to registry endpoints,
|
||||
State Hub repo ids, workplans, and source files where available
|
||||
- saved view profiles with filter rules, manual overrides, timestamps,
|
||||
duplicate/delete behavior, latest-profile defaulting, URL `profile_id`
|
||||
loading, and orphaned override reporting
|
||||
- shareable map state through URL query parameters, profile ids, or a copied
|
||||
state blob
|
||||
- graceful handling of registered-only repos that do not yet have local
|
||||
`fabric/` declarations
|
||||
|
||||
The reusable engine should be manifest-driven. Fabric and repo-scoping should be
|
||||
able to wire the same interaction shell to different graph-producing services by
|
||||
providing a manifest that describes:
|
||||
|
||||
- graph and profile endpoint URLs
|
||||
- node and edge identity fields
|
||||
- layer ordering and grouping fields
|
||||
- visual encodings for kind, layer, review state, lifecycle, confidence,
|
||||
strength, freshness, and unresolved status
|
||||
- filterable fields and supported rule actions
|
||||
- detail-panel fields and deep links
|
||||
- available modes such as full graph, impact, selected path, neighborhood focus,
|
||||
and onboarding gaps
|
||||
- profile persistence capabilities for each host application
|
||||
|
||||
## Architecture Notes
|
||||
|
||||
Keep the registry as the data source. The UI should consume registry exports and
|
||||
queries rather than reloading repo files directly.
|
||||
|
||||
Refined implementation path:
|
||||
|
||||
- define a host-neutral graph manifest and payload contract that can represent
|
||||
both repo-scoping dependency graphs and Fabric ecosystem graphs
|
||||
- add a Fabric map projection endpoint or CLI export that preserves existing
|
||||
graph ids while adding visual facets expected by the engine
|
||||
- prototype a small local web UI as a reusable graph explorer shell, likely with
|
||||
Cytoscape.js unless the transfer review finds a better fit for the
|
||||
cross-repo contract
|
||||
- wire Fabric through an adapter manifest rather than hard-coding Fabric fields
|
||||
throughout the UI
|
||||
- verify that a repo-scoping adapter could consume the same shell with minimal
|
||||
glue, using RREG-WP-0010 and RREG-WP-0011 behavior as the parity target
|
||||
- decide whether the graph explorer should be extracted into a separate
|
||||
repository after the manifest contract and first two adapters stabilize
|
||||
|
||||
Candidate extraction shape:
|
||||
|
||||
- working name: `graph-explorer-engine`
|
||||
- reusable package: static graph explorer assets plus TypeScript or JSON schema
|
||||
definitions for manifests, payloads, rules, profiles, and visual facets
|
||||
- host adapters: Fabric registry adapter and repo-scoping dependency graph
|
||||
adapter
|
||||
- host responsibilities: authentication, storage, graph projection, profile
|
||||
persistence, and deep-link targets
|
||||
- engine responsibilities: layout, filtering, display-state evaluation if not
|
||||
provided by host, hover and selection UI, profile control surface, focus
|
||||
modes, and shareable state
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Repo-Scoping Transfer Review
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0008-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "9844a9a7-f285-4523-a8d6-4ca62008ce08"
|
||||
```
|
||||
|
||||
Review the repo-scoping graph implementation and turn RREG-WP-0010/RREG-WP-0011
|
||||
into concrete Fabric requirements and reusable-engine requirements.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Identify which repo-scoping behaviors should be reused directly: Cytoscape
|
||||
payload shape, layered layout, show/blur/hide display states, filter rules,
|
||||
manual overrides, view profiles, hover popups, focus depth, latest profile
|
||||
defaulting, review-state filtering, confidence sizing, and strength sizing.
|
||||
- Identify repo-scoping-specific pieces that should remain adapter logic:
|
||||
fact/evidence/feature/capability/ability/scope layers, impact analysis, and
|
||||
candidate-vs-accepted semantics.
|
||||
- Decide the first Fabric visual grammar for repos, services, capabilities,
|
||||
interfaces, dependencies, bindings, libraries, State Hub links, unresolved
|
||||
gaps, and registered-only repos.
|
||||
- Capture a short extraction recommendation before implementation starts.
|
||||
|
||||
### T02 - Manifest And Adapter Contract
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0008-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "cb0cc9f1-5225-47e5-8b47-a945c92e7168"
|
||||
```
|
||||
|
||||
Define the reusable graph explorer manifest, payload, filtering, and profile
|
||||
contract that lets multiple repos mount the same visualization shell.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Define required and optional graph payload fields, including `id`,
|
||||
`stableKey`, `kind`, `layer`, label, description, source references,
|
||||
review/lifecycle state, confidence, freshness, unresolved state, ownership,
|
||||
visual size, edge type, edge strength, same-layer hints, and deep links.
|
||||
- Define a manifest schema for endpoints, layer order, grouping fields, style
|
||||
tokens, detail fields, search fields, filterable fields, graph modes, profile
|
||||
capabilities, and shareable state support.
|
||||
- Decide whether display-state evaluation lives in the host service, the engine,
|
||||
or both with a clear precedence rule.
|
||||
- Include compatibility notes for repo-scoping's existing graph API so an
|
||||
adapter can be added without forcing a repo-scoping rewrite.
|
||||
|
||||
### T03 - Fabric Map Projection
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0008-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "ecd967fc-05ed-4cda-bca2-cf74e26e60b3"
|
||||
```
|
||||
|
||||
Add or shape Fabric registry exports for map-friendly nodes, edges, groups,
|
||||
facets, unresolved gaps, and stable identifiers.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Include registered repositories even when they have no graph snapshot yet.
|
||||
- Include node type, domain, repo, lifecycle, State Hub ids, unresolved flags,
|
||||
declaration source links, and edge type.
|
||||
- Preserve stable ids so layout state, profiles, and deep links do not churn.
|
||||
- Export a manifest-backed graph payload that can be consumed by the reusable
|
||||
shell without Fabric-specific UI branches.
|
||||
|
||||
### T04 - Interactive Graph Explorer Shell
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0008-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "75c1f234-026c-44ed-9c88-db39653b81e0"
|
||||
```
|
||||
|
||||
Build the manifest-driven interactive map shell with layout controls, filtering,
|
||||
search, zoom, pan, hover popups, selection details, focus modes, and profile
|
||||
controls.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- The first screen is the actual map.
|
||||
- Users can search, select, filter, blur, hide, focus by depth, inspect details,
|
||||
and recover hidden or over-filtered elements without leaving the page.
|
||||
- The shell supports profile create/update/duplicate/delete where the host
|
||||
manifest declares persistence support.
|
||||
- The map remains useful with the current sparse state where many repos are
|
||||
registered-only.
|
||||
|
||||
### T05 - Fabric Orientation Workflows
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0008-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "64fe53f1-fbea-4624-8f52-1b5e2a27cf67"
|
||||
```
|
||||
|
||||
Add Fabric-specific workflows for blast-radius exploration, dependency paths,
|
||||
unresolved gaps, repo grouping, onboarding gaps, and shareable context.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Selecting an interface can show consumers and blast radius.
|
||||
- Selecting a service can show its dependency path and provider chain.
|
||||
- Registered-only repos are visible as onboarding gaps rather than noise.
|
||||
- Saved views can separate current operational context from backlog or
|
||||
onboarding cleanup.
|
||||
|
||||
### T06 - Extraction Decision, Verification, And Documentation
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0008-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "d5567337-efe7-4fe6-8379-9e5505e25f6f"
|
||||
```
|
||||
|
||||
Decide whether to extract the graph explorer into a separate repository, verify
|
||||
the Fabric implementation against seeded registry data, and document launch,
|
||||
refresh, manifest, and adapter usage.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Verify against the local registry after `registry/local-repos.yaml` onboarding.
|
||||
- Include at least one automated projection/API test and one UI smoke test.
|
||||
- Include an adapter parity checklist for repo-scoping against
|
||||
RREG-WP-0010/RREG-WP-0011 behavior.
|
||||
- If extraction is recommended, propose the new repo name, source boundaries,
|
||||
package/public API, manifest schema ownership, and migration steps.
|
||||
- Document how to launch the map and how to refresh the underlying registry
|
||||
data.
|
||||
@@ -0,0 +1,254 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0009
|
||||
type: workplan
|
||||
title: "Graph Explorer UI Refinement"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 9
|
||||
created: "2026-05-18"
|
||||
updated: "2026-05-19"
|
||||
state_hub_workstream_id: "1d797e74-bb26-4107-9221-db1248c2cb0e"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0009 - Graph Explorer UI Refinement
|
||||
|
||||
## Goal
|
||||
|
||||
Refine the interactive Fabric graph explorer user interface before extracting
|
||||
it into a shared `graph-explorer-engine` repository. The shell is still local
|
||||
to `railiance-fabric`, so this is the right moment to improve the interaction
|
||||
model, visual hierarchy, orientation workflows, and large-graph ergonomics
|
||||
while the engine boundary is still flexible.
|
||||
|
||||
This workplan intentionally comes before extraction. The goal is to learn from
|
||||
using the Fabric map against the current local registry, then turn the refined
|
||||
UI into a stronger reusable engine candidate.
|
||||
|
||||
## Design Direction
|
||||
|
||||
The explorer should feel like an operational map, not a demo page. It should
|
||||
make the registered infrastructure legible at a glance, then let a user narrow
|
||||
into services, interfaces, dependencies, onboarding gaps, and saved operational
|
||||
views without losing context.
|
||||
|
||||
Refinement should focus on:
|
||||
|
||||
- a calmer, denser toolbar that still exposes the important controls
|
||||
- clearer information architecture for the graph, selection details,
|
||||
orientation hints, saved views, node visibility, and edge visibility
|
||||
- map-first behavior where the graph remains the dominant surface
|
||||
- useful empty, loading, and error states
|
||||
- visual encodings that make repo/service/interface/dependency/binding node types
|
||||
distinguishable without becoming noisy
|
||||
- explicit node-type and edge-type controls that support multi-selection
|
||||
- a filtering model that separates hiding from removing entities from layout
|
||||
- contextual controls that explain which attributes and modifiers apply to
|
||||
which node and edge types
|
||||
- floating map navigation controls and selection anchors that do not depend on
|
||||
changing node borders
|
||||
- better onboarding-gap and unresolved-dependency workflows
|
||||
- URL and browser-local saved views that are understandable to a human user
|
||||
- responsive behavior that remains usable on laptop and narrow screens
|
||||
- bubble-help explanations, keyboard, focus, contrast, and screen-reader basics
|
||||
- explicit seams for a later repo-scoping adapter and shared engine extraction
|
||||
|
||||
## Extraction Guardrail
|
||||
|
||||
Do not extract during this workplan. Extraction should wait until:
|
||||
|
||||
- the Fabric UI refinement has produced a clearer shell contract
|
||||
- the repo-scoping adapter parity work has proven a second real host
|
||||
- any UI assumptions that are Fabric-specific have been moved behind manifest
|
||||
fields, payload metadata, or host-provided mode definitions
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Baseline UI Review
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "a8cfcf75-d03d-4c2f-8d9a-72ea3607775b"
|
||||
```
|
||||
|
||||
Run the current graph explorer against the local registry and capture concrete
|
||||
UI friction before changing the implementation.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Start the local registry and open `/ui/graph-explorer`.
|
||||
- Review desktop and narrow viewport behavior.
|
||||
- Exercise search, filters, mode switching, selection, focus, manual
|
||||
overrides, saved views, copied state URLs, and reset behavior.
|
||||
- Capture a concise refinement backlog in repo docs or the workplan.
|
||||
- Identify which issues block real use and which can wait for extraction.
|
||||
- Confirm where the current UI still says `Layer`, where global controls like
|
||||
Review and Unresolved are ambiguous, and which terms need bubble help.
|
||||
|
||||
Closeout note, 2026-05-19: this task is intentionally dropped as a remaining
|
||||
Codex-side blocker. The in-app browser visual review is unreliable in the
|
||||
desktop sandbox, and it is not required for the actual local service review.
|
||||
The explorer runs locally at `http://127.0.0.1:8765/ui/graph-explorer`, so
|
||||
visual review should happen in a normal browser while Codex continues to use
|
||||
tests, generated JavaScript compilation, and live HTTP checks.
|
||||
|
||||
### T02 - Node And Edge Control Architecture
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "751a2fc5-2263-48b0-9ef2-d55e37a0735c"
|
||||
```
|
||||
|
||||
Refine terminology, toolbar structure, side panel placement, map controls,
|
||||
saved-view controls, legend, hidden-summary surface, and orientation hints so
|
||||
the graph remains central and the controls are easier to scan.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Replace user-facing `Layer` wording with `Nodes`, `Node type`, or
|
||||
`Node types`. Internal manifest fields may keep `layer` until extraction if
|
||||
that avoids churn.
|
||||
- Replace the single node layer selector with a multi-select node type control.
|
||||
- Add a multi-select edge type control for showing and hiding relationships by
|
||||
edge type.
|
||||
- Move pan, zoom, fit, focus, and reset navigation controls into a floating map
|
||||
menu.
|
||||
- Reduce visual clutter in the toolbar without hiding core workflows.
|
||||
- Give selection details, orientation workflows, saved views, and legend
|
||||
predictable places.
|
||||
- Make hidden/blurred overrides and active filters easy to understand.
|
||||
- Keep the first screen as the working map, not documentation.
|
||||
|
||||
### T03 - Graph Readability, Layout Semantics, And Selection Anchors
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "3e60397c-c833-4bd7-ba1b-b754b203dade"
|
||||
```
|
||||
|
||||
Improve graph readability through better node-type styling, labels, edge
|
||||
treatment, selection affordances, unresolved/onboarding markers, layout
|
||||
defaults, and repo-local layout affinity.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Node type colors are distinguishable and not dominated by one hue family.
|
||||
- Node and edge labels do not overwhelm dense views.
|
||||
- Selected, hovered, hidden, blurred, unresolved, and registered-only states are
|
||||
visually distinct.
|
||||
- Selection is represented by an arrow or anchor pointing to the focused entity
|
||||
rather than by relying on border changes.
|
||||
- A selected entity can be hidden and unhidden without losing the selection
|
||||
anchor; the anchor changes only when focus changes.
|
||||
- Repo-local nodes stay closer together than cross-repo relationships, while
|
||||
servers and deployments bind tightly to their runtime/deployment entities and
|
||||
more loosely to service repos.
|
||||
- Default layout gives a useful first impression with the current registry data.
|
||||
|
||||
### T04 - Filter Rule Builder And Visibility Semantics
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "1b446ac8-eeba-4de6-9a32-d7f980d70b93"
|
||||
```
|
||||
|
||||
Design and implement an optional filtering panel that can express detailed
|
||||
node and edge rules without turning type-specific attributes into unexplained
|
||||
global controls.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Users can create a list of rules that target nodes or edges by type and by
|
||||
supported attributes.
|
||||
- Type-specific concepts such as Review and Unresolved appear only when they
|
||||
apply to the selected node or edge types, either as contextual controls or
|
||||
rule templates.
|
||||
- Rules can apply modifiers such as show, hide, blur, highlight, or remove.
|
||||
- Node and edge filtering supports two explicit result modes: hide while
|
||||
preserving the current layout, or remove from layout and redraw the graph.
|
||||
- The active rule list is inspectable, editable, reorderable, and resettable.
|
||||
|
||||
### T05 - Bubble Help, Accessibility, Responsiveness, And Failure States
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "67a9cbc9-ebaa-4cb1-bec9-46bf250faf41"
|
||||
```
|
||||
|
||||
Harden the graph explorer UI for basic accessibility, responsive use, and
|
||||
failure handling before it becomes a candidate shared engine. Explain the
|
||||
domain terms directly where users encounter them.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Add bubble-help explanations to graph terms and controls, including Nodes,
|
||||
Node types, Edge types, Layout, Review, Unresolved, Hide, Remove, Blur,
|
||||
Focus, Fit, and saved views.
|
||||
- Bubble help must explain what the control changes, whether it affects layout,
|
||||
and why a term might not apply to every node or edge type.
|
||||
- Controls have useful labels, focus order, and keyboard-accessible behavior.
|
||||
- Text fits on narrow and desktop viewports.
|
||||
- Loading, empty graph, fetch failure, and missing Cytoscape states are
|
||||
understandable.
|
||||
- Tests cover the static UI wiring for new states and controls.
|
||||
|
||||
### T06 - Repo-Scoping Adapter Readiness Review
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "934ea4d9-0d36-414d-9ed7-10f39410da8d"
|
||||
```
|
||||
|
||||
Review the refined UI against the repo-scoping parity checklist before creating
|
||||
the adapter workplan.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Identify remaining Fabric-specific assumptions in the UI shell.
|
||||
- Confirm which controls should be manifest-driven before extraction.
|
||||
- Confirm that user-facing node and edge terminology can be supplied through
|
||||
manifest labels or host-provided vocabulary without leaking Fabric internals.
|
||||
- Confirm that the rule-panel data model can support repo-scoping manifests as
|
||||
well as Fabric ecosystem manifests.
|
||||
- Update `docs/graph-explorer-operations.md` or contract docs with any refined
|
||||
engine boundary.
|
||||
- Recommend whether the next workplan should be repo-scoping adapter parity or
|
||||
one more Fabric-side UI hardening pass.
|
||||
|
||||
### T07 - Orientation Workflow Polish
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0009-T07
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "6cf1fb8b-9d50-4550-942a-69bc29d14eaa"
|
||||
```
|
||||
|
||||
Make the Fabric-specific orientation workflows easier to use for service
|
||||
dependencies, interface consumers, onboarding gaps, unresolved dependencies,
|
||||
and saved operational contexts after the node, edge, and rule controls are in
|
||||
place.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Selecting a service shows a readable dependency/provider chain.
|
||||
- Selecting an interface shows consumers and impact context.
|
||||
- Registered-only repos are visible as actionable onboarding gaps.
|
||||
- Saved local views have understandable names, status, and sharing behavior.
|
||||
- Orientation workflows reuse the same hide/remove, node type, edge type, and
|
||||
selection anchor semantics as the rest of the map.
|
||||
@@ -0,0 +1,343 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0010
|
||||
type: workplan
|
||||
title: "Repo Reality Scanner"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 10
|
||||
created: "2026-05-19"
|
||||
updated: "2026-05-19"
|
||||
state_hub_workstream_id: "ac88ac5e-7183-47ba-ac05-1a1b44cfd47e"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0010 - Repo Reality Scanner
|
||||
|
||||
## Goal
|
||||
|
||||
Create a facility that scans or rescans repositories and turns observed repo
|
||||
reality into Fabric graph entities: nodes, edges, and attributes. The scanner
|
||||
should combine deterministic extraction rules with LLM-assisted interpretation
|
||||
through `llm-connect`, so the Fabric graph can become more accurate over time
|
||||
without requiring every repository to hand-author perfect declarations first.
|
||||
|
||||
The facility must be safe for repeated rescans. It should avoid duplicate
|
||||
entities, update changed entities, and retire entities that are no longer
|
||||
observable. The result should be a disciplined discovery pipeline that can
|
||||
follow source files, manifests, service catalogs, package registries, API
|
||||
contracts, deployment descriptors, and other systematic sources before asking
|
||||
an LLM to infer higher-level structure.
|
||||
|
||||
## Background
|
||||
|
||||
Railiance Fabric currently treats repo-owned declarations as the authoritative
|
||||
graph source and the registry as a read/index layer. That remains the desired
|
||||
direction for high-confidence data. This workplan adds a discovery layer that
|
||||
can propose, maintain, and explain graph facts gathered from available repos.
|
||||
|
||||
The scanner should not create untraceable graph magic. Every inferred node,
|
||||
edge, and attribute needs source evidence, confidence, extraction method,
|
||||
stable identity, and replacement semantics. Deterministic rules should win
|
||||
where possible; LLM extraction should fill gaps, classify ambiguous evidence,
|
||||
and explain candidate relationships using structured outputs.
|
||||
|
||||
`llm-connect` provides a local Python integration surface for this:
|
||||
|
||||
- `create_adapter(provider, model=...)`
|
||||
- `RunConfig`
|
||||
- `MockLLMAdapter` for offline tests
|
||||
- provider resolution via TOML configuration
|
||||
- typed LLM errors and usage metadata
|
||||
|
||||
## Design Principles
|
||||
|
||||
- Prefer systematic evidence before LLM inference.
|
||||
- Preserve repo-owned declarations as higher-trust data than discovery output.
|
||||
- Make stable entity identity explicit and deterministic.
|
||||
- Treat rescans as replacement runs over a scoped source set, not as append-only
|
||||
guesses.
|
||||
- Keep duplicates from entering the graph by matching stable keys, aliases,
|
||||
source anchors, normalized names, and declared relationships.
|
||||
- Track stale or vanished evidence with tombstones or retired candidates rather
|
||||
than silently leaving old entities active.
|
||||
- Make every candidate explainable: source path, extractor, prompt version,
|
||||
evidence snippets or structured references, confidence, and review state.
|
||||
- Keep LLM prompts small, auditable, testable, and replaceable.
|
||||
- Support dry-run diffs before accepting discovery changes into the registry.
|
||||
|
||||
## Proposed Architecture
|
||||
|
||||
The scanner should produce a `FabricDiscoverySnapshot` for a repository and
|
||||
commit. A snapshot is a normalized candidate graph plus evidence metadata:
|
||||
|
||||
- candidate nodes
|
||||
- candidate edges
|
||||
- candidate attributes
|
||||
- source anchors
|
||||
- extraction provenance
|
||||
- identity keys and aliases
|
||||
- confidence/review state
|
||||
- replacement scope
|
||||
- tombstones for previously observed candidates no longer present
|
||||
|
||||
Accepted scanner output can then be projected into existing `FabricGraphExport`
|
||||
snapshots, graph explorer payloads, and registry drift APIs. Where repo-owned
|
||||
declarations already exist, discovered entities should be matched and attached
|
||||
as supporting evidence rather than duplicated.
|
||||
|
||||
## Identity And Rescan Model
|
||||
|
||||
The key hard problem is identity. Each entity needs:
|
||||
|
||||
- a canonical stable key derived from repo slug, entity kind, normalized name,
|
||||
and source-specific anchors when available
|
||||
- an alias set for names found in code, manifests, package metadata, route
|
||||
names, catalog ids, URLs, container names, deployment names, and service ids
|
||||
- evidence fingerprints for source fragments that explain why the entity
|
||||
exists
|
||||
- relationship keys based on normalized source id, target id, edge type, and
|
||||
evidence scope
|
||||
- a replacement scope that says which extractor owns which candidates for a
|
||||
repo/commit
|
||||
|
||||
On rescan:
|
||||
|
||||
- candidates with the same stable key are updated in place
|
||||
- candidates matching only by alias/fingerprint are merged conservatively and
|
||||
flagged for review
|
||||
- candidates missing from the same replacement scope become retired/tombstoned
|
||||
- repo-owned declarations override discovery candidates where they conflict
|
||||
- unreviewed LLM-only candidates remain candidate/review state, not accepted
|
||||
authoritative declarations
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Discovery Contract And Identity Model
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0010-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "d77423fa-a47f-4246-86bd-ea1ca2d17bc4"
|
||||
```
|
||||
|
||||
Define the discovery snapshot contract, identity keys, alias handling,
|
||||
replacement scopes, provenance fields, confidence/review states, and how
|
||||
discovered facts map into existing Fabric graph exports.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Add schema/docs for `FabricDiscoverySnapshot`, candidate nodes, candidate
|
||||
edges, candidate attributes, source anchors, extractor provenance, and
|
||||
tombstones.
|
||||
- Define stable-key generation rules for services, libraries, interfaces,
|
||||
dependencies, deployment/runtime entities, registries/catalog entries, and
|
||||
generic discovered entities.
|
||||
- Define merge precedence between repo-owned declarations, deterministic
|
||||
discoveries, registry/catalog discoveries, and LLM discoveries.
|
||||
- Define how duplicate candidates are detected and how uncertain matches are
|
||||
flagged for human review.
|
||||
- Define rescan replacement semantics so stale entities are retired only within
|
||||
the source scope that produced them.
|
||||
|
||||
### T02 - Deterministic Repo Extractor Framework
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0010-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "5d2ff304-9c79-4699-bf8c-ed6db3a90d9f"
|
||||
```
|
||||
|
||||
Implement the first deterministic extraction framework for repo-local evidence
|
||||
before involving LLMs.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Add a scanner module and CLI surface that accepts repo path, repo slug,
|
||||
commit, scan profile, and dry-run/output options.
|
||||
- Extract systematic evidence from known file families such as package
|
||||
manifests, lockfiles, Docker/Compose files, OpenAPI/AsyncAPI files, Score
|
||||
files, Helm/Kubernetes manifests, service config files, existing `fabric/`
|
||||
declarations, README/INTENT/SCOPE metadata, and repository metadata.
|
||||
- Emit normalized candidate entities with source anchors and extractor ids.
|
||||
- Keep extractor rules independently testable with fixtures.
|
||||
- Avoid network access by default unless a connector profile explicitly enables
|
||||
registry/catalog lookups.
|
||||
|
||||
### T03 - LLM-Assisted Extraction Through llm-connect
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0010-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "59c206a3-94b9-4f47-9c4f-75f87aa8f505"
|
||||
```
|
||||
|
||||
Add LLM-assisted extraction for ambiguous repo evidence using `llm-connect`
|
||||
with structured, auditable outputs.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Integrate `llm-connect` through a small adapter boundary using
|
||||
`create_adapter`, `RunConfig`, provider/model configuration, and
|
||||
`MockLLMAdapter` tests.
|
||||
- Use deterministic preselection to choose small evidence bundles for the LLM;
|
||||
do not send whole repos blindly.
|
||||
- Require structured JSON output with candidate nodes, edges, attributes,
|
||||
evidence references, confidence, uncertainty, and rationale.
|
||||
- Validate LLM output against the discovery schema before it can enter a
|
||||
snapshot.
|
||||
- Record prompt version, model, provider, usage metadata, and extraction run id.
|
||||
- Fail closed: malformed or low-confidence LLM output becomes a review artifact,
|
||||
not accepted graph data.
|
||||
|
||||
### T04 - Reconciliation, Deduplication, And Tombstones
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0010-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "f0844595-23e0-4e7a-bfd9-e0526b8f85b9"
|
||||
```
|
||||
|
||||
Build the reconciliation engine that merges deterministic, catalog, declaration,
|
||||
and LLM candidates into a coherent repo discovery snapshot.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Match candidates by stable key, source anchor, alias, normalized labels, and
|
||||
relationship fingerprints.
|
||||
- Merge attributes with source-aware precedence and conflict reporting.
|
||||
- Prevent duplicate nodes/edges from entering accepted scanner output.
|
||||
- Produce explicit added/changed/retired/conflicted candidate sets for dry-run
|
||||
review.
|
||||
- Retire vanished candidates only inside their extractor replacement scope.
|
||||
- Preserve historical tombstones long enough to explain graph drift and avoid
|
||||
immediate re-creation loops.
|
||||
|
||||
### T05 - Registry And Catalog Follow-Up Connectors
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0010-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "d664301d-c531-4cf8-a1dd-cbadda0e0fdb"
|
||||
```
|
||||
|
||||
Add connector slots for systematic follow-up against registries and catalogs
|
||||
where a repo points to more authoritative metadata.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Define connector interfaces for package registries, container registries,
|
||||
API catalogs, service catalogs, deployment inventories, and existing Fabric
|
||||
registry data.
|
||||
- Add at least one offline-safe prototype connector using local registry data or
|
||||
fixtures.
|
||||
- Keep connector evidence separate from repo-local evidence in replacement
|
||||
scopes.
|
||||
- Represent connector failures, rate limits, and unavailable catalogs without
|
||||
corrupting repo-local scan results.
|
||||
- Document when connector-derived facts should be accepted, candidate, or
|
||||
review-only.
|
||||
|
||||
### T06 - Registry Integration And Dry-Run Review
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0010-T06
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "9a8420f1-0072-4f40-8d0f-775f59cbe772"
|
||||
```
|
||||
|
||||
Integrate discovery snapshots with the Fabric registry so scans can be reviewed,
|
||||
accepted, and reflected in graph queries without losing provenance.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Add storage/API support for latest discovery snapshots per repo/commit/profile.
|
||||
- Add dry-run diff output that shows candidate additions, changes, retirements,
|
||||
conflicts, duplicate merges, and confidence changes.
|
||||
- Add an accept path that projects accepted discovery output into the combined
|
||||
graph without overwriting repo-owned declarations.
|
||||
- Expose discovery provenance and review state through inventory, graph, drift,
|
||||
and graph explorer payloads.
|
||||
- Preserve existing registry snapshot replacement semantics for accepted graph
|
||||
exports.
|
||||
|
||||
### T07 - Multi-Repo Scan Orchestration
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0010-T07
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "28014246-0a64-4d69-8065-98de881bffb4"
|
||||
```
|
||||
|
||||
Add orchestration so the scanner can run across the known local repo manifests
|
||||
and improve Fabric coverage over time.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Extend or complement `registry sync-manifest` with scan/rescan commands.
|
||||
- Support repo allowlists, scan profiles, max LLM budget, deterministic-only
|
||||
mode, and dry-run mode.
|
||||
- Produce a concise summary across repos: scanned, changed, retired, conflicted,
|
||||
LLM skipped, LLM failed, and accepted.
|
||||
- Keep one repo failure from aborting the entire multi-repo run.
|
||||
- Record enough metadata for State Hub progress notes and future automation.
|
||||
|
||||
### T08 - Tests, Fixtures, Documentation, And Rollout
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0010-T08
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "7a5b7dd7-92c6-4ac5-ae4d-6e73f75aac0d"
|
||||
```
|
||||
|
||||
Harden the scanner with fixture coverage and clear adoption guidance before
|
||||
using it broadly.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Add fixture repos that cover deterministic-only discovery, LLM-assisted
|
||||
discovery, duplicate prevention, vanished entity retirement, declaration
|
||||
override, and connector evidence.
|
||||
- Test rescans across at least three commits/snapshots to prove duplicates are
|
||||
not created and stale entities are retired.
|
||||
- Test with `MockLLMAdapter` so CI does not require network or provider keys.
|
||||
- Document scanner commands, scan profiles, identity model, review workflow,
|
||||
LLM configuration, and failure modes.
|
||||
- Run the first dry-run scan against a small set of local repos and record the
|
||||
resulting implementation backlog.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should discovered entities live only as registry-side candidates, or should
|
||||
accepted discoveries eventually generate repo-owned declaration patches?
|
||||
- Which source types should be accepted without human review, and which should
|
||||
always remain candidates?
|
||||
- How long should tombstones be retained, and should retention be per repo,
|
||||
extractor, or entity kind?
|
||||
- Should LLM extraction be synchronous in CLI scans, queued as background work,
|
||||
or both?
|
||||
- What budget and privacy controls are required before sending repo evidence to
|
||||
an external model provider?
|
||||
|
||||
## Close Criteria
|
||||
|
||||
- A repo can be scanned, rescanned, and diffed without creating duplicate graph
|
||||
entities.
|
||||
- Removed repo evidence causes scoped candidate retirements instead of stale
|
||||
active entities.
|
||||
- LLM-assisted extraction is optional, schema-validated, provenance-rich, and
|
||||
testable offline through `MockLLMAdapter`.
|
||||
- Registry and graph explorer surfaces can show discovered facts with confidence
|
||||
and review status.
|
||||
- The first multi-repo dry run produces useful candidate graph improvements and
|
||||
a clear next implementation backlog.
|
||||
@@ -0,0 +1,313 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0011
|
||||
type: workplan
|
||||
title: "Operational Rescan Loops"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 11
|
||||
created: "2026-05-19"
|
||||
updated: "2026-05-19"
|
||||
state_hub_workstream_id: "b6eb92ee-1aba-49b4-8580-ab15782cb970"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0011 - Operational Rescan Loops
|
||||
|
||||
## Goal
|
||||
|
||||
Turn the repo reality scanner into a regular operational loop that can rescan
|
||||
the local Fabric estate, compare each repo against its latest known discovery
|
||||
state, store useful baselines, surface changes for review, and update the
|
||||
registry without requiring manual JSON handoffs between runs.
|
||||
|
||||
The desired outcome is a boring, repeatable command path that can be run by a
|
||||
human, cron, Codex automation, or a later State Hub operator. A run should answer
|
||||
three practical questions:
|
||||
|
||||
- what changed in the observed repo reality?
|
||||
- what needs review before acceptance?
|
||||
- which repos failed, were skipped, or are becoming stale?
|
||||
|
||||
## Background
|
||||
|
||||
`RAIL-FAB-WP-0010` established the repo reality scanner, deterministic and
|
||||
LLM-assisted extraction, reconciliation, registry discovery snapshot storage,
|
||||
multi-repo `registry scan-manifest`, and the first small rollout dry-run.
|
||||
|
||||
The scanner can already:
|
||||
|
||||
- scan one repo or a manifest of repos
|
||||
- write discovery snapshots to files
|
||||
- reconcile against a previous snapshot directory
|
||||
- ingest discovery snapshots into the Fabric registry
|
||||
- accept candidates that are already review-safe
|
||||
- produce concise per-repo summaries
|
||||
|
||||
The remaining operational gap is that repeated rescans still require too much
|
||||
manual setup: choosing a snapshot directory, exporting previous snapshots,
|
||||
remembering when to ingest, and turning run summaries into a persistent review
|
||||
backlog.
|
||||
|
||||
This workplan closes that gap by making the registry and CLI cooperate around
|
||||
baselines, previous-from-registry diffs, run reports, stale/failure health, and
|
||||
automation-safe modes.
|
||||
|
||||
## Design Principles
|
||||
|
||||
- Default to safe dry-runs and explicit ingest/accept actions.
|
||||
- Prefer the registry as the durable source of prior discovery state.
|
||||
- Keep local snapshot caches useful but optional.
|
||||
- Make unchanged runs cheap and quiet.
|
||||
- Treat conflicts, tombstones, LLM failures, and missing repos as review
|
||||
signals, not as silent noise.
|
||||
- Preserve per-repo failure isolation in every operational mode.
|
||||
- Keep the loop automation-friendly: stable exit codes, machine-readable
|
||||
reports, lock/overlap behavior, and concise human summaries.
|
||||
- Avoid accepting or projecting discovery data unless review state and policy
|
||||
allow it.
|
||||
|
||||
## Proposed Operational Loop
|
||||
|
||||
1. Read `registry/local-repos.yaml` or another onboarding manifest.
|
||||
2. For each selected repo, determine the previous discovery snapshot from:
|
||||
- the latest registry snapshot for the same repo/profile, or
|
||||
- a configured local snapshot cache, or
|
||||
- no previous snapshot on first baseline.
|
||||
3. Run the scanner with deterministic rules and explicitly enabled connectors
|
||||
or LLM profile.
|
||||
4. Reconcile current evidence against previous evidence.
|
||||
5. Write an operational run report with per-repo results, diffs, failures,
|
||||
skipped LLM state, review artifact counts, and accepted/ingested ids.
|
||||
6. Optionally ingest changed or baseline snapshots into the registry.
|
||||
7. Optionally project candidates only when policy says they are acceptable.
|
||||
8. Expose the run result through registry/status endpoints and State Hub
|
||||
progress notes.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- CLI and registry support for previous-from-registry rescans.
|
||||
- Standard local snapshot/report directory conventions.
|
||||
- Run reports that can be consumed by humans and automation.
|
||||
- Idempotent ingest behavior for unchanged runs.
|
||||
- Review-oriented summary output and health status.
|
||||
- Documentation and tests for recurring use.
|
||||
|
||||
Out of scope for this workplan:
|
||||
|
||||
- A full review UI for discovery conflicts and tombstones.
|
||||
- Live server/deployment inventory connectors beyond existing local connector
|
||||
mechanics.
|
||||
- Auto-generating repo-owned Fabric declaration patches from accepted
|
||||
discoveries.
|
||||
- Enabling external LLM providers by default.
|
||||
|
||||
Those are likely follow-up workplans once the operational loop produces steady
|
||||
baseline data.
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Snapshot Cache And Baseline Conventions
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0011-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "cb6f05b6-ae8c-47b1-aead-4505276b089f"
|
||||
```
|
||||
|
||||
Define and implement the local baseline conventions for repeated discovery
|
||||
scans.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Define a standard local directory, likely `.fabric-discovery/`, for snapshot
|
||||
caches and run reports.
|
||||
- Decide whether the directory is ignored, partially checked in, or fully local
|
||||
operational state; document the reason.
|
||||
- Add CLI defaults or manifest configuration so `scan-manifest` can write and
|
||||
read this directory without repeated flags.
|
||||
- Preserve explicit `--output-dir` and `--previous-dir` overrides.
|
||||
- Ensure output filenames remain stable by repo slug and scan profile.
|
||||
- Add tests that prove first-baseline runs create predictable snapshot/report
|
||||
paths without affecting registry state in dry-run mode.
|
||||
|
||||
### T02 - Previous-From-Registry Reconciliation
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0011-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "ee8e5437-3c87-473c-99a0-84d947d09249"
|
||||
```
|
||||
|
||||
Allow manifest rescans to diff against the latest stored discovery snapshot in
|
||||
the registry, so operators do not need to export JSON before every run.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Add a `scan-manifest` option such as `--previous-source registry|dir|none`
|
||||
or `--previous-from-registry`.
|
||||
- Fetch the latest discovery snapshot for each repo/profile through existing
|
||||
registry discovery APIs.
|
||||
- Fall back cleanly when a repo has no previous registry snapshot and mark the
|
||||
run as a first baseline for that repo.
|
||||
- Keep local `--previous-dir` support for offline or file-based workflows.
|
||||
- Include previous snapshot id/source in per-repo results and run reports.
|
||||
- Add tests for registry previous found, registry previous missing, registry
|
||||
unavailable, and file-directory fallback.
|
||||
|
||||
### T03 - Operational Run Reports
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0011-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "d11621f2-7610-4060-863d-dbf86858a3e6"
|
||||
```
|
||||
|
||||
Persist each rescan loop as a report that can drive review, State Hub notes,
|
||||
and future automation.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Add a report schema or documented JSON shape for manifest rescan runs.
|
||||
- Record command profile, manifest path, selected repos, generated timestamp,
|
||||
scanner version, registry URL, dry-run/ingest/accept flags, and LLM budget
|
||||
policy.
|
||||
- For each repo, record commit, previous source/id, current output path,
|
||||
discovery snapshot id, accepted graph snapshot id, candidate counts, diff
|
||||
counts, review artifact counts, connector run summaries, and errors.
|
||||
- Add `--report-output` and a default report path under the standard
|
||||
operational directory.
|
||||
- Keep console output concise while making the JSON report complete.
|
||||
- Add tests for report content in success, partial failure, and no-change runs.
|
||||
|
||||
### T04 - Idempotent Ingest And Acceptance Policies
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0011-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "c64daf3b-a5ec-4ea9-82b6-f8f352eb9283"
|
||||
```
|
||||
|
||||
Make registry writes safe for recurring execution by avoiding unnecessary
|
||||
snapshot churn and by separating ingest from acceptance policy.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Add a mode to skip ingesting unchanged discovery snapshots unless explicitly
|
||||
requested.
|
||||
- Detect unchanged snapshots by reconciliation diff and/or normalized snapshot
|
||||
fingerprint.
|
||||
- Keep an explicit first-baseline ingest mode for repos with no prior discovery
|
||||
snapshot.
|
||||
- Add acceptance policy controls such as accepted-only, no-conflicts,
|
||||
no-tombstones, selected keys, or selected review states.
|
||||
- Prevent `--accept` from projecting conflicted, needs-review, or low-confidence
|
||||
candidates unless an explicit override is supplied.
|
||||
- Report why a repo was ingested, skipped unchanged, blocked for review, or
|
||||
accepted.
|
||||
- Add tests covering unchanged skip, baseline ingest, changed ingest, blocked
|
||||
acceptance, and explicit acceptance override.
|
||||
|
||||
### T05 - Rescan Health And Registry Surfaces
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0011-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "b3440439-b9c4-4753-98bc-618d1934ed4e"
|
||||
```
|
||||
|
||||
Expose operational rescan state through the registry so humans and tools can
|
||||
see freshness, failures, and review load.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Store or derive latest rescan metadata per repo/profile.
|
||||
- Add registry inventory/status fields for latest discovery run, latest diff
|
||||
counts, latest failure, stale age, and review artifact counts.
|
||||
- Add an endpoint or CLI view for repos needing review.
|
||||
- Add an endpoint or CLI view for repos stale beyond a configurable age.
|
||||
- Keep existing graph and discovery snapshot APIs backward compatible.
|
||||
- Add tests for inventory/status output after baseline, changed, failed, and
|
||||
stale runs.
|
||||
|
||||
### T06 - Automation-Safe Command Mode
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0011-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "7461e6f1-7ef0-4947-9cfa-67f463e9aa00"
|
||||
```
|
||||
|
||||
Make the rescan loop safe to run from cron, Codex automations, or a State Hub
|
||||
operator without bespoke shell glue.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Add a documented command recipe, script, or subcommand for the standard local
|
||||
rescan loop.
|
||||
- Define stable exit codes for success, changes found, review required,
|
||||
partial repo failures, and infrastructure failure.
|
||||
- Add lock/overlap protection so two local rescan loops do not run against the
|
||||
same manifest concurrently.
|
||||
- Keep dry-run as the safe default unless ingest/accept flags are explicit.
|
||||
- Emit concise human output and machine-readable JSON consistently.
|
||||
- Add tests for exit-code policy and lock behavior where practical.
|
||||
|
||||
### T07 - Documentation, Rollout, And First Baseline
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0011-T07
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "9c6f8e33-dd13-48ca-815d-73fd09b25423"
|
||||
```
|
||||
|
||||
Document the operational loop and run a first controlled baseline against a
|
||||
small local repo set before broad adoption.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Document the standard local rescan workflow, registry-backed workflow,
|
||||
report format, exit codes, and failure handling.
|
||||
- Document how to use deterministic-only mode, connector mode, and LLM-capped
|
||||
mode safely.
|
||||
- Document the manual review steps before acceptance.
|
||||
- Run a first baseline loop against a small allowlist such as
|
||||
`repo-scoping`, `llm-connect`, and `railiance-fabric`.
|
||||
- Record the resulting report summary and follow-up backlog in docs and State
|
||||
Hub progress.
|
||||
- Mark this workplan ready for broader all-local-repo rollout only after the
|
||||
small baseline loop is repeatable.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should local discovery caches be committed, ignored, or treated as operator
|
||||
runtime state only?
|
||||
- Should the registry store every run report or only latest run metadata?
|
||||
- What is the right default stale age for local repos: daily, weekly, or based
|
||||
on commit changes?
|
||||
- Should exit code `0` mean "no infrastructure failure" or "no changes found"?
|
||||
- Which acceptance policies are safe enough for unattended operation?
|
||||
- Should State Hub receive one progress note per run or only when changes,
|
||||
failures, or review-required conditions appear?
|
||||
|
||||
## Close Criteria
|
||||
|
||||
- A single documented command can perform a safe repeated rescan loop across a
|
||||
manifest.
|
||||
- The command can diff against registry-stored previous discovery snapshots.
|
||||
- First-baseline, unchanged, changed, failed, and review-required repos are
|
||||
distinguishable in console output, JSON reports, and registry status.
|
||||
- Repeated runs do not create noisy duplicate registry snapshots by default.
|
||||
- Acceptance remains explicit and policy-gated.
|
||||
- Tests cover the recurring loop behavior well enough to trust automation.
|
||||
@@ -0,0 +1,233 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0012
|
||||
type: workplan
|
||||
title: "Baseline Rollout And Conflict Review"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 12
|
||||
created: "2026-05-20"
|
||||
updated: "2026-05-20"
|
||||
state_hub_workstream_id: "c7f85db5-59db-4f4b-bfe5-f984edb201f9"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0012 - Baseline Rollout And Conflict Review
|
||||
|
||||
## Goal
|
||||
|
||||
Start using the operational rescan loop in anger: run the local Fabric registry,
|
||||
ingest a controlled baseline for a small repo allowlist, review the
|
||||
`repo-scoping` discovery conflicts found by the dry-run, and decide whether the
|
||||
baseline is clean enough to expand toward all-local-repo rollout.
|
||||
|
||||
The implementation should prove that `RAIL-FAB-WP-0011` is not just a command
|
||||
surface, but a usable operating loop for keeping Fabric discovery state fresh.
|
||||
|
||||
## Background
|
||||
|
||||
`RAIL-FAB-WP-0011` implemented:
|
||||
|
||||
- `.fabric-discovery` snapshot/report caches
|
||||
- previous-from-registry reconciliation
|
||||
- idempotent unchanged ingest skipping
|
||||
- safe acceptance policy
|
||||
- registry discovery health/status surfaces
|
||||
- automation-safe exit codes and locking
|
||||
|
||||
The first local-cache dry-run on 2026-05-20 scanned:
|
||||
|
||||
- `repo-scoping`
|
||||
- `llm-connect`
|
||||
- `railiance-fabric`
|
||||
|
||||
It completed with 3 scanned repos, 2 baselines, 1 changed repo, 7 conflicts, and
|
||||
1 review-required repo. The registry-backed path could not run because the
|
||||
local Fabric registry service was not listening on `127.0.0.1:8765`.
|
||||
|
||||
## Design Principles
|
||||
|
||||
- Keep the first baseline small and inspectable.
|
||||
- Do not broaden to all repos while review conflicts are still unexplained.
|
||||
- Prefer ingesting discovery baselines over accepting/projection until the
|
||||
conflict set is understood.
|
||||
- Treat the registry service bootstrap as operational setup, not a source-code
|
||||
feature unless implementation gaps appear.
|
||||
- Record enough evidence in docs and State Hub to make the next operator run
|
||||
repeatable.
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Registry Service Bootstrap
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0012-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "53880e37-6800-47db-8c35-4278eb241da4"
|
||||
```
|
||||
|
||||
Start or verify the local Fabric registry service on `127.0.0.1:8765` using the
|
||||
repo-local `.railiance-fabric/registry.sqlite3` database.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Verify whether a registry service is already listening on `127.0.0.1:8765`.
|
||||
- Start `railiance-fabric-registry --db .railiance-fabric/registry.sqlite3 --port 8765` when needed.
|
||||
- Confirm `/health`, `/status`, and graph explorer routes respond.
|
||||
- Record the service command, database path, and log path used for the session.
|
||||
- Avoid changing source code unless startup reveals a real defect.
|
||||
|
||||
### T02 - Controlled Baseline Ingest
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0012-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "1b945a9e-6193-4e34-8e3b-9b2d5a6aa828"
|
||||
```
|
||||
|
||||
Run the small allowlist operational rescan against the live registry and ingest
|
||||
baseline discovery snapshots.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Use allowlist: `repo-scoping`, `llm-connect`, `railiance-fabric`.
|
||||
- Use `--previous-from-registry` and `--ingest`; do not use `--accept` yet.
|
||||
- Confirm registry-backed first-baseline behavior for repos without prior
|
||||
discovery snapshots.
|
||||
- Confirm unchanged follow-up runs skip ingest by default.
|
||||
- Record discovery snapshot ids, report path, counts, and review-required
|
||||
conditions.
|
||||
|
||||
### T03 - Repo-Scoping Conflict Review
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0012-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "52e18533-df3f-4478-84bd-f8fa688d83e3"
|
||||
```
|
||||
|
||||
Inspect the `repo-scoping` conflicts from the rescan report and classify what
|
||||
they mean.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Open the latest report and/or discovery snapshot for `repo-scoping`.
|
||||
- List the 7 conflicted candidates by stable key, kind, label, and evidence.
|
||||
- Determine whether conflicts are expected duplicate-detection noise, real
|
||||
declaration/discovery disagreement, or scanner identity defects.
|
||||
- Capture recommended action for each conflict: accept, ignore, improve
|
||||
scanner identity, improve repo declarations, or create follow-up workplan.
|
||||
- Do not project accepted graph changes until this review is complete.
|
||||
|
||||
Review result:
|
||||
|
||||
- Latest `repo-scoping` discovery snapshot: `4`, commit
|
||||
`fd7f25866a94897acfdefaafc83a9d8336c1081b`, generated
|
||||
`2026-05-20T21:21:22Z`.
|
||||
- Conflicted candidates are all `Lockfile` nodes with labels `uv.lock` or
|
||||
`package-lock.json` under distinct `var/checkouts/...` paths:
|
||||
`llm-connect-ce2118b9dc59/uv.lock`,
|
||||
`markitect-main-1e0f80026926/package-lock.json`,
|
||||
`ops-bridge-9733411215b8/uv.lock`,
|
||||
`ops-warden-eac790a4872c/uv.lock`,
|
||||
`railiance-cluster-95d336518aae/uv.lock`,
|
||||
`vergabe-teilnahme-336b6f081ec8/package-lock.json`, and
|
||||
`vergabe-teilnahme-336b6f081ec8/uv.lock`.
|
||||
- Classification: duplicate-detection noise for path-scoped lockfile entities.
|
||||
The scanner is treating same kind plus same normalized label as enough to
|
||||
raise `possible_duplicate_node`, even when source paths clearly distinguish
|
||||
separate lockfiles.
|
||||
- Recommended action: refine duplicate detection for path-scoped nodes before
|
||||
broad rollout or acceptance projection. Lockfiles should require matching
|
||||
source anchor/path identity, not label alone, before being treated as possible
|
||||
duplicates.
|
||||
|
||||
### T04 - Acceptance Policy Trial
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0012-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "7ceaa12a-8044-4fa1-82c3-d202a815e494"
|
||||
```
|
||||
|
||||
Exercise the safe acceptance policy on the clean subset without forcing
|
||||
conflicted candidates through projection.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Identify whether `llm-connect` and `railiance-fabric` have accepted
|
||||
repo-owned declaration candidates suitable for projection.
|
||||
- Run accept only where the safe policy allows it.
|
||||
- Verify projected graph snapshots do not overwrite repo-owned declarations.
|
||||
- Confirm `registry rescan-status --review-only` still highlights unresolved
|
||||
conflict/review work.
|
||||
- Record any blocked acceptance reasons.
|
||||
|
||||
Trial result:
|
||||
|
||||
- `llm-connect` discovery snapshot `2` is clean but contains only
|
||||
`candidate` review-state discoveries, so no candidates were projected.
|
||||
- `railiance-fabric` discovery snapshot `3` is clean, has accepted
|
||||
repo-declaration candidates, and was projected into accepted graph snapshot
|
||||
`24` with 49 nodes and 63 edges.
|
||||
- Projection appended a new graph snapshot with commit
|
||||
`discovery:9ad2750965f0100adcee2473b31ede6f7098205c`; it did not mutate the
|
||||
earlier repo-owned graph snapshots.
|
||||
- `registry rescan-status --review-only` still shows only `repo-scoping`
|
||||
snapshot `4` as review-required.
|
||||
|
||||
### T05 - Rollout Readiness Decision
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0012-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "4a73225c-18ce-4ba6-89b9-cdc8c76ca5d9"
|
||||
```
|
||||
|
||||
Decide whether the operational loop is ready for all-local-repo rollout or
|
||||
needs another targeted refinement first.
|
||||
|
||||
Acceptance notes:
|
||||
|
||||
- Summarize the small baseline outcome in docs and State Hub.
|
||||
- State whether broad rollout is recommended now, recommended after conflict
|
||||
fixes, or blocked.
|
||||
- If blocked or deferred, create a focused follow-up backlog item/workplan.
|
||||
- If ready, propose the command and guardrails for all-local-repo baseline
|
||||
ingestion.
|
||||
|
||||
Decision:
|
||||
|
||||
- Broad all-local-repo rollout is deferred until duplicate detection respects
|
||||
path-scoped node identity for lockfile-style evidence.
|
||||
- The operational loop itself is usable: registry service bootstrap, baseline
|
||||
ingest, unchanged skip, review-only status, and safe projection for clean
|
||||
accepted declarations all worked locally.
|
||||
- Follow-up: `RAIL-FAB-WP-0013` owns the path-scoped duplicate identity
|
||||
refinement and should be completed before the next broad rollout attempt.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Are `repo-scoping` conflicts caused by stale cache baselines from before the
|
||||
latest scanner refinements?
|
||||
- Should the first ingested baseline include conflicted discovery snapshots, or
|
||||
should conflicted repos be ingested only after review?
|
||||
- Should the registry service be treated as a long-running local service with a
|
||||
documented startup command, or should this repo provide a helper command?
|
||||
|
||||
## Close Criteria
|
||||
|
||||
- The local registry service is running and verified.
|
||||
- The three-repo controlled baseline has been run against registry-backed
|
||||
previous snapshots.
|
||||
- Baseline discovery snapshots are ingested or intentionally withheld with
|
||||
reasons.
|
||||
- `repo-scoping` conflicts are classified and turned into concrete next steps.
|
||||
- We know whether to proceed to all-local-repo rollout.
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0013
|
||||
type: workplan
|
||||
title: "Path Scoped Duplicate Identity"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 13
|
||||
created: "2026-05-20"
|
||||
updated: "2026-05-20"
|
||||
state_hub_workstream_id: "bf80900b-606c-442c-aa15-d6272d73a8d6"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0013 - Path Scoped Duplicate Identity
|
||||
|
||||
## Goal
|
||||
|
||||
Refine discovery reconciliation so path-scoped nodes, starting with `Lockfile`
|
||||
candidates, are not marked as duplicate entities solely because they share the
|
||||
same display label.
|
||||
|
||||
This unblocks broad local-repo rollout by making rescan review output point to
|
||||
real identity concerns instead of expected repeated files such as `uv.lock` and
|
||||
`package-lock.json` across different checkouts.
|
||||
|
||||
## Background
|
||||
|
||||
`RAIL-FAB-WP-0012` ingested a controlled three-repo baseline into the local
|
||||
Fabric registry. The only review-required repo was `repo-scoping`; all seven
|
||||
conflicted candidates were `Lockfile` nodes with labels `uv.lock` or
|
||||
`package-lock.json` under distinct `var/checkouts/...` paths.
|
||||
|
||||
The current duplicate detector compares node kind plus normalized label/alias.
|
||||
That is useful for semantic declaration nodes, but too broad for file-backed
|
||||
path-scoped evidence.
|
||||
|
||||
## Design Principles
|
||||
|
||||
- Keep semantic duplicate detection intact for declaration-like nodes.
|
||||
- For path-scoped node kinds, require matching source path identity before
|
||||
treating same-label nodes as possible duplicates.
|
||||
- Preserve conservative behavior when source path evidence is missing.
|
||||
- Add a regression test that mirrors the `repo-scoping` false-positive shape.
|
||||
- Rerun the controlled baseline before recommending broad rollout.
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Add Path-Scoped Reconciliation Coverage
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0013-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "8d9cb1c2-77f7-45da-b942-a8d68454477a"
|
||||
```
|
||||
|
||||
Add tests proving that same-label `Lockfile` nodes at different source paths do
|
||||
not raise `possible_duplicate_node`, while same-label semantic nodes still do.
|
||||
|
||||
### T02 - Implement Path-Aware Duplicate Detection
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0013-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "7d4d439d-4f7f-4bdd-bc5f-b02524a10684"
|
||||
```
|
||||
|
||||
Update reconciliation duplicate detection so path-scoped node kinds compare
|
||||
source anchors before emitting duplicate conflicts.
|
||||
|
||||
### T03 - Verify Controlled Rescan
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0013-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "0d6cad1d-16f8-4ac7-b8d3-b62a2f8e4549"
|
||||
```
|
||||
|
||||
Rerun the three-repo controlled rescan against the local registry and confirm
|
||||
that `repo-scoping` no longer reports the seven lockfile duplicate conflicts.
|
||||
|
||||
Verification result:
|
||||
|
||||
- Command: `registry scan-manifest registry/local-repos.yaml --repo-slug
|
||||
repo-scoping --repo-slug llm-connect --repo-slug railiance-fabric
|
||||
--previous-from-registry --ingest --no-lock`.
|
||||
- Report:
|
||||
`registry/.fabric-discovery/reports/2026-05-20t214250z-deterministic.rescan-report.json`.
|
||||
- Result: 3 scanned, 1 unchanged, 2 changed, 0 retired, 0 conflicted, 0 review
|
||||
required.
|
||||
- `repo-scoping` snapshot `5` still reports 7 changed lockfile candidates, but
|
||||
none are conflicted; the previous false `possible_duplicate_node` warnings
|
||||
are gone.
|
||||
- `registry rescan-status --review-only --json` shows 0 review-required repos.
|
||||
|
||||
### T04 - Rollout Recommendation
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0013-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "4be31147-b060-4b47-9589-8d3d8024879d"
|
||||
```
|
||||
|
||||
Record whether broad all-local-repo baseline ingestion is ready after the
|
||||
identity refinement, or whether another targeted blocker remains.
|
||||
|
||||
Recommendation:
|
||||
|
||||
- Broad all-local-repo baseline ingestion is ready to attempt as an ingest-only
|
||||
operational run.
|
||||
- Keep `--previous-from-registry`, `--ingest`, and no `--accept` for the broad
|
||||
pass; review `registry rescan-status --review-only` before any projection.
|
||||
- Use safe projection only for clean repos with accepted repo-declaration
|
||||
candidates. Do not project candidate-only repositories until their discoveries
|
||||
are reviewed or explicitly accepted.
|
||||
|
||||
## Close Criteria
|
||||
|
||||
- Unit tests cover path-scoped duplicate identity.
|
||||
- Reconciliation keeps semantic duplicate warnings intact.
|
||||
- Controlled rescan no longer flags distinct lockfiles as duplicates.
|
||||
- State Hub and this workplan capture the updated rollout recommendation.
|
||||
@@ -0,0 +1,134 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0014
|
||||
type: workplan
|
||||
title: "Runtime Topology Discovery"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 14
|
||||
created: "2026-05-21"
|
||||
updated: "2026-05-21"
|
||||
state_hub_workstream_id: "9cb51719-3ef1-400a-916e-959b24c67b79"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0014 - Runtime Topology Discovery
|
||||
|
||||
## Goal
|
||||
|
||||
Discover runtime topology before broader projection: servers, ports exposed by
|
||||
services, and domain names that map onto those ports.
|
||||
|
||||
## Background
|
||||
|
||||
The current scanner already discovers deployment-like evidence from Docker
|
||||
Compose, Kubernetes manifests, service configs, and Fabric declarations. The
|
||||
graph explorer can infer some `Server` nodes from accepted interface endpoint
|
||||
URLs, but that inference is UI-local and misses servers/domains/ports that live
|
||||
in runtime manifests.
|
||||
|
||||
Before a full discovery/projection pass, Fabric should capture these runtime
|
||||
facts as normal discovery candidates with source anchors and conservative review
|
||||
state.
|
||||
|
||||
## Design Principles
|
||||
|
||||
- Keep repo-owned declaration schemas unchanged for this increment.
|
||||
- Emit discovery candidates for `Server`, `NetworkPort`, and `DomainName`.
|
||||
- Keep facts source-linked to Compose, Kubernetes, or Fabric declaration files.
|
||||
- Do not resolve DNS or scan networks; only parse deterministic repo evidence.
|
||||
- Avoid projection until the broad runtime discovery pass has been reviewed.
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Add Runtime Topology Test Fixture
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0014-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "714e3560-cd32-4009-8cdd-8ff410cd2725"
|
||||
```
|
||||
|
||||
Extend scanner tests so a fixture repo exposes Compose ports, Kubernetes Service
|
||||
ports, Kubernetes Ingress domains, and Fabric interface endpoint URLs.
|
||||
|
||||
### T02 - Discover Compose Runtime Ports And Domains
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0014-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "20923f1d-6bf7-4f59-a9e5-4898d6f0a699"
|
||||
```
|
||||
|
||||
Extract `Server`, `NetworkPort`, and `DomainName` candidates from Compose
|
||||
published ports and common domain labels such as Traefik `Host(...)`,
|
||||
`VIRTUAL_HOST`, and `LETSENCRYPT_HOST`.
|
||||
|
||||
### T03 - Discover Kubernetes Runtime Ports And Domains
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0014-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "a7664f5e-4530-413d-a1b1-2a1702ac9763"
|
||||
```
|
||||
|
||||
Extract ports from Kubernetes `Service` manifests and domains from `Ingress`
|
||||
rules/TLS hosts, linking domains to the relevant ingress/service/port evidence
|
||||
where possible.
|
||||
|
||||
### T04 - Discover Fabric Endpoint Runtime Facts
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0014-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "4f5e5c34-453c-4c3b-969e-80d5d2b9b370"
|
||||
```
|
||||
|
||||
Extract server/domain/port candidates from `InterfaceDeclaration` endpoint URLs
|
||||
so declared HTTP/database endpoints participate in the same runtime topology
|
||||
view.
|
||||
|
||||
### T05 - Verify Broad Runtime Discovery
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0014-T05
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "4aae0fa0-39a4-401c-ad5f-8d0f7647cfb6"
|
||||
```
|
||||
|
||||
Run the deterministic tests and a broad ingest-only rescan. Confirm server,
|
||||
port, and domain candidates appear without duplicate conflicts or review-only
|
||||
blockers.
|
||||
|
||||
Verification result:
|
||||
|
||||
- `python3 -m pytest` passed with 33 tests.
|
||||
- Broad ingest-only rescan completed with 35 repos scanned, 28 unchanged, 7
|
||||
changed, 0 retired, 0 conflicted, 0 review required, and 0 errors.
|
||||
- Report:
|
||||
`registry/.fabric-discovery/reports/2026-05-20t222151z-deterministic.rescan-report.json`.
|
||||
- Latest discovery snapshots now include 20 `Server`, 26 `NetworkPort`, and 14
|
||||
`DomainName` candidates across `flex-auth`, `net-kingdom`, `railiance-apps`,
|
||||
`railiance-cluster`, `railiance-fabric`, `repo-scoping`, and `state-hub`.
|
||||
- `registry rescan-status --review-only --json` shows 0 review-required repos.
|
||||
|
||||
Projection recommendation:
|
||||
|
||||
- Keep this runtime topology as ingested discovery state for review.
|
||||
- Do not project candidate-only topology into accepted graph snapshots until we
|
||||
have reviewed the server/domain/port inventory in the graph explorer or a
|
||||
focused report.
|
||||
|
||||
## Close Criteria
|
||||
|
||||
- Scanner tests validate server, network port, and domain candidates.
|
||||
- Runtime topology candidates are schema-valid discovery output.
|
||||
- Broad ingest-only rescan reports no scanner errors.
|
||||
- State Hub records the outcome and the next projection recommendation.
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0015
|
||||
type: workplan
|
||||
title: "Runtime Entity Taxonomy Refinement"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 15
|
||||
created: "2026-05-21"
|
||||
updated: "2026-05-21"
|
||||
state_hub_workstream_id: "958559cc-c640-40d6-afe3-467ee0e9e973"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0015 - Runtime Entity Taxonomy Refinement
|
||||
|
||||
## Goal
|
||||
|
||||
Refine runtime topology discovery and graph rendering so servers, services,
|
||||
applications, ports, and domains are distinct entities instead of variants of
|
||||
the old catch-all `Server` node.
|
||||
|
||||
## Background
|
||||
|
||||
The first runtime topology pass intentionally used conservative `Server`,
|
||||
`NetworkPort`, and `DomainName` nodes. After projecting all candidates into the
|
||||
graph, this proved too broad:
|
||||
|
||||
- `127.0.0.1:8765` is a port endpoint, not a server.
|
||||
- `gitea.coulomb.social` is an application-facing endpoint, not a machine.
|
||||
- `pink-account.coulomb.social` should be connected through the privacyIDEA
|
||||
service/application topology instead of floating as a repo-declared server.
|
||||
|
||||
## Target Model
|
||||
|
||||
- `Server` is reserved for concrete machine or host addresses such as IPs and
|
||||
localhost loopback addresses.
|
||||
- `RuntimeService` represents a running service target such as a Kubernetes
|
||||
Service DNS name or a declared service endpoint.
|
||||
- `ApplicationEndpoint` represents user-facing application endpoints exposed
|
||||
through domains, ingress hosts, or declared HTTP URLs.
|
||||
- `NetworkPort` remains the separate port/protocol binding node.
|
||||
- `DomainName` remains the DNS name and routes to the port/service/application
|
||||
it describes.
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Update Runtime Scanner Taxonomy
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0015-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "c19f55e2-dd68-4cb9-8c21-fd9c61a3ab25"
|
||||
```
|
||||
|
||||
Emit refined runtime candidates from Compose, Kubernetes, and Fabric endpoint
|
||||
evidence without using `Server` for domain names or service DNS targets.
|
||||
|
||||
### T02 - Update Graph Explorer Runtime Projection
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0015-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "b5caa75d-04bf-4eb3-9b61-f28eb85fe9d4"
|
||||
```
|
||||
|
||||
Render legacy accepted `Server` candidates as the refined presentation kind
|
||||
where their attributes make the intent clear, and stop inferring `host:port`
|
||||
values as server nodes.
|
||||
|
||||
### T03 - Preserve Port And Service Relationships
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0015-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "06b19102-d5f9-4707-af86-7fb248126374"
|
||||
```
|
||||
|
||||
Keep existing port/domain relationships while adding explicit relationships
|
||||
from runtime services and application endpoints to their ports. Deduplicate
|
||||
inferred deployment `runs_on` edges.
|
||||
|
||||
### T04 - Verify Fixtures And Live Graph Shape
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0015-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "d14e85b4-4323-4ce6-9e25-bc92293dc351"
|
||||
```
|
||||
|
||||
Update scanner and graph explorer tests, then verify the live graph no longer
|
||||
classifies application domains or `host:port` endpoints as servers.
|
||||
|
||||
Verification result:
|
||||
|
||||
- `python3 -m pytest tests/test_graph_explorer.py tests/test_scanner.py -q`
|
||||
passed with 8 tests.
|
||||
- `python3 -m pytest` passed with 35 tests.
|
||||
- Restarted the local registry on port 8765.
|
||||
- Live graph explorer export now shows:
|
||||
- `127.0.0.1:8765` as a `NetworkPort`.
|
||||
- `gitea.coulomb.social` and `pink-account.coulomb.social` as
|
||||
`ApplicationEndpoint` nodes where legacy discovery previously rendered
|
||||
them as `Server`.
|
||||
- `privacyidea.mfa.svc.cluster.local` as a `RuntimeService`.
|
||||
- 0 `Server` nodes whose label contains `host:port`.
|
||||
- 1 `runs_on` edge from `deployment:railiance-fabric.registry:dev`.
|
||||
|
||||
## Close Criteria
|
||||
|
||||
- Scanner tests distinguish `Server`, `RuntimeService`, `ApplicationEndpoint`,
|
||||
`NetworkPort`, and `DomainName`.
|
||||
- Graph explorer tests validate endpoint parsing and duplicate `runs_on`
|
||||
removal.
|
||||
- The local graph export shows application domains as applications, service DNS
|
||||
names as runtime services, and `127.0.0.1:8765` as a port.
|
||||
@@ -0,0 +1,212 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0016
|
||||
type: workplan
|
||||
title: "Canon-Aligned Graph Model Reset And Reingest"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 16
|
||||
created: "2026-05-23"
|
||||
updated: "2026-05-23"
|
||||
depends_on_workplans:
|
||||
- RAIL-FAB-WP-0015
|
||||
state_hub_workstream_id: "4f776f2c-9a54-4658-8e30-eb0d3fc00b32"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0016 - Canon-Aligned Graph Model Reset And Reingest
|
||||
|
||||
## Goal
|
||||
|
||||
Use InfoTechCanon to refactor Railiance Fabric's nodes and edges model, then
|
||||
archive/drop prior registry graph data and reingest all repositories to build a
|
||||
renewed model aligned with canon semantics.
|
||||
|
||||
## Background
|
||||
|
||||
The current Fabric graph grew through iterative discovery and projection work.
|
||||
That helped make the registry practically useful, but the node and edge model
|
||||
now needs a deliberate canon alignment pass before broad adoption. The canon
|
||||
now provides:
|
||||
|
||||
- a reusable consumer alignment review kit,
|
||||
- railiance-fabric conformance support for entity and edge capture,
|
||||
- PURPOSES / INTENT / SCOPE guidance,
|
||||
- graph-oriented canonical entity categories,
|
||||
- CARING and Kubernetes benchmark pressure around roles, scope, evidence, and
|
||||
derived relationships.
|
||||
|
||||
This workplan should use those canon surfaces to make Fabric's graph cleaner,
|
||||
more semantically stable, and easier to visualize without confusing canonical
|
||||
relationships with display-only graph edges.
|
||||
|
||||
## Safety Boundary
|
||||
|
||||
This workplan intentionally includes a destructive reset phase, but the reset
|
||||
MUST NOT be executed casually. Implementation must first produce an export,
|
||||
backup, rollback note, and explicit operator command. Prior registry data may
|
||||
be dropped only after the replacement model, scanner changes, and validation
|
||||
path are ready.
|
||||
|
||||
## Canon Inputs
|
||||
|
||||
- `info-tech-canon` review kit: `review-kit/alignment`
|
||||
- Railiance conformance pack:
|
||||
`infospace/evaluations/railiance-fabric/conformance-pack.yaml`
|
||||
- Entity and edge capture criteria:
|
||||
`infospace/evaluations/railiance-fabric/entity-edge-capture-criteria.yaml`
|
||||
- Mapping expectations:
|
||||
`infospace/evaluations/railiance-fabric/mapping-expectations.yaml`
|
||||
- Visualization examples:
|
||||
`infospace/evaluations/railiance-fabric/visualization-examples.yaml`
|
||||
- PURPOSES / INTENT / SCOPE pattern and model extension
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Canon alignment review and target model
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0016-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "865c048b-fddc-43ee-a379-b61ca31df85b"
|
||||
```
|
||||
|
||||
- Run the canon consumer alignment review workflow against railiance-fabric.
|
||||
- Select relevant canon surfaces for graph capture, governance, purpose,
|
||||
evidence, tasks, landscape, DevSecOps, network, observability, and tagging.
|
||||
- Produce a target node and edge taxonomy with direct, partial, conflicting,
|
||||
and missing mappings.
|
||||
|
||||
### T02 - Refactor nodes, edges, schemas, and validation
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0016-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "26fbc0d5-3b82-45d2-8307-97dffb9de500"
|
||||
```
|
||||
|
||||
- Refactor Fabric graph nodes toward canon-aligned categories such as source
|
||||
repository, software system, service, endpoint, deployment, runtime resource,
|
||||
datastore, flow, policy, control, evidence, task, consumer purpose, and
|
||||
telemetry signal.
|
||||
- Refactor canonical edges toward relationships such as built_from,
|
||||
implements, exposes, depends_on, deploys, flows_to, governed_by,
|
||||
evidenced_by, observed_by, part_of, reads_or_writes, and creates_task.
|
||||
- Keep display-only visualization edges separate from canonical edges.
|
||||
- Update schemas, validators, scanner output, registry projection, docs, and
|
||||
graph explorer mapping as needed.
|
||||
|
||||
### T03 - Export, archive, and controlled reset
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0016-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "f9ce7cd7-48c1-4aa0-9760-b2bcf38feedd"
|
||||
```
|
||||
|
||||
- Export the current registry graph, discovery snapshots, accepted projections,
|
||||
and reingest metadata before any destructive action.
|
||||
- Add a guarded reset path that requires an explicit operator command and
|
||||
records what was dropped.
|
||||
- Document rollback limits and the intended post-reset source of truth.
|
||||
- Drop prior graph data only after backup and validation gates are satisfied.
|
||||
|
||||
### T04 - Full repository reingest
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0016-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "1d3efc3b-029e-4db5-9a83-b658f5ccdebd"
|
||||
```
|
||||
|
||||
- Reingest all registered/local repositories using the new canon-aligned model.
|
||||
- Start with deterministic scanner output and ingest-only mode.
|
||||
- Review changed, conflicted, and review-required repos before acceptance.
|
||||
- Project accepted graph state only after model validation and sample review.
|
||||
|
||||
Progress 2026-05-23:
|
||||
|
||||
- Deterministic no-cache dry run completed for `registry/local-repos.yaml` with
|
||||
35/35 repositories scanned, 0 errors, 0 conflicted candidates, and 0
|
||||
review-required repositories.
|
||||
- Candidate totals from the dry-run report: 381 nodes, 415 edges, and 186
|
||||
attributes.
|
||||
- Fixed a dry-run artifact naming collision for slugs that normalize to the
|
||||
same cache filename, observed with `vergabe-teilnahme` and
|
||||
`vergabe_teilnahme`; the rerun produced 35 unique snapshot paths and 35
|
||||
snapshot files.
|
||||
- Actual reset/ingest/acceptance remains pending the explicit guarded reset
|
||||
command and operator confirmation token.
|
||||
|
||||
Progress 2026-05-23 reset execution:
|
||||
|
||||
- Operator provided confirmation token `RESET-RAILIANCE-FABRIC-GRAPH-DATA`.
|
||||
- Guarded reset event `1` archived current graph data, dropped 54 discovery
|
||||
snapshots and 59 graph snapshots, and preserved 35 repository registrations.
|
||||
- Post-reset deterministic ingest-only run scanned and ingested 35/35
|
||||
repositories with 0 errors, 0 conflicted candidates, and 0 review-required
|
||||
repositories.
|
||||
- Accepted/projected all 35 ingested discovery snapshots into renewed graph
|
||||
snapshots; final registry status after T04 is 35 repositories, 35 discovery
|
||||
snapshots, 35 graph snapshots, and 1 reset event.
|
||||
|
||||
### T05 - Validation, visualization, and State Hub readiness
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0016-T05
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "420336e1-3450-4bbc-8c0f-d091098ee990"
|
||||
```
|
||||
|
||||
- Add regression tests for canonical node categories, edge categories,
|
||||
duplicate identity, destructive reset guardrails, and reingest idempotency.
|
||||
- Verify graph explorer displays the renewed model clearly.
|
||||
- Produce before/after counts and representative examples.
|
||||
- Confirm State Hub can ingest the renewed graph as a read model.
|
||||
|
||||
Progress 2026-05-23:
|
||||
|
||||
- Full regression suite passed after reset/reingest: 42 tests.
|
||||
- Renewed registry status: 35 repositories, 35 discovery snapshots, 35 graph
|
||||
snapshots, and 1 reset event.
|
||||
- State Hub export validates against `schemas/state-hub-export.schema.yaml`
|
||||
and currently contains 49 nodes and 58 edges. Representative canonical edge
|
||||
relationships include `exposes` (31), `depends_on` (15), and `implements`
|
||||
(12).
|
||||
- Graph explorer manifest and payload validate against their schemas. The UI
|
||||
shell is reachable as `Fabric Map`; graph explorer payload metrics report 95
|
||||
nodes, 129 edges, 35 repository nodes, 11 deployment nodes, and 5 unresolved
|
||||
items.
|
||||
- Blocked on actual State Hub read-model ingestion: no State Hub graph ingest
|
||||
endpoint or job was found in `~/state-hub`; `docs/state-hub-integration.md`
|
||||
still describes this as a required State Hub ingestion endpoint/job.
|
||||
|
||||
Progress 2026-05-23 unblock:
|
||||
|
||||
- `STATE-WP-0050` added and completed the missing State Hub Fabric graph
|
||||
read-model ingestion path.
|
||||
- Verified the live State Hub service can pull the current Fabric export from
|
||||
`http://127.0.0.1:8765/exports/state-hub`.
|
||||
- Pull result was idempotent against import
|
||||
`130ffb56-7e30-4963-a3b1-b7527f685b45`, storing 49 nodes and 58 edges.
|
||||
- Confirmed State Hub graph summary/query counts match the renewed Fabric
|
||||
export: canonical relationships `exposes` 31, `depends_on` 15, and
|
||||
`implements` 12.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- The target Fabric node and edge model is explicitly mapped to InfoTechCanon.
|
||||
- Display-only graph relationships are separated from canonical relationships.
|
||||
- Prior graph data is exported or archived before any destructive reset.
|
||||
- The reset path is explicit, guarded, documented, and test-covered.
|
||||
- All registered/local repos are reingested into a renewed canon-aligned graph.
|
||||
- Validation and graph explorer review show cleaner entity and edge capture.
|
||||
- Any canon gaps or pressure discovered during the work are recorded as canon
|
||||
feedback, not silently folded into Fabric-specific semantics.
|
||||
@@ -0,0 +1,337 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0017
|
||||
type: workplan
|
||||
title: "Financial Fabric Model Reset"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-05-23"
|
||||
updated: "2026-05-24"
|
||||
state_hub_workstream_id: "39cc363c-6e2a-46a2-bd19-cee7ff6fc149"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0017 - Financial Fabric Model Reset
|
||||
|
||||
## Goal
|
||||
|
||||
Adapt `railiance-fabric` to the revised Fabric intent captured in
|
||||
`docs/FabricDiscoveryAndUpdate.md`.
|
||||
|
||||
Fabric should model durable infrastructure-responsibility boundaries rather
|
||||
than repo-owned external relation declarations. The core model must understand
|
||||
the Railiance netkingdom, king/lord/tenant financial actors, fabric and
|
||||
subfabric containment, resolvable node ownership, cross-boundary utility
|
||||
interfaces, and optional cost/profit center attribution.
|
||||
|
||||
## Background
|
||||
|
||||
The current Fabric implementation grew from repo-owned declarations and a
|
||||
canon-aligned graph export. That was useful for bootstrapping, but it now
|
||||
misplaces authority for external relations: a repository cannot sustainably own
|
||||
all deployment contexts, tenant relations, or cross-boundary utility edges in
|
||||
which it participates.
|
||||
|
||||
The updated architecture establishes these principles:
|
||||
|
||||
- a fabric is bounded by financial and operational accountability;
|
||||
- the king is responsible for the whole netkingdom and holds the relevant
|
||||
recovery/secrets/backups authority;
|
||||
- a lord pays for a fabric;
|
||||
- a tenant pays for restricted use of a subfabric;
|
||||
- every node needs resolvable ownership;
|
||||
- cross-boundary utility edges are first-class value interfaces;
|
||||
- cost/profit centers are accounting attributions and view dimensions, not
|
||||
fabric boundaries;
|
||||
- Fabric should avoid security-zone terms such as realm or domain for its core
|
||||
concepts.
|
||||
|
||||
This workplan resets the Fabric contract and internal model so later discovery
|
||||
work can rebuild the graph from accountability roots and deployment automation.
|
||||
|
||||
## T01 - Audit Current Model Assumptions
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0017-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "3d259e3c-5534-4b6a-930a-d085d3db57e4"
|
||||
```
|
||||
|
||||
Inventory the current assumptions that must change.
|
||||
|
||||
Scope:
|
||||
|
||||
- schema files and declaration shapes under `schemas/` and `fabric/`;
|
||||
- Python model classes and validators;
|
||||
- registry storage tables and snapshot materialization;
|
||||
- State Hub export payload shape;
|
||||
- tests and fixtures that assume repo-owned declarations are the primary graph
|
||||
source;
|
||||
- documentation that still describes Fabric as repo-owned external relation
|
||||
declarations.
|
||||
|
||||
Done when:
|
||||
|
||||
- affected files and APIs are listed;
|
||||
- compatibility risks are documented;
|
||||
- the migration approach for existing accepted graph data is explicit;
|
||||
- follow-on tasks have enough detail to implement without rediscovering the
|
||||
whole codebase.
|
||||
|
||||
Result:
|
||||
|
||||
- Added `docs/financial-fabric-model-audit.md`.
|
||||
- Listed affected schemas, Python modules, registry/API surfaces, docs,
|
||||
fixtures, tests, and projections.
|
||||
- Documented compatibility risks for State Hub ingest, Graph Explorer,
|
||||
provider/consumer query commands, registry storage, test fixtures, canon
|
||||
mapping, and the existing accepted graph baseline.
|
||||
- Defined a migration approach that preserves `v1alpha1` declarations as
|
||||
legacy evidence, adds a versioned vNext contract, reuses the existing
|
||||
discovery/reconciliation mechanics, seeds the current one-fabric Railiance
|
||||
baseline, and coordinates State Hub changes through `STATE-WP-0051`.
|
||||
|
||||
## T02 - Define The VNext Fabric Semantic Contract
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0017-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "8bbab878-0bff-4302-a925-15a8aceabf9b"
|
||||
```
|
||||
|
||||
Define the next graph contract for Fabric snapshots and exports.
|
||||
|
||||
Required concepts:
|
||||
|
||||
- netkingdom root;
|
||||
- actor nodes for king, lord, tenant, and supporting operators/stewards;
|
||||
- fabric and subfabric containment;
|
||||
- node ownership and inherited ownership resolution;
|
||||
- cross-boundary utility interfaces;
|
||||
- optional cost center and profit center attribution on nodes and edges;
|
||||
- evidence and provenance fields for every discovered or accepted fact;
|
||||
- schema versioning and compatibility metadata.
|
||||
|
||||
Done when:
|
||||
|
||||
- schemas or contract documents describe the vNext shape;
|
||||
- existing canonical node/edge concepts are mapped to the new model or marked
|
||||
for retirement;
|
||||
- unresolved ownership and ambiguous containment have explicit representation;
|
||||
- examples cover the current single Railiance fabric, a tenant subfabric, and a
|
||||
cross-boundary utility edge.
|
||||
|
||||
Result:
|
||||
|
||||
- Added `docs/financial-fabric-vnext-contract.md`.
|
||||
- Defined a proposed `railiance.fabric/v1alpha2` / `financial-fabric-v1`
|
||||
export shape with top-level netkingdom, actor, fabric, node, edge, and
|
||||
unresolved sections.
|
||||
- Defined actor roles, fabric/subfabric containment, ownership resolution,
|
||||
cross-boundary utility edges, accounting attribution, and evidence/provenance
|
||||
shape.
|
||||
- Mapped legacy declaration kinds and existing edge types to vNext disposition.
|
||||
- Included examples for the current single Railiance fabric, a future tenant
|
||||
subfabric, and a cross-subfabric utility edge.
|
||||
- Listed State Hub import requirements for `STATE-WP-0051`.
|
||||
|
||||
## T03 - Refactor Core Validation And Registry Materialization
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0017-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "7ff1c162-f778-4ab4-9e09-a512a54b2f68"
|
||||
```
|
||||
|
||||
Update validation and registry materialization around the new contract.
|
||||
|
||||
Requirements:
|
||||
|
||||
- enforce resolvable ownership for graph nodes;
|
||||
- distinguish containment, ownership, accounting attribution, and diagnostic
|
||||
views;
|
||||
- support fabric and subfabric membership without treating environments as
|
||||
fabrics;
|
||||
- represent cross-boundary utility edges as first-class accepted graph edges;
|
||||
- retain evidence/provenance and confidence/review state;
|
||||
- keep old graph data readable long enough for migration or controlled reset.
|
||||
|
||||
Done when:
|
||||
|
||||
- model classes, validators, registry materialization, and tests support the
|
||||
new contract;
|
||||
- invalid missing-owner cases fail or are flagged according to the contract;
|
||||
- existing snapshot/export code can emit the vNext model.
|
||||
|
||||
Result:
|
||||
|
||||
- Added `railiance_fabric/financial.py` with `v1alpha2` financial Fabric
|
||||
graph materialization, validation, and merge helpers.
|
||||
- Registry snapshot ingestion now materializes financial graphs before
|
||||
validation while preserving the legacy `v1alpha1` schema path.
|
||||
- Registry combined graph output can preserve and merge `v1alpha2` actors,
|
||||
fabrics, nodes, edges, unresolved gaps, ownership, containment, accounting,
|
||||
and utility metadata when all latest snapshots use the financial contract.
|
||||
- Added canon mappings for vNext kinds and edge types such as `FabricActor`,
|
||||
`Fabric`, `Subfabric`, `UtilityInterface`, `CostCenter`, `ProfitCenter`,
|
||||
`contains`, `owned_by`, `operated_by`, `provides_utility_to`, and accounting
|
||||
attribution edges.
|
||||
- Added registry tests covering missing accepted-node ownership rejection,
|
||||
financial graph snapshot ingestion, utility edge materialization, and
|
||||
combined `v1alpha2` graph output.
|
||||
- Verified with `python3 -m pytest tests/test_registry.py -q` and full
|
||||
`python3 -m pytest`.
|
||||
|
||||
## T04 - Update The State Hub Export Contract
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0017-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "d10f120d-746d-468d-b208-d946b54c2707"
|
||||
```
|
||||
|
||||
Revise the State Hub export payload so State Hub can import the improved Fabric
|
||||
model as a read model.
|
||||
|
||||
Requirements:
|
||||
|
||||
- include fabric/subfabric identity and containment;
|
||||
- include owner actor identity and owner role;
|
||||
- include accounting attribution fields when present;
|
||||
- include cross-boundary utility metadata;
|
||||
- include schema/export version metadata;
|
||||
- preserve enough current canonical fields for compatibility where practical;
|
||||
- document required State Hub changes for `STATE-WP-0051`.
|
||||
|
||||
Done when:
|
||||
|
||||
- export schema and sample payloads are updated;
|
||||
- current State Hub import limitations are documented;
|
||||
- compatibility tests cover both old baseline import behavior and the new
|
||||
vNext export behavior, or intentionally document a controlled breaking reset.
|
||||
|
||||
Result:
|
||||
|
||||
- Updated `schemas/state-hub-export.schema.yaml` to accept both the legacy
|
||||
`railiance.fabric/v1alpha1` declaration-centered export and the
|
||||
`railiance.fabric/v1alpha2` / `financial-fabric-v1` export.
|
||||
- Added schema fields for netkingdom, actors, fabrics, node containment,
|
||||
node ownership, accounting attribution, evidence, utility edge
|
||||
provider/consumer context, boundary crossing flags, and unresolved gaps.
|
||||
- Added `examples/exports/financial-fabric-v1.json` as a materialized sample
|
||||
payload.
|
||||
- Updated `docs/state-hub-integration.md` to describe the v1alpha1/v1alpha2
|
||||
contract split, State Hub import expectations, and the current limitation
|
||||
that `STATE-WP-0050` only materializes v1alpha1 until `STATE-WP-0051`.
|
||||
- Added schema compatibility coverage for both old and financial graph export
|
||||
shapes.
|
||||
- Verified with `python3 -m pytest tests/test_registry.py -q` and full
|
||||
`python3 -m pytest`.
|
||||
|
||||
## T05 - Seed The Current Railiance Netkingdom Baseline
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0017-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "b8430050-94a8-43f6-9b3c-7928c5c6bb69"
|
||||
```
|
||||
|
||||
Create the initial accepted model for the current Railiance responsibility
|
||||
boundary.
|
||||
|
||||
Requirements:
|
||||
|
||||
- one root Railiance netkingdom;
|
||||
- current king actor;
|
||||
- current lord/fabric boundary reflecting that one actor pays for the current
|
||||
infrastructure;
|
||||
- initial default ownership rules for discovered nodes;
|
||||
- placeholders for future tenant/subfabric modeling;
|
||||
- no security-zone terminology in the core model.
|
||||
|
||||
Done when:
|
||||
|
||||
- the current graph can resolve ownership for all accepted nodes;
|
||||
- the baseline explains why there is currently one effective fabric;
|
||||
- future tenant subfabrics can be added without changing the root fabric
|
||||
definition.
|
||||
|
||||
Result:
|
||||
|
||||
- Added `fabric/financial/railiance-netkingdom.yaml` as the current Railiance
|
||||
netkingdom baseline with king, lord, one active fabric, inherited default
|
||||
containment/ownership/accounting, and a future subfabric template.
|
||||
- Added `railiance_fabric/financial_baseline.py` to load the baseline and
|
||||
project legacy `v1alpha1` exports into `v1alpha2` financial Fabric exports.
|
||||
- Added `railiance-fabric export --format financial` so the current graph can
|
||||
emit a financial baseline projection.
|
||||
- Added tests proving the current graph projects to the Railiance baseline,
|
||||
validates as a financial graph, has no unresolved gaps, and gives every node
|
||||
inherited ownership in `fabric.railiance.primary`.
|
||||
- Verified with `python3 -m pytest tests/test_registry.py -q` and full
|
||||
`python3 -m pytest`.
|
||||
|
||||
## T06 - Update Documentation, Fixtures, And Operator Guidance
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0017-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "93a8a79e-877f-48c1-888e-0fb50c8de75b"
|
||||
```
|
||||
|
||||
Bring docs and fixtures in line with the reset model.
|
||||
|
||||
Requirements:
|
||||
|
||||
- update README and affected architecture/registry/export docs;
|
||||
- document the migration from repo-owned declarations to accountability-root
|
||||
discovery;
|
||||
- update sample graph exports and validation fixtures;
|
||||
- document the handoff to State Hub and to the discovery/update-loop workplan;
|
||||
- keep `docs/FabricDiscoveryAndUpdate.md` as the architecture anchor.
|
||||
|
||||
Done when:
|
||||
|
||||
- docs no longer present repo-owned external declarations as the default source
|
||||
of truth;
|
||||
- tests and examples exercise king/lord/tenant, ownership, fabric/subfabric,
|
||||
cost/profit attribution, and cross-boundary utility edges;
|
||||
- operator guidance explains how to refresh State Hub after a reset export.
|
||||
|
||||
Result:
|
||||
|
||||
- Added `docs/financial-fabric-operator-guide.md` with the baseline refresh
|
||||
loop, guarded reset rebuild sequence, State Hub handoff, and discovery-loop
|
||||
follow-up.
|
||||
- Updated README, query/export docs, State Hub integration docs, registry API,
|
||||
onboarding, and reset operations to document
|
||||
`railiance-fabric export --format financial` and the v1alpha1/v1alpha2
|
||||
transition.
|
||||
- Updated declaration, rollout, scanner, canon, fabric, and example docs so
|
||||
repo-local declarations are presented as evidence/bootstrap data rather than
|
||||
the default authority for external fabric relations.
|
||||
- Kept `docs/FabricDiscoveryAndUpdate.md` as the architecture anchor and linked
|
||||
operator-facing docs back to it.
|
||||
- Verified with `git diff --check`,
|
||||
`python3 -m pytest tests/test_registry.py -q`, and full
|
||||
`python3 -m pytest`.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Fabric has a documented vNext contract aligned with
|
||||
`docs/FabricDiscoveryAndUpdate.md`.
|
||||
- Every accepted graph node has resolvable ownership.
|
||||
- Fabric and subfabric membership is distinct from environments, deployment
|
||||
scenarios, and views.
|
||||
- Cross-boundary utility interfaces are first-class graph edges.
|
||||
- Cost/profit centers are optional accounting attributions and view dimensions.
|
||||
- The State Hub export schema is updated or a controlled reset path is
|
||||
documented.
|
||||
- Existing tests are updated or replaced with coverage for the new model.
|
||||
@@ -0,0 +1,340 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0018
|
||||
type: workplan
|
||||
title: "Accountability Root Discovery And Update Loop"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-05-23"
|
||||
updated: "2026-05-24"
|
||||
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: 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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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.
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0019
|
||||
type: workplan
|
||||
title: "Duplicate Repository Identity Review"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-05-24"
|
||||
updated: "2026-05-24"
|
||||
state_hub_workstream_id: "bc69549c-3cbc-4a7d-8766-b84added1133"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0019 - Duplicate Repository Identity Review
|
||||
|
||||
## Goal
|
||||
|
||||
Resolve the duplicate repository identity blockers found during the
|
||||
`RAIL-FAB-WP-0018` bootstrap run.
|
||||
|
||||
The 2026-05-24 accountability-root ownership review resolved ownership and
|
||||
containment for all candidates, but flagged four repository identities as
|
||||
ambiguous because registry inventory evidence maps two repo slugs onto the same
|
||||
local checkout path.
|
||||
|
||||
## T01 - Inspect Duplicate Repo Path Evidence
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0019-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "63c5ee1e-6c9f-4d63-b0b4-61308e833ac2"
|
||||
```
|
||||
|
||||
Review the duplicate path evidence for:
|
||||
|
||||
- `identity:repository:railiance-hosts`
|
||||
- `identity:repository:railiance-infra`
|
||||
- `identity:repository:vergabe-teilnahme`
|
||||
- `identity:repository:vergabe_teilnahme`
|
||||
|
||||
Done when the intended canonical repo identity, alias, or split-identity rule is
|
||||
known for `/home/worsch/railiance-infra` and `/home/worsch/vergabe-teilnahme`.
|
||||
|
||||
Result: `/home/worsch/railiance-infra` is canonicalized as
|
||||
`railiance-infra`; `railiance-hosts` remains an alias while its State Hub record
|
||||
still carries older goal context. `/home/worsch/vergabe-teilnahme` is
|
||||
canonicalized as `vergabe-teilnahme`; `vergabe_teilnahme` is an alias/stale
|
||||
registration.
|
||||
|
||||
## T02 - Encode Canonical Identity Decisions
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0019-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "bd0496f2-9a95-4487-9620-eabbf0e78c6b"
|
||||
```
|
||||
|
||||
Apply the chosen resolution in the durable source of truth.
|
||||
|
||||
Candidate options include:
|
||||
|
||||
- fix duplicate entries in `registry/local-repos.yaml`;
|
||||
- add explicit repository alias/canonicalization support to the identity
|
||||
projection;
|
||||
- persist review decisions for the affected stable identity keys.
|
||||
|
||||
Done when duplicate repo path evidence no longer produces ambiguous repository
|
||||
identity blockers.
|
||||
|
||||
Result: accountability-root discovery now supports `canonical_slug` and
|
||||
automatic duplicate-path canonicalization for registered repositories. Current
|
||||
aliases are annotated in `registry/local-repos.yaml`, and the live ownership
|
||||
review reports no `ambiguous_identity` blockers.
|
||||
|
||||
## T03 - Refresh Bootstrap Review Artifacts
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0019-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "2c90c5c1-46be-41b7-8854-602eea0e3aaf"
|
||||
```
|
||||
|
||||
Rerun the accountability-root bootstrap review and update the saved discovery
|
||||
snapshot artifacts.
|
||||
|
||||
Done when `fabric/discovery/snapshots/*bootstrap-ownership-review.json` shows
|
||||
zero ambiguous repository identity blockers, or documents any remaining blocker
|
||||
as intentionally unresolved.
|
||||
|
||||
Result: bootstrap identity, ownership-review, and update-delta snapshots were
|
||||
refreshed on 2026-05-24. The saved ownership review reports `needs_review: 0`
|
||||
and no blockers.
|
||||
@@ -0,0 +1,208 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0020
|
||||
type: workplan
|
||||
title: "Deployment Zone Discovery And Visualization"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-05-24"
|
||||
updated: "2026-05-24"
|
||||
state_hub_workstream_id: "e70820a9-d6f3-473d-a17c-b15fe3180773"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0020 - Deployment Zone Discovery And Visualization
|
||||
|
||||
## Goal
|
||||
|
||||
Improve Fabric discovery and visualization so operators can see which services
|
||||
run in dev, test, and production deployment overlays without making Fabric the
|
||||
authority for ports, routes, or access policy.
|
||||
|
||||
This work follows the terminology in `docs/FabricDiscoveryAndUpdate.md`:
|
||||
|
||||
- fabric/subfabric remain financial responsibility boundaries;
|
||||
- deployment environment classifies lifecycle target: `dev`, `test`, `prod`;
|
||||
- deployment scenario names the concrete place where services run:
|
||||
`bernd-laptop`, `coulombcore`, `railiance01`;
|
||||
- routing authority maps names or ports to backend services;
|
||||
- access zone groups intended reachability for visualization;
|
||||
- policy authority is the external system expected to enforce access rules.
|
||||
|
||||
## Background
|
||||
|
||||
The current local collision between the Fabric graph explorer port and the
|
||||
NetKingdom control surface showed that Fabric should detect routing reality,
|
||||
not organize it. The NetKingdom control surface now uses local port `8876`;
|
||||
the Fabric registry and graph explorer use `8765`.
|
||||
|
||||
Railiance currently treats:
|
||||
|
||||
- the operator laptop as private `dev`;
|
||||
- `coulombcore` as shared `test` for collaborators and friendly early-access
|
||||
users;
|
||||
- `railiance01` as `prod`, currently alpha-accessible to developers but moving
|
||||
toward restricted production access.
|
||||
|
||||
## T01 - Extend Discovery Overlay Model
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0020-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "b8cf7d91-7743-4e58-9b13-ce99f2d9eef1"
|
||||
```
|
||||
|
||||
Define schema/export fields for deployment overlays.
|
||||
|
||||
Fields should cover:
|
||||
|
||||
- `deployment_environment`;
|
||||
- `deployment_scenario`;
|
||||
- `routing_authority`;
|
||||
- `access_zone`;
|
||||
- `policy_authority`;
|
||||
- exposure class, such as local-only, collaborator-test, early-access,
|
||||
production-public, or production-admin;
|
||||
- host, port, hostname, protocol, and route evidence where applicable.
|
||||
|
||||
Done when identity projection, financial export, and graph-explorer payloads
|
||||
have a clear place to carry these fields without changing fabric membership.
|
||||
|
||||
Result: added a normalized `deployment_overlay` object and threaded it through
|
||||
identity candidates, financial exports, State Hub export schema validation, and
|
||||
graph-explorer payload fields/modes.
|
||||
|
||||
## T02 - Discover Local Dev Routing Evidence
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0020-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "b072e11b-08b5-426f-9f98-001abf8afd70"
|
||||
```
|
||||
|
||||
Discover private developer-local routing evidence for `bernd-laptop`.
|
||||
|
||||
Initial sources:
|
||||
|
||||
- Makefile or script defaults;
|
||||
- local process launcher command lines where durable enough;
|
||||
- loopback URLs in docs and manifests;
|
||||
- Docker Compose published ports;
|
||||
- current known local surfaces such as Fabric registry `8765`, NetKingdom
|
||||
control surface `8876`, State Hub API `8000`, State Hub MCP `8001`, and State
|
||||
Hub dashboard `3000`.
|
||||
|
||||
Done when local-only surfaces are marked as `deployment_environment: dev`,
|
||||
`deployment_scenario: bernd-laptop`, and `access_zone: private-dev` with
|
||||
provenance.
|
||||
|
||||
Result: known local surfaces are declared or discovered with `dev`,
|
||||
`bernd-laptop`, `private-dev`, local-loopback policy authority, and route
|
||||
evidence: Fabric registry/explorer `8765`, NetKingdom control surface `8876`,
|
||||
State Hub API `8000`, State Hub MCP `8001`, and State Hub dashboard `3000`.
|
||||
|
||||
## T03 - Discover Test And Production Routing Authorities
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0020-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "91fc3f28-fbb9-43d2-bb46-44d179f4b485"
|
||||
```
|
||||
|
||||
Discover routing authority evidence for `coulombcore` and `railiance01`.
|
||||
|
||||
Initial sources:
|
||||
|
||||
- Kubernetes `Service` and `Ingress` manifests;
|
||||
- Traefik, nginx, Caddy, HAProxy, or equivalent proxy configuration;
|
||||
- DNS and TLS/cert-manager evidence when present;
|
||||
- Railiance infra and NetKingdom deployment documentation until executable
|
||||
manifests are complete.
|
||||
|
||||
Done when test-stage routes can be attributed to `coulombcore` and production
|
||||
routes can be attributed to `railiance01`, with access zones flagged as
|
||||
candidate values for operator review.
|
||||
|
||||
Result: published `fabric/discovery/snapshots/2026-05-24-deployment-zone-inventory.yaml`
|
||||
with `coulombcore` test tunnel evidence, `railiance01` Traefik ingress evidence,
|
||||
candidate access zones, and explicit ambiguity flags for host/IP conflicts and
|
||||
operator review.
|
||||
|
||||
## T04 - Add Zone Overlay Graph Explorer Modes
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0020-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "664c2688-f45b-47bf-90ff-b17096a326fb"
|
||||
```
|
||||
|
||||
Add graph explorer support for overlay views:
|
||||
|
||||
- by fabric/accountability;
|
||||
- by deployment environment;
|
||||
- by deployment scenario;
|
||||
- by routing authority;
|
||||
- by access zone.
|
||||
|
||||
The UI should make it easy to answer:
|
||||
|
||||
- what is running in private dev, shared test, and production;
|
||||
- what is production-facing on `railiance01`;
|
||||
- what is early-access reachable on `coulombcore`;
|
||||
- which control surfaces appear in user-facing zones;
|
||||
- which routes have no discovered policy authority.
|
||||
|
||||
Done when the graph explorer can group/filter by overlay fields and surface the
|
||||
basic warnings without making policy decisions.
|
||||
|
||||
Result: graph-explorer manifests and payloads expose deployment overlay fields;
|
||||
the UI includes zone modes, overlay search/rule filtering, visible zone summaries,
|
||||
and route-without-policy-authority warnings.
|
||||
|
||||
## T05 - Preserve State Hub Read-Model Compatibility
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0020-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "1a5ef6f9-357f-4803-a1f8-ebd1ff5443fb"
|
||||
```
|
||||
|
||||
Ensure State Hub can ingest and query the new overlay fields.
|
||||
|
||||
Done when Fabric exports remain backward compatible, State Hub keeps importing
|
||||
valid v1alpha2 exports, and overlay fields are visible enough for dashboard or
|
||||
search views.
|
||||
|
||||
Result: `schemas/state-hub-export.schema.yaml` accepts optional
|
||||
`deployment_overlay` objects on financial nodes and edges while preserving the
|
||||
legacy export shape. Focused compatibility tests pass.
|
||||
|
||||
## T06 - Publish Current Zone Inventory
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0020-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "a1b208e3-3321-4792-ba44-d32aba682183"
|
||||
```
|
||||
|
||||
Run the improved discovery against the current Railiance workspace and publish a
|
||||
reviewable zone inventory.
|
||||
|
||||
Done when there is a saved artifact answering:
|
||||
|
||||
- which local dev services are visible on `bernd-laptop`;
|
||||
- which test-stage services are visible on `coulombcore`;
|
||||
- which production services are visible on `railiance01`;
|
||||
- which routes or ports are ambiguous, conflicting, or missing a policy
|
||||
authority.
|
||||
|
||||
Result: saved the current inventory at
|
||||
`fabric/discovery/snapshots/2026-05-24-deployment-zone-inventory.yaml` and added
|
||||
focused test coverage to keep the dev/test/prod scenario answers present.
|
||||
@@ -0,0 +1,195 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0021
|
||||
type: workplan
|
||||
title: "Zone Boundary Overlays"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-05-24"
|
||||
updated: "2026-05-24"
|
||||
state_hub_workstream_id: "e9e2d47f-a965-4e2e-b65d-379dbb206a65"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0021 - Zone Boundary Overlays
|
||||
|
||||
## Goal
|
||||
|
||||
Make deployment zones visible as labeled rectangular boundaries in the Fabric
|
||||
graph explorer, so an operator can immediately see which nodes belong to local
|
||||
dev, shared test, and production contexts.
|
||||
|
||||
This work builds on `RAIL-FAB-WP-0020` deployment overlay fields. Zone
|
||||
boundaries are visual annotations over graph elements. They must not create new
|
||||
fabric membership, ownership, security policy, or routing authority.
|
||||
|
||||
Initial display labels:
|
||||
|
||||
- `dev-tegwick` for the private developer-local overlay;
|
||||
- `test` for shared test-stage services;
|
||||
- `prod` for production services.
|
||||
|
||||
The implementation should keep the underlying graph explorable and avoid
|
||||
turning zones into hard layout containers unless that proves necessary.
|
||||
|
||||
## Background
|
||||
|
||||
WP-20 added deployment overlay fields and graph explorer modes for:
|
||||
|
||||
- deployment environment;
|
||||
- deployment scenario;
|
||||
- routing authority;
|
||||
- access zone;
|
||||
- policy authority;
|
||||
- route evidence.
|
||||
|
||||
The current UI can filter and summarize zone-oriented data, but the operator
|
||||
still needs to infer the spatial grouping from node labels and details. The next
|
||||
step is to draw zone boundaries around the visible nodes that share a deployment
|
||||
zone, with a readable label on the boundary.
|
||||
|
||||
The likely implementation path is a graph-canvas overlay layer that computes
|
||||
bounding rectangles from rendered node positions after layout, pan, zoom, filter,
|
||||
or mode changes. This is preferred over changing graph topology to compound
|
||||
parent nodes unless testing shows the overlay layer is too fragile.
|
||||
|
||||
## T01 - Define Zone Grouping And Labels
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0021-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "91777c22-663c-443a-b682-38bfb7a864bf"
|
||||
```
|
||||
|
||||
Define how graph explorer elements map to zone overlay groups.
|
||||
|
||||
Expected grouping rules:
|
||||
|
||||
- primary grouping field is `deploymentEnvironment`;
|
||||
- `dev` nodes in the private local scenario render as `dev-tegwick`;
|
||||
- `test` nodes render as `test`;
|
||||
- `prod` nodes render as `prod`;
|
||||
- nodes without deployment overlay data are not enclosed by a zone boundary;
|
||||
- edge-only overlay evidence should affect zone warnings/details but should not
|
||||
create a rectangle unless at least one visible node belongs to the zone.
|
||||
|
||||
Done when the grouping and label rules are documented in the graph explorer
|
||||
contract or operations docs and have focused tests.
|
||||
|
||||
Result: documented environment/access-zone boundary rules in
|
||||
`docs/graph-explorer-contract.md`; graph explorer maps `dev` to `dev-tegwick`,
|
||||
legacy `staging` to `test`, `prod` to `prod`, and ignores catch-all `all`
|
||||
environment values for rectangle boundaries.
|
||||
|
||||
## T02 - Render Rectangle Boundary Overlays
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0021-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "98ef5ecc-fa4d-443c-a4fe-fa896984d6c4"
|
||||
```
|
||||
|
||||
Draw labeled rectangular boundaries around the currently visible nodes in each
|
||||
zone group.
|
||||
|
||||
Implementation expectations:
|
||||
|
||||
- compute rectangles from rendered node bounding boxes;
|
||||
- add padding so borders do not collide with node labels;
|
||||
- draw borders above the canvas background but below interaction-critical UI;
|
||||
- keep zone labels readable at normal zoom levels;
|
||||
- update rectangles after layout, pan, zoom, resize, filter, mode, focus,
|
||||
manual override, and rule changes;
|
||||
- hide a zone boundary when no visible nodes remain in that zone.
|
||||
|
||||
Done when the UI shows stable labeled rectangles for `dev-tegwick`, `test`, and
|
||||
`prod` where matching nodes are visible.
|
||||
|
||||
Result: added a canvas overlay layer that computes padded rendered-node bounds,
|
||||
draws labeled rectangles, updates after layout/pan/zoom/filter changes, and
|
||||
hides empty zones.
|
||||
|
||||
## T03 - Add Zone Overlay Controls
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0021-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "30d48d5c-bd53-434b-9b8b-ed1a495cee4e"
|
||||
```
|
||||
|
||||
Add lightweight controls for zone boundaries without cluttering the graph
|
||||
explorer toolbar.
|
||||
|
||||
Expected controls:
|
||||
|
||||
- toggle zone boundaries on or off;
|
||||
- choose whether boundaries group by deployment environment or access zone if
|
||||
both are useful;
|
||||
- preserve the setting in copied URL state and browser-local profiles.
|
||||
|
||||
Done when operators can turn the overlay off for dense graph inspection and
|
||||
restore it through shared/saved view state.
|
||||
|
||||
Result: added map controls for zone visibility and grouping by deployment
|
||||
environment or access zone, with URL/profile state preservation.
|
||||
|
||||
## T04 - Surface Zone Boundary Details
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0021-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "c002aa54-a243-4912-81ae-0d282910ebc6"
|
||||
```
|
||||
|
||||
Make a zone boundary useful when inspected.
|
||||
|
||||
Expected behavior:
|
||||
|
||||
- clicking or selecting a zone label should show zone summary details;
|
||||
- details should include visible node count, deployment environment, scenarios,
|
||||
access zones, routing authorities, and route-without-policy-authority warnings;
|
||||
- zone selection should not replace node/edge selection semantics permanently;
|
||||
- a zone-focused view should be possible via existing focus/rule mechanisms if
|
||||
it can be done simply.
|
||||
|
||||
Done when a zone label provides the same core answers as the WP-20 map overview,
|
||||
but scoped to that zone.
|
||||
|
||||
Result: zone labels are clickable and show scoped counts for visible nodes,
|
||||
environments, scenarios, access zones, routing authorities, policy authorities,
|
||||
and route-without-policy-authority warnings; existing focus/highlight/hide
|
||||
orientation actions work for zone contexts.
|
||||
|
||||
## T05 - Verify Responsive And Dense Graph Behavior
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0021-T05
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "03f265ad-f335-4caf-a882-35d8d30c75fc"
|
||||
```
|
||||
|
||||
Verify that zone rectangles remain useful across normal operator viewports and
|
||||
dense graphs.
|
||||
|
||||
Checks should cover:
|
||||
|
||||
- desktop and narrower browser widths;
|
||||
- full graph mode and deployment zone modes;
|
||||
- filtered views where a zone has only one or two nodes;
|
||||
- hidden/removed nodes from rule and manual override controls;
|
||||
- graph pan/zoom/layout changes;
|
||||
- no incoherent overlap between labels, controls, and detail panels.
|
||||
|
||||
Done when automated tests cover the computed grouping behavior and a browser
|
||||
smoke check confirms the canvas overlay is visible and aligned.
|
||||
|
||||
Result: static UI tests cover the zone controls/helpers; JavaScript syntax was
|
||||
checked with `node --check`; the full test suite and validator pass; a headless
|
||||
Edge smoke screenshot confirmed visible labeled boundaries in deployment
|
||||
environment mode.
|
||||
@@ -0,0 +1,250 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0022
|
||||
type: workplan
|
||||
title: "Promote graph zones to first-class visualization entities"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-05-24"
|
||||
updated: "2026-05-24"
|
||||
state_hub_workstream_id: "343f8383-ba5e-4d60-b55e-81611954d9b9"
|
||||
---
|
||||
|
||||
# Promote Graph Zones To First-Class Visualization Entities
|
||||
|
||||
## Context
|
||||
|
||||
RAIL-FAB-WP-0021 introduced labeled zone boundary overlays in the graph
|
||||
explorer. That gave the operator a useful visual grouping by deployment
|
||||
environment and access zone, but the zones are still derived directly inside the
|
||||
UI as overlay rectangles around already-rendered nodes.
|
||||
|
||||
The next direction is described in `docs/ZoneEntityVisualization.md`: zones
|
||||
should become first-class visualization entities beside nodes and edges. A zone
|
||||
is a drawing surface for part of the graph, with declarative membership rules,
|
||||
optional attraction rules, rendering height, diagnostics, and eventually
|
||||
collapse/drill-down behavior.
|
||||
|
||||
This workplan moves toward that model without forcing a large rewrite in one
|
||||
step.
|
||||
|
||||
## Task 1: Define The Zone View Model
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0022-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "636b14f7-e5c7-4d5d-acda-40f0c270cd29"
|
||||
```
|
||||
|
||||
Define an internal zone view model that can represent:
|
||||
|
||||
- zone definitions
|
||||
- resolved zone instances
|
||||
- node assignments
|
||||
- edge summaries
|
||||
- cross-zone boundary edges
|
||||
- membership and attraction diagnostics
|
||||
- presentation metadata such as label, color, and height
|
||||
|
||||
The model should be serializable enough to support saved graph profiles later,
|
||||
but it does not need a persistence store in this task.
|
||||
|
||||
Expected result: a small typed model or schema with tests for construction and
|
||||
basic serialization.
|
||||
|
||||
Result: Added `railiance_fabric.zone_view` dataclasses for zone definitions,
|
||||
attraction rules, layout, presentation, collapse settings, resolved zone
|
||||
instances, node assignments, boundary edges, diagnostics, and serializable
|
||||
resolution output. Covered definition round-trip and resolution serialization in
|
||||
`tests/test_zone_view.py`.
|
||||
|
||||
## Task 2: Implement A Pure Zone Resolver
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0022-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "d0ca41d2-f7c4-4409-8799-4c0099192af5"
|
||||
```
|
||||
|
||||
Implement a pure resolver that accepts graph nodes, graph edges, and zone
|
||||
definitions, then returns resolved zone instances.
|
||||
|
||||
The first resolver should support a conservative rule subset:
|
||||
|
||||
- membership operators: `equals`, `in`, `exists`
|
||||
- rule composition: `all`, `any`
|
||||
- attraction by edge type, direction, and depth
|
||||
- single-zone assignment invariant
|
||||
- conflict diagnostics when rules overlap
|
||||
|
||||
Expected result: resolver unit tests that prove deterministic node assignment,
|
||||
seed-vs-attraction precedence, conflict reporting, and depth-limited attraction.
|
||||
|
||||
Result: Implemented `resolve_zones()` as a pure resolver over Cytoscape-style or
|
||||
raw node/edge mappings. It supports `equals`, `in`, `exists`, `all`, `any`,
|
||||
membership `rules`, edge-type/direction/depth attraction, seed precedence,
|
||||
height/order conflict resolution, single-zone node assignments, boundary edge
|
||||
summaries, and conflict diagnostics. Covered the core behavior in
|
||||
`tests/test_zone_view.py`.
|
||||
|
||||
## Task 3: Back The Existing Overlays With Zone Definitions
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0022-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "c89d8d53-72a4-4590-a0e5-67b012c3550c"
|
||||
```
|
||||
|
||||
Replace the graph explorer's hard-coded environment/access overlay grouping
|
||||
logic with resolver-backed default zone definitions.
|
||||
|
||||
The current operator-facing behavior should remain available:
|
||||
|
||||
- deployment environment grouping renders `dev-tegwick`, `test`, and `prod`
|
||||
- legacy `staging` evidence maps to `test`
|
||||
- `all` is not rendered as a deployment environment zone
|
||||
- access-zone grouping remains available when access-zone metadata exists
|
||||
- visible nodes must be assigned to no more than one rendered zone
|
||||
|
||||
Expected result: existing graph explorer tests continue to pass, with new tests
|
||||
showing that the UI obtains zone rectangles from resolved zone instances.
|
||||
|
||||
Result: Refactored the graph explorer overlay to use explicit default zone
|
||||
definitions and a client-side `resolveZoneInstances()` path. Deployment
|
||||
environment zones now resolve through declarative membership rules with
|
||||
`deploymentEnvironment` normalization for `dev` -> `dev-tegwick`,
|
||||
`test`/`staging` -> `test`, `prod` -> `prod`, and ignored `all` values. Access
|
||||
zone overlays are generated as dynamic definitions from visible graph evidence.
|
||||
The overlay keeps the single-zone visible-node assignment behavior while
|
||||
preserving edge evidence in zone details.
|
||||
|
||||
## Task 4: Add Zone Diagnostics To The Explorer
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0022-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "d140cb5b-6a35-4cb0-ab68-e39e708c08e9"
|
||||
```
|
||||
|
||||
Expose zone resolver diagnostics in the graph explorer without overwhelming the
|
||||
map.
|
||||
|
||||
Diagnostics should include at least:
|
||||
|
||||
- node matched by more than one zone
|
||||
- node attracted by more than one zone
|
||||
- zone definition produced no seed nodes
|
||||
- attraction reached its configured depth limit
|
||||
- edge crosses zone boundaries
|
||||
|
||||
Expected result: zone detail panels show scoped diagnostics, and tests verify
|
||||
that diagnostics are generated by the resolver rather than ad hoc UI checks.
|
||||
|
||||
Result: Added resolver diagnostics for empty seed sets, overlapping zone
|
||||
membership, attraction depth-limit stops, and boundary-crossing edges. The graph
|
||||
explorer now surfaces scoped zone diagnostics in the selected zone detail panel
|
||||
and orientation context, with assertions proving diagnostics come from the zone
|
||||
resolver path.
|
||||
|
||||
## Task 5: Persist Zone View Settings In Profiles
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0022-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "765caa50-f372-4ab4-adb4-87660e684c54"
|
||||
```
|
||||
|
||||
Extend saved graph profile state so profiles can remember zone configuration.
|
||||
|
||||
At minimum, preserve:
|
||||
|
||||
- whether zones are visible
|
||||
- active zone definition set
|
||||
- active zone grouping
|
||||
- zone presentation preferences that are already supported by the UI
|
||||
|
||||
Expected result: saved views restore the same zone mode and default definition
|
||||
set after reload.
|
||||
|
||||
Result: Added explicit nested zone state to graph explorer profiles with
|
||||
`visible`, `grouping`, `definitionSet`, and `presentation` fields while keeping
|
||||
legacy URL aliases for `zoneBoundaries`, `zoneGrouping`, and
|
||||
`zoneDefinitionSet`. Saved and copied views now preserve the active zone
|
||||
definition set and presentation state, and profile restore normalizes unknown
|
||||
future definition sets back to the Fabric default.
|
||||
|
||||
## Task 6: Prototype Collapse-To-Zone-Node
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0022-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "7f3676cb-3d2e-417c-a385-f95545bcd738"
|
||||
```
|
||||
|
||||
Prototype collapsing a resolved zone into a representative node while preserving
|
||||
external connectivity in the visible graph.
|
||||
|
||||
The prototype should:
|
||||
|
||||
- hide nodes assigned to the collapsed zone
|
||||
- render a zone node with summary metadata
|
||||
- reconnect external edges to the zone node for the current view
|
||||
- hide or summarize internal edges
|
||||
- expand back to the original view without data loss
|
||||
|
||||
Expected result: collapse behavior works for one zone at a time and is covered
|
||||
by focused tests. Multi-zone hierarchy can remain future work.
|
||||
|
||||
Result: Added a view-only zone collapse prototype to the graph explorer. Zone
|
||||
detail panels now offer `Collapse Zone`; collapsed zones hide member nodes,
|
||||
render a synthetic zone node with node/internal-edge/boundary-edge summaries,
|
||||
draw synthetic boundary edges to visible external neighbors, and expose
|
||||
`Expand Zone` from the collapsed zone node. Expanding removes synthetic elements
|
||||
and restores the original graph view without changing the underlying payload.
|
||||
|
||||
## Task 7: Prepare For Per-Zone Layout
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0022-T07
|
||||
status: done
|
||||
priority: low
|
||||
state_hub_task_id: "4b6f0b7e-a066-490d-8160-ba23b03cf820"
|
||||
```
|
||||
|
||||
Identify the UI and Cytoscape integration changes needed for each zone to use a
|
||||
different layout algorithm for its assigned subgraph.
|
||||
|
||||
This task should not attempt a full layout rewrite unless the preceding tasks
|
||||
make it small and safe. It should produce either a narrow implementation step or
|
||||
a follow-up workplan for two-phase layout.
|
||||
|
||||
Expected result: the codebase has a documented path toward per-zone layouts
|
||||
without destabilizing the current graph explorer.
|
||||
|
||||
Result: Documented the per-zone layout preparation path in
|
||||
`docs/ZoneEntityVisualization.md`. The recommended direction is a two-phase
|
||||
layout: resolve zones and containers first, then compute local zone coordinates
|
||||
and project them into Cytoscape space. The note identifies the prerequisites
|
||||
already established by WP-0022 and avoids a premature nested-layout rewrite.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Zone entity behavior is documented in `docs/ZoneEntityVisualization.md`.
|
||||
- Zone definitions and resolved zone instances exist as explicit internal
|
||||
concepts.
|
||||
- The current deployment/access overlay behavior is implemented through the
|
||||
zone resolver.
|
||||
- The graph explorer keeps the single-zone assignment invariant for visible
|
||||
nodes.
|
||||
- Zone diagnostics are available to the operator.
|
||||
- Saved graph views can preserve supported zone settings.
|
||||
- Collapse-to-zone-node is prototyped behind clear UI behavior or an explicit
|
||||
experimental switch.
|
||||
@@ -0,0 +1,115 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0023
|
||||
type: workplan
|
||||
title: "Improve zone labels and dragging"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-05-25"
|
||||
updated: "2026-06-05"
|
||||
state_hub_workstream_id: "f02e14c5-e60f-4950-b1a2-682c38b30431"
|
||||
---
|
||||
|
||||
# Improve Zone Labels And Dragging
|
||||
|
||||
## Context
|
||||
|
||||
RAIL-FAB-WP-0021 introduced zone boundary rectangles and RAIL-FAB-WP-0022
|
||||
promoted zones to first-class graph explorer view entities. The current zone
|
||||
labels still look like small framed buttons with a white background. That makes
|
||||
the overlay read more like controls than like labels printed on a drawing
|
||||
surface.
|
||||
|
||||
The next interaction step is to let the operator grab a zone and move it around,
|
||||
dragging all currently attached visible nodes with it. This makes zones behave
|
||||
more like the intended "piece of paper" view entity while keeping the underlying
|
||||
Fabric graph unchanged.
|
||||
|
||||
## Task 1: Simplify Zone Labels
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0023-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "cb31f964-9e25-483d-b2b3-c4acc7a1033a"
|
||||
```
|
||||
|
||||
Change zone labels from framed button badges to plain text in the upper-left
|
||||
corner of the zone rectangle.
|
||||
|
||||
The label should:
|
||||
|
||||
- have no frame;
|
||||
- have no white background;
|
||||
- remain readable against the zone fill;
|
||||
- still be keyboard-focusable/clickable enough to open zone details;
|
||||
- avoid adding visual clutter to dense graph views.
|
||||
|
||||
Expected result: graph explorer zone labels look like text drawn on the zone
|
||||
surface rather than separate UI controls.
|
||||
|
||||
Result: Updated graph explorer zone labels to render as transparent, unframed
|
||||
text in the upper-left corner of each zone rectangle. Labels remain
|
||||
keyboard-focusable and clickable, and the visual smoke screenshot confirms the
|
||||
labels read as text on the zone surface.
|
||||
|
||||
## Task 2: Drag Zones With Member Nodes
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0023-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "84de3a0d-2ab9-4775-b026-87646ea14176"
|
||||
```
|
||||
|
||||
Add a zone drag interaction that moves all currently attached visible member
|
||||
nodes with the zone.
|
||||
|
||||
The interaction should:
|
||||
|
||||
- start from the zone label or zone boundary affordance;
|
||||
- move assigned visible nodes by the drag delta;
|
||||
- keep Cytoscape node positions and overlay bounds in sync;
|
||||
- update zone details and labels during/after the drag;
|
||||
- avoid mutating the underlying Fabric payload;
|
||||
- not interfere with normal node dragging more than necessary.
|
||||
|
||||
Expected result: grabbing a zone lets the operator reposition the visible zone
|
||||
subgraph as a unit.
|
||||
|
||||
Result: Added a view-only zone drag interaction using the plain zone label as
|
||||
the grab handle. Dragging translates the currently assigned visible zone member
|
||||
nodes by the pointer delta, recomputes overlay bounds, refreshes zone details,
|
||||
and leaves the Fabric graph payload unchanged.
|
||||
|
||||
## Task 3: Verify Interaction Behavior
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0023-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "8793e982-8991-4cda-8259-3f981bbb9201"
|
||||
```
|
||||
|
||||
Verify the visual and interaction behavior with focused tests and a browser
|
||||
smoke check.
|
||||
|
||||
The verification should cover:
|
||||
|
||||
- static UI test assertions for the new label/drag helpers;
|
||||
- JavaScript syntax validation;
|
||||
- graph explorer focused tests;
|
||||
- a visual smoke screenshot showing plain labels;
|
||||
- manual or scripted confirmation that zone dragging moves member nodes.
|
||||
|
||||
Expected result: the UI renders clean labels and the zone drag interaction works
|
||||
without breaking existing graph explorer behavior.
|
||||
|
||||
Result: Static UI assertions, JavaScript syntax validation, focused graph tests,
|
||||
full test suite, Fabric CLI validation, and a headless Edge visual smoke pass.
|
||||
The scripted drag smoke ran against the registry-backed graph explorer in
|
||||
disposable Edge via CDP, dragged the `dev-tegwick` zone label, confirmed 25
|
||||
rendered nodes moved together, and observed the UI status text
|
||||
`Moved zone "dev-tegwick".`
|
||||
@@ -0,0 +1,134 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0024
|
||||
type: workplan
|
||||
title: "Stabilize zone containers and layout zone subgraphs"
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-05-25"
|
||||
updated: "2026-05-25"
|
||||
state_hub_workstream_id: "63202459-2f73-409a-8881-307a5fc1835a"
|
||||
---
|
||||
|
||||
# Stabilize Zone Containers And Layout Zone Subgraphs
|
||||
|
||||
## Context
|
||||
|
||||
RAIL-FAB-WP-0022 made zones first-class visualization entities and
|
||||
RAIL-FAB-WP-0023 added plain labels plus view-only zone dragging. The current
|
||||
prototype still derives a zone rectangle directly from the current positions of
|
||||
its member nodes. When the operator changes the layout algorithm or reruns
|
||||
layout, the zone surface moves with the global graph layout instead of staying
|
||||
where the operator placed it.
|
||||
|
||||
The current resolver also treats every edge attached to a zoned node as zone
|
||||
context. That includes display-only repository declaration edges. Those edges
|
||||
help explain where graph declarations came from, but they should not be read as
|
||||
direct deployment or operational connections across a zone boundary.
|
||||
|
||||
This workplan moves the graph explorer toward the intended model: a zone is a
|
||||
stable drawing surface, and the assigned subgraph is laid out inside that
|
||||
surface as a separate view concern.
|
||||
|
||||
## Task 1: Separate Context Edges From Zone Boundary Connectivity
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0024-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "5e018a70-5aff-41bb-b0f9-0f59302c58ae"
|
||||
```
|
||||
|
||||
Exclude display-only/context edges, especially repository `declares` edges,
|
||||
from zone boundary diagnostics and collapsed-zone boundary edges.
|
||||
|
||||
Expected result: zone detail may still mention contextual evidence when useful,
|
||||
but display-only declaration edges do not make it look as if every zoned node is
|
||||
directly connected to an unzoned repository.
|
||||
|
||||
Result: Display-only edges and repository `declares` edges are now treated as
|
||||
context-only in both the shared zone resolver and the browser view. They do not
|
||||
create boundary diagnostics, attraction paths, or collapsed-zone boundary
|
||||
edges.
|
||||
|
||||
## Task 2: Persist Stable Zone Container Positions
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0024-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "ffa3f7b8-ee85-461a-89b8-007e4879171c"
|
||||
```
|
||||
|
||||
Introduce a view-level zone container state keyed by stable zone id.
|
||||
|
||||
The implementation should:
|
||||
|
||||
- remember zone container center and size after layout and drag;
|
||||
- keep user-moved zone positions stable when the global layout algorithm
|
||||
changes;
|
||||
- keep saved/copied view state compatible with the nested `zone` object;
|
||||
- avoid mutating the Fabric graph payload.
|
||||
|
||||
Expected result: switching between layout algorithms keeps zone papers in the
|
||||
same operator-chosen positions.
|
||||
|
||||
Result: The graph explorer now stores stable zone containers in view state.
|
||||
Containers remember graph-coordinate position and size, survive global layout
|
||||
reruns, can be saved/copied through the nested `zone` state, and remain separate
|
||||
from Fabric graph payload data.
|
||||
|
||||
## Task 3: Layout Zone Subgraphs Inside Containers
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0024-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "f2f5adfa-4de4-4606-aa9f-51dbf10c6443"
|
||||
```
|
||||
|
||||
Add a per-zone layout pass that positions assigned visible nodes inside their
|
||||
zone container after the global layout places the surrounding graph.
|
||||
|
||||
The first implementation may use a deterministic compact layout rather than a
|
||||
full nested Cytoscape layout, as long as it:
|
||||
|
||||
- only moves visible nodes assigned to the zone;
|
||||
- keeps each node inside the zone's drawing surface;
|
||||
- treats unzoned nodes as part of the base canvas;
|
||||
- keeps edge routing intact through Cytoscape's normal renderer.
|
||||
|
||||
Expected result: the visible subgraph inside each zone is arranged by the zone
|
||||
view model, not merely enclosed after the global layout.
|
||||
|
||||
Result: After global layout, each visible zone projects its assigned nodes into
|
||||
a local compact layout inside its stable container. New, not-yet-moved zones are
|
||||
packed into readable rows so the default deployment-environment papers start as
|
||||
separate drawing surfaces.
|
||||
|
||||
## Task 4: Verify And Document Zone Layout Semantics
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0024-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "cd418134-cacc-42f6-a6ea-0bfd1cda9965"
|
||||
```
|
||||
|
||||
Update the graph explorer contract and run focused validation.
|
||||
|
||||
Verification should cover:
|
||||
|
||||
- static UI assertions for context-edge filtering and zone container helpers;
|
||||
- JavaScript syntax validation;
|
||||
- focused graph explorer and zone resolver tests;
|
||||
- a visual smoke check of the graph explorer.
|
||||
|
||||
Expected result: documentation and tests describe the new semantics, and the
|
||||
running UI shows stable zone containers with locally arranged member nodes.
|
||||
|
||||
Result: Updated the graph explorer contract and zone entity documentation.
|
||||
Focused tests, generated JavaScript syntax validation, full tests, CLI
|
||||
validation, and a headless Edge visual smoke check all passed.
|
||||
Reference in New Issue
Block a user