@camstack/system 1.2.155 → 1.2.157

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { St as storageMigrationCapability, Yt as parseJsonObject, b as StorageMigrationJobSchema, kt as BaseAddon, xt as storageCapability, y as StorageLocationTypeSchema, yt as settingsStoreCapability } from "../../dist-D_NyUV6Y.mjs";
+import { St as storageMigrationCapability, Yt as parseJsonObject, b as StorageMigrationJobSchema, kt as BaseAddon, xt as storageCapability, y as StorageLocationTypeSchema, yt as settingsStoreCapability } from "../../dist-LvKus-mT.mjs";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path$1 from "node:path";
@@ -229,8 +229,41 @@ function mapRowToLocation(row) {
 var STORAGE_CLASSES = [
 	"recordings",
 	"recordingsLow",
-	"eventMedia"
+	"eventMedia",
+	"backups",
+	"galleryMedia"
 ];
+/** The classes footage/media movers actually own. Everything else is planned,
+*  reported and refused rather than silently accepted. */
+var MOVER_CLASSES = [
+	"recordings",
+	"recordingsLow",
+	"eventMedia",
+	"galleryMedia"
+];
+/**
+* Classes that can never span two locations at once.
+*
+* `galleryMedia` is `cardinality: 'single'` and `upsertLocation` refuses a
+* second instance of a single type, so the "both locations are first-class for
+* reads while the past drains" transient the non-blocking mode rests on is not
+* merely undesirable there — it is not constructible. Its move is therefore
+* stop-the-world, always. That is acceptable only because the enrolled gallery
+* is a few KB per sample, and it is said here rather than discovered.
+*/
+var BLOCKING_ONLY_CLASSES = ["galleryMedia"];
+/**
+* Location types whose volume `galleryMedia` must NEVER land on.
+*
+* Verbatim from its own declaration: *"Deliberately NOT on the recordings
+* volume: these images survive every retention sweep, so they must also survive
+* a footage wipe, a quota eviction and a recordings disk swap."* A planner that
+* accepted `galleryMedia` → the recordings volume would let an operator destroy
+* the enrolment gallery on the next disk swap, months later, with no visible
+* link back to this decision.
+*/
+var GALLERY_FORBIDDEN_NEIGHBOUR_TYPES = ["recordings", "recordingsLow"];
+var MOVE_LANES = ["media", "footage"];
 var PARTICIPANTS = [
 	"pipeline",
 	"recorder",
@@ -255,7 +288,9 @@ var StorageMigrationCoordinator = class {
 		this.deps = deps;
 	}
 	async plan(input) {
+		const mode = input.mode ?? "blocking";
 		const moves = [];
+		const findings = [];
 		for (const storageClass of STORAGE_CLASSES) {
 			const targetId = input.destinations[storageClass];
 			if (targetId === void 0) continue;
@@ -265,6 +300,9 @@ var StorageMigrationCoordinator = class {
 			if (!target) throw new Error(`Storage location "${targetId}" not found`);
 			if (target.type !== storageClass) throw new Error(`Storage location "${targetId}" is type "${target.type}", expected "${storageClass}"`);
 			if (source.id === target.id) throw new Error(`Storage location "${targetId}" is already the "${storageClass}" default`);
+			if (!MOVER_CLASSES.includes(storageClass)) throw new Error(`No mover owns "${storageClass}" — the migration can repoint its default but cannot move its bytes. Move it by hand, then repoint the default with upsertLocation.`);
+			if (mode === "nonBlocking" && BLOCKING_ONLY_CLASSES.includes(storageClass)) throw new Error(`"${storageClass}" is a single-cardinality storage class: it can never exist at two locations at once, so it cannot be repointed first and drained behind. Use mode "blocking".`);
+			await this.refuseGalleryOntoRecordingsVolume(storageClass, targetId);
 			moves.push({
 				storageClass,
 				fromLocationId: source.id,
@@ -273,17 +311,79 @@ var StorageMigrationCoordinator = class {
 				state: null,
 				error: null
 			});
+			if (BLOCKING_ONLY_CLASSES.includes(storageClass)) findings.push({
+				code: "blockingOnly",
+				storageClass,
+				message: `"${storageClass}" is single-cardinality: this move is stop-the-world for its whole duration, in every mode. It is a few KB per enrolled sample, which is why that is acceptable.`
+			});
+			findings.push(...await this.deviceFindings(storageClass, source.id, target.id));
 		}
 		if (moves.length === 0) throw new Error("select at least one storage class");
+		if (moves.some((move) => move.storageClass === "eventMedia")) {
+			const unstamped = await this.deps.participants.analytics.countUnstamped();
+			if (unstamped.total > 0) {
+				if (mode === "nonBlocking") throw new Error(`${unstamped.total.toString()} event-media row(s) still carry no locationId (${unstamped.media.toString()} media, ${unstamped.retrainFrames.toString()} retrain frames). A non-blocking cutover would silently orphan them. Run the seal first: pipelineAnalytics.relocateMedia({ mode: "seal", toLocationId: "${this.deps.locations.getDefaultLocation("eventMedia")?.id ?? "eventMedia"}" }).`);
+				findings.push({
+					code: "unstampedEventMediaRows",
+					storageClass: "eventMedia",
+					message: `${unstamped.total.toString()} event-media row(s) carry no locationId. This blocking migration stamps them as it moves them, but a non-blocking one would be refused until a seal pass drives the count to zero.`
+				});
+			}
+		}
 		return {
 			destinations: input.destinations,
+			mode,
 			moves: moves.map(({ storageClass, fromLocationId, toLocationId }) => ({
 				storageClass,
 				fromLocationId,
 				toLocationId
-			}))
+			})),
+			findings
 		};
 	}
+	/**
+	* HARD refusal: `galleryMedia` onto a volume a recordings class lives on.
+	*
+	* This is the one same-device case that is a refusal rather than a finding,
+	* because its consequence is silent and arrives months later — the gallery is
+	* wiped by the next footage wipe, quota eviction or recordings disk swap, and
+	* nothing at that moment points back at this migration.
+	*
+	* It can only refuse what it can SEE. `deviceKeyOf` is a realpath, so it
+	* catches a symlink, a bind mount and a literally-shared directory — and
+	* misses two distinct directories on one filesystem, and any location pinned
+	* to another node. Those come back `null`/distinct and produce a
+	* `deviceIdentityUnknown` finding instead.
+	*/
+	async refuseGalleryOntoRecordingsVolume(storageClass, targetId) {
+		if (storageClass !== "galleryMedia") return;
+		const targetKey = await this.deviceKey(targetId);
+		if (targetKey === null) return;
+		for (const type of GALLERY_FORBIDDEN_NEIGHBOUR_TYPES) for (const neighbour of this.deps.locations.listLocations({ type })) {
+			if (await this.deviceKey(neighbour.id) !== targetKey) continue;
+			throw new Error(`Storage location "${targetId}" shares a volume with "${neighbour.id}" (${type}). galleryMedia is deliberately NOT on the recordings volume: enrolment images survive every retention sweep, so they must also survive a footage wipe, a quota eviction and a recordings disk swap. Choose a destination on another volume.`);
+		}
+	}
+	/** Same-device observations that are reported, not refused. */
+	async deviceFindings(storageClass, sourceId, targetId) {
+		if (this.deps.deviceKeyOf === void 0) return [];
+		const [sourceKey, targetKey] = await Promise.all([this.deviceKey(sourceId), this.deviceKey(targetId)]);
+		if (sourceKey === null || targetKey === null) return [{
+			code: "deviceIdentityUnknown",
+			storageClass,
+			message: `Could not establish whether "${sourceId}" and "${targetId}" are on the same device (a location with no basePath, or pinned to another node — the realpath would have to be taken there). Note also that this check is PATH identity, not st_dev: two distinct directories on one filesystem are never detected as one device.`
+		}];
+		if (sourceKey !== targetKey) return [];
+		return [{
+			code: "sharesDeviceWithSource",
+			storageClass,
+			message: `"${targetId}" resolves to the same path as "${sourceId}". The move will re-stamp rows rather than copy bytes, and it buys no redundancy — both "locations" are one disk.`
+		}];
+	}
+	async deviceKey(locationId) {
+		if (this.deps.deviceKeyOf === void 0) return null;
+		return this.deps.deviceKeyOf(locationId);
+	}
 	async start(input) {
 		if (this.startReserved) throw new Error("storage migration is already active");
 		this.startReserved = true;
@@ -300,6 +400,7 @@ var StorageMigrationCoordinator = class {
 			const job = {
 				jobId: this.deps.newId(),
 				phase: "planning",
+				mode: plan.mode,
 				destinations: input.destinations,
 				throttleMbps: input.throttleMbps ?? 40,
 				moves: plan.moves.map((move) => ({
@@ -317,8 +418,8 @@ var StorageMigrationCoordinator = class {
 				finishedAt: null,
 				error: null
 			};
-			this.active = job;
 			await this.persist(job);
+			this.active = job;
 			this.runPromise = this.run(job);
 			this.runPromise;
 			return job.jobId;
@@ -333,7 +434,8 @@ var StorageMigrationCoordinator = class {
 	}
 	async cancel(jobId) {
 		const job = await this.status(jobId);
-		if (!job || isTerminal(job) || job.repointed) return false;
+		const cutoverInFlight = job !== null && job.repointed && (job.phase === "refreshing" || job.phase === "resuming");
+		if (!job || isTerminal(job) || cutoverInFlight) return false;
 		job.cancelRequested = true;
 		await this.persist(job);
 		await Promise.all(job.moves.filter((move) => move.moverJobId !== null).map((move) => this.cancelMove(move)));
@@ -364,7 +466,7 @@ var StorageMigrationCoordinator = class {
 		job.pauseLeaseId ??= this.deps.newId();
 		if (job.repointed && job.phase === "resuming") job.phase = "refreshing";
 		await this.persist(job);
-		try {
+		if (!runsUnleased(job)) try {
 			await this.pauseParticipants(job, true);
 		} catch (err) {
 			job.error = err instanceof Error ? err.message : String(err);
@@ -376,14 +478,34 @@ var StorageMigrationCoordinator = class {
 			this.runPromise;
 		}
 	}
+	/**
+	* The state machine. Both modes run the SAME phase handlers; only the order
+	* differs, which is the whole of the non-blocking design — no second mover,
+	* no parallel code path, nothing that can drift between the two.
+	*
+	*   blocking:    planning → pausing → moving → verifying → repointing →
+	*                refreshing → resuming → done
+	*   nonBlocking: planning → sealing → pausing → repointing → refreshing →
+	*                resuming → draining → verifying → done
+	*
+	* Written as a straight-line sequence of `if (phase === X)` blocks so boot
+	* recovery re-enters at whatever phase the durable record says, exactly as
+	* before.
+	*/
 	async run(job) {
+		const nonBlocking = job.mode === "nonBlocking";
 		try {
-			if (job.phase === "planning") await this.setPhase(job, "pausing");
+			if (job.phase === "planning") await this.setPhase(job, nonBlocking ? "sealing" : "pausing");
+			if (job.phase === "sealing") {
+				await this.sealEventMedia(job);
+				if (job.cancelRequested) return this.finishCancelled(job);
+				await this.setPhase(job, "pausing");
+			}
 			if (job.phase === "pausing") {
 				job.pauseLeaseId ??= job.jobId;
 				await this.pauseParticipants(job);
 				if (job.cancelRequested) return this.finishCancelled(job);
-				await this.setPhase(job, "moving");
+				await this.setPhase(job, nonBlocking ? "repointing" : "moving");
 			}
 			if (job.phase === "moving") {
 				await this.startOrResumeMoves(job);
@@ -391,7 +513,7 @@ var StorageMigrationCoordinator = class {
 				if (job.cancelRequested) return this.finishCancelled(job);
 				await this.setPhase(job, "verifying");
 			}
-			if (job.phase === "verifying") {
+			if (job.phase === "verifying" && !nonBlocking) {
 				await this.verifyMoves(job);
 				if (job.cancelRequested) return this.finishCancelled(job);
 				await this.setPhase(job, "repointing");
@@ -404,17 +526,28 @@ var StorageMigrationCoordinator = class {
 			}
 			if (job.phase === "refreshing") {
 				const leaseId = requireLease(job);
-				if (job.moves.some((move) => move.storageClass !== "eventMedia")) await this.deps.participants.recorder.refresh(leaseId);
-				if (job.moves.some((move) => move.storageClass === "eventMedia")) await this.deps.participants.analytics.refresh(leaseId);
+				if (job.moves.some((move) => laneOf(move.storageClass) === "footage")) await this.deps.participants.recorder.refresh(leaseId);
+				if (job.moves.some((move) => laneOf(move.storageClass) === "media")) await this.deps.participants.analytics.refresh(leaseId);
 				await this.setPhase(job, "resuming");
 			}
 			if (job.phase === "resuming") {
 				await this.resumeParticipants(job);
+				await this.setPhase(job, nonBlocking ? "draining" : "done");
+			}
+			if (job.phase === "draining") {
+				await this.startOrResumeMoves(job);
+				await this.waitForMoves(job);
+				if (job.cancelRequested) return this.finishCancelled(job);
+				await this.setPhase(job, "verifying");
+			}
+			if (job.phase === "verifying" && nonBlocking) {
+				await this.verifyMoves(job);
+				if (job.cancelRequested) return this.finishCancelled(job);
 				await this.setPhase(job, "done");
 			}
 		} catch (err) {
 			job.error = err instanceof Error ? err.message : String(err);
-			if (job.repointed) {
+			if (job.repointed && job.pausedParticipants.length > 0) {
 				job.phase = "refreshing";
 				job.finishedAt = null;
 				await this.persist(job);
@@ -462,21 +595,28 @@ var StorageMigrationCoordinator = class {
 			} catch {}
 		}
 	}
+	/**
+	* Start whatever is startable, honouring the ONE constraint the engines
+	* impose: each is single-flight.
+	*
+	* Two lanes — the recorder's footage engine and post-analysis's media engine
+	* — run in parallel with each other and strictly FIFO within themselves.
+	* `galleryMedia` shares the media lane with `eventMedia` because it shares
+	* the same `MediaRelocateEngine`, which refuses a second running job; starting
+	* both would fail the second one instantly.
+	*/
 	async startOrResumeMoves(job) {
 		if (job.cancelRequested) return;
-		const mediaMove = job.moves.find((move) => move.storageClass === "eventMedia");
-		if (mediaMove?.moverJobId === null) {
-			mediaMove.moverJobId = await this.startMove(job, mediaMove);
-			await this.persist(job);
-		}
-		const footageMoves = job.moves.filter((move) => move.storageClass !== "eventMedia");
-		for (let index = 0; index < footageMoves.length; index++) {
-			const move = footageMoves[index];
-			if (move.moverJobId !== null) continue;
-			if (!footageMoves.slice(0, index).every((predecessor) => predecessor.state === "done")) return;
-			move.moverJobId = await this.startMove(job, move);
-			await this.persist(job);
-			return;
+		for (const lane of MOVE_LANES) {
+			const laneMoves = job.moves.filter((move) => laneOf(move.storageClass) === lane);
+			for (let index = 0; index < laneMoves.length; index++) {
+				const move = laneMoves[index];
+				if (move === void 0 || move.moverJobId !== null) continue;
+				if (!laneMoves.slice(0, index).every((predecessor) => predecessor.state === "done")) break;
+				move.moverJobId = await this.startMove(job, move);
+				await this.persist(job);
+				break;
+			}
 		}
 	}
 	async waitForMoves(job) {
@@ -487,7 +627,7 @@ var StorageMigrationCoordinator = class {
 			let complete = true;
 			for (const [index, move] of job.moves.entries()) {
 				if (job.cancelRequested && move.moverJobId === null) continue;
-				if (move.storageClass !== "eventMedia" && job.moves.slice(0, index).filter((predecessor) => predecessor.storageClass !== "eventMedia").some((predecessor) => predecessor.state !== "done")) {
+				if (job.moves.slice(0, index).filter((predecessor) => laneOf(predecessor.storageClass) === laneOf(move.storageClass)).some((predecessor) => predecessor.state !== "done")) {
 					complete = false;
 					continue;
 				}
@@ -521,30 +661,92 @@ var StorageMigrationCoordinator = class {
 			await sleep(pollMs);
 		}
 	}
+	/**
+	* Nail every unstamped `eventMedia`/retrain row to the location its bytes are
+	* ALREADY on, before anything repoints. Runs with every writer up — it moves
+	* no bytes at all.
+	*
+	* The gate is the RE-COUNT, not the seal job's terminal state: a seal that
+	* failed some rows still finishes, and "finished" is not "there are none
+	* left". A non-zero count here fails the job while nothing has been paused
+	* and nothing has been repointed, which is the cheapest possible place to
+	* discover it.
+	*
+	* The seal's own mover job id is deliberately NOT durable. It is idempotent
+	* and cheap, so a coordinator restart mid-seal simply re-runs the whole
+	* phase — and the count that follows is what actually decides, so a lost job
+	* id cannot make the gate pass.
+	*/
+	async sealEventMedia(job) {
+		const move = job.moves.find((candidate) => candidate.storageClass === "eventMedia");
+		if (move === void 0) return;
+		if ((await this.deps.participants.analytics.countUnstamped()).total > 0) {
+			const started = await this.deps.participants.analytics.startDrain({
+				toLocationId: move.fromLocationId,
+				mode: "seal"
+			});
+			await this.waitForSeal(job, started.jobId);
+			if (job.cancelRequested) return;
+		}
+		const after = await this.deps.participants.analytics.countUnstamped();
+		if (after.total > 0) throw new Error(`event-media seal left ${after.total.toString()} row(s) without a locationId (${after.media.toString()} media, ${after.retrainFrames.toString()} retrain frames). A non-blocking cutover would silently orphan them; nothing has been paused or repointed.`);
+	}
+	async waitForSeal(job, moverJobId) {
+		const sleep = this.deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+		const pollMs = this.deps.pollMs ?? 250;
+		for (;;) {
+			if (job.cancelRequested) {
+				await this.deps.participants.analytics.cancelMove(moverJobId);
+				return;
+			}
+			const status = await this.deps.participants.analytics.getMove(moverJobId);
+			if (status === null || status.state === "done" || status.state === "cancelled") return;
+			if (status.state === "failed") throw new Error(status.error ?? "event-media seal failed");
+			await sleep(pollMs);
+		}
+	}
 	async verifyMoves(job) {
 		for (const move of job.moves) if (move.state !== "done") throw new Error(`${move.storageClass} move did not complete verification`);
 	}
+	/**
+	* Arm one class's mover.
+	*
+	* `draining` runs after every writer has been resumed, so there is no lease
+	* left to present — it goes through the participants' UNLEASED entry points
+	* (`recording.relocateFootage` / `pipelineAnalytics.relocateMedia`), which
+	* are the same engines, not a second mover.
+	*/
 	async startMove(job, move) {
-		if (move.storageClass === "eventMedia") return (await this.deps.participants.analytics.startMove({
-			toLocationId: move.toLocationId,
-			throttleMbps: job.throttleMbps,
-			leaseId: requireLease(job)
-		})).jobId;
-		return (await this.deps.participants.recorder.startMove({
+		const unleased = runsUnleased(job);
+		if (laneOf(move.storageClass) === "media") {
+			const input = {
+				toLocationId: move.toLocationId,
+				throttleMbps: job.throttleMbps,
+				mode: move.storageClass === "galleryMedia" ? "gallery" : "move"
+			};
+			return (unleased ? await this.deps.participants.analytics.startDrain(input) : await this.deps.participants.analytics.startMove({
+				...input,
+				leaseId: requireLease(job)
+			})).jobId;
+		}
+		const input = {
 			fromLocationId: move.fromLocationId,
 			toLocationId: move.toLocationId,
-			footageClass: move.storageClass,
-			throttleMbps: job.throttleMbps,
+			footageClass: move.storageClass === "recordingsLow" ? "recordingsLow" : "recordings",
+			throttleMbps: job.throttleMbps
+		};
+		return (unleased ? await this.deps.participants.recorder.startDrain(input) : await this.deps.participants.recorder.startMove({
+			...input,
 			leaseId: requireLease(job)
 		})).jobId;
 	}
 	async moveStatus(move) {
 		if (move.moverJobId === null) return null;
-		return move.storageClass === "eventMedia" ? this.deps.participants.analytics.getMove(move.moverJobId) : this.deps.participants.recorder.getMove(move.moverJobId);
+		return laneOf(move.storageClass) === "media" ? this.deps.participants.analytics.getMove(move.moverJobId) : this.deps.participants.recorder.getMove(move.moverJobId);
 	}
 	async cancelMove(move) {
 		if (move.moverJobId === null) return;
-		if (move.storageClass === "eventMedia") await this.deps.participants.analytics.cancelMove(move.moverJobId);
+		if (laneOf(move.storageClass) === "media") await this.deps.participants.analytics.cancelMove(move.moverJobId);
 		else await this.deps.participants.recorder.cancelMove(move.moverJobId);
 	}
 	participant(name) {
@@ -573,6 +775,27 @@ function requireLease(job) {
 function isTerminal(job) {
 	return job.phase === "done" || job.phase === "failed" || job.phase === "cancelled";
 }
+/**
+* Which single-flight engine owns a class.
+*
+* `galleryMedia` is in the media lane not because it is event media — it
+* explicitly is not (D197) — but because it is moved by the same
+* `MediaRelocateEngine`, which refuses a second running job.
+*/
+function laneOf(storageClass) {
+	return storageClass === "eventMedia" || storageClass === "galleryMedia" ? "media" : "footage";
+}
+/**
+* True when this phase runs with every writer already back up, so no
+* maintenance lease exists to present to a participant.
+*
+* `verifying` is in both camps: it precedes the repoint (paused) under
+* `blocking` and follows the drain (running) under `nonBlocking`.
+*/
+function runsUnleased(job) {
+	if (job.phase === "sealing" || job.phase === "draining") return true;
+	return job.phase === "verifying" && job.mode === "nonBlocking";
+}
 //#endregion
 //#region src/kernel/storage-location-registry.ts
 /**
@@ -758,6 +981,14 @@ var StorageOrchestratorService = class {
 	* early-boot path that predates the resolver wiring.
 	*/
 	nodeLocalResolver = null;
+	/**
+	* Injected occupancy probe (see {@link LocationOccupancyProbe}). `null` until
+	* {@link setOccupancyProbe} runs, and a `null` probe answers `unknown` — so a
+	* service with no probe REFUSES an unforced delete rather than performing one
+	* it could not check. The check is the point; a check that defaults to
+	* "permit" is a paragraph, not a guard.
+	*/
+	occupancyProbe = null;
 	/** `localNodeId` with any forked-child `/addon` suffix stripped. */
 	localNode;
 	/**
@@ -856,6 +1087,15 @@ var StorageOrchestratorService = class {
 		this.nodeLocalResolver = resolver;
 	}
 	/**
+	* Inject the "does this location still hold anything" probe read by
+	* {@link deleteLocation}. Absent → every delete sees `unknown` and therefore
+	* REFUSES without `force`, which is the safe direction for a service wired
+	* without one.
+	*/
+	setOccupancyProbe(probe) {
+		this.occupancyProbe = probe;
+	}
+	/**
 	* The full set of addon-declared storage locations, as aggregated by
 	* the kernel and injected via {@link setRegistry}. Powers the admin-UI
 	* Data screen's per-declaration grouping. Empty until the registry is
@@ -1078,13 +1318,22 @@ var StorageOrchestratorService = class {
 	* Persistence (Task 6) mirrors the delete asynchronously, with errors
 	* routed to the logger — see `upsertLocation` for the rationale.
 	*/
-	deleteLocation(id) {
+	async deleteLocation(id, options) {
 		const loc = this.locations.get(id);
 		if (!loc) throw new Error(`Storage location "${id}" not found`);
 		if (loc.isSystem) throw new Error(`Storage location "${id}" is system-managed and cannot be deleted. Edit its config (path / providerId) instead.`);
 		if (loc.isDefault) {
 			if (![...this.locations.values()].find((l) => l.type === loc.type && l.id !== id && l.isDefault)) throw new Error(`Cannot delete default location "${id}" for type "${loc.type}" — promote another location to default first`);
 		}
+		const occupancy = await this.probeOccupancy(loc);
+		if (occupancy !== "empty") {
+			if (options?.force !== true) throw new Error(occupancy === "occupied" ? `Storage location "${id}" still holds data — drain it first (storage migration / relocate), or pass force to delete the record anyway and strand what is on it` : `Storage location "${id}" could not be checked for remaining data (unreachable provider, another node, or an unmounted root) — pass force to delete the record anyway`);
+			this.logger.warn("storage-orchestrator: FORCED delete of a location that was not verified empty", { meta: {
+				id,
+				type: loc.type,
+				occupancy
+			} });
+		}
 		this.locations.delete(id);
 		if (this.locationStore) this.locationStore.delete(id).catch((err) => {
 			this.logger.error("storage-orchestrator: delete persistence failed", { meta: {
@@ -1094,6 +1343,23 @@ var StorageOrchestratorService = class {
 		});
 	}
 	/**
+	* Run the injected occupancy probe, converting "no probe" and "the probe
+	* threw" into `unknown` rather than into a permit.
+	*/
+	async probeOccupancy(location) {
+		const probe = this.occupancyProbe;
+		if (probe === null) return "unknown";
+		try {
+			return await probe(location);
+		} catch (err) {
+			this.logger.warn("storage-orchestrator: occupancy probe failed", { meta: {
+				id: location.id,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+			return "unknown";
+		}
+	}
+	/**
 	* Remove system-seeded locations whose type is no longer declared by any
 	* addon (stale defaults from a removed location type). Operator-added
 	* (non-system) locations of an undeclared type are KEPT but warned — the
@@ -1530,6 +1796,7 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 		});
 		this.service = service;
 		service.setNodeLocalResolver((providerId) => this.nodeLocalByProvider.get(providerId));
+		service.setOccupancyProbe((location) => this.locationOccupancy(location));
 		await service.initialize();
 		const provider = {
 			listLocations: async ({ type }) => {
@@ -1542,8 +1809,8 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			getDefaultLocation: async ({ type }) => service.getDefaultLocation(type),
 			listLocationDeclarations: async () => service.listDeclarations(),
 			upsertLocation: async (input) => service.upsertLocation(input),
-			deleteLocation: async ({ id }) => {
-				service.deleteLocation(id);
+			deleteLocation: async ({ id, force }) => {
+				await service.deleteLocation(id, { force: force === true });
 			},
 			testLocation: async ({ id }) => {
 				const loc = service.getLocationById(id);
@@ -1706,6 +1973,7 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 						await this.ctx.api.recording.resumeForStorageMigration.mutate({ leaseId });
 					},
 					startMove: (input) => this.ctx.api.recording.startStorageMigrationMove.mutate(input),
+					startDrain: (input) => this.ctx.api.recording.relocateFootage.mutate(input),
 					getMove: (jobId) => this.ctx.api.recording.getStorageMigrationMoveStatus.query({ jobId }),
 					cancelMove: async (jobId) => (await this.ctx.api.recording.cancelStorageMigrationMove.mutate({ jobId })).cancelled,
 					refresh: async (leaseId) => {
@@ -1720,6 +1988,8 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 						await this.ctx.api.pipelineAnalytics.resumeForStorageMigration.mutate({ leaseId });
 					},
 					startMove: (input) => this.ctx.api.pipelineAnalytics.startStorageMigrationMove.mutate(input),
+					startDrain: (input) => this.ctx.api.pipelineAnalytics.relocateMedia.mutate(input),
+					countUnstamped: () => this.ctx.api.pipelineAnalytics.countUnstampedEventMedia.query({}),
 					getMove: (jobId) => this.ctx.api.pipelineAnalytics.getStorageMigrationMoveStatus.query({ jobId }),
 					cancelMove: async (jobId) => (await this.ctx.api.pipelineAnalytics.cancelStorageMigrationMove.mutate({ jobId })).cancelled,
 					refresh: async (leaseId) => {
@@ -1728,7 +1998,8 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 				}
 			},
 			now: () => Date.now(),
-			newId: () => randomUUID()
+			newId: () => randomUUID(),
+			deviceKeyOf: (locationId) => this.locationDeviceKey(locationId)
 		});
 		this.migration = migration;
 		const migrationProvider = {
@@ -1941,6 +2212,44 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			return path$1.resolve(bp);
 		}
 	}
+	/**
+	* Does this location still hold anything? A SHALLOW `readdir` of its
+	* `basePath` — one syscall, never a walk. `/recordings` holds one entry per
+	* camera, so this is cheap on a volume with millions of segments, and a
+	* `find`-style walk of a saturated recordings disk is precisely what must
+	* not happen here.
+	*
+	* **What it cannot see, stated rather than papered over:**
+	*
+	*  - A location on ANOTHER node, or behind a remote provider (S3 / SFTP /
+	*    WebDAV): its bytes are not on this filesystem and this probe answers
+	*    `unknown`, never `empty`.
+	*  - A location with no `basePath` — same answer.
+	*  - The difference between "holds live footage" and "holds one stray
+	*    lock-file". It measures BYTES ON DISK, not durable rows, so it refuses
+	*    a location holding orphan files that no index names. That direction is
+	*    the safe one, and `force` is the escape hatch for it.
+	*
+	* A missing root (`ENOENT`) is `empty`, not `unknown`: an unmounted disk and
+	* a deleted directory are indistinguishable here, and if the record's own
+	* path does not exist there is nothing this delete can strand. Every OTHER
+	* errno — `EACCES`, `EIO`, a stale NFS handle — is `unknown` and refuses.
+	*/
+	async locationOccupancy(location) {
+		if ((location.nodeId === void 0 || location.nodeId === "" ? HUB_NODE_ID : location.nodeId) !== (this.service?.getLocalNodeId() ?? HUB_NODE_ID)) return "unknown";
+		const basePath = this.locationBasePath(location.id);
+		if (basePath === null) return "unknown";
+		try {
+			return (await fs.readdir(basePath)).length > 0 ? "occupied" : "empty";
+		} catch (err) {
+			if (err instanceof Error && "code" in err && err.code === "ENOENT") return "empty";
+			this.ctx.logger.warn("storage-orchestrator: could not read a location root to check it", { meta: {
+				id: location.id,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+			return "unknown";
+		}
+	}
 	/** Free capacity (%) on a location's volume via `statfs`; 100 (guard inert) when unstattable. */
 	async locationFreePercent(locationId) {
 		const bp = this.locationBasePath(locationId);

package/dist/builtins/storage-orchestrator/storage-orchestrator.service.d.ts

@@ -37,6 +37,22 @@ export type StorageProviderLookup = () => readonly IStorageProviderImpl[];
  *     remote), the safe default for the early-boot / in-memory path.
  */
 export type NodeLocalResolver = (providerId: string) => boolean | undefined;
+/**
+ * Whether a location still holds anything — the only question `deleteLocation`
+ * is allowed to destroy a record on the answer to.
+ *
+ *  - `'occupied'` — something is there. Deleting the record now strands it.
+ *  - `'empty'`    — the location was reached and holds nothing.
+ *  - `'unknown'`  — it could not be reached at all: a remote provider, another
+ *                   node's disk, an unmounted root. NOT "empty". A read that
+ *                   fails must never authorise a destruction (D49).
+ */
+export type LocationOccupancy = 'occupied' | 'empty' | 'unknown';
+export type LocationOccupancyProbe = (location: StorageLocation) => Promise<LocationOccupancy>;
+export interface DeleteLocationOptions {
+    /** Override an `occupied` or `unknown` verdict. See the cap docblock. */
+    readonly force?: boolean;
+}
 /**
  * Where a single dispatch must execute: which `storage-provider`, on which
  * node. `providerId` alone is NOT a routing key — every node's filesystem
@@ -89,6 +105,14 @@ export declare class StorageOrchestratorService {
      * early-boot path that predates the resolver wiring.
      */
     private nodeLocalResolver;
+    /**
+     * Injected occupancy probe (see {@link LocationOccupancyProbe}). `null` until
+     * {@link setOccupancyProbe} runs, and a `null` probe answers `unknown` — so a
+     * service with no probe REFUSES an unforced delete rather than performing one
+     * it could not check. The check is the point; a check that defaults to
+     * "permit" is a paragraph, not a guard.
+     */
+    private occupancyProbe;
     /** `localNodeId` with any forked-child `/addon` suffix stripped. */
     private readonly localNode;
     /**
@@ -166,6 +190,13 @@ export declare class StorageOrchestratorService {
      * changes. Powers the node-local upsert guard and the boot backfill.
      */
     setNodeLocalResolver(resolver: NodeLocalResolver | null): void;
+    /**
+     * Inject the "does this location still hold anything" probe read by
+     * {@link deleteLocation}. Absent → every delete sees `unknown` and therefore
+     * REFUSES without `force`, which is the safe direction for a service wired
+     * without one.
+     */
+    setOccupancyProbe(probe: LocationOccupancyProbe | null): void;
     /**
      * The full set of addon-declared storage locations, as aggregated by
      * the kernel and injected via {@link setRegistry}. Powers the admin-UI
@@ -231,7 +262,12 @@ export declare class StorageOrchestratorService {
      * Persistence (Task 6) mirrors the delete asynchronously, with errors
      * routed to the logger — see `upsertLocation` for the rationale.
      */
-    deleteLocation(id: string): void;
+    deleteLocation(id: string, options?: DeleteLocationOptions): Promise<void>;
+    /**
+     * Run the injected occupancy probe, converting "no probe" and "the probe
+     * threw" into `unknown` rather than into a permit.
+     */
+    private probeOccupancy;
     /**
      * Remove system-seeded locations whose type is no longer declared by any
      * addon (stale defaults from a removed location type). Operator-added