docs: define zone visualization engine workplan

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

@@ -0,0 +1,194 @@
+---
+id: RAIL-FAB-WP-0022
+type: workplan
+title: "Promote graph zones to first-class visualization entities"
+domain: railiance
+repo: railiance-fabric
+status: proposed
+owner: codex
+topic_slug: railiance-fabric
+created: "2026-05-24"
+updated: "2026-05-24"
+---
+
+# 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: todo
+priority: high
+```
+
+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.
+
+## Task 2: Implement A Pure Zone Resolver
+
+```task
+id: RAIL-FAB-WP-0022-T02
+status: todo
+priority: high
+```
+
+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.
+
+## Task 3: Back The Existing Overlays With Zone Definitions
+
+```task
+id: RAIL-FAB-WP-0022-T03
+status: todo
+priority: high
+```
+
+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.
+
+## Task 4: Add Zone Diagnostics To The Explorer
+
+```task
+id: RAIL-FAB-WP-0022-T04
+status: todo
+priority: medium
+```
+
+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.
+
+## Task 5: Persist Zone View Settings In Profiles
+
+```task
+id: RAIL-FAB-WP-0022-T05
+status: todo
+priority: medium
+```
+
+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
+
+```task
+id: RAIL-FAB-WP-0022-T06
+status: todo
+priority: medium
+```
+
+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
+
+```task
+id: RAIL-FAB-WP-0022-T07
+status: todo
+priority: low
+```
+
+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.