TenantAtlas/specs/149-queued-execution-reauthorization/plan.md

Implementation Plan: Queued Execution Reauthorization and Scope Continuity

Branch: 149-queued-execution-reauthorization | Date: 2026-03-17 | Spec: specs/149-queued-execution-reauthorization/spec.md Input: Feature specification from /specs/149-queued-execution-reauthorization/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/scripts/ for helper scripts.

Summary

Introduce one canonical execution-legitimacy contract for queued tenant-affecting operations so work is re-authorized when the worker is actually about to act, not only when the operator clicked Start. The implementation will reuse the existing OperationRun observability model, OperationRunService blocked outcome flow, TenantOperabilityService, and write-hardening seams, but add a shared run-time execution gate and middleware ordering that can fail closed before any side effects.

This is a support-layer and job-orchestration hardening feature, not a new UI surface or persistence redesign. The plan therefore focuses on extending the queue execution path already present in app/Jobs, app/Jobs/Middleware, app/Services/OperationRunService.php, app/Services/Providers, app/Services/Tenants, and app/Services/Hardening, then migrating representative high-risk job families first: provider-backed queued runs, restore or write jobs, inventory or sync jobs, and bulk orchestrator families.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12, Filament 5, Livewire 4, Pest 4, existing OperationRunService, TrackOperationRun, ProviderOperationStartGate, TenantOperabilityService, CapabilityResolver, and WriteGateInterface seams
Storage: PostgreSQL-backed application data plus queue-serialized OperationRun context; no schema migration planned for the first implementation slice
Testing: Pest 4 unit and feature coverage run through Laravel Sail
Target Platform: Laravel Sail web application with queue workers processing Filament-started and scheduled tenant-affecting operations Project Type: Laravel monolith web application
Performance Goals: Execution legitimacy checks must complete synchronously before side effects, add no render-time remote calls, and keep per-job startup overhead limited to current authoritative DB lookups plus existing support-layer evaluation
Constraints: Preserve existing Ops-UX run lifecycle ownership, terminal notification rules, centralized badge semantics, Filament v5 plus Livewire v4 compliance, provider registration in bootstrap/providers.php, and current route contracts; no new Graph bypasses, no asset or panel changes, and no weakening of 404 versus 403 semantics
Scale/Scope: One shared execution-legitimacy contract, one queue-middleware or execution-gate integration path, representative adoption across provider, restore, inventory or sync, and bulk job families, plus focused regression coverage under tests/Feature and tests/Unit

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Pre-Phase 0 Gate: PASS

• Inventory-first: PASS. This feature does not change inventory or snapshot ownership and only hardens when queued jobs may act.
• Read/write separation: PASS WITH HARDENING EMPHASIS. In-scope write paths remain queued, auditable, and confirmation-backed where already required. This feature strengthens fail-closed execution rather than broadening write authority.
• Graph contract path: PASS. No new Microsoft Graph domain is introduced, and existing provider or restore flows continue to rely on existing service layers instead of direct endpoint shortcuts.
• Deterministic capabilities: PASS. Capability enforcement remains tied to the canonical capability registry and resolver services; the feature extends when those checks happen.
• RBAC-UX planes: PASS. This feature remains in the admin /admin plane and tenant-context admin starts. Platform /system is not broadened. Non-members remain 404, members lacking capability remain 403 in authorization semantics.
• Workspace isolation: PASS. Execution legitimacy will re-check workspace and tenant scope using authoritative records, not UI memory.
• Tenant isolation: PASS. Tenant-bound queued work must still prove current tenant entitlement before acting.
• Destructive confirmation: PASS. No new destructive Filament action is introduced; existing start actions keep current confirmation rules.
• Global search safety: PASS. No global search behavior changes are planned.
• Run observability and Ops-UX: PASS. OperationRun remains the canonical observability record, start surfaces remain enqueue-only, Monitoring remains DB-only, and denied execution paths remain terminal run outcomes rather than ad-hoc notifications.
• Ops-UX lifecycle ownership: PASS. OperationRun.status and OperationRun.outcome remain service-owned through OperationRunService; the implementation must not let middleware or jobs bypass that rule.
• Ops-UX summary counts: PASS. Denied runs will continue using existing normalized summary counts and failure payload rules.
• Ops-UX guards: PASS WITH EXTENSION. Existing guard philosophy remains correct; this feature will add focused regression tests around execution-time denial rather than weaken current service-ownership rules.
• Ops-UX system runs: PASS. Scheduled or initiator-null runs remain visible in Monitoring without initiator-only terminal DB notifications.
• Automation and idempotency: PASS. Existing queue locks, idempotency, stale-queued handling, and dedupe contracts remain in force and become more reliable when legitimacy is rechecked before work starts.
• Data minimization: PASS. Denial reasons and audit entries will remain sanitized and secret-free.
• Badge semantics (BADGE-001): PASS. Existing blocked versus failed outcome semantics remain centralized through operation outcome helpers.
• UI naming (UI-NAMING-001): PASS. Operator-facing text continues to use domain wording such as blocked, failed, queued, and View run.
• Filament Action Surface Contract: PASS. Visible action inventories are unchanged; only their backend trust contract is hardened.
• Filament UX-001: PASS. No layout change is planned.
• Asset strategy: PASS. No new Filament or front-end assets are needed, so deployment guidance for php artisan filament:assets remains unchanged.

Post-Phase 1 Re-check: PASS

• The design extends existing support seams instead of introducing a second operation-run lifecycle model.
• No database migration, Graph-contract registry change, panel registration change, or asset build change is required for the first implementation slice.
• Livewire v4 and Filament v5 compliance remain intact, and provider registration stays in bootstrap/providers.php.
• Existing global-search requirements remain satisfied because no resource search contract is changed.

Project Structure

Documentation (this feature)

specs/149-queued-execution-reauthorization/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── execution-legitimacy.schema.json
│   └── no-external-api-changes.md
└── tasks.md

Source Code (repository root)

app/
├── Contracts/
│   └── Hardening/
├── Jobs/
│   ├── Middleware/
│   └── Operations/
├── Models/
│   ├── OperationRun.php
│   ├── ProviderConnection.php
│   ├── Tenant.php
│   └── User.php
├── Notifications/
│   └── OperationRunCompleted.php
├── Policies/
├── Services/
│   ├── Hardening/
│   ├── Inventory/
│   ├── OperationRunService.php
│   ├── Providers/
│   ├── Tenants/
│   └── Verification/
└── Support/
    ├── Auth/
    ├── Badges/
    ├── Operation*/
    ├── OpsUx/
    ├── Providers/
    └── Tenants/
tests/
├── Feature/
│   ├── Operations/
│   ├── Rbac/
│   ├── Restore/
│   └── Verification/
└── Unit/
    ├── Jobs/
    ├── Operations/
    └── Tenants/

Structure Decision: Use the existing Laravel monolith and harden the queue execution boundary in-place. Shared execution legitimacy should live beside the current job, tenant-operability, provider-start, and OperationRun seams rather than in a new standalone subsystem.

Phase 0 Research Summary

• OperationRunService already provides the core observability primitives needed for this feature: canonical queued runs, stale-queued failure handling, blocked terminal outcomes, sanitized failure payloads, and terminal audit plus notification emission.
• ProviderOperationStartGate is a strong dispatch-time gate for provider-backed operations, but it only validates legitimacy before enqueue and not again inside the worker. The new feature should extend the same contract to execution time rather than replacing it.
• TrackOperationRun currently marks runs as running before any legitimacy recheck. That ordering is too early for this spec because a denied-at-execution run must fail closed before side effects and ideally before being treated as a real running operation.
• The codebase already distinguishes a provider-blocked outcome through OperationRunOutcome::Blocked, finalizeBlockedRun(), and provider reason codes. That is the correct existing vocabulary to reuse for denied execution instead of inventing a parallel terminal state.
• Job families are inconsistent today. Provider Gen2 flows use an explicit start gate and connection resolution, restore or write jobs use localized WriteGateInterface checks inside the job, and other queued jobs often resolve tenant and user IDs directly without a canonical actor or scope continuity contract.
• TenantOperabilityService already centralizes tenant lifecycle and entitlement-aware decisions, but it has no queued-execution lane or execution-specific question. The first implementation slice should reuse its authority while introducing an execution-oriented decision seam rather than reintroducing local lifecycle checks in jobs.
• The audit-derived candidate notes already narrowed the must-answer questions for this feature: execution identity, non-operable tenant handling, retryable versus terminal denials, and OperationRun plus AuditLog representation. Those questions are fully resolved in research.md and carried into the design below.

Phase 1 Design

Implementation Approach

1. Add one shared execution-legitimacy contract ahead of side effects.

   • Introduce a support-layer decision boundary that evaluates whether a queued operation may still begin.
   • Keep OperationRunService as the lifecycle owner and treat the new decision layer as the gate that decides whether the run may transition from queued to meaningful execution.

2. Separate dispatch-time acceptance from execution-time legitimacy.

   • Keep existing dispatch gates such as ProviderOperationStartGate for enqueue-time checks, dedupe, and blocked preflight outcomes.
   • Add a second revalidation stage in the worker path so queue delay cannot bypass current authorization, scope, operability, or prerequisite truth.

3. Reuse existing blocked outcome semantics.

   • Represent execution-time refusal through OperationRunOutcome::Blocked plus structured reason codes and sanitized failure payloads.
   • Do not introduce a second terminal state just for execution reauthorization.

4. Distinguish human-bound authority from system authority explicitly.

   • Human-initiated runs remain actor-bound and must re-check the current actor's membership, entitlement, and capability at execution time.
   • Scheduled or initiator-null runs remain system-authority runs and must re-check allowed system execution plus tenant operability and prerequisites without pretending they are user-authorized actions.
   • The allowed system execution policy comes from one canonical operation-type allowlist owned by the execution legitimacy gate and fed only by trusted scheduler or system entry paths.

5. Move the first legitimacy check before TrackOperationRun marks a run as running.

   • Either introduce a new queue middleware that executes before TrackOperationRun or refactor the existing middleware flow so legitimacy is evaluated first.
   • The queue worker must not display a denied run as running before the denial is known.

6. Scope the first implementation slice to representative high-risk job families.

   • Provider-backed runs already using ProviderOperationStartGate.
   • Restore or write jobs currently guarded by WriteGateInterface inside the worker.
   • Inventory or sync jobs that resolve tenant and user at execution time and already use TrackOperationRun.
   • Bulk orchestrator or worker families that fan out destructive tenant-affecting work.

7. Keep the first slice schema-free and asset-free.

   • Store new authority or denial metadata inside existing OperationRun.context and failure payloads.
   • Reuse current Monitoring pages, notifications, and badges.
   • Prove the metadata contract with focused regression coverage so blocked execution remains observable without adding persistence fields.

Planned Workstreams

• Workstream A: Execution legitimacy core model
  Introduce or extend support-layer types for authority mode, execution context, legitimacy decision, denial classification, reason codes, and the initial retryability mapping. Keep them close to the existing operation and tenant support layers.

• Workstream B: Queue middleware and lifecycle ordering
  Refactor queue execution entry so legitimacy is evaluated before TrackOperationRun marks a run as running, while preserving service-owned run transitions and retry-safe behavior.

• Workstream C: Representative job-family adoption
  Apply the shared contract to provider-backed jobs, restore or write jobs, inventory or sync jobs, and at least one bulk orchestrator family so the new contract is proven across different execution shapes.

• Workstream D: Denial observability and audit semantics
  Normalize execution-time denial into blocked run outcomes, structured reason codes, Monitoring detail messaging, summary-count-safe payloads, and audit events that clearly separate policy refusal from runtime failure.

• Workstream E: Regression hardening
  Add focused Pest coverage for allowed paths, lost capability, lost entitlement, tenant non-operability, system-run behavior, retry behavior, representative job-family adoption, and direct-access 404 versus 403 semantics on canonical operations surfaces.

Testing Strategy

• Add unit tests for the execution-legitimacy decision layer, covering actor-bound and system-authority contexts plus structured denial reasons.
• Add unit tests for the canonical system-authority allowlist and the initial retryability mapping so gate decisions stay deterministic across job families.
• Add unit or integration tests for queue-middleware ordering to prove a run is not marked running before legitimacy passes.
• Add focused feature tests for representative provider-backed jobs showing dispatch-time acceptance plus execution-time denial when connection or scope truth changes.
• Add focused feature tests for representative provider-backed, restore, and system-authority flows showing still-legitimate execution continues successfully without false denial.
• Add focused feature tests for restore or write jobs showing existing write-gate checks are folded into the canonical execution contract rather than left as isolated local patterns.
• Add focused feature tests for inventory or sync jobs showing lost capability, lost tenant membership, and non-operable tenant outcomes are blocked before execution.
• Add focused feature tests for at least one bulk orchestrator family showing retries perform a fresh legitimacy evaluation and blocked execution remains observable.
• Add focused tests proving initiator-null runs do not emit initiator-only terminal database notifications while still recording blocked terminal outcomes in Monitoring.
• Add or update run-detail, notification, and canonical operations access tests to prove blocked execution remains distinct from generic failure while preserving 404 versus 403 semantics.
• Add focused tests proving blocked-run summary counts remain normalized through the canonical summary key contract.
• Add focused tests proving authority and denial metadata stays inside existing OperationRun context and failure payload structures with no schema change.
• Run the minimum focused Pest suite through Sail; no full-suite run is required for planning artifacts.

Complexity Tracking

No constitution violations or exceptional complexity are planned at this stage.