railiance-fabric/workplans/RAIL-FAB-WP-0020-deployment-zone-discovery-visualization.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-0020	workplan	Deployment Zone Discovery And Visualization	railiance	railiance-fabric	finished	codex	railiance	2026-05-24	2026-05-24	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

id: RAIL-FAB-WP-0020-T01
status: done
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.

Result: added a normalized deployment_overlay object and threaded it through identity candidates, financial exports, State Hub export schema validation, and graph-explorer payload fields/modes.

T02 - Discover Local Dev Routing Evidence

id: RAIL-FAB-WP-0020-T02
status: done
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.

Result: known local surfaces are declared or discovered with dev, bernd-laptop, private-dev, local-loopback policy authority, and route evidence: Fabric registry/explorer 8765, NetKingdom control surface 8876, State Hub API 8000, State Hub MCP 8001, and State Hub dashboard 3000.

T03 - Discover Test And Production Routing Authorities

id: RAIL-FAB-WP-0020-T03
status: done
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.

Result: published fabric/discovery/snapshots/2026-05-24-deployment-zone-inventory.yaml with coulombcore test tunnel evidence, railiance01 Traefik ingress evidence, candidate access zones, and explicit ambiguity flags for host/IP conflicts and operator review.

T04 - Add Zone Overlay Graph Explorer Modes

id: RAIL-FAB-WP-0020-T04
status: done
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.

Result: graph-explorer manifests and payloads expose deployment overlay fields; the UI includes zone modes, overlay search/rule filtering, visible zone summaries, and route-without-policy-authority warnings.

T05 - Preserve State Hub Read-Model Compatibility

id: RAIL-FAB-WP-0020-T05
status: done
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.

Result: schemas/state-hub-export.schema.yaml accepts optional deployment_overlay objects on financial nodes and edges while preserving the legacy export shape. Focused compatibility tests pass.

T06 - Publish Current Zone Inventory

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

Result: saved the current inventory at fabric/discovery/snapshots/2026-05-24-deployment-zone-inventory.yaml and added focused test coverage to keep the dev/test/prod scenario answers present.