ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
97e06587bf
TenantAtlas/specs/074-verification-checklist/research.md
Ahmed Darrazi 97e06587bf feat: verification report framework
2026-02-04 00:57:26 +01:00

3.3 KiB
Raw 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).