Router Microservice Transport Guardrails

This document defines mandatory guardrails for migrating StellaOps.*.WebService services to Router microservice transport over Valkey messaging.

Required Contract

Service startup must use AddRouterMicroservice(...) from StellaOps.Router.AspNet.
Router transport activation must be configuration-driven from environment/compose keys.
Transport implementation loading must remain plugin-based:
Router transport plugins from Router:TransportPlugins:*.
Messaging backend plugin from Router:Messaging:PluginDirectory and Router:Messaging:SearchPattern.
Messaging transport selection must be explicit (Router:Messaging:Transport=valkey for this rollout).
Services must keep rollback-compatible toggles so routing can return to reverse proxy without code edits.

The loader scans Router:Messaging:PluginDirectory itself and its immediate subdirectories, and nothing deeper. A bundle is a directory that holds manifest.json; its name is the transport name (valkey). Two layouts load: the directory is the bundle (/app/plugins/messaging/base/valkey, most hosts) or its parent (/app/plugins/messaging holding valkey/, the Vulnerabilities hub). A tree copied from another host’s image keeps that host’s layout and is not scanned when the two differ.
Admission is fail-closed: the bundle must verify against Router:Messaging:TrustRootPath (default /app/trust-roots/plugins/messaging/cosign.pub).
When the configured transport is not discovered, startup stops with Messaging transport '<name>' configured at '<section>:transport' was not discovered, followed by the scanned directory and the bundle directories found there. No messaging transport configured means the transport key itself is unset.
Release images carry the bundles in a second build stage (devops/release/bundle/tools/build-plugin-layers.sh). An image from devops/docker/build-service-publish.sh alone carries none. tools/scripts/validate/check-bundle-messaging-payload.py checks every bundle host’s configuration against the layer plan, and --image <ref> checks a built image.

Direct service-level DI calls to concrete transport registration methods such as:
AddMessagingTransportClient()
AddTcpTransportClient()
AddUdpTransportClient()
AddRabbitMqTransportClient()
AddTlsTransportClient()
Legacy gateway startup paths must not call AddInMemoryTransport() to satisfy default gateway transport binding. AddRouterGateway(...) is fail-closed by default; process-local in-memory transport is only available through the explicit AddRouterGatewayLocalInMemoryHarness(...) API and only in Development, Testing, or Local host environments.
Compile-time coupling from webservice projects to transport assemblies solely to enable default behavior.
Hardcoded transport selection in code paths that bypass environment/compose configuration.

Router enabled with missing gateway endpoints must fail fast.
Missing/invalid router options section input must fail fast.
Missing transport plugin for configured TransportType must fail fast with explicit error text.
Messaging transport binding must verify queue/timeouts and Valkey options from configuration.

[ ] Service startup uses AddRouterMicroservice(...) and retains TryUseStellaRouter(...) behavior.
[ ] No direct concrete transport registration calls are added in service DI.
[ ] Compose/environment keys are added for router enablement, plugin directories, and Valkey settings.
[ ] Gateway route plan updated (ReverseProxy -> Microservice) with rollback instructions.
[ ] OpenAPI preview (/openapi.json) shows migrated endpoint paths plus schema components.
[ ] Targeted tests include plugin-missing and section-validation failure cases.
[ ] Sprint execution log and decisions/risks updated with doc links and evidence.