refactor: model recording backends

[thymikee]

Summary

Model recording start/stop behind daemon recording backends so the record handler owns lifecycle while platform-specific execution stays below the backend seam.

Adds focused iOS simulator recording implementation module, documents the Recording backend term, and removes unused speculative backend hooks from the refactor layer.

Touched files: 4; scope is recording handler architecture only.

Validation

Verified with direct local binaries from the existing installed worktree because this temporary worktree could not install dependencies under restricted registry access: formatter passed, TypeScript passed, focused recording tests passed, and build/declaration bundling passed.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.3 MB	1.3 MB	+1.2 kB
JS gzip	437.1 kB	437.3 kB	+227 B
npm tarball	575.0 kB	575.4 kB	+353 B
npm unpacked	1.9 MB	1.9 MB	+1.2 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	29.6 ms	28.8 ms	-0.7 ms
CLI --help	52.3 ms	49.6 ms	-2.7 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/record-trace-recording.js	+1.2 kB	+227 B

[thymikee]

Review pass complete: I did not find actionable blockers on latest green head 4086f9b. Checked the recording backend extraction against the production start/stop route: start still validates flags, resolves the backend by device, expands and clears output, then delegates to the existing iOS simulator, iOS device, macOS, and Android implementations; stop resolves by the active recording platform and preserves invalidation and finalization handling. CI is green. Residual risk is low because this is an internal refactor and does not claim new live device behavior.

[thymikee]

Review — refactor: model recording backends (#893)

This PR extracts recording start/stop into per-platform RecordingBackend objects (resolveRecordingBackendForDevice / ...ForRecording), moves the iOS-simulator implementation into its own module, and documents the "Recording backend" term in CONTEXT.md. The lifecycle code in startRecording/stopRecording is now dispatch-only, and the moved start/stop bodies are byte-identical to the originals.

Verified: the else → unsupportedRecordingBackend routing change is not a regression — record capability is apple/android only, and isCommandSupportedOnDevice('record', device) already rejects linux/web before backend.start is reached. Import removals, async-conversion of releaseRecordOnlySession, and the ios/android stop split all check out. No correctness regressions survived verification.

Two cleanup/altitude findings — speculative generality the new seam adds with no current payoff:

1. src/daemon/handlers/record-trace-recording-backends.ts:306,310 — validateStart and cleanupRecordOnlySession hooks are declared and called but no backend implements either.
startRecording calls backend.validateStart?.(req) and releaseRecordOnlySession now awaits backend.cleanupRecordOnlySession?.(session), yet none of the five backend literals define these. The hooks are dead call sites today, and releaseRecordOnlySession was converted sync→async (with both call sites updated to await) solely to support a hook nothing implements. Cost: extra surface + an async conversion that buys nothing now — either wire up a real implementation or drop the hooks until needed.

2. record-trace-recording-backends.ts:274,337 — resolveOutputPath's { ok: false; response } branch is unreachable.
RecordingOutputPathResult is a discriminated union, but every backend uses resolveNativeRecordingOutputPath, which always returns { ok: true, path }. The if (!outputPath.ok) return outputPath.response guard in startRecording can never fire. Cost: dead error-handling path; resolveOutputPath could just return string until a backend genuinely needs to reject.

Both are judgment calls for an intentional seam, but as written they add complexity without a current consumer.

[thymikee]

Addressed in 897a0db97.

For #893 specifically, I removed the unused validateStart and cleanupRecordOnlySession backend hooks, made releaseRecordOnlySession synchronous again, and simplified resolveOutputPath to return a string instead of an unreachable { ok: false } branch.

The stacked web feature PR (#891) reintroduces validateStart/cleanupRecordOnlySession as concrete web feature hooks, because web needs to reject native recording flags before native fps validation and close the browser provider for record-only cleanup. Keeping those out of #893 leaves the refactor PR non-speculative while still keeping web-specific lifecycle below the backend seam in the feature layer.

[thymikee]

Follow-up review on 897a0db: the cleanup findings are addressed. The unused validateStart and cleanupRecordOnlySession hooks are gone, releaseRecordOnlySession is synchronous again, and resolveOutputPath now returns a string without the unreachable error branch. CI is green and the PR remains a behavior-preserving internal recording-backend refactor. I do not see remaining blockers; merge-ready from this review pass.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-26 16:30 UTC