ahmido
2a12729dc5
Implements platform feature branch `358-operationrun-queue-truth-foundation`. Target branch: `platform-dev`. Follow-up integration path after merge: `platform-dev` -> `dev`. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #429
210 lines
12 KiB
Markdown
210 lines
12 KiB
Markdown
# 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
|
|
|
|
```text
|
|
specs/358-operationrun-queue-truth-foundation/
|
|
|-- spec.md
|
|
|-- plan.md
|
|
|-- tasks.md
|
|
`-- checklists/
|
|
`-- requirements.md
|
|
```
|
|
|
|
### Runtime surfaces likely to change later
|
|
|
|
```text
|
|
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
|
|
```
|