generated from coulomb/repo-seed
251 lines
9.1 KiB
Markdown
251 lines
9.1 KiB
Markdown
---
|
|
id: RAIL-FAB-WP-0022
|
|
type: workplan
|
|
title: "Promote graph zones to first-class visualization entities"
|
|
domain: railiance
|
|
repo: railiance-fabric
|
|
status: finished
|
|
owner: codex
|
|
topic_slug: railiance-fabric
|
|
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.
|