# AI Codex / Zastava Companion

## Module
AdvisoryAI

## Status
VERIFIED

## Description
Companion explanation feature that combines AdvisoryAI evidence-grounded explanations with runtime signals (for example Zastava observer signals) and exposes an API endpoint for companion explain generation.

## Implementation Details
- **Companion Service**: `src/AdvisoryAI/StellaOps.AdvisoryAI/Explanation/CodexZastavaCompanionService.cs`
  - `ICodexCompanionService` contract and deterministic `CodexZastavaCompanionService` implementation.
  - Normalizes and deduplicates runtime signals, computes deterministic companion hash, and returns companion summary/highlights.
- **Web Endpoint Registration**: `src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/Program.cs`
  - Registers `ICodexCompanionService` and maps `POST /v1/advisory-ai/companion/explain`.
- **API Contracts**: `src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/Contracts/CompanionExplainContracts.cs`
  - `CompanionExplainRequest`, `CompanionExplainResponse`, runtime-signal request/response contracts, and domain mapping.
- **Behavioral Tests**:
  - `src/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Companion.Tests/CodexZastavaCompanionServiceTests.cs`
  - `src/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Companion.Tests/CompanionExplainEndpointTests.cs`

## E2E Test Plan
- [ ] Submit companion explain request without scopes and verify the endpoint returns `403`.
- [ ] Submit companion explain request with `advisory:companion` scope and verify mapped request + companion response payload.
- [ ] Submit companion explain request where companion service rejects input and verify endpoint returns `400`.
- [ ] Verify deterministic companion hash for permuted/deduplicated runtime signal inputs.

## Verification
- Verified on 2026-02-11 via `run-002`.
- Tier 0: `docs/qa/feature-checks/runs/advisoryai/ai-codex-zastava-companion/run-002/tier0-source-check.json`
- Tier 1: `docs/qa/feature-checks/runs/advisoryai/ai-codex-zastava-companion/run-002/tier1-build-check.json`
- Tier 2: `docs/qa/feature-checks/runs/advisoryai/ai-codex-zastava-companion/run-002/tier2-integration-check.json`