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

---
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.