PyLoxone-Audio 0.1.0__tar.gz → 0.1.1__tar.gz

pyloxone_audio-0.1.1/API.md

@@ -0,0 +1,123 @@
+# PyLoxone-Audio 0.1.1 — API and compatibility
+
+A separately installable Apache-2.0 Python library containing the concrete native
+audio implementation used by one existing PyLoxone integration. This is not a
+second integration, new login, facade-only prototype or claim of upstream automatic
+adoption. Public availability is verified separately by the release production gate. See NOTICE.md for attribution/provenance.
+
+## Concrete public API and ownership
+
+The explicit exports in pyloxone_audio/__init__.py are the public API:
+
+- AudioServerCommands(host, current_credentials) owns bounded native command
+  authentication, correlation, cancellation, close and uncertain-write fences.
+  The callback supplies the current username/token; there is no token persistence.
+- AudioServerListener and AudioEventReceiver receive/parse exact-player metadata;
+  AudioZoneMetadata is the neutral snapshot. AudioMetadataCoordinator supports
+  exact-player subscriptions, optional host task scheduling, start and awaited stop.
+- AudioCatalogue(commands, player_id), CatalogueTarget, ConfiguredSource and
+  AudioFavourite own discovery, opaque browser targets, last-good source history,
+  configured favourites, provider/account qualification and neutral search values.
+- MediaNode, SearchResult and MediaKind contain no HA entity or UI dependency.
+- async_select_catalogue, async_select_favourite, async_select_radio_station and
+  async_native_catalogue_noop own source dispatch, settlement and fresh exact-room
+  provider feedback. Browser selection remains strict exact-item proof. Source
+  return for a saved exact item requires matching track feedback, and may attempt
+  at most one optional best-effort position restore after bounded seek readiness. Optional failure does not
+  undo confirmed playback; a fixed warning is emitted, never exception payloads.
+- async_source_route owns native/retained routing and safety decisions; SourceRoute
+  and SourceContentRequiredError describe its outcomes. Hosts provide lifecycle/
+  newest-request liveness callbacks and snapshot bootstrap. There is no HA-provider
+  bridge callback. Native identity checks, uncertain-write fences and cancellation
+  remain; no blind replay/retry or substitute content is introduced.
+- manual_seek_supported, manual_seek_position, native_track_identity,
+  ManualSeekQualification and async_seek_track retain strict current-track/manual
+  seek capability, account/identity, echo and observed-progress qualification.
+- passive_history_eligible and confirmed_library_session own reusable native
+  history eligibility. Genuine ordered observed feedback is distinct from intent.
+- async_send_prepared_announcement handles prepared bounded WAV bytes through
+  the native event operation; the host supplies an existing lazy HTTP session.
+- audioserver_uri and parse_audio_events retain their concrete native semantics.
+
+SourceEnvironment(clock=callable) is immutable per-consumer clock configuration.
+Pass environment= to source/seek/routing functions when injecting a clock.
+The callable must return aware UTC datetimes in the metadata.received_at domain.
+The default is the library's aware UTC clock, not HA or another consumer's state.
+Its async_observed_change method executes the concrete native settlement algorithm;
+asyncio deadlines remain monotonic. No process-wide clock replacement is required.
+
+The host retains HA setup/entities/registries/services, newest-request tasks and
+unload cancellation, existing native authentication, error translation, artwork and
+HA media/TTS preparation. It must keep liveness checks valid across awaits, drain
+owned tasks before teardown and close commands before metadata/token owners.
+ManualSeekQualification must be checked against actual current native metadata
+and the host revision/duration, not merely a cached UI value. Optional native
+completion requires settled dispatch and fresh exact-room/provider/account proof.
+
+## Native modes
+
+`AudioRepeatMode` (OFF=0, ALL=1, ONE=3) and `audio_mode_supported` are public
+HA-independent exports. `AudioZoneMetadata` adds nullable `shuffle`, typed
+`repeat` and connection-qualified `shuffle_switch_supported` state.
+`AudioServerCommands.async_set_shuffle(player_id, bool, *, is_current=...)` and
+`async_set_repeat(player_id, AudioRepeatMode, *, is_current=...)` send exactly one
+explicit native player request through existing authentication/serialization and
+strictly validate its reply. The host qualifies fresh native permissions/state
+and maintains its liveness callback; no Spotify bridge/API or optimistic metadata
+write is involved. See [NATIVE-MODES.md](NATIVE-MODES.md) for firmware, partial
+repeat capability, standard HA mapping and unknown/lifecycle semantics.
+
+## Optional structured diagnostics (new 0.1.1 increment)
+
+`pyloxone_audio.diagnostic_events` defines the version1 fixed-field schema,
+`DiagnosticEmitter`, `diagnostics_enabled` and exception-isolating
+`diagnostic_event`. `AudioServerCommands(..., diagnostics=None)` and
+`AudioMetadataCoordinator.diagnostics` accept an optional observer. Its `enabled`
+must be literally true; its synchronous `emit(stage, **fields)` must only enqueue,
+never await/write files. Callers gate detailed construction before invoking it.
+The emitter allowlists fields/routes and keyed pseudonyms before calling its sink.
+Foreign observer exceptions are isolated. Authentication data never enters events.
+
+The HA adapter supplies `EntryAudioDiagnostics`/`RollingJournal`, one diagnostic
+switch and the existing admin config-entry download. These are host internals,
+not a portable HA/storage dependency or a second integration. Separate HA Store
+preference/salt avoids reload-on-options. See [DIAGNOSTICS.md](DIAGNOSTICS.md) for
+the supported enable/export workflow, exact bounds and evidence/privacy limits.
+
+This narrowly supersedes the earlier blanket instrumentation exclusion. The old
+`pyloxone_audio.diagnostics`, `SourceDiagnostics`, `trace_source_action`, raw
+snapshot logging and `last_source_failure` API remain removed, not compatibility
+stubs. No source/playback, authentication, fence, clock or retry policy changes.
+
+## Tested boundary and installation
+
+Only the canonical Python 3.14.7 / HA 2026.9.1 / websockets 15.0.1 /
+pycryptodome 4.0.1 / aiohttp 3.14.3 environment is exercised here. The metadata
+requires Python >=3.14 but is not a wider tested compatibility promise. HA-free
+portable runs explicitly reject HA imports. External I/O in tests is synthetic;
+AF_UNIX wire tests use actual websocket/crypto implementations with TCP blocked.
+No all-version/firmware/room or universal physical playback claim follows from these tests.
+
+For Python consumers, install the public named pin `PyLoxone-Audio==0.1.1` in a
+supported isolated environment. The release production gate checks both public
+wheel and sdist resolution, dependencies, imports and runtime identity. A local
+`--no-deps` wheel installation is only an artifact test, not public resolution.
+The matching host manifest pins that version while retaining domain `loxone`,
+name PyLoxone and integration version 0.10.2. For HA, use the complete matching
+adapter/preview and normal host dependency handling, not a manual live pip step.
+
+The matching library and adapter passed independent source and exact-wheel review, and the common pair was installed on Home Assistant OS (Core 2026.10.4, Python 3.14.9). On 28 October 2026 the owner accepted two normal-use Local Library → Spotify returns to the same track near its saved position, supported by integration command and native content/position feedback. This is one-room confirmation, not all-room acoustic, whole-queue, persistent shuffle or restart-recovery proof.
+
+For public availability, use the matching GitHub release, PyPI version and release verification receipts. Source, tag or uploader success alone is not the production gate. Existing Home Assistant installations do not automatically update.
+
+## Intentional 0.1.1 retirement
+
+The optional SpotifySessionBridge, SpotifyNativeSession,
+NativeSessionUnavailableError, NativeResumeOutcome, async_optional_native_resume
+and async_resume_native_session API and its bridge parameter are removed together
+with the HA-only controller. Consumers using those optional interfaces must update
+alongside the matching 0.1.1 adapter pin; no compatibility facade silently retains
+provider access. The native command/authentication/metadata/Browse/manual-seek API
+remains. previous_source_labels is the room-local playable-content view; configured
+presence is still source_descriptors, not evidence of selected/played content.
+See SPOTIFY.md and POSITION-RESTORE.md for the current function map and limits.

pyloxone_audio-0.1.1/DIAGNOSTICS.md

@@ -0,0 +1,203 @@
+# Opt-in audio diagnostics — 0.1.1
+
+This feature is part of the matching PyLoxone 0.10.2 adapter and PyLoxone-Audio
+0.1.1 release pair, not the older 0.1.0 release. Installing the wheel alone does
+not add the Home Assistant switch. The matching pair has been privately installed
+on HAOS (Core 2026.10.4, Python 3.14.9); owner-enabled collection and a downloaded
+diagnostic report have been observed. This is not public availability, upstream
+approval, a universal UI/device test or a physical playback repair.
+
+The final same-track/native-mode pair has completed independent review and
+common private adoption. The owner subsequently accepted two one-room returns
+with supporting saved-session, exact command, content and position feedback.
+That is bounded confirmation, not all-room acoustic or queue proof.
+
+Defaults, switch preferences, retention, storage/export bounds and schema version1
+remain unchanged. Its narrowly extended allowlist records native aliased
+`shuffle/enable|disable`, `repeat/0|1|3`, standard HA `shuffle_set`/`repeat_set`
+requests and validated feedback fields `shuffle` (literal boolean) and `repeat`
+(`off|all|one`). Unknown mode fields are omitted, never inferred as off; malformed
+routes/enums/booleans remain rejected. A command reply is not physical acceptance.
+No raw mode payload, credential or provider state is exported.
+During a bounded readiness wait, `seek_unsupported` is a
+current decision, not proof the source can never seek. A later `eligible` requires
+positive capability on the same valid target; a source-transport `timeout` with
+`seek_unsupported` means playback was retained without a seek. No prior raw native
+capability mask can be reconstructed from a false diagnostic boolean.
+
+## Tester workflow
+
+1. In Home Assistant **Settings > Devices & services > Entities**, filter to your
+   Loxone integration entry and find **Audio diagnostics**. It is a diagnostic
+   entity, hidden from automatic dashboards, not disabled. Turn it **on**. With
+   several entries each has its own switch and independent report.
+2. Reproduce the problem through your usual native UI or controlling app. Note
+   local time/timezone, the room, source sequence, expected result and what you
+   actually saw/heard. Do not repeatedly trigger a failure merely to fill a report.
+3. Open **Settings > Devices & services > Loxone**, use the relevant entry's
+   three-dot menu and **Download diagnostics**. This uses HA's existing
+   administrator-only config-entry diagnostic download, not a new public endpoint.
+4. Turn **Audio diagnostics off**. That stops new collection, not the integration
+   or playback. No reload, new connection, Core restart, media command or bookmark
+   reset occurs when switching it on/off. The explicit setting survives ordinary
+   restarts once persistence is confirmed; new installs/upgrades without a valid
+   saved setting start **off**. OFF stops emission immediately, before storage I/O.
+   Check the switch/report health: `pending_preference` is the latest unconfirmed
+   requested bool (or null when confirmed), and `preference_restart_risk` is true
+   while pending. `storage_unavailable` plus a sticky `storage_failures` count
+   reports failed, mismatched, deferred or cancelled persistence. A successful
+   journal flush/export does not clear that pending preference error.
+5. Review the downloaded JSON before attaching it to your agreed issue/report
+   channel. Nothing uploads automatically. Include the exact candidate/ZIP hash,
+   HA/PyLoxone/library versions, symptom time/timezone, steps and audible versus
+   displayed result. Locally match a room to its `room`/`player` aliases if needed;
+   do not post original household IDs or private account details. Do not contact
+   maintainers/testers until your own agreed outreach/publication gate is met.
+
+The switch and actual HA admin download handler have been exercised through an
+offline owning-HA harness, then installed and checked on the real HAOS runtime.
+An owner subsequently enabled collection and supplied an actual downloaded report
+containing send/completion/reply, saved-session and restore-decision evidence.
+The supplied report had no storage, observer or queue-loss errors. This validates
+that live collection/export journey, not all branches or audible playback.
+Menu placement may vary with HA. The private report is not a public fixture.
+
+## Reading a report and preparing a useful bug report
+
+- Check `enabled` and `status`: `collecting` means the feature was enabled when
+  exported. It is independent of the integration's existing experimental
+  play/pause option, which gates native Audio Server playback features rather
+  than diagnostic recording. Turning diagnostics on does not enable those controls.
+- Check `coverage_oldest_utc`, `coverage_newest_utc` and `export_oldest_utc` against
+  the incident time. The report cannot reconstruct commands from before collection
+  started. A short window immediately after enabling is normal.
+- Check `dropped_queue`, `dropped_storage`, `export_omitted_records`,
+  `storage_failures` and `observer_failures`. Nonzero counters qualify what can be
+  inferred; zero counters do not prove every external/native event was received.
+- `complete_24h: false` is deliberately conservative, not by itself a fault.
+  Retention is up to 24 hours; it is not a promise of uninterrupted or complete
+  reception, and the bounded download may be shorter than the stored window.
+- Follow the same request/player/source aliases through `request`,
+  `send_attempt`, `send_completed` and `reply` or an error/timeout. Use
+  `session_saved` and `restore_decision` to distinguish a missing bookmark, an
+  ineligible seek and an actual seek attempt. A `restore_echo` is not proof the
+  loudspeaker playback moved; report what was heard separately.
+- Include the local incident time and timezone, intended room/source, exact
+  versions/build, normal UI steps, and expected versus observed behaviour.
+  Review the complete JSON before attaching it manually. Do not post private
+  room/account mappings, credentials or unrelated raw exports.
+
+Turning collection off preserves unexpired evidence, so a report can also be
+downloaded after disabling it. Do not assume `enabled: false` means a retained
+timeline is empty. Check the actual event times and collection status instead.
+
+## Retention and limits
+
+Collection continues while on: **24 hours is a rolling maximum record age, not a
+collection timeout**. Off retains unexpired evidence for reporting and preserves
+configuration. Disabled housekeeping runs approximately every 60 seconds;
+export filters expiry too. Timestamps use UTC/elapsed seconds, including DST.
+Already expired records are not recovered after restart or a coverage gap.
+
+Preference saves use HA's existing Store and public readback, checking the exact
+requested bool and this entry's pseudonym key without exporting the key. The
+existing housekeeping writer retries the latest pending request at most once per
+60 seconds (monotonic backoff), outside the journal lock. It never replays an old
+ON over a newer OFF; closing retires retry ownership. HA stopping/deferred writes
+are not treated as durable confirmation. Once storage recovers and save/readback
+succeed, pending clears and ordinary `off`/`collecting` health returns. While a
+failed OFF remains unpersisted, an actual restart can restore the earlier saved
+ON. Storage that cannot write cannot promise durable OFF: resolve the reported
+disk/permission problem and confirm pending has cleared before relying on restart.
+
+Per integration entry:
+
+- Queue: at most **256 events**; overflow removes the oldest queued record.
+- Sanitised event: at most **2 KiB**; no unbounded raw frames or DEBUG logs.
+- Timeline: at most **4 MiB**, in **256 KiB** segments. Size pressure rotates the
+  oldest segment, potentially shortening coverage to much less than 24 hours.
+- Atomic maintenance reserves at most one additional segment plus bounded counter
+  metadata (8 KiB read bound). Preference/pseudonym-key storage is separate and
+  tiny. Local files are private, outside web/static paths.
+- Export: newest records within a bounded **1 MiB** audio-report budget. The
+  adapter reserves **64 KiB** for HA's separate envelope. HA owns that envelope;
+  unusually large platform metadata is not under this integration's control.
+  Exports state their omission count rather than promising every retained record.
+
+Coverage oldest/newest times, export oldest time, mapped/omitted room aliases,
+expiry/rotation/invalid counts and queue/storage/observer failures accompany the
+report. `complete_24h` is conservatively false: a timestamp range is not proof of
+unbroken reception. Restarted sequence/monotonic values belong to a new process;
+UTC and transport/request/player aliases provide correlation, not unique physical
+causality. A reported storage failure warns once with fixed advice to check disk
+space/permissions; it never includes exception text or interrupts playback.
+
+File I/O runs in the existing HA executor, through one entry-owned writer and
+serial lock. Cancellation waits for an in-progress filesystem operation before
+releasing that lock. This cannot cancel a stuck OS filesystem operation. A slow
+or full disk can lose diagnostics, not backpressure native playback. Stored
+partial/invalid event lines are rejected; atomic replacement preserves preceding
+complete records where possible. A report can honestly have no recoverable data.
+Startup and ordinary maintenance (even cached/OFF maintenance) discard abandoned
+`events-<numeric index>.jsonl.tmp` files with the journal's minimum 16-digit index
+and `state.json.tmp`; uncommitted payloads are not evidence. Cleanup never reads
+these payloads or follows symlinks, leaves unrelated names untouched, inspects at
+most 256 directory entries and removes at most 64 recognised regular temporary
+files per operation. Unexpected types, work limits or unlink errors report storage
+failure rather than claiming recovery. Successful recovery/rotation restores the
+timeline plus one atomic segment and small metadata allowance above; foreign files
+or an inaccessible directory cannot be claimed bounded or successfully cleaned.
+
+## What the evidence means
+
+- `ha_service_request` is HA's request event for an exact registered audio entity;
+  area/device-only targeting and unrelated controls are not reconstructed.
+- `session_saved` samples the actual qualified room/source cache, not Recorder or
+  a separately recreated bookmark. `restore_decision` reports the first evaluated
+  guard reason, saved/current numeric positions/durations and initial/post-auth
+  phase; unevaluated guards are not falsely described as failures.
+- Audio Server `request`, `authenticated`, `send_attempt`, `send_completed` and
+  `reply` distinguish authentication, the actual existing socket send await and
+  a parsed native result. Source confirmation can instead settle from separately
+  qualified requested-source feedback. A completed send is **not device execution**.
+- `restore_echo` is a numeric native position echo, **not acoustic movement** or
+  proof that playback advanced from the requested position. Optional-restore
+  failure leaves confirmed source success intact; no retry is introduced.
+- Miniserver sends are recorded on its existing connection **only** for discovered
+  audio controls and allowlisted play/pause/stop/next/previous/volume operations.
+  Encrypted command bytes/authentication remain untouched; no auth envelope enters
+  the sink. Relevant numeric volume/play-state feedback is labelled separately
+  from Audio Server track/source/position/event feedback and disconnects.
+
+The same opt-in policy covers all AudioZoneV2 players discovered in that loaded
+entry; there are no hardcoded household room IDs. Report aliases correlate routes,
+player, room, account, content and parent context without exposing originals.
+Meaningful non-secret seek numbers and semantic route structure remain exact.
+No title, private announcement text, raw house structure, arbitrary frame/error,
+credential, cookie, token, password or raw media URL is persisted by this feature.
+
+HA itself adds standard system/custom-integration metadata to diagnostic downloads,
+which can include installation/platform/hostname details. That HA-owned envelope
+is **not** claimed to be anonymous. Review the actual entire download before
+sharing; pseudonymisation of the audio portion is not universal anonymisation.
+
+## Scope and cost
+
+The library supplies no-op-by-default structured events and imports no HA/storage
+implementation. The existing adapter owns the switch, preference, local writer
+and export. There is no sidecar, second integration, new socket, global debug
+setting or automatic upload. Disabled callers skip detailed diagnostic field
+construction and queue/file writes; expiry of previously retained data still runs.
+
+Synthetic HA-harness measurements are retained with this candidate's development
+receipts: process CPU deltas, `/proc/self/status` RSS/HWM, event rate, actual journal
+bytes and export bytes/time. They are a short synthetic load, not quiet-house or
+busy-house measurements, device latency proof, a per-day write forecast, or an
+incremental production Core memory estimate. Limits are fixed bounds, not a promise
+that a busy installation will retain a full day.
+
+This capability cannot retrieve commands from before enablement or retroactively
+diagnose earlier Spotify returns. It changes no source, queue, seek, retry, newest
+request, authentication or control policy. Existing independently operated private
+rolling observers/watchdogs are neither imported, replaced nor stopped. Their
+records are not included in this report, and their settings remain independent.

pyloxone_audio-0.1.1/EXACT-TRACK-RETURN.md

@@ -0,0 +1,94 @@
+# Exact remembered-track return — 0.1.1
+
+The matching library and adapter passed independent source and exact-wheel review, and the common pair was installed on Home Assistant OS (Core 2026.10.4, Python 3.14.9). On 28 October 2026 the owner accepted two normal-use Local Library → Spotify returns to the same track near its saved position, supported by integration command and native content/position feedback. This is one-room confirmation, not all-room acoustic, whole-queue, persistent shuffle or restart-recovery proof.
+
+For public availability, use the matching GitHub release, PyPI version and release verification receipts. Source, tag or uploader success alone is not the production gate. Existing Home Assistant installations do not automatically update.
+Use the exact matching release wheel, adapter, preview and checksums; historical
+same-version development artifacts are not interchangeable.
+
+## What this correction does
+
+- Individual Spotify **track and podcast-episode** starts include the native
+  per-start `/noshuffle` argument, after any validated parent/cursor. Configured
+  account, exact item and optional parent/zero-based index stay unchanged.
+  Account-qualified item identifiers are retained, not stripped.
+- When returning to a saved exact Local Library/Spotify item, feedback from the
+  same provider/account but a **different track is not success**. It cannot
+  trigger the old track's position seek or replace the preceding last-good item.
+  The player still displays the track actually reported by Loxone.
+- Continuing feedback from that rejected return retains the prior bookmark.
+  A later explicit return attempts that retained item instead of treating the
+  wrong currently-playing track as a provider-only no-op. No automatic retry is
+  added. A matching return, a new explicit Browse selection, or independently
+  corroborated later different playback can update the record normally.
+- After matching playback, at most **one best-effort** position attempt retains
+  existing bounded capability readiness, authentication, room/account/track,
+  lifecycle, event/fence and newer-action checks. An unsupported/failed optional
+  seek does not turn matching confirmed playback into source failure.
+- A positively qualified current native Spotify session can still use native
+  empty-content resume. Unknown/history-only context return retains its existing
+  provider contract; exact remembered-item confirmation does not invent an item
+  for a context. Local Library commands, context starts, radio, Line-In,
+  explicit native Shuffle/Repeat setters and their capability rules are unchanged.
+
+There is no Spotify API, compensating Shuffle/Repeat write, queue controller,
+new setting, delay-only fix, cursor arithmetic change, fallback item, cross-room
+policy or persistence implementation. The existing playback setup gate remains
+required (see the main README).
+
+## Function-to-feature map
+
+| File/symbol | Change and regression coverage |
+| --- | --- |
+| `pyloxone_audio/native.py:AudioServerCommands.async_play_catalogue` | Type-specific per-item flag; `tests/library/test_exact_track_start.py` checks tracks/episodes, qualified IDs, no parent and cursors 0/13/63, plus context/other-route negatives |
+| `pyloxone_audio/sources.py:_source_matcher`, `async_select_catalogue` | Saved exact-item match before confirmation/optional seek; preserve ordered source/track/account restore reasons |
+| `pyloxone_audio/selection.py:async_source_route` | Owning adapter may suppress current-session no-op after a rejected exact return; ordinary native session routing unchanged |
+| `adapters/pyloxone/overlay/custom_components/loxone/media_player.py:LoxoneAudioZoneV2._update_audio_metadata`, `async_select_source`, `_async_play_radio` | One room-local rejected-return marker, using the existing saved session and passive qualification. Protect last-good without changing truthful metadata; release on qualified replacement/explicit success |
+| `adapters/pyloxone/overlay/custom_components/loxone/audio_diagnostics.py:_safe_event` | Persisted strict schema retains the aliased Spotify flag; recovery/extra-tail/non-Spotify negatives in owning-HA tests |
+| `pyloxone_audio/diagnostic_events.py:DiagnosticEmitter.route` | Recognise only the fixed per-item flag, preserving keyed account/content/parent aliases; unknown tails still refused |
+| `tests/adapter/test_exact_track_return_ha.py` | Real owning HA service/coordinator/authenticated native transport, synthetic I/O: 30.021s/index13 shape, wrong feedback even with new flag and reported shuffle false/true, delayed correct feedback, account/room negatives, explicit retry/Browse, late matches and independent replacement |
+
+Existing full-suite lifecycle/authentication/cancellation, all-room isolation,
+mode, manual seek, announcement, setup/unload and no-uncertain-replay controls
+remain part of acceptance. See the maintainer's `EXACT-TRACK-DELTA.json` and
+`EXACT-TRACK-TEST-MIGRATIONS.json` for exact file/expectation dispositions.
+
+## Source evidence and limits
+
+The pinned official Loxone 17.2.2 client, retrieved 26 October 2026 from the official
+Linux release AppImage, uses `playItem -> shouldShuffleAudioItem ->
+ServicePlayScheme`; individual track/episode types choose `noshuffle`, serialized
+**after** `parentpath/<parent>/<zero-based-index>`. The retained bundle SHA-256 is
+`76f4ff34c3156cf9109524c37640d33352968fc7dc7477af6866a9983f5abacf`.
+This is command/caller parity, not proof of the physical firmware's selection
+algorithm or a persistent shuffle/queue-preservation guarantee. The motivating
+wrong-track observation included reported shuffle **false**, so it is not
+explained simply by a shuffle-on switch.
+
+Wrong-feedback fixtures are deliberately independent of the flag. A simulator
+that returns the right item when it sees the flag cannot prove the hardware cause.
+Those offline fixtures use no device credentials or household commands. Later
+owner-operated one-room returns supplied matching content/position confirmation;
+parent/queue, universal audible position and persistent-mode effects remain unproved.
+
+The receiver cannot establish an external command's issuer from identical
+same-item feedback. Continuing the rejected item alone does not establish a new
+independent selection. Explicit Browse can deliberately choose that item; later
+qualified different playback also replaces the marker. This is a bounded
+interpretation of observed identity, not invented causal device evidence.
+
+## Review and adoption
+
+1. Inspect the exact delta, test-migration map and retained original failed receipts.
+2. Reproduce canonical source and exact installed-wheel suites with blocked TCP,
+   strict runtime/resource warning gates, case parity and import evidence.
+3. Verify the complete preview against its provenance; exercise the unchanged
+   builder/install/update/rollback tests. Preview material stays out of Python
+   wheel/sdist. Do not use older same-version artifact hashes.
+4. Preserve the completed independent exact-correction review and common adoption
+   evidence. Re-review changed runtime; historical mode/seek reviews alone do not
+   approve future changes.
+5. Keep software tests, installed-byte verification, one-room owner acceptance and
+   the public production gate separate. Upstream adoption/contact is not implied.
+
+Restart persistence is a separate design and is intentionally not bundled here.

{pyloxone_audio-0.1.0 → pyloxone_audio-0.1.1}/MANIFEST.in

@@ -11,3 +11,7 @@ include README.md
 include SPOTIFY.md
 prune tests/release
 recursive-include tests/library *.py *.ini *.json *.txt *.md
+include POSITION-RESTORE.md
+include DIAGNOSTICS.md
+include NATIVE-MODES.md
+include EXACT-TRACK-RETURN.md

pyloxone_audio-0.1.1/NATIVE-MODES.md

@@ -0,0 +1,96 @@
+# Native Shuffle and Repeat — 0.1.1
+
+## What appears in Home Assistant
+
+Open an existing Loxone room's **More info** media-player dialog. Where the
+current Audio Server reports support, the normal HA controls offer **Shuffle**
+and **Repeat**. Shuffle is on/off; Repeat cycles **Off → All → One → Off**.
+The standard icons distinguish the reported modes. Compact Media Control/Tile
+cards do not necessarily show extended controls. No custom card, helper switch,
+frontend resource or Core patch is installed.
+
+Configure **Audioserver host** and turn on the existing option
+**Use Audio Server player play/pause (experimental; off by default)**
+(`audioserver_playback`). This option and its default are unchanged. Metadata can
+still be received with control disabled. **Audio diagnostics** is a different,
+default-off feature, not a prerequisite for mode control.
+
+These are **Loxone player controls, not Spotify controls**. Every action addresses
+one exact existing native Audio Server player through the library's current-token
+command client. Local Library and any other genuinely capable native source use
+the same implementation. There is no Spotify Web API/Connect command, HA Spotify
+entity/service, provider credential, binding or provider-derived mode state in
+this feature. Existing room identities, configuration and independent bookmarks
+are retained. Radio or Line-In labels do not imply support.
+
+## Truthful state and limits
+
+- The exact player's native `plshuffle` and `plrepeat` feedback supplies the
+  displayed state, including changes made in Loxone or another controlling app.
+  A submitted HA request or successful socket write does not turn the indicator
+  on. A validated native reply acknowledges the command; this adapter waits for
+  the ordinary exact-player feedback to change its displayed mode.
+- Missing, malformed or disconnected state is **unknown**, not a fabricated Off.
+  Full native player-state records are replaced rather than merging absent mode
+  fields from an older track/session. Announcement events are not queue state.
+- Shuffle requires native bit2048, known shuffle state, current ordinary playing
+  media, and API >=1.6 / firmware >=16.1.09.23 on the event connection. The command
+  connection must independently qualify that greeting before sending an explicit
+  enable/disable. There is no fallback to the older no-argument shuffle action.
+- Native repeat is **0 Off / 1 All / 3 One**, never2. HA has one REPEAT_SET feature
+  and its standard button cycles all three modes. Therefore this adapter exposes
+  that button only with known repeat state and **both** native permissions4096
+  and8192 on current playing/paused media. Partial repeat support is not advertised
+  as a full cycle; a direct HA setter also refuses it. The library's qualification
+  helper can check a specifically requested repeat mode for another typed host.
+- Support follows current native data, not provider/source-name guesses. Unknown
+  permissions and unsupported source records hide the extended control without
+  changing existing Miniserver controls. Unknown or older shuffle firmware does
+  not disable otherwise-qualified native Repeat.
+- Exactly one requested native mode command is sent. No play, source start,
+  queue replacement, seek, skip or automatic retry is added. In particular this
+  mode-control feature does **not** replace queues or implement source-return
+  selection. The separate exact-item return correction is described in
+  [EXACT-TRACK-RETURN.md](EXACT-TRACK-RETURN.md).
+- A queued request cannot survive loss of its original track/account/context,
+  capability, connection, newest-action ownership or entity lifetime while
+  authentication is awaited. Existing shared serialization and clean cancellation
+  remain. Mode feedback does not alter artwork identity or saved source content.
+
+## Portable API and adapter map
+
+`AudioRepeatMode` and `audio_mode_supported` are public HA-independent exports.
+`AudioZoneMetadata.shuffle` is `bool | None`; `repeat` is
+`AudioRepeatMode | None`; `shuffle_switch_supported` is connection-qualified
+`bool | None`. Only greeting versions are retained, never the session credential.
+
+`AudioServerCommands.async_set_shuffle(player_id, bool, *, is_current=...)` and
+`async_set_repeat(player_id, AudioRepeatMode, *, is_current=...)` reuse current
+authentication, bounded command-wide timeout, connection serialization and close.
+The host must qualify the latest native snapshot and maintain a liveness callback
+across awaits. The repeat API rejects bare integers/strings rather than silently
+coercing an unknown enum. Setters strictly validate the corresponding native mode
+reply. Neither setters nor helpers import Home Assistant or own provider APIs.
+
+The existing AudioZoneV2 entity translates HA SHUFFLE_SET/REPEAT_SET and
+`async_set_shuffle`/`async_set_repeat` into those calls. The normal event callback
+updates HA attributes. The same policy is used in every mapped room, with no
+per-room flags/delays. Strict optional diagnostics add only fixed aliased command
+routes and typed mode fields; default-off and all storage/export bounds remain.
+
+## Evidence and remaining acceptance
+
+The maintained tests use synthetic data and real owning HA services, native
+RSA/AES authentication and AF_UNIX WebSocket framing with TCP blocked. The all-room
+matrix includes Local Library and native Spotify without loading HA Spotify;
+additional positive/negative permission controls do not claim physical radio or
+Line-In firmware support. Existing mode-control tests remain separate from exact-item source-start tests.
+Version-matched frontend function tests exercise HA's real control/icon/cycle
+functions using emitted HA entity states, not a replacement player UI.
+
+Independent review and common private HAOS adoption are complete. Actual mode
+requests and native mode feedback were observed, but those are not proof of
+physical queue behaviour or every rendered frontend control. The ordinary
+install/backup/update/rollback route is in
+[the preview guide](preview-build/README.md); the maintainer's exact patch and
+what/why/test map are in [the review pack](adapters/pyloxone/jo-review/README.md).

{pyloxone_audio-0.1.0 → pyloxone_audio-0.1.1}/NOTICE.md

@@ -1,15 +1,17 @@
-# Provenance and licence — concrete offline extraction
+# Provenance and licence — PyLoxone-Audio 0.1.1
 
-This local 0.1.0 release candidate is supplied under Apache-2.0. `LICENSE` is copied verbatim from the local PyLoxone repository's Apache License, Version 2.0 file. No package has been published or registered. The library's 0.1.0 metadata and exact local host dependency are not a public index release or installed production change.
+PyLoxone-Audio 0.1.1 is supplied under Apache-2.0. Published 0.1.0 remains
+immutable. `LICENSE` retains PyLoxone's Apache License, Version 2.0 verbatim.
+Actual public availability is established by the matching release production gate.
 
-The HA entry ownership, exact-player mapping, current-token callback and entity-property delegation are adapted from the PyLoxone integration maintained by JoDehli and its contributors, specifically the sealed `media_player.py`, `audio.py` and `coordinator.py` call graph. Those inspected source files contain no additional per-file copyright notices to remove or replace. This draft does not assign invented upstream copyright ownership.
+The HA entry ownership, exact-player mapping, current-token callback and entity-property delegation are adapted from the PyLoxone integration maintained by JoDehli and its contributors, specifically the sealed `media_player.py`, `audio.py` and `coordinator.py` call graph. Those inspected source files contain no additional per-file copyright notices to remove or replace. This project does not assign invented upstream copyright ownership.
 
 The original native protocol source retains this attribution, which must accompany any future adaptation of its event mapping:
 
 > Event names adapted from SebastianEitzert's Apache-2.0 POC in #523, comment 6251138699. See tests/fixtures/audioserver/README.md for provenance.
 
-The actual parser/event mapping is now extracted into `pyloxone_audio/native.py`, retaining that attribution. Native transport/authentication, metadata coordination, source policy, radio and catalogue implementations are derived from the immutable accepted source tree identified by `baseline-verification.json` and the extraction provenance receipts. Native announcement ownership and the native read-only-bridge Spotify session selection are also extracted; HA preparation, provider session storage and UI responsibilities stay with the host. Relevant upstream attribution and Apache-2.0 terms are retained; no invented copyright assignment is made.
+The actual parser/event mapping is now extracted into `pyloxone_audio/native.py`, retaining that attribution. Native transport/authentication, metadata coordination, source policy, radio and catalogue implementations are derived from the immutable accepted source tree identified by `baseline-verification.json` and the extraction provenance receipts. Native announcement ownership remains extracted; the optional HA-Spotify bridge/provider session controller was retired in0.1.1, preserving native Spotify. HA preparation and UI responsibilities stay with the host. Relevant upstream attribution and Apache-2.0 terms are retained; no invented copyright assignment is made.
 
-Historical fake-facade, extraction and operational evidence remains outside release assets. The concrete package exports real native classes and source-policy functions instead. Synthetic fixture provenance is preserved under `tests/library/fixtures/audioserver/README.md` outside the wheel. The older path in the attribution quoted above is historical; the current location applies to this repository and its source archive. Development-only detailed tracing and HA failure-summary publication are excluded from both library and adapter at this cutoff.
+Historical fake-facade, extraction and operational evidence remains outside release assets. The concrete package exports real native classes and source-policy functions instead. Synthetic fixture provenance is preserved under `tests/library/fixtures/audioserver/README.md` outside the wheel. The older path in the attribution quoted above is historical; the current location applies to this repository and its source archive. New default-off fixed-schema audio diagnostics supersedes the blanket instrumentation exclusion only for this increment; legacy private tracing, household observer/watchdog assets and HA failure-summary publication remain excluded.
 
 Dave directed requirements, behaviour decisions and normal-use validation. Implementation and offline testing were AI-assisted through Hermes with OpenAI primary models; release-cutoff implementation uses gpt-6.1-sol and the independently recorded review uses an actual primary OpenAI invocation. AI assistance is provenance, not an invented human author, a transfer of upstream ownership, hardware certification or a guarantee of defect freedom. Independent review identity and limitations are recorded in release-level evidence, not claimed as a substitute for tests.