lab: Milestone 3 dext bring-up — ZTS timer chain, activation host, bench runbook

[boggspa]

What

Milestone 3 per the lab README: the dext becomes loadable and answers O1–O3 / C1–C4 with counters, not docs. Stacked on #23 (Step 6) — review the top two commits; the base commit is the Step 6 verifier this work runs under.

The dext clock model (commit 1)

• ZTS timer chain: IOTimerDispatchSource on the work queue, kIOTimerClockMachAbsoluteTime (the clock CoreAudio host times use). Each fire anchors UpdateCurrentZeroTimestamp(n × period, fire_time) with raw values — nominal drift-free deadline chain (derived from the period index via mach_timebase_info, never from the previous jittered fire), actual fire times, host smooths via the clock algorithm. No driver-side extrapolation — the reference model from the README.
• Packet pump: the same fire exposes the next period's packets via the controller — the lab analog of the IT-ring refill interrupt. WriteEnd only fills PCM into already-exposed packets (the Saffire one-buffer model).
• Verifying(Fake) under real pacing: the Step 6 instrument + StickyCounterSink run for the whole IO session; StopIO dumps everything via IOLog (ADKLab[dump] prefix — never from the IO callback).
• O/C instrumentation: anchors-before-first-WriteEnd (C1 — the lab proxy for the ASFW "no ZTS anchor → no IO cycle" bug), WriteEnd shape stats: min/max in_io_buffer_frame_size, sample-time continuity breaks, first-callback tuple (C3), callbacks/timer fires after StopIO counted-not-crashed and logged at free (O2), prepare-failure and other-op counters.
• SetTransportType(FireWire) — the contract ASFW will live under.
• Ring widened to 8 ZTS periods (4096 frames, matching the host scenario pump). The 1-period ring left the HAL zero headroom around the wrap anchor; kRingPeriods keeps C4 observable.

Info.plist matching fix — please audit

IOProviderClass was IOUserService; a hardware-free dext matches IOUserResources (+ IOResourceMatch: IOKit) — with the old value the personality should never match and the dext never starts. Flagging explicitly since it's your file; revert if it was intentional.

Bring-up harness (commit 2)

• ADKLabHost: minimal SwiftUI activation app; xcodegen embeds the dext into Contents/Library/SystemExtensions; the dext identifier is discovered from the embedded bundle at launch so bundle-id-overriding signing lanes need no code edits.
• Entitlements files for both targets (signing itself stays off by default, exactly as before — your lane is untouched).
• BENCH.md: both signing lanes (ad-hoc SIP-off bench / provisioned SIP-on), activation, driving audio, reading the dump, and the counter → O1–O3/C1–C4 mapping with M3 exit criteria.

Verification

xcodegen generate
xcodebuild -scheme ADKVirtualAudioLabTests → BUILD SUCCEEDED; 17440 checks, 0 failures
xcodebuild -scheme ADKVirtualAudioLab      → BUILD SUCCEEDED (dext)
xcodebuild -scheme ADKLabHost              → BUILD SUCCEEDED (dext embedded correctly)

Every API claim verified against the DriverKit 25.2 SDK headers (IOLib.h ships mach_timebase_info/mach_absolute_time; IOTimerDispatchSource.iig; IOUserAudioClockDevice.iig) — no invented surfaces.

Runtime bring-up (activate + play + read dump) happens next on Chris's SIP-on machine with his DriverKit entitlements; results will be reported back so the README's O/C answers can be recorded.

🤖 Generated with Claude Code