generated from coulomb/repo-seed
213 lines
8.3 KiB
Markdown
213 lines
8.3 KiB
Markdown
---
|
|
id: RAIL-FAB-WP-0016
|
|
type: workplan
|
|
title: "Canon-Aligned Graph Model Reset And Reingest"
|
|
domain: railiance
|
|
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.
|