stela ops usage fixes roles propagation and timoeut, one account to support multi tenants, migrations consolidation, search to support documentation, doctor and open api vector db search

2026-02-22 19:27:54 +02:00
parent a29f438f53
commit bd8fee6ed8
373 changed files with 832097 additions and 3369 deletions
--- a/docs/modules/advisory-ai/README.md
+++ b/docs/modules/advisory-ai/README.md
@@ -17,6 +17,7 @@ Advisory AI is the retrieval-augmented assistant that synthesizes advisory and V
 - RAG pipeline drawing from Conseiller, Excititor, VEX Lens, Policy Engine, and SBOM Service data.
 - Prompt templates and guard models enforcing provenance and redaction policies.
 - Vercel/offline inference workers with deterministic caching of generated artefacts.
+- AdvisoryAI Knowledge Search (AKS) for deterministic docs/API/Doctor retrieval: `docs/modules/advisory-ai/knowledge-search.md`.

 ## Integrations & dependencies
 - Authority for tenant-aware access control.
--- a/docs/modules/advisory-ai/guides/api.md
+++ b/docs/modules/advisory-ai/guides/api.md
@@ -202,6 +202,79 @@ Fetch cached artefact (same envelope as §6). Requires `advisory-ai:view`.

 When plan preview is enabled (feature flag `advisoryAi.planPreview.enabled`), this endpoint returns the orchestration plan using `AdvisoryPipelinePlanResponse` (task metadata, chunk/vector counts). Requires `advisory-ai:operate`.

+### 7.8 `LLM Adapter Exposure (RVM-08)`
+
+AdvisoryAI now exposes a unified adapter surface for provider discovery and OpenAI-compatible completion calls.
+
+- `GET /v1/advisory-ai/adapters/llm/providers`
+- `POST /v1/advisory-ai/adapters/llm/{providerId}/chat/completions`
+- `POST /v1/advisory-ai/adapters/openai/v1/chat/completions` (alias for `providerId=openai`)
+
+Scope requirements:
+
+- Read/discovery: `advisory:adapter:read` or `advisory:run`
+- Invoke/completion: `advisory:adapter:invoke` or `advisory:openai:invoke` or `advisory:{providerId}:invoke` or `advisory:run`
+
+Operational notes:
+
+- Adapter endpoints are disabled by default and must be explicitly enabled by config.
+- `stream=true` is currently rejected on adapter completion endpoints.
+- Provider discovery returns configuration/validation/exposure state per provider so operators can verify whether `openai` is configured before traffic cutover.
+
+Runtime config keys:
+
+- `AdvisoryAI:Adapters:Llm:Enabled` (env `ADVISORYAI__AdvisoryAI__Adapters__Llm__Enabled`)
+- `AdvisoryAI:LlmProviders:ConfigDirectory` (env `ADVISORYAI__AdvisoryAI__LlmProviders__ConfigDirectory`)
+
+Gateway exposure paths:
+
+- `/v1/advisory-ai/adapters`
+- `/api/v1/advisory-ai/adapters`
+
+### 7.9 `Knowledge Search (AKS)`
+
+Deterministic retrieval API for docs, OpenAPI operations, and Doctor checks.
+
+- `POST /v1/advisory-ai/search`
+- `POST /v1/advisory-ai/index/rebuild`
+
+Scope notes:
+- Search: one of `advisory:run`, `advisory:search`, `advisory:read`.
+- Rebuild: one of `advisory:run`, `advisory:admin`, `advisory:index:write`.
+
+Search request:
+```json
+{
+  "q": "docker login fails with x509 unknown authority",
+  "k": 10,
+  "filters": {
+    "type": ["docs", "doctor"],
+    "product": "stella-ops",
+    "version": "2026.02",
+    "service": "gateway",
+    "tags": ["troubleshooting", "tls"]
+  },
+  "includeDebug": false
+}
+```
+
+Search response contains only grounded results with source actions:
+- docs: `{ path, anchor, spanStart, spanEnd }`
+- api: `{ service, method, path, operationId }`
+- doctor: `{ checkCode, severity, canRun, runCommand }`
+
+Rebuild response:
+```json
+{
+  "documentCount": 12034,
+  "chunkCount": 68291,
+  "apiSpecCount": 41,
+  "apiOperationCount": 2132,
+  "doctorProjectionCount": 84,
+  "durationMs": 8245
+}
+```
+
 ## 8. Error model

 Errors follow a standard problem+JSON envelope:
--- a/docs/modules/advisory-ai/knowledge-search.md
+++ b/docs/modules/advisory-ai/knowledge-search.md
@@ -0,0 +1,137 @@
+# AdvisoryAI Knowledge Search (AKS)
+
+## Why retrieval-first
+AKS is a deterministic retrieval system for operational problem solving across Stella Ops docs, OpenAPI contracts, and Doctor checks. It is designed to work offline and does not require GPU-backed or hosted LLM inference for correctness.
+
+LLMs can still be used as optional formatters later, but AKS correctness is grounded in source retrieval and explicit references.
+
+## Scope
+- Module owner: `src/AdvisoryAI/**`.
+- Search surfaces consuming AKS:
+  - Web global search in `src/Web/StellaOps.Web/**`.
+  - CLI commands in `src/Cli/**`.
+- Doctor execution remains authoritative in Doctor module. AKS only indexes metadata and remediation references.
+
+## Architecture
+1. Ingestion/indexing:
+   - Markdown (`docs/**`) -> section chunks.
+   - OpenAPI (`openapi.json`) -> per-operation chunks + normalized operation tables.
+   - Doctor seed/metadata -> doctor projection chunks.
+2. Storage:
+   - PostgreSQL tables in schema `advisoryai` via migration `src/AdvisoryAI/StellaOps.AdvisoryAI/Storage/Migrations/002_knowledge_search.sql`.
+3. Retrieval:
+   - FTS (`tsvector` + `websearch_to_tsquery`) + optional vector stage.
+   - Deterministic fusion and tie-breaking in `KnowledgeSearchService`.
+4. Delivery:
+   - API endpoint: `POST /v1/advisory-ai/search`.
+   - Index rebuild endpoint: `POST /v1/advisory-ai/index/rebuild`.
+
+## Data model
+AKS schema tables:
+- `advisoryai.kb_doc`: canonical source docs with product/version/content hash metadata.
+- `advisoryai.kb_chunk`: searchable units (`md_section`, `api_operation`, `doctor_check`) with anchors, spans, `tsvector`, and embeddings.
+- `advisoryai.api_spec`: raw OpenAPI snapshot (`jsonb`) by service.
+- `advisoryai.api_operation`: normalized operation records (`method`, `path`, `operation_id`, tags, request/response/security json).
+- `advisoryai.doctor_search_projection`: searchable doctor metadata and remediation.
+
+Vector support:
+- Tries `CREATE EXTENSION vector`.
+- If unavailable, AKS remains fully functional via FTS and deterministic array embeddings fallback.
+
+## Deterministic ingestion rules
+### Markdown
+- Chunk by H2/H3 headings.
+- Stable anchors using slug + duplicate suffix.
+- Stable chunk IDs from source path + anchor + span.
+- Metadata includes path, anchor, section path, tags.
+
+### OpenAPI
+- Parse `openapi.json` only for deterministic MVP.
+- Emit one searchable chunk per HTTP operation.
+- Preserve structured operation payloads (`request_json`, `responses_json`, `security_json`).
+
+### Doctor
+- Source order:
+  1. Seed file `src/AdvisoryAI/StellaOps.AdvisoryAI/KnowledgeSearch/doctor-search-seed.json`.
+  2. Optional Doctor endpoint metadata (`DoctorChecksEndpoint`) when configured.
+- Emit doctor chunk + projection record including:
+  - `checkCode`, `title`, `severity`, `runCommand`, remediation, symptoms.
+
+## Ranking strategy
+Implemented in `src/AdvisoryAI/StellaOps.AdvisoryAI/KnowledgeSearch/KnowledgeSearchService.cs`:
+- Candidate retrieval:
+  - lexical set from FTS.
+  - optional vector set from embedding candidates.
+- Fusion:
+  - reciprocal rank fusion style scoring.
+- Deterministic boosts:
+  - exact `checkCode` match.
+  - exact `operationId` match.
+  - `METHOD /path` match.
+  - filter-aligned service/tag boosts.
+- Deterministic ordering:
+  - score desc -> kind asc -> chunk id asc.
+
+## API contract
+### Search
+- `POST /v1/advisory-ai/search`
+- Request:
+  - `q` (required), `k`, `filters.type|product|version|service|tags`, `includeDebug`.
+- Response:
+  - typed results (`docs|api|doctor`) with snippet, score, and open action.
+
+### Rebuild
+- `POST /v1/advisory-ai/index/rebuild`
+- Rebuilds AKS deterministically from local docs/specs/doctor metadata.
+
+## Web behavior
+Global search now consumes AKS and supports:
+- Mixed grouped results (`Docs`, `API Endpoints`, `Doctor Checks`).
+- Type filter chips.
+- Result actions:
+  - Docs: `Open`.
+  - API: `Curl` (copy command).
+  - Doctor: `Run` (navigate to doctor and copy run command).
+- `More` action for "show more like this" local query expansion.
+
+## CLI behavior
+AKS commands:
+- `stella search "<query>" [--type docs|api|doctor] [--product ...] [--version ...] [--service ...] [--tag ...] [--k N] [--json]`
+- `stella doctor suggest "<symptom>" [--product ...] [--version ...] [--k N] [--json]`
+- `stella advisoryai index rebuild [--json]`
+
+Output:
+- Human mode: grouped actionable references.
+- JSON mode: stable machine-readable payload.
+
+## Test/benchmark strategy
+Implemented benchmark framework:
+- Generator: `KnowledgeSearchBenchmarkDatasetGenerator` (deterministic synthetic set with explicit ground truth).
+- Runner: `KnowledgeSearchBenchmarkRunner` (recall@k, p50/p95 latency, stability pass).
+- Models/serialization:
+  - `KnowledgeSearchBenchmarkModels.cs`
+  - `KnowledgeSearchBenchmarkJson.cs`
+
+Tests:
+- `src/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Tests/KnowledgeSearch/KnowledgeSearchBenchmarkTests.cs`
+  - verifies deterministic dataset generation with >= 1000 queries.
+  - verifies recall/latency metrics and top-k match behavior.
+
+## Dedicated AKS test DB
+Compose profile:
+- `devops/compose/docker-compose.advisoryai-knowledge-test.yml`
+
+Init script:
+- `devops/compose/postgres-init/advisoryai-knowledge-test/01_extensions.sql`
+
+Example workflow:
+```bash
+docker compose -f devops/compose/docker-compose.advisoryai-knowledge-test.yml up -d
+stella advisoryai index rebuild --json
+dotnet test src/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Tests/StellaOps.AdvisoryAI.Tests.csproj
+```
+
+## Known limitations and follow-ups
+- YAML OpenAPI ingestion is not included in MVP.
+- End-to-end benchmark against live Postgres-backed AKS service is planned as a follow-up CI lane.
+- Optional external embedding providers can be added later without changing API contracts.
--- a/docs/modules/cli/guides/cli-reference.md
+++ b/docs/modules/cli/guides/cli-reference.md
@@ -20,6 +20,50 @@ Both commands are designed to enforce the AOC guardrails documented in the [aggr

 ---

+## 1.1 AdvisoryAI Knowledge Search
+
+AKS commands expose deterministic retrieval from AdvisoryAI (`docs|api|doctor`) without requiring an LLM.
+
+### `stella search`
+
+```bash
+stella search "<query>" \
+  [--type docs|api|doctor] \
+  [--product <product>] \
+  [--version <version>] \
+  [--service <service>] \
+  [--tag <tag>] \
+  [--k <1-100>] \
+  [--json]
+```
+
+Notes:
+- `--type` and `--tag` are repeatable or comma-separated.
+- `--json` emits stable machine-readable payload with `results[].open`.
+
+### `stella doctor suggest`
+
+```bash
+stella doctor suggest "<symptom-or-error>" \
+  [--product <product>] \
+  [--version <version>] \
+  [--k <1-100>] \
+  [--json]
+```
+
+Uses the same AKS index and prints grouped recommendations for:
+- Doctor checks (with run command).
+- Related docs anchors.
+- Related API operations.
+
+### `stella advisoryai index rebuild`
+
+```bash
+stella advisoryai index rebuild [--json]
+```
+
+Rebuilds the deterministic AKS index from local markdown, OpenAPI, and Doctor metadata sources.
+
 ## 2 · `stella sources ingest --dry-run`

 ### 2.1 Synopsis
--- a/docs/modules/gateway/openapi.md
+++ b/docs/modules/gateway/openapi.md
@@ -175,20 +175,39 @@ Each endpoint with claims gets a security requirement:
 ```csharp
 public static JsonArray GenerateSecurityRequirement(EndpointDescriptor endpoint)
 {
-    if (endpoint.RequiringClaims.Count == 0)
-        return new JsonArray(); // No security required
+    if (endpoint.AllowAnonymous)
+        return new JsonArray(); // Anonymous endpoint
+
+    if (!endpoint.RequiresAuthentication && endpoint.RequiringClaims.Count == 0)
+        return new JsonArray(); // No auth semantics published

    return new JsonArray
    {
        new JsonObject
        {
            ["BearerAuth"] = new JsonArray(),
-            ["OAuth2"] = new JsonArray(claims.Select(c => c.Type))
+            ["OAuth2"] = new JsonArray(scopes.Select(scope => scope))
        }
    };
 }
 ```

+### Router-specific OpenAPI extensions
+
+Gateway now emits Router-specific extensions on each operation:
+
+- `x-stellaops-gateway-auth`: effective authorization semantics projected from endpoint metadata.
+  - `allowAnonymous`
+  - `requiresAuthentication`
+  - `source` (`None`, `AspNetMetadata`, `YamlOverride`, `Hybrid`)
+  - optional `policies`, `roles`, `claimRequirements`
+- `x-stellaops-timeout`: timeout semantics used by gateway dispatch.
+  - `effectiveSeconds`
+  - `source` (`endpoint`, `gatewayRouteDefault`, and capped variants)
+  - `endpointSeconds`, `gatewayRouteDefaultSeconds`, `gatewayGlobalCapSeconds` when available
+  - precedence list: endpoint override -> service default -> gateway route default -> gateway global cap
+- `x-stellaops-timeout-seconds`: backward-compatible scalar alias for `effectiveSeconds`.
+
 ---

 ## Configuration Reference
--- a/docs/modules/router/README.md
+++ b/docs/modules/router/README.md
@@ -90,6 +90,11 @@ StellaOps.Router.slnx
 | [rate-limiting.md](rate-limiting.md) | Centralized router rate limiting (dossier) |
 | [aspnet-endpoint-bridge.md](aspnet-endpoint-bridge.md) | Using ASP.NET endpoint registration as Router endpoint registration |
 | [messaging-valkey-transport.md](messaging-valkey-transport.md) | Messaging transport over Valkey |
+| [timelineindexer-microservice-pilot.md](timelineindexer-microservice-pilot.md) | TimelineIndexer Valkey microservice transport pilot mapping and rollback |
+| [webservices-valkey-rollout-matrix.md](webservices-valkey-rollout-matrix.md) | All-webservices Valkey microservice migration matrix (waves, owners, rollback) |
+| [microservice-transport-guardrails.md](microservice-transport-guardrails.md) | Plugin-only transport guardrails and migration PR checklist |
+| [authority-gateway-enforcement-runbook.md](authority-gateway-enforcement-runbook.md) | Operations runbook for gateway-enforced auth and signed identity envelope trust |
+| [rollout-acceptance-20260222.md](rollout-acceptance-20260222.md) | Dual-mode rollout acceptance package and evidence index |

 ### Implementation Guides (docs/modules/router/guides/)
 | Document | Purpose |
--- a/docs/modules/router/authority-gateway-enforcement-runbook.md
+++ b/docs/modules/router/authority-gateway-enforcement-runbook.md
@@ -0,0 +1,81 @@
+# Router Authority Enforcement Runbook
+
+This runbook documents operational semantics for gateway-enforced authorization and signed user-identity propagation in Stella Router deployments.
+
+## Scope
+- Router gateway as centralized policy decision point (PDP).
+- Authority-driven effective claims.
+- Signed identity envelope propagation to webservices using Router trust mode.
+
+## Required Configuration
+
+Gateway-side:
+- `Gateway__Auth__Authority__Issuer`
+- `Gateway__Auth__Authority__RequireHttpsMetadata`
+- `Router__OnMissingAuthorization`
+
+Service-side (per service `Router` section):
+- `Router__Enabled`
+- `Router__AuthorizationTrustMode`
+- `Router__IdentityEnvelopeSigningKey`
+- `Router__IdentityEnvelopeClockSkewSeconds`
+
+Identity transport headers emitted by gateway:
+- `X-StellaOps-Identity-Envelope`
+- `X-StellaOps-Identity-Envelope-Signature`
+- `X-StellaOps-Identity-Envelope-Alg`
+- `X-StellaOps-Identity-Envelope-Kid`
+- `X-StellaOps-Identity-Envelope-Iat`
+- `X-StellaOps-Identity-Envelope-Exp`
+
+## Trust Modes
+
+`ServiceEnforced`
+- Service enforces its local policies.
+- Gateway envelope is optional for service authorization.
+
+`Hybrid`
+- Service accepts gateway envelope when present.
+- Service can fall back to local checks for compatibility.
+
+`GatewayEnforced`
+- Service requires valid signed gateway envelope.
+- Missing/invalid envelope is fail-closed (`403`/`401` based on service policy).
+- Use for centralized authorization rollout after verification.
+
+## Key Rotation Procedure
+1. Rotate Authority/gateway signing material using the Authority key-rotation SOP:
+- `docs/modules/authority/operations/key-rotation.md`
+2. Update `Router__IdentityEnvelopeSigningKey` for gateway and services.
+3. Restart gateway and services in wave order (gateway first).
+4. Validate with targeted tests and route smoke.
+
+## Authority Outage and Fallback
+
+If Authority is degraded/unreachable:
+1. Keep gateway running with last known effective claim cache.
+2. For critical service continuity, temporarily switch affected services:
+- `Router__AuthorizationTrustMode=Hybrid`
+3. If envelope verification is disrupted by key mismatch, switch to `ServiceEnforced` only as emergency fallback.
+4. Record incident window and restore target mode (`GatewayEnforced` or `Hybrid`) after recovery.
+
+## Compose Toggle Examples
+
+Global gateway mode:
+```powershell
+$env:ROUTER_GATEWAY_CONFIG = "./router-gateway-local.json"
+docker compose -f devops/compose/docker-compose.stella-ops.yml up -d
+```
+
+Emergency compatibility fallback (example service):
+```powershell
+$env:SCANNER_ROUTER_ENABLED = "true"
+$env:Router__AuthorizationTrustMode = "Hybrid"
+docker compose -f devops/compose/docker-compose.stella-ops.yml up -d scanner-web
+```
+
+## Verification Checklist
+- Gateway route smoke has `500=0`.
+- OpenAPI operations expose `x-stellaops-gateway-auth`.
+- Envelope spoofing tests pass (`IdentityHeaderPolicyMiddlewareTests`).
+- Authority refresh tests pass (`AuthorityClaimsRefreshServiceTests`).
--- a/docs/modules/router/messaging-valkey-transport.md
+++ b/docs/modules/router/messaging-valkey-transport.md
@@ -74,9 +74,14 @@ if (bootstrapOptions.Transports.Messaging.Enabled)
 ```

 ### Microservice
- Register Valkey messaging services (`StellaOps.Messaging.Transport.Valkey`)
- Add messaging transport client (`AddMessagingTransportClient`)
- Ensure Microservice Router SDK connects via `IMicroserviceTransport`
+- Register router transports via plugin loading (no hard transport references in `StellaOps.Router.AspNet`).
+- Use `AddRouterMicroservice(...)` from `StellaOps.Router.AspNet`; it resolves configured gateway transport types through `RouterTransportPluginLoader`.
+- For messaging mode, the `StellaOps.Router.Transport.Messaging` plugin registers:
+  - backend messaging plugin loading (`AddMessagingPlugins(...)`, env/config key `transport=valkey`)
+  - Router messaging transport client (`AddMessagingTransportClient`)
+- Ensure the following plugin DLLs are available either as service dependencies or under configured plugin directories:
+  - `StellaOps.Router.Transport.Messaging.dll`
+  - `StellaOps.Messaging.Transport.Valkey.dll`

 ## Operational Semantics (Draft)
 - **At-least-once** delivery: message queues and leases imply retries are possible; handlers should be idempotent where feasible.
@@ -104,4 +109,3 @@ if (bootstrapOptions.Transports.Messaging.Enabled)
   - microservice HELLO registration via messaging
   - request dispatch + response return
 3. Validate streaming support (or document as out-of-scope).
-
--- a/docs/modules/router/microservice-transport-guardrails.md
+++ b/docs/modules/router/microservice-transport-guardrails.md
@@ -0,0 +1,51 @@
+# 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.
+
+## Required Configuration Keys
+- `<Service>:Router:Enabled`
+- `<Service>:Router:Gateways:*:TransportType`
+- `<Service>:Router:TransportPlugins:Directory`
+- `<Service>:Router:TransportPlugins:SearchPattern`
+- `<Service>:Router:Messaging:Transport`
+- `<Service>:Router:Messaging:PluginDirectory`
+- `<Service>:Router:Messaging:SearchPattern`
+- `<Service>:Router:Messaging:RequestQueueTemplate`
+- `<Service>:Router:Messaging:ResponseQueueName`
+- `<Service>:Router:Messaging:ConsumerGroup`
+- `<Service>:Router:Messaging:valkey:ConnectionString`
+- `<Service>:Router:Messaging:valkey:Database`
+
+## Forbidden Patterns
+- Direct service-level DI calls to concrete transport registration methods such as:
+- `AddMessagingTransportClient()`
+- `AddTcpTransportClient()`
+- `AddUdpTransportClient()`
+- `AddRabbitMqTransportClient()`
+- `AddTlsTransportClient()`
+- 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.
+
+## Required Test Coverage
+- 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.
+
+## Migration PR Checklist
+- [ ] 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.
--- a/docs/modules/router/migration-guide.md
+++ b/docs/modules/router/migration-guide.md
@@ -12,6 +12,9 @@ The router provides a transport-agnostic communication layer between services, r
 - **Claims**: Authority-integrated authorization
 - **Health**: Automatic heartbeat and failover

+Active rollout planning artifact:
+- [webservices-valkey-rollout-matrix.md](webservices-valkey-rollout-matrix.md) - source-of-truth matrix for wave assignment, acceptance owners, and rollback switches for all gateway reverse-proxy service hosts.
+
 ## Prerequisites

 Before migrating, ensure:
--- a/docs/modules/router/openapi-aggregation.md
+++ b/docs/modules/router/openapi-aggregation.md
@@ -215,6 +215,14 @@ Client credentials flow with collected scopes (only if endpoints have claims):

 Scopes are automatically collected from all connected services. If multiple endpoints require the same claim, it appears only once in the scopes list.

+### Legacy HELLO Compatibility
+
+`x-stellaops-gateway-auth.requiresAuthentication` is emitted from the Gateway's effective authorization semantics, not only the raw endpoint flag.
+
+- If a microservice HELLO payload comes from an older router-common contract that does not include `requiresAuthentication`, the Gateway fails closed.
+- For `allowAnonymous: false` endpoints with no explicit auth flag, the Gateway treats the route as authenticated-only.
+- Public routes must be explicitly marked `AllowAnonymous` in the microservice to avoid accidental protection.
+
 ---

 ## Generated Document Structure
--- a/docs/modules/router/rollout-acceptance-20260222.md
+++ b/docs/modules/router/rollout-acceptance-20260222.md
@@ -0,0 +1,78 @@
+# Router Rollout Acceptance Package (2026-02-22)
+
+## Scope
+- Program closeout for Router sprints `047-050`.
+- Dual-mode verification:
+- Default microservice mode (`router-gateway-local.json`).
+- Reverse-proxy fallback mode (`router-gateway-local.reverseproxy.json`).
+
+## Command Matrix
+- Image refresh:
+- `docker build ... -t stellaops/scanner-web:dev`
+- `docker build ... -t stellaops/integrations-web:dev`
+- `docker build ... -t stellaops/gateway:dev`
+- `docker build ... -t stellaops/doctor-web:dev`
+- Clean bootstrap:
+- `devops/compose/scripts/router-mode-redeploy.ps1 -Mode reverseproxy`
+- `devops/compose/scripts/router-mode-redeploy.ps1 -Mode microservice`
+- Route smoke:
+- `devops/compose/scripts/router-routeprefix-smoke.ps1`
+- Conformance tests:
+- `dotnet test src/Router/__Tests/StellaOps.Router.AspNet.Tests/StellaOps.Router.AspNet.Tests.csproj`
+- `dotnet test src/Router/__Tests/StellaOps.Router.Gateway.Tests/StellaOps.Router.Gateway.Tests.csproj`
+- `dotnet test src/Router/__Tests/StellaOps.Gateway.WebService.Tests/StellaOps.Gateway.WebService.Tests.csproj`
+
+## Evidence Artifacts
+- `devops/compose/openapi_current.json`
+- `devops/compose/openapi_reverse.json`
+- `devops/compose/openapi_routeprefix_smoke_microservice.csv`
+- `devops/compose/openapi_routeprefix_smoke_reverseproxy.csv`
+- `devops/compose/openapi_quality_report_microservice.json`
+- `devops/compose/openapi_quality_report_reverseproxy.json`
+- `devops/compose/perf_microservice.json`
+- `devops/compose/perf_reverseproxy.json`
+- `devops/compose/perf_mode_comparison.json`
+- `devops/compose/timeline.json`
+- `devops/compose/timeline_schemas.json`
+- `devops/compose/openai_adapter.json`
+- `devops/compose/llm_providers.json`
+
+## Acceptance Results
+
+Microservice mode:
+- Route smoke summary: `200=30,302=4,400=25,401=14,403=2,404=3,410=1`
+- Route smoke blocker status: `500=0`
+- OpenAPI counts: `paths=1899`, `schemas=901`
+- Timeline contract gate: 4 timeline operations with summary/description/security/timeouts/auth extensions.
+- Advisory AI adapter exposure: 2 LLM adapter operations in aggregated `openapi.json`; providers endpoint denies anonymous access (`403`).
+
+Reverse mode:
+- Route smoke summary: `200=15,400=6,401=18,404=15`
+- Route smoke blocker status: `500=0`
+- OpenAPI counts: `paths=1529`, `schemas=901`
+- Reverse-proxy exception set remains explicit (`/rekor`, `/platform`, static SPA/error routes).
+
+Security and authorization:
+- Gateway and Router conformance suites pass.
+- Identity-header spoofing protections covered in gateway test suite.
+- Authority claims refresh and effective-claim integration covered in Router gateway tests.
+
+## Performance Gate Decision
+- Baseline: reverse-proxy mode.
+- Candidate: microservice mode.
+- Comparison artifact: `devops/compose/perf_mode_comparison.json`.
+- Result:
+- `openapi.json` and timeline unauthorized path remained within acceptable local-dev drift.
+- Advisory AI adapter unauthorized path showed higher latency in microservice mode; accepted for now as non-blocking because error-rate and contract gates passed, with follow-up hardening item retained in Router backlog.
+
+## Rollback
+- Scripted mode rollback:
+- `devops/compose/scripts/router-mode-redeploy.ps1 -Mode reverseproxy`
+- Return to default:
+- `devops/compose/scripts/router-mode-redeploy.ps1 -Mode microservice`
+- The redeploy helper now auto-recovers transient unhealthy services (bounded retries) before declaring failure.
+
+## Final Runtime State
+- Default compose mode restored to microservice routing:
+- `ROUTER_GATEWAY_CONFIG=./router-gateway-local.json`
+- Timeline route `/api/v1/timeline` remains `Type=Microservice` with Valkey messaging transport.
--- a/docs/modules/router/timelineindexer-microservice-pilot.md
+++ b/docs/modules/router/timelineindexer-microservice-pilot.md
@@ -0,0 +1,39 @@
+# Router TimelineIndexer Microservice Pilot
+
+## Scope
+- Pilot service: `TimelineIndexer` (`src/TimelineIndexer/StellaOps.TimelineIndexer/StellaOps.TimelineIndexer.WebService`).
+- Transport: `TransportType.Messaging` backed by Valkey.
+- Gateway entry under pilot: `/api/v1/timeline*`.
+
+## Baseline
+- Previous gateway route:
+- `ReverseProxy /api/v1/timeline -> http://timelineindexer.stella-ops.local/api/v1/timeline`
+- Reverse proxy mode strips the matched prefix before forwarding.
+- Microservice mode does not strip prefixes and routes by method+path identity.
+
+## Path Compatibility Mapping
+| External path | Reverse proxy behavior | Required microservice path | Pilot status |
+| --- | --- | --- | --- |
+| `/api/v1/timeline` | proxied to `/api/v1/timeline` upstream | `/api/v1/timeline` | converted |
+| `/api/v1/timeline/{eventId}` | proxied to `/api/v1/timeline/{eventId}` upstream | `/api/v1/timeline/{eventId}` | converted |
+| `/api/v1/timeline/{eventId}/evidence` | proxied to `/api/v1/timeline/{eventId}/evidence` upstream | `/api/v1/timeline/{eventId}/evidence` | converted |
+| `/api/v1/timeline/events` | proxied to `/api/v1/timeline/events` upstream | `/api/v1/timeline/events` | converted |
+| `/timelineindexer/*` | reverse-proxy prefix path for direct service access | unchanged (still reverse proxy) | unchanged |
+
+TimelineIndexer now exposes both native and gateway-alias endpoints:
+- native: `/timeline*`
+- gateway alias: `/api/v1/timeline*`
+
+## Compose Activation
+- Gateway messaging toggle: `ROUTER_GATEWAY_MESSAGING_ENABLED` (default `true`).
+- TimelineIndexer router toggle: `TIMELINE_ROUTER_ENABLED` (default `true`).
+- Compose env vars are applied on `timeline-indexer-web` (not `vexlens-web`) and mapped to:
+- `TimelineIndexer:Router`
+- `TimelineIndexer:Router:TransportPlugins:*`
+- `TimelineIndexer:Router:Messaging:*`
+- Valkey backend selection is environment-driven via `TimelineIndexer:Router:Messaging:Transport=valkey`.
+
+## Rollback
+1. Set `TIMELINE_ROUTER_ENABLED=false` and `ROUTER_GATEWAY_MESSAGING_ENABLED=false` in compose environment.
+2. Revert route entry in `devops/compose/router-gateway-local.json` from `Microservice` back to `ReverseProxy`.
+3. Re-deploy stack and verify `/api/v1/timeline*` responses through reverse proxy path.
--- a/docs/modules/router/webservice-integration-guide.md
+++ b/docs/modules/router/webservice-integration-guide.md
@@ -48,6 +48,94 @@ builder.Services.TryAddStellaRouter(
    routerOptions: options.Router);
 ```

+#### Optional: generic microservice transport registration
+
+For services that should auto-register transport clients from configuration, use:
+
+```csharp
+builder.Services.AddRouterMicroservice(
+    builder.Configuration,
+    serviceName: "my-service-name",
+    version: typeof(Program).Assembly.GetName().Version?.ToString() ?? "1.0.0",
+    routerOptionsSection: "MyService:Router");
+```
+
+`AddRouterMicroservice(...)` keeps `TryAddStellaRouter(...)` behavior and registers transport clients through `RouterTransportPluginLoader` based on configured gateway transport types (`InMemory`, `Tcp`, `Certificate`/`tls`, `Udp`, `RabbitMq`, `Messaging`).  
+The `StellaOps.Router.AspNet` library does not hard-reference transport assemblies; transports are activated from plugin DLLs and environment/config values.
+
+For Valkey messaging mode, configure:
+
+```yaml
+myservice:
+  router:
+    enabled: true
+    region: "local"
+    transportPlugins:
+      directory: "plugins/router/transports"
+      searchPattern: "StellaOps.Router.Transport.*.dll"
+    gateways:
+      - host: "router.stella-ops.local"
+        port: 9100
+        transportType: "Messaging"
+    messaging:
+      transport: "valkey"
+      pluginDirectory: "plugins/messaging"
+      searchPattern: "StellaOps.Messaging.Transport.*.dll"
+      requestQueueTemplate: "router:requests:{service}"
+      responseQueueName: "router:responses"
+      consumerGroup: "myservice"
+      requestTimeout: "30s"
+      leaseDuration: "5m"
+      batchSize: 10
+      heartbeatInterval: "10s"
+      valkey:
+        connectionString: "cache.stella-ops.local:6379"
+```
+
+### 2.2 Gateway trust mode and identity envelope verification
+
+Service-side Router bridge can enforce gateway-issued identity semantics:
+
+```yaml
+myservice:
+  router:
+    authorizationTrustMode: "GatewayEnforced" # ServiceEnforced | Hybrid | GatewayEnforced
+    identityEnvelopeSigningKey: "${ROUTER_IDENTITY_SIGNING_KEY}"
+    identityEnvelopeClockSkewSeconds: 30
+```
+
+- `ServiceEnforced`: service-local checks remain primary.
+- `Hybrid`: prefer signed envelope; fallback to legacy headers.
+- `GatewayEnforced`: fail closed when envelope is missing/invalid.
+
+### 2.3 Timeout precedence
+
+Gateway dispatch timeout is now resolved with explicit precedence:
+
+1. Endpoint timeout (including endpoint override/service default published by service).
+2. Route default timeout (optional per gateway route via `defaultTimeout`).
+3. Gateway routing default timeout (`Gateway:Routing:DefaultTimeout`).
+4. Global gateway cap (`Gateway:Routing:GlobalTimeoutCap`).
+
+Route-level timeout example:
+
+```yaml
+gateway:
+  routing:
+    defaultTimeout: "30s"
+    globalTimeoutCap: "120s"
+  routes:
+    - type: Microservice
+      path: "/api/v1/timeline"
+      translatesTo: "http://timelineindexer.stella-ops.local/api/v1/timeline"
+      defaultTimeout: "15s"
+```
+
+### 2.1 Gateway SPA deep-link handling with microservice routes
+
+When gateway route prefixes overlap with UI routes (for example `/policy`), browser navigations must still resolve to the SPA shell.  
+Gateway `RouteDispatchMiddleware` now serves the configured static SPA fallback route for browser document requests on both `ReverseProxy` and `Microservice` route types. API prefixes (`/api`, `/v1`) are explicitly excluded from this fallback and continue to dispatch to backend services.
+
 ### 3. Enable Middleware

 After `UseAuthorization()`, add:
--- a/docs/modules/router/webservices-valkey-rollout-matrix.md
+++ b/docs/modules/router/webservices-valkey-rollout-matrix.md
@@ -0,0 +1,75 @@
+# Router Valkey Microservice Rollout Matrix (All WebServices)
+
+## Scope
+- Source route table: `devops/compose/router-gateway-local.json`
+- Source service aliases: `devops/compose/docker-compose.stella-ops.yml`
+- Snapshot date (UTC): 2026-02-21
+- ReverseProxy routes in snapshot: 116
+- Distinct target service hosts: 42
+
+Legend:
+- `Wave`: `A`, `B`, `C`, `D`, `PILOT`
+- `Acceptance Owner`: rollout sign-off owner for that host's cutover wave
+- `Migration Disposition`: current route-level migration intent
+
+## Service Migration Matrix
+
+| Service Host | Compose Service | Current ReverseProxy Path Prefixes | Wave | Acceptance Owner | Migration Disposition | Rollback Switch |
+| --- | --- | --- | --- | --- | --- | --- |
+| advisoryai.stella-ops.local | advisory-ai-web | /advisoryai, /api/v1/advisory, /api/v1/advisory-ai, /api/v1/advisory-ai/adapters, /v1/advisory-ai, /v1/advisory-ai/adapters | A | Developer + Test Automation (Wave A) | Migrate API prefixes to Microservice; keep root compatibility path until cutover acceptance. | Route type revert in `router-gateway-local.json` + `ADVISORYAI_ROUTER_ENABLED=false` (standardized in RMW-03). |
+| airgap-controller.stella-ops.local | airgap-controller | /airgapController | A | Developer + Test Automation (Wave A) | Add API-form microservice endpoint mapping and migrate root compatibility path in same wave. | Route type revert + `AIRGAP_CONTROLLER_ROUTER_ENABLED=false` (RMW-03). |
+| airgap-time.stella-ops.local | airgap-time | /airgapTime | A | Developer + Test Automation (Wave A) | Add API-form microservice endpoint mapping and migrate root compatibility path in same wave. | Route type revert + `AIRGAP_TIME_ROUTER_ENABLED=false` (RMW-03). |
+| attestor.stella-ops.local | attestor | /api/v1/attestations, /api/v1/attestor, /api/v1/witnesses, /attestor | B | Developer + Test Automation (Wave B) | Migrate API prefixes first; keep root compatibility route until evidence-plane acceptance sign-off. | Route type revert + `ATTESTOR_ROUTER_ENABLED=false` (RMW-03). |
+| authority.stella-ops.local | authority | /.well-known, /api/v1/authority, /api/v1/trust, /authority, /connect, /console, /jwks | B | Developer + Test Automation (Wave B) | Migrate Authority API and OIDC identity routes to Microservice; use in-service OIDC bridge endpoints (`/connect/*`, `/well-known/openid-configuration`) for protocol compatibility. | Route type revert + `AUTHORITY_ROUTER_ENABLED=false` (RMW-03). |
+| binaryindex.stella-ops.local | binaryindex-web | /api/v1/ops/binaryindex, /api/v1/resolve, /binaryindex | A | Developer + Test Automation (Wave A) | Migrate API prefixes to Microservice; keep root compatibility path during transition. | Route type revert + `BINARYINDEX_ROUTER_ENABLED=false` (RMW-03). |
+| cartographer.stella-ops.local | cartographer | /cartographer | D | Developer + Test Automation (Wave D) | Introduce API alias if required, then migrate route to Microservice in Wave D. | Route type revert + `CARTOGRAPHER_ROUTER_ENABLED=false` (RMW-03). |
+| concelier.stella-ops.local | concelier | /api/v1/concelier, /concelier | D | Developer + Test Automation (Wave D) | Migrate API prefix first, then root compatibility route. | Route type revert + `CONCELIER_ROUTER_ENABLED=false` (RMW-03). |
+| doctor.stella-ops.local | doctor-web | /api/doctor, /doctor | D | Developer + Test Automation (Wave D) | Migrate API prefix first; keep root compatibility path until UI/runtime consumers are validated. | Route type revert + `DOCTOR_ROUTER_ENABLED=false` (RMW-03). |
+| doctor-scheduler.stella-ops.local | doctor-scheduler | /api/v1/doctor/scheduler | D | Developer + Test Automation (Wave D) | Migrate API prefix directly to Microservice. | Route type revert + `DOCTOR_SCHEDULER_ROUTER_ENABLED=false` (RMW-03). |
+| evidencelocker.stella-ops.local | evidence-locker-web | /api/v1/evidence, /api/v1/proofs, /api/v1/verdicts, /api/verdicts, /evidencelocker, /v1/evidence-packs | B | Developer + Test Automation (Wave B) | Migrate API/v1 and v1 endpoints first; keep root compatibility path until evidence workflows pass QA. | Route type revert + `EVIDENCELOCKER_ROUTER_ENABLED=false` (RMW-03). |
+| excititor.stella-ops.local | excititor | /excititor | D | Developer + Test Automation (Wave D) | Add API-form microservice mapping if needed; migrate root compatibility route in Wave D. | Route type revert + `EXCITITOR_ROUTER_ENABLED=false` (RMW-03). |
+| exportcenter.stella-ops.local | export | /api/v1/export, /exportcenter, /v1/audit-bundles | B | Developer + Test Automation (Wave B) | Migrate API/v1 and v1 routes first; keep root compatibility path until trust/evidence export checks pass. | Route type revert + `EXPORTCENTER_ROUTER_ENABLED=false` (RMW-03). |
+| findings.stella-ops.local | findings-ledger-web | /api/v1/findings, /findingsLedger | D | Developer + Test Automation (Wave D) | Migrate API prefix first, then root compatibility path. | Route type revert + `FINDINGS_ROUTER_ENABLED=false` (RMW-03). |
+| gateway.stella-ops.local | gateway | /gateway | D | Developer + Test Automation (Wave D) | Defer root compatibility path until downstream service migration waves are complete. | Route type revert + `GATEWAY_ROUTER_ENABLED=false` (RMW-03). |
+| integrations.stella-ops.local | integrations-web | /api/v1/integrations, /integrations | A | Developer + Test Automation (Wave A) | Migrate API prefix first, then root compatibility path. | Route type revert + `INTEGRATIONS_ROUTER_ENABLED=false` (RMW-03). |
+| issuerdirectory.stella-ops.local | issuer-directory | /issuerdirectory | B | Developer + Test Automation (Wave B) | Migrate route in trust-plane wave with issuer/auth verification checks. | Route type revert + `ISSUERDIRECTORY_ROUTER_ENABLED=false` (RMW-03). |
+| notifier.stella-ops.local | notifier-web | /api/v1/notifier, /notifier | D | Developer + Test Automation (Wave D) | Migrate API prefix first, then root compatibility path. | Route type revert + `NOTIFIER_ROUTER_ENABLED=false` (RMW-03). |
+| notify.stella-ops.local | notify-web | /api/v1/notify, /notify | D | Developer + Test Automation (Wave D) | Migrate API prefix first, then root compatibility path. | Route type revert + `NOTIFY_ROUTER_ENABLED=false` (RMW-03). |
+| opsmemory.stella-ops.local | opsmemory-web | /api/v1/opsmemory, /opsmemory | A | Developer + Test Automation (Wave A) | Migrate API prefix first, then root compatibility path. | Route type revert + `OPSMEMORY_ROUTER_ENABLED=false` (RMW-03). |
+| orchestrator.stella-ops.local | orchestrator | /api/approvals, /api/orchestrator, /api/release-orchestrator, /api/releases, /api/v1/orchestrator, /api/v1/release-orchestrator, /api/v1/workflows, /orchestrator, /v1/runs | C | Developer + Test Automation (Wave C) | Migrate all API/v1 and v1 routes first; keep root compatibility path until control-plane acceptance. | Route type revert + `ORCHESTRATOR_ROUTER_ENABLED=false` (RMW-03). |
+| packsregistry.stella-ops.local | packsregistry-web | /packsregistry | A | Developer + Test Automation (Wave A) | Add API-form endpoint mapping if required, then migrate root compatibility route. | Route type revert + `PACKSREGISTRY_ROUTER_ENABLED=false` (RMW-03). |
+| platform.stella-ops.local | platform | /api, /api/admin, /api/analytics, /api/v1/authority/quotas, /api/v1/gateway/rate-limits, /api/v1/platform, /envsettings.json, /platform | C | Developer + Test Automation (Wave C) | Migrate API prefixes to Microservice; keep `/platform` and `/envsettings.json` reverse proxy for static/bootstrap behavior. | Route type revert + `PLATFORM_ROUTER_ENABLED=false` (RMW-03). |
+| policy-engine.stella-ops.local | policy-engine | /api/risk, /api/risk-budget, /api/v1/determinization, /policyEngine | C | Developer + Test Automation (Wave C) | Migrate API prefixes first; keep root compatibility path until control-plane verification completes. | Route type revert + `POLICY_ENGINE_ROUTER_ENABLED=false` (RMW-03). |
+| policy-gateway.stella-ops.local | policy | /api/cvss, /api/exceptions, /api/gate, /api/policy, /api/v1/governance, /api/v1/policy, /policy, /policyGateway | C | Developer + Test Automation (Wave C) | Migrate API prefixes first; keep `/policy` and `/policyGateway` compatibility paths until final cutover. | Route type revert + `POLICY_GATEWAY_ROUTER_ENABLED=false` (RMW-03). |
+| reachgraph.stella-ops.local | reachgraph-web | /api/v1/reachability, /reachgraph | D | Developer + Test Automation (Wave D) | Migrate API prefix first, then root compatibility path. | Route type revert + `REACHGRAPH_ROUTER_ENABLED=false` (RMW-03). |
+| registry-token.stella-ops.local | registry-token | /registryTokenservice | A | Developer + Test Automation (Wave A) | Migrate compatibility route with token flow validation in Wave A. | Route type revert + `REGISTRY_TOKEN_ROUTER_ENABLED=false` (RMW-03). |
+| replay.stella-ops.local | replay-web | /replay | A | Developer + Test Automation (Wave A) | Migrate compatibility route in Wave A; add API-form alias if needed. | Route type revert + `REPLAY_ROUTER_ENABLED=false` (RMW-03). |
+| riskengine.stella-ops.local | riskengine-web | /riskengine | C | Developer + Test Automation (Wave C) | Migrate compatibility route in control-plane wave; add API alias if required. | Route type revert + `RISKENGINE_ROUTER_ENABLED=false` (RMW-03). |
+| sbomservice.stella-ops.local | sbomservice | /api/change-traces, /api/compare, /api/sbomservice, /api/v1/lineage, /api/v1/sbom, /api/v1/sources, /sbomservice | D | Developer + Test Automation (Wave D) | Migrate API prefixes first; keep root compatibility path until graph/feed wave acceptance. | Route type revert + `SBOMSERVICE_ROUTER_ENABLED=false` (RMW-03). |
+| scanner.stella-ops.local | scanner-web | /api/fix-verification, /api/v1/scanner, /api/v1/secrets, /api/v1/triage, /api/v1/vulnerabilities, /api/v1/watchlist, /scanner | D | Developer + Test Automation (Wave D) | Migrate API prefixes first; keep root compatibility path until scanner behavioral checks pass. | Route type revert + `SCANNER_ROUTER_ENABLED=false` (RMW-03). |
+| scheduler.stella-ops.local | scheduler-web | /api/scheduler, /scheduler | C | Developer + Test Automation (Wave C) | Migrate API prefix first, then root compatibility path. | Route type revert + `SCHEDULER_ROUTER_ENABLED=false` (RMW-03). |
+| signals.stella-ops.local | signals | /api/v1/signals, /signals | D | Developer + Test Automation (Wave D) | Migrate API prefix first, then root compatibility path. | Route type revert + `SIGNALS_ROUTER_ENABLED=false` (RMW-03). |
+| signer.stella-ops.local | signer | /signer | B | Developer + Test Automation (Wave B) | Migrate compatibility route in trust/evidence wave with signing validation. | Route type revert + `SIGNER_ROUTER_ENABLED=false` (RMW-03). |
+| smremote.stella-ops.local | smremote | /smremote | A | Developer + Test Automation (Wave A) | Migrate compatibility route in Wave A; add API alias if required. | Route type revert + `SMREMOTE_ROUTER_ENABLED=false` (RMW-03). |
+| symbols.stella-ops.local | symbols | /symbols | A | Developer + Test Automation (Wave A) | Migrate compatibility route in Wave A; add API alias if required. | Route type revert + `SYMBOLS_ROUTER_ENABLED=false` (RMW-03). |
+| taskrunner.stella-ops.local | taskrunner-web | /taskrunner | C | Developer + Test Automation (Wave C) | Migrate compatibility route in control-plane wave; add API alias if required. | Route type revert + `TASKRUNNER_ROUTER_ENABLED=false` (RMW-03). |
+| timelineindexer.stella-ops.local | timeline-indexer-web | /timelineindexer | PILOT | Developer (pilot accepted) | Timeline API is already microservice (`/api/v1/timeline`); keep root compatibility route reverse proxy until later cleanup. | Route type revert + `TIMELINE_ROUTER_ENABLED=false` (already supported). |
+| unknowns.stella-ops.local | unknowns-web | /unknowns | A | Developer + Test Automation (Wave A) | Migrate compatibility route in Wave A; add API alias if required. | Route type revert + `UNKNOWNS_ROUTER_ENABLED=false` (RMW-03). |
+| vexhub.stella-ops.local | vexhub-web | /api/v1/vex, /api/vex, /vexhub | D | Developer + Test Automation (Wave D) | Migrate API prefixes first, then root compatibility path. | Route type revert + `VEXHUB_ROUTER_ENABLED=false` (RMW-03). |
+| vexlens.stella-ops.local | vexlens-web | /api/v1/vexlens, /vexlens | D | Developer + Test Automation (Wave D) | Migrate API prefix first, then root compatibility path. | Route type revert + `VEXLENS_ROUTER_ENABLED=false` (RMW-03). |
+| vulnexplorer.stella-ops.local | api | /api/vuln-explorer, /vulnexplorer | D | Developer + Test Automation (Wave D) | Migrate API prefix first; keep root compatibility path until vuln explorer routing is validated. | Route type revert + `VULNEXPLORER_ROUTER_ENABLED=false` (RMW-03). |
+
+## Wave Acceptance Mapping
+
+| Wave | Acceptance Owner |
+| --- | --- |
+| A | Developer + Test Automation (Wave A) |
+| B | Developer + Test Automation (Wave B) |
+| C | Developer + Test Automation (Wave C) |
+| D | Developer + Test Automation (Wave D) |
+| PILOT | Developer (pilot accepted) |
+
+## Notes
+- This matrix is the authoritative inventory artifact for sprint task `RMW-01`.
+- Route-level rollback is always available by reverting route `Type` back to `ReverseProxy` in `devops/compose/router-gateway-local.json`.
+- Service env rollback keys are currently planning placeholders and are standardized in `RMW-03`.
--- a/docs/modules/timeline-indexer/architecture.md
+++ b/docs/modules/timeline-indexer/architecture.md
@@ -59,9 +59,16 @@ src/TimelineIndexer/StellaOps.TimelineIndexer/
 ## 4) REST API

 ```
-GET  /timeline?subject={id}&from={date}&to={date}  → { events[] }
-GET  /timeline/{eventId}                            → { event }
-GET  /timeline/stats?subject={id}                   → { statistics }
+GET  /timeline?eventType=&source=&correlationId=&traceId=&severity=&since=&after=&limit=
+GET  /timeline/{eventId}
+GET  /timeline/{eventId}/evidence
+POST /timeline/events
+
+# Gateway microservice aliases
+GET  /api/v1/timeline
+GET  /api/v1/timeline/{eventId}
+GET  /api/v1/timeline/{eventId}/evidence
+POST /api/v1/timeline/events

 GET  /healthz | /readyz | /metrics
 ```
@@ -72,3 +79,5 @@ GET  /healthz | /readyz | /metrics

 * Signals: `../signals/architecture.md`
 * Scanner: `../scanner/architecture.md`
+
+
--- a/docs/modules/timeline-indexer/guides/timeline.md
+++ b/docs/modules/timeline-indexer/guides/timeline.md
@@ -29,9 +29,16 @@ Events are stored append-only with tenant-specific partitions. Producers include

 ## 2. APIs

- `GET /api/v1/timeline/events` – paginated event stream with filters (tenant, category, time window, correlation IDs).
- `GET /api/v1/timeline/events/{id}` – fetch single event payload.
- `GET /api/v1/timeline/export` – NDJSON export for offline review.
+- Native endpoints:
+- `GET /timeline` - query timeline entries with filter parameters.
+- `GET /timeline/{eventId}` - fetch a single timeline entry.
+- `GET /timeline/{eventId}/evidence` - fetch evidence linked to a timeline entry.
+- `POST /timeline/events` - ingestion ack endpoint.
+- Router/Gateway aliases for microservice transport routing:
+- `GET /api/v1/timeline`
+- `GET /api/v1/timeline/{eventId}`
+- `GET /api/v1/timeline/{eventId}/evidence`
+- `POST /api/v1/timeline/events`

 API headers: `X-Stella-Tenant`, optional `X-Stella-TraceId`, and `If-None-Match` for cache revalidation.

@@ -73,3 +80,4 @@ Privacy/PII: producers must redact PII before emission; once emitted, redactions
 - `docs/modules/zastava/architecture.md`
 - `docs/modules/export-center/architecture.md`
 - `src/TimelineIndexer/StellaOps.TimelineIndexer`
+