macOS: make VideoToolbox hardware decode per-resource and observable

[tcconnally]

Problem

videotoolbox-copy reduced some symptoms in a 10-minute trial but reproduced resource-specific failures such as output image buffer is null: -12909, hardware accelerator errors, recovery exhaustion, and fallback activity. A global hardware-decoder default is unsafe for the current library.

Scope

• Keep decoder choice per resource/codec/container class until a known-good corpus is established.
• Count hardware attempts, successes, software fallbacks, recovery exhaustion, and quarantine separately.
• Ensure one bad resource cannot change the wall-wide decoder policy.
• Preserve bounded software fallback and resource quarantine.

Acceptance criteria

• The known-good pilot corpus has zero hardware faults and audio underruns.
• Malformed resources fall back once and then quarantine without a retry loop.
• Final stats identify requested decoder, active decoder, and fallback reason per cell.

[tcconnally]

Implemented in PR #81, merged as 300e14c. Decoder state now records requested/active decoder, hardware attempts and activations, software fallback, recovery exhaustion, and quarantine per resource. The known-good VideoToolbox corpus run remains hardware qualification work.

[tcconnally]

Native acceptance update

Current main is 4475e0ff8f9207f28f92f0067d9d0ba8b739094d. Per-resource decoder telemetry and bounded fallback/quarantine controls are present in merged PR #81, but native qualification is not complete: no current known-good and malformed-resource runs are available. The old hardware trial is historical and had hardware faults, fallback/recovery activity, audio underruns, and freezes; it is not a pass.

Still required: current per-resource requested/active decoder, hardware attempts/activations, one software fallback, recovery exhaustion, quarantine, retry-storm check, audio underruns, A/V drift, and transport evidence. This issue remains open.

[tcconnally]

Post-merge status: main is now b94be1ce3d86f06841ff458e3708d66efacd4ef1 after PR #84. PR #84 changed only the #79 capacity-evaluator contract; it produced no Mac/native measurements and does not change the open native blockers for this issue. The issue remains open.

[tcconnally]

Native pilot update for run 20260905T165329Z/profile-8-docked-clamshell-fixed on commit 2ce6de1c66ce7f4217249c59fa710268c47bc2bc. This run used HYPERWALL_HWDEC=no, so it is not VideoToolbox hardware qualification and included neither the known-good hardware corpus nor the malformed-resource experiment. No per-resource VideoToolbox acceptance claim is made. Issue remains open.

[tcconnally]

Native acceptance boundary update on commit 074258ddb6b1b2e3e1e8bd5cbe09742310c5d99b.

The fixed-corpus 1/2/4/6/8 matrix and HQ/low-cost comparison all used HYPERWALL_HWDEC=no; they do not qualify VideoToolbox. No valid #78 known-good hardware phase or malformed-resource hardware phase has been run.

The current soak harness selects the 67-item Favorites corpus but does not provide deterministic single-resource selection for the required known-good/malformed pair. The observed blaze_1 freeze/malformed-log activity is not enough to call it a controlled malformed-resource test. No requested/active VideoToolbox decoder, bounded fallback, recovery exhaustion, quarantine, retry-storm, audio, or A/V acceptance claim is made. Issue remains open.

[tcconnally]

Code-side harness update

PR #89 is merged to main as a858488152f1e57453c7ad98ad9c620a69dda407 (candidate f4132740a4b7ab1c2552614d894a8e1b1a9b1ad1). GitHub tests and windows-build both passed.

The harness now supports deterministic --item-id selection, applies exact selection against the full Emby response, fails closed for missing/ambiguous IDs, and records the selected resource in the private phase manifest without credentials. The full local suite was green.

This closes the implementation gap, but not the native acceptance gate. The required known-good and malformed-resource VideoToolbox phases still need to run on the target Mac with per-resource decoder, fallback/quarantine, audio, A/V, retry-storm, and transport evidence. The target airbud host was unreachable from the current Linux environment (connection refused), so no native result is claimed. Issue remains open pending that evidence.

[tcconnally]

Follow-up: empty shell selectors are now rejected

The two reported runs on main a858488152f1e57453c7ad98ad9c620a69dda407 were not controlled resource phases: KNOWN_GOOD_ID and MALFORMED_ID were unset, so zsh passed --item-id "". The prior runner treated that as no selector and proceeded to a generic phase; both correctly ended BLOCK. The zsh: command not found: # lines are also from pasting comment lines into an interactive zsh without interactivecomments enabled.

PR #90 is merged to main as 33e1dbed9eb871e1b95884e8313b7334b2658d7e. Empty and whitespace-only --item-id values now fail immediately with:

error: --item-id must be a non-empty Emby item ID

Before rerunning, set real Emby IDs and verify they are non-empty. Configure and accept the 1x1 SetupWizard phase when prompted; the runner cannot automate that step:

export KNOWN_GOOD_ID='REPLACE_WITH_REAL_EMBY_ID'
export MALFORMED_ID='REPLACE_WITH_REAL_EMBY_ID'
: "${KNOWN_GOOD_ID:?set KNOWN_GOOD_ID first}"
: "${MALFORMED_ID:?set MALFORMED_ID first}"

HYPERWALL_SOAK_FILTER=favorites python3 scripts/run-soak-diagnostics.py --minutes 10 --expected-cells 1 --item-id "$KNOWN_GOOD_ID" --decoders videotoolbox-copy
HYPERWALL_SOAK_FILTER=favorites python3 scripts/run-soak-diagnostics.py --minutes 10 --expected-cells 1 --item-id "$MALFORMED_ID" --decoders videotoolbox-copy

Do not use the literal placeholders. This fixes the harness misconfiguration; native VideoToolbox acceptance remains pending until both phases produce complete per-resource telemetry and pass their media gates.