@camstack/types 1.2.41 → 1.2.42

package/dist/interfaces/camera-switches.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Per-camera FUNCTION SWITCHES — the one coherent on/off surface over the
+ * pipeline functions an operator thinks in terms of.
+ *
+ * ## This file adds no state
+ *
+ * Every switch here is a VIEW onto an authority that already existed
+ * ([D61](../../../../docs/decisions/adr-0062.md)). The whole point of the
+ * group is that there is exactly one place each function is turned off, and
+ * the group routes to it:
+ *
+ * | Switch | Authority | Proven "off stops the work" gate |
+ * | --- | --- | --- |
+ * | `stream-broker` | `deviceManager.setDisabled` | `StreamBrokerManager.reconcileAllCatalogs` releases the brokers; `ensureBroker` refuses re-creation |
+ * | `object-detection` | `deviceManager.setWrapperActive('detection-pipeline')` | `PipelineSettingsStore.resolvePipelineForDevice` returns `{ steps: [], audio: null }` |
+ * | `audio-analysis` | `deviceManager.setWrapperActive('audio-analysis')` | `AudioSubscriptionController.subscribeAudioStream` returns `null` before opening the stream |
+ * | `recording` | `recording.setDeviceConfig` → `RecordingConfig.enabled` | `band-decision.shouldRecord` returns false; the controller detaches the device |
+ * | `notifications` | `notificationRules.setDeviceMuted` | `NotificationCenter.evaluateAndEnqueue` returns before any rule is evaluated |
+ *
+ * The wrapper-binding pair is not a new idea: `legacy-migrations.ts` already
+ * migrated the legacy `audioEnabled` / `pipelineEnabled` /
+ * `motionDetectionEnabled` booleans ONTO `setWrapperActive`. The group is the
+ * surface that decision never got.
+ *
+ * ## Two rules that are load-bearing
+ *
+ * - **Recording's switch is `enabled`, never the bands.** `bands` is the only
+ *   authored intent and `mode` is derived from it (`deriveRecordingMode`).
+ *   Expressing "off" by clearing bands destroys the operator's schedule and
+ *   turning the camera back on would then silently record nothing.
+ * - **A switch that is off must be reported as off**, not merely produce
+ *   nothing. {@link CameraSwitch.enabled} is what a status surface renders as
+ *   "disabled by an operator" instead of "broken" — see
+ *   `CameraStatus.switchedOff`.
+ */
+import { z } from 'zod';
+/**
+ * The five functions the operator named (2026-08-05). Deliberately NOT one id
+ * per pipeline step: face recognition and plate/LPR are per-step toggles on
+ * `pipelineOrchestrator.setCameraStepToggle` and belong in the pipeline
+ * editor, not in a five-button safety group.
+ */
+export declare const CameraSwitchIdSchema: z.ZodEnum<{
+    "audio-analysis": "audio-analysis";
+    recording: "recording";
+    "stream-broker": "stream-broker";
+    notifications: "notifications";
+    "object-detection": "object-detection";
+}>;
+export type CameraSwitchId = z.infer<typeof CameraSwitchIdSchema>;
+/** Stable render order — broadest blast radius first. */
+export declare const CAMERA_SWITCH_ORDER: readonly CameraSwitchId[];
+/**
+ * WHERE the switch's state actually lives. A discriminated union rather than a
+ * string so both the writer (the orchestrator's `setCameraSwitch`) and any
+ * reader can exhaustively narrow — and so "the group added a parallel map" is
+ * a compile error rather than a review comment.
+ */
+export declare const CameraSwitchAuthoritySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"device-disabled">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"wrapper-binding">;
+    capName: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"recording-config">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"notification-mute">;
+}, z.core.$strip>], "kind">;
+export type CameraSwitchAuthority = z.infer<typeof CameraSwitchAuthoritySchema>;
+/**
+ * Why a switch is not offered for this camera. Rendered instead of the
+ * control, never as a dead control — an absent function and a broken one must
+ * not look the same.
+ */
+export declare const CameraSwitchUnavailableReasonSchema: z.ZodEnum<{
+    "no-provider": "no-provider";
+    "source-unreachable": "source-unreachable";
+}>;
+export type CameraSwitchUnavailableReason = z.infer<typeof CameraSwitchUnavailableReasonSchema>;
+/**
+ * One switch, resolved for one camera.
+ *
+ * `label` and `costWhenOff` travel ON THE WIRE rather than being looked up
+ * client-side: the viewer is a separate repository that does not import
+ * `@camstack/types`, and a cost line duplicated in two clients is a cost line
+ * that will disagree with itself. Five rows per camera is nothing.
+ */
+export declare const CameraSwitchSchema: z.ZodObject<{
+    id: z.ZodEnum<{
+        "audio-analysis": "audio-analysis";
+        recording: "recording";
+        "stream-broker": "stream-broker";
+        notifications: "notifications";
+        "object-detection": "object-detection";
+    }>;
+    label: z.ZodString;
+    costWhenOff: z.ZodString;
+    available: z.ZodBoolean;
+    unavailableReason: z.ZodOptional<z.ZodEnum<{
+        "no-provider": "no-provider";
+        "source-unreachable": "source-unreachable";
+    }>>;
+    enabled: z.ZodBoolean;
+    authority: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"device-disabled">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"wrapper-binding">;
+        capName: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"recording-config">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"notification-mute">;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
+export type CameraSwitch = z.infer<typeof CameraSwitchSchema>;
+/** The whole group for one camera. */
+export declare const CameraSwitchGroupSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    switches: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        id: z.ZodEnum<{
+            "audio-analysis": "audio-analysis";
+            recording: "recording";
+            "stream-broker": "stream-broker";
+            notifications: "notifications";
+            "object-detection": "object-detection";
+        }>;
+        label: z.ZodString;
+        costWhenOff: z.ZodString;
+        available: z.ZodBoolean;
+        unavailableReason: z.ZodOptional<z.ZodEnum<{
+            "no-provider": "no-provider";
+            "source-unreachable": "source-unreachable";
+        }>>;
+        enabled: z.ZodBoolean;
+        authority: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"device-disabled">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"wrapper-binding">;
+            capName: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"recording-config">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"notification-mute">;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>>>;
+    fetchedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type CameraSwitchGroup = z.infer<typeof CameraSwitchGroupSchema>;
+/**
+ * The wrapper capability each wrapper-backed switch controls. Named constants
+ * because the same strings appear in `legacy-migrations.ts`, in
+ * `isCapActiveForDevice` call sites and in the fake harness — a typo in any of
+ * them is a switch that silently writes a binding nobody reads.
+ */
+export declare const DETECTION_PIPELINE_CAP_NAME = "detection-pipeline";
+export declare const AUDIO_ANALYSIS_CAP_NAME = "audio-analysis";
+/** Static half of a switch: everything that does not depend on a device. */
+export interface CameraSwitchDescriptor {
+    readonly id: CameraSwitchId;
+    readonly label: string;
+    readonly costWhenOff: string;
+    readonly authority: CameraSwitchAuthority;
+}
+/**
+ * THE catalog. One entry per switch; the cost lines are the operator-facing
+ * contract and are written to be true rather than reassuring.
+ */
+export declare const CAMERA_SWITCH_CATALOG: Readonly<Record<CameraSwitchId, CameraSwitchDescriptor>>;
+/**
+ * Everything the pure derivation needs, gathered by the caller. A `null`
+ * sub-state means the owning source did not answer — which produces
+ * `available: false` with `source-unreachable`, NEVER a control defaulted to
+ * "on". Guessing a switch is on when we could not read it is how an operator
+ * learns a function is off a week later.
+ */
+export interface CameraSwitchDerivationInput {
+    readonly deviceId: number;
+    /** `deviceManager` soft-disable flag for this device. */
+    readonly deviceDisabled: boolean;
+    /**
+     * Capability names bindable for this device's TYPE
+     * (`deviceManager.listBindableCapsForDeviceType`). This is what makes the
+     * group derived rather than hardcoded: a deployment with no audio analyzer
+     * has no `audio-analysis` here, so no audio switch is rendered.
+     * `null` = the lookup failed.
+     */
+    readonly bindableCapNames: readonly string[] | null;
+    /**
+     * Capability names currently bound `kind: 'wrapped'` for this device
+     * (`deviceManager.getBindings`). Absence IS how a deactivated wrapper is
+     * represented — there is no `active: false` row.
+     */
+    readonly activeWrapperCapNames: readonly string[] | null;
+    /** `RecordingConfig.enabled`; `null` when the recording cap did not answer. */
+    readonly recordingEnabled: boolean | null;
+    /** `notificationRules` per-camera mute; `null` when the cap did not answer. */
+    readonly notificationsMuted: boolean | null;
+}
+/**
+ * Pure derivation of the whole group. No I/O — the orchestrator gathers, this
+ * decides, so the decision is testable without a hub.
+ *
+ * Order is {@link CAMERA_SWITCH_ORDER}; unavailable switches are RETURNED
+ * rather than filtered out, so a client can explain the gap instead of
+ * silently rendering four buttons where another camera shows five.
+ */
+export declare function deriveCameraSwitches(input: CameraSwitchDerivationInput): readonly CameraSwitch[];
+/**
+ * The ids an operator has switched OFF, for a status surface.
+ *
+ * This is the answer to "a disabled function must be visible as DISABLED, not
+ * merely quiet": a camera reporting zero detections with
+ * `switchedOff: ['object-detection']` was turned off; the same camera with an
+ * empty list is broken. Unavailable switches never appear — a function nobody
+ * provides was not switched off by anyone.
+ */
+export declare function switchedOffIds(switches: readonly CameraSwitch[]): readonly CameraSwitchId[];

package/dist/interfaces/ops-log.d.ts

@@ -23,6 +23,7 @@ export declare const OpsLogOpSchema: z.ZodEnum<{
     rescan: "rescan";
     "retention-run": "retention-run";
     relocate: "relocate";
+    "orphan-audit": "orphan-audit";
 }>;
 export type OpsLogOp = z.infer<typeof OpsLogOpSchema>;
 /** Why the operation ran. */
@@ -31,6 +32,7 @@ export declare const OpsLogReasonSchema: z.ZodEnum<{
     operator: "operator";
     retention: "retention";
     quota: "quota";
+    maintenance: "maintenance";
 }>;
 export type OpsLogReason = z.infer<typeof OpsLogReasonSchema>;
 /** One audit row, shared verbatim by both domains. */
@@ -47,12 +49,14 @@ export declare const OpsLogEntrySchema: z.ZodObject<{
         rescan: "rescan";
         "retention-run": "retention-run";
         relocate: "relocate";
+        "orphan-audit": "orphan-audit";
     }>;
     reason: z.ZodEnum<{
         manual: "manual";
         operator: "operator";
         retention: "retention";
         quota: "quota";
+        maintenance: "maintenance";
     }>;
     deviceId: z.ZodNullable<z.ZodNumber>;
     nodeId: z.ZodString;

package/dist/interfaces/pipeline-runner-capability.d.ts

@@ -1,7 +1,7 @@
-import type { OrchestratorMetrics, CameraMetrics } from './api-shared.js';
 import type { PipelineStepInputOutput } from '../capabilities/pipeline-executor.cap.js';
 import type { Zone } from '../capabilities/zones.cap.js';
 import type { PipelinePhaseMode } from '../device/device-profile.js';
+import type { CameraMetrics, OrchestratorMetrics } from './api-shared.js';
 /**
  * Camera assignment payload sent by the pipeline-orchestrator to a runner
  * via `attachCamera`. Carries everything the runner needs to subscribe to
@@ -204,4 +204,12 @@ export interface IPipelineRunnerProvider {
      * `null` when neither `frameHandle` nor `cropJpeg` resolves to a crop.
      */
     runDetailSubtree(input: import('../capabilities/pipeline-runner.cap.js').RunDetailSubtreeInput): Promise<import('../capabilities/pipeline-runner.cap.js').RunDetailSubtreeResult | null>;
+    /**
+     * Run ONE enrichment step against caller-supplied pixels with NO camera
+     * session — no attach, no handle, no device affinity. See
+     * `pipelineRunnerCapability.runStatelessStep`
+     * (`capabilities/pipeline-runner.cap.ts`) for the full contract, including
+     * why the model pin is refused rather than substituted.
+     */
+    runStatelessStep(input: import('../capabilities/pipeline-runner.cap.js').RunStatelessStepInput): Promise<import('../capabilities/pipeline-runner.cap.js').RunStatelessStepResult>;
 }

package/dist/node.d.ts

@@ -6,3 +6,5 @@ export { FilesystemStorageProvider } from './storage/filesystem-storage-provider
 export { canonicalHash } from './utils/canonical-hash.js';
 export { canonicalDeviceFingerprint, diffExportTargets, resolveExportFingerprint, } from './utils/export-reconciler.js';
 export type { DeviceExportShape, ExportDelta, ExportTargetEntry, } from './utils/export-reconciler.js';
+export { FfmpegProcess } from './ffmpeg/process.js';
+export type { FfmpegProcessOptions, FfmpegExit, FfmpegExitClass } from './ffmpeg/process.js';

package/dist/node.js

@@ -21,7 +21,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
+const require_canonical_hash = require("./canonical-hash-BcZHRHIx.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
+let node_crypto = require("node:crypto");
 let node_fs = require("node:fs");
 node_fs = __toESM(node_fs);
 let node_path = require("node:path");
@@ -29,7 +31,6 @@ node_path = __toESM(node_path);
 let node_stream_promises = require("node:stream/promises");
 let node_stream = require("node:stream");
 let node_child_process = require("node:child_process");
-let node_crypto = require("node:crypto");
 //#region src/deps/binary-downloader.ts
 /**
 * Recursively find the first file named exactly `name` under `dir`. Used as the
@@ -600,39 +601,6 @@ var FilesystemStorageProvider = class {
 	}
 };
 //#endregion
-//#region src/utils/canonical-hash.ts
-/**
-* Deterministic SHA-256 hash of an arbitrary serialisable value. The
-* canonical form sorts object keys alphabetically at every depth so two
-* structurally-equal inputs with different key insertion orders produce
-* the same hash. Returns a 64-char lowercase hex digest.
-*
-* Used by export adapters (Alexa, HAP) to short-circuit re-discovery /
-* accessory-rebuild work when the upstream shape is byte-identical to
-* the last applied state — preventing user-visible "re-discovery"
-* notifications on every addon-runner respawn. Each respawn re-fires
-* `DeviceBindingsChanged` for every cap registration, which without
-* this guard would propagate redundant pushes.
-*
-* Note: this is a SYMPTOMATIC fix layered on top of the binding-change
-* subscription. The proper fix is a single "device ready" lifecycle
-* barrier so exports react only when the full cap set has landed —
-* tracked separately for post-HA-integration work.
-*/
-function canonicalHash(value) {
-	const canonical = JSON.stringify(value, replaceWithSortedKeys);
-	return (0, node_crypto.createHash)("sha256").update(canonical ?? "").digest("hex");
-}
-function replaceWithSortedKeys(_key, value) {
-	if (value && typeof value === "object" && !Array.isArray(value)) {
-		const obj = value;
-		const out = {};
-		for (const k of Object.keys(obj).toSorted()) out[k] = obj[k];
-		return out;
-	}
-	return value;
-}
-//#endregion
 //#region src/utils/export-reconciler.ts
 /**
 * Compute the stable 64-char lowercase-hex fingerprint of a device's
@@ -641,7 +609,7 @@ function replaceWithSortedKeys(_key, value) {
 */
 function canonicalDeviceFingerprint(shape) {
 	const features = [...new Set(shape.features)].toSorted();
-	return canonicalHash({
+	return require_canonical_hash.canonicalHash({
 		deviceType: shape.deviceType,
 		features
 	});
@@ -689,11 +657,277 @@ function resolveExportFingerprint(input) {
 	return input.persisted ?? input.fresh;
 }
 //#endregion
+//#region src/ffmpeg/process.ts
+/**
+* `FfmpegProcess` — the ONE spawn/lifecycle wrapper for a live-media ffmpeg.
+*
+* Extracted from `TranscodeEgress.spawnAttempt`, which was already the most
+* complete of the repo's hand-rolled lifecycles: first-data deadline, hardware
+* →software retry, SIGTERM-then-SIGKILL. This generalises it and adds the two
+* things every copy was missing — a `tags: { deviceId }` on every line, and a
+* bounded restart — so a consumer gets them by construction instead of by
+* remembering.
+*
+* ## What it owns
+*
+* - spawn, with the argv from the ONE builder (`./invocation.js`);
+* - a FIRST-DATA deadline: an ffmpeg that starts but never emits is dead, and
+*   nothing downstream can tell that apart from a slow camera;
+* - HARDWARE→SOFTWARE retry, announced at `warn`. A silent downgrade on this
+*   hub is a flow bug, not a capability limit — see `docs/design/decode-path.md`;
+* - exit classification (`ok` / `signalled-by-us` / `crashed` / `no-output`);
+* - bounded restart with backoff, and a terminal give-up (never an infinite
+*   loop — the same rule `CrashSupervisor` enforces for runners, D6);
+* - SIGTERM then SIGKILL after a grace, gated on the child not having already
+*   exited.
+*
+* ## What it does NOT own
+*
+* The output PLUMBING. A consumer attaches to `stdout` / `stderr` itself,
+* because what the bytes mean is the consumer's business: the broker deframes
+* Annex-B into a restreamer, the WebRTC leg regroups access units, HomeKit
+* writes nothing to stdout at all (its output is two RTP sockets). A wrapper
+* that also owned the bytes would need a mode per consumer, which is the same
+* mistake as one builder per consumer.
+*/
+var DEFAULT_FIRST_DATA_TIMEOUT_MS = 8e3;
+var DEFAULT_RESTART_DELAY_MS = 1e3;
+var DEFAULT_STABLE_RUN_MS = 3e4;
+var DEFAULT_KILL_GRACE_MS = 500;
+var STDERR_TAIL_LINES = 12;
+var FfmpegProcess = class {
+	opts;
+	child = null;
+	stopped = false;
+	producedOutput = false;
+	consecutiveFailures = 0;
+	startedAtMs = 0;
+	stderrTail = [];
+	activeHwAccel;
+	triedSoftwareFallback = false;
+	firstDataTimer = null;
+	constructor(opts) {
+		this.opts = opts;
+		this.activeHwAccel = opts.decodeHwAccel;
+	}
+	/** Queryable tags on every line — `deviceId` is never optional. */
+	get logTags() {
+		return {
+			deviceId: this.opts.deviceId,
+			...this.opts.tags
+		};
+	}
+	get now() {
+		return (this.opts.now ?? Date.now)();
+	}
+	/** `true` while a child is running. */
+	isRunning() {
+		return this.child !== null && !this.stopped;
+	}
+	/** The backend the CURRENT child decodes with (`null` ⇒ software). */
+	activeDecodeHwAccel() {
+		return this.activeHwAccel;
+	}
+	/**
+	* Spawn the first child. Resolves as soon as it produces output; rejects if
+	* it dies or stays silent past the deadline AFTER the software retry has
+	* also been exhausted. A caller that wants fire-and-forget can ignore the
+	* promise — the restart loop runs regardless.
+	*/
+	start() {
+		return new Promise((resolve, reject) => {
+			this.spawnAttempt(resolve, reject);
+		});
+	}
+	spawnAttempt(onLive, onDead) {
+		if (this.stopped) return;
+		const args = [...this.opts.buildArgs(this.activeHwAccel)];
+		const spawnFn = this.opts.spawnFn ?? node_child_process.spawn;
+		const setTimeoutImpl = this.opts.setTimeoutFn ?? setTimeout;
+		this.opts.logger.info(`ffmpeg ${this.opts.role}: spawning`, {
+			tags: this.logTags,
+			meta: {
+				decodeHwAccel: this.activeHwAccel ?? "software",
+				attempt: this.consecutiveFailures + 1
+			}
+		});
+		let child;
+		try {
+			child = spawnFn(this.opts.binaryPath, args, { stdio: this.opts.stdio ?? [
+				"ignore",
+				"pipe",
+				"pipe"
+			] });
+		} catch (err) {
+			this.handleFailure("crashed", null, null, err, onLive, onDead);
+			return;
+		}
+		this.child = child;
+		this.startedAtMs = this.now;
+		this.producedOutput = false;
+		this.stderrTail = [];
+		let settled = false;
+		const timeoutMs = this.opts.firstDataTimeoutMs ?? DEFAULT_FIRST_DATA_TIMEOUT_MS;
+		if (timeoutMs > 0) this.firstDataTimer = setTimeoutImpl(() => {
+			if (settled || this.producedOutput || this.stopped) return;
+			settled = true;
+			this.opts.logger.warn(`ffmpeg ${this.opts.role}: no output within ${timeoutMs}ms`, {
+				tags: this.logTags,
+				meta: { decodeHwAccel: this.activeHwAccel ?? "software" }
+			});
+			this.killChild();
+			this.handleFailure("no-output", null, null, null, onLive, onDead);
+		}, timeoutMs);
+		child.stderr?.setEncoding("utf8");
+		child.stderr?.on("data", (line) => {
+			const text = String(line).trim();
+			if (text.length === 0) return;
+			this.stderrTail.push(text);
+			if (this.stderrTail.length > STDERR_TAIL_LINES) this.stderrTail.shift();
+			this.opts.logger.debug(`ffmpeg ${this.opts.role}`, {
+				tags: this.logTags,
+				meta: { line: text }
+			});
+		});
+		child.once("error", (err) => {
+			if (settled || this.stopped) return;
+			settled = true;
+			this.handleFailure("crashed", null, null, err, onLive, onDead);
+		});
+		child.once("exit", (code, signal) => {
+			this.clearFirstDataTimer();
+			if (this.child === child) this.child = null;
+			if (this.stopped) {
+				this.report("stopped", code, signal);
+				return;
+			}
+			if (settled && this.producedOutput) {
+				this.report("crashed", code, signal);
+				this.scheduleRestart(onLive, onDead);
+				return;
+			}
+			if (settled) return;
+			settled = true;
+			this.handleFailure(this.producedOutput ? "crashed" : "no-output", code, signal, null, onLive, onDead);
+		});
+		this.opts.onChild(child);
+		child.stdout?.once("data", () => {
+			this.producedOutput = true;
+			this.clearFirstDataTimer();
+			if (settled) return;
+			settled = true;
+			this.opts.logger.info(`ffmpeg ${this.opts.role}: live`, {
+				tags: this.logTags,
+				meta: { decodeHwAccel: this.activeHwAccel ?? "software" }
+			});
+			onLive();
+		});
+	}
+	/**
+	* A child failed before going live. Try SOFTWARE once if it was decoding in
+	* hardware — loudly — then fall through to the bounded restart.
+	*/
+	handleFailure(classification, code, signal, err, onLive, onDead) {
+		this.report(classification, code, signal, err);
+		if (this.activeHwAccel !== null && !this.triedSoftwareFallback && !this.stopped) {
+			this.triedSoftwareFallback = true;
+			this.opts.logger.warn(`ffmpeg ${this.opts.role}: hardware decode produced no output — retrying in SOFTWARE`, {
+				tags: this.logTags,
+				meta: {
+					decodeHwAccel: this.activeHwAccel,
+					classification,
+					code,
+					signal,
+					stderrTail: this.stderrTail
+				}
+			});
+			this.activeHwAccel = null;
+			this.spawnAttempt(onLive, onDead);
+			return;
+		}
+		this.consecutiveFailures += 1;
+		const maxRestarts = this.opts.maxRestarts ?? 0;
+		if (this.consecutiveFailures > maxRestarts || this.stopped) {
+			const reason = `ffmpeg ${this.opts.role} gave up after ${this.consecutiveFailures} attempt(s) (${classification}, code=${code} signal=${signal})`;
+			this.opts.logger.error(reason, {
+				tags: this.logTags,
+				meta: { stderrTail: this.stderrTail }
+			});
+			onDead(new Error(reason));
+			return;
+		}
+		this.scheduleRestart(onLive, onDead);
+	}
+	scheduleRestart(onLive, onDead) {
+		if (this.stopped) return;
+		const maxRestarts = this.opts.maxRestarts ?? 0;
+		if (maxRestarts === 0) return;
+		if (this.producedOutput && this.now - this.startedAtMs >= (this.opts.stableRunMs ?? DEFAULT_STABLE_RUN_MS)) this.consecutiveFailures = 0;
+		if (this.consecutiveFailures > maxRestarts) return;
+		(this.opts.setTimeoutFn ?? setTimeout)(() => {
+			if (this.stopped) return;
+			this.spawnAttempt(onLive, onDead);
+		}, (this.opts.restartDelayMs ?? DEFAULT_RESTART_DELAY_MS) * Math.min(this.consecutiveFailures + 1, 8));
+	}
+	report(classification, code, signal, err) {
+		const exit = {
+			classification,
+			code,
+			signal,
+			stderrTail: [...this.stderrTail],
+			decodeHwAccel: this.activeHwAccel
+		};
+		if (classification === "crashed" || classification === "no-output") this.opts.logger.warn(`ffmpeg ${this.opts.role} exited: ${classification}`, {
+			tags: this.logTags,
+			meta: {
+				code,
+				signal,
+				decodeHwAccel: this.activeHwAccel ?? "software",
+				error: err instanceof Error ? err.message : err === void 0 ? void 0 : String(err),
+				stderrTail: exit.stderrTail
+			}
+		});
+		this.opts.onExit?.(exit);
+	}
+	clearFirstDataTimer() {
+		if (this.firstDataTimer !== null) {
+			clearTimeout(this.firstDataTimer);
+			this.firstDataTimer = null;
+		}
+	}
+	/** Terminate for good. Idempotent; no restart follows. */
+	stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		this.clearFirstDataTimer();
+		this.killChild();
+	}
+	killChild() {
+		const child = this.child;
+		this.child = null;
+		if (!child) return;
+		if (child.exitCode !== null || child.signalCode !== null) return;
+		try {
+			child.kill("SIGTERM");
+		} catch {
+			return;
+		}
+		const grace = (this.opts.setTimeoutFn ?? setTimeout)(() => {
+			if (child.exitCode !== null || child.signalCode !== null) return;
+			try {
+				child.kill("SIGKILL");
+			} catch {}
+		}, this.opts.killGraceMs ?? DEFAULT_KILL_GRACE_MS);
+		if (typeof grace === "object" && grace !== null && "unref" in grace) grace.unref();
+	}
+};
+//#endregion
+exports.FfmpegProcess = FfmpegProcess;
 exports.FilesystemStorageProvider = FilesystemStorageProvider;
 exports.PYTHON_VERSION = PYTHON_VERSION;
 exports.buildBinaryPath = buildBinaryPath;
 exports.canonicalDeviceFingerprint = canonicalDeviceFingerprint;
-exports.canonicalHash = canonicalHash;
+exports.canonicalHash = require_canonical_hash.canonicalHash;
 exports.diffExportTargets = diffExportTargets;
 exports.downloadBinary = downloadBinary;
 exports.ensureBinary = ensureBinary;