@camstack/addon-pipeline 1.1.61 → 1.1.63

package/dist/pipeline-runner/index.js

@@ -3,11 +3,11 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_dist = require("../dist-p_JqOxtk.js");
+const require_dist = require("../dist-B2jTt7Lq.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
 const require_sheet_geometry = require("../sheet-geometry-BR-ip0CP.js");
 const require_worker_protocol = require("../worker-protocol-PP4jKHHJ.js");
-const require_step_definitions = require("../step-definitions-CoxF5G31.js");
+const require_step_definitions = require("../step-definitions-DXkY5Zor.js");
 let node_child_process = require("node:child_process");
 let node_url = require("node:url");
 let sharp = require("sharp");
@@ -106,6 +106,109 @@ var pipelineRunnerBenchActions = require_dist.defineCustomActions({
 	runSyntheticBench: require_dist.customAction(RunSyntheticBenchInputSchema, RunSyntheticBenchResultSchema, { kind: "mutation" })
 });
 //#endregion
+//#region src/pipeline-runner/motion-settle-governor.ts
+/**
+* MotionSettleGovernor — decides WHEN the root-plane `package-detection` step
+* should run, so it is NOT executed on every frame.
+*
+* A delivered package is STATIONARY: per-frame inference on it is wasted cost.
+* The interesting moments are the EDGES — someone just set a parcel down, or
+* just picked one up — which coincide with motion in the package zone
+* SETTLING (transitioning from moving to still). This governor fires:
+*
+*   - on a **settle edge**: motion was observed, then has been absent for
+*     `settleMs` (kills flicker between motion frames and the "bag briefly
+*     set down then snatched back" case), and
+*   - on a **low-cadence safety poll** (`pollIntervalMs`, ~30–60s): a
+*     backstop so a delivery whose motion was never observed (a session-gap
+*     camera that only decodes intermittently) is still eventually caught.
+*
+* Pure logic with an injected clock (every method takes `now`), mirroring
+* `FrameGovernor` / `recomputeGovernor(now)` — no timers, no `Date.now()`
+* inside, fully unit-testable. Per-device state lives in a Map; the caller
+* consults it only while the step is enabled and calls `forget()` on detach.
+*
+* NOTE: today `motionInZone` is the whole-frame analyzer motion signal the
+* runner already tracks (`lastAnalyzerDetected`). Scoping it to the package
+* zone specifically (intersecting motion regions with the `package`-stage
+* zones) is a refinement that lands with the crop-zone frame-prep follow-up,
+* where the package zones first become available at the frame layer. The
+* governor contract does not change when that happens — only the boolean the
+* caller feeds it.
+*
+* See docs/superpowers/specs/2026-07-17-package-zones-design.md
+* (ADDENDUM 2026-07-17 — motion-settle trigger).
+*/
+/** The step id (`PipelineStepInput.addonId`) the governor gates. */
+var PACKAGE_DETECTION_STEP_ID = "package-detection";
+var DEFAULT_MOTION_SETTLE_CONFIG = {
+	settleMs: 3e3,
+	pollIntervalMs: 45e3
+};
+var INITIAL_STATE = {
+	lastMotionAt: null,
+	armed: false,
+	lastRunAt: Number.NEGATIVE_INFINITY
+};
+var NO_RUN = {
+	run: false,
+	reason: null
+};
+var MotionSettleGovernor = class {
+	config;
+	state = /* @__PURE__ */ new Map();
+	constructor(config = DEFAULT_MOTION_SETTLE_CONFIG) {
+		this.config = config;
+	}
+	/**
+	* Decide whether `package-detection` runs for this device this frame, and
+	* advance the per-device state immutably. Never throws.
+	*/
+	evaluate(sample) {
+		const prev = this.state.get(sample.deviceId) ?? INITIAL_STATE;
+		const lastMotionAt = sample.motionInZone ? sample.now : prev.lastMotionAt;
+		const armed = sample.motionInZone ? true : prev.armed;
+		const settleReady = armed && !sample.motionInZone && lastMotionAt !== null && sample.now - lastMotionAt >= this.config.settleMs;
+		const pollReady = sample.now - prev.lastRunAt >= this.config.pollIntervalMs;
+		if (settleReady) {
+			this.state.set(sample.deviceId, {
+				lastMotionAt,
+				armed: false,
+				lastRunAt: sample.now
+			});
+			return {
+				run: true,
+				reason: "settle"
+			};
+		}
+		if (pollReady) {
+			this.state.set(sample.deviceId, {
+				lastMotionAt,
+				armed,
+				lastRunAt: sample.now
+			});
+			return {
+				run: true,
+				reason: "poll"
+			};
+		}
+		this.state.set(sample.deviceId, {
+			lastMotionAt,
+			armed,
+			lastRunAt: prev.lastRunAt
+		});
+		return NO_RUN;
+	}
+	/** Drop a device's state (call on detach / step-disable) to avoid a leak. */
+	forget(deviceId) {
+		this.state.delete(deviceId);
+	}
+	/** Clear all state (e.g. runner teardown). */
+	reset() {
+		this.state.clear();
+	}
+};
+//#endregion
 //#region src/pipeline-runner/frame-governor.ts
 var FrameGovernor = class {
 	config;
@@ -2401,6 +2504,13 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 	*  only (otherwise we'd emit on every analyzer frame). */
 	lastAnalyzerDetected = /* @__PURE__ */ new Map();
 	/**
+	* Gates the root-plane `package-detection` step to motion-settle edges +
+	* a low-cadence safety poll instead of every frame (packages are
+	* stationary — per-frame parcel inference is wasted cost). Consulted in
+	* `runInference` only when the step is enabled; state dropped on detach.
+	*/
+	packageGovernor = new MotionSettleGovernor();
+	/**
 	* Last positive motion timestamp per device — preserved across the
 	* OFF transition so the motion runtime-state slice keeps a stable
 	* `lastDetectedAt` after the cooldown closes the phase. Cleared on
@@ -2584,6 +2694,7 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 			this.unsubMotionEvents = null;
 		}
 		this.lastAnalyzerDetected.clear();
+		this.packageGovernor.reset();
 		for (const deviceId of [...this.onboardAnalyzerTeardownTimers.keys(), ...this.onboardAnalyzerSubs.keys()]) this.clearOnboardAnalyzer(deviceId);
 		if (this.runner) {
 			this.runner.stop();
@@ -3197,6 +3308,7 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 		this.lastMotionFrameAt.delete(deviceId);
 		this.lastDecodeUnexpectedEndAt.delete(deviceId);
 		this.thumbSampler?.forget(deviceId);
+		this.packageGovernor.forget(deviceId);
 		this.attached.delete(deviceId);
 		this.lastMotionAt.delete(deviceId);
 		this.lastEmittedCameraMetrics.delete(deviceId);
@@ -3615,6 +3727,17 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 			return null;
 		}
 		if (steps.length === 0) return null;
+		let dispatchSteps = steps;
+		if (steps.some((s) => s.addonId === "package-detection" && s.enabled !== false)) {
+			if (!this.packageGovernor.evaluate({
+				deviceId,
+				motionInZone: this.lastAnalyzerDetected.get(deviceId) ?? false,
+				now: Date.now()
+			}).run) {
+				dispatchSteps = steps.filter((s) => s.addonId !== PACKAGE_DETECTION_STEP_ID);
+				if (dispatchSteps.length === 0) return null;
+			}
+		}
 		let image;
 		if (!this.executorCoLocated()) {
 			if (frame.format === "rgb") try {
@@ -3629,7 +3752,7 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 		}
 		try {
 			return await api.pipelineExecutor.runPipeline.mutate({
-				steps: [...steps],
+				steps: [...dispatchSteps],
 				...image !== void 0 ? { image } : { frame },
 				deviceId,
 				plane: "frame"

package/dist/pipeline-runner/index.mjs

@@ -1,8 +1,8 @@
-import { $ as _enum, A as pipelineRunnerCapability, B as BaseAddon, O as nodePin, W as createEvent, at as number, b as defineCustomActions, ct as string, et as array, ot as object, rt as lazy, tt as boolean, ut as EventCategory, v as customAction, z as errMsg } from "../dist-D16_dBsr.mjs";
+import { B as errMsg, G as createEvent, V as BaseAddon, dt as EventCategory, et as _enum, it as lazy, j as pipelineRunnerCapability, k as nodePin, lt as string, nt as boolean, ot as number, st as object, tt as array, x as defineCustomActions, y as customAction } from "../dist-BzVZ2I4P.mjs";
 import { n as profileForStreamId, t as isRemoteRestream } from "../remote-restream-BeHi78PZ.mjs";
 import { r as resolveHubHostname } from "../sheet-geometry-DcpuGTCm.mjs";
 import { t as isWorkerReply } from "../worker-protocol-CyVJTZEO.mjs";
-import { a as getStepDefinition } from "../step-definitions-DxAcpUV-.mjs";
+import { a as getStepDefinition } from "../step-definitions-B07M9qhj.mjs";
 import { fork } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import sharp from "sharp";
@@ -100,6 +100,109 @@ var pipelineRunnerBenchActions = defineCustomActions({
 	runSyntheticBench: customAction(RunSyntheticBenchInputSchema, RunSyntheticBenchResultSchema, { kind: "mutation" })
 });
 //#endregion
+//#region src/pipeline-runner/motion-settle-governor.ts
+/**
+* MotionSettleGovernor — decides WHEN the root-plane `package-detection` step
+* should run, so it is NOT executed on every frame.
+*
+* A delivered package is STATIONARY: per-frame inference on it is wasted cost.
+* The interesting moments are the EDGES — someone just set a parcel down, or
+* just picked one up — which coincide with motion in the package zone
+* SETTLING (transitioning from moving to still). This governor fires:
+*
+*   - on a **settle edge**: motion was observed, then has been absent for
+*     `settleMs` (kills flicker between motion frames and the "bag briefly
+*     set down then snatched back" case), and
+*   - on a **low-cadence safety poll** (`pollIntervalMs`, ~30–60s): a
+*     backstop so a delivery whose motion was never observed (a session-gap
+*     camera that only decodes intermittently) is still eventually caught.
+*
+* Pure logic with an injected clock (every method takes `now`), mirroring
+* `FrameGovernor` / `recomputeGovernor(now)` — no timers, no `Date.now()`
+* inside, fully unit-testable. Per-device state lives in a Map; the caller
+* consults it only while the step is enabled and calls `forget()` on detach.
+*
+* NOTE: today `motionInZone` is the whole-frame analyzer motion signal the
+* runner already tracks (`lastAnalyzerDetected`). Scoping it to the package
+* zone specifically (intersecting motion regions with the `package`-stage
+* zones) is a refinement that lands with the crop-zone frame-prep follow-up,
+* where the package zones first become available at the frame layer. The
+* governor contract does not change when that happens — only the boolean the
+* caller feeds it.
+*
+* See docs/superpowers/specs/2026-07-17-package-zones-design.md
+* (ADDENDUM 2026-07-17 — motion-settle trigger).
+*/
+/** The step id (`PipelineStepInput.addonId`) the governor gates. */
+var PACKAGE_DETECTION_STEP_ID = "package-detection";
+var DEFAULT_MOTION_SETTLE_CONFIG = {
+	settleMs: 3e3,
+	pollIntervalMs: 45e3
+};
+var INITIAL_STATE = {
+	lastMotionAt: null,
+	armed: false,
+	lastRunAt: Number.NEGATIVE_INFINITY
+};
+var NO_RUN = {
+	run: false,
+	reason: null
+};
+var MotionSettleGovernor = class {
+	config;
+	state = /* @__PURE__ */ new Map();
+	constructor(config = DEFAULT_MOTION_SETTLE_CONFIG) {
+		this.config = config;
+	}
+	/**
+	* Decide whether `package-detection` runs for this device this frame, and
+	* advance the per-device state immutably. Never throws.
+	*/
+	evaluate(sample) {
+		const prev = this.state.get(sample.deviceId) ?? INITIAL_STATE;
+		const lastMotionAt = sample.motionInZone ? sample.now : prev.lastMotionAt;
+		const armed = sample.motionInZone ? true : prev.armed;
+		const settleReady = armed && !sample.motionInZone && lastMotionAt !== null && sample.now - lastMotionAt >= this.config.settleMs;
+		const pollReady = sample.now - prev.lastRunAt >= this.config.pollIntervalMs;
+		if (settleReady) {
+			this.state.set(sample.deviceId, {
+				lastMotionAt,
+				armed: false,
+				lastRunAt: sample.now
+			});
+			return {
+				run: true,
+				reason: "settle"
+			};
+		}
+		if (pollReady) {
+			this.state.set(sample.deviceId, {
+				lastMotionAt,
+				armed,
+				lastRunAt: sample.now
+			});
+			return {
+				run: true,
+				reason: "poll"
+			};
+		}
+		this.state.set(sample.deviceId, {
+			lastMotionAt,
+			armed,
+			lastRunAt: prev.lastRunAt
+		});
+		return NO_RUN;
+	}
+	/** Drop a device's state (call on detach / step-disable) to avoid a leak. */
+	forget(deviceId) {
+		this.state.delete(deviceId);
+	}
+	/** Clear all state (e.g. runner teardown). */
+	reset() {
+		this.state.clear();
+	}
+};
+//#endregion
 //#region src/pipeline-runner/frame-governor.ts
 var FrameGovernor = class {
 	config;
@@ -2395,6 +2498,13 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	*  only (otherwise we'd emit on every analyzer frame). */
 	lastAnalyzerDetected = /* @__PURE__ */ new Map();
 	/**
+	* Gates the root-plane `package-detection` step to motion-settle edges +
+	* a low-cadence safety poll instead of every frame (packages are
+	* stationary — per-frame parcel inference is wasted cost). Consulted in
+	* `runInference` only when the step is enabled; state dropped on detach.
+	*/
+	packageGovernor = new MotionSettleGovernor();
+	/**
 	* Last positive motion timestamp per device — preserved across the
 	* OFF transition so the motion runtime-state slice keeps a stable
 	* `lastDetectedAt` after the cooldown closes the phase. Cleared on
@@ -2578,6 +2688,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			this.unsubMotionEvents = null;
 		}
 		this.lastAnalyzerDetected.clear();
+		this.packageGovernor.reset();
 		for (const deviceId of [...this.onboardAnalyzerTeardownTimers.keys(), ...this.onboardAnalyzerSubs.keys()]) this.clearOnboardAnalyzer(deviceId);
 		if (this.runner) {
 			this.runner.stop();
@@ -3191,6 +3302,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		this.lastMotionFrameAt.delete(deviceId);
 		this.lastDecodeUnexpectedEndAt.delete(deviceId);
 		this.thumbSampler?.forget(deviceId);
+		this.packageGovernor.forget(deviceId);
 		this.attached.delete(deviceId);
 		this.lastMotionAt.delete(deviceId);
 		this.lastEmittedCameraMetrics.delete(deviceId);
@@ -3609,6 +3721,17 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			return null;
 		}
 		if (steps.length === 0) return null;
+		let dispatchSteps = steps;
+		if (steps.some((s) => s.addonId === "package-detection" && s.enabled !== false)) {
+			if (!this.packageGovernor.evaluate({
+				deviceId,
+				motionInZone: this.lastAnalyzerDetected.get(deviceId) ?? false,
+				now: Date.now()
+			}).run) {
+				dispatchSteps = steps.filter((s) => s.addonId !== PACKAGE_DETECTION_STEP_ID);
+				if (dispatchSteps.length === 0) return null;
+			}
+		}
 		let image;
 		if (!this.executorCoLocated()) {
 			if (frame.format === "rgb") try {
@@ -3623,7 +3746,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		}
 		try {
 			return await api.pipelineExecutor.runPipeline.mutate({
-				steps: [...steps],
+				steps: [...dispatchSteps],
 				...image !== void 0 ? { image } : { frame },
 				deviceId,
 				plane: "frame"

package/dist/recorder/index.js

@@ -1,5 +1,5 @@
 const require_chunk = require("../chunk-D6vf50IK.js");
-const require_dist = require("../dist-p_JqOxtk.js");
+const require_dist = require("../dist-B2jTt7Lq.js");
 const require_sheet_geometry = require("../sheet-geometry-BR-ip0CP.js");
 const require_model_download_service_Cp9f4dk6 = require("../model-download-service-Cp9f4dk6-Dv-oFwjN.js");
 let node_child_process = require("node:child_process");
@@ -1005,6 +1005,34 @@ function segmentsByLocation(rows) {
 	return out;
 }
 /**
+* Evict a set of victim segments through the SegmentStore, grouped by their
+* storage location, and return the reclaimed bytes + deleted-bucket count.
+* Per-location isolated: one location's evict failure is logged and never aborts
+* the others. Shared by `pruneFootage` (retention) and `deleteFootprint`
+* (manual).
+*/
+async function evictVictims(deps, deviceId, victims) {
+	let reclaimedBytes = 0;
+	let deletedBuckets = 0;
+	for (const [locationId, locVictims] of segmentsByLocation(victims)) try {
+		const freed = await deps.segmentStore.evict(locationId, locVictims);
+		reclaimedBytes += freed;
+		if (freed > 0) deletedBuckets += locVictims.length;
+	} catch (err) {
+		deps.logger.warn("recorder evict failed for location", {
+			tags: { deviceId },
+			meta: {
+				locationId,
+				error: require_dist.errMsg(err)
+			}
+		});
+	}
+	return {
+		reclaimedBytes,
+		deletedBuckets
+	};
+}
+/**
 * Build the `IRecordingProvider`. The provider is a thin façade over the v2
 * core; all storage I/O flows through the injected deps.
 */
@@ -1101,37 +1129,63 @@ function buildRecordingProvider(deps) {
 		rescanStorage: async ({ deviceId }) => {
 			const locations = await deps.refreshLocations();
 			await deps.hydrateDevice(deviceId, locations);
-			return statusFor(deps, deviceId, await loadDeviceConfig(deps.configStore, deviceId));
+			const config = await loadDeviceConfig(deps.configStore, deviceId);
+			await deps.opsLog?.append({
+				op: "rescan",
+				reason: "operator",
+				deviceId,
+				itemsAffected: deps.index.segments(deviceId).length,
+				bytesReclaimed: 0,
+				detail: "rescanned footage from disk"
+			});
+			return statusFor(deps, deviceId, config);
 		},
-		pruneFootage: async ({ deviceId }) => {
+		pruneFootage: async ({ deviceId, reason }) => {
 			const retention = (await loadDeviceConfig(deps.configStore, deviceId)).retention;
 			const nowMs = Date.now();
-			const victims = selectEvictions(deps.index.segments(deviceId), {
+			const { reclaimedBytes, deletedBuckets } = await evictVictims(deps, deviceId, selectEvictions(deps.index.segments(deviceId), {
 				maxAgeDays: retention?.maxAgeDays,
 				maxSizeGb: retention?.maxSizeGb,
 				nowMs
+			}));
+			const floorMs = deps.index.accounting(deviceId).oldestMs ?? (retention?.maxAgeDays ? nowMs - retention.maxAgeDays * DAY_MS : null);
+			const opReason = reason ?? "retention";
+			await deps.opsLog?.append({
+				op: "prune",
+				reason: opReason,
+				deviceId,
+				itemsAffected: deletedBuckets,
+				bytesReclaimed: reclaimedBytes,
+				detail: floorMs === null ? "no footage remaining" : `floor moved to ${floorMs}`
+			});
+			return {
+				floorMs,
+				deletedBuckets,
+				reclaimedBytes
+			};
+		},
+		deleteFootprint: async ({ deviceId, fromMs, toMs }) => {
+			const lo = fromMs ?? Number.NEGATIVE_INFINITY;
+			const hi = toMs ?? Number.POSITIVE_INFINITY;
+			const { reclaimedBytes, deletedBuckets } = await evictVictims(deps, deviceId, deps.index.segments(deviceId).filter((s) => s.startMs < hi && s.startMs + s.durMs > lo));
+			const windowed = fromMs !== void 0 || toMs !== void 0;
+			await deps.opsLog?.append({
+				op: "manual-delete",
+				reason: "manual",
+				deviceId,
+				itemsAffected: deletedBuckets,
+				bytesReclaimed: reclaimedBytes,
+				detail: windowed ? `deleted footage in [${fromMs ?? "−∞"}, ${toMs ?? "+∞"})` : "deleted all footage"
 			});
-			let reclaimedBytes = 0;
-			let deletedBuckets = 0;
-			for (const [locationId, locVictims] of segmentsByLocation(victims)) try {
-				const freed = await deps.segmentStore.evict(locationId, locVictims);
-				reclaimedBytes += freed;
-				if (freed > 0) deletedBuckets += locVictims.length;
-			} catch (err) {
-				deps.logger.warn("recorder pruneFootage evict failed for location", {
-					tags: { deviceId },
-					meta: {
-						locationId,
-						error: require_dist.errMsg(err)
-					}
-				});
-			}
 			return {
-				floorMs: deps.index.accounting(deviceId).oldestMs ?? (retention?.maxAgeDays ? nowMs - retention.maxAgeDays * DAY_MS : null),
 				deletedBuckets,
 				reclaimedBytes
 			};
 		},
+		listOpsLog: async ({ deviceId, limit }) => await deps.opsLog?.list({
+			deviceId,
+			limit
+		}) ?? [],
 		getDeviceSettingsContribution: async ({ deviceId }) => {
 			if (deps.isCameraDevice && !await deps.isCameraDevice(deviceId)) return null;
 			return require_dist.hydrateSchema(buildRecordingDeviceSchema(), {});
@@ -1208,6 +1262,81 @@ async function listExportsFor(state, deviceId) {
 	return [...(await readExports(state)).values()].filter((r) => deviceId === void 0 || r.deviceId === deviceId).toSorted((a, b) => b.createdAt - a.createdAt);
 }
 //#endregion
+//#region src/recorder/addon/ops-log-store.ts
+/**
+* Recordings ops-log persistence for the recorder addon.
+*
+* A bounded, append-only audit ring lives in ONE addon-store blob (same
+* DurableState pattern as `export-store.ts` / `config-store.ts`) — no SQLite in
+* the recorder. The whole Zod-validated array round-trips on every read/write,
+* so no row is silently dropped on persist. Appends evict the oldest rows once
+* the ring exceeds its cap, so the blob stays bounded regardless of churn. A
+* corrupt blob reads back as EMPTY rather than crashing boot.
+*
+* Writes are BEST-EFFORT: `createRecordingOpsLogSink().append` never throws — a
+* failed audit write must not fail the operation it records.
+*/
+/** The addon-store key holding the bounded ops-log ring. */
+var RECORDING_OPS_LOG_KEY = "recordingOpsLog";
+/** Persisted shape: a flat array of ops-log rows (oldest-first on disk). */
+var RecordingOpsLogBlobSchema = require_dist.array(require_dist.OpsLogEntrySchema);
+/**
+* Append one row and persist, evicting the oldest rows so the ring never grows
+* past `maxEntries`. Validates at the boundary. Returns the stored row. Rows are
+* kept oldest-first on disk (the tail is newest); {@link listOpsLog} reverses.
+*/
+async function appendOpsLog(state, entry, maxEntries = 500) {
+	const validated = require_dist.OpsLogEntrySchema.parse(entry);
+	const next = [...await state.get(), validated];
+	const bounded = next.length > maxEntries ? next.slice(next.length - maxEntries) : next;
+	await state.set(bounded);
+	return validated;
+}
+/**
+* List ops-log rows newest-first, optionally scoped to one device, capped at
+* `limit` (default {@link OPS_LOG_DEFAULT_LIMIT}).
+*/
+async function listOpsLog(state, query) {
+	const rows = await state.get();
+	return (query.deviceId === void 0 ? rows : rows.filter((r) => r.deviceId === query.deviceId)).toSorted((a, b) => b.at - a.at).slice(0, query.limit ?? 200);
+}
+/**
+* Build the recorder's ops-log sink. `append` stamps `domain:'recording'`,
+* `nodeId`, `id` and `at`, then persists best-effort — a failed write is logged,
+* never thrown, so it cannot fail the operation being audited.
+*/
+function createRecordingOpsLogSink(deps) {
+	return {
+		append: async (input) => {
+			const entry = {
+				id: deps.newId(),
+				at: deps.now(),
+				domain: "recording",
+				op: input.op,
+				reason: input.reason,
+				deviceId: input.deviceId,
+				nodeId: deps.nodeId,
+				itemsAffected: input.itemsAffected,
+				bytesReclaimed: input.bytesReclaimed,
+				detail: input.detail ?? null,
+				actor: input.actor ?? "operator"
+			};
+			try {
+				await appendOpsLog(deps.state, entry, deps.maxEntries);
+			} catch (err) {
+				deps.logger.warn("recorder: ops-log append failed (best-effort)", {
+					tags: { deviceId: input.deviceId ?? void 0 },
+					meta: {
+						op: input.op,
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
+			}
+		},
+		list: (query) => listOpsLog(deps.state, query)
+	};
+}
+//#endregion
 //#region src/recorder/addon/export-ffmpeg-args.ts
 /** Widest [min,max] speed a single ffmpeg `atempo` filter accepts. Outside this
 *  band audio is dropped rather than chained (kept simple + predictable). */
@@ -3582,12 +3711,20 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 			}),
 			brokerCall: makeBrokerCall(brokerHandle)
 		});
+		const opsLog = createRecordingOpsLogSink({
+			state: this.opsLogStore(),
+			nodeId: this.nodeId,
+			now: () => Date.now(),
+			newId: () => (0, node_crypto.randomUUID)(),
+			logger: this.ctx.logger.child("ops-log")
+		});
 		const recordingDeps = {
 			index: this.index,
 			segmentStore: this.segmentStore,
 			nodeId: this.nodeId,
 			logger: this.ctx.logger,
 			configStore: this.configStore(),
+			opsLog,
 			locations: () => this.resolvedLocations,
 			refreshLocations: () => this.refreshLocations(),
 			capacity: (root) => this.locationCapacity(root),
@@ -3926,6 +4063,10 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 	exportsStore() {
 		return this.state(RECORDING_EXPORTS_KEY, RecordingExportsBlobSchema, {});
 	}
+	/** Durable handle over the bounded recordings ops-log ring. */
+	opsLogStore() {
+		return this.state(RECORDING_OPS_LOG_KEY, RecordingOpsLogBlobSchema, []);
+	}
 	/** Retention deps shared by the sweep and the download-complete hook. */
 	exportJanitorDeps() {
 		return {