@camstack/system 1.2.157 → 1.2.160

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-LvKus-mT.mjs";
+import { Mt as BaseAddon, N as collectSecretConfigKeys, Qt as parseJsonObject, S as StorageMigrationJobSchema, St as settingsStoreCapability, Tt as storageMigrationCapability, m as REDACTED_SECRET, wt as storageCapability, x as StorageLocationTypeSchema } from "../../dist-DKs---Vx.mjs";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path$1 from "node:path";
@@ -263,6 +263,8 @@ var BLOCKING_ONLY_CLASSES = ["galleryMedia"];
 * link back to this decision.
 */
 var GALLERY_FORBIDDEN_NEIGHBOUR_TYPES = ["recordings", "recordingsLow"];
+/** The two single-flight mover engines. Lanes run in parallel; within a lane,
+*  classes run FIFO because the engine refuses a second concurrent job. */
 var MOVE_LANES = ["media", "footage"];
 var PARTICIPANTS = [
 	"pipeline",
@@ -275,6 +277,18 @@ var REVERSE_PARTICIPANTS = [
 	"pipeline"
 ];
 /**
+* One lane of the seal gate, as an operator reads it.
+*
+* "0" and "unknown" must not print the same, and neither may be silently
+* turned into the other: `{ present: true, rows: null }` is "there are some
+* and the count did not land", which is a refusal with a missing number, not a
+* clean lane.
+*/
+function describeUnstamped(lane) {
+	if (!lane.present) return "0";
+	return lane.rows === null ? "an unknown number of" : lane.rows.toString();
+}
+/**
 * Durable orchestration layer over the independent recorder and event-media
 * movers. It owns the only public migration state machine; participants expose
 * intentionally narrow lease/move primitives and never alter camera settings.
@@ -309,7 +323,8 @@ var StorageMigrationCoordinator = class {
 				toLocationId: target.id,
 				moverJobId: null,
 				state: null,
-				error: null
+				error: null,
+				progress: null
 			});
 			if (BLOCKING_ONLY_CLASSES.includes(storageClass)) findings.push({
 				code: "blockingOnly",
@@ -321,12 +336,21 @@ var StorageMigrationCoordinator = class {
 		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"}" }).`);
+			if (unstamped === null) {
+				if (mode === "nonBlocking") throw new Error("could not determine whether any event-media row still carries no locationId. A non-blocking cutover repoints the default and would silently orphan every such row, so an unmeasured collection is refused exactly like a non-empty one. Retry, or run the blocking mode, which stamps rows as it moves them.");
 				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.`
+					message: "the count of event-media rows carrying no locationId could not be taken — treat it as unknown, not as zero. This blocking migration stamps them as it moves them, so it is safe regardless; a non-blocking one would be refused."
+				});
+			} else if (unstamped.anyPresent) {
+				const scale = unstamped.total === null ? "an unknown number of" : unstamped.total.toString();
+				const perLane = `${describeUnstamped(unstamped.media)} media, ${describeUnstamped(unstamped.retrainFrames)} retrain frames`;
+				if (mode === "nonBlocking") throw new Error(`${scale} event-media row(s) still carry no locationId (${perLane}). 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: `${scale} event-media row(s) carry no locationId (${perLane}). 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.`
 				});
 			}
 		}
@@ -407,7 +431,8 @@ var StorageMigrationCoordinator = class {
 					...move,
 					moverJobId: null,
 					state: null,
-					error: null
+					error: null,
+					progress: null
 				})),
 				pauseLeaseId: null,
 				pausedParticipants: [],
@@ -441,6 +466,178 @@ var StorageMigrationCoordinator = class {
 		await Promise.all(job.moves.filter((move) => move.moverJobId !== null).map((move) => this.cancelMove(move)));
 		return true;
 	}
+	/**
+	* Every mover running right now, in both lanes — including the ones no
+	* migration armed.
+	*
+	* `status` already carries a migration's own progress (the coordinator folds
+	* it onto each move from the poll it is already doing). This exists for the
+	* other half: `recording.relocateFootage` and `pipelineAnalytics.relocateMedia`
+	* are operator-callable, and until {@link drain} existed that was the only way
+	* to run a drain at all. Such a mover has no job to fold into, so without this
+	* read a five-hour operation is invisible in the UI.
+	*
+	* `migrationJobId` is best-effort by construction: the coordinator keeps ONE
+	* durable job, so a mover armed by an older, since-overwritten migration
+	* reports `null`. That is the honest answer — nothing here can still claim it.
+	*/
+	async movers() {
+		const job = await this.status();
+		const owned = /* @__PURE__ */ new Map();
+		for (const move of job?.moves ?? []) if (move.moverJobId !== null) owned.set(move.moverJobId, job?.jobId ?? "");
+		const [footage, media] = await Promise.all([this.deps.participants.recorder.listMovers(), this.deps.participants.analytics.listMovers()]);
+		const observedAt = this.deps.now();
+		const label = (lane, jobs) => jobs.map((mover) => ({
+			lane,
+			job: mover,
+			migrationJobId: owned.get(mover.jobId) ?? null,
+			observedAt
+		}));
+		return [...label("footage", footage), ...label("media", media)];
+	}
+	/**
+	* What every class's source STILL holds — the census behind a "drain
+	* remaining" action.
+	*
+	* A class appears here only when something is (or might be) left on a
+	* location that is not its default. An empty result therefore means exactly
+	* "there is nothing to drain", which is what lets the UI offer the action
+	* only when it is true, and what lets {@link drain} refuse rather than start
+	* a job that would move nothing and report `done` — the failure mode D295
+	* exists to end.
+	*
+	* `items: null` is "the archive could not be asked" and is still listed. A
+	* residue nobody could measure is the case an operator most needs to see;
+	* dropping it because the read failed would be the quiet success again.
+	*/
+	async residue() {
+		const out = [];
+		for (const storageClass of STORAGE_CLASSES) {
+			if (!MOVER_CLASSES.includes(storageClass)) continue;
+			const target = this.deps.locations.getDefaultLocation(storageClass);
+			if (!target) continue;
+			if (laneOf(storageClass) === "media") {
+				const count = await unanswerable(this.deps.participants.analytics.residue({
+					toLocationId: target.id,
+					mode: storageClass === "galleryMedia" ? "gallery" : "move"
+				}));
+				if (count !== null && count.rows === 0) continue;
+				out.push({
+					storageClass,
+					fromLocationId: "*",
+					toLocationId: target.id,
+					items: count?.rows ?? null,
+					bytes: null
+				});
+				continue;
+			}
+			for (const source of this.deps.locations.listLocations({ type: storageClass })) {
+				if (source.id === target.id) continue;
+				const census = await unanswerable(this.deps.participants.recorder.residue({
+					fromLocationId: source.id,
+					footageClass: storageClass === "recordingsLow" ? "recordingsLow" : "recordings"
+				}));
+				if (census !== null && census.segments === 0) continue;
+				out.push({
+					storageClass,
+					fromLocationId: source.id,
+					toLocationId: target.id,
+					items: census?.segments ?? null,
+					bytes: census?.bytes ?? null
+				});
+			}
+		}
+		return out;
+	}
+	/**
+	* Run the DRAIN half alone, against classes whose default has already moved.
+	*
+	* ## Why this is a second verb rather than a looser `start`
+	*
+	* `start` refuses a destination that is already the class's default
+	* (`"recordingsLow:ssd" is already the "recordingsLow" default`). That refusal
+	* is correct and it is load-bearing: there is genuinely nothing left to
+	* repoint, and an operator must never be able to re-repoint a migrated class
+	* by accident. Making `start` idempotent — "an already-repointed class
+	* proceeds straight to draining" — would delete that protection AND make the
+	* verb mean two different things depending on state, so the confirmation an
+	* operator reads ("pauses the writers…") would be a lie half the time.
+	*
+	* `drain` instead cannot repoint AT ALL: it never touches
+	* `setDefaultLocations`, and its job starts in `draining` with `repointed`
+	* already true, so the `repointing` / `refreshing` / `resuming` blocks of
+	* {@link run} are behind it and unreachable. The two verbs are disjoint, and
+	* `start`'s refusal keeps meaning exactly what it meant.
+	*
+	* ## Why it re-derives the work instead of resuming the old job
+	*
+	* The finished job is the audit of what happened; re-opening it destroys
+	* that. And a drain is needed in cases where no migration job ever existed
+	* (a mover armed by hand, footage stranded on a location an operator added
+	* and then un-defaulted). One job = one operation, and the work list comes
+	* from {@link residue} — the archive — not from what a previous job believed.
+	*/
+	async drain(input) {
+		if (this.startReserved) throw new Error("storage migration is already active");
+		this.startReserved = true;
+		try {
+			const existing = await this.status();
+			if (existing && isTerminal(existing) && existing.pausedParticipants.length > 0) {
+				await this.releaseAfterTerminal(existing);
+				await this.persist(existing);
+				if (existing.pausedParticipants.length > 0) throw new Error(`storage migration ${existing.jobId} still holds maintenance leases`);
+			}
+			if (existing && !isTerminal(existing)) throw new Error(`storage migration is already active (${existing.jobId})`);
+			for (const storageClass of input.classes) {
+				if (MOVER_CLASSES.includes(storageClass)) continue;
+				throw new Error(`No mover owns "${storageClass}" — there is nothing that can drain it. Move it by hand.`);
+			}
+			const residue = await this.residue();
+			const moves = [];
+			const destinations = {};
+			for (const storageClass of input.classes) {
+				const remaining = residue.filter((entry) => entry.storageClass === storageClass);
+				if (remaining.length === 0) throw new Error(`"${storageClass}" has nothing left outside its default location — there is nothing to drain. To CHANGE where it writes, use storageMigration.start with a new destination.`);
+				for (const entry of remaining) {
+					if (this.deps.locations.getLocationById(entry.toLocationId)?.enabled === false) throw new Error(`The "${storageClass}" drain destination "${entry.toLocationId}" is DISABLED — a disabled location takes no writes, and a drain is the largest write there is. Enable it on the Storage screen, or make an enabled location the "${storageClass}" default first.`);
+					moves.push({
+						storageClass,
+						fromLocationId: entry.fromLocationId,
+						toLocationId: entry.toLocationId,
+						moverJobId: null,
+						state: null,
+						error: null,
+						progress: null
+					});
+					destinations[storageClass] = entry.toLocationId;
+				}
+			}
+			const now = this.deps.now();
+			const job = {
+				jobId: this.deps.newId(),
+				phase: "draining",
+				mode: "nonBlocking",
+				destinations,
+				throttleMbps: input.throttleMbps ?? 40,
+				moves,
+				pauseLeaseId: null,
+				pausedParticipants: [],
+				repointed: true,
+				cancelRequested: false,
+				startedAt: now,
+				updatedAt: now,
+				finishedAt: null,
+				error: null
+			};
+			await this.persist(job);
+			this.active = job;
+			this.runPromise = this.run(job);
+			this.runPromise;
+			return job.jobId;
+		} finally {
+			this.startReserved = false;
+		}
+	}
 	/** Boot recovery resumes a durable unfinished state. A missing in-memory
 	* child mover is recreated from the same copy-if-absent input. */
 	async recover() {
@@ -649,6 +846,14 @@ var StorageMigrationCoordinator = class {
 				}
 				move.state = status.state;
 				move.error = status.error;
+				move.progress = {
+					filesMoved: status.filesMoved,
+					filesTotal: status.filesTotal,
+					bytesMoved: status.bytesMoved,
+					...status.rowsReconciled === void 0 ? {} : { rowsReconciled: status.rowsReconciled },
+					startedAt: status.startedAt,
+					observedAt: this.deps.now()
+				};
 				if (status.state === "failed") throw new Error(move.error ?? `${move.storageClass} move failed`);
 				if (status.state === "cancelled") {
 					job.cancelRequested = true;
@@ -668,9 +873,10 @@ var StorageMigrationCoordinator = class {
 	*
 	* 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
+	* left". A remaining row here fails the job while nothing has been paused
 	* and nothing has been repointed, which is the cheapest possible place to
-	* discover it.
+	* discover it. So does a re-count that could not be TAKEN: the gate opens on
+	* a measured absence, and only on that.
 	*
 	* 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
@@ -680,7 +886,8 @@ var StorageMigrationCoordinator = class {
 	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 before = await this.deps.participants.analytics.countUnstamped();
+		if (before === null || before.anyPresent) {
 			const started = await this.deps.participants.analytics.startDrain({
 				toLocationId: move.fromLocationId,
 				mode: "seal"
@@ -689,7 +896,8 @@ var StorageMigrationCoordinator = class {
 			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.`);
+		if (after === null) throw new Error("event-media seal ran, but whether any row still carries no locationId could not be measured afterwards. Unknown is not zero; nothing has been paused or repointed.");
+		if (after.anyPresent) throw new Error(`event-media seal left ${after.total === null ? "an unknown number of" : after.total.toString()} row(s) without a locationId (${describeUnstamped(after.media)} media, ${describeUnstamped(after.retrainFrames)} 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)));
@@ -768,6 +976,25 @@ var StorageMigrationCoordinator = class {
 		await this.deps.state.set(job);
 	}
 };
+/**
+* A residue read that FAILED is unanswerable, not zero — and it must not take
+* the other lane down with it.
+*
+* `residue` asks two addons. One of them being mid-restart is an ordinary
+* event, and letting that throw out of the whole call would blank the panel:
+* an operator with 80 GB stranded on a recordings disk would be told nothing,
+* because post-analysis was rebooting. `null` is the same "unknown" the
+* participants themselves return for a read they could not take, so the entry
+* is still LISTED and still labelled unknown — a drain attempted against it
+* then fails loudly with the participant's own message, which is the point.
+*/
+async function unanswerable(read) {
+	try {
+		return await read;
+	} catch {
+		return null;
+	}
+}
 function requireLease(job) {
 	if (job.pauseLeaseId === null) throw new Error("storage migration has no maintenance lease");
 	return job.pauseLeaseId;
@@ -810,6 +1037,12 @@ function runsUnleased(job) {
 * - **Cardinality conflict throws**: if two addons declare the same `id` with
 *   different `cardinality` values an `Error` is thrown immediately (message
 *   contains the words "cardinality" and the conflicting `id`).
+* - **Access conflict throws**, for the same reason and more sharply: the
+*   EFFECTIVE access (declared, else `STORAGE_ACCESS_FALLBACK`) must agree.
+*   "First declarer wins" is the right rule for a display name and a
+*   catastrophic one for a safety constraint — it would let a second addon
+*   silently widen a kind that the first one restricted, which is exactly the
+*   accident this constraint exists to make impossible.
 *
 * @param perAddon - One entry per addon; each entry is that addon's
 *   `storageLocations` declaration array.
@@ -820,6 +1053,9 @@ function buildStorageLocationRegistry(perAddon) {
 		const existing = map.get(declaration.id);
 		if (existing !== void 0) {
 			if (existing.cardinality !== declaration.cardinality) throw new Error(`Storage location cardinality conflict for id "${declaration.id}": "${existing.cardinality}" (first declarer) vs "${declaration.cardinality}" (later declarer). All addons declaring the same storage location id must agree on cardinality.`);
+			const existingAccess = existing.access ?? "local-path";
+			const declaredAccess = declaration.access ?? "local-path";
+			if (existingAccess !== declaredAccess) throw new Error(`Storage location access conflict for id "${declaration.id}": "${existingAccess}" (first declarer) vs "${declaredAccess}" (later declarer). All addons declaring the same storage location id must agree on access — a later declaration must never widen what an earlier one restricted.`);
 			continue;
 		}
 		map.set(declaration.id, declaration);
@@ -835,12 +1071,53 @@ function buildStorageLocationRegistry(perAddon) {
 		cardinalityOf(id) {
 			return map.get(id)?.cardinality ?? null;
 		},
+		accessOf(id) {
+			const declaration = map.get(id);
+			if (declaration === void 0) return null;
+			return declaration.access ?? "local-path";
+		},
 		list() {
 			return frozen;
 		}
 	};
 }
 //#endregion
+//#region src/builtins/storage-orchestrator/access-guards.ts
+/**
+* May `storage.resolve` return a path for this location?
+*
+* `resolve` is the only method on the cap whose result LEAVES the storage
+* abstraction — every caller of it opens the string with `node:fs`. A remote
+* provider answers with a path on the remote host, which on this node is
+* either missing or an unrelated local directory of the same name. For the
+* recorder, writing to the wrong place is not an error the operator sees; it
+* is a black window in the footage.
+*
+* Only a POSITIVE `false` refuses. `undefined` is "not yet classified", not
+* "remote" — and a conclusion drawn from a read that was never made is how a
+* doorbell rang 0/3 (D49).
+*/
+function resolveRefusalFor(location, locality) {
+	if (locality !== false) return null;
+	return `storage.resolve is a request for a path this node can open with node:fs, and location "${location.id}" is served by the remote provider "${location.providerId}" (nodeLocal: false) — the path it would return exists on the remote host, not here. Read and write this location through the storage cap (read/write, or beginUpload/writeChunk/finalizeUpload) instead.`;
+}
+/**
+* Can this node's filesystem answer "does this location still hold anything?"
+*
+* Only for a provider it KNOWS to be node-local. Everything else is `unknown`,
+* which refuses a delete.
+*
+* The direction that matters is the one this closes. A remote location carries
+* a plain-looking `basePath` (`/backups/camstack`); `fs.readdir` of it on the
+* hub answers `ENOENT`, and `ENOENT` is deliberately read as `empty` — because
+* for a LOCAL location an absent root means there is nothing the delete can
+* strand. Applied to a remote row, that same reasoning turns a full share into
+* a vacant one and walks D293's delete guard straight past it.
+*/
+function canProbeOccupancyLocally(locality) {
+	return locality === true;
+}
+//#endregion
 //#region src/builtins/storage-orchestrator/data-store-dispatch.ts
 /**
 * Pick the engine to serve a call.
@@ -892,6 +1169,106 @@ function createDataStoreDispatch(getEngines) {
 	};
 }
 //#endregion
+//#region src/builtins/storage-orchestrator/location-secrets.ts
+/**
+* Credential redaction for `StorageLocation.config`.
+*
+* ── What was wrong ─────────────────────────────────────────────────────────
+* `storage.listLocations` carries no `auth` override, so it is `protected` —
+* every authenticated session reaches it, admin or not. The orchestrator
+* spread each stored row verbatim. `StorageLocation.config` is
+* `z.record(z.string(), z.unknown())`, and the SFTP / S3 / WebDAV providers
+* already declare `password`, `privateKey`, `privateKeyPassphrase`,
+* `secretAccessKey` and `token` inside it. Nothing was exposed only because
+* every location on the live hub is `filesystem-storage`, whose config is
+* `basePath` + `maxUsedGb`. The exposure arrives with the first remote
+* location, and three providers that collect one already ship.
+*
+* ── The mechanism ──────────────────────────────────────────────────────────
+* Schema-driven, never a hardcoded key list: each provider's
+* `getProviderInfo().configSchema` already says which of its fields hold a
+* credential, so it is the one thing that cannot drift from the provider.
+*
+* Two directions, and both are needed:
+*  - **out** — {@link redactLocationConfig} replaces every secret value with
+*    `REDACTED_SECRET` on the way to a caller.
+*  - **in** — {@link restoreRedactedSecrets} treats that same sentinel, sent
+*    back on an upsert, as "keep what is stored". Without it the wizard's
+*    edit-and-save round trip would write the sentinel into the config and
+*    lock the operator out of their own share on the first rename.
+*
+* ── The trap this deliberately avoids ──────────────────────────────────────
+* Keying redaction off `type: 'password'` alone MISSES a secret parked in a
+* `textarea`, and the SFTP provider parks an entire PEM private key there.
+* Discovery goes through `collectSecretConfigKeys`, whose discriminator is
+* `type === 'password' || secret === true`. A redaction that quietly misses a
+* credential is worse than none: it is a leak plus an assurance there is not
+* one.
+*/
+/** Shared empty set for providers that declare no secrets (or are unknown). */
+var EMPTY_SECRET_KEYS = /* @__PURE__ */ new Set();
+/** Secret config keys a provider declares, derived from its own form schema. */
+function secretKeysOfProviderInfo(info) {
+	return collectSecretConfigKeys(info.configSchema);
+}
+/**
+* A copy of `config` with every declared secret replaced by the sentinel.
+* Returns the SAME object when there is nothing to redact, so the common case
+* (a filesystem location) allocates nothing.
+*
+* A key the provider declares secret but that is absent from the stored config
+* is NOT invented — an absent password must keep reading as absent, or the
+* wizard would show a credential where none is set and the write-back would
+* then "keep" a value that never existed.
+*/
+function redactLocationConfig(config, secretKeys) {
+	if (secretKeys.size === 0) return config;
+	let touched = false;
+	const out = {};
+	for (const [key, value] of Object.entries(config)) {
+		if (secretKeys.has(key) && value !== void 0 && value !== null && value !== "") {
+			out[key] = REDACTED_SECRET;
+			touched = true;
+			continue;
+		}
+		out[key] = value;
+	}
+	return touched ? out : config;
+}
+/** The same, applied to a whole location record. */
+function redactLocation(location, secretKeys) {
+	const config = redactLocationConfig(location.config, secretKeys);
+	if (config === location.config) return location;
+	return {
+		...location,
+		config
+	};
+}
+/**
+* Undo the redaction on the way IN: any secret key whose incoming value is the
+* sentinel is restored from what is already stored.
+*
+* A sentinel with NOTHING stored behind it is dropped rather than persisted —
+* writing the literal `__camstack_redacted__` as a password is a
+* lock-yourself-out bug that would only surface at the next connection
+* attempt, hours later, as an authentication failure with no explanation.
+*/
+function restoreRedactedSecrets(incoming, stored, secretKeys) {
+	if (secretKeys.size === 0) return incoming;
+	let touched = false;
+	const out = {};
+	for (const [key, value] of Object.entries(incoming)) {
+		if (value !== "__camstack_redacted__" || !secretKeys.has(key)) {
+			out[key] = value;
+			continue;
+		}
+		touched = true;
+		const previous = stored?.[key];
+		if (previous !== void 0) out[key] = previous;
+	}
+	return touched ? out : incoming;
+}
+//#endregion
 //#region src/builtins/storage-orchestrator/provider-discovery.ts
 async function collectProviderInfos(providers, onError) {
 	const out = [];
@@ -1068,6 +1445,34 @@ var StorageOrchestratorService = class {
 			backfilled: backfill.length,
 			total: this.locations.size
 		} });
+		this.reportDisabledDefaults();
+	}
+	/**
+	* Shout about a persisted row that is BOTH the type default and disabled.
+	*
+	* `upsertLocation` cannot produce this (`resolveEnabled` force-enables a
+	* default) and neither can `setDefaultLocations` — but hydrate writes rows
+	* straight into the map without either, so a hand-edited store, a partial
+	* migration or a row written by another build can. It matters because every
+	* bare-type ref resolves through {@link getDefaultLocation}: on such a row
+	* `storage.write({ location: 'eventMedia' })` and the migration coordinator's
+	* drain destination both point at a disk the operator turned off. That is the
+	* one thing this model must never do silently.
+	*
+	* Reported, never repaired: flipping an operator's flag back on at boot would
+	* be the system overruling the switch instead of obeying it. The coordinator
+	* refuses the drain (`storage-migration-coordinator.drain`); the bare-ref read
+	* path is deliberately left working, because narrowing a READ is a worse bug
+	* than the one this line reports.
+	*/
+	reportDisabledDefaults() {
+		for (const loc of this.locations.values()) {
+			if (!loc.isDefault || loc.enabled !== false) continue;
+			this.logger.error("storage-orchestrator: the type DEFAULT is disabled — every bare-type ref for this type resolves to a location the operator turned off. Enable it, or make another location the default.", { meta: {
+				id: loc.id,
+				type: loc.type
+			} });
+		}
 	}
 	/**
 	* Inject the declaration-driven cardinality source. Called once by the
@@ -1139,6 +1544,7 @@ var StorageOrchestratorService = class {
 			loaded: this.locations.size,
 			isSystemUpgraded: upgraded
 		} });
+		this.reportDisabledDefaults();
 	}
 	/**
 	* Boot backfill (SP1): stamp `nodeId` on every persisted node-local
@@ -1248,6 +1654,66 @@ var StorageOrchestratorService = class {
 	* implicitly-demoted siblings are persisted before the in-memory map
 	* mutation returns. Persistence errors propagate to the caller.
 	*/
+	/**
+	* Refuse a `(location kind, provider)` pair the kind cannot use.
+	*
+	* The rule, in one line: a `'local-path'` kind requires a provider whose
+	* `getProviderInfo().nodeLocal` is `true`.
+	*
+	* `nodeLocal` is the honest name for "this provider's `resolve` returns a
+	* path on the filesystem of the node that resolved it". The
+	* `storage-provider` cap's own discriminated union already forces every
+	* provider to declare it, and all four remote providers declare `false`, so
+	* no new cap surface is needed to ask the question.
+	*
+	* Three-valued on purpose. Only a POSITIVE `false` refuses:
+	*  - `true`      → node-local, always fine.
+	*  - `false`     → the provider is known and known to be remote. REFUSE.
+	*  - `undefined` → the provider has not registered yet (early boot, an addon
+	*    still loading). That is "unknown", not "remote", and a read that could
+	*    not be made must never destroy work (D49) — the system seed runs
+	*    through this path before any provider registers. Allowed, and logged,
+	*    so the allowance is never silent.
+	*
+	* The DECLARATION side is read the same way. A kind the registry does not
+	* know is `local-path` (fail-closed: an unknown kind is not a permissive
+	* one), but NO REGISTRY AT ALL is a different statement — nothing has been
+	* loaded, so nothing can be concluded about any kind. The addon injects the
+	* registry inside `onInitialize`, before the `storage` cap is mounted, so
+	* there is no window in which an operator upsert sees this branch; a service
+	* constructed without one is the in-memory/early-boot path.
+	*/
+	refuseIncompatibleProvider(input) {
+		const registry = this.registry;
+		if (registry === null) {
+			this.logger.debug("storage-orchestrator: no location declarations loaded — access constraint not evaluated", { meta: {
+				id: input.id,
+				type: input.type,
+				providerId: input.providerId
+			} });
+			return;
+		}
+		const access = registry.accessOf(input.type) ?? "local-path";
+		if (access !== "local-path") return;
+		const nodeLocal = this.nodeLocalResolver?.(input.providerId);
+		if (nodeLocal === true) return;
+		if (nodeLocal === void 0) {
+			this.logger.debug("storage-orchestrator: provider not yet classified — allowing a local-path upsert", { meta: {
+				id: input.id,
+				type: input.type,
+				providerId: input.providerId,
+				access
+			} });
+			return;
+		}
+		this.logger.warn("storage-orchestrator: REFUSED a remote provider for a local-path kind", { meta: {
+			id: input.id,
+			type: input.type,
+			providerId: input.providerId,
+			access
+		} });
+		throw new Error(`Storage kind "${input.type}" is declared access "local-path": the service that owns it reads and writes its bytes with node:fs on the path "storage.resolve" returns, so it can only be backed by a node-local provider. Provider "${input.providerId}" is remote (nodeLocal: false) and its resolved paths do not exist on this node. Refusing location "${input.id}".`);
+	}
 	upsertLocation(input) {
 		const now = Date.now();
 		const existing = this.locations.get(input.id);
@@ -1257,6 +1723,7 @@ var StorageOrchestratorService = class {
 				if (already) throw new Error(`Storage type "${input.type}" is single — only one location allowed (existing: "${already.id}"). Edit it instead of adding a new one.`);
 			}
 		}
+		this.refuseIncompatibleProvider(input);
 		if (this.nodeLocalResolver?.(input.providerId) === true && !input.nodeId) input = {
 			...input,
 			nodeId: "hub"
@@ -1768,6 +2235,19 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 	*/
 	nodeLocalByProvider = /* @__PURE__ */ new Map();
 	/**
+	* Cached `providerId → secret config keys`, derived from each provider's own
+	* `configSchema` in the SAME refresh as `nodeLocalByProvider` — one
+	* `getProviderInfo()` round trip answers both questions.
+	*
+	* An absent providerId yields an EMPTY set, which redacts nothing. That is
+	* the one direction this cache can be wrong in, so it is worth saying why it
+	* is acceptable: the entry is populated at the same moment the provider
+	* becomes resolvable at all, so a location whose provider is unknown here
+	* cannot be dispatched to either — there is no window in which a credential
+	* is readable through a provider the orchestrator can otherwise use.
+	*/
+	secretKeysByProvider = /* @__PURE__ */ new Map();
+	/**
 	* Disposers run on `onShutdown` — currently the eventBus subscription
 	* for `capability:provider-registered` events used by the lazy seed
 	* fallback. Stored separately from the `BaseAddon` disposer chain so
@@ -1802,13 +2282,24 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			listLocations: async ({ type }) => {
 				const rows = type !== void 0 ? service.listLocations({ type }) : service.listLocations();
 				return Promise.all(rows.map(async (loc) => ({
-					...loc,
+					...this.redacted(loc),
 					capacity: await this.localCapacityOf(loc)
 				})));
 			},
-			getDefaultLocation: async ({ type }) => service.getDefaultLocation(type),
+			getDefaultLocation: async ({ type }) => {
+				const loc = service.getDefaultLocation(type);
+				return loc === null ? null : this.redacted(loc);
+			},
 			listLocationDeclarations: async () => service.listDeclarations(),
-			upsertLocation: async (input) => service.upsertLocation(input),
+			upsertLocation: async (input) => {
+				const stored = service.getLocationById(input.id);
+				const config = restoreRedactedSecrets(input.config, stored?.config, this.secretKeysFor(input.providerId));
+				const saved = service.upsertLocation(config === input.config ? input : {
+					...input,
+					config
+				});
+				return this.redacted(saved);
+			},
 			deleteLocation: async ({ id, force }) => {
 				await service.deleteLocation(id, { force: force === true });
 			},
@@ -1853,6 +2344,7 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			},
 			resolve: async ({ location, relativePath }) => {
 				const loc = service.resolveRef(location);
+				this.refuseRemoteResolve(loc);
 				return (await service.getProviderFor(loc)).resolve({
 					location: loc,
 					relativePath
@@ -1975,6 +2467,8 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 					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 }),
+					listMovers: () => this.ctx.api.recording.listRelocateJobs.query({}),
+					residue: (input) => this.ctx.api.recording.getRelocateResidue.query(input),
 					cancelMove: async (jobId) => (await this.ctx.api.recording.cancelStorageMigrationMove.mutate({ jobId })).cancelled,
 					refresh: async (leaseId) => {
 						await this.ctx.api.recording.refreshStorageLocationsForMigration.mutate({ leaseId });
@@ -1991,6 +2485,8 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 					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 }),
+					listMovers: () => this.ctx.api.pipelineAnalytics.listRelocateMediaJobs.query({}),
+					residue: (input) => this.ctx.api.pipelineAnalytics.countRelocatableMedia.query(input),
 					cancelMove: async (jobId) => (await this.ctx.api.pipelineAnalytics.cancelStorageMigrationMove.mutate({ jobId })).cancelled,
 					refresh: async (leaseId) => {
 						await this.ctx.api.pipelineAnalytics.refreshStorageLocationsForMigration.mutate({ leaseId });
@@ -2006,7 +2502,10 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			plan: (input) => migration.plan(input),
 			start: async (input) => ({ jobId: await migration.start(input) }),
 			status: ({ jobId }) => migration.status(jobId),
-			cancel: async ({ jobId }) => ({ cancelled: await migration.cancel(jobId) })
+			cancel: async ({ jobId }) => ({ cancelled: await migration.cancel(jobId) }),
+			movers: () => migration.movers(),
+			residue: () => migration.residue(),
+			drain: async (input) => ({ jobId: await migration.drain(input) })
 		};
 		await this.seedFromDeclarations();
 		const eventBus = this.ctx.eventBus;
@@ -2149,6 +2648,34 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 		}
 		return out;
 	}
+	/** Declared secret config keys for a provider; empty when unknown. */
+	secretKeysFor(providerId) {
+		return this.secretKeysByProvider.get(providerId) ?? EMPTY_SECRET_KEYS;
+	}
+	/** A location with its provider's declared secrets replaced by the sentinel. */
+	redacted(location) {
+		return redactLocation(location, this.secretKeysFor(location.providerId));
+	}
+	/**
+	* Is this location backed by a provider that serves a genuine local
+	* filesystem? `true` / `false` / `undefined` — see
+	* `StorageOrchestratorService.refuseIncompatibleProvider` for why the
+	* unknown case is kept distinct rather than folded into either answer.
+	*/
+	providerIsNodeLocal(location) {
+		return this.nodeLocalByProvider.get(location.providerId);
+	}
+	/** See the call site in the `resolve` dispatch, and `access-guards.ts`. */
+	refuseRemoteResolve(location) {
+		const refusal = resolveRefusalFor(location, this.providerIsNodeLocal(location));
+		if (refusal === null) return;
+		this.ctx.logger.warn("storage-orchestrator: REFUSED resolve() on a remote-backed location", { meta: {
+			id: location.id,
+			type: location.type,
+			providerId: location.providerId
+		} });
+		throw new Error(refusal);
+	}
 	/** statfs capacity of a location's basePath, walking up to the nearest
 	*  existing ancestor. Null for remote-node locations or unstattable paths. */
 	async localCapacityOf(loc) {
@@ -2236,6 +2763,13 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 	* errno — `EACCES`, `EIO`, a stale NFS handle — is `unknown` and refuses.
 	*/
 	async locationOccupancy(location) {
+		if (!canProbeOccupancyLocally(this.providerIsNodeLocal(location))) {
+			this.ctx.logger.debug("storage-orchestrator: occupancy unknown — location is not backed by a local filesystem", { meta: {
+				id: location.id,
+				providerId: location.providerId
+			} });
+			return "unknown";
+		}
 		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";
@@ -2318,7 +2852,10 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 				error: err instanceof Error ? err.message : String(err)
 			} });
 		});
-		for (const info of infos) this.nodeLocalByProvider.set(info.providerId, info.nodeLocal);
+		for (const info of infos) {
+			this.nodeLocalByProvider.set(info.providerId, info.nodeLocal);
+			this.secretKeysByProvider.set(info.providerId, secretKeysOfProviderInfo(info));
+		}
 	}
 };
 //#endregion