Emit generation-scoped terminal outcomes with the final timeline

[omaralbeik]

Issue

Playback error and end events do not identify their cause or media generation. An unattributed stop can be synthesized as natural end, and no terminal payload preserves the final timeline before the observable mirror is reset.

Evidence

• PlayerEvent.swift:20-24 exposes payload-free .encounteredError.
• PlaybackEndCoordinator.swift:3-17 and :70-82 can synthesize .endReached from an unattributed stop.
• Player.swift:784-790 documents a stop/end race that can affect the next session.
• EventBridge.swift:174-224 queues .stopped before synthesized .endReached onto independent internal and public streams.
• Player+Events.swift:47-59 processes the internal stream on its own task, and :75-86 clears time, position, and buffer fill while handling .stopped. A public consumer can race ahead or behind that reset, so reading Player properties on .endReached cannot recover a reliable final snapshot.
• VLC commit 5e85463c0f7 adds native error/EOS/user-stop reasons after the bundled pin.

Expected

Emit exactly one structured terminal outcome per media generation: natural end, requested stop, replacement, cancellation, source/demux error, decoder error, renderer error, output error, or unknown native stop. Capture final time, duration, position, and relevant render counters before clearing the session.

Acceptance criteria

• Clean EOF, explicit stop, replacement, server close, malformed input, decode failure, renderer failure, and network loss are distinguishable.
• Every subscriber receives the same payload-bearing pre-reset final timeline, independent of task scheduling.
• A terminal event from generation A cannot end or classify generation B.
• An unattributed stop is never reported as a confirmed natural end.

[omaralbeik]

Blocked on a release, not on design. Recording why, because the obvious way to start this is unsafe today.

Criterion 1 wants clean EOF, explicit stop, replacement and the various failures to be distinguishable, and criterion 4 wants an unattributed stop never reported as a confirmed natural end. SwiftVLC currently infers endReached: a stopped that no library-issued stop, error, or attached MediaListPlayer accounts for. That inference is exactly what these criteria are asking to replace.

The authoritative answer exists. Patch 0015 exposes libvlc_stopping_reason_t and a reason field on media_player_media_stopping, giving eos, user and error directly from the engine. #138 landed the vendored header so Swift can see it.

It cannot be consumed yet. The binary everything links is the v1.0.0 release, which shipped patches 0001-0006. 0015 is not in it. So today:

• Sources/CLibVLC/include/vlc/libvlc_events.h declares a media_player_media_stopping with a reason field.
• The linked v1.0.0 libvlc.a was built from a struct without it, and writes only media.

Reading reason against that binary reads uninitialized union memory. It is harmless right now purely because nothing reads it. The moment this issue's work starts consuming it, that stops being true, and it would fail quietly rather than loudly.

So the ordering is forced: a release built from the patched tree has to ship before the reason can be wired into terminal outcomes. #141 adds a CI warning that names the patches outside the tested binary, so this stays visible instead of being rediscovered.

The generation-scoping half of this issue (criteria 2 and 3) has no such dependency and can proceed separately, alongside #81, #89 and #96, which want the same generation identifier.