@camstack/addon-pipeline 1.2.100 → 1.2.101

package/dist/recorder/index.mjs

@@ -1,6 +1,7 @@
-import { $ as recordingExportCapability, C as RecordingConfigSchema, Ct as nodePin, Et as selectAssignedProfileSlots, Ft as object, It as record, L as deriveRecordingMode, Lt as string, Pt as number, Q as recordingCapability, S as RECORDING_EXPORT_MAX_READ_BYTES, _t as DeviceType, ct as errMsg, f as EVENT_PAD_MS, it as storageEvictableCapability, kt as array, l as DEFAULT_EVENTS_BAND_BUFFER_SEC, m as ExportRecordSchema, mt as BaseAddon, nt as resolveRecordingProfiles, v as OpsLogEntrySchema, yt as hydrateSchema, zt as EventCategory } from "../dist-gXdWP96z.mjs";
+import { $ as recordingExportCapability, C as RecordingConfigSchema, Ct as nodePin, Et as selectAssignedProfileSlots, Ft as object, It as record, L as deriveRecordingMode, Lt as string, Pt as number, Q as recordingCapability, S as RECORDING_EXPORT_MAX_READ_BYTES, _t as DeviceType, ct as errMsg, f as EVENT_PAD_MS, it as storageEvictableCapability, l as DEFAULT_EVENTS_BAND_BUFFER_SEC, m as ExportRecordSchema, mt as BaseAddon, nt as resolveRecordingProfiles, v as OpsLogEntrySchema, yt as hydrateSchema, zt as EventCategory } from "../dist-gXdWP96z.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { n as createFileDataPlaneHandler, s as parseRangeHeader, t as contentTypeFor } from "../addon-utils-A2S9D7pu.mjs";
+import { n as RowMapStore, t as retireRootKeys } from "../retire-root-keys-DMolfhsP.mjs";
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import path from "node:path";
@@ -2480,70 +2481,75 @@ var CalendarIndex = class {
 //#endregion
 //#region src/recorder/addon/config-store.ts
 /**
-* Per-device recording-config persistence for the recorder addon.
-*
-* Every camera's `RecordingConfig` lives in ONE addon-store blob keyed by
-* (stringified) numeric deviceId — enumerable for boot hydrate (so the addon
-* knows which devices have persisted footage to index without scanning every
-* device store). The whole Zod-validated blob round-trips on every read/write
-* via a {@link DurableState} handle, so no per-device field can be silently
-* dropped on persist. A corrupt blob reads back as EMPTY rather than crashing
-* boot.
-*
-* P3b settings-API migration: the functions here consume the durable handle
-* directly — in production the recorder addon builds it via the sanctioned
-* `BaseAddon.state()` (retry budget + validated fallback + parse-warning
-* logging); {@link recordingConfigsState} adapts a raw store slice for test
-* fakes. Same store key, same persisted blob shape as before.
-*
-* `bands` is the ONLY authored recording intent (the legacy
-* mode/schedules/triggers/rules authoring surface was retired 2026-07-30); on
-* save `mode` is stamped as their derived summary for cheap consumers.
-*/
-/** The addon-store key holding the deviceId → RecordingConfig map. */
-var RECORDING_CONFIGS_KEY = "recordingConfigs";
-/**
-* Persisted shape: stringified numeric deviceId → full RecordingConfig.
-*
-* READ is forgiving where the wire contract is strict: `RecordingConfigSchema`
-* rejects unknown keys so a stale caller fails loudly, but a blob written by an
-* older build may still carry retired keys — and one unparseable device would
-* take the WHOLE blob down to the empty fallback (= every camera silently
-* unconfigured). `.strip()` drops them instead.
-*/
-var RecordingConfigsBlobSchema = record(string(), RecordingConfigSchema.strip());
+* @durable class=config owner=recorder
+*   write="one row per camera, written by `saveDeviceConfig` (the `recording` cap's
+*     setConfig / band authoring) — the only writer"
+*   retention="none by age. A row goes only when the operator deletes the camera's
+*     configuration; an unconfigured camera has no row and reads as DEFAULT_DEVICE_CONFIG"
+*/
+var RECORDING_CONFIGS_COLLECTION = "recorder:recording-configs";
+var RECORDING_CONFIGS_SPEC = {
+	collection: RECORDING_CONFIGS_COLLECTION,
+	schema: RecordingConfigSchema.strip(),
+	columns: [
+		{
+			name: "deviceId",
+			type: "INTEGER",
+			notNull: true
+		},
+		{
+			name: "enabled",
+			type: "BOOLEAN",
+			notNull: true
+		},
+		{
+			name: "mode",
+			type: "TEXT"
+		}
+	],
+	project: (key, value) => ({
+		deviceId: Number(key),
+		enabled: value.enabled,
+		mode: value.mode ?? null
+	}),
+	deviceIdColumn: "deviceId",
+	loadLimit: 2e4
+};
 /** Cold-start default for a camera that has never been configured: disabled, no bands. */
 var DEFAULT_DEVICE_CONFIG = {
 	enabled: false,
 	bands: []
 };
-function serialize$1(map) {
-	const out = {};
-	for (const [id, config] of map) out[String(id)] = config;
-	return out;
+/** Build the handle. `declare()` MUST run once at boot before any read/write. */
+function recordingConfigsState(store, logger) {
+	return new RowMapStore({
+		spec: RECORDING_CONFIGS_SPEC,
+		store,
+		logger
+	});
 }
 /** Read every persisted device config, keyed by numeric deviceId. */
 async function readDeviceConfigs(state) {
-	const blob = await state.get();
+	const rows = await state.readAll();
 	const map = /* @__PURE__ */ new Map();
-	for (const [key, config] of Object.entries(blob)) {
+	for (const [key, config] of rows) {
 		const id = Number(key);
 		if (Number.isInteger(id)) map.set(id, config);
 	}
 	return map;
 }
 /**
-* The persisted config for a device — `bands` is always materialized (the
-* schema defaults it to `[]`). An unconfigured device returns
+* The persisted config for a device — ONE keyed row read. `bands` is always
+* materialized (the schema defaults it to `[]`). An unconfigured device returns
 * {@link DEFAULT_DEVICE_CONFIG}.
 */
 async function loadDeviceConfig(state, deviceId) {
-	return (await readDeviceConfigs(state)).get(deviceId) ?? DEFAULT_DEVICE_CONFIG;
+	return await state.read(String(deviceId)) ?? DEFAULT_DEVICE_CONFIG;
 }
 /**
 * The devices whose stored config claims to record (`enabled` + a non-`off`
 * derived `mode`) but has no band left — the one shape this store cannot
-* repair. It can only come from a pre-retirement blob whose legacy authoring
+* repair. It can only come from a pre-retirement config whose legacy authoring
 * fields were stripped on read: the camera records NOTHING until its bands are
 * re-authored, so the recorder shouts about it once at boot
 * ({@link warnLostBands}) instead of failing silently.
@@ -2560,7 +2566,7 @@ async function warnLostBands(state, logger) {
 	logger.warn(`recording config: device(s) ${lost.join(", ")} claim a recording mode but have NO bands — a pre-retirement config that lost its legacy authoring fields. Nothing is recorded for them until their bands are re-authored.`);
 }
 /**
-* Persist (insert or replace) a device's config. Validates against
+* Persist (insert or replace) a device's config — ONE row. Validates against
 * `RecordingConfigSchema` at the boundary (untrusted cap input). Returns the
 * validated config that was persisted.
 */
@@ -2570,9 +2576,7 @@ async function saveDeviceConfig(state, deviceId, config) {
 		...parsed,
 		mode: parsed.enabled ? activeModeForConfig(parsed) : "off"
 	};
-	const map = await readDeviceConfigs(state);
-	map.set(deviceId, validated);
-	await state.set(serialize$1(map));
+	await state.write(String(deviceId), validated);
 	return validated;
 }
 /**
@@ -2939,61 +2943,122 @@ function buildExportArgs(input) {
 /**
 * Recording-export persistence for the recorder addon.
 *
-* Every export job/history row lives in ONE addon-store blob keyed by export
-* id. The whole Zod-validated blob round-trips on every read/write via a
-* {@link DurableState} handle (same pattern as `config-store.ts`), so no field
-* is silently dropped on persist. History rows are never removed by the system
-* (audit) — `deleteExport`/janitor flip `state` and clear the file, keeping the
-* row. A corrupt blob reads back as EMPTY rather than crashing boot.
-*/
-/**
-* The addon-store key holding the exportId → ExportRecord map. Production
-* builds the durable handle via `BaseAddon.state(RECORDING_EXPORTS_KEY,
-* RecordingExportsBlobSchema, {})`; the pure functions below take that handle,
-* so this module never touches the @internal raw addon-store primitive.
-*/
-var RECORDING_EXPORTS_KEY = "recordingExports";
-/** Persisted shape: export id → full ExportRecord. */
-var RecordingExportsBlobSchema = record(string(), ExportRecordSchema);
+* ONE ROW PER EXPORT in `recorder:exports`, through {@link RowMapStore}. History
+* rows are never removed by the system (audit) — `deleteExport` / the janitor
+* flip `state` and clear the file, keeping the row.
+*
+* ## What this replaced, and why it mattered here more than anywhere
+*
+* Every job used to live in one key of the recorder's `addon-settings` / `root`
+* blob — 201 833 bytes on the reference hub, of which the export history was
+* 50 441. The engine patches `progressPct` roughly once a second for an
+* in-flight render, so moving one integer read, parsed, re-serialised and
+* rewrote 201 KB, per second.
+*
+* Worse than the cost was the CLOBBER. Both halves of a read-modify-write are
+* async, so two overlapping cycles read the same snapshot and the second `set`
+* discarded whatever the first added. On 2026-08-14 a `createExport` for camera
+* 615 landed between one progress patch's read and its write, the row was
+* erased, and the poll answered `unknown export "547ea182-…"`; the scheduler
+* read the vanished row as a failed render and re-queued forever. A per-row
+* upsert makes that class of loss unrepresentable — a write names ONE row.
+*
+* What is still needed is a per-ID serialiser: two patches to the SAME export
+* still read-modify-write the same row. That is what {@link serialize} bounds,
+* and it is now per (store, id) rather than per store, so two exports never
+* queue behind each other.
+*/
+/**
+* @durable class=ledger owner=recorder
+*   write="one row per export job, inserted by `createExport` and rewritten by the
+*     render engine's progress/state patches and by the download hook"
+*   retention="the SYSTEM never deletes a row — it is the export AUDIT. `deleteExport`
+*     and the janitor flip `state` to 'deleted'/'expired' and remove the FILE, keeping
+*     the row. `removeExport` exists for an operator-driven purge and nothing calls it
+*     on a schedule."
+*/
+var RECORDING_EXPORTS_COLLECTION = "recorder:exports";
+/**
+* Bound for the whole-history read. Explicit because `settings-store.query`
+* caps an unbounded read at 2 000 rows SILENTLY, and an export list that
+* silently loses its oldest half looks exactly like a purge.
+*/
+var RECORDING_EXPORTS_LIMIT = 2e4;
+var RECORDING_EXPORTS_SPEC = {
+	collection: RECORDING_EXPORTS_COLLECTION,
+	schema: ExportRecordSchema,
+	columns: [
+		{
+			name: "deviceId",
+			type: "INTEGER",
+			notNull: true
+		},
+		{
+			name: "createdAt",
+			type: "INTEGER",
+			notNull: true
+		},
+		{
+			name: "state",
+			type: "TEXT",
+			notNull: true
+		}
+	],
+	indexes: [{
+		name: "idx_recorder_exports_device",
+		columns: ["deviceId"]
+	}, {
+		name: "idx_recorder_exports_created",
+		columns: ["createdAt"]
+	}],
+	project: (_key, value) => ({
+		deviceId: value.deviceId,
+		createdAt: value.createdAt,
+		state: value.state
+	}),
+	deviceIdColumn: "deviceId",
+	loadLimit: RECORDING_EXPORTS_LIMIT
+};
+/** Build the handle. `declare()` MUST run once at boot before any read/write. */
+function recordingExportsState(store, logger) {
+	return new RowMapStore({
+		spec: RECORDING_EXPORTS_SPEC,
+		store,
+		logger
+	});
+}
 /**
-* One in-flight mutation chain per durable handle.
+* One in-flight mutation chain per (handle, export id).
 *
-* EVERY mutation here is a read-modify-write of the SAME blob, and both halves
-* are async — so two overlapping cycles read the same snapshot and the second
-* `set` discards whatever the first one added. Last writer wins, silently.
+* A row upsert removed the cross-export clobber; it does not order two
+* read-modify-writes of the SAME row. `patchExport` reads the row, merges and
+* writes — so two overlapping patches on one export still race, and the loser's
+* fields vanish. Serialising per ID keeps those pairs atomic while leaving
+* unrelated exports fully concurrent (the old chain was per HANDLE, so a slow
+* patch queued every other export behind it).
 *
-* That is not a hypothetical. The engine patches `progressPct` roughly once a
-* second for an in-flight render, unawaited; on 2026-08-14 a `createExport` for
-* camera 615 landed between one such patch's read and its write, the row was
-* erased, and five seconds later the poll answered `unknown export
-* "547ea182-…"`. The camera's whole night was lost to it — the scheduler read a
-* vanished row as a failed render and re-queued, forever.
-*
-* Serialising per handle is the smallest fix that makes the loss impossible:
-* the cycles queue instead of interleaving, and the queue is per state object
-* so two recorders in one process never contend. A `WeakMap` keeps a disposed
-* handle collectable. Reads stay OUTSIDE the chain — a blob replacement is
-* atomic, so a reader always sees one consistent generation.
+* A `WeakMap` keyed by the handle keeps a disposed store collectable; the inner
+* map is keyed by export id.
 */
 var mutationChains = /* @__PURE__ */ new WeakMap();
-/** Run `work` after every mutation already queued for `state`, never before. */
-async function serialize(state, work) {
-	const next = (mutationChains.get(state) ?? Promise.resolve()).then(work, work);
-	mutationChains.set(state, next.catch(() => void 0));
+/** Run `work` after every mutation already queued for `(state, id)`, never before. */
+async function serialize(state, id, work) {
+	const existing = mutationChains.get(state);
+	const queued = existing ?? /* @__PURE__ */ new Map();
+	if (existing === void 0) mutationChains.set(state, queued);
+	const next = (queued.get(id) ?? Promise.resolve()).then(work, work);
+	const settled = next.catch(() => void 0);
+	queued.set(id, settled);
+	settled.then(() => {
+		if (queued.get(id) === settled) queued.delete(id);
+	});
 	return next;
 }
-/** Read every persisted export row, keyed by export id. */
-async function readExports(state) {
-	const blob = await state.get();
-	return new Map(Object.entries(blob));
-}
 /** Insert or replace one export row. Validates at the boundary. Returns it. */
 async function upsertExport(state, record) {
 	const validated = ExportRecordSchema.parse(record);
-	return serialize(state, async () => {
-		const map = await readExports(state);
-		map.set(validated.id, validated);
-		await state.set(Object.fromEntries(map));
+	return serialize(state, validated.id, async () => {
+		await state.write(validated.id, validated);
 		return validated;
 	});
 }
@@ -3002,28 +3067,37 @@ async function upsertExport(state, record) {
 * record, or null when the id is unknown.
 */
 async function patchExport(state, id, patch) {
-	return serialize(state, async () => {
-		const map = await readExports(state);
-		const existing = map.get(id);
-		if (!existing) return null;
+	return serialize(state, id, async () => {
+		const existing = await state.read(id);
+		if (existing === null) return null;
 		const merged = ExportRecordSchema.parse({
 			...existing,
 			...patch
 		});
-		map.set(id, merged);
-		await state.set(Object.fromEntries(map));
+		await state.write(id, merged);
 		return merged;
 	});
 }
-/** Read one export row by id, or null. */
+/** Read one export row by id — ONE keyed row read. */
 async function getExportRecord(state, id) {
-	return (await readExports(state)).get(id) ?? null;
+	return state.read(id);
 }
 /**
 * List export rows, newest-first, optionally scoped to one device.
+*
+* Scoped to a device this is an INDEXED query on the projected `deviceId`
+* column — not a parse of every export in the installation followed by a filter
+* in JS.
 */
 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);
+	return (await state.readWhere({
+		...deviceId === void 0 ? {} : { where: { deviceId } },
+		orderBy: {
+			field: "createdAt",
+			direction: "desc"
+		},
+		limit: RECORDING_EXPORTS_LIMIT
+	})).map((entry) => entry.value);
 }
 //#endregion
 //#region src/recorder/addon/spawn-failure.ts
@@ -4790,39 +4864,117 @@ function runFfmpeg(renderDeps, args, ext) {
 /**
 * 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.
+* ONE ROW PER OPERATION in `recorder:ops-log`, through {@link RowMapStore}. The
+* ring is still bounded — `maxEntries` newest rows survive — but the eviction
+* is now a single `DELETE … WHERE at BETWEEN`, and a listing is an indexed
+* `WHERE deviceId … ORDER BY at DESC LIMIT`.
+*
+* ## What this replaced
+*
+* The ring lived in ONE key of the recorder's `addon-settings` / `root` blob,
+* as a flat JSON array. On the reference hub it was 147 437 bytes of that row's
+* 201 833 — so appending one audit line read, parsed, re-serialised and rewrote
+* ~200 KB, and so did every unrelated reader of that row (`resolveConfig`,
+* `loadDeviceConfig`, the export progress patch). The ops log is the CHEAPEST
+* thing in the recorder and it was paying for the most expensive.
+*
+* Writes stay BEST-EFFORT: `createRecordingOpsLogSink().append` never throws —
+* a failed audit write must not fail the operation it records.
+*/
+/**
+* @durable class=audit owner=recorder
+*   write="one row per recordings operation (prune, evict, relocate, export, …), appended
+*     best-effort by `createRecordingOpsLogSink().append` — never read back by the system,
+*     only listed by an operator through the `recording.listOpsLog` cap method"
+*   retention="a bounded ring: every append trims to the newest OPS_LOG_RING_DEFAULT_MAX
+*     (500) rows with one `deleteWhere` on `at`. Rows tied on the cutoff millisecond
+*     survive, so the ring may hold a few MORE than the cap and never fewer."
+*/
+var RECORDING_OPS_LOG_COLLECTION = "recorder:ops-log";
+var RECORDING_OPS_LOG_SPEC = {
+	collection: RECORDING_OPS_LOG_COLLECTION,
+	schema: OpsLogEntrySchema,
+	columns: [{
+		name: "at",
+		type: "INTEGER",
+		notNull: true
+	}, {
+		name: "deviceId",
+		type: "INTEGER"
+	}],
+	indexes: [{
+		name: "idx_recorder_ops_log_at",
+		columns: ["at"]
+	}, {
+		name: "idx_recorder_ops_log_device",
+		columns: ["deviceId"]
+	}],
+	project: (_key, value) => ({
+		at: value.at,
+		deviceId: value.deviceId
+	}),
+	deviceIdColumn: "deviceId",
+	loadLimit: 2e4
+};
+/** Build the handle. `declare()` MUST run once at boot before any read/write. */
+function recordingOpsLogState(store, logger) {
+	return new RowMapStore({
+		spec: RECORDING_OPS_LOG_SPEC,
+		store,
+		logger
+	});
+}
+/**
+* Trim the ring to the newest `maxEntries` rows. Returns how many went.
+*
+* The cursor is the OLDEST row that must SURVIVE — offset `maxEntries - 1`
+* newest-first — and the delete is strictly older than it (`[0, at - 1]`).
 *
-* Writes are BEST-EFFORT: `createRecordingOpsLogSink().append` never throws — a
-* failed audit write must not fail the operation it records.
+* Strictly, because `whereBetween` is inclusive and the filter surface has no
+* `<`: including the cursor's own millisecond would take every row tied on it,
+* and a ring whose rows all shared one millisecond would be deleted whole.
+* Erring this way keeps a few EXTRA audit rows on a tie and never fewer than
+* the cap.
 */
-/** 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 = array(OpsLogEntrySchema);
+async function trimOpsLog(state, maxEntries = 500) {
+	if (await state.count() <= maxEntries) return 0;
+	const oldestKept = (await state.readWhere({
+		orderBy: {
+			field: "at",
+			direction: "desc"
+		},
+		limit: 1,
+		offset: maxEntries - 1
+	}))[0];
+	if (oldestKept === void 0) return 0;
+	return state.deleteWhere({ whereBetween: { at: [0, oldestKept.value.at - 1] } });
+}
 /**
-* 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.
+* Append one row and persist, then trim the ring. Validates at the boundary.
+* Returns the stored row.
 */
 async function appendOpsLog(state, entry, maxEntries = 500) {
 	const validated = OpsLogEntrySchema.parse(entry);
-	const next = [...await state.get(), validated];
-	const bounded = next.length > maxEntries ? next.slice(next.length - maxEntries) : next;
-	await state.set(bounded);
+	await state.write(validated.id, validated);
+	await trimOpsLog(state, maxEntries);
 	return validated;
 }
 /**
 * List ops-log rows newest-first, optionally scoped to one device, capped at
 * `limit` (default {@link OPS_LOG_DEFAULT_LIMIT}).
+*
+* Scoped to a device this is an INDEXED query, not a read of the whole ring
+* followed by a filter and a sort in JS.
 */
 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);
+	return (await state.readWhere({
+		...query.deviceId === void 0 ? {} : { where: { deviceId: query.deviceId } },
+		orderBy: {
+			field: "at",
+			direction: "desc"
+		},
+		limit: query.limit ?? 200
+	})).map((entry) => entry.value);
 }
 /**
 * Build the recorder's ops-log sink. `append` stamps `domain:'recording'`,
@@ -8090,6 +8242,25 @@ async function readLocationCapacity(root, statfs) {
 	}
 }
 //#endregion
+//#region src/recorder/addon/retired-root-keys.ts
+var RECORDER_RETIRED_ROOT_KEYS = [
+	{
+		key: "recordingOpsLog",
+		successor: RECORDING_OPS_LOG_COLLECTION,
+		reason: "the audit ring is one row per operation since the flatten; as a blob it was 147 KB of the 201 KB root row, re-parsed by every unrelated reader of that row"
+	},
+	{
+		key: "recordingExports",
+		successor: RECORDING_EXPORTS_COLLECTION,
+		reason: "one row per export job since the flatten; as a blob a once-a-second progress patch rewrote 201 KB, and an overlapping createExport erased the row (2026-08-14)"
+	},
+	{
+		key: "recordingConfigs",
+		successor: RECORDING_CONFIGS_COLLECTION,
+		reason: "one row per camera since the flatten; as a blob, asking what camera 617 records parsed every camera in the installation"
+	}
+];
+//#endregion
 //#region src/durable/durable-ledger.ts
 /** Default reseed cap — every current consumer's row set is installation-bounded. */
 var DEFAULT_LOAD_LIMIT = 1e5;
@@ -9653,6 +9824,8 @@ var RecorderV2Addon = class extends BaseAddon {
 			} });
 			return { providers: [] };
 		}
+		await this.declareRowCollections();
+		await this.purgeFlattenedSettingsKeys();
 		this.segmentHours = new SegmentHourLedger({
 			store: this.ctx.api.settingsStore,
 			logger: this.ctx.logger,
@@ -10621,17 +10794,52 @@ var RecorderV2Addon = class extends BaseAddon {
 			this.fullWalkInFlight = false;
 		}
 	}
+	/**
+	* Declare the three row collections that replaced the `recordingConfigs`,
+	* `recordingExports` and `recordingOpsLog` blob keys. Idempotent — a
+	* re-declaration of the same shape is a no-op in the engine.
+	*/
+	async declareRowCollections() {
+		await this.configStore().declare();
+		await this.exportsStore().declare();
+		await this.opsLogStore().declare();
+	}
+	/**
+	* Drop the flattened keys from `recorder:addon-settings` / `root`, each gated
+	* on its own successor collection being non-empty.
+	*
+	* `recordingPlacement` is NOT here: it stays a blob key. It is 1.4 KB of
+	* per-(camera, profile) assignments plus a handful of volume ids, written
+	* only when placement changes — and the row has to survive anyway, because it
+	* is where `BaseAddon.resolveConfig` reads the operator's config fields from.
+	* The problem was a 201 KB row, not a blob.
+	*
+	* Best-effort: a purge that throws must not take recording down. The keys are
+	* dead weight, not a fault.
+	*/
+	async purgeFlattenedSettingsKeys() {
+		try {
+			await retireRootKeys({
+				store: this.ctx.api.settingsStore,
+				addonId: RECORDER_ADDON_ID,
+				logger: this.ctx.logger,
+				specs: RECORDER_RETIRED_ROOT_KEYS
+			});
+		} catch (err) {
+			this.ctx.logger.warn("recorder: retiring the flattened settings keys failed", { meta: { error: errMsg(err) } });
+		}
+	}
 	configStore() {
-		return this.state(RECORDING_CONFIGS_KEY, RecordingConfigsBlobSchema, {});
+		return recordingConfigsState(this.ctx.api.settingsStore, this.ctx.logger);
 	}
 	/** Durable handle over the exportId→ExportRecord blob (same `BaseAddon.state()`
 	*  wrapper as the config store). */
 	exportsStore() {
-		return this.state(RECORDING_EXPORTS_KEY, RecordingExportsBlobSchema, {});
+		return recordingExportsState(this.ctx.api.settingsStore, this.ctx.logger);
 	}
 	/** Durable handle over the bounded recordings ops-log ring. */
 	opsLogStore() {
-		return this.state(RECORDING_OPS_LOG_KEY, RecordingOpsLogBlobSchema, []);
+		return recordingOpsLogState(this.ctx.api.settingsStore, this.ctx.logger);
 	}
 	/** Durable handle over the recorder-owned placement blob (assignments + volume ids). */
 	placementStore() {