@camstack/system 1.2.452 → 1.2.454

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

@@ -1,4 +1,4 @@
-import { $n as resolveLocationMode, Hi as isSecretMarker, Hr as BaseAddon, Ji as normalizeNodeId, Mi as defineRecordKinds, Mn as modeMayWrite, On as mayReadLocation, Tr as withLocationMode, W as LegacyStorageLocationDefaultSchema, Xi as parseJsonObject, ai as REDACTED_SECRET, at as StorageLocationModeSchema, cn as gbToBytes, da as transformSecretWrite, en as evictionPolicyOfLocation, fr as storageCapability, ia as resolveSecretMarkers, it as StorageCleanupJobSchema, kn as mayWriteToLocation, ma as EventCategory, mn as isLocationEnabled, oa as secretTreeFromPaths, or as settingsStoreCapability, ot as StorageLocationTypeSchema, pr as storageMigrationCapability, st as StorageMigrationJobSchema, wi as collectSecretConfigKeys, xn as legacyModeOf } from "../../dist-DV2ll9Hi.mjs";
+import { Ii as defineRecordKinds, In as modeMayWrite, Ki as isSecretMarker, Kr as BaseAddon, Mn as mayReadLocation, Nn as mayWriteToLocation, Oi as collectSecretConfigKeys, Qi as normalizeNodeId, Tn as legacyModeOf, W as LegacyStorageLocationDefaultSchema, _r as storageMigrationCapability, at as StorageLocationModeSchema, ca as resolveSecretMarkers, ea as parseJsonObject, gr as storageCapability, ha as transformSecretWrite, it as StorageCleanupJobSchema, kr as withLocationMode, li as REDACTED_SECRET, nn as evictionPolicyOfLocation, ot as StorageLocationTypeSchema, rr as resolveLocationMode, st as StorageMigrationJobSchema, ua as secretTreeFromPaths, un as gbToBytes, ur as settingsStoreCapability, va as EventCategory, vn as isLocationEnabled } from "../../dist-7ZciHCIp.mjs";
 import { t as require_read_all_rows } from "../../read-all-rows-TaPqdWNF.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
@@ -26,6 +26,7 @@ var StorageLocationBodySchema = z.object({
 	mode: StorageLocationModeSchema.optional(),
 	isDefault: z.boolean().optional()
 });
+var StorageSeedMarkerBodySchema = z.object({ seededAt: z.number() });
 var StorageDrainStateBodySchema = z.object({
 	locationId: z.string(),
 	startedAtMs: z.number(),
@@ -50,6 +51,14 @@ var _storageOrchestratorRecordKinds = defineRecordKinds({
 		retention: { none: "operator delete or declaration prune only" },
 		adoptsFrom: STORAGE_LOCATIONS
 	},
+	"seed-markers": {
+		schema: StorageSeedMarkerBodySchema,
+		class: "config",
+		writeTrigger: "a declared location type was seeded (or found already present on an existing install); the id is the type",
+		device: "none",
+		at: "none",
+		retention: { none: "one row per location type ever seeded — what makes an operator delete stick" }
+	},
 	"drain-state": {
 		schema: StorageDrainStateBodySchema,
 		class: "config",
@@ -183,9 +192,27 @@ var SqliteLocationStore = class {
 	store;
 	declared = false;
 	locationsKind;
-	constructor(store, locationsKind = null) {
+	constructor(store, locationsKind = null, seedMarkersKind = null) {
 		this.store = store;
 		this.locationsKind = locationsKind;
+		this.seedMarkersKind = seedMarkersKind;
+	}
+	seedMarkersKind;
+	static seedMarkersOf(records) {
+		return records.kind(storageOrchestratorRecordKinds["seed-markers"]);
+	}
+	async loadSeededTypes() {
+		const kind = this.seedMarkersKind;
+		if (kind === null) return [];
+		return (await (0, import_read_all_rows.readAllRows)(kind)).map((r) => r.id);
+	}
+	async markTypeSeeded(type) {
+		const kind = this.seedMarkersKind;
+		if (kind === null) return;
+		await kind.put({
+			id: type,
+			data: { seededAt: Date.now() }
+		});
 	}
 	static recordStoresOf(records) {
 		return records.kind(storageOrchestratorRecordKinds.locations);
@@ -1227,6 +1254,111 @@ function buildStorageLocationRegistry(perAddon) {
 	};
 }
 //#endregion
+//#region src/builtins/storage-orchestrator/location-occupancy.ts
+/**
+* Delete-time occupancy of a location's on-disk root.
+*
+* A recordings disk may host several classes at one `basePath`
+* (`<camera>/high|mid`, `<camera>/low`, `<camera>/events`). Occupancy for
+* a class is therefore the class subtree, not the shared root — otherwise a
+* drained `eventMedia:default` still looks full because high footage is
+* writing next to it (observed 2026-09-01).
+*
+* The walk is shallow: one `readdir` of the root (one dirent per camera)
+* plus `opendir`+first-entry of each named subtree. No recursive find of
+* segments — that is the walk that saturates a USB disk.
+*/
+/**
+* Class → directories under `<root>/<camera>/`. Same map as the discard
+* wipe (`DISCARD_SUBTREES` in the recorder / pipeline-analytics addons).
+* Types not listed keep the legacy "any non-dot entry at the root" rule
+* (backups, addon-data, …).
+*/
+var STORAGE_CLASS_SUBTREES = {
+	eventMedia: ["events"],
+	recordingsLow: ["low"],
+	recordings: ["high", "mid"]
+};
+function isDotEntry(name) {
+	return name.startsWith(".");
+}
+/**
+* True when `dir` exists and contains at least one dirent. Missing → false.
+* Any other errno throws so the caller can answer `unknown` (D49).
+*/
+async function dirHasAnyEntry(dir) {
+	let handle;
+	try {
+		handle = await opendir(dir);
+	} catch (err) {
+		if (err.code === "ENOENT") return false;
+		throw err;
+	}
+	try {
+		return await handle.read() !== null;
+	} finally {
+		await handle.close();
+	}
+}
+/**
+* Occupancy of `basePath` for a location of `type`.
+*
+*  - missing root → `empty` (nothing this delete can strand)
+*  - class-mapped type → occupied iff any `<camera>/<subtree>` has an entry
+*  - other types → occupied iff the root has a non-dot entry
+*/
+async function probeLocalDirectoryOccupancy(input) {
+	let names;
+	try {
+		names = await readdir(input.basePath);
+	} catch (err) {
+		if (err.code === "ENOENT") return "empty";
+		return "unknown";
+	}
+	const visible = names.filter((name) => !isDotEntry(name));
+	const subtrees = STORAGE_CLASS_SUBTREES[input.type];
+	if (subtrees === void 0) return visible.length > 0 ? "occupied" : "empty";
+	try {
+		for (const camera of visible) for (const subtree of subtrees) if (await dirHasAnyEntry(path.join(input.basePath, camera, subtree))) return "occupied";
+	} catch {
+		return "unknown";
+	}
+	return "empty";
+}
+//#endregion
+//#region src/builtins/storage-orchestrator/location-class-paths.ts
+/**
+* Which paths under a shared root BELONG to a storage class (D327).
+*
+* A recordings disk hosts several classes at one `basePath`:
+* `<camera>/high|mid` (recordings), `<camera>/low` (recordingsLow),
+* `<camera>/events` (eventMedia) and `homekit-clips/…` (homekitClips). A
+* location may touch only its own subtree; the rest of the root is another
+* location's data. On 2026-10-20 a repoint of `homekitClips:default` walked the
+* WHOLE shared root and deleted ~8.6k event-media files that were not its own.
+*
+* The per-camera map is {@link STORAGE_CLASS_SUBTREES} (the one source, shared
+* with occupancy scoring). A class whose subtree sits at the ROOT, not under a
+* camera, is listed here. A type in neither map owns its whole root (backups,
+* artifacts, …): there is no subtree to scope to.
+*/
+/** Class → top-level directories directly under the root (no camera segment). */
+var STORAGE_CLASS_ROOT_SUBTREES = { homekitClips: ["homekit-clips"] };
+/** Classify a root-relative path (`/` separators) for a location of `type`. */
+function classifyPath(type, relativePath) {
+	const rootSubtrees = STORAGE_CLASS_ROOT_SUBTREES[type];
+	const cameraSubtrees = STORAGE_CLASS_SUBTREES[type];
+	if (rootSubtrees === void 0 && cameraSubtrees === void 0) return "own";
+	const segments = relativePath.split("/").filter((segment) => segment.length > 0);
+	if (rootSubtrees !== void 0) {
+		const top = segments[0];
+		return top !== void 0 && rootSubtrees.includes(top) ? "own" : "foreign";
+	}
+	if (segments.length < 2) return "descend";
+	const subtree = segments[1];
+	return subtree !== void 0 && cameraSubtrees?.includes(subtree) === true ? "own" : "foreign";
+}
+//#endregion
 //#region src/builtins/storage-orchestrator/location-repoint-move.ts
 /**
 * Walk the source root and collect FILES.
@@ -1237,24 +1369,28 @@ function buildStorageLocationRegistry(perAddon) {
 * (an empty directory) is skipped by the copy loop, which is the only place
 * that can tell — and skipping it is right, since there is nothing to move.
 */
-async function collectFiles(io, prefix) {
+async function collectFiles(io, scope, prefix) {
 	const entries = await io.list(prefix);
 	const files = [];
 	for (const entry of entries) {
+		const verdict = scope(entry);
+		if (verdict === "foreign") continue;
 		if ((await io.list(entry)).length > 0) {
-			files.push(...await collectFiles(io, entry));
+			files.push(...await collectFiles(io, scope, entry));
 			continue;
 		}
-		files.push(entry);
+		if (verdict === "own") files.push(entry);
 	}
 	return files;
 }
+/** The whole root — only correct for a class that owns all of it. */
+var WHOLE_ROOT = () => "own";
 /**
 * Copy every file from the source root to the destination, verify each, then
 * delete the originals. Throws with NOTHING deleted if any copy fails.
 */
-async function moveLocationTree(io) {
-	const candidates = await collectFiles(io);
+async function moveLocationTree(io, scope = WHOLE_ROOT) {
+	const candidates = await collectFiles(io, scope);
 	const copied = [];
 	let bytes = 0;
 	for (const relativePath of candidates) {
@@ -1277,6 +1413,121 @@ async function moveLocationTree(io) {
 	};
 }
 //#endregion
+//#region src/builtins/storage-orchestrator/location-repointer.ts
+var RepointRefusedError = class extends Error {
+	reason;
+	name = "RepointRefusedError";
+	constructor(reason, message) {
+		super(message);
+		this.reason = reason;
+	}
+};
+/** Does `a` equal `b`, or sit inside it, or contain it? Segment-wise, never by raw prefix. */
+function rootsOverlap(a, b) {
+	if (a === b) return true;
+	const within = (inner, outer) => inner.startsWith(outer.endsWith("/") ? outer : `${outer}/`);
+	return within(a, b) || within(b, a);
+}
+function basePathOf$1(config) {
+	const raw = config["basePath"];
+	return typeof raw === "string" && raw.length > 0 ? raw : null;
+}
+var LocationRepointer = class {
+	deps;
+	claims = /* @__PURE__ */ new Set();
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/**
+	* Move `stored`'s own subtree to `next`'s root, then run `commit` (the row
+	* save) while the claim is still held. Throws {@link RepointRefusedError}
+	* with NOTHING copied or deleted when a mover is on the root.
+	*/
+	async run(stored, next, commit) {
+		const claim = await this.claim(stored, next);
+		try {
+			await this.refuseWhileMovers(claim, stored);
+			const moved = await moveLocationTree(await this.deps.ioFor(stored, next), (path) => classifyPath(stored.type, path));
+			this.logMoved(stored, next, moved);
+			return await commit();
+		} finally {
+			this.claims.delete(claim);
+		}
+	}
+	/**
+	* May a mover that touches `locationIds` run? Refuses while a repoint holds
+	* an overlapping root. Called by the owning addon AFTER its job is
+	* registered, so the repoint's mover listing and this check cannot both miss.
+	*/
+	async clearance(locationIds) {
+		const keys = await this.keysOf(locationIds);
+		for (const claim of this.claims) if (claim.keys.some((held) => keys.some((key) => rootsOverlap(held, key)))) return {
+			clear: false,
+			reason: "repoint-active",
+			repointLocationId: claim.locationId
+		};
+		return { clear: true };
+	}
+	async claim(stored, next) {
+		const paths = [basePathOf$1(stored.config), basePathOf$1(next.config)].filter((path) => path !== null);
+		const keys = await Promise.all(paths.map((path) => this.deps.resolveKey(path)));
+		for (const other of this.claims) if (other.keys.some((held) => keys.some((key) => rootsOverlap(held, key)))) this.refuse(stored, "repoint-active", `a repoint of "${other.locationId}" holds the same root`);
+		const claim = {
+			locationId: stored.id,
+			keys
+		};
+		this.claims.add(claim);
+		return claim;
+	}
+	async refuseWhileMovers(claim, stored) {
+		let movers;
+		try {
+			movers = await this.deps.listMovers();
+		} catch (err) {
+			this.claims.delete(claim);
+			this.refuse(stored, "movers-unreadable", `the active movers could not be listed (${err instanceof Error ? err.message : String(err)})`);
+		}
+		for (const mover of movers) {
+			if (mover.job.state !== "queued" && mover.job.state !== "running") continue;
+			const touched = await this.keysOf(this.locationsTouchedBy(mover));
+			if (claim.keys.some((held) => touched.some((key) => rootsOverlap(held, key)))) {
+				this.claims.delete(claim);
+				this.refuse(stored, "mover-active", `${mover.lane} mover ${mover.job.jobId} (${mover.job.fromLocationId} -> ${mover.job.toLocationId}) touches the same physical root`, {
+					jobId: mover.job.jobId,
+					lane: mover.lane
+				});
+			}
+		}
+	}
+	locationsTouchedBy(mover) {
+		return [mover.job.fromLocationId, mover.job.toLocationId];
+	}
+	/** `*` is the media mover's "from wherever the rows are": every eventMedia location. */
+	async keysOf(locationIds) {
+		const paths = locationIds.flatMap((id) => id === "*" ? this.deps.locationIdsOfType("eventMedia") : [id]).map((id) => this.deps.locationBasePath(id)).filter((path) => path !== null);
+		return Promise.all(paths.map((path) => this.deps.resolveKey(path)));
+	}
+	refuse(stored, reason, detail, meta = {}) {
+		this.deps.logger.warn("storage-orchestrator: REFUSING to re-point a location — nothing was moved", { meta: {
+			id: stored.id,
+			type: stored.type,
+			reason,
+			detail,
+			...meta
+		} });
+		throw new RepointRefusedError(reason, `re-point of "${stored.id}" refused (${reason}): ${detail}`);
+	}
+	logMoved(stored, next, moved) {
+		this.deps.logger.info("storage-orchestrator: singleton location re-pointed — its data was carried over", { meta: {
+			id: stored.id,
+			type: stored.type,
+			from: basePathOf$1(stored.config),
+			to: basePathOf$1(next.config),
+			...moved
+		} });
+	}
+};
+//#endregion
 //#region src/builtins/storage-orchestrator/access-guards.ts
 /**
 * May `storage.resolve` return a path for this location?
@@ -1776,78 +2027,6 @@ function resolveHubSettingsForward(options) {
 	}, { timeout: HUB_SETTINGS_FORWARD_TIMEOUT_MS }));
 }
 //#endregion
-//#region src/builtins/storage-orchestrator/location-occupancy.ts
-/**
-* Delete-time occupancy of a location's on-disk root.
-*
-* A recordings disk may host several classes at one `basePath`
-* (`<camera>/high|mid`, `<camera>/low`, `<camera>/events`). Occupancy for
-* a class is therefore the class subtree, not the shared root — otherwise a
-* drained `eventMedia:default` still looks full because high footage is
-* writing next to it (observed 2026-09-01).
-*
-* The walk is shallow: one `readdir` of the root (one dirent per camera)
-* plus `opendir`+first-entry of each named subtree. No recursive find of
-* segments — that is the walk that saturates a USB disk.
-*/
-/**
-* Class → directories under `<root>/<camera>/`. Same map as the discard
-* wipe (`DISCARD_SUBTREES` in the recorder / pipeline-analytics addons).
-* Types not listed keep the legacy "any non-dot entry at the root" rule
-* (backups, addon-data, …).
-*/
-var STORAGE_CLASS_SUBTREES = {
-	eventMedia: ["events"],
-	recordingsLow: ["low"],
-	recordings: ["high", "mid"]
-};
-function isDotEntry(name) {
-	return name.startsWith(".");
-}
-/**
-* True when `dir` exists and contains at least one dirent. Missing → false.
-* Any other errno throws so the caller can answer `unknown` (D49).
-*/
-async function dirHasAnyEntry(dir) {
-	let handle;
-	try {
-		handle = await opendir(dir);
-	} catch (err) {
-		if (err.code === "ENOENT") return false;
-		throw err;
-	}
-	try {
-		return await handle.read() !== null;
-	} finally {
-		await handle.close();
-	}
-}
-/**
-* Occupancy of `basePath` for a location of `type`.
-*
-*  - missing root → `empty` (nothing this delete can strand)
-*  - class-mapped type → occupied iff any `<camera>/<subtree>` has an entry
-*  - other types → occupied iff the root has a non-dot entry
-*/
-async function probeLocalDirectoryOccupancy(input) {
-	let names;
-	try {
-		names = await readdir(input.basePath);
-	} catch (err) {
-		if (err.code === "ENOENT") return "empty";
-		return "unknown";
-	}
-	const visible = names.filter((name) => !isDotEntry(name));
-	const subtrees = STORAGE_CLASS_SUBTREES[input.type];
-	if (subtrees === void 0) return visible.length > 0 ? "occupied" : "empty";
-	try {
-		for (const camera of visible) for (const subtree of subtrees) if (await dirHasAnyEntry(path.join(input.basePath, camera, subtree))) return "occupied";
-	} catch {
-		return "unknown";
-	}
-	return "empty";
-}
-//#endregion
 //#region src/builtins/storage-orchestrator/location-occupancy-slice.ts
 /** One minute: the same order as the pressure sweep, and far longer than an
 *  admin-UI repaint. */
@@ -2583,6 +2762,44 @@ var StorageOrchestratorService = class {
 	getLocalNodeId() {
 		return this.localNode;
 	}
+	/**
+	* Whether a seed must wait for an ANSWERED read of the store (D49). True on a
+	* node whose locations live in a store: seeding before that read lands writes
+	* defaults the store's own rows (not yet adopted, or not yet read) then
+	* contradict. False on a node that has no store by design — it seeds in memory
+	* at every boot.
+	*/
+	storeRequiredForSeed = false;
+	setStoreRequiredForSeed(required) {
+		this.storeRequiredForSeed = required;
+	}
+	/**
+	* The location types a default was ever seeded for — null when the store
+	* cannot remember (then a type with no row is seeded, as before). What makes
+	* an operator's delete of a seeded default STICK: zero rows today is not
+	* "fresh install", it is only fresh when nothing was ever seeded.
+	*/
+	seededTypes = null;
+	/** The store held locations but no seed memory: an install older than the memory. */
+	installPredatesSeedMemory = false;
+	async loadSeedMemory(store, rowCount) {
+		if (!store.loadSeededTypes) return;
+		const types = await store.loadSeededTypes();
+		this.seededTypes = new Set(types);
+		this.installPredatesSeedMemory = types.length === 0 && rowCount > 0;
+	}
+	rememberSeeded(type) {
+		const seeded = this.seededTypes;
+		const store = this.locationStore;
+		if (seeded === null || seeded.has(type) || !store?.markTypeSeeded) return;
+		seeded.add(type);
+		store.markTypeSeeded(type).catch((err) => {
+			this.logger.error("storage-orchestrator: persisting the seed memory failed", { meta: {
+				type,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		});
+	}
 	/** True once a persistence store is wired (constructor or {@link attachStore}). */
 	hasStore() {
 		return this.locationStore !== null;
@@ -2616,6 +2833,7 @@ var StorageOrchestratorService = class {
 	async attachStore(store) {
 		if (this.locationStore) return;
 		const rows = await store.loadAll();
+		await this.loadSeedMemory(store, rows.length);
 		this.locationStore = store;
 		const dbIds = new Set(rows.map((r) => r.id));
 		for (const loc of rows) this.locations.set(loc.id, loc);
@@ -2754,6 +2972,7 @@ var StorageOrchestratorService = class {
 	async initialize() {
 		if (!this.locationStore) return;
 		const rows = await this.locationStore.loadAll();
+		await this.loadSeedMemory(this.locationStore, rows.length);
 		for (const loc of rows) this.locations.set(loc.id, loc);
 		this.logger.info("storage-orchestrator: hydrated locations from store", { meta: { loaded: this.locations.size } });
 		this.migrateOntoTheWriteSet(rows);
@@ -3205,14 +3424,35 @@ var StorageOrchestratorService = class {
 	* directory for derivative slots like `recordingsLow` → `recordings`).
 	*/
 	seedDefaults(input) {
+		if (this.storeRequiredForSeed && this.locationStore === null) {
+			this.logger.warn("storage-orchestrator: seed deferred — the location store has not answered a read yet (not wired, adoption pending, or the read failed); seeding now could shadow the operator's existing locations");
+			return {
+				added: 0,
+				deferred: "store-not-answered"
+			};
+		}
 		let added = 0;
+		let deferredProvider = false;
 		const declById = new Map(input.declarations.map((d) => [d.id, d]));
 		const rootFor = (d) => {
 			const dedicated = d.defaultRoot === "media" ? input.mediaBasePath : d.defaultRoot === "backup" ? input.backupBasePath : void 0;
 			return path$1.join(dedicated ?? input.basePath, d.id);
 		};
 		for (const d of input.declarations) {
-			if (this.hasAnyLocationOfType(d.id)) continue;
+			if (this.hasAnyLocationOfType(d.id)) {
+				this.rememberSeeded(d.id);
+				continue;
+			}
+			if (this.seededTypes?.has(d.id)) continue;
+			if (this.installPredatesSeedMemory) {
+				this.logger.info("storage-orchestrator: existing install — not re-creating a default the operator may have removed", { meta: { type: d.id } });
+				this.rememberSeeded(d.id);
+				continue;
+			}
+			if (this.nodeLocalResolver !== null && this.nodeLocalResolver(input.providerId) === void 0) {
+				deferredProvider = true;
+				continue;
+			}
 			const base = d.defaultsTo ? this.getLocationById(`${d.defaultsTo}:default`)?.config["basePath"] ?? rootFor(declById.get(d.defaultsTo) ?? d) : rootFor(d);
 			this.upsertLocation({
 				id: `${d.id}:default`,
@@ -3223,12 +3463,18 @@ var StorageOrchestratorService = class {
 				enabled: true,
 				isSystem: false
 			});
+			this.rememberSeeded(d.id);
 			added++;
 		}
 		if (added > 0) this.logger.info("storage-orchestrator: seeded default locations", { meta: {
 			added,
 			basePath: input.basePath
 		} });
+		if (deferredProvider) this.logger.info("storage-orchestrator: seed deferred for some types — provider not classified yet", { meta: { providerId: input.providerId } });
+		return deferredProvider ? {
+			added,
+			deferred: "provider-unclassified"
+		} : { added };
 	}
 	/**
 	* The same-type physical-root refusal (D389).
@@ -3603,29 +3849,72 @@ var DEFAULT_STORAGE_LOCATION_BAND_CONFIG = {
 	lowPercent: 15,
 	criticalPercent: 5
 };
-function bandOf(freePercent, config) {
-	if (freePercent === null) return {
-		band: "critical",
-		reason: "capacity-unreadable"
-	};
-	if (freePercent <= config.criticalPercent) return {
-		band: "critical",
-		reason: "free-below-critical"
-	};
-	if (freePercent <= config.lowPercent) return {
-		band: "low",
-		reason: "free-below-warn"
+/** Margin, in percentage points, between the enter and exit of an unmanaged edge. */
+var UNMANAGED_HYSTERESIS_POINTS = 2;
+/** Managed: fractions of the floor. */
+var MANAGED_LOW_ENTER = .8;
+var MANAGED_LOW_EXIT = .9;
+var MANAGED_CRITICAL_ENTER = .5;
+var MANAGED_CRITICAL_EXIT = .6;
+/** How long the evictor may sit below the low margin before it counts as behind. */
+var MANAGED_LOW_GRACE_MS = 10 * 6e4;
+function boundsOf(floorPercent, config) {
+	if (floorPercent === void 0) return {
+		lowEnter: config.lowPercent,
+		lowExit: config.lowPercent + UNMANAGED_HYSTERESIS_POINTS,
+		criticalEnter: config.criticalPercent,
+		criticalExit: config.criticalPercent + UNMANAGED_HYSTERESIS_POINTS,
+		lowGraceMs: 0,
+		lowReason: "free-below-warn",
+		criticalReason: "free-below-critical"
 	};
 	return {
-		band: "ok",
-		reason: "free-ok"
+		lowEnter: floorPercent * MANAGED_LOW_ENTER,
+		lowExit: floorPercent * MANAGED_LOW_EXIT,
+		criticalEnter: floorPercent * MANAGED_CRITICAL_ENTER,
+		criticalExit: floorPercent * MANAGED_CRITICAL_EXIT,
+		lowGraceMs: MANAGED_LOW_GRACE_MS,
+		lowReason: "free-below-floor",
+		criticalReason: "free-below-hard-bound"
 	};
 }
 var StorageLocationBandMonitor = class {
 	config;
+	now;
 	band = /* @__PURE__ */ new Map();
-	constructor(config = DEFAULT_STORAGE_LOCATION_BAND_CONFIG) {
+	/** When free first went under `lowEnter` and has stayed there. */
+	belowLowSince = /* @__PURE__ */ new Map();
+	constructor(config = DEFAULT_STORAGE_LOCATION_BAND_CONFIG, now = Date.now) {
 		this.config = config;
+		this.now = now;
+	}
+	nextBand(locationId, previous, free, b) {
+		if (free < b.criticalEnter || previous === "critical" && free < b.criticalExit) return {
+			band: "critical",
+			reason: b.criticalReason
+		};
+		const lowActive = previous === "low" || previous === "critical";
+		if (free < b.lowEnter || lowActive && free < b.lowExit) {
+			if (lowActive) return {
+				band: "low",
+				reason: b.lowReason
+			};
+			const since = this.belowLowSince.get(locationId) ?? this.now();
+			this.belowLowSince.set(locationId, since);
+			if (this.now() - since >= b.lowGraceMs) return {
+				band: "low",
+				reason: b.lowReason
+			};
+			return {
+				band: previous ?? "ok",
+				reason: "free-ok"
+			};
+		}
+		this.belowLowSince.delete(locationId);
+		return {
+			band: "ok",
+			reason: "free-ok"
+		};
 	}
 	/**
 	* Observe one sweep of managed locations. Locations missing from `samples`
@@ -3636,8 +3925,9 @@ var StorageLocationBandMonitor = class {
 		const out = [];
 		for (const sample of samples) {
 			seen.add(sample.locationId);
-			const { band, reason } = bandOf(sample.freePercent, this.config);
+			if (sample.freePercent === null) continue;
 			const previous = this.band.get(sample.locationId) ?? null;
+			const { band, reason } = this.nextBand(sample.locationId, previous, sample.freePercent, boundsOf(sample.floorPercent, this.config));
 			if (previous === band) continue;
 			this.band.set(sample.locationId, band);
 			if (previous === null && band === "ok") continue;
@@ -3647,11 +3937,17 @@ var StorageLocationBandMonitor = class {
 				...sample.locationName !== void 0 ? { locationName: sample.locationName } : {},
 				band,
 				freePercent: sample.freePercent,
+				...sample.floorPercent !== void 0 ? { floorPercent: sample.floorPercent } : {},
+				...sample.freeBytes !== void 0 ? { freeBytes: sample.freeBytes } : {},
+				...sample.floorBytes !== void 0 ? { floorBytes: sample.floorBytes } : {},
 				reason,
 				previous
 			});
 		}
-		for (const id of [...this.band.keys()]) if (!seen.has(id)) this.band.delete(id);
+		for (const id of [...this.band.keys()]) if (!seen.has(id)) {
+			this.band.delete(id);
+			this.belowLowSince.delete(id);
+		}
 		return out;
 	}
 };
@@ -3699,6 +3995,7 @@ var PRESSURE_SWEEP_INTERVAL_MS = 6e4;
 var CAP_PROVIDER_REGISTERED_CATEGORY = "capability:provider-registered";
 var StorageOrchestratorAddon = class extends BaseAddon {
 	locationsKind = null;
+	seedMarkersKind = null;
 	drainStateKind = null;
 	service = null;
 	pressureManager = null;
@@ -3724,6 +4021,8 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 	pressureTimer = null;
 	pressureSweepInFlight = false;
 	migration = null;
+	/** Guards every single-location repoint and arbitrates movers per physical root. */
+	repointer = null;
 	/**
 	* Cached `providerId → nodeLocal` snapshot (SP1). Backs the orchestrator's
 	* synchronous `NodeLocalResolver` — `getProviderInfo()` is async, so we
@@ -3760,6 +4059,7 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 		if (records !== void 0) {
 			await records.declare(storageOrchestratorRecordKinds);
 			this.locationsKind = SqliteLocationStore.recordStoresOf(records);
+			this.seedMarkersKind = SqliteLocationStore.seedMarkersOf(records);
 			this.drainStateKind = SqliteDrainStateStore.recordStoresOf(records);
 		}
 		const getProviders = () => {
@@ -3779,6 +4079,7 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			return proxy;
 		});
 		this.service = service;
+		service.setStoreRequiredForSeed(this.locationsKind !== null);
 		service.setNodeLocalResolver((providerId) => this.nodeLocalByProvider.get(providerId));
 		service.setOccupancyProbe((location) => this.locationOccupancy(location));
 		await service.initialize();
@@ -3802,8 +4103,7 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 					...input,
 					config: keychained
 				};
-				await this.carryDataOnRepoint(stored, next);
-				const saved = service.upsertLocation(next);
+				const saved = await this.upsertCarryingData(stored, next, () => service.upsertLocation(next));
 				this.announceLocationsChanged(saved.id, saved.type, "upsert");
 				return this.redacted(saved);
 			},
@@ -4013,6 +4313,49 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			deviceKeyOf: (locationId) => this.locationDeviceKey(locationId)
 		});
 		this.migration = migration;
+		this.repointer = new LocationRepointer({
+			logger: this.ctx.logger,
+			resolveKey: async (basePath) => {
+				try {
+					return await fs.realpath(basePath);
+				} catch {
+					return path$1.resolve(basePath);
+				}
+			},
+			locationBasePath: (id) => this.locationBasePath(id),
+			locationIdsOfType: (type) => service.listLocations({ type }).map((loc) => loc.id),
+			listMovers: () => migration.movers(),
+			ioFor: async (stored, next) => {
+				const target = {
+					...stored,
+					config: next.config
+				};
+				const [source, destination] = await Promise.all([service.getProviderFor(stored), service.getProviderFor(target)]);
+				return {
+					list: (prefix) => source.list(prefix === void 0 ? { location: stored } : {
+						location: stored,
+						prefix
+					}),
+					read: (relativePath) => source.read({
+						location: stored,
+						relativePath
+					}),
+					write: (relativePath, data) => destination.write({
+						location: target,
+						relativePath,
+						data
+					}),
+					readBack: (relativePath) => destination.read({
+						location: target,
+						relativePath
+					}),
+					deleteSource: (relativePath) => source.delete({
+						location: stored,
+						relativePath
+					})
+				};
+			}
+		});
 		const cleanup = new StorageCleanupCoordinator({
 			locations: service,
 			state: this.state("storage-cleanup", StorageCleanupJobSchema.nullable(), null),
@@ -4048,6 +4391,13 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			status: ({ jobId }) => migration.status(jobId),
 			cancel: async ({ jobId }) => ({ cancelled: await migration.cancel(jobId) }),
 			movers: () => migration.movers(),
+			moverClearance: async ({ locationIds }) => {
+				const verdict = await this.requireRepointer().clearance(locationIds);
+				return verdict.clear ? { clear: true } : {
+					clear: false,
+					repointLocationId: verdict.repointLocationId
+				};
+			},
 			residue: () => migration.residue(),
 			drain: async (input) => ({ jobId: await migration.drain(input) }),
 			cleanupStart: async (input) => ({ jobId: await cleanup.start(input) }),
@@ -4174,7 +4524,7 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			else this.ctx.logger.info("storage-orchestrator: this node boots no data-store engine — storage locations are seeded from addon declarations at every boot, and node-pinned locations live on the hub");
 			return null;
 		}
-		return new SqliteLocationStore(engine, this.locationsKind);
+		return new SqliteLocationStore(engine, this.locationsKind, this.seedMarkersKind);
 	}
 	/**
 	* Late-wire the persistence store once a `data-store-provider` engine
@@ -4186,12 +4536,26 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 	* restart — the service never hydrates from / persists to SQLite.
 	*/
 	storeWireInFlight = null;
+	/** True while the locations kind is empty and its legacy table still holds rows. */
+	async adoptionIsPending() {
+		const records = this.ctx.records;
+		if (records === void 0 || this.locationsKind === null) return false;
+		try {
+			await records.declare(storageOrchestratorRecordKinds);
+			return false;
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			this.ctx.logger.warn("storage-orchestrator: persistence NOT wired — the storage-locations kind is not authoritative yet (adoption pending or the check failed); seeding is deferred", { meta: { error: message } });
+			return true;
+		}
+	}
 	async ensureStoreWired() {
 		const service = this.service;
 		if (!service || service.hasStore()) return;
 		if (this.storeWireInFlight) return this.storeWireInFlight;
 		const store = this.resolveLocationStore(true);
 		if (!store) return;
+		if (await this.adoptionIsPending()) return;
 		this.ctx.logger.info("storage-orchestrator: data-store engine now available — wiring persistence");
 		this.storeWireInFlight = service.attachStore(store).then(() => this.seedFromDeclarations()).catch((err) => {
 			this.ctx.logger.error("storage-orchestrator: attachStore failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
@@ -4220,7 +4584,7 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 	}
 	/**
 	* Sample free space for every managed location and emit NC band edges.
-	* A failed capacity read stays `null` (critical) — never folded to 0 (D393).
+	* A failed capacity read stays `null` and changes no band — never folded to 0 (D393).
 	*/
 	async emitLocationBandEvents() {
 		const svc = this.service;
@@ -4236,11 +4600,18 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			};
 			const capacity = await this.volumeCapacityOf(locationId).catch(() => null);
 			const freePercent = capacity === null ? null : freePercentOf(capacity);
+			if (capacity === null) ctx.logger.debug("storage: location capacity unreadable — band unchanged", { meta: { locationId } });
+			const floorPercent = thresholds.get(locationId);
 			return {
 				locationId,
 				nodeId: loc.nodeId,
 				locationName: loc.displayName,
-				freePercent
+				freePercent,
+				...floorPercent !== void 0 ? { floorPercent } : {},
+				...capacity !== null ? {
+					freeBytes: capacity.availableBytes,
+					...floorPercent !== void 0 ? { floorBytes: Math.round(capacity.totalBytes * floorPercent / 100) } : {}
+				} : {}
 			};
 		}));
 		for (const edge of this.locationBandMonitor.observe(samples)) {
@@ -4249,6 +4620,9 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 				locationId: edge.locationId,
 				band: edge.band,
 				freePercent: edge.freePercent,
+				floorPercent: edge.floorPercent ?? null,
+				freeBytes: edge.freeBytes ?? null,
+				floorBytes: edge.floorBytes ?? null,
 				reason: edge.reason
 			} });
 			ctx.eventBus.emit({
@@ -4362,50 +4736,19 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 	* A no-op for everything else — a rename, a mode change, a `multi` kind, or a
 	* location being created for the first time.
 	*/
-	async carryDataOnRepoint(stored, next) {
-		if (stored === void 0) return;
+	async upsertCarryingData(stored, next, commit) {
+		if (stored === void 0) return commit();
 		const service = this.service;
-		if (service === null) return;
-		if (service.listDeclarations().find((entry) => entry.id === next.type)?.cardinality !== "single") return;
+		if (service === null) return commit();
+		if (service.listDeclarations().find((entry) => entry.id === next.type)?.cardinality !== "single") return commit();
 		const from = stored.config["basePath"];
 		const to = next.config["basePath"];
-		if (typeof from !== "string" || typeof to !== "string" || from === to) return;
-		const source = await service.getProviderFor(stored);
-		const target = {
-			...stored,
-			config: next.config
-		};
-		const destination = await service.getProviderFor(target);
-		const moved = await moveLocationTree({
-			list: (prefix) => source.list(prefix === void 0 ? { location: stored } : {
-				location: stored,
-				prefix
-			}),
-			read: (relativePath) => source.read({
-				location: stored,
-				relativePath
-			}),
-			write: (relativePath, data) => destination.write({
-				location: target,
-				relativePath,
-				data
-			}),
-			readBack: (relativePath) => destination.read({
-				location: target,
-				relativePath
-			}),
-			deleteSource: (relativePath) => source.delete({
-				location: stored,
-				relativePath
-			})
-		});
-		this.ctx.logger.info("storage-orchestrator: singleton location re-pointed — its data was carried over", { meta: {
-			id: stored.id,
-			type: stored.type,
-			from,
-			to,
-			...moved
-		} });
+		if (typeof from !== "string" || typeof to !== "string" || from === to) return commit();
+		return this.requireRepointer().run(stored, next, commit);
+	}
+	requireRepointer() {
+		if (this.repointer === null) throw new Error("storage-orchestrator: not initialized");
+		return this.repointer;
 	}
 	secretKeysFor(providerId, config) {
 		return secretKeysForConfig(config, this.declaredSecretKeys(providerId));