ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
dev
TenantAtlas/specs/074-verification-checklist/research.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

3.3 KiB
Raw Permalink Blame History

Research: Verification Checklist Framework (074)

Date: 2026-02-03
Phase: Phase 0 (Foundational Research)
Status: Complete

Decisions

D-001 — Canonical storage location for verification reports

Decision: Store the verification report in operation_runs.context.verification_report (JSONB).

Rationale:

  • Monitoring pages must be DB-only at render time (constitution: Operations / Run Observability Standard).
  • OperationRun is the canonical operational record; keeping the report attached avoids new tables/indexing for v1.
  • The existing UI already renders OperationRun.context safely as JSON, so we can progressively enhance into a structured viewer.

Alternatives considered:

  • Dedicated verification_reports table: rejected for v1 to keep adoption lightweight; can be introduced later if querying/indexing becomes necessary.

D-002 — Idempotency / dedupe mechanism

Decision: Use the existing OperationRunService::ensureRunWithIdentity() mechanism and the DB partial unique index on (tenant_id, run_identity_hash) for active statuses (queued, running).

Rationale:

  • This repo already enforces active-run dedupe at the DB level via operation_runs_active_unique.
  • Matches the clarified spec policy: dedupe only while a run is active; completed runs allow a new run.

Alternatives considered:

  • Application-only locks/dedupe: rejected as non-race-safe.

D-003 — Flow identifier and identity scope

Decision: Treat OperationRun.type as the primary flow identifier for the verification run, and keep additional flow details (wizard step, etc.) in context.

Rationale:

  • Existing operations already key UX semantics (labels, polling, related links) off OperationRun.type.
  • Dedupe identity hashing already includes type, making flow part of the dedupe boundary.

Alternatives considered:

  • Separate flow_id column: rejected for v1 (schema change not required).

D-004 — Reason code taxonomy and extensions

Decision: Maintain a small baseline set of cross-cutting reason codes, and reserve ext.* for flow/check-specific extensions.

Rationale:

  • Prevents brittle UI parsing and enables future automation.
  • Keeps room for flow-specific details without polluting the baseline vocabulary.

Alternatives considered:

  • Free-form codes everywhere: rejected due to support/automation cost.

D-005 — Evidence policy (strict safe pointers)

Decision: Evidence fields in check results are strictly structured safe pointers only (IDs, masked strings, hashes). No payloads, tokens, claims, headers, or full error bodies.

Rationale:

  • Aligns with constitution data-minimization and safe logging rules.
  • Avoids accidentally persisting secrets inside run context.

Alternatives considered:

  • Storing raw error payloads: rejected for security and compliance risk.

D-006 — UI semantics for statuses and badges

Decision: Render status-like values (check status, severity) via centralized badge semantics (BADGE-001), not ad-hoc mappings in feature pages.

Rationale:

  • Prevents drift in meaning/colors across the suite.
  • Enables straightforward regression tests for new/changed status values.

Alternatives considered:

  • Inline color mapping inside a Blade view: rejected (violates BADGE-001).