Implementation Plan: Onboarding Lifecycle, Operation Checkpoints & Concurrency MVP

Branch: 140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp | Date: 2026-03-14 | Spec: spec.md Input: Feature specification from /specs/140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp/spec.md

Summary

Keep the existing Filament onboarding wizard as the operator shell, but move workflow truth out of ad hoc page-state inference and into canonical draft lifecycle fields plus existing OperationRun execution truth. The implementation will extend managed_tenant_onboarding_sessions with lifecycle, checkpoint, blocker, and version columns; centralize lifecycle recalculation and readiness evaluation in one onboarding service; move wizard mutations behind version-checked draft writes; and add conditional polling to Verify Access and Bootstrap so active checkpoint state reflects backend truth without manual refresh. Existing verification, bootstrap, audit, authorization, and Spec 139 assist behavior remain in place.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12, Filament v5, Livewire v4, PostgreSQL, Laravel Sail, Pest v4, existing OperationRunService, ProviderOperationStartGate, onboarding services, workspace audit logging
Storage: PostgreSQL tables including managed_tenant_onboarding_sessions, operation_runs, tenants, and provider-connection-backed tenant records
Testing: Pest feature, browser, and unit tests run through vendor/bin/sail artisan test --compact
Target Platform: Laravel web application in the /admin Filament panel, developed locally through Sail and deployed containerized
Project Type: Single web application
Performance Goals: Active Verify Access and Bootstrap states update within an active 5s poll interval while the page is open; no manual refresh is required to observe terminal checkpoint results; lifecycle recalculation remains request-bounded DB work
Constraints: No new onboarding routes; no new Graph call surfaces; no new operation backend; no lease or takeover model; Spec 139 assist must remain additive; OperationRun transitions remain service-owned; monitoring pages remain DB-only at render time; all relevant draft mutations must enforce optimistic locking
Scale/Scope: Workspace-scoped admin onboarding flow for managed tenants, small concurrent editor set but multi-tab and multi-operator safe, limited to the existing onboarding wizard, supporting services, database schema, and focused onboarding or Ops-UX tests

Constitution Check

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

Inventory-first: PASS. This feature changes workflow coordination only; it does not alter inventory or snapshot truth.
Read/write separation: PASS. The feature introduces draft writes and gating logic only. Verification, bootstrap, activation, cancel, and override audit paths remain explicit and test-covered.
Graph contract path: PASS. No new Graph calls or contract bypasses are introduced; verification and bootstrap continue to use existing providers and operation flows.
Deterministic capabilities: PASS. Capability checks remain registry-based and reusable through existing onboarding capability constants.
Workspace isolation: PASS. The feature remains in the workspace-admin plane and keeps deny-as-not-found semantics for non-members.
Tenant isolation: PASS. Tenant-bound verification, bootstrap, and activation truth still come from tenant-scoped records and access checks.
RBAC-UX 404/403 semantics: PASS. Existing onboarding authorization remains server-side; the plan preserves 404 for non-members and 403 for in-scope capability denial.
Destructive confirmations: PASS. No new destructive actions are added; existing Cancel onboarding confirmation remains in place.
Global search safety: PASS. No global search behavior is introduced or modified.
Run observability: PASS. Verify Access and Bootstrap continue reusing OperationRun, enqueue-only start surfaces, and Monitoring DB truth.
Ops-UX 3-surface feedback: PASS. The feature keeps queued toast intent feedback, in-wizard progress state, and existing terminal notification behavior, with no new ad hoc completion notifications.
Ops-UX lifecycle ownership: PASS. OperationRun.status and OperationRun.outcome transitions remain owned by OperationRunService.
Ops-UX summary counts and guards: PASS. No new summary key contract is introduced; existing guards remain applicable.
Ops-UX system-run rules: PASS. No initiator-null notification changes are introduced.
Automation, idempotency, and dedupe: PASS. Existing verification and bootstrap dispatch continue through current gate and run services.
Data minimization: PASS. The feature adds workflow metadata only and does not broaden secrets or payload storage.
Badge semantics: PASS. Any new lifecycle or checkpoint badge presentation must route through the existing centralized status semantics rather than page-local mappings.
UI naming: PASS. Operator language remains aligned with current onboarding and Spec 139 terminology.
Filament Action Surface Contract: PASS WITH EXEMPTION. The wizard remains a composite page, and Step 3 or Step 4 continue using documented in-step checkpoint exemptions rather than list-table affordances.
Filament UX-001: PASS WITH EXEMPTION. The feature extends an existing wizard surface rather than creating new create, edit, or view pages.

No constitution violations require justification at plan time.

Project Structure

Documentation (this feature)

specs/140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── onboarding-lifecycle-logical-contract.openapi.yaml
└── tasks.md

Source Code (repository root)

app/
├── Filament/Pages/Workspaces/
│   └── ManagedTenantOnboardingWizard.php
├── Models/
│   └── TenantOnboardingSession.php
├── Services/
│   ├── Onboarding/
│   │   ├── OnboardingDraftResolver.php
│   │   ├── OnboardingDraftStageResolver.php
│   │   ├── OnboardingLifecycleService.php
│   │   └── OnboardingDraftMutationService.php
│   ├── OperationRunService.php
│   └── Providers/
│       └── ProviderOperationStartGate.php
├── Support/Onboarding/
│   └── OnboardingDraftStatus.php
└── Notifications/
    └── OperationRunCompleted.php

database/
├── migrations/
└── factories/

resources/
└── views/
    ├── filament/pages/workspaces/
    │   └── managed-tenant-onboarding-wizard.blade.php
    └── filament/forms/components/
        └── managed-tenant-onboarding-verification-report.blade.php

tests/
├── Browser/
│   ├── OnboardingDraftRefreshTest.php
│   └── OnboardingDraftVerificationResumeTest.php
├── Feature/
│   ├── Onboarding/
│   │   ├── OnboardingActivationTest.php
│   │   ├── OnboardingDraftAccessTest.php
│   │   ├── OnboardingDraftAuthorizationTest.php
│   │   ├── OnboardingDraftLifecycleTest.php
│   │   ├── OnboardingDraftMultiTabTest.php
│   │   ├── OnboardingVerificationAssistTest.php
│   │   └── OnboardingVerificationTest.php
│   ├── OpsUx/
│   └── Rbac/
└── Unit/
    └── Onboarding/
        ├── OnboardingLifecycleServiceTest.php
        └── OnboardingDraftStageResolverTest.php

Structure Decision: Use the existing single Laravel application structure. Most implementation work should land in the onboarding wizard page, onboarding services, onboarding support enums or value objects, one migration, and focused Feature, Browser, and Unit tests. No new top-level module or route layer is needed.

Phase 0 Research Summary

Current onboarding draft truth is split between TenantOnboardingSession.state, current_step, completed_at, cancelled_at, and ad hoc reads of OperationRun state. Research confirms the smallest additive change is to promote lifecycle and checkpoint metadata into first-class session columns.
Verification currently requires manual refresh in the wizard. Existing repo patterns use conditional wire:poll in Livewire views and page shells, and this feature standardizes on an active 5s cadence to match existing operation-detail behavior without a new real-time stack.
Current wizard mutations save the onboarding session directly in the page class. That is the main seam for introducing centralized version checks and lifecycle recalculation.
Verification start already flows through ProviderOperationStartGate and bootstrap start already records selected operation runs. Those existing services should remain the dispatch boundary.

Phase 1 Design Summary

Add top-level draft fields for version, lifecycle_state, current_checkpoint, last_completed_checkpoint, reason_code, and blocking_reason_code.
Introduce controlled lifecycle and checkpoint value types in the onboarding support layer.
Introduce a centralized onboarding lifecycle service responsible for recalculation, readiness evaluation, and mapping current run or connection conditions into canonical lifecycle fields.
Introduce a versioned draft mutation path so all onboarding writes compare expected version and fail atomically on mismatch.
Add conditional 5s polling and checkpoint refresh hooks to Verify Access and Bootstrap using existing Livewire polling patterns.
Keep Spec 139 assist visibility and new-tab deep-dive continuity as a derived concern of Step 3 state rather than as a competing lifecycle owner.

Post-Design Constitution Check

Re-check result: PASS.
The design preserves Livewire v4 and Filament v5 compatibility, keeps provider registration unchanged in bootstrap/providers.php, introduces no new global-searchable resources, keeps Cancel onboarding as the only destructive action with confirmation, reuses existing asset strategy, and adds a focused testing plan for lifecycle, checkpoint, authorization, conflict, and browser polling behavior.

Complexity Tracking

No constitution exceptions or complexity waivers are required for this plan.

10 KiB Raw Blame History