railiance-fabric/workplans/RAIL-FAB-WP-0015-runtime-entity-taxonomy.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-0015	workplan	Runtime Entity Taxonomy Refinement	railiance	railiance-fabric	finished	codex	railiance	high	15	2026-05-21	2026-05-21	958559cc-c640-40d6-afe3-467ee0e9e973

RAIL-FAB-WP-0015 - Runtime Entity Taxonomy Refinement

Goal

Refine runtime topology discovery and graph rendering so servers, services, applications, ports, and domains are distinct entities instead of variants of the old catch-all Server node.

Background

The first runtime topology pass intentionally used conservative Server, NetworkPort, and DomainName nodes. After projecting all candidates into the graph, this proved too broad:

• 127.0.0.1:8765 is a port endpoint, not a server.
• gitea.coulomb.social is an application-facing endpoint, not a machine.
• pink-account.coulomb.social should be connected through the privacyIDEA service/application topology instead of floating as a repo-declared server.

Target Model

• Server is reserved for concrete machine or host addresses such as IPs and localhost loopback addresses.
• RuntimeService represents a running service target such as a Kubernetes Service DNS name or a declared service endpoint.
• ApplicationEndpoint represents user-facing application endpoints exposed through domains, ingress hosts, or declared HTTP URLs.
• NetworkPort remains the separate port/protocol binding node.
• DomainName remains the DNS name and routes to the port/service/application it describes.

Tasks

T01 - Update Runtime Scanner Taxonomy

id: RAIL-FAB-WP-0015-T01
status: done
priority: high
state_hub_task_id: "c19f55e2-dd68-4cb9-8c21-fd9c61a3ab25"

Emit refined runtime candidates from Compose, Kubernetes, and Fabric endpoint evidence without using Server for domain names or service DNS targets.

T02 - Update Graph Explorer Runtime Projection

id: RAIL-FAB-WP-0015-T02
status: done
priority: high
state_hub_task_id: "b5caa75d-04bf-4eb3-9b61-f28eb85fe9d4"

Render legacy accepted Server candidates as the refined presentation kind where their attributes make the intent clear, and stop inferring host:port values as server nodes.

T03 - Preserve Port And Service Relationships

id: RAIL-FAB-WP-0015-T03
status: done
priority: medium
state_hub_task_id: "06b19102-d5f9-4707-af86-7fb248126374"

Keep existing port/domain relationships while adding explicit relationships from runtime services and application endpoints to their ports. Deduplicate inferred deployment runs_on edges.

T04 - Verify Fixtures And Live Graph Shape

id: RAIL-FAB-WP-0015-T04
status: done
priority: high
state_hub_task_id: "d14e85b4-4323-4ce6-9e25-bc92293dc351"

Update scanner and graph explorer tests, then verify the live graph no longer classifies application domains or host:port endpoints as servers.

Verification result:

• python3 -m pytest tests/test_graph_explorer.py tests/test_scanner.py -q passed with 8 tests.
• python3 -m pytest passed with 35 tests.
• Restarted the local registry on port 8765.
• Live graph explorer export now shows:
  • 127.0.0.1:8765 as a NetworkPort.
  • gitea.coulomb.social and pink-account.coulomb.social as ApplicationEndpoint nodes where legacy discovery previously rendered them as Server.
  • privacyidea.mfa.svc.cluster.local as a RuntimeService.
  • 0 Server nodes whose label contains host:port.
  • 1 runs_on edge from deployment:railiance-fabric.registry:dev.

Close Criteria

• Scanner tests distinguish Server, RuntimeService, ApplicationEndpoint, NetworkPort, and DomainName.
• Graph explorer tests validate endpoint parsing and duplicate runs_on removal.
• The local graph export shows application domains as applications, service DNS names as runtime services, and 127.0.0.1:8765 as a port.