docs: define deployment zone overlays

workplans/RAIL-FAB-WP-0020-deployment-zone-discovery-visualization.md

@@ -0,0 +1,182 @@
+---
+id: RAIL-FAB-WP-0020
+type: workplan
+title: "Deployment Zone Discovery And Visualization"
+domain: railiance
+repo: railiance-fabric
+status: ready
+owner: codex
+topic_slug: railiance
+created: "2026-05-24"
+updated: "2026-05-24"
+state_hub_workstream_id: "e70820a9-d6f3-473d-a17c-b15fe3180773"
+---
+
+# RAIL-FAB-WP-0020 - Deployment Zone Discovery And Visualization
+
+## Goal
+
+Improve Fabric discovery and visualization so operators can see which services
+run in dev, test, and production deployment overlays without making Fabric the
+authority for ports, routes, or access policy.
+
+This work follows the terminology in `docs/FabricDiscoveryAndUpdate.md`:
+
+- fabric/subfabric remain financial responsibility boundaries;
+- deployment environment classifies lifecycle target: `dev`, `test`, `prod`;
+- deployment scenario names the concrete place where services run:
+  `bernd-laptop`, `coulombcore`, `railiance01`;
+- routing authority maps names or ports to backend services;
+- access zone groups intended reachability for visualization;
+- policy authority is the external system expected to enforce access rules.
+
+## Background
+
+The current local collision between the Fabric graph explorer port and the
+NetKingdom control surface showed that Fabric should detect routing reality,
+not organize it. The NetKingdom control surface now uses local port `8876`;
+the Fabric registry and graph explorer use `8765`.
+
+Railiance currently treats:
+
+- the operator laptop as private `dev`;
+- `coulombcore` as shared `test` for collaborators and friendly early-access
+  users;
+- `railiance01` as `prod`, currently alpha-accessible to developers but moving
+  toward restricted production access.
+
+## T01 - Extend Discovery Overlay Model
+
+```task
+id: RAIL-FAB-WP-0020-T01
+status: todo
+priority: high
+state_hub_task_id: "b8cf7d91-7743-4e58-9b13-ce99f2d9eef1"
+```
+
+Define schema/export fields for deployment overlays.
+
+Fields should cover:
+
+- `deployment_environment`;
+- `deployment_scenario`;
+- `routing_authority`;
+- `access_zone`;
+- `policy_authority`;
+- exposure class, such as local-only, collaborator-test, early-access,
+  production-public, or production-admin;
+- host, port, hostname, protocol, and route evidence where applicable.
+
+Done when identity projection, financial export, and graph-explorer payloads
+have a clear place to carry these fields without changing fabric membership.
+
+## T02 - Discover Local Dev Routing Evidence
+
+```task
+id: RAIL-FAB-WP-0020-T02
+status: todo
+priority: high
+state_hub_task_id: "b072e11b-08b5-426f-9f98-001abf8afd70"
+```
+
+Discover private developer-local routing evidence for `bernd-laptop`.
+
+Initial sources:
+
+- Makefile or script defaults;
+- local process launcher command lines where durable enough;
+- loopback URLs in docs and manifests;
+- Docker Compose published ports;
+- current known local surfaces such as Fabric registry `8765`, NetKingdom
+  control surface `8876`, State Hub API `8000`, State Hub MCP `8001`, and State
+  Hub dashboard `3000`.
+
+Done when local-only surfaces are marked as `deployment_environment: dev`,
+`deployment_scenario: bernd-laptop`, and `access_zone: private-dev` with
+provenance.
+
+## T03 - Discover Test And Production Routing Authorities
+
+```task
+id: RAIL-FAB-WP-0020-T03
+status: todo
+priority: high
+state_hub_task_id: "91fc3f28-fbb9-43d2-bb46-44d179f4b485"
+```
+
+Discover routing authority evidence for `coulombcore` and `railiance01`.
+
+Initial sources:
+
+- Kubernetes `Service` and `Ingress` manifests;
+- Traefik, nginx, Caddy, HAProxy, or equivalent proxy configuration;
+- DNS and TLS/cert-manager evidence when present;
+- Railiance infra and NetKingdom deployment documentation until executable
+  manifests are complete.
+
+Done when test-stage routes can be attributed to `coulombcore` and production
+routes can be attributed to `railiance01`, with access zones flagged as
+candidate values for operator review.
+
+## T04 - Add Zone Overlay Graph Explorer Modes
+
+```task
+id: RAIL-FAB-WP-0020-T04
+status: todo
+priority: high
+state_hub_task_id: "664c2688-f45b-47bf-90ff-b17096a326fb"
+```
+
+Add graph explorer support for overlay views:
+
+- by fabric/accountability;
+- by deployment environment;
+- by deployment scenario;
+- by routing authority;
+- by access zone.
+
+The UI should make it easy to answer:
+
+- what is running in private dev, shared test, and production;
+- what is production-facing on `railiance01`;
+- what is early-access reachable on `coulombcore`;
+- which control surfaces appear in user-facing zones;
+- which routes have no discovered policy authority.
+
+Done when the graph explorer can group/filter by overlay fields and surface the
+basic warnings without making policy decisions.
+
+## T05 - Preserve State Hub Read-Model Compatibility
+
+```task
+id: RAIL-FAB-WP-0020-T05
+status: todo
+priority: medium
+state_hub_task_id: "1a5ef6f9-357f-4803-a1f8-ebd1ff5443fb"
+```
+
+Ensure State Hub can ingest and query the new overlay fields.
+
+Done when Fabric exports remain backward compatible, State Hub keeps importing
+valid v1alpha2 exports, and overlay fields are visible enough for dashboard or
+search views.
+
+## T06 - Publish Current Zone Inventory
+
+```task
+id: RAIL-FAB-WP-0020-T06
+status: todo
+priority: medium
+state_hub_task_id: "a1b208e3-3321-4792-ba44-d32aba682183"
+```
+
+Run the improved discovery against the current Railiance workspace and publish a
+reviewable zone inventory.
+
+Done when there is a saved artifact answering:
+
+- which local dev services are visible on `bernd-laptop`;
+- which test-stage services are visible on `coulombcore`;
+- which production services are visible on `railiance01`;
+- which routes or ports are ambiguous, conflicting, or missing a policy
+  authority.