Debounce workspace persistence writes

[trydis]

Summary by CodeRabbit

• New Features

  • Workspace save operations are now batched and grouped together.
  • Pending workspace changes automatically persist during application shutdown.

• Tests

  • Added comprehensive test coverage for batched save persistence behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a76da58a-2035-43fa-ac2e-d333a6ec80ef

📥 Commits

Reviewing files that changed from the base of the PR and between 05e1cc2 and 9d1cb36.

📒 Files selected for processing (7)

• Sources/Shellraiser/Services/Persistence/WorkspacePersistence.swift
• Sources/Shellraiser/Services/Workspaces/WorkspaceManager+WorkspaceLifecycle.swift
• Sources/Shellraiser/Services/Workspaces/WorkspaceManager.swift
• Tests/ShellraiserTests/CoalescingWorkspacePersistenceTests.swift
• Tests/ShellraiserTests/WorkspaceManagerLifecycleTests.swift
• Tests/ShellraiserTests/WorkspacePersistenceTests.swift
• Tests/ShellraiserTests/WorkspaceTestSupport.swift

---

📝 Walkthrough

Walkthrough

Introduces debounced workspace persistence through a new CoalescingWorkspacePersistence wrapper that coalesces rapid saves into single writes with configurable debounce intervals. Adds a flush() requirement to the WorkspacePersisting protocol for immediate persistence of pending writes. WorkspaceManager defaults to coalescing persistence when none is provided.

Changes

Cohort / File(s)	Summary
Persistence Protocol & Implementation Sources/Shellraiser/Services/Persistence/WorkspacePersistence.swift	Added flush() method requirement to WorkspacePersisting protocol (no-op in base WorkspacePersistence). Introduced CoalescingWorkspacePersistence wrapper that debounces saves, maintains pending snapshot state, cancels prior scheduled writes, and flushes on-demand or after debounce interval elapses. Removed pretty-print JSON encoding configuration.
Workspace Manager Integration Sources/Shellraiser/Services/Workspaces/WorkspaceManager.swift, Sources/Shellraiser/Services/Workspaces/WorkspaceManager+WorkspaceLifecycle.swift	Modified WorkspaceManager.init() to accept optional persistence parameter with automatic resolution to CoalescingWorkspacePersistence(backing: WorkspacePersistence()) when not provided. Added explicit flush() call in save() to immediately persist buffered writes.
Coalescing Persistence Tests Tests/ShellraiserTests/CoalescingWorkspacePersistenceTests.swift	Added comprehensive test suite covering debounce coalescing behavior, explicit flush semantics, and pending snapshot load semantics. Introduced RecordingWorkspacePersistence test double to track calls and snapshots.
Lifecycle & Integration Tests Tests/ShellraiserTests/WorkspaceManagerLifecycleTests.swift, Tests/ShellraiserTests/WorkspacePersistenceTests.swift, Tests/ShellraiserTests/WorkspaceTestSupport.swift	Added test verifying prepareForTermination flushes pending debounced persistence. Added test validating compact JSON encoding (no pretty-print). Updated test support InMemoryWorkspacePersistence with no-op flush() method.

Sequence Diagram

sequenceDiagram
    actor Client
    participant CoalescingWP as CoalescingWorkspacePersistence
    participant Queue as Debounce Queue
    participant BackingWP as BackingWorkspacePersistence
    participant Disk as Disk

    rect rgba(0, 150, 200, 0.5)
    Note over Client,Disk: Debounced Save Flow
    Client->>CoalescingWP: save(workspace)
    activate CoalescingWP
    CoalescingWP->>CoalescingWP: Update pendingSnapshot
    CoalescingWP->>Queue: Cancel prior scheduled save
    CoalescingWP->>Queue: Schedule debounced write (0.5s)
    deactivate CoalescingWP
    
    Note over Queue: Debounce interval elapses
    Queue->>CoalescingWP: Debounce timer fires
    activate CoalescingWP
    CoalescingWP->>BackingWP: persistPendingWorkspaces()
    activate BackingWP
    BackingWP->>Disk: Write pendingSnapshot to disk
    deactivate BackingWP
    deactivate CoalescingWP
    end

    rect rgba(150, 200, 0, 0.5)
    Note over Client,Disk: Explicit Flush Flow
    Client->>CoalescingWP: flush()
    activate CoalescingWP
    CoalescingWP->>Queue: Cancel scheduled save
    CoalescingWP->>BackingWP: persistPendingWorkspaces()
    activate BackingWP
    BackingWP->>Disk: Write pendingSnapshot to disk immediately
    deactivate BackingWP
    deactivate CoalescingWP
    end

Loading

Possibly related PRs

• Implement agent session resume and relaunch recovery #20 — Adds termination lifecycle hook (prepareForTermination) that explicitly calls flush() on persistence, ensuring pending debounced writes are flushed before shutdown; directly consumes the flush semantics introduced in this PR.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Debounce workspace persistence writes' directly and accurately summarizes the main change: introducing debounced/coalesced persistence through the new CoalescingWorkspacePersistence wrapper that delays and batches writes.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch persistence-writes-on-every-mutation

📝 Coding Plan

• Generate coding plan for human review comments

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}