---
id: RAIL-FAB-WP-0014
type: workplan
title: "Runtime Topology Discovery"
domain: railiance
repo: railiance-fabric
status: finished
owner: codex
topic_slug: railiance
planning_priority: high
planning_order: 14
created: "2026-05-21"
updated: "2026-05-21"
state_hub_workstream_id: "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

```task
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

```task
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

```task
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

```task
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

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