# Implementation Plan: Spec 362 - Sync, Capture, and Backup Operation Semantics **Branch**: `362-sync-capture-backup-operation-semantics` | **Date**: 2026-06-07 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/362-sync-capture-backup-operation-semantics/spec.md` **Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/362-sync-capture-backup-operation-semantics/spec.md` **Note**: This plan is repo-aware and preparation-only. No application implementation is performed in this step. ## Summary Extend the current `OperationRun` reconciliation path so selected current-proof families can finalize truthfully after stale, interrupted, or late-finishing execution: - `inventory.sync` - `baseline.capture` - `backup.schedule.execute` Reuse only current repo-real proof seams and the existing `OperationRunOutcome` enum. Add no new persistence, no new queue family, and no new UI framework. Keep `policy.sync`, `backup_set.update`, restore, and generic report families fail-closed and explicitly deferred. ## Technical Context **Language/Version**: PHP 8.4.15 **Primary Dependencies**: Laravel 12.52, Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1 **Storage**: PostgreSQL 16 (`operation_runs`, `inventory_items`, `baseline_snapshots`, `policy_versions`, `backup_sets`, `backup_items`) **Testing**: Pest Unit + Feature + one bounded Browser smoke **Validation Lanes**: fast-feedback, confidence, browser **Target Platform**: Laravel monolith in Sail / Dokploy container workflow **Project Type**: single web application (`apps/platform`) **Performance Goals**: no new polling or background family; reconciliation remains bounded to current stale/queued scan paths and current operator-facing read surfaces **Constraints**: no new schema, no new operation type, no new panel/provider, no new Filament asset strategy, no broad sync/backup taxonomy rewrite, no Graph calls during render **Scale/Scope**: narrow `OperationRun` truth hardening over exactly three current-proof families plus explicit unsupported-family handling ## UI / Surface Guardrail Plan - **Guardrail scope**: changed surfaces - **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: - `apps/platform/app/Filament/Pages/Monitoring/Operations.php` - `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` - current inventory, baseline, and backup detail surfaces only if outcome wording or safe related links need alignment - **No-impact class, if applicable**: N/A - **Native vs custom classification summary**: native Filament surfaces with shared `OperationRun` and current proof/detail helpers - **Shared-family relevance**: `OperationRun` monitoring family plus current inventory, baseline, and backup detail families - **State layers in scope**: page, detail, URL-query - **Audience modes in scope**: operator-MSP, support-platform - **Decision/diagnostic/raw hierarchy plan**: decision-first on the Operations hub, diagnostics-second on run detail, deeper proof on current detail pages only - **Raw/support gating plan**: raw context stays in current diagnostic sections only - **One-primary-action / duplicate-truth control**: keep current inspect/open paths; do not add a second competing outcome summary on related proof pages - **Handling modes by drift class or surface**: review-mandatory - **Repository-signal treatment**: review-mandatory for any attempt to widen scope into `policy.sync`, generic backup taxonomy work, or new persistence - **Special surface test profiles**: monitoring-state-page - **Required tests or manual smoke**: functional-core plus one bounded browser smoke - **Exception path and spread control**: none - **Active feature PR close-out entry**: Guardrail / Smoke Coverage - **UI/Productization coverage decision**: existing route and page families remain sufficient; no new coverage artifact is expected by default - **Coverage artifacts to update**: none by default - **No-impact rationale**: existing reachable operations and current proof/detail surfaces only; no new route family or navigation entry is planned - **Navigation / Filament provider-panel handling**: no panel, provider, or navigation change - **Screenshot or page-report need**: no by default; use bounded browser smoke unless implementation proves a material hierarchy shift ## Shared Pattern & System Fit - **Cross-cutting feature marker**: yes - **Systems touched**: - `App\Services\OperationRunService` - `App\Services\Operations\OperationLifecycleReconciler` - `App\Services\AdapterRunReconciler` - `App\Support\Operations\Reconciliation\OperationRunReconciliationRegistry` - `App\Support\Operations\Reconciliation\ReconciliationResult` - `App\Support\OperationRunLinks` - `App\Support\Ui\GovernanceArtifactTruth\ArtifactTruthPresenter` - current inventory, baseline, and backup proof/detail helpers - **Shared abstractions reused**: current adapter contract, service-owned reconciliation writes, current monitoring/detail presenters, current scope-safe links, and current proof models - **New abstraction introduced? why?**: at most one small shared proof helper if duplicated completeness rules across the three selected families become noisy; no generic sync/backup framework is allowed - **Why the existing abstraction was sufficient or insufficient**: the registry and service-owned write seam already exist, but they currently stop short of selected sync/capture/backup proof semantics and cannot yet represent partial success inside the reconciliation-result helper path - **Bounded deviation / spread control**: keep family-specific proof logic local to `App\Support\Operations\Reconciliation\`; do not add provider-neutral engines, new persistence, or a second lifecycle owner ## OperationRun UX Impact - **Touches OperationRun start/completion/link UX?**: yes - **Central contract reused**: current `OperationRunService`, `OperationLifecycleReconciler`, registry-backed reconciliation, `OperationRunLinks`, and existing monitoring/detail presenters - **Delegated UX behaviors**: existing queued toast, run link, run-enqueued browser event, and terminal notification paths remain unchanged - **Surface-owned behavior kept local**: wording and placement only - **Queued DB-notification policy**: unchanged - **Terminal notification path**: unchanged central lifecycle mechanism - **Exception path**: none ## Provider Boundary & Portability Fit - **Shared provider/platform boundary touched?**: no new provider seam - **Provider-owned seams**: N/A - **Platform-core seams**: `OperationRun`, current proof/result truth, current scope-safe links - **Neutral platform terms / contracts preserved**: `operation`, `coverage`, `snapshot`, `backup set`, `reconciliation`, `partially succeeded`, `blocked` - **Retained provider-specific semantics and why**: only already-recorded provider error codes or readiness reasons remain secondary evidence; no new provider-owned truth is introduced - **Bounded extraction or follow-up path**: `policy.sync`, broader counted-progress, and broader backup/restore taxonomy remain separate follow-ups ## Constitution Check *GATE: Must pass before implementation starts. Re-check if scope changes.* - Inventory-first: PASS. The selected proof paths read current inventory, baseline snapshot, and backup artifact truth instead of creating a new truth layer. - Read/write separation: PASS. Adapters read proof only and finalize runs only through `OperationRunService`. - Graph contract path: PASS. No new Graph surface or render-time Graph call is planned. - Deterministic capabilities: PASS. No new capability derivation is introduced. - Workspace and tenant isolation: PASS. Adapters must use run-owned workspace/environment scope and current related resource policies. - Run observability: PASS. `OperationRun` remains the only lifecycle owner; no shadow table or duplicate outcome store is introduced. - TEST-GOV-001: PASS. Unit + Feature + bounded Browser are the narrowest honest proof. - PROP-001 / ABSTR-001: PASS only if any new helper stays local to the three selected families and does not become a generic sync/backup engine. - PERSIST-001 / STATE-001: PASS. No new persisted truth or new outcome family is planned. - XCUT-001 / LAYER-001: PASS. Extend the current registry and presenters; do not create parallel operator language. - UI-SEM-001 / UI-FIL-001 / UI-COV-001: PASS. Existing native surfaces only; no new page family or asset strategy. - BADGE-001: PASS. Existing outcome and badge semantics remain authoritative; only truthful mapping changes are allowed. ## Test Governance Check - **Test purpose / classification by changed surface**: Unit for family resolution, partial-success helper behavior, proof rules, and idempotency; Feature for run finalization, wrong-scope rejection, DB-only render-path protection, and operator-facing fallthrough; Browser for the changed Operations hub/detail wording only if visible copy changes - **Affected validation lanes**: fast-feedback, confidence, browser - **Why this lane mix is the narrowest sufficient proof**: the feature is primarily service and model coordination with a small amount of operator-visible wording fallout; no PGSQL-only schema behavior is introduced - **Narrowest proving command(s)**: - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Unit/Support/Operations/Reconciliation/Spec362SelectedFamilyRegistryResolutionTest.php tests/Unit/Support/Operations/Reconciliation/Spec362SelectedFamilyProofRulesTest.php tests/Unit/Support/Operations/Reconciliation/Spec359ReconciliationResultTest.php tests/Feature/Operations/Spec362*` - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Feature/MonitoringOperationsTest.php tests/Feature/Inventory/InventorySyncServiceTest.php tests/Feature/Inventory/RunInventorySyncJobTest.php tests/Feature/Baselines/BaselineCaptureTest.php tests/Feature/Baselines/BaselineCaptureGapClassificationTest.php tests/Feature/Baselines/BaselineCaptureAmbiguousMatchGapTest.php tests/Feature/BackupScheduling/RunBackupScheduleJobTest.php tests/Feature/Console/ReconcileBackupScheduleOperationRunsCommandTest.php` - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec362SyncCaptureBackupSemanticsSmokeTest.php` - **Fixture / helper / factory / seed / context cost risks**: existing workspace/environment, `OperationRun`, `InventoryItem`, `BaselineSnapshot`, `BackupSet`, and `BackupItem` factories only; no new global defaults should be introduced - **Expensive defaults or shared helper growth introduced?**: no - **Heavy-family additions, promotions, or visibility changes**: one explicit Browser smoke only - **Surface-class relief / special coverage rule**: monitoring-state-page - **Closing validation and reviewer handoff**: reviewers should verify that partial success only lands when proof is truly incomplete but usable, that blocked remains distinct from failed, that weaker families stay unsupported, and that no new persistence or operation type appears - **Budget / baseline / trend follow-up**: none expected - **Review-stop questions**: does the feature overclaim success, broaden into `policy.sync`, or create a second lifecycle truth? - **Escalation path**: document-in-feature if a weaker family still needs a named follow-up; reject-or-split if implementation tries to widen into generic sync/backup semantics - **Active feature PR close-out entry**: Guardrail / Smoke Coverage - **Why no dedicated follow-up spec is needed now**: the three selected families already expose stronger current proof than the weaker families, so they can be implemented safely as one bounded slice ## Repo-Verified Runtime Surfaces Likely Affected - `apps/platform/app/Services/OperationRunService.php` - `apps/platform/app/Services/Operations/OperationLifecycleReconciler.php` - `apps/platform/app/Services/AdapterRunReconciler.php` - `apps/platform/app/Support/Operations/Reconciliation/OperationRunReconciliationRegistry.php` - `apps/platform/app/Support/Operations/Reconciliation/ReconciliationResult.php` - `apps/platform/app/Support/OperationCatalog.php` - `apps/platform/app/Support/OperationRunType.php` - `apps/platform/app/Support/OperationRunLinks.php` - `apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php` - `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php` - `apps/platform/app/Models/OperationRun.php` - `apps/platform/app/Models/InventoryItem.php` - `apps/platform/app/Models/BaselineSnapshot.php` - `apps/platform/app/Models/BackupSet.php` - `apps/platform/app/Models/BackupItem.php` - `apps/platform/app/Services/Inventory/InventorySyncService.php` - `apps/platform/app/Support/Inventory/InventoryCoverage.php` - `apps/platform/app/Services/Baselines/BaselineCaptureService.php` - `apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php` - `apps/platform/app/Services/BackupScheduling/BackupScheduleDispatcher.php` - `apps/platform/app/Jobs/RunBackupScheduleJob.php` - `apps/platform/app/Console/Commands/TenantpilotReconcileBackupScheduleOperationRuns.php` - `apps/platform/app/Filament/Pages/Monitoring/Operations.php` - `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` - current inventory, baseline, and backup detail surfaces only as required by runtime fallout - `apps/platform/tests/Unit/Support/Operations/Reconciliation/*` - `apps/platform/tests/Feature/Operations/*` - `apps/platform/tests/Feature/Inventory/*` - `apps/platform/tests/Feature/Baselines/*` - `apps/platform/tests/Feature/BackupScheduling/*` - `apps/platform/tests/Feature/Console/ReconcileBackupScheduleOperationRunsCommandTest.php` - `apps/platform/tests/Browser/Spec360OperationRunCanonicalCutoverSmokeTest.php` plus new Spec 362 smoke coverage as needed ## Technical Approach 1. Re-verify the exact current proof seams and operation types before runtime edits. 2. Reuse the current registry and service-owned lifecycle write seam. 3. Add bounded family-specific adapters for: - inventory sync - baseline capture - backup schedule execution 4. Add a bounded reconciliation-result helper for partial success only if the current object cannot express the existing enum cleanly. 5. Keep weaker families explicit and unsupported rather than broadening proof heuristics. 6. Reuse current operations and current proof/detail presentation seams for operator-visible fallout. ## Risk Controls - Fail closed on ambiguous, missing, wrong-scope, or stale proof. - No adapter may mutate inventory, baseline, or backup artifacts. - No new operation type, queue family, or lifecycle table may be introduced. - Touched Operations hub/detail render paths must remain DB-only and keep the existing no-Graph render guard green; if any related proof host surface changes render behavior, extend the smallest existing host render guard before merge. - If `policy.sync` or another weaker family still appears to need proof semantics, record a named follow-up instead of widening this package. - No new panel/provider, asset registration, or destructive action may be added in this slice. ## Implementation Phases ### Phase 1: Baseline and Repo-Truth Inventory Confirm current operation types, run-start context, current proof models, and current operator-surface fallout. Explicitly verify that `policy.sync` remains weaker than `inventory.sync`. ### Phase 2: Foundational Reconciliation Contract Add the bounded partial-success helper if needed, selected-family registry resolution, and proof-rule tests before family-specific runtime edits. ### Phase 3: Inventory Sync Truth Add proof-based inventory sync reconciliation and the focused operations/inventory tests. ### Phase 4: Baseline Capture Truth Add proof-based baseline capture reconciliation and the focused operations/baseline tests. ### Phase 5: Backup Schedule Execution Truth Add proof-based backup schedule reconciliation and the focused operations/backup tests. ### Phase 6: Unsupported-Family Boundaries Keep `policy.sync`, `backup_set.update`, restore, and weaker families explicit and unsupported in this slice, and record the defer path instead of widening. ### Phase 7: Validation and Close-Out Run scoped Pest and Browser validation, confirm no migration/assets/panel drift, and record the supported versus explicitly deferred families. ## Project Structure ### Documentation (this feature) ```text specs/362-sync-capture-backup-operation-semantics/ ├── spec.md ├── plan.md ├── tasks.md └── checklists/requirements.md ``` ### Source Code (repository root) ```text apps/platform/app/Services/ apps/platform/app/Support/Operations/Reconciliation/ apps/platform/app/Support/OpsUx/ apps/platform/app/Support/Ui/GovernanceArtifactTruth/ apps/platform/app/Services/Inventory/ apps/platform/app/Services/Baselines/ apps/platform/app/Services/BackupScheduling/ apps/platform/app/Jobs/ apps/platform/app/Console/Commands/ apps/platform/app/Filament/Pages/ apps/platform/tests/Unit/ apps/platform/tests/Feature/ apps/platform/tests/Browser/ ``` ## Assumptions - The current registry and correlation seams visible in `platform-dev` are authoritative enough for this bounded follow-through. - `inventory.sync`, `baseline.capture`, and `backup.schedule.execute` retain their current proof models and current operator meaning. - `policy.sync` remains intentionally out of scope because its current proof is weaker than the selected families. ## Open Preparation Decision Spec 360 artifacts still exist as open context, but current runtime inspection already shows the registry, correlation resolver, and reconciliation write seam that Spec 362 needs. That is sufficient for preparation readiness. If implementation later proves a missing Spec 360 canonical-cutover delta still blocks safe adapter work, that prerequisite must be handled explicitly and minimally rather than being smuggled into Spec 362 as unrelated drift.