[AAASM-5086] ✨ (aa-api): Canonical verdict enum + enriched decision record (schema + ADR)

[Chisanan232]

Description

Freezes the gating contract for the Bucket-B backend program (Epic AAASM-5082): the canonical 5-way runtime verdict vocabulary and the enriched per-decision record shape that AAASM-5085/5089 depend on. Schema + read-side only — no enforcement/hot-path behavior change.

• ADR 0018 (docs/src/adr/0018-…md, registered in README.md + SUMMARY.md): records the 5-way vocabulary, the enriched record, and a decision-capture plan describing exactly what hot-path instrumentation a follow-up would need (where the verdict is derived in aa-runtime, where per-decision latency is measured, how trace_id propagates) — explicitly flagged as requiring product/architecture sign-off before implementation.
• RuntimeVerdict enum (aa-api models::verdict): allow / narrow / scrub / pending / deny. Deliberately distinct from the proto Decision wire enum (allow/deny/pending/redact) and the capability-matrix Decision (allow/narrow/approval/deny/na) — neither can express narrow/scrub. The existing enums are left unchanged.
• Enriched decision record: GET /api/v1/agents/{id}/decisions (AAASM-5058) gains nullable verdict + traceId, joining the already-present nullable latencyMs + matchedPolicy. Both new fields return null — capturing them is the ADR-0018-gated hot-path follow-up.

Schema extension of an existing path: 0 new OpenAPI paths (count stays 71). openapi/v1.yaml and the dashboard schema.d.ts codegen are regenerated so the drift gate stays green.

Type of Change

• ✨ New feature
• 📝 Documentation update

Breaking Changes

• No — additive, nullable fields on an existing response; no path added; existing enums untouched; no enforcement/audit-write path modified.

Related Issues

• Related Jira ticket: AAASM-5086 (Epic AAASM-5082)

Testing

• Unit tests added / updated — RuntimeVerdict wire form + distinctness from capability Decision; decision-row test asserts verdict/traceId read null.
• Integration tests — OpenAPI contract (openapi_spec, 71 paths) passes; live-response schema validation passes.

Validated locally (org CI billing-blocked): cargo nextest -p aa-api -p aa-integration-tests (verdict + decision-row + contract green), clippy --all-targets -D warnings clean, fmt --check clean, cargo deny check clean, cargo doc clean. Dashboard: type-check + lint + test (1940 pass) + build all green.

Checklist

• Code follows project style guidelines (cargo fmt, cargo clippy)
• Self-review of the diff completed
• Documentation updated if behaviour changed
• All CI checks passing — org CI is billing-blocked; validated locally instead
• Commits are small and follow the Gitmoji convention

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Chisanan232]

🤖 Claude Code review — READY

Review-only pass on the AAASM-5086 gating contract (Epic AAASM-5082). No source changes made.

CI

• gh pr checks 1697: 37 passed / 0 failed. Sonar shows 0 issues (note-and-pass). Green.

Scope vs AAASM-5086 + Epic 5082 — COMPLETE

• (a) Canonical 5-way RuntimeVerdict (aa-api/src/models/verdict.rs): allow/narrow/scrub/pending/deny, lowercase wire form. Deliberately DISTINCT from the proto wire Decision (allow/deny/pending/redact) and the capability-matrix Decision (allow/narrow/approval/deny/na). Both existing enums are left unchanged; a unit test (scrub_is_not_a_capability_decision_variant) guards against an accidental future merge.
• (b) Enriched decision record: GET /api/v1/agents/{id}/decisions (AAASM-5058) gains nullable verdict + traceId, joining the already-nullable latencyMs + matchedPolicy.
• (c) ADR 0018 (docs/src/adr/0018-…md, registered in README.md + SUMMARY.md): Status "Accepted (schema freeze)"; sections A (verdict derivation), B (per-decision latency measurement), C (trace_id propagation) form the decision-capture plan, each explicitly flagged as requiring product + architecture sign-off before implementation.

Side-effects — schema + read-side ONLY ✅

• git diff (merge-base): 9 files, +409/-0. aa-api types/model + read-side projection, openapi/v1.yaml, regenerated schema.d.ts, and ADR docs. (A docker.yml entry appears only in the remote/main..HEAD direction because the branch is 1 behind main — it is not part of this PR.)
• 0 hot-path change: grep for aa-runtime/aa-gateway/aa-ebpf/aa-proxy/enforcement/audit-write in the diff → NONE. entry_to_decision_row returns verdict: None + trace_id: None, doc-commented as pending the ADR-0018 follow-up.
• Both new fields return null — no fabrication.
• Existing Decision enums (proto + capability): untouched.
• 0 new OpenAPI paths — count stays 71 (all yaml additions are under components: schemas; the openapi_spec_paths_match_implemented_routes contract test passes).
• schema.d.ts codegen regenerated and clean (matches v1.yaml).

Local validation

• cargo nextest -p aa-api -p aa-integration-tests openapi_spec → 6 passed (71-path contract green).
• cargo nextest -p aa-api verdict decision → 24 passed (verdict wire-form + distinctness + decision-row null-reads).
• dashboard pnpm test → 1940 passed / 226 files.

FE sanity

Purely a schema extension with no visible change: no dashboard component consumes AgentDecisionResponse.verdict/traceId (grep, excl. generated → none; the features/trace/decision.ts Verdict is a separate client-side trace explainer, not this field). AgentDecisionStream rendering is unchanged and covered by the 1940 passing unit tests. Light check sufficient; full browser launch not warranted for a null-field, no-render-change schema PR.

Verdict: READY ✅

Schema-freeze + ADR only; 0 enforcement/hot-path touch; existing enums intact; 71 paths held. The A/B/C capture work is correctly gated behind ADR-0018 product/architecture sign-off. Not merging (review-only, per instruction).