# Quickstart: Verification Checklist Framework (074)

This quickstart explains how to *write* and *render* a verification report attached to an `OperationRun`.

## 1) Writing a report (queued job / service)

**Goal**: produce a `verification_report` JSON document and store it in `OperationRun->context`.

Guidelines:
- Generate reports inside queued execution (not in a Filament page render).
- Keep evidence pointer-only (IDs/masked/hashes), never raw payloads or tokens.
- Keep next steps navigation-only in v1.

Pseudo-code sketch:

```php
$context = is_array($run->context) ? $run->context : [];

$context['verification_report'] = [
    'schema_version' => '1.0',
    'flow' => $run->type,
    'generated_at' => now('UTC')->toIso8601String(),
    'identity' => [
        'tenant_id' => (int) $run->tenant_id,
        'provider_connection_id' => (int) data_get($run->context, 'provider_connection_id', 0),
    ],
    'summary' => [
        'overall' => 'needs_attention',
        'counts' => [
            'total' => 5,
            'pass' => 3,
            'fail' => 2,
            'warn' => 0,
            'skip' => 0,
            'running' => 0,
        ],
    ],
    'checks' => [
        [
            'key' => 'provider_connection.token_acquisition',
            'title' => 'Token acquisition works',
            'status' => 'fail',
            'severity' => 'high',
            'blocking' => true,
            'reason_code' => 'permission_denied',
            'message' => 'The app cannot acquire a token with the configured credentials.',
            'evidence' => [
                ['kind' => 'provider_connection_id', 'value' => (int) data_get($run->context, 'provider_connection_id')],
            ],
            'next_steps' => [
                ['label' => 'Review connection credentials', 'url' => '/admin/...'],
                ['label' => 'Microsoft docs: app permissions', 'url' => 'https://learn.microsoft.com/...'],
            ],
        ],
    ],
];

$run->update(['context' => $context]);
```

## 2) Rendering the report (Filament, DB-only)

Recommended integration points:
- Monitoring → Operations: in the `OperationRun` view page, show a “Verification report” section when `context.verification_report` exists.
- Flow pages (e.g., onboarding wizard): embed the same viewer component using the run ID stored in wizard state.

**Hard requirement**: rendering must not trigger any outbound HTTP (no Graph calls, no jobs dispatched, no side effects).

## 3) Authorization split

- Viewing a report: allowed for tenant-scoped members.
- Starting verification: requires a specific capability.
- Non-members: deny-as-not-found (404) for tenant-scoped pages and actions.

## 4) Tests to add

- Viewer DB-only render test: `Http::fake()` + assert no requests during render.
- Evidence redaction test: report JSON contains none of `access_token`, `client_secret`, `Authorization`, bearer tokens, or raw payload dumps.
- Dedupe test: repeated starts while active reuse the same run.