[jonluca]

Summary

Stopping software video currently waits on the main actor for an asynchronous synchronizer removal. Retire the output and display layer asynchronously so teardown stays responsive, while keeping both alive until AVFoundation finishes removing the renderer.

What changed

• Request immediate removal with an invalid time, including when the synchronizer is stopped.
• Keep one retirement task per attachment; duplicate requests share it and cancellation cannot release the output or layer early.
• Require callers that reuse a layer to await retirement. Software sessions allocate a fresh host and layer.
• Add stopped-clock, unrelated-layer, duplicate-removal and cancellation/lifetime regression coverage; document the ownership contract.

Test plan

• Device / OS: Apple M4 Max, macOS 27.0.1, Xcode 27.1.
• Source media: none required for this regression; tests exercise real AVSampleBufferRenderSynchronizer and display-layer attachments, with a held completion for lifetime checks.
• swift test --disable-automatic-resolution --filter 'AudioOutput|Issue395RendererTimelineTests|Issue549RendererClockResumeTests|Sodalite104PausedFirstFrameTests|PublicAPIDocumentationTests' passes: 27 Swift tests plus 4 public API documentation tests.
• AetherEngine target builds with -warnings-as-errors.
• Documentation link validation and git diff --check pass.
• Physical iOS/tvOS playback and Atmos route transitions were not exercised.

Checklist

• CHANGELOG.md updated
• Conventional commit
• Engine-owned fix
• No public API change

[Copilot]

🟢 Approval recommended

The ownership lifecycle, cancellation handling, caller integration, and regression coverage have no identified blocking issues.

No open issues 🎉

What changed in this PR

This PR makes software video teardown nonblocking while preserving attachment ownership until AVFoundation completes renderer removal.

Changes:

• Replaces synchronous waiting with a shared retirement task that retains the output and display layer through cancellation.
• Updates software playback callers and documents the requirement to await retirement before reusing a layer.
• Adds regression coverage for stopped clocks, duplicate removal, unrelated layers, and cancellation lifetime.

File	Description
Tests/​AetherEngineTests/​AudioOutputRendererLifecycleTests.swift	Adds renderer retirement and lifetime regression tests.
Sources/​AetherEngine/​Native/​SoftwarePlaybackHost.swift	Uses layer-based attachment and asynchronous retirement.
Sources/​AetherEngine/​Audio/​AudioOutput.swift	Implements immediate removal with shared, lifetime-preserving retirement tasks.
docs/​architecture.md	Documents retirement ownership and layer reuse requirements.
CHANGELOG.md	Records the nonblocking teardown fix.

_{Review effort: Balanced}