feat(ios): route Simulator snapshots through AX bridge

[thymikee]

Summary

Closes #2197.

Eligible local iOS Simulator snapshots now use the packaged AX bridge and existing TypeScript presentation engine. XCTest remains the typed, generation-scoped fallback; a failed bridge attempt disables that generation, while a relaunched app may try again.

Fallback comparison now fails closed: stale-target failures re-resolve lineage before XCTest, and unresolved generations receive a unique typed residue. Regular depth remains a presentation constraint, so the bridge acquires the bounded full tree needed to preserve visible descendants; raw depth still bounds native traversal.

Providers, physical devices, tvOS, macOS, custom actions, interactions, and runner prewarm are unchanged. Scope is 23 files in the Apple snapshot family and shared identity contracts.

Validation

Validated head 1519222.

• pnpm check:affected --run passed all runnable gates and 5,624 tests across 734 files.
• Planted red: stale fallback retained old lineage; unresolved fallbacks compared equal; regular depth 1 incorrectly limited native acquisition to depth 1. All now pass.
• Live at pre-rebase equivalent 1600d40: iOS 26.2 bridge acquisition presented 26 nodes with clean helper/simulator teardown.
• Exact-head GitHub checks are green, including iOS clean-install bridge preparation, XCTest regressions, public CLI preflight, Settings replay, fixture E2E, and gesture replay.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	2.61 MB	2.64 MB	+34.4 kB
JS gzip	878.8 kB	890.0 kB	+11.2 kB
npm bundled raw	2.61 MB	2.64 MB	+34.4 kB
npm bundled gzip	878.8 kB	890.0 kB	+11.2 kB
npm tarball	1.04 MB	1.05 MB	+10.5 kB
npm unpacked	3.52 MB	3.56 MB	+35.2 kB
npm clean-installed	3.52 MB	3.56 MB	+35.2 kB

npm unpacked components

Component	Base	Current	Diff
JS / dist source	2.77 MB	2.80 MB	+35.1 kB
Apple runner source/project	544.4 kB	544.4 kB	0 B
Apple snapshot presentation source	33.8 kB	33.8 kB	0 B
Apple Simulator snapshot bridge source	30.5 kB	30.5 kB	0 B
macOS helper source	54.8 kB	54.8 kB	0 B
Android helper artifacts	43.3 kB	43.3 kB	0 B
Other package files	46.7 kB	46.8 kB	+77 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	30.8 ms	31.7 ms	+0.9 ms
CLI --help	81.9 ms	79.2 ms	-2.7 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/runtime4.js	+4.8 kB	+1.7 kB
dist/src/interaction2.js	+301 B	+60 B
dist/src/interactor.js	+70 B	+10 B

Top changed packed files

Packed file	Base	Current	Diff
dist/src/adapter.js	0 B	27.2 kB	+27.2 kB
dist/src/runtime4.js	51.3 kB	56.1 kB	+4.8 kB
dist/src/ios-snapshot-planning.js	0 B	2.0 kB	+2.0 kB
dist/src/runner-presentation.js	5.8 kB	5.1 kB	-706 B
dist/src/sdk-selectors.d.ts	35.8 kB	36.4 kB	+568 B
dist/src/ios-snapshot-runtime.js	10.2 kB	10.7 kB	+488 B
dist/src/interaction2.js	33.5 kB	33.8 kB	+301 B
dist/src/apps-simctl.js	0 B	264 B	+264 B
dist/src/physical-device-control.js	14.8 kB	14.6 kB	-184 B
dist/src/sdk-contracts.d.ts	18.3 kB	18.4 kB	+125 B

[thymikee]

Review at exact head 1600d40d077b02a547349396b0677d15902bb7ab: blocked on two comparison-lineage bugs plus the exact-head iOS failure.

1. snapshot-route.ts stamps XCTest fallback with the pre-acquisition target lineage. When bridge acquisition reports a stale/relaunched target, XCTest may capture the new app while the result is labeled with the old generation. Re-resolve before fallback or make that fallback explicitly incomparable, and add a stale-generation -> fallback regression.
2. Target-resolution failure creates a comparison identity with only stable targetId; two results with omitted generations compare equal. They can straddle an app relaunch and still be treated as one baseline. Unknown-generation fallback must fail closed across comparisons, with a closest-negative regression.
3. Exact-head iOS Smoke is red: the regular depth-1 fixture now routes through the bridge and no longer provides the asserted snapshotQuality.backend === "tree". Reconcile the shipped output/evidence contract and rerun the iOS lane green.

The route otherwise reuses the Apple runtime/facade and shutdown seams cleanly, and the merged source lifecycle already provides authoritative OS process-start-time checks around acquisition.

[thymikee]

Addressed all three actionable review items in fd3c6ac:

1. Stale acquisition: stale-target failures now resolve the current target again before XCTest fallback, and the regression proves the fallback identity carries the relaunched generation.
2. Unknown generation: resolution failures carry a typed per-capture unknown-generation residue. The closest-negative regression proves two otherwise identical unresolved fallbacks do not compare equal.
3. iOS smoke: the depth-frontier scenario now asserts the bridge public evidence shape (no XCTest tree quality annotation plus the acquisition evidence warning) for regular and raw captures.

Also normalized fallback lineage to the declared targetId/generation fields only.

Planted-red failures were observed for items 1 and 2 before the fix. Exact-head pnpm check:affected --run is green: 731 test files, 5,589 tests. The updated iOS native lane is running on this head.

[thymikee]

Re-review at exact head fd3c6ac226e6fe2fff5eb3aaf2ded51662aacf63 remains blocked. P1: exact-head iOS Simulator Smoke failed in the live fixture: snapshot --depth 1 published only the Application root and omitted visible-depth-projected-child. This was a successful bridge publication (not typed fallback), so it violates #2197's established regular-depth result and disproves readiness. Fix the acquisition/presentation route so bridge success preserves the visible-depth contract, then rerun the live lane. P2: the Size report shows +35.2 kB npm unpacked (+11.2 kB gzip), above the 3 kB review trigger, but the PR body does not itemize the growth or record why a materially smaller design was rejected. The architecture otherwise reuses the intended source facade, runtime binding, shared presentation engine, and interaction facade; all non-iOS checks pass.

[thymikee]

Follow-up from the exact-head iOS rerun: after the requested evidence assertion was corrected, the lane exposed a real bridge-depth bug rather than a test-only mismatch.

Regular --depth 1 was being sent to the native bridge as maxDepth: 1, so the TypeScript presenter never received the deeper structural nodes needed to project the visible child to presented depth 1. Fixed in 1519222: only rawTraversalDepth bounds native acquisition; regularPresentedDepth remains presentation-only.

A planted-red adapter test observed 1 instead of the bounded maximum 10, while raw depth 1 remained 1. Focused tests pass, and the rebased exact-head affected gate is green with 734 files / 5,624 tests.

[thymikee]

Exact-head iOS rerun is green at 1519222. It passed clean-install bridge preparation, targeted XCTest regressions, public CLI preflight, Settings replay, the fixture-backed E2E scenario with the corrected depth frontier, and gesture replay. All PR checks are now green.

[thymikee]

The exact-head depth fix is correct: regular --depth is presentation-only again, while only rawTraversalDepth bounds native acquisition. The regression test covers the old failure, exact-head iOS Smoke includes the real projected-child assertion plus raw-depth counterexample, and all checks are green.

One readiness item remains: CI reports +35.2 kB npm unpacked (+11.2 kB gzip). Because this exceeds the repository threshold, please itemize the justified package growth and record which materially smaller designs were considered and why they were rejected. Until that rationale is recorded, I’m holding ready-for-human.