generated from coulomb/repo-seed
Discover runtime topology facts
This commit is contained in:
134
workplans/RAIL-FAB-WP-0014-runtime-topology-discovery.md
Normal file
134
workplans/RAIL-FAB-WP-0014-runtime-topology-discovery.md
Normal file
@@ -0,0 +1,134 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user