You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a46f3e7
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/adr/0024-screen-recording-provable-signal.md
+13-9Lines changed: 13 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -68,7 +68,7 @@ Six rules make the table operational:
68
68
A collection, validation, or commit failure preserves the material that a retry needs.
69
69
Only session teardown and failed-start rollback invoke forced cleanup.
70
70
Forced cleanup is never inferred from "finish threw".
71
-
The mechanism is in the shared coordinator (the durable-capturetransitions owner).
71
+
The mechanism is in the shared coordinator (`packages/capture-kit/src/durable-capture/transitions.ts`).
72
72
But each kind must earn its scope.
73
73
Each of app-log, audio-probe, and perf-capture gets its own failed-finish test that proves what its retry needs.
74
74
A kind whose retry needs nothing keeps its current disposal explicitly.
@@ -79,13 +79,17 @@ the reduction of the Android device marker to marker-only content (2.6), and `--
79
79
80
80
## 1. Context
81
81
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.
82
+
A playable export and a stopped recorder are independent facts. The ADR 0019 section 5 contract refuses a usable export when ownership is uncertain. Its forced cleanup after a failed finish can destroy the material that a retry needs. On Android, forced cleanup after a failed pull can remove the remote artifact and the marker, so a retry has nothing to pull. Screen recording now preserves retry material after a failed finish. Platform backends need different identity and stop procedures, while the coordinator needs one guarded stop-and-export path.
83
+
84
+
HarmonyOS and web reattachment return `unreattachable`. Android can report `active` or `completed`; Apple can return an `active` export-restoration handle when a simulator recorder is gone and its export remains recoverable. An active recording holds off the idle reaper, and the startup reaper initially sends `SIGINT` to orphaned owned `simctl recordVideo` processes.
85
+
86
+
#2551's short clips come from `screenrecord`'s change-driven encoding, not the stop path; disclosure (PR #2566) is the fix.
83
87
84
88
## 2. Decision
85
89
86
90
### 2.1 Shape
87
91
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.
92
+
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, and recovery reads them.
89
93
90
94
The coordinator reuses the existing manifest store, fence, pending-transfer guard, and completed replay (PR #2534).
91
95
There is no new framework.
@@ -176,7 +180,7 @@ Native-path disposition is complete only after fenced retirement succeeds or the
176
180
A path marked retirable still needs its manifest until retirement completes.
177
181
178
182
**Checkpoints mark durable, valid artifacts; they never mark attempts.**
179
-
`collected` is recorded only after the collected copy passes the playability sniff (`ftyp` + `moov`, the existing video check).
183
+
`collected` is recorded only after the collected copy passes the playability sniff (`ftyp` + `moov`, the existing video check in `packages/capture-kit/src/recording/video.ts`).
180
184
Thus a pull of a not-yet-finalized MP4 leaves no checkpoint.
181
185
`finalized` is recorded after the export is written.
182
186
Step 1 records its observation.
@@ -188,7 +192,7 @@ A retry resumes at the first missing checkpoint, after it re-runs step 1 when it
188
192
The collected copy is preserved until step 4 commits.
189
193
The finalizer reads it and writes the export beside it.
190
194
Thus a retry after a failed commit re-runs nothing that changes the video.
191
-
Today, `exportProcessedVideo` applies the touch overlay **in place** (the overlay owner renames the processed file over its input; PR #2586 removed start trimming).
195
+
Today, `exportProcessedVideo` applies the touch overlay **in place** (`packages/capture-kit/src/recording/overlay.ts` renames the processed file over its input; PR #2586 removed start trimming).
192
196
That is why the copy is required: without it, a retry after a commit failure would burn the overlay twice.
1. If the session already holds a live handle, refuse (`recording already in progress`).
223
227
2. If the recording manifest of the device is `open` and **actively owned**, refuse.
224
-
Actively owned means: the owner named in the manifest is alive by the existing host-kitowner-identity check, and that owner holds the fence.
228
+
Actively owned means: the owner named in the manifest is alive by the existing owner-identity check in `packages/host-kit/src/internal/owner-identity.ts`, and that owner holds the fence.
225
229
This is the ADR 0019 rule, and it is unchanged.
226
230
3. Otherwise, the manifest is abandoned or completed.
227
231
Hand it to recovery (2.5) under the ownership guard **before** launch.
@@ -307,7 +311,7 @@ Section 5 currently has these requirements:
307
311
308
312
- Every durable facet exposes `reattach` and `cleanup`.
309
313
- Uncertain cleanup stays `cleanup-pending`.
310
-
- When finish throws, forced cleanup runs in the durable-capturetransitions owner.
314
+
- When finish throws, forced cleanup runs in `packages/capture-kit/src/durable-capture/transitions.ts`.
311
315
312
316
The proposed amendment:
313
317
*Screen recording would be a **stop-and-collect** resource.
@@ -480,10 +484,10 @@ Each backend proves the ordinary stop, the host-silent stop, the post-daemon-los
480
484
481
485
## 8. End state
482
486
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.
487
+
The proposed end state has one stop path, one lifecycle store, three ownership and outcome enums (from ten), and three runtime operations: start, stop, collect. 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.
484
488
485
489
Deletion test:
486
490
487
491
-`screenRecordingReattach`, `screenRecordingCleanup`, `cleanup-pending` for recording, and `ScreenRecordingAdmissionLedger` no longer exist in production.
488
-
-The durable-capturetransitions owner has no cleanup-on-failed-finish path.
492
+
-`packages/capture-kit/src/durable-capture/transitions.ts` has no cleanup-on-failed-finish path.
489
493
- Every situation in the rules table has a passing test on every backend where it applies.
0 commit comments