Skip to content

Commit 49361de

Browse files
committed
docs: slim screen recording proposal
1 parent e35d0d4 commit 49361de

1 file changed

Lines changed: 18 additions & 99 deletions

File tree

‎docs/adr/0024-screen-recording-provable-signal.md‎

Lines changed: 18 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ Six rules make the table operational:
6868
A collection, validation, or commit failure preserves the material that a retry needs.
6969
Only session teardown and failed-start rollback invoke forced cleanup.
7070
Forced cleanup is never inferred from "finish threw".
71-
The mechanism is in the shared coordinator (`capture-kit/durable-capture/transitions.ts`).
71+
The mechanism is in the shared coordinator (the durable-capture transitions owner).
7272
But each kind must earn its scope.
7373
Each of app-log, audio-probe, and perf-capture gets its own failed-finish test that proves what its retry needs.
7474
A kind whose retry needs nothing keeps its current disposal explicitly.
@@ -79,74 +79,13 @@ the reduction of the Android device marker to marker-only content (2.6), and `--
7979

8080
## 1. Context
8181

82-
`record start` / `record stop` is one command family.
83-
But each of its fixes in the last three months touched 10 to 35 files (#2447, #2457, #2487, #2534, #2564, #2565, #2566).
84-
The subsystem has ~10,150 production lines and ~19,000 test lines across these areas:
85-
86-
- `contracts`
87-
- `capture-kit`
88-
- `host-kit`
89-
- four platform packages
90-
- nine `src/platform-runtime-screen-recording-*` hosts
91-
- eight daemon modules
92-
93-
Nine user-facing record bugs were filed since July 2026.
94-
In five of them, the ownership machinery refused because of its own uncertainty:
95-
96-
| Issue | Refusal | Native cause? |
97-
| --- | --- | --- |
98-
| #2549 | `ps` 1 s probe timed out under load → `cleanup-pending`, session wedged | no |
99-
| #2550 | device manifest `deviceId` ≠ current serial → "recovery evidence already exists" | no |
100-
| #2476 | reused pid → "completed evidence cannot be safely retired" | no |
101-
| #2281 | client window expired → no CLI path to the finished export | no |
102-
| #1117 | daemon lost session state → "no active recording" | no |
103-
| #2170 | CoreSimulator host lock after `SIGKILL` | yes |
104-
| #1651 | validator rejected a static single-frame clip; `moov` patched in place | yes |
105-
| #615 | `screenrecord` 180 s cap | yes |
106-
| #2551 | clip ends at the last screen change | yes |
107-
108-
Three facts make the fail-closed contract cost more than it protects:
109-
110-
- **Reattachment is already dead on four of five backends.**
111-
`reattachAppleRecording` and the HarmonyOS and web operations return `unreattachable` unconditionally.
112-
After daemon loss, `finishRecoveredDurableCapture` runs descriptor cleanup and then **throws**.
113-
It throws even when cleanup succeeded and the finalized MP4 is on disk.
114-
Only Android can answer `active` or `completed`.
115-
Ten ownership and outcome enums express distinctions that four backends cannot make.
116-
- **Daemon loss mid-recording is rare and already mitigated.**
117-
An active recording holds off the idle reaper.
118-
The startup reaper already sends `SIGINT` to orphaned `simctl recordVideo` children from `owned-processes.json`.
119-
The local daemon logs of the maintainer hold zero recording reattachments.
120-
All the reported failures are ordinary same-daemon stops.
121-
- **A failed export destroys its own retry.**
122-
`finishDurableCaptureHandle` calls `handle.forceCleanup()` when `finish` throws (`transitions.ts`, `compensateFailedFinish`).
123-
On Android, that reaches `cleanupVerifiedAndroidEvidence`, which removes the remote artifact and marker.
124-
A pull that fails once under load leaves nothing to pull a second time.
125-
126-
`#2551` was reproduced with raw `adb` on an API 36 emulator.
127-
`SIGINT` at +16 s produced a clip whose last frame is at +12.6 s, the last screen change.
128-
Changes after the last input were captured.
129-
The clip length comes from the change-driven encoding of `screenrecord`, not from our stop path.
130-
Disclosure (PR #2566) is the whole fix.
82+
A playable export and a stopped recorder are independent facts. The earlier recovery contract could refuse a usable export when ownership was uncertain. A failed export could also destroy the material that a retry needed. Platform backends need different identity and stop procedures, while the coordinator needs one guarded stop-and-export path.
13183

13284
## 2. Decision
13385

13486
### 2.1 Shape
13587

136-
```mermaid
137-
flowchart TD
138-
Commands["record start / stop"] --> Owner["Recording coordinator"]
139-
Recovery["Startup recovery / abandoned recordings"] --> Owner
140-
Owner <--> Manifest["Recording manifest<br/>identity + artifacts + committed export<br/>last recorder observation"]
141-
Owner --> Backend["Platform backend<br/>start · stop safely · collect"]
142-
Backend --> Apple["Apple"]
143-
Backend --> Android["Android"]
144-
Backend --> Harmony["HarmonyOS"]
145-
Backend --> Web["Web"]
146-
Owner --> Finalizer["Shared validation + post-processing"]
147-
Finalizer --> Commit["Commit export → return / replay"]
148-
Markers["Native orphan markers<br/>owned-processes.json, Android device marker<br/>cover incomplete starts"] -.-> Recovery
149-
```
88+
Commands and recovery use one recording coordinator. The coordinator owns the manifest and calls the platform backend and shared finalizer. Native orphan markers cover incomplete starts before a manifest exists.
15089

15190
The coordinator reuses the existing manifest store, fence, pending-transfer guard, and completed replay (PR #2534).
15291
There is no new framework.
@@ -237,7 +176,7 @@ Native-path disposition is complete only after fenced retirement succeeds or the
237176
A path marked retirable still needs its manifest until retirement completes.
238177

239178
**Checkpoints mark durable, valid artifacts; they never mark attempts.**
240-
`collected` is recorded only after the collected copy passes the playability sniff (`ftyp` + `moov`, the existing check in `video.ts`).
179+
`collected` is recorded only after the collected copy passes the playability sniff (`ftyp` + `moov`, the existing video check).
241180
Thus a pull of a not-yet-finalized MP4 leaves no checkpoint.
242181
`finalized` is recorded after the export is written.
243182
Step 1 records its observation.
@@ -249,7 +188,7 @@ A retry resumes at the first missing checkpoint, after it re-runs step 1 when it
249188
The collected copy is preserved until step 4 commits.
250189
The finalizer reads it and writes the export beside it.
251190
Thus a retry after a failed commit re-runs nothing that changes the video.
252-
Today, `exportProcessedVideo` applies the touch overlay **in place** (`overlay.ts` renames the processed file over its input; PR #2586 removed start trimming).
191+
Today, `exportProcessedVideo` applies the touch overlay **in place** (the overlay owner renames the processed file over its input; PR #2586 removed start trimming).
253192
That is why the copy is required: without it, a retry after a commit failure would burn the overlay twice.
254193
After commit, the collected copy is removed.
255194
A failed removal is a diagnostic, never an error.
@@ -282,7 +221,7 @@ settle recorder (request: recovery only)
282221

283222
1. If the session already holds a live handle, refuse (`recording already in progress`).
284223
2. If the recording manifest of the device is `open` and **actively owned**, refuse.
285-
Actively owned means: the owner named in the manifest is alive by the existing owner-identity check (`host-kit/internal/owner-identity.ts`), and that owner holds the fence.
224+
Actively owned means: the owner named in the manifest is alive by the existing host-kit owner-identity check, and that owner holds the fence.
286225
This is the ADR 0019 rule, and it is unchanged.
287226
3. Otherwise, the manifest is abandoned or completed.
288227
Hand it to recovery (2.5) under the ownership guard **before** launch.
@@ -368,7 +307,7 @@ Section 5 currently has these requirements:
368307

369308
- Every durable facet exposes `reattach` and `cleanup`.
370309
- Uncertain cleanup stays `cleanup-pending`.
371-
- When finish throws, forced cleanup runs (in `transitions.ts`).
310+
- When finish throws, forced cleanup runs in the durable-capture transitions owner.
372311

373312
The proposed amendment:
374313
*Screen recording would be a **stop-and-collect** resource.
@@ -389,15 +328,15 @@ This step comes after 2.1–2.7, and 2.1–2.7 do not require it.
389328

390329
## 3. Cross-platform matrix
391330

392-
| Backend | `stop` from a live handle | `stop` from a descriptor (recovery) | `collect` | Today after daemon loss |
393-
| --- | --- | --- | --- | --- |
394-
| iOS / tvOS simulator | `ChildProcess.kill` tiers; descendant markers probed before pid signals | probe markers; signal on ours; `unconfirmed` if the host is silent; `lost` on mismatch | local copy of the `simctl` output file; native file retained until the writer is proven gone | cleanup signals, then **throws** |
395-
| iOS device (CoreDevice), macOS | runner stop RPC bound to `runnerSessionId` | same RPC if the runner session matches; `lost` if the runner restarted | device copy (iOS); local copy of the runner's output file (macOS) | cleanup stops the runner, **never retrieves**, throws |
396-
| Android | probe `/proc`, then `kill -2` → `-9`; `unconfirmed` when `/proc` is unreadable | same, from the pid triple in the descriptor | `adb pull` of every chunk, playability sniff | reattach through the device manifest; five ownership states |
397-
| HarmonyOS | one `aa start` toggle, tracked by the handle | **no signal**; `mediatool query` by file name; `unconfirmed` if found, `lost` if not | stage + `hdc file recv` | `cleanup-pending`, manual |
398-
| Web | provider `record stop` on the session browser | stop if the browser is alive, else `lost` | local copy of the WebM; native file retained while the browser is not proven gone | `cleanup-pending`, manual |
399-
| Limrun (iOS, Android) | provider stop RPC on the live session; the served download URL is memoized so a stop is never repeated | **no signal**: the recording lives and dies with the instance; `unreattachable` | HTTP download of the served MP4 to the output path, bounded by a deadline that ends inside the `record` request window (60 s of its 90 s envelope) and not cancellable; retriable from the memoized URL while the instance lives | `cleanup-pending`, manual; the instance (and its file) is deleted on lease release |
400-
| WebDriver providers, Vega | unavailable | — | — | unchanged |
331+
| Backend | `stop` from a live handle | `stop` from a descriptor (recovery) | `collect` |
332+
| --- | --- | --- | --- |
333+
| iOS / tvOS simulator | `ChildProcess.kill` tiers; descendant markers probed before pid signals | probe markers; signal on ours; `unconfirmed` if the host is silent; `lost` on mismatch | local copy of the `simctl` output file; native file retained until the writer is proven gone |
334+
| iOS device (CoreDevice), macOS | runner stop RPC bound to `runnerSessionId` | same RPC if the runner session matches; `lost` if the runner restarted | device copy (iOS); local copy of the runner's output file (macOS) |
335+
| Android | probe `/proc`, then `kill -2` → `-9`; `unconfirmed` when `/proc` is unreadable | same, from the pid triple in the descriptor | `adb pull` of every chunk, playability sniff |
336+
| HarmonyOS | one `aa start` toggle, tracked by the handle | **no signal**; `mediatool query` by file name; `unconfirmed` if found, `lost` if not | stage + `hdc file recv` |
337+
| Web | provider `record stop` on the session browser | stop if the browser is alive, else `lost` | local copy of the WebM; native file retained while the browser is not proven gone |
338+
| Limrun (iOS, Android) | provider stop RPC on the live session; the served download URL is memoized so a stop is never repeated | **no signal**: the recording lives and dies with the instance; `unreattachable` | HTTP download of the served MP4 to the output path, bounded by a deadline that ends inside the `record` request window (60 s of its 90 s envelope) and not cancellable; retriable from the memoized URL while the instance lives |
339+
| WebDriver providers, Vega | unavailable | — | — |
401340

402341
Two traps stay visible:
403342

@@ -541,30 +480,10 @@ Each backend proves the ordinary stop, the host-silent stop, the post-daemon-los
541480

542481
## 8. End state
543482

544-
| Area | Before | After step 4 | After step 5 |
545-
| --- | --- | --- | --- |
546-
| `contracts` recording types, ops, plan | 505 | ~350 | ~350 |
547-
| `platform-android/recording` | 1,566 | ~1,100 | ~800 |
548-
| `platform-apple/recording` | 685 | ~450 | ~450 |
549-
| `platform-harmonyos/recording` | 386 | ~300 | ~300 |
550-
| `platform-web/recording` | 171 | ~140 | ~140 |
551-
| nine `src/platform-runtime-screen-recording-*` hosts | 1,325 | ~1,100 | ~1,000 |
552-
| `src/daemon` recording modules | 899 | ~500 | ~500 |
553-
| shared: finalizer, durable-capture, host-kit, commands, layering, Swift | ~4,600 | ~4,600 | ~4,600 |
554-
| **Recording-specific total** | **~10,150** | **~8,500** | **~8,100** |
555-
| Recording test lines | ~19,000 | ~15,000 | ~14,000 |
556-
| Ownership / outcome enums | 10 | 3 | 3 |
557-
| Runtime operations for recording | 3 (start, reattach, cleanup) | 3 (start, stop, collect) | 3 |
558-
| `record stop` paths | 2 (live; recovery that throws on 4 backends) | 1 | 1 |
559-
| Files on an Android stop path | 9 | ~7 | ~6 |
560-
561-
The reduction is modest, because the device marker stays, the root host files stay, and rotation stays below API 34.
562-
What this design buys is one path, one store, three enums, and no refusal that a silent host or a reused pid can produce.
563-
A later, separate ADR may fold the nine root host files into per-platform transports once the layering gates (R16) are re-cut.
564-
That is shape, not policy, and no row of the table in section 1 needs it.
483+
The proposed end state has one stop path and one lifecycle store. Rotation remains below API 34. A later, separate ADR may fold the root host files into per-platform transports once the R16 layering gates are re-cut.
565484

566485
Deletion test:
567486

568487
- `screenRecordingReattach`, `screenRecordingCleanup`, `cleanup-pending` for recording, and `ScreenRecordingAdmissionLedger` no longer exist in production.
569-
- `transitions.ts` has no cleanup-on-failed-finish path.
488+
- The durable-capture transitions owner has no cleanup-on-failed-finish path.
570489
- Every situation in the rules table has a passing test on every backend where it applies.

0 commit comments

Comments
 (0)