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:

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:

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

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.

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.

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

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

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).

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.