Add an atomic zone event outbox - 2

[Pixelobserver]

AI Policy

• I have read the Open Home Foundation AI Policy.

Select exactly one option that describes AI usage in this contribution:

• I have not used AI for this contribution.
• AI assistance was used for this contribution.
• AI fully generated the code for this contribution, but I've reviewed and understood it before submitting and will respond without AI during review.

Summary

Add a standalone, atomic file-backed outbox for pending zone events. This is part 2 of the split requested for #5629.

• Persist stable event identifiers, ordering, payloads and delivery-start metadata across recreation.
• Expire unstarted events after two minutes while retaining started deliveries for reconciliation.
• Coalesce only adjacent redundant unstarted beacon transitions for the same server and zone.
• Limit storage to 100 events without evicting started deliveries. If all entries are started, reject the append without modifying the store.
• Propagate read, decoding and write errors without silently replacing existing data.
• Add 23 focused XCTest cases covering persistence, ordering, coalescing, capacity, failure handling and payload compatibility.

This foundation does not activate outbox delivery in ZoneManager and does not depend on #5703. Delivery integration will follow separately.

Screenshots

N/A — internal persistence changes only; no visual changes.

Link to pull request in Documentation repository

N/A — this foundation does not activate user-facing functionality or configuration.

Any other notes

Completed validation:

• SwiftFormat 0.53.1.
• Diff whitespace and four-file feature scope.
• Test target membership and inclusion in the Tests-Unit scheme.

Pending CI verification:

• Xcode build and execution of the 23 test cases.
• Full lint checks.
• Measured patch coverage meeting the unchanged 90% threshold.

The test count describes the available test cases, not a completed test run.

[Copilot]

🟡 Changes recommended

Unresolved critical concurrency and coalescing issues, plus moderate expiry and error-propagation issues, block approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a standalone, persistent outbox for zone events without integrating delivery into ZoneManager.

Changes:

• Adds persisted pending-event models and outbox operations.
• Implements expiry, coalescing, capacity handling, and atomic file storage.
• Adds 23 focused XCTest cases.

File summaries

File	Summary
Tests/App/ZoneManager/ZoneEventOutbox.test.swift	Tests persistence, ordering, expiry, coalescing, capacity, and failure handling.
Sources/App/ZoneManager/ZoneEventOutbox.swift	Defines the outbox interface.
Sources/App/ZoneManager/PendingZoneEvent.swift	Defines persisted zone-event data.
Sources/App/ZoneManager/AtomicFileZoneEventOutbox.swift	Implements file-backed storage and queue management; has two critical and two moderate unresolved findings covering concurrency, coalescing, expiry, and error propagation.

Review details

Suppressed comments (1)

Sources/App/ZoneManager/AtomicFileZoneEventOutbox.swift:44

• Appending an already-expired event returns before load(). If the persisted file is corrupt or otherwise unreadable, this path silently hides the read/decoding error instead of propagating it as promised by the outbox contract, so callers can continue believing the store is usable. Load the existing events before applying the freshness guard (without saving the expired input).

            guard isFresh(event, at: now) else { return }

            var events = try freshEvents(from: load(), at: now)

• Files reviewed: 4/4 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.