@pictor-sdk/video-android 0.1.0

package/android/src/main/java/dev/pictor/video/ExportGate.kt

@@ -0,0 +1,1974 @@
+package dev.pictor.video
+
+import android.content.Context
+import android.media.MediaExtractor
+import android.media.MediaFormat
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import androidx.media3.common.Effect
+import androidx.media3.common.MediaItem
+import androidx.media3.common.C
+import androidx.media3.common.audio.SpeedProvider
+import androidx.media3.effect.FrameDropEffect
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.transformer.Composition
+import androidx.media3.transformer.EditedMediaItem
+import androidx.media3.transformer.EditedMediaItemSequence
+import androidx.media3.transformer.ExportException
+import androidx.media3.transformer.ExportResult
+import androidx.media3.transformer.Effects
+import androidx.media3.transformer.Transformer
+import com.google.common.collect.ImmutableList
+import java.io.File
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicLong
+import org.json.JSONObject
+
+/**
+ * The V3.3 Transformer–Skia GL interoperability **gate**.
+ *
+ * Not an exporter. It encodes one media item to an adapter-private temporary
+ * file and reports what came out, so the question "can Skia draw inside
+ * Transformer's frame processor without changing the picture" can be answered
+ * with measurements instead of an opinion. Nothing here maps a `VideoProject`,
+ * and nothing here is reachable from `VideoExporter`.
+ *
+ * ## Two runs, in this order, always
+ *
+ * **Vanilla first.** A Transformer run with no effect establishes what the codec
+ * alone does to the picture — decode, re-encode and mux are lossy, and a
+ * comparison threshold chosen after seeing the Skia output would be a threshold
+ * chosen to pass. The floor is measured, frozen, and only then is the effect
+ * run evaluated against it.
+ *
+ * That run must be forced to **re-encode**. Left alone, Transformer transmuxes a
+ * source it does not need to touch — it finished in 400 ms, produced a 630 KB
+ * file against the effect run's 2.4 MB, and reported no colour information at
+ * all, because nothing was decoded. A transmux is a byte copy: its codec noise
+ * is zero, and a threshold frozen from it would declare every real difference a
+ * failure. `setTransmuxVideo(false)` is what makes the baseline a baseline.
+ *
+ * ## Audio
+ *
+ * **Audio is copied through unmodified**, by not asking Transformer to do
+ * anything with it. This gate is about video frames; speed, mixing and pitch are
+ * V3.5 and are deliberately absent. A run whose input has no audio track simply
+ * has none in its output, which the metadata check reports rather than assumes.
+ *
+ * ## Destination
+ *
+ * Adapter-private and temporary: `context.cacheDir`, deleted by
+ * [releaseTemporary]. `VideoExportSpec.destination` is a V3.6 decision and is
+ * not being pre-empted by a gate.
+ */
+@UnstableApi
+internal class ExportGate(private val context: Context) {
+
+    /** What one run produced. Numbers and strings only — Media3 stops here. */
+    data class Outcome(
+        val ok: Boolean,
+        val uri: String,
+        val error: String,
+        /** Wall time from `start` to the callback, in milliseconds. */
+        val elapsedMs: Long,
+        val fileBytes: Long,
+        val durationMs: Long,
+        val width: Int,
+        val height: Int,
+        /** Frames the encoder reported writing. */
+        val videoFrameCount: Int,
+        val hasAudio: Boolean,
+        val videoMimeType: String,
+        val audioMimeType: String,
+        val colorInfo: String,
+        /** `glGetError` values seen inside the effect, joined. Empty is the pass. */
+        val glErrors: String,
+        /** Frames the effect saw. Zero on a vanilla run. */
+        val effectFrames: Long,
+        /** Presentation timestamps in, joined — to compare against what came out. */
+        val effectTimestampsUs: String,
+        /** Where Transformer ran the effect: context, thread, and any changes. */
+        val boundary: String,
+        /** GL programs created and deleted, and on which threads. */
+        val lifecycle: String,
+        /** Segments the program selected, and any window mismatch. */
+        val programTrace: String,
+        /** What the final mux copied, against what produced it. */
+        val muxTrace: String = "",
+        /** Rasters uploaded, and textures freed, for leak accounting. */
+        val overlayUploads: Long,
+        val overlayDraws: Long,
+        val overlayTexturesFreed: Long,
+        /** Native heap allocated after the run, in bytes. */
+        val nativeHeapBytes: Long,
+        /** Java heap in use after the run, in bytes. */
+        val javaHeapBytes: Long,
+        /** The thread `run` was called on, so single-thread access is checkable. */
+        val callerThread: String,
+    )
+
+    private val main = Handler(Looper.getMainLooper())
+
+    /**
+     * Files this gate created, so a caller can prove it left none behind.
+     *
+     * A failed run must leave no partial file. Transformer writes to the path it
+     * was given as it goes, so the path is remembered before the run starts and
+     * deleted when the run fails.
+     */
+    private val created = mutableListOf<File>()
+
+    /*
+      Accounting, split three ways.
+
+      `runs == releases` on its own is ambiguous: a scene refused before
+      Transformer started allocated nothing, so counting it alongside a real
+      export makes a balanced tally that proves nothing about cleanup. What
+      matters is that every export that **started** also released, and refusals
+      are tracked separately so they cannot flatter that number.
+    */
+    /*
+      Cancellation, reaching the Transformer rather than only the promise.
+
+      A Transformer nobody is listening to still encodes, still writes and still
+      holds its codecs, so rejecting in JavaScript would leave a cancelled UI
+      over a running export. The handle is kept while one is in flight and
+      cleared the moment it finishes, and `cancelled` is checked between stages
+      so a cancel that arrives between two Transformer runs is not ignored until
+      the next one ends.
+    */
+    @Volatile private var currentJob: String? = null
+    @Volatile private var cancelled = false
+    @Volatile private var activeTransformer: Transformer? = null
+    /*
+      The run's latch, so a cancellation can end the wait.
+
+      `Transformer.cancel()` does not call the listener — traced: cancel entered
+      and exited on the main thread in 47 ms, and no `onCompleted` or `onError`
+      ever followed. The run's latch was therefore never counted down and the
+      export sat on `latch.await` until its timeout, which is where the seconds
+      came from once the cancel finally reached the Transformer at all.
+    */
+    @Volatile private var activeLatch: CountDownLatch? = null
+
+    /**
+     * Whether to hash every sample to prove the mux copied rather than encoded.
+     *
+     * Conformance work. Off in production, because an export should not pay to
+     * verify itself, and a watchdog calibrated with it present would be
+     * calibrated against work the user never runs.
+     */
+    /**
+     * Whether a conformance run has armed the gate controls *within a build that
+     * has them at all*.
+     *
+     * Scoping only. Whether they exist is [Diagnostics.ENABLED], decided at
+     * compile time — this cannot widen that, only narrow it, which is why every
+     * read below is the conjunction. A release build has the constant false, so
+     * no value here makes any difference.
+     */
+    @Volatile var armed: Boolean = false
+
+    /** Armed *and* built with the controls. Every gate-only site reads this. */
+    val diagnostics: Boolean
+        get() = Diagnostics.ENABLED && armed
+
+    @Volatile var provenance: Boolean = false
+
+    /**
+     * Gate-only: wedge the cadence program after N frames, on any shard.
+     *
+     * Set out of band rather than through the shard descriptor, because the
+     * production exporter builds those and must not gain a fault field to make
+     * a gate reachable. -1 is off.
+     */
+    @Volatile var stallAfterFrames: Int = -1
+
+    /**
+     * Gate-only: fail the publication at a chosen point.
+     *
+     * `"stage"` — the copy fails. `"afterStage"` — everything is written and
+     * verified and the rename does not happen. `"raceCreate"` — something else
+     * creates the target between validation and publication, which is the race
+     * the atomic no-replace exists for and which no amount of retrying produces
+     * on demand. `""` is off.
+     */
+    @Volatile var publishFault: String = ""
+
+    /** Whether the job in flight has been asked to stop. */
+    fun isCancelled(): Boolean = cancelled
+
+
+    /*
+      Cancels that arrive before the job registers.
+
+      `exportRunProjectAsync` is dispatched by the bridge, so a cancel issued
+      immediately after the call can reach native *first* — `cancelJob` then
+      finds no job with that id and drops the request on the floor. Measured:
+      such a cancel took 4.5 s to settle and the export ran to completion,
+      because only the JavaScript checkpoint after the native call ever saw it.
+
+      Remembering the id closes the window. Bounded, because a job either
+      begins and consumes its entry or was never going to.
+    */
+    private val pendingCancels = HashSet<String>()
+
+    /** Take the job. Returns false if another is already running. */
+    fun beginJob(jobId: String): Boolean {
+        synchronized(this) {
+            if (currentJob != null) return false
+            currentJob = jobId
+            cancelled = pendingCancels.remove(jobId)
+            resetHeartbeats()
+            // Ownership starts here and ends in `endJob`: beats from the job
+            // before this one carry an older epoch and are discarded.
+            ExportProgress.begin(ExportHeartbeat.attach { source -> heartbeat(source) })
+            return true
+        }
+    }
+
+    /** Give the job back, whatever happened to it. */
+    fun endJob() {
+        synchronized(this) {
+            currentJob = null
+            cancelled = false
+            activeTransformer = null
+            ExportHeartbeat.detach()
+            ExportProgress.end()
+        }
+    }
+
+    /**
+     * Stop `jobId`, if it is the one running.
+     *
+     * The id is checked so a cancel that arrives late cannot stop a different
+     * export that started in the meantime.
+     */
+    fun cancelJob(jobId: String): Boolean {
+        synchronized(this) {
+            if (currentJob != jobId) {
+                // Not running yet, or already finished. Remembered either way:
+                // an id that never begins simply leaves an unused entry.
+                pendingCancels.add(jobId)
+                return false
+            }
+            cancelled = true
+        }
+        val running = activeTransformer
+        if (running != null) {
+            // Transformer is main-thread only; cancelling from the export's own
+            // worker would be the same crash this gate wraps elsewhere.
+            main.post {
+                runCatching { running.cancel() }
+                // `cancel()` is silent, so the waiter is released here. Without
+                // this the run waits out its whole timeout after being stopped.
+                activeLatch?.countDown()
+            }
+        }
+        return true
+    }
+
+    /*
+      Three domains, never added together.
+
+      Reporting "started 29, completed 29, cancelled 10" as one balance was
+      incoherent: `started` counted Transformer runs, several per export, while
+      `cancelled` counted export jobs. The numbers were fine and the arithmetic
+      was nonsense, which is the worse kind of wrong — it reads like a
+      reconciliation.
+
+      Within the run domain a terminal outcome is exactly one of succeeded,
+      cancelled or failed, and **release is not one of them**: a run that failed
+      still releases, so releasing is lifecycle accounting kept on its own axis.
+    */
+    /*
+      Heartbeat: evidence that work continues, distinct from visible progress.
+
+      Progress is throttled to a few updates a second because that is all anyone
+      can read. A heartbeat is not — a muxed sample batch or a block of copied
+      bytes counts even when the percentage does not visibly move. Keeping them
+      separate is what stops a long mux from looking stalled and a 0.1x shard
+      from being mistaken for one.
+
+      The maximum gap per source is recorded because the watchdog's threshold has
+      to be derived from the longest *legitimate* silence, not from how long the
+      platform takes to notice a wedge.
+    */
+    private val beats = java.util.concurrent.ConcurrentHashMap<String, LongArray>()
+    @Volatile private var lastBeatNs = 0L
+
+
+    fun heartbeat(source: String) {
+        val now = System.nanoTime()
+        val previous = lastBeatNs
+        lastBeatNs = now
+        val gap = if (previous == 0L) 0L else (now - previous) / 1_000_000
+        // [count, maxGapMs, lastNs]
+        val entry = beats.getOrPut(source) { longArrayOf(0, 0, 0) }
+        synchronized(entry) {
+            entry[0] += 1
+            if (gap > entry[1]) entry[1] = gap
+            entry[2] = now
+        }
+    }
+
+    fun resetHeartbeats() {
+        beats.clear()
+        lastBeatNs = 0
+    }
+
+    /** Gate-only: the epoch a producer would capture right now. */
+    fun currentBeatEpoch(): Long = ExportHeartbeat.currentEpoch()
+
+    /**
+     * Gate-only: offer a beat on behalf of `atEpoch` and report whether it counted.
+     *
+     * The only way to prove from outside that a late beat from a released run is
+     * discarded rather than credited to whatever job happens to be current.
+     */
+    fun testBeat(source: String, atEpoch: Long): Boolean {
+        if (!diagnostics) return false
+        val before = beats[source]?.get(0) ?: 0
+        ExportHeartbeat.beat(source, atEpoch)
+        val after = beats[source]?.get(0) ?: 0
+        return after > before
+    }
+
+    /** Every beat from every source, summed. Liveness, not work. */
+    fun beatTotal(): Long {
+        var total = 0L
+        for (entry in beats.values) total += entry[0]
+        return total
+    }
+
+    /** Counted work, plus the beat total the watchdog keys on. */
+    fun progressSnapshotJson(): String = ExportProgress.snapshotJson(beatTotal())
+
+    fun heartbeatJson(): String {
+        val sources = JSONObject()
+        var maxGap = 0L
+        for ((name, entry) in beats) {
+            synchronized(entry) {
+                sources.put(
+                    name,
+                    JSONObject().put("count", entry[0]).put("maxGapMs", entry[1]),
+                )
+                if (entry[1] > maxGap) maxGap = entry[1]
+            }
+        }
+        val idleMs = if (lastBeatNs == 0L) -1L else (System.nanoTime() - lastBeatNs) / 1_000_000
+        return JSONObject()
+            .put("sources", sources)
+            .put("maxGapMs", maxGap)
+            .put("idleMs", idleMs)
+            .toString()
+    }
+
+    private val refusals = AtomicLong(0)
+    private val runsStarted = AtomicLong(0)
+    private val runsSucceeded = AtomicLong(0)
+    private val runsCancelled = AtomicLong(0)
+    private val runsFailed = AtomicLong(0)
+    private val runsReleased = AtomicLong(0)
+    private val tempFilesCreated = AtomicLong(0)
+    private val tempFilesReleased = AtomicLong(0)
+
+    /**
+     * Delete a tracked temporary, and say so.
+     *
+     * The single accounted act. Deleting a file and removing it from `created`
+     * without incrementing the counter is what made the ledger disagree with the
+     * disk, so the three steps do not exist separately.
+     */
+    private fun releaseTemp(file: File) {
+        runCatching { file.delete() }
+        synchronized(created) { if (created.remove(file)) tempFilesReleased.incrementAndGet() }
+    }
+    /** Every run's parent job, so a run is always attributable to an export. */
+    private val runJobs = java.util.Collections.synchronizedList(mutableListOf<String>())
+
+    /** Start a run, recorded against the job that owns it. */
+    private fun beginRun() {
+        runsStarted.incrementAndGet()
+        runJobs.add(currentJob ?: "")
+    }
+
+    /**
+     * End a run with exactly one terminal outcome, then release it.
+     *
+     * `wasCancelled` is checked before `ok` because a cancelled run is not a
+     * failure: reporting it as one would make every cancellation look like a
+     * defect in the export.
+     */
+    private fun finishRun(ok: Boolean, wasCancelled: Boolean) {
+        when {
+            wasCancelled -> runsCancelled.incrementAndGet()
+            ok -> runsSucceeded.incrementAndGet()
+            else -> runsFailed.incrementAndGet()
+        }
+        runsReleased.incrementAndGet()
+    }
+
+    fun accountingJson(): String {
+        val started = runsStarted.get()
+        val succeeded = runsSucceeded.get()
+        val cancelled = runsCancelled.get()
+        val failed = runsFailed.get()
+        val released = runsReleased.get()
+        val runs = JSONObject()
+            .put("started", started)
+            .put("succeeded", succeeded)
+            .put("cancelled", cancelled)
+            .put("failed", failed)
+            .put("active", started - succeeded - cancelled - failed)
+            .put("released", released)
+            .put("currentlyAllocated", started - released)
+            .put("attributed", runJobs.size)
+            .put("unattributed", runJobs.count { it.isEmpty() })
+        /*
+          `live` is counted, not derived.
+
+          It used to be `created - released`, which makes the invariant true by
+          construction and therefore worthless: every delete site that forgot to
+          increment the counter inflated `live` by one, and the ledger reported
+          36 files still allocated while the cache directory held none. Reading
+          the set the files are actually tracked in means a missed increment
+          shows up as `created != released + live` instead of hiding inside it.
+        */
+        val live = synchronized(created) { created.size.toLong() }
+        val temp = JSONObject()
+            .put("created", tempFilesCreated.get())
+            .put("released", tempFilesReleased.get())
+            .put("live", live)
+            .put("reconciles", tempFilesCreated.get() == tempFilesReleased.get() + live)
+        return JSONObject()
+            .put("runs", runs)
+            .put("resources", JSONObject().put("tempFiles", temp))
+            .put("refusals", refusals.get())
+            .toString()
+    }
+
+
+    fun refusalCount(): Long = refusals.get()
+    fun startedCount(): Long = runsStarted.get()
+    fun releaseCount(): Long = runsReleased.get()
+    fun completedCount(): Long = runsSucceeded.get()
+    fun failureCount(): Long = runsFailed.get()
+    fun cancellationCount(): Long = runsCancelled.get()
+
+    /**
+     * Encode `uri` once.
+     *
+     * `withSkia` selects the effect chain: empty for the vanilla baseline, and
+     * the pass-through Skia effect for the gate itself. Blocking, with a
+     * timeout, because a gate that hangs is a gate that reports nothing.
+     */
+    /**
+     * Run a **validated scene** through the same Transformer path.
+     *
+     * Everything is checked before Transformer starts, so a rejected scene costs
+     * no encoder, no GL thread and no partial file.
+     */
+    fun runScene(
+        uri: String,
+        sceneJson: String,
+        timeoutSeconds: Long = 120,
+        failAfterFrames: Int = -1,
+    ): Outcome {
+        val (program, invalid) = SceneProgram.parse(sceneJson)
+        if (program == null) {
+            // A refusal, not a started export: nothing was allocated, so it must
+            // not appear in the started/released balance at all.
+            refusals.incrementAndGet()
+            return failed("scene rejected: ${invalid?.reason ?: "unknown"}", 0, Thread.currentThread().name)
+        }
+        return run(uri, true, timeoutSeconds, program, failAfterFrames)
+    }
+
+    /**
+     * Run a **compiled program** over a sequence of sources.
+     *
+     * The two-source case is the one that matters: window identity changes at
+     * the seam, and the program's segments must agree with what Media3 plays
+     * without native knowing where the seam is.
+     */
+    fun runProgram(uris: List<String>, programJson: String, timeoutSeconds: Long = 180): Outcome {
+        val (compiled, invalid) = SceneProgramNative.parse(programJson)
+        if (compiled == null) {
+            refusals.incrementAndGet()
+            return failed("program rejected: " + (invalid?.reason ?: "unknown"), 0, Thread.currentThread().name)
+        }
+        return runSequence(uris, timeoutSeconds, compiled)
+    }
+
+    private fun failed(error: String, elapsedMs: Long, callerThread: String) = Outcome(
+        ok = false,
+        uri = "",
+        error = error,
+        elapsedMs = elapsedMs,
+        fileBytes = 0,
+        durationMs = 0,
+        width = 0,
+        height = 0,
+        videoFrameCount = 0,
+        hasAudio = false,
+        videoMimeType = "",
+        audioMimeType = "",
+        colorInfo = "",
+        glErrors = "",
+        effectFrames = 0,
+        effectTimestampsUs = "",
+        boundary = "",
+        lifecycle = "",
+        programTrace = "",
+        overlayUploads = 0,
+        overlayDraws = 0,
+        overlayTexturesFreed = 0,
+        nativeHeapBytes = android.os.Debug.getNativeHeapAllocatedSize(),
+        javaHeapBytes = Runtime.getRuntime().let { it.totalMemory() - it.freeMemory() },
+        callerThread = callerThread,
+    )
+
+    fun run(
+        uri: String,
+        withSkia: Boolean,
+        timeoutSeconds: Long = 120,
+        program: SceneProgram? = null,
+        failAfterFrames: Int = -1,
+    ): Outcome = runSequence(listOf(uri), timeoutSeconds, null, withSkia, program, failAfterFrames)
+
+    /**
+     * One source in a sequence, with the clipping and speed **TypeScript chose**.
+     *
+     * Native performs none of this arithmetic: it receives a start, an end and a
+     * rate, and hands them to Media3. Deciding which part of a source plays, and
+     * how fast, is timeline interpretation and lives in the compiler.
+     */
+    class Item(
+        val uri: String,
+        val startMs: Long,
+        val endMs: Long,
+        val speed: Float,
+        /** Drop this item's own audio; the sequence supplies silence. */
+        val removeAudio: Boolean = false,
+        /**
+         * How a rate change treats audio.
+         *
+         * `"resample"` is `setSpeed`, which re-times the samples — the tape
+         * effect, where half speed is an octave down. `"preserve"` uses the
+         * coordinated Sonic processor and timestamp adjustment, which stretches
+         * time and leaves pitch where it was.
+         */
+        val speedMode: String = "preserve",
+        /** Source-time length to declare, or 0 to declare nothing. */
+        val durationUs: Long = 0,
+        /** Microsecond clip end, for spans a millisecond cannot express. */
+        val endUs: Long = 0,
+    )
+
+    /**
+     * One clip, exported alone, then concatenated at 1×.
+     *
+     * Per-item speed inside a sequence is broken: only the first item's rate is
+     * honoured, and a later item at any other rate has its video truncated or
+     * dropped while its duration and audio still look right. Sharding puts every
+     * re-timed clip in the position where `setSpeed` is proven exact — first and
+     * only — and leaves the concatenation nothing to re-time.
+     *
+     * The clip's scene-program segments run in the **same** encoding pass, so a
+     * frame is encoded once. Encoding for speed and again for visuals would put
+     * two generations of loss into every exported clip.
+     */
+    class Shard(
+        val uri: String,
+        val startMs: Long,
+        val endMs: Long,
+        val speed: Float,
+        /** Compiled in TypeScript. Native adds it to a local timestamp; nothing more. */
+        val timelineOffsetUs: Long,
+        val forceAudioTrack: Boolean,
+        /** Thin to this rate before the scene interpreter, or 0. */
+        val frameDropFps: Int = 0,
+        /** Encoder repeat interval, or 0. */
+        val encoderRepeatUs: Long = 0,
+        /** Copies each input frame owes, compiled by `resampleClip`. */
+        val emitsPerInput: IntArray? = null,
+        /** Output timestamps, flattened in emission order. */
+        val outputPtsUs: LongArray? = null,
+        val cadenceFailAfterEmits: Int = -1,
+        /**
+         * The shard's compiled span, used to clip it during concatenation.
+         *
+         * An intermediate's container runs longer than its video: the audio tail
+         * is quantised to AAC packets and the muxer's duration follows it. The
+         * concatenation lays items out by container duration, so without this the
+         * next shard starts late and the seam lands off the grid — 76 034 µs
+         * where 33 333 was compiled. Clipping to the span TypeScript planned
+         * removes the tail rather than compensating for it.
+         */
+        val spanUs: Long = 0,
+        /**
+         * Drop this clip's own audio.
+         *
+         * Not "produce no audio track": the sequence still forces one, so a muted
+         * clip contributes digital silence in a track structurally identical to
+         * its neighbours'. A shard with no audio track at all cannot be
+         * concatenated with one that has it by copying samples.
+         */
+        val removeAudio: Boolean = false,
+        /** `"preserve"` (Sonic time-stretch) or `"resample"` (tape effect). */
+        val speedMode: String = "preserve",
+        /** Fail during overlay drawing, after N draws. */
+        val overlayFailAfterDraws: Int = -1,
+        /**
+         * Destroy an intermediate before the concatenation reads it.
+         *
+         * The one failure mode with no other way in: shards have all succeeded,
+         * the encoders are gone, and the remaining work is a transmux. Proving
+         * that path cleans up needs it to actually fail, not to be skipped.
+         */
+        val failConcat: Boolean = false,
+        /**
+         * Gate-only: stop emitting, and stop beating, after N frames.
+         *
+         * A wedge, not a failure. Every other fault control here raises
+         * something; this one produces the condition the watchdog exists for and
+         * that nothing else can imitate — a pipeline that is neither making
+         * progress nor reporting an error. Media3's own stall detection finds it
+         * eventually, at 10.5 s, which is precisely why a shorter watchdog is
+         * worth having.
+         */
+        val cadenceStallAfterEmits: Int = -1,
+    )
+
+    /**
+     * A constant rate for the whole item.
+     *
+     * `C.TIME_UNSET` for the next change means "never", which is what makes this
+     * constant. Media3 asks; it is not told, and no duration is computed here.
+     */
+    private class ConstantSpeed(private val speed: Float) : SpeedProvider {
+        override fun getSpeed(timeUs: Long): Float = speed
+        override fun getNextSpeedChangeTimeUs(timeUs: Long): Long = C.TIME_UNSET
+    }
+
+    fun runItems(
+        items: List<Item>,
+        programJson: String,
+        timeoutSeconds: Long = 180,
+        forceAudioTrack: Boolean = false,
+    ): Outcome {
+        val (compiled, invalid) = SceneProgramNative.parse(programJson)
+        if (compiled == null) {
+            refusals.incrementAndGet()
+            return failed("program rejected: " + (invalid?.reason ?: "unknown"), 0, Thread.currentThread().name)
+        }
+        return runSequence(
+            items.map { it.uri }, timeoutSeconds, compiled,
+            items = items, forceAudioTrack = forceAudioTrack,
+        )
+    }
+
+    /**
+     * The first shard whose encoded format cannot be concatenated with shard 0.
+     *
+     * Compares the fields a sample copy silently reinterprets. `null` when every
+     * part agrees and the copy is safe.
+     */
+    private fun firstFormatMismatch(files: List<java.io.File>, shards: List<Shard>): String? {
+        if (files.size < 2) return null
+        val head = videoFormatOf(files[0]) ?: return "clip 1 produced no video track"
+        for (i in 1 until files.size) {
+            val f = videoFormatOf(files[i]) ?: return "clip " + (i + 1) + " produced no video track"
+            val name = "clip " + (i + 1)
+            fun i32(fmt: android.media.MediaFormat, key: String) =
+                if (fmt.containsKey(key)) fmt.getInteger(key) else -1
+            val keys = listOf(
+                android.media.MediaFormat.KEY_WIDTH to "width",
+                android.media.MediaFormat.KEY_HEIGHT to "height",
+                android.media.MediaFormat.KEY_ROTATION to "rotation",
+                android.media.MediaFormat.KEY_PROFILE to "profile",
+                android.media.MediaFormat.KEY_LEVEL to "level",
+                android.media.MediaFormat.KEY_COLOR_RANGE to "colour range",
+                android.media.MediaFormat.KEY_COLOR_STANDARD to "colour standard",
+                android.media.MediaFormat.KEY_COLOR_TRANSFER to "colour transfer",
+            )
+            for ((key, label) in keys) {
+                val a = i32(head, key)
+                val b = i32(f, key)
+                if (a != b) {
+                    return name + " encoded a different " + label + " (" + b + ") than clip 1 (" + a + ")"
+                }
+            }
+            val am = head.getString(android.media.MediaFormat.KEY_MIME)
+            val bm = f.getString(android.media.MediaFormat.KEY_MIME)
+            if (am != bm) return name + " encoded " + bm + " where clip 1 encoded " + am
+            for (key in listOf("csd-0", "csd-1")) {
+                if (!sameCsd(head, f, key)) {
+                    return name + " has codec-specific data (" + key +
+                        ") a decoder configured for clip 1 cannot use"
+                }
+            }
+            if (i < shards.size) Unit
+        }
+        return null
+    }
+
+    /** Byte-identical codec-specific data, or neither side has it. */
+    private fun sameCsd(a: android.media.MediaFormat, b: android.media.MediaFormat, key: String): Boolean {
+        val ba = runCatching { a.getByteBuffer(key) }.getOrNull()
+        val bb = runCatching { b.getByteBuffer(key) }.getOrNull()
+        if (ba == null && bb == null) return true
+        if (ba == null || bb == null) return false
+        val xa = ByteArray(ba.remaining()); ba.duplicate().get(xa)
+        val xb = ByteArray(bb.remaining()); bb.duplicate().get(xb)
+        return xa.contentEquals(xb)
+    }
+
+    /** The video track's format, or `null`. */
+    private fun videoFormatOf(file: java.io.File): android.media.MediaFormat? {
+        val extractor = android.media.MediaExtractor()
+        return try {
+            extractor.setDataSource(file.absolutePath)
+            var found: android.media.MediaFormat? = null
+            for (t in 0 until extractor.trackCount) {
+                val f = extractor.getTrackFormat(t)
+                val mime = f.getString(android.media.MediaFormat.KEY_MIME) ?: continue
+                if (mime.startsWith("video/")) { found = f; break }
+            }
+            found
+        } catch (e: Exception) {
+            null
+        } finally {
+            runCatching { extractor.release() }
+        }
+    }
+
+    /**
+     * One video track's format, as the muxer would see it.
+     *
+     * Diagnostics: the fields a sample copy silently reinterprets — size,
+     * rotation, MIME, profile, level, colour and the codec-specific data every
+     * decoder configures itself from.
+     */
+    private fun describeVideoFormat(file: java.io.File): String {
+        val extractor = android.media.MediaExtractor()
+        return try {
+            extractor.setDataSource(file.absolutePath)
+            var out = "no video track"
+            for (t in 0 until extractor.trackCount) {
+                val f = extractor.getTrackFormat(t)
+                val mime = f.getString(android.media.MediaFormat.KEY_MIME) ?: continue
+                if (!mime.startsWith("video/")) continue
+                fun i(key: String) = if (f.containsKey(key)) f.getInteger(key).toString() else "-"
+                fun csd(key: String): String {
+                    val b = runCatching { f.getByteBuffer(key) }.getOrNull() ?: return "-"
+                    val a = ByteArray(b.remaining())
+                    b.duplicate().get(a)
+                    var h = 0
+                    for (v in a) h = h * 31 + v
+                    return a.size.toString() + ":" + Integer.toHexString(h)
+                }
+                out = "mime=" + mime +
+                    " " + i(android.media.MediaFormat.KEY_WIDTH) + "x" +
+                    i(android.media.MediaFormat.KEY_HEIGHT) +
+                    " rot=" + i(android.media.MediaFormat.KEY_ROTATION) +
+                    " fps=" + i(android.media.MediaFormat.KEY_FRAME_RATE) +
+                    " profile=" + i(android.media.MediaFormat.KEY_PROFILE) +
+                    " level=" + i(android.media.MediaFormat.KEY_LEVEL) +
+                    " range=" + i(android.media.MediaFormat.KEY_COLOR_RANGE) +
+                    " standard=" + i(android.media.MediaFormat.KEY_COLOR_STANDARD) +
+                    " transfer=" + i(android.media.MediaFormat.KEY_COLOR_TRANSFER) +
+                    " csd0=" + csd("csd-0") + " csd1=" + csd("csd-1")
+                break
+            }
+            out
+        } catch (e: Exception) {
+            "unreadable: " + e.message
+        } finally {
+            runCatching { extractor.release() }
+        }
+    }
+
+    /**
+     * Export each clip alone, then concatenate the intermediates by transmux.
+     *
+     * Intermediates are deleted on every path — success, failure, refusal — in a
+     * `finally`. They are full-size encoded video in a cache directory the user
+     * never asked to fill, and a gate that leaves them behind on the one run
+     * that crashed is the gate that fills a phone.
+     */
+    fun runShards(
+        shards: List<Shard>,
+        programJson: String,
+        timeoutSeconds: Long = 240,
+        overlaysJson: String = "[]",
+    ): Outcome {
+        val (compiled, invalid) = SceneProgramNative.parse(programJson)
+        if (compiled == null) {
+            refusals.incrementAndGet()
+            return failed("program rejected: " + (invalid?.reason ?: "unknown"), 0, Thread.currentThread().name)
+        }
+        /*
+          Overlays are loaded and checked before anything is encoded.
+
+          A resource discovered missing mid-run leaves a partial file and an
+          encoder to unwind, and the frames already written are silently missing
+          something the timeline said was on screen.
+        */
+        val (resources, badResource) = OverlayResources.parse(context, overlaysJson)
+        if (resources == null) {
+            refusals.incrementAndGet()
+            return failed(
+                "overlay resources rejected: " + (badResource?.reason ?: "unknown"),
+                0, Thread.currentThread().name,
+            )
+        }
+        for (id in compiled.requiredResourceIds()) {
+            if (!resources.entries.containsKey(id)) {
+                refusals.incrementAndGet()
+                return failed(
+                    "overlay resource '" + id + "' is referenced by the program but not supplied",
+                    0, Thread.currentThread().name,
+                )
+            }
+        }
+        if (shards.isEmpty()) {
+            refusals.incrementAndGet()
+            return failed("no shards", 0, Thread.currentThread().name)
+        }
+
+        val intermediates = mutableListOf<File>()
+        val perShard = org.json.JSONArray()
+        try {
+            for ((shardIndex, shard) in shards.withIndex()) {
+                if (cancelled) {
+                    return failed("cancelled during betweenShards", 0, Thread.currentThread().name)
+                }
+                // Shards run one at a time, so the shader program does not have
+                // to know which one it is drawing for — Media3 constructs it and
+                // tells it nothing about the timeline.
+                ExportProgress.enterShard(shardIndex, ExportHeartbeat.currentEpoch())
+                val cadenceEffect = shard.emitsPerInput?.let { per ->
+                    shard.outputPtsUs?.let { pts ->
+                        CadenceEffect(
+                            per,
+                            pts,
+                            // Inert without diagnostics, whatever the payload
+                            // says. A production build must not be one malformed
+                            // JSON field away from a failed user export.
+                            failAfterEmits = if (diagnostics) shard.cadenceFailAfterEmits else -1,
+                            stallAfterEmits = when {
+                                !diagnostics -> -1
+                                stallAfterFrames >= 0 -> stallAfterFrames
+                                else -> shard.cadenceStallAfterEmits
+                            },
+                        )
+                    }
+                }
+                val outcome = runSequence(
+                    listOf(shard.uri),
+                    timeoutSeconds,
+                    compiled,
+                    items = listOf(
+                        Item(
+                            shard.uri, shard.startMs, shard.endMs, shard.speed,
+                            shard.removeAudio, shard.speedMode,
+                        ),
+                    ),
+                    forceAudioTrack = shard.forceAudioTrack,
+                    timelineOffsetUs = shard.timelineOffsetUs,
+                    frameDropFps = shard.frameDropFps,
+                    encoderRepeatUs = shard.encoderRepeatUs,
+                    cadence = cadenceEffect,
+                    overlays = resources,
+                    overlayFailAfterDraws = if (diagnostics) shard.overlayFailAfterDraws else -1,
+                    // Shards must be concatenable by copying, and a mono track
+                    // beside a stereo one is not.
+                    normaliseAudioChannels = 2,
+                )
+                val cadenceTrace = cadenceEffect?.trace() ?: ""
+                perShard.put(
+                    org.json.JSONObject()
+                        .put("ok", outcome.ok)
+                        .put("error", outcome.error)
+                        .put("videoFrameCount", outcome.videoFrameCount)
+                        .put("durationMs", outcome.durationMs)
+                        .put("hasAudio", outcome.hasAudio)
+                        .put("videoMimeType", outcome.videoMimeType)
+                        .put("width", outcome.width)
+                        .put("height", outcome.height)
+                        .put("colorInfo", outcome.colorInfo)
+                        .put("programTrace", outcome.programTrace)
+                        // Scene executions, to compare against output frames.
+                        .put("effectFrames", outcome.effectFrames)
+                        .put("cadenceTrace", cadenceTrace)
+                        .put("overlayUploads", outcome.overlayUploads)
+                        .put("overlayDraws", outcome.overlayDraws)
+                        .put("overlayTexturesFreed", outcome.overlayTexturesFreed)
+                        .put("timelineOffsetUs", shard.timelineOffsetUs)
+                        // Gate-only, like the ones at the mux: reading every
+                        // sample of every intermediate is conformance work, and
+                        // a production export must not pay to verify itself.
+                        .put(
+                            "sampleHashes",
+                            if (diagnostics && provenance) {
+                                GateFrames.sampleHashes(context, outcome.uri)
+                            } else {
+                                "{}"
+                            },
+                        ),
+                )
+                if (!outcome.ok) {
+                    return outcome.copy(
+                        error = "shard failed: " + outcome.error,
+                        programTrace = perShard.toString(),
+                    )
+                }
+                intermediates.add(File(outcome.uri))
+            }
+
+            if (diagnostics && shards.any { it.failConcat } && intermediates.isNotEmpty()) {
+                // A real failure, not a synthetic one: the concatenation is left
+                // to discover a source it cannot read, so the same cleanup runs.
+                runCatching { intermediates[0].delete() }
+            }
+            /*
+              What each shard actually encoded, before anything copies it.
+
+              Sample-copy concatenation writes every part's samples under the
+              *first* part's track format, so a shard that encoded a different
+              size, profile or codec-specific data produces a file whose
+              declared format is a lie about most of its payload. That is a
+              container correctness problem, not a cosmetic one, and it is
+              invisible from the finished file — which reports one format for
+              everything inside it.
+            */
+            for ((i, file) in intermediates.withIndex()) {
+                android.util.Log.i("PictorShardFmt", "shard=" + i + " " + describeVideoFormat(file))
+            }
+            /*
+              Refuse rather than copy samples under another shard's format.
+
+              Concatenation moves encoded bytes and writes them under the first
+              part's track metadata. If a later part encoded a different size,
+              profile, level or codec-specific data, the result declares one
+              format and contains several — and no decoder can be right about
+              all of them. The failure is silent in the file and shows up as
+              corrupt or missing picture, which is how it was found.
+
+              Named by clip, because "the export failed" is not something anyone
+              can act on and "clip 3 encoded 960x540 where the first encoded
+              1920x1080" is.
+            */
+            val mismatch = firstFormatMismatch(intermediates, shards)
+            if (mismatch != null) {
+                return failed(mismatch, 0, Thread.currentThread().name)
+            }
+            // Concatenate. No effects, no speed, and transmux: the parts are
+            // already normalised, so the final pass must move bytes rather than
+            // decode and re-encode them.
+            val concat = runSequence(
+                intermediates.map { it.absolutePath },
+                timeoutSeconds,
+                compiled = null,
+                withSkia = false,
+                transmuxVideo = true,
+                items = shards.mapIndexed { i, shard ->
+                    Item(
+                        intermediates[i].absolutePath,
+                        0,
+                        0,
+                        1f,
+                        durationUs = 0,
+                        endUs = shard.spanUs,
+                    )
+                },
+            )
+            return concat.copy(programTrace = perShard.toString())
+        } finally {
+            synchronized(created) {
+                for (file in intermediates) releaseTemp(file)
+            }
+        }
+    }
+
+    /**
+     * Encode a still image, through the same encoder the treatment uses.
+     *
+     * The reference is drawn by RNSkia and the treatment by GL, but a comparison
+     * between them is only about the renderers if everything after them is the
+     * same. So the reference is encoded and decoded too: both sides carry
+     * identical codec loss, and what is left is the difference in drawing.
+     */
+    fun runStill(pngBytes: ByteArray, frames: Int, timeoutSeconds: Long = 120): Outcome {
+        val png = File.createTempFile(TEMP_PREFIX + "still-", ".png", context.cacheDir)
+        synchronized(created) { tempFilesCreated.incrementAndGet(); created.add(png) }
+        png.outputStream().use { it.write(pngBytes) }
+        val durationUs = (frames.toLong() * 1_000_000L) / 30L
+        return runSequence(
+            listOf(png.absolutePath),
+            timeoutSeconds,
+            compiled = null,
+            withSkia = false,
+            stillDurationUs = durationUs,
+        )
+    }
+
+    /**
+     * Video shards, audio timeline, then a muxer-level copy of both.
+     *
+     * The two pipelines never meet until the last step, and that step decodes
+     * nothing. Video keeps the one-generation encode and sample-copy
+     * concatenation it already proved; audio is encoded exactly once from the
+     * original sources; `MediaMuxer` writes both sets of encoded samples
+     * unchanged.
+     */
+    /**
+     * The priming the finished audio track carries, for its own configuration.
+     *
+     * Read from the track that will actually be muxed rather than from the
+     * settings we asked for, because the encoder is free to have chosen
+     * otherwise, and a delay measured for the wrong configuration is a
+     * confident number about a different file.
+     */
+    private fun primingFramesFor(context: Context, audioUri: String): Int {
+        val extractor = MediaExtractor()
+        try {
+            if (audioUri.startsWith("/")) extractor.setDataSource(audioUri)
+            else extractor.setDataSource(context, android.net.Uri.parse(audioUri), null)
+            for (i in 0 until extractor.trackCount) {
+                val f = extractor.getTrackFormat(i)
+                if (!(f.getString(MediaFormat.KEY_MIME) ?: "").startsWith("audio/")) continue
+                val rate = f.getInteger(MediaFormat.KEY_SAMPLE_RATE)
+                val channels = f.getInteger(MediaFormat.KEY_CHANNEL_COUNT)
+                val bitrate =
+                    if (f.containsKey(MediaFormat.KEY_BIT_RATE)) f.getInteger(MediaFormat.KEY_BIT_RATE)
+                    else 128_000
+                return AacPriming.measure(rate, channels, bitrate).delayFrames
+            }
+        } finally {
+            runCatching { extractor.release() }
+        }
+        return 0
+    }
+
+    fun runProject(
+        shards: List<Shard>,
+        programJson: String,
+        overlaysJson: String,
+        mixProgramJson: String,
+        mixUrisJson: String,
+        timeoutSeconds: Long = 600,
+        destinationJson: String = "",
+    ): Outcome {
+        /*
+          Refused before anything is encoded, where that is knowable.
+
+          Not the guarantee — a directory can be unmounted and a target created
+          while the export runs, and the publication below is what actually has
+          to be safe — but the difference between failing now and failing after
+          eight seconds of work the caller cannot use.
+        */
+        val target = if (destinationJson.isEmpty()) null else GateDestination.parse(destinationJson)
+        if (target != null) {
+            GateDestination.validate(target)?.let {
+                refusals.incrementAndGet()
+                return failed(it, 0, Thread.currentThread().name)
+            }
+        }
+        var videoUri: String? = null
+        var audioUri: String? = null
+        /*
+          Checked between stages, not only inside one.
+
+          Each stage is a Transformer run or a decode loop of its own, and a
+          cancel arriving in the gap between two of them would otherwise wait
+          for the whole of the next one before anything noticed.
+        */
+        fun stopped(stage: String): Outcome? {
+            // No run counter here: this is the *job* stopping between runs, and
+            // there is no Transformer run to give a terminal outcome to.
+            return if (cancelled) {
+                failed("cancelled during $stage", 0, Thread.currentThread().name)
+            } else {
+                null
+            }
+        }
+        try {
+            stopped("resolving")?.let { return it }
+            val video = runShards(shards, programJson, timeoutSeconds, overlaysJson)
+            if (!video.ok) return video
+            stopped("shards")?.let { return it }
+            videoUri = video.uri
+            /*
+              One mix, one encode.
+
+              The timeline's audio is decoded, normalised, placed, summed and
+              saturated in `AudioMixer`, then encoded to AAC exactly once — so
+              the mux has nothing left to re-encode. Driven only by the compiled
+              plan: no audio kinds, no duration policy, no project.
+            */
+            stopped("audio")?.let { return it }
+            val mixFile = File.createTempFile(TEMP_PREFIX + "mix-", ".m4a", context.cacheDir)
+            synchronized(created) { tempFilesCreated.incrementAndGet(); created.add(mixFile) }
+            val mixResult = JSONObject(
+                run {
+                    // The mix is the longest uninterruptible stretch in an
+                    // export; without this a cancel waits out the stretch and
+                    // the AAC encode before any checkpoint can see it.
+                    //
+                    // Passed rather than assigned to the singleton: preview
+                    // mixes the same way now, and two callers sharing one
+                    // mutable predicate is a race where the loser becomes
+                    // uncancellable.
+                    try {
+                        AudioMixer.mix(
+                            context, mixProgramJson, mixUrisJson, mixFile,
+                            keepGoing = { !cancelled },
+                        )
+                    } catch (e: AudioMixer.Cancelled) {
+                        JSONObject().put("ok", false).put("cancelled", true).toString()
+                    }
+                },
+            )
+            if (!mixResult.optBoolean("ok", false)) {
+                releaseTemp(mixFile)
+                // Stopped because it was asked to, not because the mix failed.
+                if (mixResult.optBoolean("cancelled", false)) {
+                    return failed("cancelled during audio", 0, Thread.currentThread().name)
+                }
+                return failed("audio mix: " + mixResult.optString("error"), 0, Thread.currentThread().name)
+            }
+            val sound = Outcome(
+                ok = true, uri = mixFile.absolutePath, error = "", elapsedMs = 0,
+                fileBytes = mixFile.length(), durationMs = 0, width = 0, height = 0,
+                videoFrameCount = 0, hasAudio = true, videoMimeType = "", audioMimeType = "audio/mp4a-latm",
+                colorInfo = "", glErrors = "", effectFrames = 0, effectTimestampsUs = "",
+                boundary = "", lifecycle = "", programTrace = "", muxTrace = "",
+                overlayUploads = 0, overlayDraws = 0, overlayTexturesFreed = 0,
+                nativeHeapBytes = 0, javaHeapBytes = 0, callerThread = Thread.currentThread().name,
+            )
+            audioUri = sound.uri
+
+            val output = File.createTempFile(TEMP_PREFIX + "final-", ".mp4", context.cacheDir)
+            synchronized(created) { tempFilesCreated.incrementAndGet(); created.add(output) }
+            // The compiled end, so the AAC tail cannot make the file longer
+            // than the timeline it was built from.
+            val compiledEndUs = shards.sumOf { it.spanUs }
+            /*
+              Provenance hashing is conformance work, not export work.
+
+              It reads every sample of both intermediates and of the result to
+              prove the mux copied rather than re-encoded — worth doing in a
+              gate, and pure cost in a production export. It is off by default:
+              a watchdog threshold measured with it present would be calibrated
+              against work the user never pays for, and would then be wrong for
+              the export they actually run.
+            */
+            stopped("concatenating")?.let { return it }
+            val videoBefore =
+                if (diagnostics && provenance) JSONObject(GateFrames.sampleHashes(context, video.uri))
+                else JSONObject()
+            val audioBefore =
+                if (diagnostics && provenance) JSONObject(GateFrames.sampleHashes(context, sound.uri))
+                else JSONObject()
+            val muxed = JSONObject(
+                GateMux.mux(
+                    context, video.uri, sound.uri, output, compiledEndUs,
+                    primingFramesFor(context, sound.uri),
+                    keepGoing = { !cancelled },
+                ),
+            )
+            if (!muxed.optBoolean("ok", false)) {
+                releaseTemp(output)
+                // A cancelled mux is a cancellation, not a mux failure: the copy
+                // stopped because it was asked to.
+                if (muxed.optBoolean("cancelled", false)) {
+                    return failed("cancelled during concatenating", 0, Thread.currentThread().name)
+                }
+                return failed("mux: " + muxed.optString("error"), 0, Thread.currentThread().name)
+            }
+            // Muxed, not published. The bar must not reach 1 here: the file is
+            // written but nothing has yet confirmed it opens.
+            ExportProgress.muxed(ExportHeartbeat.currentEpoch())
+            ExportHeartbeat.beat("publishBytes", ExportHeartbeat.currentEpoch())
+            val after =
+                if (diagnostics && provenance) JSONObject(GateFrames.sampleHashes(context, output.absolutePath))
+                else JSONObject()
+            ExportHeartbeat.beat("publishBytes", ExportHeartbeat.currentEpoch())
+            val trace = JSONObject()
+                .put("videoBefore", videoBefore.optJSONArray("sampleHashes")?.length() ?: -1)
+                .put("videoAfter", after.optJSONArray("sampleHashes")?.length() ?: -1)
+                .put(
+                    "videoIdentical",
+                    videoBefore.optJSONArray("sampleHashes")?.toString() ==
+                        after.optJSONArray("sampleHashes")?.toString(),
+                )
+                .put("audioBefore", audioBefore.optJSONArray("audioHashes")?.length() ?: -1)
+                .put("audioAfter", after.optJSONArray("audioHashes")?.length() ?: -1)
+                .put("audioPrimingUnitsDropped", muxed.optInt("primingUnitsDropped"))
+                .put("audioPrimingResidualFrames", muxed.optInt("primingResidualFrames"))
+                .put(
+                    "audioPrefixIdentical",
+                    prefixMatches(audioBefore, after, muxed.optInt("primingUnitsDropped")),
+                )
+                .put("muxVideoSamples", muxed.optInt("videoSamples"))
+                .put("muxAudioSamples", muxed.optInt("audioSamples"))
+            /*
+              Temporary: the caller keeps it.
+
+              Nothing sweeps it out from under them, because the adapter cannot
+              know when a host has finished previewing. It stays registered, so
+              an explicit release still finds it.
+            */
+            if (target == null) {
+                return video.copy(
+                    uri = output.absolutePath,
+                    fileBytes = output.length(),
+                    hasAudio = true,
+                    programTrace = video.programTrace,
+                    muxTrace = trace.toString(),
+                )
+            }
+
+            stopped("publishing")?.let { releaseTemp(output); return it }
+            /*
+              Staged beside the target, so the last step is a rename.
+
+              Writing the destination in place would make it visible while it is
+              half-written — a player opens a truncated container, a scanner
+              indexes a file that will change under it, and a failure at 90%
+              leaves something that looks like a video and is not one.
+            */
+            // Anything a previous run left in the destination's directory. It
+            // is not in the cache, so the temporary sweep never sees it.
+            val sweptStaging = GateDestination.sweepStaging(target)
+            val staging = GateDestination.stagingFor(target, System.nanoTime())
+            synchronized(created) { tempFilesCreated.incrementAndGet(); created.add(staging) }
+            val stageError = GateDestination.stage(
+                output, staging,
+                keepGoing = { !cancelled },
+                beatEpoch = ExportHeartbeat.currentEpoch(),
+                hold = diagnostics && publishFault == "holdCopy",
+            )
+            val injected = if (diagnostics) publishFault else ""
+            if (stageError == null && injected == "stage") {
+                releaseTemp(staging)
+                releaseTemp(output)
+                return failed(
+                    "staging '" + GateDestination.describe(target.path) + "' failed: injected",
+                    0, Thread.currentThread().name,
+                )
+            }
+            if (stageError != null) {
+                releaseTemp(staging)
+                releaseTemp(output)
+                // The existing target has not been touched: nothing has been
+                // renamed, and the staging file is what took the damage.
+                return failed(
+                    if (stageError == "cancelled") "cancelled during publishing" else stageError,
+                    0, Thread.currentThread().name,
+                )
+            }
+            // The staged container, before it becomes the destination. A file
+            // that will not open must never be the thing that replaces one that
+            // would have.
+            val stagedProbe = GateDestination.probe(staging.absolutePath)
+            if (!stagedProbe.optBoolean("readable", false)) {
+                releaseTemp(staging)
+                releaseTemp(output)
+                return failed(
+                    "the staged file could not be read back: " + stagedProbe.optString("error", "no video track"),
+                    0, Thread.currentThread().name,
+                )
+            }
+            if (injected == "afterStage") {
+                // Written, flushed, verified — and not published. The target
+                // must be exactly as it was.
+                releaseTemp(staging)
+                releaseTemp(output)
+                return failed(
+                    "publishing '" + GateDestination.describe(target.path) + "' failed: injected",
+                    0, Thread.currentThread().name,
+                )
+            }
+            if (injected == "raceCreate") {
+                // Between the preflight check and the publication, which is
+                // exactly where a preflight-only guard loses.
+                runCatching { File(target.path).writeText("raced") }
+            }
+            GateDestination.publish(staging, target)?.let {
+                releaseTemp(staging)
+                releaseTemp(output)
+                return failed(it, 0, Thread.currentThread().name)
+            }
+            // Published: the staging entry is gone from the filesystem either
+            // way, so the ledger is told rather than left to guess.
+            synchronized(created) {
+                if (created.remove(staging)) tempFilesReleased.incrementAndGet()
+            }
+            releaseTemp(output)
+            return video.copy(
+                uri = target.path,
+                fileBytes = File(target.path).length(),
+                hasAudio = true,
+                programTrace = video.programTrace,
+                muxTrace = trace.toString(),
+                boundary = if (sweptStaging > 0) "sweptStaging=" + sweptStaging else video.boundary,
+            )
+        } finally {
+            /*
+              The intermediates go on every path.
+
+              They are full-size encoded media, and the run that failed is
+              exactly the one nobody comes back for.
+            */
+            for (path in listOfNotNull(videoUri, audioUri)) {
+                val file = File(path)
+                releaseTemp(file)
+            }
+        }
+    }
+
+    /**
+     * One audio-only pass over the whole timeline.
+     *
+     * The video pipeline is separate and already proven: video shards carry
+     * video only, concatenate by sample copy, and never touch audio. Audio is
+     * built once, here, straight from the original sources — so it is encoded
+     * exactly once and the final step has nothing left to re-encode.
+     *
+     * A muted or audio-less span becomes a **gap of exactly its compiled
+     * duration**. Not a silent media item: a gap cannot drift by an encoder's
+     * priming, and every clip after it keeps the timeline position the compiler
+     * gave it.
+     */
+    fun runAudioTimeline(items: List<AudioSpan>, timeoutSeconds: Long = 240): Outcome {
+        beginRun()
+        val callerThread = Thread.currentThread().name
+        val output = File.createTempFile(TEMP_PREFIX + "audio-", ".mp4", context.cacheDir)
+        synchronized(created) { tempFilesCreated.incrementAndGet(); created.add(output) }
+
+        val startedNs = System.nanoTime()
+        val latch = CountDownLatch(1)
+        var result: ExportResult? = null
+        var failure: ExportException? = null
+        var buildFailure: Throwable? = null
+        // A run stopped before its Transformer started is not a success, and
+        // not a failure either: `finishRun` reads this and the cancel flag.
+        var cancelledEarly = false
+
+        main.post {
+            try {
+            val builder = EditedMediaItemSequence.Builder()
+            builder.experimentalSetForceAudioTrack(true)
+            for (span in items) {
+                if (span.silent) {
+                    builder.addGap(span.durationUs)
+                    continue
+                }
+                val media = MediaItem.Builder()
+                    .setUri(span.uri)
+                    .setClippingConfiguration(
+                        MediaItem.ClippingConfiguration.Builder()
+                            .setStartPositionMs(span.startMs)
+                            .setEndPositionMs(span.endMs)
+                            .build(),
+                    )
+                    .build()
+                val edited = EditedMediaItem.Builder(media).setRemoveVideo(true)
+                val processors = ArrayList<androidx.media3.common.audio.AudioProcessor>()
+                // One channel layout across the whole timeline, so nothing later
+                // has to reconcile a mono span with a stereo one.
+                val mixer = androidx.media3.common.audio.ChannelMixingAudioProcessor()
+                for (inChannels in 1..2) {
+                    mixer.putChannelMixingMatrix(
+                        androidx.media3.common.audio.ChannelMixingMatrix.createForConstantPower(inChannels, 2),
+                    )
+                }
+                processors.add(mixer)
+                if (span.speed != 1f) {
+                    edited.setSpeed(ConstantSpeed(span.speed))
+                    if (span.speedMode != "resample") {
+                        val sonic = androidx.media3.common.audio.SonicAudioProcessor()
+                        sonic.setPitch(1f / span.speed)
+                        processors.add(sonic)
+                    }
+                }
+                edited.setEffects(Effects(ImmutableList.copyOf(processors), ImmutableList.of()))
+                builder.addItem(edited.build())
+            }
+            /*
+              The sequence forces the audio track, not the composition.
+
+              Setting it at composition level on an audio-only composition throws
+              `trackTypes must only contain TRACK_TYPE_AUDIO and/or
+              TRACK_TYPE_VIDEO` from inside `Composition.Builder.build`, which
+              took the process with it before this was wrapped.
+            */
+            val composition = Composition.Builder(builder.build()).build()
+            val transformer = Transformer.Builder(context)
+                .addListener(object : Transformer.Listener {
+                    override fun onCompleted(c: Composition, r: ExportResult) {
+                        activeTransformer = null
+                        activeLatch = null
+                        result = r; latch.countDown()
+                    }
+                    override fun onError(c: Composition, r: ExportResult, e: ExportException) {
+                        activeTransformer = null
+                        activeLatch = null
+                        result = r; failure = e; latch.countDown()
+                    }
+                })
+                .build()
+            /*
+              The race a flag alone does not close.
+
+              A Transformer is built inside a main-thread post, so a cancel can
+              arrive after the job has started and before the object exists --
+              `cancelJob` then finds nothing to cancel, sets the flag, and the
+              Transformer starts anyway and runs to completion. Measured: a
+              cancel issued before any native work still took 4.7 s to settle,
+              which is the whole of the first shard.
+            */
+            if (cancelled) {
+                // Not counted here. `finishRun` is the only place a run reaches
+                // a terminal outcome, so it cannot be counted twice.
+                cancelledEarly = true
+                latch.countDown()
+                return@post
+            }
+            activeTransformer = transformer
+            activeLatch = latch
+            transformer.start(composition, output.absolutePath)
+            } catch (e: Throwable) {
+                /*
+                  A malformed composition must fail the export, not the process.
+
+                  Media3 validates on `build()` and throws on the main thread; an
+                  unwrapped throw here killed the app outright, which loses the
+                  error, the cleanup and every other run in the session.
+                */
+                buildFailure = e
+                latch.countDown()
+            }
+        }
+
+        val finished = latch.await(timeoutSeconds, TimeUnit.SECONDS)
+        val elapsedMs = (System.nanoTime() - startedNs) / 1_000_000
+        val ok = finished && failure == null && buildFailure == null && !cancelledEarly
+        if (!ok) {
+            releaseTemp(output)
+        }
+        ExportHeartbeat.beat("videoFrame", ExportHeartbeat.currentEpoch())
+        finishRun(ok, cancelled)
+        return Outcome(
+            ok = ok,
+            uri = if (ok) output.absolutePath else "",
+            error = when {
+                buildFailure != null -> "audio composition rejected: " +
+                    buildFailure!!.javaClass.simpleName + ": " + buildFailure!!.message
+                !finished -> "audio timeline timed out after ${'$'}timeoutSeconds s"
+                failure != null -> "${'$'}{failure!!.errorCode}: ${'$'}{failure!!.message}"
+                else -> ""
+            },
+            elapsedMs = elapsedMs,
+            fileBytes = if (ok) output.length() else 0,
+            durationMs = result?.durationMs ?: 0,
+            width = 0, height = 0, videoFrameCount = 0,
+            hasAudio = true,
+            videoMimeType = "", audioMimeType = result?.audioEncoderName ?: "",
+            colorInfo = "", glErrors = "", effectFrames = 0, effectTimestampsUs = "",
+            boundary = "", lifecycle = "", programTrace = "",
+            overlayUploads = 0, overlayDraws = 0, overlayTexturesFreed = 0,
+            nativeHeapBytes = android.os.Debug.getNativeHeapAllocatedSize(),
+            javaHeapBytes = Runtime.getRuntime().let { it.totalMemory() - it.freeMemory() },
+            callerThread = callerThread,
+        )
+    }
+
+    /** One span of the audio timeline: a clipped source, or silence. */
+    class AudioSpan(
+        val uri: String,
+        val startMs: Long,
+        val endMs: Long,
+        val speed: Float,
+        val speedMode: String,
+        /** Silence of exactly [durationUs]; `uri` and the trim are ignored. */
+        val silent: Boolean,
+        val durationUs: Long,
+    )
+
+    /**
+     * Whether the final's audio is the timeline's audio, minus a trimmed tail.
+     *
+     * Exact equality is the wrong test: the tail is deliberately dropped so the
+     * container cannot outlast the compiled timeline. What must hold is that
+     * every sample kept is byte-identical and in order — copied, never
+     * re-encoded.
+     */
+    /**
+     * Whether the muxed audio is the encoder's own bytes, allowing for the
+     * priming units the mux removed.
+     *
+     * The comparison starts at `skip` rather than at zero, because removing
+     * priming is exactly a change to the beginning of the stream. Comparing from
+     * zero would report every correctly trimmed file as a payload mismatch --
+     * an alarm that fires on the fix -- while ignoring the offset entirely would
+     * stop checking the one thing this exists to check.
+     */
+    private fun prefixMatches(before: JSONObject, after: JSONObject, skip: Int): Boolean {
+        val a = before.optJSONArray("audioHashes") ?: return false
+        val b = after.optJSONArray("audioHashes") ?: return false
+        if (skip < 0 || b.length() + skip > a.length()) return false
+        for (i in 0 until b.length()) {
+            if (a.optLong(i + skip) != b.optLong(i)) return false
+        }
+        return b.length() > 0
+    }
+
+    private fun runSequence(
+        uris: List<String>,
+        timeoutSeconds: Long,
+        compiled: SceneProgramNative?,
+        withSkia: Boolean = true,
+        program: SceneProgram? = null,
+        failAfterFrames: Int = -1,
+        items: List<Item>? = null,
+        forceAudioTrack: Boolean = false,
+        timelineOffsetUs: Long = 0,
+        transmuxVideo: Boolean = false,
+        /** Thin the stream to this rate **before** the scene interpreter, or 0. */
+        frameDropFps: Int = 0,
+        /** Encoder-level repeat interval, or 0 for the default encoder. */
+        encoderRepeatUs: Long = 0,
+        /** Grid normalisation, upstream of the scene interpreter. */
+        cadence: CadenceEffect? = null,
+        /** Non-zero when the sources are still images rather than video. */
+        stillDurationUs: Long = 0,
+        /** Channel count every shard's audio is mixed to, or 0 to leave it alone. */
+        normaliseAudioChannels: Int = 0,
+        /** Preloaded overlay rasters, or null when the scene names none. */
+        overlays: OverlayResources? = null,
+        overlayFailAfterDraws: Int = -1,
+    ): Outcome {
+        beginRun()
+        val callerThread = Thread.currentThread().name
+        val output = File.createTempFile(TEMP_PREFIX, ".mp4", context.cacheDir)
+        synchronized(created) { tempFilesCreated.incrementAndGet(); created.add(output) }
+
+        val startedNs = System.nanoTime()
+        val latch = CountDownLatch(1)
+        var result: ExportResult? = null
+        var failure: ExportException? = null
+        // A shard stopped before its Transformer started is neither a success
+        // nor a failure; `finishRun` reads this alongside the cancel flag.
+        var cancelledEarly = false
+        val probe =
+            if (withSkia) {
+                SkiaPassThroughEffect(
+                    program, failAfterFrames, compiled, timelineOffsetUs, overlays, overlayFailAfterDraws,
+                )
+            } else {
+                null
+            }
+
+        main.post {
+            val effects: ImmutableList<Effect> =
+                if (probe == null) ImmutableList.of() else ImmutableList.of(probe as Effect)
+            val builder = EditedMediaItemSequence.Builder()
+            /*
+              Media3's speed path is driven through audio. A source with no audio
+              track fails outright at any rate other than 1, with the muxer
+              aborting on "no output sample written" — so a silent clip is not a
+              smaller case of an audible one. Generating silence gives the path
+              the track it is waiting for.
+            */
+            if (forceAudioTrack) builder.experimentalSetForceAudioTrack(true)
+            for ((index, source) in uris.withIndex()) {
+                val item = items?.getOrNull(index)
+                val media = if (stillDurationUs > 0) {
+                    /*
+                      An image needs three things the default path does not
+                      supply: a MIME so the factory routes it to a bitmap loader
+                      rather than the ExoPlayer one, and a duration **on the
+                      MediaItem** — `EditedMediaItem.setDurationUs` is not the
+                      same field, and Media3 says so in the failure it raises.
+                    */
+                    MediaItem.Builder()
+                        .setUri(android.net.Uri.fromFile(File(source)))
+                        .setMimeType(androidx.media3.common.MimeTypes.IMAGE_PNG)
+                        .setImageDurationMs(stillDurationUs / 1000)
+                        .build()
+                } else if (item != null && item.endUs > 0) {
+                    MediaItem.Builder()
+                        .setUri(source)
+                        .setClippingConfiguration(
+                            MediaItem.ClippingConfiguration.Builder()
+                                .setStartPositionUs(0)
+                                .setEndPositionUs(item.endUs)
+                                .build(),
+                        )
+                        .build()
+                } else if (item != null && item.endMs > item.startMs) {
+                    MediaItem.Builder()
+                        .setUri(source)
+                        .setClippingConfiguration(
+                            MediaItem.ClippingConfiguration.Builder()
+                                .setStartPositionMs(item.startMs)
+                                .setEndPositionMs(item.endMs)
+                                .build(),
+                        )
+                        .build()
+                } else {
+                    MediaItem.fromUri(source)
+                }
+                /*
+                  Drop *upstream* of the scene interpreter.
+
+                  Order decides what the interpreter is asked to draw. Dropping
+                  first means it runs once per output frame, which is the
+                  contract. Dropping after would have it draw frames that are
+                  then thrown away — the same picture, at more cost, with scene
+                  executions no longer equal to output frames.
+                */
+                val chain: ImmutableList<Effect> =
+                    if (frameDropFps > 0 || cadence != null) {
+                        val all = ArrayList<Effect>()
+                        if (frameDropFps > 0) {
+                            all.add(FrameDropEffect.createDefaultFrameDropEffect(frameDropFps.toFloat()))
+                        }
+                        if (cadence != null) all.add(cadence)
+                        all.addAll(effects)
+                        ImmutableList.copyOf(all)
+                    } else {
+                        effects
+                    }
+                val edited = EditedMediaItem.Builder(media)
+                    .also { b ->
+                        if (stillDurationUs > 0) {
+                            // An image has no duration or rate of its own; both
+                            // are required before it can become video.
+                            b.setDurationUs(stillDurationUs)
+                            b.setFrameRate(30)
+                        }
+                    }
+                /*
+                  Muting is silence, not absence, and it is set alongside the
+                  rate change deliberately: `setRemoveAudio` with a speed change
+                  asks Media3 to re-time a stream it has been told to discard,
+                  which is the deadlock this slice was warned about. Every
+                  combination is exercised, and the run has a timeout so a hang
+                  would be reported rather than waited on.
+                */
+                if (item != null && item.removeAudio) {
+                    edited.setRemoveAudio(true)
+                }
+                /*
+                  Pitch is preserved by default, and that is a measurement rather
+                  than a preference: `setSpeed` alone put a 440 Hz tone at 215 Hz
+                  on a 0.5x clip and 883 Hz on a 2x one -- half and double, the
+                  tape effect. `createExperimentalSpeedChangingEffect` returns a
+                  Sonic audio processor paired with the matching timestamp
+                  adjustment, so the two stay coordinated instead of being two
+                  independent rate changes that could disagree.
+                */
+                var speedAudio: androidx.media3.common.audio.AudioProcessor? = null
+                val speedVideo: Effect? = null
+                if (item != null && item.speed != 1f) {
+                    edited.setSpeed(ConstantSpeed(item.speed))
+                    if (item.speedMode != "resample") {
+                        /*
+                          Media3 re-times audio by **resampling** it, on both
+                          public paths: `setSpeed` and
+                          `createExperimentalSpeedChangingEffect` both put a
+                          440 Hz tone at 215 Hz on a 0.5x clip and 883 Hz on a
+                          2x one, measured, identically. That is the tape
+                          effect, and it is not what a speed control on a clip
+                          should do to a voice.
+
+                          Sonic's pitch shift is the correction: the resampling
+                          already moved tempo and pitch together by the rate, so
+                          shifting pitch back by its reciprocal leaves the tempo
+                          changed and the pitch where it started. Composed
+                          rather than replaced, because the resampling is also
+                          what keeps audio and video the same length.
+                        */
+                        val sonic = androidx.media3.common.audio.SonicAudioProcessor()
+                        sonic.setPitch(1f / item.speed)
+                        speedAudio = sonic
+                    }
+                }
+                run {
+                    val audio = ArrayList<androidx.media3.common.audio.AudioProcessor>()
+                    /*
+                      Every shard's audio ends up the same shape.
+
+                      A source's own track is whatever it is -- the fixtures are
+                      mono -- while the silence Media3 generates for a muted or
+                      audio-less clip is stereo. A concatenation cannot copy
+                      samples between tracks with different channel counts, so it
+                      silently re-encodes instead: measured, 176 shard samples
+                      became 174 of which only 120 were byte-identical. Forcing
+                      one layout on every shard is what makes the final transmux
+                      a copy.
+                    */
+                    if (normaliseAudioChannels > 0) {
+                        val mixer = androidx.media3.common.audio.ChannelMixingAudioProcessor()
+                        for (inChannels in 1..2) {
+                            mixer.putChannelMixingMatrix(
+                                androidx.media3.common.audio.ChannelMixingMatrix.createForConstantPower(
+                                    inChannels, normaliseAudioChannels,
+                                ),
+                            )
+                        }
+                        audio.add(mixer)
+                    }
+                    speedAudio?.let { audio.add(it) }
+                    val video = ArrayList<Effect>()
+                    // The timestamp adjustment first: everything downstream must
+                    // see the re-timed stream, not the original one.
+                    speedVideo?.let { video.add(it) }
+                    video.addAll(chain)
+                    edited.setEffects(Effects(ImmutableList.copyOf(audio), ImmutableList.copyOf(video)))
+                }
+                if (item != null && item.durationUs > 0) {
+                    // Source-time length, which is what the clip actually is.
+                    // Declared, not invented: Media3 cannot always determine an
+                    // item's duration itself, and a sequence that guesses wrong
+                    // lays out the following items at the wrong offset.
+                    edited.setDurationUs(item.durationUs)
+                }
+                builder.addItem(edited.build())
+            }
+            val composition = Composition.Builder(builder.build())
+                // Force the decode/encode round trip even with no effect, so the
+                // vanilla run measures the codec rather than a byte copy.
+                .setTransmuxVideo(transmuxVideo)
+                /*
+                  Audio too, or the concatenation re-encodes it.
+
+                  `setTransmuxVideo` covers only video: the first measured
+                  concatenation copied all 120 video samples byte-for-byte while
+                  turning 86 audio samples into 175 re-encoded ones. A second
+                  generation of lossy audio on every export, invisible to any
+                  video-only check.
+                */
+                .setTransmuxAudio(transmuxVideo)
+                .build()
+            val transformer = Transformer.Builder(context)
+                .also { builderRef ->
+                    if (stillDurationUs > 0) {
+                        // The default factory routes everything to the ExoPlayer
+                        // asset loader, which looks for tracks a PNG does not
+                        // have. An image needs a loader that can read a bitmap.
+                        builderRef.setAssetLoaderFactory(
+                            androidx.media3.transformer.DefaultAssetLoaderFactory(
+                                context,
+                                androidx.media3.datasource.DataSourceBitmapLoader(context),
+                            ),
+                        )
+                    }
+                }
+                .also { builderRef ->
+                    if (encoderRepeatUs > 0 && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+                        builderRef.setEncoderFactory(
+                            RepeatingEncoderFactory(context, encoderRepeatUs, 30),
+                        )
+                    }
+                }
+                .addListener(object : Transformer.Listener {
+                    override fun onCompleted(composition: Composition, exportResult: ExportResult) {
+                        activeTransformer = null
+                        activeLatch = null
+                        result = exportResult
+                        latch.countDown()
+                    }
+
+                    override fun onError(
+                        composition: Composition,
+                        exportResult: ExportResult,
+                        exportException: ExportException,
+                    ) {
+                        activeTransformer = null
+                        activeLatch = null
+                        failure = exportException
+                        latch.countDown()
+                    }
+                })
+                .build()
+            /*
+              Published so a cancel can reach *this* Transformer.
+
+              This is the one that encodes the video shards, and it was the only
+              construction site that never registered itself. `cancelJob` found
+              nothing to cancel and returned in 30 microseconds while the shard
+              carried on emitting — traced at 0.1x, where the cadence loop went
+              from 30 to 220 copies after the cancel had already "returned".
+              Every cancellation then waited for the shard to finish on its own
+              and was caught by the next stage check, which is where the seconds
+              came from.
+            */
+            if (cancelled) {
+                cancelledEarly = true
+                latch.countDown()
+                return@post
+            }
+            activeTransformer = transformer
+            activeLatch = latch
+            runCatching { transformer.start(composition, output.absolutePath) }
+                .onFailure {
+                    failure = ExportException.createForUnexpected(RuntimeException(it))
+                    latch.countDown()
+                }
+        }
+
+        val finished = latch.await(timeoutSeconds, TimeUnit.SECONDS)
+        val elapsedMs = (System.nanoTime() - startedNs) / 1_000_000
+        val ok = finished && failure == null && result != null && !cancelledEarly
+
+        if (!ok) {
+            // A failed gate leaves no partial file. Transformer writes as it
+            // goes, so there usually *is* one by now.
+            releaseTemp(output)
+            probe?.release()
+            finishRun(ok = false, wasCancelled = cancelled)
+            return Outcome(
+                ok = false,
+                uri = "",
+                error = when {
+                    !finished -> "timeout after ${timeoutSeconds}s"
+                    failure != null -> buildString {
+                        append(failure!!.errorCode).append(": ").append(failure!!.message)
+                        // The message alone says "Video frame processing error"
+                        // and nothing about which effect refused. The cause
+                        // chain is where the actual reason lives.
+                        var cause: Throwable? = failure!!.cause
+                        var depth = 0
+                        while (cause != null && depth < 4) {
+                            append(" <- ").append(cause.javaClass.simpleName)
+                            append(": ").append(cause.message)
+                            cause = cause.cause
+                            depth += 1
+                        }
+                    }
+                    else -> "no result"
+                },
+                elapsedMs = elapsedMs,
+                fileBytes = 0,
+                durationMs = 0,
+                width = 0,
+                height = 0,
+                videoFrameCount = 0,
+                hasAudio = false,
+                videoMimeType = "",
+                audioMimeType = "",
+                colorInfo = "",
+                glErrors = probe?.glErrors() ?: "",
+                effectFrames = probe?.frameCount() ?: 0,
+                effectTimestampsUs = probe?.timestamps() ?: "",
+                boundary = probe?.boundary() ?: "",
+                lifecycle = probe?.lifecycle() ?: "",
+                programTrace = probe?.programTrace() ?: "",
+                overlayUploads = probe?.overlayUploads?.get() ?: 0,
+                overlayDraws = probe?.overlayDraws?.get() ?: 0,
+                overlayTexturesFreed = probe?.overlayTexturesFreed?.get() ?: 0,
+                nativeHeapBytes = android.os.Debug.getNativeHeapAllocatedSize(),
+                javaHeapBytes = Runtime.getRuntime().let { it.totalMemory() - it.freeMemory() },
+                callerThread = callerThread,
+            )
+        }
+
+        val r = result!!
+        val outcome = Outcome(
+            ok = true,
+            // Scheme and nothing else at this boundary; the caller gets a path
+            // it already owns.
+            uri = output.absolutePath,
+            error = "",
+            elapsedMs = elapsedMs,
+            fileBytes = output.length(),
+            durationMs = r.durationMs,
+            width = r.width,
+            height = r.height,
+            videoFrameCount = r.videoFrameCount,
+            hasAudio = r.audioMimeType != null,
+            videoMimeType = r.videoMimeType ?: "",
+            audioMimeType = r.audioMimeType ?: "",
+            colorInfo = r.colorInfo?.toString() ?: "",
+            glErrors = probe?.glErrors() ?: "",
+            effectFrames = probe?.frameCount() ?: 0,
+            effectTimestampsUs = probe?.timestamps() ?: "",
+            boundary = probe?.boundary() ?: "",
+            lifecycle = probe?.lifecycle() ?: "",
+            programTrace = probe?.programTrace() ?: "",
+            overlayUploads = probe?.overlayUploads?.get() ?: 0,
+            overlayDraws = probe?.overlayDraws?.get() ?: 0,
+            overlayTexturesFreed = probe?.overlayTexturesFreed?.get() ?: 0,
+            nativeHeapBytes = android.os.Debug.getNativeHeapAllocatedSize(),
+            javaHeapBytes = Runtime.getRuntime().let { it.totalMemory() - it.freeMemory() },
+            callerThread = callerThread,
+        )
+        // The effect's own resources go exactly once, whether or not it ran.
+        probe?.release()
+        finishRun(ok = outcome.ok, wasCancelled = cancelled)
+        return outcome
+    }
+
+    /** Delete every temporary this gate still owns. Idempotent. */
+    /**
+     * Release one temporary output, by path, and only if this made it.
+     *
+     * The production counterpart to `releaseTemporary`, which sweeps. A sweep is
+     * exactly wrong here: a caller holding the temporary from an *earlier*
+     * export still owns that file, and a later export's cleanup taking it is a
+     * result disappearing under whoever was previewing it.
+     *
+     * Idempotent by construction. A path that is not in `created` was not made
+     * here, so nothing is deleted and nothing is an error — which also means a
+     * host cannot hand this an arbitrary path and have it removed.
+     */
+    fun releaseTemporaryOutput(path: String): Boolean {
+        val file = synchronized(created) { created.firstOrNull { it.absolutePath == path } }
+            ?: return false
+        releaseTemp(file)
+        return true
+    }
+
+    /** Gate-only: which temporaries are still registered, by name. */
+    fun liveTemporaryNames(): List<String> =
+        synchronized(created) { created.map { it.name } }
+
+    fun releaseTemporary(): Int {
+        var gone: Int
+        synchronized(created) {
+            // Everything registered is accounted for, whether or not the delete
+            // found a file: a run that already removed its own output must not
+            // leave the created/released ledger permanently short.
+            tempFilesReleased.addAndGet(created.size.toLong())
+            gone = created.count { runCatching { it.delete() }.getOrDefault(false) }
+            created.clear()
+        }
+        /*
+          Also sweep by name.
+
+          `created` only knows about this instance. A run whose process was
+          killed, or an export deliberately kept for inspection, leaves a file no
+          later instance can see — and the gate writes megabytes per run into a
+          cache directory the user never asked to fill. The prefix is specific
+          enough that nothing else can match it.
+        */
+        gone += runCatching {
+            context.cacheDir.listFiles { f -> f.name.startsWith(TEMP_PREFIX) }
+                ?.count { runCatching { it.delete() }.getOrDefault(false) } ?: 0
+        }.getOrDefault(0)
+        return gone
+    }
+
+    private companion object {
+        const val TEMP_PREFIX = "pictor-gate-"
+    }
+}