railiance-fabric/workplans/RAIL-FAB-WP-0022-zone-entity-visualization-engine.md

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

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
RAIL-FAB-WP-0022	workplan	Promote graph zones to first-class visualization entities	railiance	railiance-fabric	finished	codex	railiance-fabric	2026-05-24	2026-05-24	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

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

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

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

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

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

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

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.