railiance-fabric/workplans/RAIL-FAB-WP-0014-runtime-topology-discovery.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
RAIL-FAB-WP-0014	workplan	Runtime Topology Discovery	railiance	railiance-fabric	finished	codex	railiance	high	14	2026-05-21	2026-05-21	9cb51719-3ef1-400a-916e-959b24c67b79

RAIL-FAB-WP-0014 - Runtime Topology Discovery

Goal

Discover runtime topology before broader projection: servers, ports exposed by services, and domain names that map onto those ports.

Background

The current scanner already discovers deployment-like evidence from Docker Compose, Kubernetes manifests, service configs, and Fabric declarations. The graph explorer can infer some Server nodes from accepted interface endpoint URLs, but that inference is UI-local and misses servers/domains/ports that live in runtime manifests.

Before a full discovery/projection pass, Fabric should capture these runtime facts as normal discovery candidates with source anchors and conservative review state.

Design Principles

• Keep repo-owned declaration schemas unchanged for this increment.
• Emit discovery candidates for Server, NetworkPort, and DomainName.
• Keep facts source-linked to Compose, Kubernetes, or Fabric declaration files.
• Do not resolve DNS or scan networks; only parse deterministic repo evidence.
• Avoid projection until the broad runtime discovery pass has been reviewed.

Tasks

T01 - Add Runtime Topology Test Fixture

id: RAIL-FAB-WP-0014-T01
status: done
priority: high
state_hub_task_id: "714e3560-cd32-4009-8cdd-8ff410cd2725"

Extend scanner tests so a fixture repo exposes Compose ports, Kubernetes Service ports, Kubernetes Ingress domains, and Fabric interface endpoint URLs.

T02 - Discover Compose Runtime Ports And Domains

id: RAIL-FAB-WP-0014-T02
status: done
priority: high
state_hub_task_id: "20923f1d-6bf7-4f59-a9e5-4898d6f0a699"

Extract Server, NetworkPort, and DomainName candidates from Compose published ports and common domain labels such as Traefik Host(...), VIRTUAL_HOST, and LETSENCRYPT_HOST.

T03 - Discover Kubernetes Runtime Ports And Domains

id: RAIL-FAB-WP-0014-T03
status: done
priority: high
state_hub_task_id: "a7664f5e-4530-413d-a1b1-2a1702ac9763"

Extract ports from Kubernetes Service manifests and domains from Ingress rules/TLS hosts, linking domains to the relevant ingress/service/port evidence where possible.

T04 - Discover Fabric Endpoint Runtime Facts

id: RAIL-FAB-WP-0014-T04
status: done
priority: medium
state_hub_task_id: "4f5e5c34-453c-4c3b-969e-80d5d2b9b370"

Extract server/domain/port candidates from InterfaceDeclaration endpoint URLs so declared HTTP/database endpoints participate in the same runtime topology view.

T05 - Verify Broad Runtime Discovery

id: RAIL-FAB-WP-0014-T05
status: done
priority: high
state_hub_task_id: "4aae0fa0-39a4-401c-ad5f-8d0f7647cfb6"

Run the deterministic tests and a broad ingest-only rescan. Confirm server, port, and domain candidates appear without duplicate conflicts or review-only blockers.

Verification result:

• python3 -m pytest passed with 33 tests.
• Broad ingest-only rescan completed with 35 repos scanned, 28 unchanged, 7 changed, 0 retired, 0 conflicted, 0 review required, and 0 errors.
• Report: registry/.fabric-discovery/reports/2026-05-20t222151z-deterministic.rescan-report.json.
• Latest discovery snapshots now include 20 Server, 26 NetworkPort, and 14 DomainName candidates across flex-auth, net-kingdom, railiance-apps, railiance-cluster, railiance-fabric, repo-scoping, and state-hub.
• registry rescan-status --review-only --json shows 0 review-required repos.

Projection recommendation:

• Keep this runtime topology as ingested discovery state for review.
• Do not project candidate-only topology into accepted graph snapshots until we have reviewed the server/domain/port inventory in the graph explorer or a focused report.

Close Criteria

• Scanner tests validate server, network port, and domain candidates.
• Runtime topology candidates are schema-valid discovery output.
• Broad ingest-only rescan reports no scanner errors.
• State Hub records the outcome and the next projection recommendation.