[ramesh130]

Closes #460

Cause, with evidence

The cause is not a play request lost under load, and not a gap in the harness's teardown. AVFoundation picks a session's starting variant from a throughput history it keeps for the whole process, and we found no API that resets it. Every earlier corpus run on the fast loopback raises that history, until every ladder entry starts on its top rung. Started there, the severe ladder gap's top rung never plays.

Probes on sp-460 (iOS 27.1), since removed:

• No teardown gap. Weak references (NSHashTable.weakObjects) to every corpus AVPlayer, AVPlayerItem and AVAsset showed zero still alive at the start of every iteration.
• The starting rung moves within one process. The origin's request log, per iteration:
  • Iterations 1–3: every hls-ladder-gap entry asked for media.m3u8 (the bottom rung) first. Access log indicatedBitrate = 128000.
  • Iterations 4–6: every entry asked for media-high.m3u8 first.
  • On the top rung, benign and borderline played to the end. Severe fetched media-high.m3u8, segment-high0.aac and segment-high1.aac, then stopped at position 0 with an empty access log.
• The rate drop is the item-end pause. A key-value observer on rate caught the severe player at rate = 0 with timeControlStatus == .playing and the item .readyToPlay, about 100 ms after play(). That is the shape AVFoundation's pause at an item's end has, not a lost request.
• The severe top rung does not play in a fresh process either. A probe played each ladder entry's media-high.m3u8 directly, in a fresh process:
  • Benign and borderline played to 8 s.
  • Severe stayed at 0 with no item error, after logging AudioQueueObject.cpp Prime: failed (-50); will stop.
  • Its frames are 71 B × 48 = 3408 B. AAC's bit reservoir allows 6144 bits per channel, which is 1536 B for this stereo stream (ISO/IEC 14496-3). The ×4 frames are 284 B, which is why borderline plays.

So the "lost play()" was AVFoundation refusing media it was never obliged to decode. Whether the record met that refusal depended only on how many sessions the process had already played.

Reproduction (before the fix)

xcodebuild test-without-building -test-iterations 6 -only-testing:SuperPlayerTestkitTests/HostileManifestCorpusTests/testEveryGradedEntryIsPlayedAndItsBehaviourRecorded on sp-460 failed in 3 of 3 runs, always with "hls-ladder-gap (severe)": .neverStarts:

Run	Failed iterations
1	5, 6
2	4, 5, 6
3	4, 5, 6

The deterministic form is the fresh-process probe above: started on the severe top rung, a stock AVPlayer never starts, every time.

Remedy, and why it keeps the record honest

observe sets AVPlayerItem.startsOnFirstEligibleVariant = true on every corpus item.

• It is the start a fresh process takes. Every ladder entry started on its first variant in the first runs of each process. The setting makes later runs start where the first run does.
• Nothing after the start changes. Any climb is still AVFoundation's choice, and no outcome is reinterpreted.
• The table still records a stock player. This is a public property of a stock item, not a harness intervention. The table now records the same player on every run in a process.
• It only affects the ladder rows. Only the hls-ladder-gap entries have more than one variant, so no other row can move.

The other options:

• (a) Re-issue play(): rejected. The player did not lose a request; it refused the media. Re-issuing would not prime a rung the audio queue refuses. Worse, a harness that restarts a stopped player would hide exactly the kind of silent stop the record exists to show.
• (b) A process per run: rejected. It buys the same start at the cost of an xcodebuild invocation per run, and it would leave the dependence on process state undocumented.
• (c) "Valid for one run per process": rejected. The record would read differently depending on where its run fell in the process, with nothing to say so.

What else changed:

• Docs. The cliff iOS: the hostile corpus record loses a play() after repeated runs in one process (hls-ladder-gap severe never starts) #460 found is written beside the ladder rows (it is a cliff a flat row cannot see), with its spec: citation. The decision is recorded as ADR-0021 rule 4's iOS: the hostile corpus record loses a play() after repeated runs in one process (hls-ladder-gap severe never starts) #460 addendum, plus a paragraph in docs/testing.md's The hostile corpus on iOS.
• The record. No row moved. A single run reads the committed table, and ios/check ran the whole class.

After the fix

• The same command with -test-iterations 10: 10/10 passed, about 40 s each.
• SP_SIMULATOR=sp-460 ios/check: passed. That is 710 tests on iOS, 12 on tvOS (sp-460-tv) and 38 in ios/MoQ, plus the demo build.
• No device run. This is a test-harness change and the subject is the simulator's AVFoundation.

Review

Standards

• Hard: the ADR-0021 addendum was not yet committed. It is now committed at rule 4, in date order after iOS: a SuperPlayer on a video ladder stalls on the iOS 26.5 simulator (fetching stops; four stuck points) #474, with an Amended line in the header.
• Hard: the run counts disagreed between the comments, the docs and iOS: the hostile corpus record loses a play() after repeated runs in one process (hls-ladder-gap severe never starts) #460, which saw iteration 3 once. All three now say the change came from the third to the fifth run, depending on the host.
• Soft, fixed:
  • Inferences are worded as observations: "we found no API", and the audio-queue prime failure is stated as logged.
  • The reservoir constant has a spec: citation, and the property has a ref:.
  • The class doc names the one property that is set.
  • The prose duplication is cut: the comment in observe points to the ADR rather than retelling it.
  • One term is used throughout: "first variant".

Spec

• Hard: none.
• Soft, fixed: the "fourth run" wording; why (a), (b) and (c) were rejected now lives in tracked files (the ADR addendum and docs/testing.md); the comment says that only a multi-iteration run shows the effect; it names a climb inside the budget as the failure to expect.
• Soft, skipped: a committed test pinning "the severe top rung, started on, never starts". It would put a second recorded observation beside the table, and the corpus media itself is the likely follow-up. The severe rung's frames exceed AAC's reservoir in the shared Kotlin and Swift generator, so that belongs to its own issue.

Not done, and why

• ladderStepFactor(.severe) = 48 produces ADTS frames larger than AAC allows. That makes the entry's top rung invalid media as well as a ladder gap. Changing the shared corpus (both generators, fixtures, both records and the doctor's register) is out of scope for iOS: the hostile corpus record loses a play() after repeated runs in one process (hls-ladder-gap severe never starts) #460, and is worth its own issue.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MJAhQmFgdRRAKUaMHibQLe