refactor(capture): require complete runtime snapshots

[thymikee]

Summary

Require an assembled SnapshotState at the internal command-runtime boundary, consume it directly, and remove three reconstruction paths. Eight files changed; compiler-identified fixtures now carry canonical state facts.

The separate raw provider contract, public response annotations, sparse-store refusal, refs/session policy, and private clickability evidence are preserved. Review follow-up separates runtime/capture clocks in the stale-drop test and removes the unreachable createdAt fallback.

Validation

Tested head: b00861435086d40c78946e1083f01166ffa47236; rebased onto 22ae872676, including main's shared Coverage-gate repair (#3653).

• pnpm check:affected --base 22ae872676 --head b008614350 --run: passed; 1,477 related tests across 213 files.
• Snapshot suite: 34 passed. Omitting runtimeNow now fails the corrected clock regression; the planted edit was removed.
• Producer/export inventory confirms complete production states and an unchanged raw/public type. Response-level quality remains intentional warning/response metadata; assembly owns canonical state quality.

New-head CI coverage, provider and live-platform lanes must pass before merge. No manual device run was performed.

[cubic-dev-ai]

All reported issues were addressed across 8 files

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.24 MB	5.25 MB	+11.2 kB
Package (unpacked)	5.24 MB	5.25 MB	+11.2 kB
Package (download)	1.57 MB	1.58 MB	+3.3 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	18.9 ms	19.0 ms	+0.1 ms
CLI --help	51.8 ms	52.1 ms	+0.3 ms

[thymikee]

The code looks good at b264d2b, with no blocking findings. Typecheck & Package, Coverage, Repo Guards, Bundle Size and Smoke were still queued or running when I looked, so I have no CI result yet. I did not run typecheck or the tests; the claim that a loose result now fails typecheck comes from reading the required snapshot field and the required createdAt. No conflicts.

Not blocking, and you can take or leave these: snapshot.createdAt ?? warningTime in https://github.com/callstack/agent-device/blob/b264d2b/src/commands/capture/runtime/snapshot.ts#L217 can no longer reach its fallback, so you can use snapshot.createdAt directly. Also, the verdict on quality can still live in two places in https://github.com/callstack/agent-device/blob/b264d2b/packages/contracts/src/backend.ts#L45, result.quality and snapshot.snapshotQuality. The selector read now checks only the snapshot field. A future producer that sets only result.quality would skip the sparse refusal on get/is/wait/find, so making snapshot.snapshotQuality the single owner would close that.

One review thread still applies: the runtime-clock test fixture, #3642 (comment). The backend createdAt of 1_500 equals the clock value, so 'uses the runtime clock' would still pass if runtimeNow were dropped. Please put createdAt outside the recent window and keep the clock inside it.

Before merge, that thread needs a fix and the queued CI jobs need to go green.

[thymikee]

Investigated the successful Size job at b00861435086d40c78946e1083f01166ffa47236. Its detailed artifact accounts for the entire +11,242-byte unpacked difference:

• dist/apple/snapshot-presentation/Sources/AgentDeviceSnapshotPresentation/SnapshotPresentedSurface.swift: +11,983 bytes.
• dist/src/runtime-factory.js: −741 bytes.

The size comparison uses newer base 35c21b618ace55f2313124190d5674ea174e6d8b, including the Apple simplification from #3632. The Apple file has no diff between this PR's merge base 22ae872676213b27aeb97aeea1c83bbdecac9360 and its head, so that difference is upstream base advancement outside this PR. The changed runtime bundle shrank by 741 bytes. No code correction is needed for this report; remaining CI checks still need to finish.

[thymikee]

This PR is ready. At b008614 the earlier findings from the first review are fixed, and I have no new blocking findings.

Not blocking: SelectorCaptureResult in packages/daemon/src/execution/selector-capture-runtime.ts (https://github.com/callstack/agent-device/blob/b008614/packages/daemon/src/execution/selector-capture-runtime.ts#L81) adds & { snapshot: SnapshotState }, but BackendSnapshotResult.snapshot is now required, so you can use BackendSnapshotResult directly. You can take this or leave it.

The cubic-dev-ai P2 thread on the warning fixture (#3642 (comment)) no longer applies at this head, because the fixture now has createdAt 3_500 against a runtime clock of 1_500, so you can resolve it.

I did not run typecheck or tests, and I did not do a live device run. The change is a type-boundary refactor, and every in-repo producer I traced already returns a snapshot. External backends that return nodes without snapshot would now fail typecheck, and I found no in-repo producer of that shape.

18 of 19 checks pass, and only Smoke Tests is queued, with none failed. The diff touches no runner, Swift or device code, so I expect no change for that lane. Smoke Tests must go green on b008614 before merge.