TenantAtlas/specs/418-coverage-v2-operator-surface/implementation-report.md

# Implementation Report: Spec 418 - Coverage v2 Operator Surface

**Date**: 2026-06-26
**Branch**: `418-coverage-v2-operator-surface`
**Base HEAD**: `8cbf1f7f feat: implement canonical identity engine (#484)`
**Initial dirty state**: active spec directory `specs/418-coverage-v2-operator-surface/` was untracked; no unrelated dirty runtime files were present.
**Final dirty state**: implementation files, tests, UI audit docs, tasks, and this report are dirty/untracked for this feature package.

## Gates

- **Activated skills / gates**: `spec-kit-implementation-loop`, `spec-readiness-gate`, `workspace-scope-safety`, `rbac-action-safety`, `operation-run-truth`, `evidence-anchor-contract`, `provider-freshness-semantics`, `product-surface-gate`, `filament-livewire-v5-change-loop`, `tcm-cutover-guard`, `browser-readonly-audit`, `pest-testing`, `browsertest`.
- **Hard-gate result**: PASS. No stop condition was hit.
- **Dependency reports**: present and treated as read-only context only:
  - `specs/414-tcm-first-coverage-core-cutover/implementation-report.md`
  - `specs/415-generic-content-backed-capture/implementation-report.md`
  - `specs/417-canonical-identity-engine/implementation-report.md`
- **Historical specs**: no completed historical spec was rewritten or stripped of validation, task, smoke, browser, or review history.

## Implementation

Added a DB-only Coverage v2 readiness read model, central badge mappings, and a native Filament operator surface.

- Route: repo-equivalent internal route `/admin/workspaces/{workspace}/environments/{environment}/tenant-configuration/coverage-v2`.
- Page: `apps/platform/app/Filament/Pages/TenantConfiguration/CoverageV2Readiness.php`.
- Tables/widgets: native `TableWidget` resource type registry and environment-scoped resource instance table.
- Detail model: linked primary columns open one read-only `Inspect` slide-over model for resource types and resource instances; no separate row action column.
- Productization follow-up: readiness summary now exposes one explicit reason and one next step; secondary technical table columns are available through native Filament column toggles instead of default-visible density.
- Navigation: secondary Inventory entry `Coverage v2`; does not replace Evidence Overview, Baseline Compare, Customer Review Workspace, Review Packs, Reports, or Restore surfaces.
- Read model: `apps/platform/app/Services/TenantConfiguration/CoverageV2ReadinessReadModel.php`.
- No migration, no persisted summary, no fallback reader, no v1 adapter, no `tenant_id` ownership.

## Files Changed

- Runtime: `AdminPanelProvider`, Coverage v2 page/widgets/read model, Blade page/modal.
- Badges: `BadgeDomain`, `BadgeCatalog`, and Coverage v2 badge mappers for readiness, coverage, evidence, identity, claim, support, and source class.
- Tests: one unit badge test, two feature test files, one browser smoke.
- Product audit: `docs/ui-ux-enterprise-audit/route-inventory.md`, `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`.
- Spec close-out: `tasks.md`, `implementation-report.md`.

## Product Surface

- **No-legacy posture**: canonical Coverage v2 internal readiness surface; no compatibility exception.
- **Product Surface Impact**: new internal operator page, navigation entry, two native read-only tables, one primary-link read-only inspect slide-over model.
- **UI Surface Impact**: route inventory updated as `UI-102`; design coverage matrix counts updated.
- **Page archetype**: Technical Annex Page / Read-only Registry Report.
- **Surface budget**: approved Product Surface Contract Technical Annex exception for summary plus two native tables. The two-table view is required to compare registry denominator truth with concrete environment evidence.
- **UI-EX-001**: none. Implementation stayed native Filament.
- **Canonical status vocabulary**: readiness uses `Ready`, `Needs attention`, `Blocked`, `Unknown`; Coverage v2 diagnostic dimensions use internal labels such as `Claim allowed`, `Claim limited`, `Claim blocked`, `Internal only`.
- **Technical Annex / deep-link demotion**: OperationRun links, evidence hash, source contract state, provider provenance, identity reason code, and source class are secondary diagnostics. Raw payloads and raw provider responses are not rendered.
- **Product Surface exceptions**: PSC Technical Annex surface-budget exception only.
- **List surface review**: PASS. Tables have scoped empty states, primary-link inspect columns instead of duplicate row/view actions, no bulk actions, no destructive actions, and diagnostics are disclosed through one inspect slide-over model.
- **Visible complexity outcome**: reduced for operators by replacing scattered DB/test/report inspection with one bounded read-only surface, adding explicit readiness reason/next-step text, and demoting secondary technical columns from the default table view through native Filament column toggles.

## UI Action Matrix

| Slot | Result |
|---|---|
| Header actions | none |
| Row primary action | linked primary columns open the read-only `Inspect` slide-over model for resource types and resource instances |
| Row URL | none; primary link columns are used because full-row click conflicts with dense comparison tables |
| More menu | none |
| Bulk actions | none |
| Destructive/high-impact actions | none |
| Remote/capture/sync/restore/export/publish actions | none |
| OperationRun link | secondary diagnostic link only when `Gate::allows('view', $run)` |

## Authorization And Scope

- Uses `Capabilities::EVIDENCE_VIEW`; no new capability was required.
- Workspace/non-member and environment-entitlement failures return 404 through existing scope helpers.
- Capability denial returns 403.
- Instance query is scoped by `workspace_id` and `managed_environment_id`.
- Provider connection filter options are scoped to the same workspace and managed environment.
- No workspace-wide aggregation was implemented.

## Redaction And Safety

- Raw payload, normalized payload, permission context JSON, secrets, tokens, raw provider responses, exception dumps, and stack traces are excluded from selected columns and rendered views.
- Read model selects safe latest-evidence fields only.
- Old labels and reason codes are not active UI truth: `Evidence gaps`, `Raw gaps`, `Primary gaps`, `ambiguous_match`, `policy_record_missing`, `foundation_not_policy_backed`, `meta_fallback`.
- Static guard confirmed the render path does not register Graph/TCM/provider clients or capture/start actions.
- No destructive action was added.

## Browser Proof

Command:

```bash
cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec418CoverageV2OperatorSurfaceSmokeTest.php
```

Result: PASS, `1 passed`, `42 assertions`, duration `4.95s`.

Proof covered: authorized route load, Livewire presence, no JavaScript errors, no console logs, readiness labels, explicit reason and next step, resource type/instance tables, inspect slide-over, authorized OperationRun diagnostic link, provider provenance, identity reason code, source schema hash, and absence of raw secrets/customer-ready wording.

Integrated Browser follow-up smoke:

- Result: PASS after applying pending local migrations for Specs 414/415/417.
- Route: `/admin/workspaces/3/environments/3/tenant-configuration/coverage-v2`.
- Context: authenticated admin browser session, workspace `wp`, managed environment `YPTW2`.
- Steps: reloaded route, verified readiness summary and full status labels, created a temporary same-scope Coverage v2 resource/evidence fixture, opened the resource instance inspect slide-over, verified provider provenance, evidence hash, source schema hash, and OperationRun diagnostic link, then removed the temporary fixture.
- Safety checks: no JavaScript console warnings/errors, no 500/SQLSTATE output, no Graph/TCM/provider-remote resource requests during render, no raw/normalized payload, permission context, token/secret sentinel, legacy v1 gap label, or customer-ready/certified wording in the page or inspect dialog.
- Clean-up: temporary local smoke resource, evidence row, and OperationRun were deleted; final reload returned to the empty resource-instance state without errors.

Screenshot artifact:

```text
apps/platform/tests/Browser/Screenshots/spec418-coverage-v2-operator-surface-readiness.png
```

## Human Product Sanity

- Can an operator understand readiness? PASS: summary status, reason, next step, counts, and top blockers are visible first.
- Are blockers grouped by actionable v2 states? PASS: identity, claim, evidence, source, and beta/fallback blockers are grouped deterministically.
- Does the page avoid technical object hub behavior? PASS: secondary navigation, bounded internal route, no mutation actions, and secondary technical table columns are demoted through native column toggles.
- Are raw/support details hidden by default? PASS: raw evidence fields are neither selected nor rendered.
- Is there exactly one inspect model? PASS: one read-only slide-over model reached from primary link columns; no row URL/action-column/bulk/menu duplication.
- Are old gap labels absent? PASS: feature/browser/static guard tests assert absence.

## Validation

```bash
cd apps/platform && ./vendor/bin/sail bin pint app/Filament/Pages/TenantConfiguration/CoverageV2Readiness.php app/Filament/Widgets/TenantConfiguration/CoverageV2ResourceTypesTable.php app/Filament/Widgets/TenantConfiguration/CoverageV2ResourceInstancesTable.php app/Services/TenantConfiguration/CoverageV2ReadinessReadModel.php tests/Feature/TenantConfiguration/CoverageV2ReadinessGuardTest.php tests/Feature/Filament/CoverageV2ReadinessPageTest.php tests/Browser/Spec418CoverageV2OperatorSurfaceSmokeTest.php tests/Unit/TenantConfiguration/CoverageV2ReadinessBadgeTest.php --format agent
```

Result: PASS, fixed import/spacing in `CoverageV2ResourceInstancesTable.php`.

```bash
cd apps/platform && ./vendor/bin/sail artisan test tests/Unit/TenantConfiguration/CoverageV2ReadinessBadgeTest.php tests/Feature/TenantConfiguration/CoverageV2ReadinessGuardTest.php tests/Feature/Filament/CoverageV2ReadinessPageTest.php
```

Result: PASS, `13 passed`, `155 assertions`, duration `6.52s`.

```bash
cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec418CoverageV2OperatorSurfaceSmokeTest.php
```

Result: PASS, `1 passed`, `42 assertions`, duration `4.95s`.

```bash
cd apps/platform && ./vendor/bin/sail artisan test --filter=ActionSurface
```

Result: Coverage v2 Action Surface guard PASS; full filtered run FAILS on four pre-existing non-Spec-418 failures (`FindingResource` primary drilldown, Operations URL nav context, Required Permissions copy, Provider Connection required-permissions action).

```bash
git diff --check
```

Result: PASS.

Static guard sweep: PASS. Expected raw-payload terms appear only as negative test fixtures/assertions, not runtime render code.

PostgreSQL lane: N/A. No migrations, indexes, constraints, or query-shape persistence changes were added.

## Filament / Livewire / Deployment

- **Livewire v4.0+ compliance**: PASS. Existing app uses Livewire v4; no Livewire v3 APIs introduced.
- **Provider registration location**: unchanged. Laravel provider registration remains in `apps/platform/bootstrap/providers.php`; page registration was added to `apps/platform/app/Providers/Filament/AdminPanelProvider.php`.
- **Global search**: N/A. No Filament Resource was added; no global-searchable resource exists for this surface.
- **Destructive actions**: none. The only registered action is read-only inspect behind primary link columns and does not mutate data.
- **Asset strategy**: no new assets; no additional `filament:assets` deployment requirement beyond existing deployment process.
- **Runtime impact**: no env vars, no queues, no scheduler, no storage/volume changes, no migrations.
- **Dokploy/Staging impact**: deploy code only; validate page on staging before any future customer/cutover activation work.

## Deferred Work

Customer-facing Coverage v2 proof, Evidence Overview conversion, Baseline Compare conversion, Review Pack/report output, Restore Readiness conversion, certification, capture/start actions, and legacy cutover/removal remain out of scope for later specs.