TenantAtlas/specs/358-operationrun-queue-truth-foundation/plan.md

Implementation Plan: OperationRun Queue Truth Foundation

Branch: 358-operationrun-queue-truth-foundation | Date: 2026-06-06 | Spec: specs/358-operationrun-queue-truth-foundation/spec.md
Input: Feature specification from specs/358-operationrun-queue-truth-foundation/spec.md

Summary

Implement a narrow follow-up that aligns generic OperationRun queue truth across the existing lifecycle, freshness, progress, and monitoring-detail helpers. The slice must reuse current OperationRun persistence, current scheduled and adapter reconciliation behavior, current run links, and current authorization boundaries while removing contradictory active-work wording from shell, list, and canonical detail surfaces.

The repo already contains the foundations from Specs 149, 160, 233, 268, 270, and 272. This plan must not reopen those packages or invent a new reconciliation framework. It only corrects the remaining generic truth gap in current runtime code.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52, Filament 5.2.1, Livewire 4.1.4
Primary Dependencies: existing OperationRun monitoring helpers, OperationRunProgressContract, RunDurationInsights, OperationUxPresenter, current Filament Monitoring pages and shared OperationRun implementation seams, Pest 4.3
Storage: PostgreSQL operation_runs; no schema change planned
Testing: Pest Unit + Feature
Validation Lanes: fast-feedback, confidence
Target Platform: Laravel monolith in apps/platform
Project Type: web application
Performance Goals: keep current polling/query posture unchanged; no new queries or background work required for render-time truth
Constraints: no new OperationRun status/outcome fields, no new adapter registry, no new queue/job commands, no Graph calls, no notification policy change
Scale/Scope: one shared derived truth path plus current shell/list/detail monitoring surfaces and focused regression coverage

Likely Affected Repo Surfaces

• apps/platform/app/Support/OpsUx/OperationRunProgressContract.php
• apps/platform/app/Support/OpsUx/RunDurationInsights.php
• apps/platform/app/Support/OpsUx/OperationUxPresenter.php
• apps/platform/app/Support/Operations/OperationRunFreshnessState.php only if the current derivation needs a small bounded clarification
• apps/platform/resources/views/livewire/bulk-operation-progress.blade.php
• apps/platform/app/Filament/Pages/Monitoring/Operations.php as the current route-backed Operations hub surface
• apps/platform/resources/views/filament/pages/monitoring/operations.blade.php only if current workbench/list wording needs a bounded adjustment
• apps/platform/app/Filament/Resources/OperationRunResource.php only as the reused table/detail payload seam, not as a route-backed surface
• apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
• focused tests under:
  • apps/platform/tests/Unit/Support/OpsUx/
  • apps/platform/tests/Feature/OpsUx/
  • apps/platform/tests/Feature/Monitoring/
  • apps/platform/tests/Feature/Filament/
  • apps/platform/tests/Feature/Operations/

UI / Surface Guardrail Plan

• Guardrail scope: existing operator-facing monitoring surfaces only
• Affected routes/pages/actions/states/navigation/panel/provider surfaces:
  • tenant shell activity hint
  • /admin/workspaces/{workspace}/operations via App\Filament\Pages\Monitoring\Operations
  • /admin/workspaces/{workspace}/operations/{run} via App\Filament\Pages\Operations\TenantlessOperationRunViewer
• No-impact class, if applicable: N/A
• Native vs custom classification summary: native Filament surfaces plus one existing Livewire shell host
• Shared-family relevance: monitoring-state messaging, queue guidance, active-run hinting
• State layers in scope: shell, page, detail
• Audience modes in scope: operator-MSP, support-platform
• Decision/diagnostic/raw hierarchy plan: decision-first lifecycle truth before diagnostics; raw context remains secondary
• Raw/support gating plan: unchanged; raw/support evidence stays on current detail-only surfaces
• One-primary-action / duplicate-truth control: no new primary actions; existing row open and current shell open links remain authoritative
• Handling modes by drift class or surface:
  • contradictory stale vs queue guidance is hard-stop-candidate
  • wording-only cleanup with no behavioral effect is review-mandatory
• Repository-signal treatment: review-mandatory
• Special surface test profiles: monitoring-state-page, shared-detail-family
• Required tests or manual smoke: focused unit and feature proof only
• Exception path and spread control: any move toward new persistence, new adapter abstractions, or new queue-health orchestration is reject-or-split
• Active feature PR close-out entry: Guardrail / Smoke Coverage
• Navigation / Filament provider-panel handling: unchanged; no provider registration or panel path work

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: lifecycle freshness, progress derivation, queue guidance, shell render, canonical monitoring detail
• Shared abstractions reused:
  • OperationRunFreshnessState
  • OperationRunProgressContract
  • RunDurationInsights
  • OperationUxPresenter
  • existing OperationRunLinks and detail routes
• New abstraction introduced? why?: none by default; if one tiny queue-truth helper is required, it must stay inside App\Support\OpsUx and remain a derivation helper rather than a strategy or adapter registry
• Why the existing abstraction was sufficient or insufficient: the repo already centralizes the right ingredients, but the final operator wording remains split across helpers and render sites
• Bounded deviation / spread control: do not create a new framework layer where extending the current presenter or progress contract is sufficient

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes, reuse-only
• Central contract reused: current shared run-link, queued-toast, terminal-notification, and detail-route contract
• Delegated UX behaviors: queued toast wording, run links, browser events, and terminal notifications remain unchanged
• Surface-owned behavior kept local: only density and render ordering for shell/list/detail
• Queued DB-notification policy: unchanged
• Terminal notification path: unchanged
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: no
• Provider-owned seams: N/A
• Platform-core seams: platform-owned OperationRun monitoring truth only
• Neutral platform terms / contracts preserved: queued, running, lifecycle window, active operation, review worker health
• Retained provider-specific semantics and why: none
• Bounded extraction or follow-up path: none

Constitution Check

• Inventory-first: unchanged; no new source of truth.
• Read/write separation: unchanged; this is read-only monitoring truth.
• Deterministic capabilities: unchanged.
• Proportionality / anti-bloat: pass only if the implementation extends current helpers instead of creating a new framework.
• Persisted truth: no new tables, entities, or status families.
• State discipline: derived-only; no new persisted lifecycle category.
• Shared pattern first: extend existing Ops UX helpers and current monitoring surfaces.
• Workspace / tenant isolation: unchanged and still mandatory.
• RBAC-UX: no client-side authorization expansion; server-side boundaries remain the only access control.
• Test governance: unit + feature remain the narrowest honest proof.
• Filament v5 / Livewire v4 posture: unchanged; no provider-registration or asset change.

Test Governance Check

• Test purpose / classification by changed surface:
  • Unit: generic queue-truth derivation
  • Feature: current shell/list/detail rendering and authorization-safe presentation
• Affected validation lanes: fast-feedback, confidence
• Why this lane mix is the narrowest sufficient proof: the slice corrects shared derivation and rendered copy on current surfaces without introducing JS-heavy or browser-only behavior
• Narrowest proving command(s):
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OpsUx/ActivityFeedbackSurfaceTest.php tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php tests/Feature/MonitoringOperationsTest.php tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php tests/Feature/Monitoring/MonitoringOperationsTest.php tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php
  • git diff --check
• Fixture / helper / factory / seed / context cost risks: existing OperationRun fixtures and workspace membership helpers are sufficient; avoid widening defaults
• Expensive defaults or shared helper growth introduced?: none planned
• Heavy-family additions, promotions, or visibility changes: none
• Surface-class relief / special coverage rule: monitoring-state-page and shared-detail-family coverage is explicit
• Closing validation and reviewer handoff: reviewers should compare stale-active, fresh-active, and reconciled-terminal cases across shell, list, and detail and confirm that stale-active wording does not coexist with ordinary queue/progress reassurance
• Budget / baseline / trend follow-up: none expected
• Review-stop questions: Did the change add persistence? Did it invent a new adapter framework? Does any stale-active surface still combine stale attention with ordinary Waiting for worker., Progress details pending., or equivalent calm queue/progress reassurance?
• Escalation path: reject-or-split if scope widens into queue runtime redesign
• Active feature PR close-out entry: Guardrail / Smoke Coverage

Implementation Phases

Phase 1 — Confirm the shared queue-truth inputs

• Inventory the exact contradictory paths in:
  • OperationRunProgressContract
  • RunDurationInsights
  • OperationUxPresenter
  • current shell/list/detail renderers
• Freeze the current shared vocabulary for:
  • fresh queued/running
  • stale active
  • reconciled terminal
• Confirm that existing scheduled and adapter reconciliation commands remain context only

Phase 2 — Align the generic queue-truth derivation

• Extend existing helpers so freshness, queue guidance, and progress availability tell one story
• Keep phase/composite/determinate progress derived-only and subordinate to stale lifecycle truth
• Ensure unsupported or low-evidence cases remain cautious rather than overclaiming orphaned state

Phase 3 — Retrofit current monitoring surfaces

• Update the current shell banner so stale active work does not read as ordinary queue wait
• Update canonical list/detail guidance so they confirm the same lifecycle meaning
• Keep existing links, filters, and diagnostics structure unchanged

Phase 4 — Validate and lock the contract

• Add or update targeted unit + feature tests
• Run the focused validation commands
• Record any remaining bounded wording choices in the active feature close-out

Risks and Mitigations

• Over-escalation of healthy work: mitigate with explicit fresh-active negative assertions.
• Residual renderer drift: mitigate by covering shell, list, and detail in the same test set.
• Accidental framework expansion: mitigate by rejecting new registries, adapters, or persisted truth in review.

Project Structure

Documentation

specs/358-operationrun-queue-truth-foundation/
|-- spec.md
|-- plan.md
|-- tasks.md
`-- checklists/
    `-- requirements.md

Runtime surfaces likely to change later

apps/platform/app/Support/OpsUx/
|-- OperationRunProgressContract.php
|-- OperationUxPresenter.php
`-- RunDurationInsights.php

apps/platform/app/Support/Operations/
`-- OperationRunFreshnessState.php

apps/platform/app/Filament/
|-- Pages/Monitoring/Operations.php
|-- Pages/Operations/TenantlessOperationRunViewer.php
`-- Resources/OperationRunResource.php

apps/platform/resources/views/filament/pages/monitoring/
`-- operations.blade.php

apps/platform/resources/views/livewire/
`-- bulk-operation-progress.blade.php