Advisory AI architecture

Captures the retrieval, guardrail, and inference packaging requirements defined in the Advisory AI implementation plan and related module guides. Configuration knobs (inference modes, guardrails, cache/queue budgets) now live in docs/modules/policy/guides/assistant-parameters.mdper DOCS-AIAI-31-006.

This dossier describes the CONSOLIDATED family only. The predecessor deployables advisory-ai-web, advisory-ai-worker and opsmemory-web were retired on 2026-09-07 (SPRINT_20260722_013 AAI-10) after the AAI-9 data-move window of 2026-09-04 put the family live on its own database. What runs is advisoryai-web + advisoryai-worker, two replica roles of one deployable family on stellaops_advisoryai, composed from devops/compose/docker-compose.advisoryai.yml.

Verified against commit 79bf4c6f36 (the retirement) plus live probes taken 2026-09-07 on the running estate. Re-verify with:

docker inspect stellaops-advisoryai-web stellaops-advisoryai-worker --format '{{.Name}} {{.Image}} {{.State.Health.Status}} restarts={{.RestartCount}}'
docker exec stellaops-advisoryai-web sh -lc 'cat /app/buildinfo.json'
rg -n "^  advisoryai-(web|worker):" devops/compose/docker-compose.advisoryai.yml

At that stamp both containers were healthy with RestartCount=0 on images sha256:d423274f669b… and sha256:4fadbb883b7c…, built from gitSha 3c938e875f… with worktreeState clean.

Tenant identity (claim-bound). The family ships one host with an inbound API surface, and it takes the data-isolation tenant from the authenticated stellaops:tenant claim. A caller-supplied tenant is never an isolation key — it is the cross-tenant vector, not a safety property.

• advisoryai-web (StellaOps.AdvisoryAI.WebService) — envelope-only. Identity resolves exclusively from the gateway-signed identity envelope; InboundIdentityHeaderStripMiddleware strips X-Tenant-Id-style headers at ingress before UseAuthentication(), and the legacy AdvisoryAiHeaderAuthenticationHandler has been deleted (see §7.5). The lifted OpsMemory routes ride that same stack: the /api/v1/opsmemory and /api/advisoryai/v1/opsmemory groups carry .RequireTenant() and every handler isolates on the claim resolved by OpsMemoryTenantResolver. The tenantId query parameter and the RecordDecisionRequest.TenantId body field are optional conflict checks only: disagreeing with the claim is 400 tenant_conflict, and an identity with no tenant is 400 tenant_missing (see §15, “Tenancy contract”).

Landed in Sprint SPRINT_20260712_001 (TEN-1). Before it, OpsMemory endpoints passed the caller’s tenantId straight to PostgresOpsMemoryStore as the sole isolation key and never consulted the claim — on the compose bypass networks that was an unauthenticated cross-tenant read/write. The guarantee is now asserted on the consolidated host by StellaOps.AdvisoryAI.Tests.Integration.AdvisoryAiOpsMemoryTenancyTests (15 facts, all six routes, read and write paths, both roots). The library-level guard in Playbook/PlaybookSuggestionService (throws when handed a blank tenant; the legacy shared-"default" fallback is gone) is defence-in-depth for internal callers of the library — the value the endpoints hand it is always the claim tenant.

1) Goals

• Summarise advisories/VEX evidence into operator-ready briefs with citations.
• Explain conflicting statements with provenance and trust weights (using VEX Lens & Excititor data).
• Suggest remediation plans aligned with Offline Kit deployment models and scheduler follow-ups.
• Operate deterministically where possible; cache generated artefacts with digests for audit.

2) Pipeline overview

                       +---------------------+
   Concelier/VEX Lens  |  Evidence Retriever |
   Policy Engine ----> |  (vector + keyword) | ---> Context Pack (JSON)
   Zastava runtime     +---------------------+
                               |
                               v
                        +-------------+
                        | Prompt      |
                        | Assembler   |
                        +-------------+
                               |
                               v
                        +-------------+
                        | Guarded LLM |
                        | (local/host)|
                        +-------------+
                               |
                               v
                        +-----------------+
                        | Citation &     |
                        | Validation      |
                        +-----------------+
                               |
                               v
                        +----------------+
                        | Output cache   |
                        | (hash, bundle) |
                        +----------------+

3) Retrieval & context

• Hybrid search: vector embeddings (SBERT-compatible) + keyword filters for advisory IDs, PURLs, CVEs.

• Context packs include:

  • Advisory raw excerpts with highlighted sections and source URLs.
  • VEX statements (normalized tuples + trust metadata).
  • Policy explain traces for the affected finding.
  • Runtime/impact hints from Zastava (exposure, entrypoints).
  • Export-ready remediation data (fixed versions, patches).

• SBOM context retriever (AIAI-31-002) hydrates:

  • Version timelines (first/last observed, status, fix availability).
  • Dependency paths (runtime vs build/test, deduped by coordinate chain).
  • Tenant environment flags (prod/stage toggles) with optional blast radius summary.
  • Service-side clamps: max 500 timeline entries, 200 dependency paths, with client-provided toggles for env/blast data.
  • AddSbomContext(...) (SbomContextServiceCollectionExtensions) registers the typed ISbomContextClient HTTP client (SbomContextHttpClient) that calls the SBOM service. ISbomContextRetriever.RetrieveAsync is the in-process retriever entry point that wraps it. A NullSbomContextClient exists for harness/no-op scenarios.

  Sample configuration (wire the real SBOM base URL via SbomContextClientOptions):

  services.AddSbomContext(options =>
  {
      options.BaseAddress = new Uri("https://sbom-service.internal");
      options.ContextEndpoint = "api/sbom/context"; // default
      options.Tenant = configuration["TENANT_ID"];
      options.TenantHeaderName = "X-StellaOps-TenantId"; // default
  });
  

  Note: SbomContextClientOptions exposes only BaseAddress, ContextEndpoint, Tenant, and TenantHeaderName. It has no API-key / user-agent fields; outbound auth to internal services is supplied by the Authority client_credentials bearer (see §7.6). In hosted deployments the SBOM base address is normally set through AdvisoryAI:SbomBaseAddress and AddAdvisoryAiCore rather than a manual AddSbomContext call.

  After configuration, issue a smoke request (ISbomContextRetriever.RetrieveAsync) during deployment validation to confirm end-to-end connectivity before enabling Advisory AI endpoints.

Retriever requests and results are trimmed/normalized before hashing; metadata (counts, provenance keys) is returned for downstream guardrails. Unit coverage ensures deterministic ordering and flag handling.

All context references include content_hash and source_id enabling verifiable citations.

4) Guardrails

• Prompt templates enforce structure: summary, conflicts, remediation, references.
• Response validator ensures:
  • No hallucinated advisories (every fact must map to input context).
  • Chat citations use stable CIT-##-<hash> identifiers that reference actual source snippets and content hashes.
  • Remediation suggestions only cite policy-approved sources (fixed versions, vendor hotfixes).
• Moderation/PII filters prevent leaking secrets; responses failing validation are rejected and logged. Chat inference rejects invalid JSON, unknown citation IDs, and factual claims without citations.
• Pre-flight guardrails redact secrets (AWS keys, generic API tokens, PEM blobs), block “ignore previous instructions”-style prompt injection attempts, enforce citation presence, and cap prompt payload length (default 16 kB). Guardrail outcomes and validation failures surface via the advisory_ai_guardrail_blocks_total and advisory_ai_validation_failures_total counters (with advisory_outputs_stored recording a guardrail_blocked flag); all carry a task_type dimension. See §9 for the full meter inventory.

5) Deterministic tooling

• Version comparators — offline semantic version + RPM EVR parsers with range evaluators. Supports chained constraints (>=, <=, !=) used by remediation advice and blast radius calcs.
  • Registered via AddAdvisoryDeterministicToolset for reuse across orchestrator, CLI, and services.
• Orchestration pipeline — see orchestration-pipeline.md for prerequisites, task breakdown, and cross-guild responsibilities before wiring the execution flows.
• Planned extensions — NEVRA/EVR comparators, ecosystem-specific normalisers, dependency chain scorers (AIAI-31-003 scope).
• Exposed via internal interfaces to allow jobengine/toolchain reuse; all helpers stay side-effect free and deterministic for golden testing.

6) Output persistence

• Generated outputs are persisted by the file-backed FileSystemAdvisoryOutputStore (the default IAdvisoryOutputStore), partitioned by cache key / task type / profile under the outputs data root — there is no advisory_ai_outputs SQL table. Each artefact carries:
  • output_hash (sha256 of JSON response).
  • input_digest (hash of context pack).
  • summary, conflicts, remediation, citations.
  • generated_at, model_id, profile (free-form label; see §7).
  • signatures (optional DSSE if run in deterministic mode).
• Offline bundle format contains summary.md, citations.json, context_manifest.json, signatures/.
• Consolidated PostgreSQL database (auto-migrated). Current source embeds the immutable 001_advisoryai_consolidated_baseline.sql plus forward migrations under src/AdvisoryAI/__Libraries/StellaOps.AdvisoryAI.Persistence/Migrations/, all under one advisoryai.schema_migrations authority. advisoryai-web registers that authority behind the own-connection gate and before either knowledge indexer; the worker registers runtime DAL only. The legacy active baseline and PostgresKnowledgeSearchStore.EnsureSchemaAsync private ledger were retired together by AAI-9 gates 1–2. The pre-1.0 files remain historical under Storage/Migrations/_archived/pre_1.0/mig061/ and are not embedded. The current table families include:
  • Consent & attestation: advisoryai.ai_consents (baseline line 670), advisoryai.ai_run_attestations, advisoryai.ai_claim_attestations (folded in from the pre-1.0 009).
  • Runtime replay/ledger/chat: advisoryai.runtime_explanations (line 735), advisoryai.runtime_policy_intents, advisoryai.runtime_runs, advisoryai.runtime_chat_settings_overrides, advisoryai.conversations (line 805), advisoryai.turns (line 822) (from the pre-1.0 010).
  • Chat audit: advisoryai.chat_sessions (line 27), chat_messages, chat_policy_decisions, chat_tool_invocations, chat_evidence_links (from the pre-1.0 001).
  • Knowledge/Unified Search + analytics/feedback: advisoryai.kb_doc (line 135), kb_chunk, api_spec, api_operation, doctor_search_projection, entity_alias, search_events (line 416), search_history, search_feedback (line 445), search_quality_alerts (line 495) (from the pre-1.0 002–008), with FTS/trigram indexing (English + multilingual).
  • Evidence Packs: forward migration 002_advisoryai_evidence_pack_store.sql adds advisoryai.evidence_packs (full aggregate plus current DSSE-signed aggregate) and tenant-bound advisoryai.evidence_pack_run_links. Pack content is immutable by ID, signed content must equal the stored aggregate, and both tables are source-of-truth retention class.
• All runtime PostgreSQL stores, including AdvisoryAI:Storage, AdvisoryAI:KnowledgeSearch, chat audit, and IEvidencePackStore, resolve the same service-owned DSN from STELLAOPS_POSTGRES_ADVISORYAI_CONNECTION (or Postgres:AdvisoryAI:ConnectionString). The Evidence Pack pool is private and does not claim the host-wide bare NpgsqlDataSource slot. Legacy and generic connection values are not fallbacks. When the own DSN is absent, production-like hosts fail closed; an explicit local harness may use its named fakes, but Evidence Pack storage remains unconfigured unless the harness explicitly replaces it. This source contract is ready for the AAI-9 window but is not evidence that the live data move/deploy has occurred.
• Re-verify: run PostgresEvidencePackStoreTests, AdvisoryAiDurableRuntimeTests.EvidencePack_PersistsAcrossHostRestart_AndNativeEndpointsUseOwnedStore, AdvisoryAiDurableRuntimeTests.EvidencePack_ProductionComposition_AllowsUnsignedOperations_AndSigningFailsOnUse, and AdvisoryAiRuntimeStartupContractTests.WebHost_LocalHarnessWithoutOwnDatabase_KeepsEvidencePackStorageFailClosed with tools/scripts/test-targeted-xunit.ps1, then run the full StellaOps.AdvisoryAI.Persistence.Tests assembly.
• Process-local Null*, NoOp*, and InMemory* runtime bindings are allowed only for explicit local harnesses: environment Development or Testing plus AdvisoryAI:RuntimeBindings:AllowLocalHarnessFakes=true.
• Advisory AI attestation signing is explicit: IAiAttestationEnvelopeSigner must be registered before Create*AttestationAsync(..., sign: true) can produce a DSSE envelope. RunService.AttestAsync also requires a configured IRunAttestationSigner or registered IAiAttestationEnvelopeSigner; missing signing configuration, empty signatures, and known placeholder markers fail closed instead of creating mock signatures.
• Evidence pack creation never synthesizes sha256:unknown. Each evidence item must provide a valid sha256:<64 hex> digest, or the API computes one from normalized snapshot data when snapshot data is present and deterministic. Empty snapshot data without a caller digest is rejected. The durable integration harness proves that, with the own DSN configured and its explicit local fake signer enabled, create/get/list/run/export data survives host restart through the AdvisoryAI-owned PostgreSQL store. Commit 7d30dbf4ea79cba79569413839237c6ac84e3347 closes the Production composition gap found by the earlier isolated boot: Production now resolves UnconfiguredEvidencePackSigner, allowing unsigned storage operations while retaining fail-closed sign/verify behavior. Verified-by: pwsh ./tools/scripts/test-targeted-xunit.ps1 -Project src/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Tests/StellaOps.AdvisoryAI.Tests.csproj -Method "*EvidencePack_ProductionComposition_AllowsUnsignedOperations_AndSigningFailsOnUse*" -BuildProjectReferences boots a Production host against a fresh own database with AllowLocalHarnessFakes=false, returns list=200, persists an unsigned pack and rejects sign/verify (1 selected / 933 suite). This is source/TestServer evidence; a clean successor-image direct-host re-force remains before any runtime or signed-export claim. The store’s * tenant lookup is an internal service seam; Evidence Pack HTTP handlers reject a wildcard tenant claim before storage.

7) Profiles & sovereignty

• Profile is a free-form label, not an enumerated catalog (current code). AdvisoryTaskRequest.Profile is a string that defaults to "default" (src/AdvisoryAI/StellaOps.AdvisoryAI/Orchestration/AdvisoryTaskRequest.cs). It is threaded into the plan cache key (AdvisoryPipelineOrchestrator writes builder["profile"]) and into the output store partition (AdvisoryOutputStore requires a non-empty profile). The pipeline does not ship a built-in profile registry that maps fips-local / gost-local / cloud-openai to allowed models, key management, or telemetry endpoints — passing such a value simply produces a separate cache/output partition under that label.
• (Draft / roadmap.) Named sovereignty profiles (fips-local, gost-local) and a disabled-by-default cloud profile that bind specific models, KMS, and telemetry sinks are a forward design goal and are not yet implemented as a profile catalog. Today the model/provider choice is governed by AdvisoryAI:Chat:Inference:Provider and the LLM-provider plugin configuration (see §13), independently of the request profile.
• CryptoProfile / signing integration: generated artefacts and attestations can be signed via a registered signer (IAiAttestationEnvelopeSigner / IRunAttestationSigner / IEvidencePackSigner) to satisfy procurement/trust requirements (see §6). Signing is explicit and fails closed when no signer is configured.

7.5) Authentication & authorization (Sprint SPRINT_20260430_002)

Audit finding A2 (docs-archive/qa/audits/microservice-audit-pass2-2026-04-29.md): the previously registered AdvisoryAiHeaderAuthenticationHandler accepted raw X-User-Id, X-Tenant-Id, and X-StellaOps-Scopes headers as authoritative identity. That handler has been deleted as a security hardening; the current contract is gateway-envelope-only.

• Single auth source. AdvisoryAI’s WebService trusts only the gateway-signed identity envelope (X-StellaOps-Identity-Envelope + X-StellaOps-Identity-Envelope-Signature, HMAC-SHA256, verified by UseIdentityEnvelopeAuthentication() from StellaOps.Router.AspNet). The registered authentication scheme (AdvisoryAiEnvelope) is a thin handler that surfaces the envelope-validated principal to ASP.NET authorization; there is no fallback path.
• Inbound header strip. InboundIdentityHeaderStripMiddleware runs before UseAuthentication() and unconditionally removes X-User-Id, X-Tenant-Id, X-StellaOps-Actor, X-StellaOps-Scopes, X-StellaOps-TenantId, X-Stella-Scopes, and X-Scopes from every inbound request, so a malicious or misconfigured caller cannot pre-populate identity even if the request reaches the service directly (sidecar, debug port, misrouted gateway).
• Behavior in every environment. The strip and the envelope verification are not conditional on ASPNETCORE_ENVIRONMENT. Requests with raw identity headers and no envelope return HTTP 401 in Development, Testing, and Production alike.
• Claim mapping. Authorization policies (AdvisoryAIPolicies.View / Operate / Admin) and any handler-internal scope/tenant lookups read from httpContext.User.Claims (envelope-derived), not from raw headers. Tenant resolution uses stellaops:tenant then tenant then tenant_id; subject uses sub then ClaimTypes.NameIdentifier; scopes use scope (one claim per envelope scope) and scp (alias).
• Operator note. Internal callers that previously sent only raw identity headers (CLI, smoke scripts, ad-hoc curl) must route through the gateway to receive a signed envelope; direct calls without an envelope will be rejected with 401.

7.6) Outbound service-to-service auth (Authority client_credentials)

Inbound auth (§7.5) is envelope-only. Outbound calls from AdvisoryAI to other internal services are a separate concern handled by an OAuth client_credentials bearer, configured under AdvisoryAi:Authority and wired in Program.cs:

• When AdvisoryAi:Authority:Enabled=true, the service registers AddStellaOpsAuthClient (discovery + JWKS + token client) and attaches a StellaOpsBearerTokenHandler to the named internal HTTP clients vex-internal, findings-internal, scanner-internal, policy-internal, graph-internal, and timeline-internal. The UnifiedSearch live adapters (VEX / Policy / Findings / Graph / Timeline) need this bearer because the upstream tenant resolver reads tenant only from a signed JWT claim (stellaops:tenant); without it the upstreams reply 400 tenant_missing and the adapters fall back to a stale embedded snapshot. findings-internal is its own client rather than a rename of scanner-internal, because that one still has real scanner consumers (FederatedSearchDispatcher, the explanation runtime bindings) that did not move service.
• Config keys: Enabled, Issuer, MetadataAddress, TokenEndpoint, ClientId, ClientSecret, Scope (default advisory:read findings:read graph:read policy:read vex:read), Tenant (default default), BackchannelTimeoutSeconds. TokenEndpoint is optional but load-bearing wherever MetadataAddress is HTTP: unset, the token URL comes from the discovery document and OpenIddict refuses the resulting plain-HTTP token request (ID2083, “This server only accepts HTTPS requests”), which surfaces as a 400 inside the bearer handler and sends every adapter to its snapshot. Set it to the TLS-terminated token URL the estate accepts (https://router.stella-ops.local/connect/token in the reference compose, which also requires the calling container to trust the router CA), the same way Doctor:Registration:TokenEndpoint is set. The worker’s copy of this block reads the same key. Pinned by AdvisoryAiAuthorityClientTests. The matching stellaops-advisory-ai-internal OAuth client + service account are seeded by the Authority seed baseline S001_v1_authority_operational_baseline.sql (client insert at line 835; folded in from the pre-1.0 S005_advisory_ai_authority_client.sql, which is archived and no longer embedded).
• The token cache is forced in-memory (AdvisoryAI runs single-replica today).

Unified-search live adapter targets and provenance

Each live adapter calls one route on one service, and a wrong target does not fail a query — the adapter catches the failure and answers from its committed snapshot, so the corpus reads as healthy while it is a fixture. That is what let three separate upstream defects run unnoticed for a month (SPRINT_20260722_013 AAI-15).

Provenance is a first-class surface, not a log line:

• GET /v1/search/adapters (tenant context, advisory-ai:operate) returns per adapter the source (Upstream, Snapshot, Unconfigured, Disabled), the cause when it is not upstream, the attempted target, the chunk count, and UpstreamSuppressedUntil. The same list rides on the POST /v1/search/index/rebuild response.
• Counters advisory_ai_unified_adapter_ingest_total{domain,adapter,source} and advisory_ai_unified_adapter_fallback_total{domain,adapter,reason,structural} on meter StellaOps.AdvisoryAI.
• A 404 marks the route as structurally absent and suppresses the upstream call for five minutes, doubling to a one-hour ceiling while it stays absent and released on the first success — so the periodic refresh stops re-issuing a call that cannot succeed.

Verified-by: UnifiedSearchLiveAdapterIntegrationTests (route targets, the vulnerabilityId mapping, provenance recording, the 404 backoff and its expiry) and UnifiedSearchEndpointsIntegrationTests (the status endpoint’s scope and tenant gates).

8) APIs

All HTTP routes are mapped in src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/Program.cs (plus the per-feature Endpoints/*.cs). AAI-9 gate 3 adds native /api/advisoryai/v1/** aliases after the entire optional endpoint surface has been composed; every alias retains its handler, HTTP methods, authorization/rate-limit metadata and response behavior. The legacy /v1/advisory-ai/*, /api/v1/chat/*, /v1/search/*, /v1/evidence-packs/*, /v1/runs/*, and /api/v1/opsmemory/* routes remain in the same image for rollback until AAI-10. Gate 9 adds the six OpsMemory handlers at /api/advisoryai/v1/opsmemory/** with suffixed endpoint names and request-native decision Location links. This is source readiness only: the gateway swap and a clean digest-pinned continuation image are still pending. There is no /api/v1/advisory/* surface — that path is historical and does not exist in code. Every business endpoint is authorized by a named policy (§7.5) and rate-limited by the advisory-ai token bucket (30 req/min per X-StellaOps-Client); write paths are wrapped with .Audited(...).

Authorization policies resolve scopes via StellaOpsScopes: advisory-ai:view (View), advisory-ai:operate (Operate, implies View), advisory-ai:admin (Admin, implies Operate). The legacy advisory:run / advisory:explain / advisory:companion / advisory:remediate / advisory:justify strings still appear in some handler-internal EnsureAuthorized checks, but those strings are not registered Authority scopes — modern gateway envelopes carry the advisory-ai:* scopes that the named policies enforce first.

Pipeline & outputs

• POST /v1/advisory-ai/pipeline/{taskType} (Operate, audited) — creates a plan for taskType (summary|conflict|remediation), caches it, and enqueues execution. Body: {advisoryKey, artifactId?, artifactPurl?, policyVersion?, profile, preferredSections?, forceRefresh}. Returns the plan (cache key, prompt template hash, token budget, guardrail metadata).
• POST /v1/advisory-ai/pipeline:batch (Operate, audited) — same as above for a batch of plan requests.
• GET /v1/advisory-ai/outputs/{cacheKey}?taskType=...&profile=... (View) — retrieves a cached output. profile defaults to default when omitted (not fips-local); taskType is required and parsed case-insensitively.

Explanation & companion

• POST /v1/advisory-ai/explain (Operate, audited) — evidence-anchored explanation for a finding/vulnerability.
• GET /v1/advisory-ai/explain/{explanationId}/replay (View) — deterministic replay of a stored explanation.
• POST /v1/advisory-ai/companion/explain (Operate) — composes the explanation with deterministic runtime signals from Zastava-compatible observers; request extends explain fields with runtimeSignals[], response returns companionId, companionHash, composed summary lines, and normalized runtime highlights.

Remediation (Remedy Autopilot)

• POST /v1/advisory-ai/remediation/plan (Operate, audited) and POST /v1/advisory-ai/remediate (Operate, alias).
• POST /v1/advisory-ai/remediation/apply (Operate, audited) — dispatches to the SCM-specific IPullRequestGenerator selected by scmType.
• GET /v1/advisory-ai/remediation/status/{prId}?scmType=... (View) — scmType defaults to github.

Policy Studio (Copilot)

• POST /v1/advisory-ai/policy/studio/parse and .../generate (both Operate) are wired.
• POST /v1/advisory-ai/policy/studio/validate and .../compile (Operate) currently return HTTP 501 Not Implemented — they are not yet wired to durable generated-rule storage.

Consent, justification, rate limits (VEX-AI)

• GET|POST|DELETE /v1/advisory-ai/consent (View/Operate; POST and DELETE audited) — durable consent under advisoryai.ai_consents.
• POST /v1/advisory-ai/justify (Operate) — VEX justification draft.
• GET /v1/advisory-ai/rate-limits (View).

Chat gateway (/api/v1/chat/*, all Operate)

• POST /query, POST /query/stream (SSE), POST /intent, POST /evidence-preview.
• GET|PUT|DELETE /settings, GET /doctor, GET /status.
• Legacy /v1/advisory-ai/conversations* endpoints remain for backward compatibility and are deprecated (sunset 2026-12-31 UTC) in favor of /api/v1/chat/*.
• The legacy conversation handlers retain authorization, tenant binding, runtime dispatch, persistence, and HTTP/SSE ownership in the WebService composition root. Their deterministic value projection is isolated in internal AdvisoryConversationValues: response/evidence/action mapping, query-context enrichment, header/role parsing, citation formatting, confidence/token normalization, and token streaming. This boundary is deliberately behavior-preserving and does not create a second runtime or endpoint surface.

Runs ledger (/v1/advisory-ai/runs, group View; mutations Operate, audited)

• POST / (create), GET /{runId}, GET / (query), GET /{runId}/timeline, GET /active, GET /pending-approval.
• Turn/action/approval lifecycle: POST /{runId}/events, /turns/user, /turns/assistant, /actions, /actions/{actionEventId}/execute, /approval/request, /approval/decide, /artifacts, /complete, /cancel, /handoff, /attest.

Attestations & evidence packs

• GET /v1/advisory-ai/runs/{runId}/attestation, .../claims, GET /v1/advisory-ai/attestations/recent, POST /v1/advisory-ai/attestations/verify (all View).
• POST /v1/evidence-packs (Operate), GET /v1/evidence-packs[/{packId}], .../export, POST .../sign (Operate), POST .../verify (View), GET /v1/runs/{runId}/evidence-packs (View). Item reads own the pack-* identifier namespace: an identifier outside that namespace returns 404 before storage is invoked, while a real pack-store failure remains a 5xx. Tenant comes only from the authenticated envelope; empty and wildcard tenant claims return 401, and run-link results are filtered back to that tenant before projection.

Knowledge Search & Unified Search

• POST /v1/advisory-ai/search (Operate), POST /v1/advisory-ai/index/rebuild (Admin).
• POST /v1/search/query (Operate), .../suggestions/evaluate, .../synthesize (Operate), POST /v1/search/index/rebuild (Admin).
• Search analytics/history: POST|GET|DELETE /v1/advisory-ai/search/analytics|history (View/Operate). Feedback/quality: POST /v1/advisory-ai/search/feedback (View), .../quality/alerts|metrics (Admin).

LLM adapter passthrough (only when AdvisoryAI:Adapters:Llm:Enabled=true)

• GET /v1/advisory-ai/adapters/llm/providers (View), POST /v1/advisory-ai/adapters/llm/{providerId}/chat/completions (Operate), POST /v1/advisory-ai/adapters/openai/v1/chat/completions (Operate).
• Runtime plugin boundary: the WebService no longer references StellaOps.AdvisoryAI.Plugin.Unified directly. When the adapter surface is enabled, the host loads the unified LLM adapter from an explicit AdvisoryAI:Adapters:Llm:PluginAssemblyPath, AdvisoryAI:Adapters:Llm:PluginDirectory, or the mounted bundle path /app/plugins/advisoryai/base/llm-unified/. If the bundle is missing or cannot register the real LlmPluginAdapterFactory, completion calls return a controlled unavailable response rather than falling back to in-process implementation code.
• Per-provider signed plugins (commit a36f672403, 2026-06-07, WS1): per the decision to ship per-provider signed assembly plugins (not config-only), AdvisoryAI now loads individual ILlmProviderPlugin bundles through MountedLlmProviderRuntimePluginLoader and merges the survivors into LlmProviderCatalog so they flow through the existing unified LlmPluginAdapter exactly like the built-in providers. Both previously insecure drop-points were hardened to the shared signed admission: AdvisoryAiLlmAdapterPluginBridge replaced the bare LoadFromAssemblyPath of the mounted unified adapter, and the new AdvisoryAiScmAdapterPluginBridge does the same for the identical SCM twin. ListProviders surfaces rejected bundles (no silent-green). See §11.1 Mounted LLM provider plugin loader for the admission chain, config keys, producer, internal diagnostics, and overlay. A live overlay-up acceptance run is still pending.

Health & infra

• GET /health, /health/live, /health/ready (model-gateway-aware), /health/model (detailed gateway payload), plus the build-info endpoint. These are anonymous/unauthenticated.

Pipeline plan/output responses carry output_hash, input_digest, and citations for verification.

9) Observability

• Meter: all instruments use the meter name StellaOps.AdvisoryAI (defined in both AdvisoryPipelineMetrics and the hosting AdvisoryAiMetrics). Most carry a task_type dimension; there is no profile metric label in current code.
• Hosting counters (StellaOps.AdvisoryAI.Hosting/AdvisoryAiMetrics.cs): advisory_ai_pipeline_requests_total, advisory_ai_pipeline_messages_enqueued_total, advisory_ai_pipeline_messages_processed_total.
• Pipeline metrics (StellaOps.AdvisoryAI/Metrics/AdvisoryPipelineMetrics.cs): counters advisory_plans_created, advisory_plans_queued, advisory_plans_processed, advisory_outputs_stored, advisory_ai_guardrail_blocks_total, advisory_ai_validation_failures_total; histograms advisory_plan_build_duration_seconds, advisory_ai_latency_seconds, advisory_ai_citation_coverage_ratio.
• Logs include output_hash, input_digest, profile, model_id, tenant, and artifact identifiers. Sensitive context is not logged.
• Traces: AdvisoryAiActivitySource.Instance emits server spans for plan requests, batch plans, explain/replay, companion explain, remediation, policy parse/generate, and justify.

10) Operational controls

• HTTP rate limiting. The WebService registers an ASP.NET token-bucket limiter (advisory-ai policy) partitioned by the X-StellaOps-Client header: 30 tokens, 30/minute refill, no queue. Requests over budget get HTTP 429. (This is request-level throttling, not orchestrator-/profile-based quota.)
• Chat quotas. Chat traffic additionally enforces per-tenant/per-user quotas (requests/min, requests/day, tokens/day, tool-calls/day) and tool allowlists via IAdvisoryChatQuotaService / AdvisoryChatToolPolicy, layered as global → tenant → user overrides (see §14 and the /api/v1/chat/settings + /doctor endpoints).
• Offline/air-gapped deployments run local models packaged with the Offline Kit; model artifacts are validated via manifest digests (operators supply the gateway and weights — Stella Ops does not bundle weights).

11) Hosting surfaces

• WebService (advisoryai-web) - exposes the full dual-prefix API surface in §8 (notably legacy POST /v1/advisory-ai/pipeline/{taskType} and native POST /api/advisoryai/v1/advisory-ai/pipeline/{taskType}) to materialise plans and enqueue execution messages. Plan materialisation runs the structured retriever in-process, so since 2026-09-10 (SPRINT_20260722_013 AAI-5) the web role binds the same hub-backed HubAdvisoryDocumentProvider as the worker whenever AdvisoryAI:DocumentProvider:Hub:BaseAddress is configured; a Production host without the key keeps the fail-closed fallback and the pipeline routes answer 400 rather than an empty plan.
• Worker (advisoryai-worker) - AdvisoryTaskWorker hosted service draining the advisory pipeline queue. The queue binding is the file-backed FileSystemAdvisoryTaskQueue (registered by AddAdvisoryAiCore); shared message-transport integration is still pending. The worker binds HubAdvisoryDocumentProvider before AddAdvisoryAiCore, reads the Vulnerabilities owner API’s consensus projection, and uses the established stellaops-advisory-ai-internal Authority client. It does not read Concelier persistence.
• Doctor registration identity. The same stellaops-advisory-ai-internal client is granted platform:doctor:register; the host must not configure a second Doctor client because its outbound adapters share one StellaOpsAuthClientOptions registration. The live Authority row and a fresh default-tenant scoped token were reconciled and verified on 2026-08-22 without changing the existing audiences or adapter scopes. Capability registration stays default-off until the AAI-9 cutover enables it and verifies the registry row.
• Both hosts register AddAdvisoryAiCore, which wires the SBOM context client, deterministic toolset, pipeline orchestrator, file-backed queue/plan/output stores, and queue metrics.
• QA-only fixture container (advisory-fixture). An nginx serving devops/compose/fixtures/integration-fixtures/advisory/data, defined only in the integration-fixtures / advisory-fixture-offline overrides (docker-compose.integration-fixtures.yml) — not in the default stella-services stack. It exists to feed deterministic advisory inputs to integration tests; correctly gated behind overrides, so it never reaches a production stack.
• In supported compose, both hosts depend on advisory-ai-data-init and use the same initialized /var/lib/advisory-ai/{queue,plans,outputs} named volumes. /tmp queue/cache paths are local-harness only and must not be used by the setup procedure.
• advisoryai-web registers AddAdvisoryAiExplanationRuntimeBindings before AddAdvisoryAiCore. When AdvisoryAI:EvidenceRetrieval:BaseAddress is configured, IEvidenceRetrievalService resolves to the Scanner-backed unified evidence adapter rather than the fail-closed fallback. The adapter calls /api/v1/triage/findings/{findingId}/evidence through the scanner-internal HTTP client and maps SBOM, reachability, VEX, attestation, manifest, verification, delta, binary-diff, and policy data into deterministic explanation evidence nodes. It also binds the explanation endpoint to the configured AdvisoryAI inference client and a citation extractor that verifies model citations against evidence references.
• The compose frontdoor publishes AdvisoryAI through gateway ReverseProxy routes (/api/v1/advisory-ai/*, /v1/advisory-ai/*, /api/v1/search/*, and /v1/evidence-packs/*) with preserved gateway auth headers. These paths are not service-discovery Microservice routes in the supported compose setup because advisoryai-web is already reachable by container DNS alias (advisoryai.stella-ops.local) and requires the gateway identity envelope.
• advisoryai-web registers AddAdvisoryAiRuntimePersistence, and advisoryai-worker registers AddAdvisoryAiCoreRuntimePersistence; together those paths auto-migrate the advisoryai schema and bind durable PostgreSQL-backed consent, attestation, explanation replay, policy-intent, run, conversation, and chat-settings stores whenever runtime database configuration is present.
• In-memory and null runtime implementations are reserved for explicit local harnesses. Development or Testing may opt in with AdvisoryAI:RuntimeBindings:AllowLocalHarnessFakes=true; every other host, and local hosts without that flag, fail fast when durable/runtime contracts are missing.
• SBOM base address + tenant metadata are configured via AdvisoryAI:SbomBaseAddress and propagated through AddSbomContext.

11.1) Mounted LLM provider plugin loader (signed bundle admission)

MountedLlmProviderRuntimePluginLoader (src/AdvisoryAI/StellaOps.AdvisoryAI/Inference/LlmProviders/Admission/MountedLlmProviderRuntimePluginLoader.cs, commit a36f672403) discovers, admits, and activates signed per-provider ILlmProviderPlugin bundles from a mounted profile directory and registers the survivors in LlmProviderCatalog so they flow through the existing unified LlmPluginAdapter. Only the AdvisoryAI web service runs the provider loader (the worker does not), and the LLM adapter surface must be enabled (AdvisoryAI:Adapters:Llm:Enabled, default true in the base stack) for mounted providers to be admitted. The loader is fail-closed and de-duplicates by ILlmProviderPlugin.ProviderId (a duplicate is surfaced as rejected, never silently shadowed). A missing/unmounted root is fail-open: AdvisoryAI keeps running with only the built-in providers.

advisoryai-web also maps the canonical pluginized-compose diagnostics: GET /internal/plugins/status returns the loader’s catalog state, and POST /internal/plugins/probe runs a deterministic catalog probe that marks mounted, discovered, admitted, and loaded provider bundles as responded. The probe does not call an external model endpoint.

Admission chain — each bundle is admitted through the shared SignedRuntimePluginAdmission chokepoint (src/__Libraries/StellaOps.Plugin/Security/SignedRuntimePluginAdmission.cs, promoted from AdvisoryAI in commit c1922c1ce5; AdvisoryAI keeps a thin facade that bakes in module advisoryai, contract runtime-bundle.v1, and capability advisoryai:llm-provider):

1. Manifest binding — id equals the bundle directory name, module is advisoryai, contractVersion is runtime-bundle.v1, the configured profile matches (when non-empty), capability advisoryai:llm-provider is declared, and a well-formed assembly descriptor (relative path + sha256) is present.
2. Per-assembly SHA-256 + path-traversal guard — the on-disk assembly bytes must hash to the manifest digest; rooted/escaping paths are rejected; the detached <assembly>.sig is enforced to the conventional location so a tampered manifest cannot redirect the verifier.
3. Detached RSA-PKCS1-SHA256 verification — OfflineDevRsaSha256PluginVerifier with AllowUnsigned=false against the configured trust root. Only then is the ILlmProviderPlugin entry type activated via ActivatorUtilities. An AssemblyLoadContext resolving hook (AdvisoryAiPluginAssemblyResolver) resolves transitive StellaOps.* deps.

Before code activation, two additional host-level gates keep the mount boundary deterministic. A manifest with enabled=false is reported as disabled with zero providers and no assembly load. When RequireReadOnlyBundles=true (the default), writable bundle directories are reported as rejected with zero providers so the compose read-only mount contract is visible in the probe report.

Configuration (AdvisoryAI:LlmProviders:RuntimePlugins, env prefix ADVISORYAI_):

Hardened drop-points: AdvisoryAiLlmAdapterPluginBridge (mounted unified LLM adapter) and AdvisoryAiScmAdapterPluginBridge (the identical SCM twin) both replaced their bare LoadFromAssemblyPath with the same signed admission, and the /v1/advisory-ai/adapters/llm/... ListProviders surface reports rejected bundles.

Bundle / trust-root layout:

Bundle producer: devops/build/package-runtime-plugins.ps1 -Module advisoryai -Profile base -SignAdvisoryAiBundles -UseOfflineDevSigner -OfflineDevSigningKeyRoot <installation-custody-root> stages the signed stellaops.advisoryai.llm-provider.ollama bundle under <profile>/llm-providers/. The cryptography library resolves the installation’s existing runtime-plugin purpose key; missing custody fails instead of silently generating a replacement. Explicit enrollment and lost-key rotation follow Signing keys by purpose. The loader already handles multiple providers; staging the remote provider and adapter bundles is the documented follow-up. The exported public cosign.pub is git-ignored under the AdvisoryAI trust-root directory.

Compose mounts: the advisoryai-web definition in devops/compose/docker-compose.advisoryai.yml carries the read-only mounts of devops/plugins/advisoryai/base + the trust root, keeps the LLM adapter enabled, restates the loader defaults (ADVISORYAI__AdvisoryAI__LlmProviders__RuntimePlugins__RootPath/Profile/TrustRootPath) and names the writable scratch volume explicitly. That contract was written onto the continuation key at AAI-9 gate 4 precisely because the predecessor definition it replaced lived in another file, and it is now the only copy: AAI-10 deleted the predecessor key from devops/compose/docker-compose.stella-services.yml on 2026-09-07. An earlier separate mount overlay had already been retired after Linux Compose 2.39 rejected its duplicate imported-service definition.

Tests: focused loader admission coverage includes signed load, missing/unmounted root, bad hash, bad signature, duplicate provider ID, unsupported contract, capability mismatch, disabled manifest, writable mount, and malformed/path traversal cases; every reject path admits zero providers. The internal status/probe endpoints have integration coverage for status output, probe response marking, and plugin ID filtering.

Live runtime probe is pending. The loader, hardened bridges, producer, and canonical Compose mounts are committed, and /internal/plugins/status + /internal/plugins/probe are mapped, but a live canonical-stack acceptance probe against a running advisoryai-web (mount the signed Ollama provider, confirm GET /v1/advisory-ai/adapters/llm/providers and /internal/plugins/* report it admitted/responded) has not yet been recorded.

12) QA harness & determinism (Sprint 110 refresh)

• Injection fixtures: src/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Tests/TestData/guardrail-injection-cases.json now enumerates both blocked and allow-listed prompts (redactions, citation checks, prompt-length clamps) while the legacy prompt-injection-fixtures.txt file continues to supply quick block-only payloads. AdvisoryGuardrailInjectionTests consumes both datasets so guardrail regressions surface with metadata (blocked phrase counts, redaction counters, citation enforcement) instead of single-signal failures.
• Golden prompts: summary-prompt.json now pairs with conflict-prompt.json; AdvisoryPromptAssemblerTests load both to enforce deterministic JSON payloads across task types and verify vector preview truncation (600 characters + ellipsis) keeps prompts under the documented perf ceiling.
• Plan determinism: AdvisoryPipelineOrchestratorTests shuffle structured/vector/SBOM inputs and assert cache keys + metadata remain stable, proving that seeded plan caches stay deterministic even when retrievers emit out-of-order results.
• Execution telemetry: AdvisoryPipelineExecutorTests exercise partial citation coverage (target ≥0.5 when only half the structured chunks are cited) so advisory_ai_citation_coverage_ratio reflects real guardrail quality.
• Plan cache stability: AdvisoryPlanCacheTests now seed the in-memory cache with a fake time provider to confirm TTL refresh when plans are replaced, guaranteeing reproducible eviction under air-gapped runs.

13) Deployment profiles, scaling, and local model inference

• Local inference containers. advisoryai-web exposes the API/plan cache endpoints while advisoryai-worker drains the queue and executes prompts. Both containers mount the same shared data root that hosts three deterministic paths: /var/lib/advisory-ai/queue, /var/lib/advisory-ai/plans, /var/lib/advisory-ai/outputs. Compose bundles create named volumes (advisory-ai-{queue,plans,outputs}); Kubernetes/Helm PVC packaging is not a supported Stella Ops release target.
• In-house OpenAI-compatible gateway. Production-like chat question answering binds to AdvisoryAI:Chat:Inference:Provider=inhouse-ternary or openai-compatible and requires an operator-configured AdvisoryAI:Chat:Inference:BaseUrl. The gateway calls GET /health, GET /v1/models, and POST /v1/chat/completions; model registry entries must advertise the configured model, optional digest, and required production capabilities (chat.completions, response_format.json_object, citations.required, seed, top_k). Unavailable health/model checks, missing capabilities, digest mismatches, invalid JSON envelopes, and uncited model output return controlled runtime unavailability with structured diagnostics instead of prompt echo or placeholder answers.
• Default ternary model pin. Setup guidance (llm-setup-guide.md) defaults to microsoft/bitnet-b1.58-2B-4T, an MIT-licensed native 1.58-bit/ternary roughly 2B-parameter model. The shipped appsettings.json carries the placeholder AdvisoryAI:Chat:Inference:Model=local-32b-ternary and an empty BaseUrl/ModelDigest, so operators must override Model/BaseUrl to the approved local gateway artifact. Stella Ops does not bundle model weights; operators provide the gateway, model artifact, and expected digest or signed manifest. A future custom/larger Stella Ops model requires release guide and model-selection updates before it becomes the documented default.
• Operational health. advisoryai-web exposes /health/live for process liveness, /health/ready for model-gateway-aware readiness, and /health/model for the detailed gateway status payload used by operators and diagnostics.
• Deterministic generation contract. Chat requests use temperature=0, top_p=1, top_k=1 (SendTopK=true), a fixed seed (default 42), bounded max_tokens (default 512), and response_format={type:json_object} — see the AdvisoryAI:Chat:Inference block in appsettings.json. Audit metadata records model_id, optional model_digest, prompt_template_hash, and context_digest.
• No inference fallback. Production-like AdvisoryAI chat and provider-based inference do not fall back to dummy providers, null clients, sanitized prompts, prompt previews, empty-output prompt echoes, or cloud models. Local harness fakes require Development or Testing plus AdvisoryAI:RuntimeBindings:AllowLocalHarnessFakes=true; otherwise missing configuration is a fail-closed runtime error. Prompt-preview output is labeled with dev-harness.prompt-preview, inference.harness=local-dev-test-only, and inference.production_eligible=false.
• Scalability. Start with 1 web replica + 1 worker for up to ~10 requests/minute. For higher throughput, scale advisoryai-worker horizontally; each worker is CPU-bound (2 vCPU / 4 GiB RAM recommended) while the web front end is I/O-bound (1 vCPU / 1 GiB). Because the queue/plan/output stores are content-addressed files, ensure the shared volume delivers ≥500 IOPS and <5 ms latency; otherwise queue depth will lag.
• Offline & air-gapped stance. Supported compose/service-manager release manifests avoid external network calls by default and the Offline Kit publishes the AdvisoryAI web and worker images alongside their SBOMs/provenance. Operators can rehydrate the shared data root from the kit to pre-prime cache directories before enabling the service.
• Local runtime truthfulness. The in-process LlamaCppRuntime does not provide inference without a wired native llama.cpp binding. Loading a GGUF file verifies path presence only and then fails closed; digest verification remains available, but no placeholder text or stream chunks are emitted. Use a real ILlmProvider such as a configured llama.cpp server/Ollama provider for local inference until AIAI-TRUTH-003-01 is replaced by a native runtime implementation.
• Provider abstraction & on-prem posture. Two distinct abstractions exist: (1) the chat inference client selected by AdvisoryAI:Chat:Inference:Provider (inhouse-ternary/openai-compatible is the default; local, ollama, openai, claude clients also exist under Chat/Inference/); and (2) the ILlmProvider plugin catalog (Inference/LlmProviders/) used by the optional LLM adapter passthrough (§8). The provider implementation catalog is now loaded through the unified adapter plugin bundle instead of a WebService ProjectReference. The catalog registers plugins for llama-server and ollama (on-prem) and for openai, claude, and gemini (cloud) only when the mounted/configured adapter bundle is present and admitted by the current bridge. The cloud providers are opt-in only: the LLM adapter is disabled by default (AdvisoryAI:Adapters:Llm:Enabled=false), provider configs are loaded from per-provider YAML in etc/llm-providers, and the dummy provider is registered only when local-harness fakes are allowed. No cloud provider is the default and none is reachable until an operator explicitly enables the adapter, supplies a provider config, and mounts/configures the adapter bundle. Remote inference is additionally blocked in sealed/air-gapped mode (§14).

14) Controlled conversational interface and tool gating

• Chat Gateway controls. Chat endpoints enforce Authority auth, per-tenant/user quotas, token budgets, and PII/secret scrubbing before any model invocation.
• Grounded QA boundary. Chat context is assembled from the evidence bundle plus Knowledge Search and Unified Search results as the BitRAG substitute. The model must return structured JSON with cited claims; invalid or uncited output maps to controlled unavailability, not a fallback answer.
• Sanctioned tools only. Tool calls are schema-bound and allowlisted (read-only by default). Action tools require explicit user confirmation plus policy allow.
• Policy lattice. Tool permissions are evaluated against policy rules (scope, tenant, role, resource) before invocation.
• Audit log. Persist prompt hash, redaction metadata, tool calls, policy decisions, and model identifiers to Postgres; optional DSSE signatures capture evidence integrity.
• Offline parity. Local model profiles are the default; remote inference is opt-in and blocked in sealed mode.
• Action execution boundary. IActionExecutor does not simulate action success. After policy and approval checks, it dispatches only to registered IActionConnector implementations. If no connector can execute the action type, the result is Failed with ACTION_CONNECTOR_UNAVAILABLE and an ExecutionFailed audit entry. Connector success is the only path that records idempotent successful execution. Rollback is also connector-gated: the executor looks up the original executed audit entry and returns ACTION_EXECUTION_NOT_FOUND, ACTION_ROLLBACK_NOT_SUPPORTED, or ACTION_ROLLBACK_CONNECTOR_UNAVAILABLE rather than pretending compensation exists.
• GitHub remediation PR boundary. GitHubPullRequestGenerator creates PR bodies only after an SCM connector and repository owner/repo context are valid. Missing connector/configuration, status lookup without persisted repository context, delta verdict update, and close operations fail closed instead of returning placeholder PR text, “waiting for CI” status, or silent no-ops.

See docs/modules/advisory-ai/chat-interface.md and docs-archive/product/advisories/13-Jan-2026 - Controlled Conversational Interface.md.

15) OpsMemory (Operational Memory and RAG)

Consolidated from src/OpsMemory/ into src/AdvisoryAI/ (Sprint 213, 2026-03-04). Archived docs: docs-archive/modules/opsmemory/.

Overview

OpsMemory provides a decision ledger for security operations learning. It captures the complete lifecycle of a security decision – from situation context through action taken to eventual outcome – enabling playbook suggestions for future similar situations.

Source layout (post-consolidation)

• Library: src/AdvisoryAI/__Libraries/StellaOps.OpsMemory/ – core domain: models, similarity vectors, playbook suggestion engine, storage abstractions.
• Application: src/AdvisoryAI/__Libraries/StellaOps.OpsMemory.Application/ – the HTTP surface (/api/v1/opsmemory/* and /api/advisoryai/v1/opsmemory/*), the tenancy resolver and the scope policies. Mapped in-process by advisoryai-web; it is a module, not a deployable.
• Retired host: src/__Obsoleted/AdvisoryAI/StellaOps.OpsMemory.WebService/ – the former opsmemory-web container, frozen 2026-09-07 (AAI-10, CoC §15.4). It was a composition root with no routes of its own.
• Tests: src/AdvisoryAI/__Tests/StellaOps.OpsMemory.Tests/ – unit (similarity vectors, playbook suggestions, context enrichers, chat provider) and integration (Postgres store with Testcontainers).

Key components

API surface

advisoryai-web serves all six on both roots: the legacy /api/v1/opsmemory/** above and the native /api/advisoryai/v1/opsmemory/**. Route names on the native aliases use the .consolidated suffix, so create responses generate a Location under the prefix the caller used. The pairing is asserted route by route – method, endpoint name, authorization policy and audit metadata – by AdvisoryAiOpsMemoryEndpointTests.HostCarriesAllSixLegacyAndNativeRoutes_WithEquivalentNamesAuthAndAuditMetadata.

Route group requires OpsMemoryPolicies.Read; write paths (POST /decisions, POST /decisions/{memoryId}/outcome) additionally require OpsMemoryPolicies.Write and are .Audited(...). Path parameter is memoryId (OpsMemoryEndpoints.MapOpsMemoryEndpoints). Those policy names read ops-memory:read / ops-memory:write from the signed gateway envelope.

Tenancy contract (claim-bound)

Auth-model note, corrected by the retirement (2026-09-07). Until AAI-10 these routes ran on a second host that did not use the §7.5 envelope stack: opsmemory-web authenticated as an Authority resource server (a raw JWT bearer) reachable over the backend bypass networks, so the header strip and envelope authentication §7.5 describes did not apply to it. That host is gone. The routes now run inside advisoryai-web and inherit §7.5 in full — envelope-only identity, the inbound header strip, and UseStellaOpsTenantMiddleware + .RequireTenant() on the groups. The tenancy guarantee below is enforced in the endpoints themselves, so it holds on either root.

The isolation tenant is resolved exclusively from the authenticated stellaops:tenant claim (OpsMemoryTenantResolver → IStellaOpsTenantAccessor, populated by the shared tenant middleware). Caller-supplied tenant input is never an isolation key:

• The tenantId query parameter (GET /decisions, GET /decisions/{memoryId}, GET /stats, GET /suggestions, POST /decisions/{memoryId}/outcome) and the tenantId body field of RecordDecisionRequest are optional conflict checks. When present and different from the claim, the request is rejected with 400 / error_code: tenant_conflict (accept-but-verify: a mismatched caller fails loudly rather than being silently re-scoped).
• A request with no tenant claim is rejected by the route group’s .RequireTenant() filter with 400 / error_code: tenant_missing. This is load-bearing on the compose bypass networks (Authority__ResourceServer__BypassNetworks), where StellaOpsBypassEvaluator can satisfy the scope policy with no principal at all: such a caller carries no tenant claim and is refused, instead of being served whichever tenant it named.
• Regression coverage: StellaOps.OpsMemory.Tests/Integration/OpsMemoryTenancyEndpointTests.cs (a tenant-A principal asking for tenant-B is refused on both read and write paths, and the store is never invoked with the foreign tenant).

Landed in Sprint SPRINT_20260712_001 (TEN-1); before it, every endpoint passed the caller’s tenantId straight to PostgresOpsMemoryStore as the sole isolation key.

Database

The opsmemory schema now lives in the family’s own database stellaops_advisoryai, created by the consolidated baseline, which carries opsmemory.decisions alongside the AdvisoryAI tables. There is exactly one migration authority: advisoryai-web registers the folded store/playbook/chat services against the same service-owned DSN as every other AdvisoryAI store, without a second migrator, and the OpsMemory pool stays private to the module so the bare NpgsqlDataSource DI slot is free. __Libraries/StellaOps.OpsMemory/Migrations/001_initial_schema.sql is no longer applied by anything: the host that ran it (AddStartupMigrations<PostgresOptions>(...)) was retired on 2026-09-07. The legacy stellaops_platform.opsmemory schema is retained offline as a rollback input until the separately approved destructive drop. Tenant isolation is enforced at the query level (WHERE tenant_id = @tenantId), and the @tenantId the store receives is always the claim tenant — see the tenancy contract above; it is never taken from caller input. Similarity search uses array-stored vectors with in-store cosine similarity — no pgvector dependency.

Connection contract:

• Pre-cutover host connection precedence: ConnectionStrings:OpsMemory -> OpsMemory:Storage:ConnectionString -> ConnectionStrings:Default.
• Consolidated host: only STELLAOPS_POSTGRES_ADVISORYAI_CONNECTION (or Postgres:AdvisoryAI:ConnectionString); no OpsMemory/legacy/generic fallback.
• Missing DB configuration is a startup error (fail-fast); localhost fallback is limited to development-only workflows.

Dependencies

• StellaOps.Findings.Ledger (upstream library)
• StellaOps.Auth.ServerIntegration (authentication)
• StellaOps.Determinism.Abstractions (deterministic time/GUID providers)
• StellaOps.Localization (i18n)
• AdvisoryAI core references OpsMemory via ProjectReference for context enrichment