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	active	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: todo
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.

Task 6: Prototype Collapse-To-Zone-Node

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

Task 7: Prepare For Per-Zone Layout

id: RAIL-FAB-WP-0022-T07
status: todo
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.

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.