generated from coulomb/repo-seed
135 lines
4.2 KiB
Markdown
135 lines
4.2 KiB
Markdown
---
|
|
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.
|