refactor(ios): implement snapshot engine

[thymikee]

Summary

Slice B of #2191 (“refactor(ios): build and prove the converged snapshot engine”), stacked on #2206 at exact head 4ef845fe1fec3d0cd4ed9a17cfcad703a35bea45.

• Moves the iOS snapshot engine and semantic compaction ownership to @agent-device/capture-kit/ios-snapshot-engine: planning, viewport/cumulative clip folding, regular/raw projection, scope/depth, eligibility/actionability, hints, lineage, invariants, and publication.
• Migrates production consumers/tests to the package subpath and deletes the old src/snapshot/snapshot-presentation/ios façade/noise owner.
• No live producer selection, routing, public wire shape, or integration behavior change; this establishes the one engine owner for the later runner integration.

Scope and design rationale: 43 touched files, +2,047/-463 vs #2206. Itemized growth is the new capture-kit engine modules/tests and one explicit package export, offset by renames/deletions from the old semantic path and migrated consumers/tests. A materially smaller patch that kept the old façade/import surface was rejected because it would leave the superseded path as an effective second owner and make the one-engine invariant unenforceable; splitting the engine across existing packages would do the same. Bundle evidence is bounded: JS source +1.2 kB, npm unpacked +1.2 kB, tarball +210 B; Apple runner and other package components unchanged.

Validation

Exact reviewed head: 6fd7576902065aa38b70e7ed869385bd13f1dbec

• pnpm build
• pnpm typecheck
• pnpm exec vitest run --project unit-core packages/capture-kit/src/ios-snapshot-engine/engine.test.ts (11/11)
• Exact-head iOS Smoke Tests passed native runner build, targeted XCTest, CLI preflight, Settings replay, fixture-backed iOS Simulator E2E (15/15), gesture replay, and artifact upload.
• Recorded fixture coverage includes smoke:regular-visible-depth-frontier: public regular depth 1 kept the raw-deep visible-depth-projected-child at presented depth 1 with wrapper reparenting, while raw full/depth-bounded output preserved the acquisition frontier; smoke:automation-input, smoke:form-input, and smoke:capture-close also passed.
• Exact-head CI static/package/native checks for refactor(ios): implement snapshot engine #2211 are green: lint/format, typecheck/package, integration, coverage, Repo Guards, Compatibility & Provenance, Android, Linux, macOS, bundle size, test-app cache, Agent Guidance, and CodeQL.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	2.55 MB	2.55 MB	+1.2 kB
JS gzip	857.4 kB	857.6 kB	+254 B
npm tarball	979.4 kB	979.6 kB	+210 B
npm unpacked	3.38 MB	3.39 MB	+1.2 kB

npm unpacked components

Component	Base	Current	Diff
JS / dist source	2.71 MB	2.71 MB	+1.2 kB
Apple runner source/project	543.4 kB	543.4 kB	0 B
macOS helper source	54.8 kB	54.8 kB	0 B
Android helper artifacts	0 B	0 B	0 B
Other package files	79.7 kB	79.7 kB	0 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	32.9 ms	33.2 ms	+0.3 ms
CLI --help	83.2 ms	83.8 ms	+0.6 ms

Top changed chunks: no changes in the largest emitted chunks.

Top changed packed files

Packed file	Base	Current	Diff
dist/src/snapshot-state.js	20.3 kB	21.5 kB	+1.2 kB

[thymikee]

Re-reviewed exact head 490c83fb69199e06e5ddef9ee7a7efacde07346c: BLOCKED.

1. scripts/package-apple-runner-source.mjs adds snapshotPresentationRunnerManifest and installSnapshotPresentationRunnerManifest, but the exact parent already owns those concerns through requireSnapshotPresentationManifest / copySnapshotPresentationManifest. The new pair is unused duplicate code and makes exact-head lint fail. Delete it; do not add a second construction path.
2. Complete the ownership move. src/snapshot/snapshot-presentation/ios/index.ts and noise.ts are now compatibility re-export facades, while live consumers such as src/core/snapshot-state.ts and src/daemon/adapters/maestro/daemon-runtime-port-observation.ts still import the old path. Migrate production consumers/tests to @agent-device/capture-kit/ios-snapshot-engine and delete the old facades; an internal barrel/shim leaves the superseded surface as the effective owner.
3. Remove the new .fallowrc.json waiver for unused iosSnapshotEngine. Its paragraph says a later PR will consume it, which confirms this slice has no current production consumer. Do not ship/allowlist future dead API: expose the currently used factory/named functions now and add the default object only at its true integration point.

The Android Integration failure (IME recovery records could not be persisted) is unrelated to this iOS slice and looks like lane noise, but the exact-head lane still must rerun green. iOS Smoke is pending. The PR is also above the size scrutiny threshold (+2,179/-566; +15.5 kB unpacked) and its body is only stack boilerplate. Add the #2191 slice-B scope, itemized justified growth and why a smaller design was rejected, exact validation, and live iOS Simulator evidence for the moved semantic-compaction route. No readiness label until the code findings and confirmed failing CI are resolved.

[thymikee]

Re-reviewed exact head 8917129db3813d63e2455c35edf1001d0b566d1b: the prior code findings are resolved and all exact-head checks are green. The duplicate manifest construction path, internal re-export facades, and dead-export waiver are gone; the ownership move is now coherent.

BLOCKED only on readiness evidence: replace the stack boilerplate body with the #2191 slice-B scope, itemized move/growth rationale and why a materially smaller design was rejected, exact-head validation, and recorded iOS Simulator proof for the moved semantic-compaction route. Green iOS Smoke does not document that changed-path evidence.

[thymikee]

Re-reviewed exact head 8e3a26e94b97ee3f85a321e5daceddfb203aa04a: prior code findings remain resolved.

BLOCKED on readiness evidence: the body is only stack boilerplate, so the #2191 slice-B scope, itemized growth and materially-smaller-design rationale, exact-head validation, and recorded iOS Simulator semantic-compaction proof are absent. This rebase also cancelled prior lanes; current exact-head CI has not completed. No readiness label.

[thymikee]

Re-reviewed exact head 8e3a26e94b97ee3f85a321e5daceddfb203aa04a: prior code/ownership findings remain resolved, and exact-head CI is now green, including iOS Smoke. The updated body now records #2191 Layer B, scope, ownership rationale, exact head, and stack validation.

Still BLOCKED on readiness record: there is no recorded real iOS Simulator command/outcome for the moved semantic-compaction route, nor a precise blocker/residual-risk statement. The validation section is also stale because it says iOS Smoke is still in progress, and the >700-line growth rationale remains aggregate rather than itemizing the principal moved/new categories. Add the changed-path Simulator evidence, update the completed checks, and itemize justified growth before labeling.

[thymikee]

Re-reviewed new exact head 6fd7576902065aa38b70e7ed869385bd13f1dbec: this is a correct restack on current #2206; the slices own code is unchanged and no new code/architecture finding emerged.

Still BLOCKED on readiness. The body remains stamped at old 8e3a26…, says iOS is pending, and still lacks a recorded real-Simulator semantic-compaction command/outcome or precise blocker/residual-risk statement. The >700-line growth rationale remains aggregate rather than itemizing the principal moved/new categories. Prior checks were cancelled; replacement exact-head CI is queued/in progress. Update the exact-head evidence, itemize growth, and record changed-path Simulator proof before labeling.

[thymikee]

Re-reviewed exact head 6fd7576902065aa38b70e7ed869385bd13f1dbec: prior code findings and readiness blockers are fully resolved. The body now records Slice B scope, itemized move/growth rationale, rejected smaller designs, and bounded package growth. All current-head checks are green, including iOS Smoke; its Simulator run exercised the presentation/viewport/depth XCTest suite and 15/15 fixture E2E, with smoke:regular-visible-depth-frontier proving wrapper reparenting and raw/frontier preservation on the moved semantic-compaction route. No new finding. READY for human review and merge-ready.

[thymikee]

Addressed in the PR body at exact head 6fd7576902065aa38b70e7ed869385bd13f1dbec: it now records the #2191 Slice B scope, itemized growth and materially-smaller-design rationale, exact-head validation, and the recorded iOS Simulator semantic-compaction evidence. The exact-head required checks are green. No readiness label was added.

[thymikee]

Reconciled unchanged exact head 6fd7576902065aa38b70e7ed869385bd13f1dbec: code, stack, body, readiness label, green exact-head CI, and Simulator semantic-compaction evidence are unchanged. The prior READY/merge-ready verdict stands.