ahmido
439248ba15
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
87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# 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).
|