feat: verification modes + evidence fields + transport combo rejection (hosted parity)

[govindkavaturi-art]

Summary

Ports the outcome-verification feature from the hosted monorepo into cueapi-core, and fixes the partially-ported /verify endpoint from PR #15 so it honors the {valid, reason} contract documented by the hosted API.

What changed

Schema (app/schemas/)

• VerificationMode enum: none, require_external_id, require_result_url, require_artifacts, manual
• VerificationPolicy sub-object with a single mode field today (leaves room for future fields without breaking the shape)
• verification: Optional[VerificationPolicy] on CueCreate and CueUpdate
• OutcomeRequest extended with optional external_id, result_url, result_ref, result_type, summary, artifacts. Legacy shape ({success, result, error, metadata}) is unchanged

Model (app/models/cue.py)

• verification_mode column: String(50), nullable, CHECK constraint over the enum values. NULL and 'none' are treated identically
• evidence_* columns already exist (PR feat: port 10 missing endpoints for feature parity with hosted service #15) and are reused

Migration

• 017_add_verification_mode.py — adds the column + CHECK constraint. Applies cleanly on a blank DB (verified locally). Downgrade drops the constraint first, then the column

Services

• outcome_service.record_outcome computes outcome_state from (success, verification_mode, evidence):

success	mode	evidence	outcome_state
false	any	—	reported_failure
true	none/NULL	—	reported_success
true	manual	—	verification_pending
true	require_external_id	present	verified_success
true	require_external_id	missing	verification_failed
true	require_result_url	present	verified_success
true	require_result_url	missing	verification_failed
true	require_artifacts	present	verified_success
true	require_artifacts	missing	verification_failed

• cue_service._check_transport_verification_combo rejects worker transport paired with evidence-requiring modes at both create and update (see "Restriction" below)

Router

• POST /v1/executions/{id}/verify now accepts {valid: bool, reason: str?} via a typed VerifyRequest body.
  • valid=true (default) → verified_success (legacy behavior preserved — empty body still works)
  • valid=false → verification_failed, reason recorded on evidence_summary (truncated to 500 chars, prepended to any existing summary)
  • Accepted starting states expanded to include reported_failure — this was rejected before but there was no semantic reason to
• OutcomeResponse now surfaces outcome_state

Intentional behavior change

POST /v1/executions/{id}/verify with an explicit {valid: false} body now transitions to verification_failed instead of verified_success. Before this PR, the endpoint ignored the request body and always transitioned to verified_success — a silent-failure bug that made the valid=false branch impossible to exercise. Callers relying on the always-success behavior were getting broken semantics anyway. Empty-body requests remain verified_success (the previous default).

Restriction

Worker-transport cues cannot combine with require_external_id / require_result_url / require_artifacts. Attempting to do so at create or PATCH time returns:

{
  "error": {
    "code": "unsupported_verification_for_transport",
    "transport": "worker",
    "verification_mode": "require_external_id",
    "supported_worker_modes": ["none", "manual"]
  }
}

This is because cueapi-worker < 0.3.0 has no mechanism to attach evidence to the outcome POST. The restriction will be lifted in a follow-up PR once cueapi-worker 0.3.0 (evidence reporting via CUEAPI_OUTCOME_FILE) is published to PyPI.

Tests

35 new tests across four files:

• tests/test_verification_modes.py — 10 tests, 5 modes × (satisfied, unsatisfied / applicable variants)
• tests/test_transport_verification_combo.py — 13 tests: 3 evidence modes rejected × (create, PATCH) + 2 worker-compatible modes accepted + 5 webhook-always-allowed modes + 3 PATCH transitions
• tests/test_outcome_evidence.py — 4 tests: inline evidence persists, legacy shape still works, Pydantic length caps enforced, PATCH evidence still works
• tests/test_verify_endpoints.py — 8 tests covering both branches of valid, empty body default, reason-preserves-existing-summary, invalid-state rejections, and /verification-pending

Test-suite delta

• +35 new passing tests, 0 new failures
• Amended one existing test: test_execution_parity.py::TestVerify::test_verify_wrong_state now uses a pre-outcome state (since reported_failure is now valid starting state)
• Pre-existing failures in test_sdk_integration.py (7) — ModuleNotFoundError: No module named 'cueapi'. Confirmed on clean origin/main (stashed this PR's changes and re-ran). These are environment-dependent tests that expect the Python SDK to be installed; CI handles that

Backward compatibility

• POST /outcome without evidence fields → identical behavior to before
• POST /verify with empty body → identical behavior to before (verified_success)
• Cues without a verification field → verification_mode = NULL → outcome-state engine treats as none → same reported_success / reported_failure semantics as before
• PATCH /v1/executions/{id}/evidence → untouched, still accepts the two-step flow

References

• Private monorepo sources: app/schemas/cue.py (VerificationMode/VerificationConfig), app/schemas/outcome.py (evidence fields), app/services/outcome_service.py (rule engine), app/services/cue_service.py (_check_transport_verification_combo), app/routers/executions.py (/verify body contract)
• Audit context: this PR addresses the ABSENT/PARTIAL items 1, 2, 3, 4, 5, 6, 8 from the cueapi-core drift re-audit. Items 7, 9–14 are out of scope (alerts + sync-discipline land in follow-up PRs)

Test plan

• 35 new tests pass locally (pytest tests/test_verification_modes.py tests/test_transport_verification_combo.py tests/test_outcome_evidence.py tests/test_verify_endpoints.py)
• Full pytest tests/ — no new failures (SDK-integration failures pre-exist)
• Migration 017 applies cleanly on a blank DB (alembic upgrade head from empty schema)
• Column + CHECK constraint verified in Postgres (\d cues)

🤖 Generated with Claude Code

[argus-qa-ai]

All CI checks passing. Approved by Argus.