TenantAtlas/specs/074-verification-checklist/contracts/reason-codes.md
ahmido 439248ba15 feat: verification report framework (074) (#89)
Implements the 074 verification checklist framework.

Highlights:
- Versioned verification report contract stored in operation_runs.context.verification_report (DB-only viewer).
- Strict sanitizer/redaction (evidence pointers only; no tokens/headers/payloads) + schema validation.
- Centralized BADGE-001 semantics for check status, severity, and overall report outcome.
- Deterministic start (dedupe while active) via shared StartVerification service; capability-first authorization (non-member 404, member missing capability 403).
- Completion audit event (verification.completed) with redacted metadata.
- Integrations: OperationRun detail viewer, onboarding wizard verification step, provider connection start surfaces.

Tests:
- vendor/bin/sail artisan test --compact tests/Feature/Verification tests/Unit/Badges/VerificationBadgesTest.php
- vendor/bin/sail bin pint --dirty

Co-authored-by: Ahmed Darrazi <ahmeddarrazi@MacBookPro.fritz.box>
Reviewed-on: #89
2026-02-03 23:58:17 +00:00

1.1 KiB
Raw Blame History

Reason Codes (074)

This file defines the baseline reason_code taxonomy for verification check results.

Rules

  • Reason codes are stable and machine-readable.
  • New codes must be appended (avoid renames) to keep support and automation stable.
  • Flow/check-specific codes must use the reserved namespace: ext.*.

Baseline Codes (v1)

  • ok — Check passed.
  • not_applicable — Check skipped because it doesnt apply to this identity/scope.
  • missing_configuration — Required config is absent.
  • permission_denied — Insufficient permissions / consent missing.
  • authentication_failed — Token acquisition or auth precondition failed.
  • throttled — Remote dependency throttled (e.g., 429/503) and check could not complete.
  • dependency_unreachable — Remote dependency unavailable.
  • invalid_state — Local model state conflicts with required preconditions.
  • unknown_error — Failure could not be classified.

Reserved Extension Namespace

  • ext.<flow>.<detail> — Flow-specific extensions.
    • Example: ext.managed_tenant_onboarding.role_mapping_missing