@camstack/system 1.2.201 → 1.2.203

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

@@ -3,10 +3,11 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CcV3k-hD.js");
+const require_dist = require("../../dist-BFvWv_bz.js");
 const require_hub_cap_forward = require("../../hub-cap-forward-DmHNjbB0.js");
 let zod = require("zod");
 let node_crypto = require("node:crypto");
+let _camstack_types_node = require("@camstack/types/node");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = require_chunk.__toESM(node_fs_promises);
 let node_path = require("node:path");
@@ -43,6 +44,17 @@ var NODE_ID_CONFIG_KEY = "__nodeId";
 */
 var ENABLED_CONFIG_KEY = "__enabled";
 /**
+* Reserved key under which the location's typed STATE ({@link
+* StorageLocationMode}, D385) is persisted — same channel, same reason, as
+* {@link NODE_ID_CONFIG_KEY} and {@link ENABLED_CONFIG_KEY}.
+*
+* ABSENT means UNSTAMPED, not `active`: the orchestrator's boot migration folds
+* the legacy `enabled` / `config.readOnly` pair into a mode and writes it once.
+* Reading absence as a state here would do that fold on every read forever,
+* which is the thing D385 removes.
+*/
+var MODE_CONFIG_KEY = "__mode";
+/**
 * `config` is declared `JSON`, so the store hands the surface an object and
 * gets an object back. There is deliberately NO `node_id` column — `nodeId`
 * rides inside the blob under a reserved key (see {@link NODE_ID_CONFIG_KEY}),
@@ -187,13 +199,14 @@ function mapLocationToRow(loc) {
 	const storedConfig = { ...loc.config };
 	if (loc.nodeId !== void 0) storedConfig[NODE_ID_CONFIG_KEY] = loc.nodeId;
 	if (loc.enabled !== void 0) storedConfig[ENABLED_CONFIG_KEY] = loc.enabled;
+	if (loc.mode !== void 0) storedConfig[MODE_CONFIG_KEY] = loc.mode;
 	return {
 		id: loc.id,
 		type: loc.type,
 		display_name: loc.displayName,
 		provider_id: loc.providerId,
 		config: storedConfig,
-		is_default: loc.isDefault ? 1 : 0,
+		is_default: 0,
 		is_system: loc.isSystem ? 1 : 0,
 		created_at: loc.createdAt,
 		updated_at: loc.updatedAt
@@ -216,9 +229,12 @@ function mapRowToLocation(row) {
 	const nodeId = typeof nodeIdRaw === "string" && nodeIdRaw.length > 0 ? nodeIdRaw : void 0;
 	const enabledRaw = storedConfig[ENABLED_CONFIG_KEY];
 	const enabled = typeof enabledRaw === "boolean" ? enabledRaw : void 0;
+	const parsedMode = require_dist.StorageLocationModeSchema.safeParse(storedConfig[MODE_CONFIG_KEY]);
+	const mode = parsedMode.success ? parsedMode.data : void 0;
 	const config = { ...storedConfig };
 	delete config[NODE_ID_CONFIG_KEY];
 	delete config[ENABLED_CONFIG_KEY];
+	delete config[MODE_CONFIG_KEY];
 	return {
 		id,
 		type,
@@ -227,7 +243,8 @@ function mapRowToLocation(row) {
 		config,
 		...nodeId !== void 0 ? { nodeId } : {},
 		...enabled !== void 0 ? { enabled } : {},
-		isDefault: row["is_default"] === 1 || row["is_default"] === true,
+		...mode !== void 0 ? { mode } : {},
+		...require_dist.LegacyStorageLocationDefaultSchema.parse({ isDefault: row["is_default"] === 1 || row["is_default"] === true }),
 		isSystem: row["is_system"] === 1 || row["is_system"] === true,
 		createdAt: Number(row["created_at"] ?? 0),
 		updatedAt: Number(row["updated_at"] ?? 0)
@@ -295,16 +312,18 @@ var StorageMigrationCoordinator = class {
 			const targetId = input.destinations[storageClass];
 			if (targetId === void 0) continue;
 			const namedSourceId = input.sources?.[storageClass];
-			const defaultLoc = this.deps.locations.getDefaultLocation(storageClass);
-			const source = namedSourceId ? this.deps.locations.getLocationById(namedSourceId) : defaultLoc;
-			if (!source) throw new Error(namedSourceId ? `Storage location "${namedSourceId}" not found` : `No default storage location for "${storageClass}"`);
+			const writeSet = this.deps.locations.writeTargets(storageClass);
+			const implicitSources = writeSet.filter((loc) => loc.id !== targetId);
+			if (!namedSourceId && implicitSources.length > 1) throw new Error(`"${storageClass}" writes to ${String(implicitSources.length)} locations (${implicitSources.map((loc) => loc.id).join(", ")}) — name the one to cut over explicitly with \`sources\`.`);
+			const source = namedSourceId ? this.deps.locations.getLocationById(namedSourceId) : implicitSources[0];
+			if (!source) throw new Error(namedSourceId ? `Storage location "${namedSourceId}" not found` : `Storage location "${targetId}" is already the only write target for "${storageClass}" — there is nothing to cut over. Use storageMigration.drain to move what is left behind.`);
 			if (source.type !== storageClass) throw new Error(`Storage location "${source.id}" is type "${source.type}", expected "${storageClass}"`);
 			const target = this.deps.locations.getLocationById(targetId);
 			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(namedSourceId ? `Source and destination are the same location ("${targetId}")` : `Storage location "${targetId}" is already the "${storageClass}" default`);
-			const freezeSource = defaultLoc === null || source.id !== defaultLoc.id;
-			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 (source.id === target.id) throw new Error(namedSourceId ? `Source and destination are the same location ("${targetId}")` : `Storage location "${targetId}" is already the only write target for "${storageClass}"`);
+			const freezeSource = !writeSet.some((loc) => loc.id === source.id);
+			if (!MOVER_CLASSES.includes(storageClass)) throw new Error(`No mover owns "${storageClass}" — the migration can move its write set but cannot move its bytes. Move it by hand, then enable the destination (and disable the source) with upsertLocation.`);
 			moves.push({
 				storageClass,
 				fromLocationId: source.id,
@@ -321,7 +340,7 @@ var StorageMigrationCoordinator = class {
 		if (moves.some((move) => move.storageClass === "eventMedia")) {
 			const unstamped = await this.deps.participants.analytics.countUnstamped();
 			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.");
+				if (mode === "nonBlocking") throw new Error("could not determine whether any event-media row still carries no locationId. A non-blocking cutover moves the write set 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",
@@ -330,7 +349,7 @@ var StorageMigrationCoordinator = class {
 			} 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"}" }).`);
+				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.writeTargets("eventMedia")[0]?.id ?? "eventMedia"}" }).`);
 				findings.push({
 					code: "unstampedEventMediaRows",
 					storageClass: "eventMedia",
@@ -469,7 +488,7 @@ var StorageMigrationCoordinator = class {
 	* 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
+	* location outside its write set. 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
@@ -483,11 +502,13 @@ var StorageMigrationCoordinator = class {
 		const out = [];
 		for (const storageClass of STORAGE_CLASSES) {
 			if (!MOVER_CLASSES.includes(storageClass)) continue;
-			const target = this.deps.locations.getDefaultLocation(storageClass);
+			const writeSet = this.deps.locations.writeTargets(storageClass);
+			const target = writeSet[0];
 			if (!target) continue;
+			const inWriteSet = new Set(writeSet.map((loc) => loc.id));
 			if (laneOf(storageClass) === "media") {
 				for (const source of this.deps.locations.listLocations({ type: storageClass })) {
-					if (source.id === target.id) continue;
+					if (inWriteSet.has(source.id)) continue;
 					const count = await unanswerable(this.deps.participants.analytics.residue({
 						toLocationId: target.id,
 						fromLocationId: source.id,
@@ -505,7 +526,7 @@ var StorageMigrationCoordinator = class {
 				continue;
 			}
 			for (const source of this.deps.locations.listLocations({ type: storageClass })) {
-				if (source.id === target.id) continue;
+				if (inWriteSet.has(source.id)) continue;
 				const census = await unanswerable(this.deps.participants.recorder.residue({
 					fromLocationId: source.id,
 					footageClass: storageClass === "recordingsLow" ? "recordingsLow" : "recordings"
@@ -523,12 +544,12 @@ var StorageMigrationCoordinator = class {
 		return out;
 	}
 	/**
-	* Run the DRAIN half alone, against classes whose default has already moved.
+	* Run the DRAIN half alone, against classes whose write set 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
+	* `start` refuses a destination that is already the class's only write target
+	* (`"recordingsLow:ssd" is already the only write target for "recordingsLow"`). 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
@@ -537,7 +558,7 @@ var StorageMigrationCoordinator = class {
 	* 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`
+	* `setWriteTargets`, 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.
@@ -547,7 +568,7 @@ var StorageMigrationCoordinator = class {
 	* 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
+	* and then disabled again). One job = one operation, and the work list comes
 	* from {@link residue} — the archive — not from what a previous job believed.
 	*/
 	async drain(input) {
@@ -570,9 +591,10 @@ var StorageMigrationCoordinator = class {
 			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.`);
+				if (remaining.length === 0) throw new Error(`"${storageClass}" has nothing left outside its write set — 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.`);
+					const target = this.deps.locations.getLocationById(entry.toLocationId);
+					if (target !== void 0 && !require_dist.mayWriteToLocation(target)) throw new Error(`The "${storageClass}" drain destination "${entry.toLocationId}" is not a write target (mode: ${require_dist.resolveLocationMode(target)}) — it takes no writes, and a drain is the largest write there is. Set it active on the Storage screen first.`);
 					moves.push({
 						storageClass,
 						fromLocationId: entry.fromLocationId,
@@ -690,8 +712,13 @@ var StorageMigrationCoordinator = class {
 				await this.setPhase(job, "repointing");
 			}
 			if (job.phase === "repointing") {
-				const targets = new Map(job.moves.filter((move) => move.freezeSource !== true).map((move) => [move.storageClass, move.toLocationId]));
-				if (targets.size > 0) await this.deps.locations.setDefaultLocations(targets);
+				const targets = /* @__PURE__ */ new Map();
+				for (const move of job.moves) {
+					if (move.freezeSource === true) continue;
+					targets.set(move.toLocationId, true);
+					targets.set(move.fromLocationId, false);
+				}
+				if (targets.size > 0) await this.deps.locations.setWriteTargets(targets);
 				job.repointed = true;
 				await this.setPhase(job, "refreshing");
 			}
@@ -890,21 +917,18 @@ var StorageMigrationCoordinator = class {
 		for (const move of job.moves) if (move.state !== "done") throw new Error(`${move.storageClass} move did not complete verification`);
 	}
 	/**
-	* After a from→to copy whose source was NOT the class default: stop new
-	* writes to `from`. The default is unchanged (that is the whole point of
-	* naming a non-default source). A location that is already disabled is
+	* After a from→to copy whose source was NOT a write target: stop new writes
+	* to `from`. The rest of the write set is unchanged (that is the whole point
+	* of naming a source outside it). A location that is already disabled is
 	* left alone.
 	*/
 	freezeDrainedSources(job) {
 		for (const move of job.moves) {
 			if (move.freezeSource !== true) continue;
 			const loc = this.deps.locations.getLocationById(move.fromLocationId);
-			if (!loc || loc.enabled === false) continue;
+			if (!loc || !require_dist.mayWriteToLocation(loc)) continue;
 			const { createdAt: _c, updatedAt: _u, capacity: _cap, ...rest } = loc;
-			this.deps.locations.upsertLocation({
-				...rest,
-				enabled: false
-			});
+			this.deps.locations.upsertLocation(require_dist.withLocationMode(rest, "readonly"));
 		}
 	}
 	/**
@@ -1175,6 +1199,136 @@ function createDataStoreDispatch(getEngines, getRemote) {
 	};
 }
 //#endregion
+//#region src/builtins/storage-orchestrator/drain-state-store.ts
+/**
+* @durable class=config owner=storage-orchestrator
+*   write="one row per location the operator has switched to `drain`, rewritten on every pressure sweep (60 s) while it drains"
+*   retention="the row is deleted the moment the location leaves `drain` mode. Bounded by the number of disks a human is retiring at once."
+*/
+var STORAGE_DRAIN_STATE = "storage_drain_state";
+var STORAGE_DRAIN_STATE_COLUMNS = [
+	{
+		name: "location_id",
+		type: "TEXT",
+		primaryKey: true
+	},
+	{
+		name: "started_at_ms",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "start_bytes",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "cap_bytes",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "last_peer_bytes",
+		type: "INTEGER"
+	},
+	{
+		name: "last_sweep_ms",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "observed_growth_bytes",
+		type: "INTEGER",
+		notNull: true,
+		defaultValue: 0
+	},
+	{
+		name: "observed_elapsed_ms",
+		type: "INTEGER",
+		notNull: true,
+		defaultValue: 0
+	}
+];
+/** A finite number off a persisted row, or the documented fallback. A row
+*  written by a hand-edit must never become a cap. */
+function num(raw, fallback) {
+	return typeof raw === "number" && Number.isFinite(raw) ? raw : fallback;
+}
+function mapRow(row) {
+	const locationId = String(row["location_id"] ?? "");
+	if (!locationId) return null;
+	const lastPeerRaw = row["last_peer_bytes"];
+	return {
+		locationId,
+		startedAtMs: num(row["started_at_ms"], 0),
+		startBytes: num(row["start_bytes"], 0),
+		capBytes: num(row["cap_bytes"], 0),
+		lastPeerBytes: typeof lastPeerRaw === "number" && Number.isFinite(lastPeerRaw) ? lastPeerRaw : null,
+		lastSweepMs: num(row["last_sweep_ms"], 0),
+		observedGrowthBytes: num(row["observed_growth_bytes"], 0),
+		observedElapsedMs: num(row["observed_elapsed_ms"], 0)
+	};
+}
+function mapState(state) {
+	return {
+		location_id: state.locationId,
+		started_at_ms: state.startedAtMs,
+		start_bytes: state.startBytes,
+		cap_bytes: state.capBytes,
+		last_peer_bytes: state.lastPeerBytes,
+		last_sweep_ms: state.lastSweepMs,
+		observed_growth_bytes: state.observedGrowthBytes,
+		observed_elapsed_ms: state.observedElapsedMs
+	};
+}
+/** {@link DrainStateStore} on the `settings-store` collection surface. */
+var SqliteDrainStateStore = class {
+	store;
+	declared = false;
+	constructor(store) {
+		this.store = store;
+	}
+	async ensureDeclared() {
+		if (this.declared) return;
+		await this.store.declareCollection({
+			collection: STORAGE_DRAIN_STATE,
+			columns: STORAGE_DRAIN_STATE_COLUMNS
+		});
+		this.declared = true;
+	}
+	async load() {
+		await this.ensureDeclared();
+		const rows = await this.store.query({ collection: STORAGE_DRAIN_STATE });
+		const out = [];
+		for (const row of rows) {
+			const mapped = mapRow(row.data);
+			if (mapped) out.push(mapped);
+		}
+		return out;
+	}
+	async save(state) {
+		await this.ensureDeclared();
+		await this.store.deleteWhere({
+			collection: STORAGE_DRAIN_STATE,
+			filter: { where: { location_id: state.locationId } }
+		});
+		await this.store.insert({
+			collection: STORAGE_DRAIN_STATE,
+			record: {
+				id: state.locationId,
+				data: mapState(state)
+			}
+		});
+	}
+	async clear(locationId) {
+		await this.ensureDeclared();
+		await this.store.deleteWhere({
+			collection: STORAGE_DRAIN_STATE,
+			filter: { where: { location_id: locationId } }
+		});
+	}
+};
+//#endregion
 //#region src/builtins/storage-orchestrator/hub-settings-forward.ts
 /**
 * The data door with the HUB behind it — an agent's `settings-store` provider.
@@ -1386,6 +1540,139 @@ async function probeLocalDirectoryOccupancy(input) {
 	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. */
+var DEFAULT_STALE_AFTER_MS = 6e4;
+var LocationOccupancySlice = class {
+	deps;
+	slice = /* @__PURE__ */ new Map();
+	refreshing = null;
+	lastRefreshMs = 0;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/**
+	* What the last completed refresh saw for this location, or `undefined` when
+	* nothing has reported for it. There is deliberately no fallback: unknown is
+	* the truth about a location nobody owns bytes on.
+	*/
+	ownedFor(locationId) {
+		return this.slice.get(locationId);
+	}
+	/**
+	* Serve-and-revalidate. Called by every read: it returns immediately, and
+	* kicks a background refresh when the slice is older than the window. A read
+	* never awaits, and never joins a refresh already in flight (D224).
+	*/
+	serveAndRevalidate() {
+		if (this.refreshing !== null) return;
+		const staleAfter = this.deps.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+		if (this.lastRefreshMs !== 0 && this.deps.now() - this.lastRefreshMs < staleAfter) return;
+		this.refresh();
+	}
+	/**
+	* Ask every provider once and replace the slice.
+	*
+	* A provider that throws contributes NOTHING and is logged — it does not
+	* contribute a zero, and it does not take the other providers' answers down
+	* with it. A location that ends up with no contribution at all simply stays
+	* out of the slice, which is what makes it read back as unknown.
+	*/
+	async refresh() {
+		if (this.refreshing !== null) return this.refreshing;
+		this.refreshing = this.runRefresh().finally(() => {
+			this.refreshing = null;
+		});
+		return this.refreshing;
+	}
+	async runRefresh() {
+		const locationIds = [...this.deps.locationIds()];
+		if (locationIds.length === 0) {
+			this.slice = /* @__PURE__ */ new Map();
+			this.lastRefreshMs = this.deps.now();
+			return;
+		}
+		const merged = /* @__PURE__ */ new Map();
+		for (const provider of this.deps.getProviders()) {
+			let reports;
+			try {
+				reports = await provider.getOccupancy({ locationIds });
+			} catch (err) {
+				this.deps.logger.warn("storage-orchestrator: a storage-occupancy provider failed — its bytes are MISSING from this refresh, not counted as zero", { meta: { error: err instanceof Error ? err.message : String(err) } });
+				continue;
+			}
+			for (const report of reports) {
+				const previous = merged.get(report.locationId);
+				merged.set(report.locationId, {
+					bytes: (previous?.bytes ?? 0) + report.ownedBytes,
+					measuredAtMs: previous === void 0 ? report.measuredAtMs : Math.min(previous.measuredAtMs, report.measuredAtMs)
+				});
+			}
+		}
+		this.slice = merged;
+		this.lastRefreshMs = this.deps.now();
+	}
+};
+//#endregion
+//#region src/builtins/storage-orchestrator/location-protection.ts
+/**
+* The protection criterion, in the two units an operator thinks in.
+*
+* The disk-pressure guard has always spoken ONE language — a free-space
+* PERCENTAGE. An operator does not: on a 20 TB array "10%" is 2 TB of headroom
+* nobody asked for, and on a 500 GB SSD it is 50 GB. So a location may instead
+* declare `config.minFreeGb`, and this module converts it to the percentage the
+* guard already speaks using the volume total the orchestrator can already
+* stat.
+*
+* `minFreeGb` WINS when both are present, and the redundancy is logged — two
+* knobs that disagree is the shape D62 forbids, and the one the operator set
+* most recently is not knowable here. `maxUsedGb` stays in the model but stops
+* being an operator knob: it is the internal lever the drain ratchet drives
+* (D386).
+*
+* Pure. Every input is a parameter.
+*/
+/** A finite, non-negative number off the untyped config blob, or `null`.
+*  Garbage must never become a capacity limit. */
+function positiveNumber(raw) {
+	if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) return null;
+	return raw;
+}
+/**
+* The free-space percentage the guard enforces for one location.
+*
+* Order:
+*   1. `config.minFreeGb`, converted against the volume total — the operator's
+*      criterion in the unit they set it in.
+*   2. `config.minFreePercent` — the legacy per-location override, and the
+*      fallback when `minFreeGb` cannot be converted (no volume total: a
+*      remote-node or unstattable location). Falling back is the right
+*      direction — the alternative is a location with no guard at all.
+*   3. the provider's declared default.
+*/
+function resolveMinFreePercent(config, providerDefaultPercent, capacity, notice) {
+	const minFreeGb = positiveNumber(config["minFreeGb"]);
+	const minFreePercent = positiveNumber(config["minFreePercent"]);
+	const fallback = minFreePercent ?? providerDefaultPercent;
+	if (minFreeGb === null) return fallback;
+	if (minFreePercent !== null) notice("storage-orchestrator: location declares BOTH minFreeGb and minFreePercent — minFreeGb wins and minFreePercent is ignored. Remove one.", {
+		minFreeGb,
+		minFreePercent
+	});
+	const totalBytes = capacity?.totalBytes ?? 0;
+	if (totalBytes <= 0) {
+		notice("storage-orchestrator: minFreeGb cannot be converted — the volume total is unknown (remote node, or an unstattable path). Falling back to the percentage guard.", {
+			minFreeGb,
+			fallbackPercent: fallback
+		});
+		return fallback;
+	}
+	const percent = require_dist.gbToBytes(minFreeGb) / totalBytes * 100;
+	return Math.min(100, percent);
+}
+//#endregion
 //#region src/builtins/storage-orchestrator/location-secrets.ts
 /**
 * The config keys the ORCHESTRATOR itself owns, as opposed to the ones a
@@ -1518,8 +1805,13 @@ var FOOTAGE_TYPES = new Set(["recordings", "recordingsLow"]);
 function isTerminal(job) {
 	return job.phase === "done" || job.phase === "failed" || job.phase === "cancelled";
 }
+/**
+* A location whose footage the system will not remove on its own — eviction
+* policy `never` (D385): `readonly` and `disabled`. NOT `drain`, which is
+* shrinking on purpose and whose leftovers the ratchet is already removing.
+*/
 function footageFrozen(location) {
-	return location.enabled === false || location.config["readOnly"] === true;
+	return require_dist.evictionPolicyOfLocation(location) === "never";
 }
 /**
 * One operator-facing cleanup of leftover analytics rows/blobs, optional
@@ -1680,6 +1972,78 @@ var StorageCleanupCoordinator = class {
 	}
 };
 //#endregion
+//#region src/builtins/storage-orchestrator/location-root-collision.ts
+function basePathOf(row) {
+	const raw = row.config["basePath"];
+	return typeof raw === "string" && raw.length > 0 ? raw : null;
+}
+/** Both rows on one node? Absent `nodeId` means the hub (the seed writes
+*  node-blind rows), so the comparison normalises rather than skipping. */
+function sameNode(a, b) {
+	return (a.nodeId ?? "hub") === (b.nodeId ?? "hub");
+}
+/**
+* Does `next` collide with anything already stored?
+*
+* `existing` is every other location; the row being EDITED is excluded by id,
+* so re-saving a location without moving its root never refuses itself.
+*/
+function findRootCollision(next, existing, resolveRoot, storedSelf) {
+	if (storedSelf !== void 0 && basePathOf(storedSelf) === basePathOf(next)) return { outcome: "clear" };
+	const basePath = basePathOf(next);
+	if (basePath === null) return { outcome: "clear" };
+	const root = resolveRoot(basePath);
+	if (!root.resolved) return {
+		outcome: "unknown",
+		unknown: {
+			reason: "unresolvable",
+			detail: `could not resolve "${basePath}" on this node`
+		}
+	};
+	for (const other of existing) {
+		if (other.id === next.id) continue;
+		if (other.type !== next.type) continue;
+		if (!sameNode(other, next)) continue;
+		const otherPath = basePathOf(other);
+		if (otherPath === null) continue;
+		const otherRoot = resolveRoot(otherPath);
+		if (!otherRoot.resolved) continue;
+		if (root.key === otherRoot.key) return {
+			outcome: "collides",
+			collision: {
+				otherId: other.id,
+				type: next.type,
+				sharedRoot: root.key,
+				kind: "equal"
+			}
+		};
+		if ((0, _camstack_types_node.containsOrEquals)(otherRoot.key, root.key)) return {
+			outcome: "collides",
+			collision: {
+				otherId: other.id,
+				type: next.type,
+				sharedRoot: otherRoot.key,
+				kind: "nested"
+			}
+		};
+		if ((0, _camstack_types_node.containsOrEquals)(root.key, otherRoot.key)) return {
+			outcome: "collides",
+			collision: {
+				otherId: other.id,
+				type: next.type,
+				sharedRoot: root.key,
+				kind: "nested"
+			}
+		};
+	}
+	return { outcome: "clear" };
+}
+/** The operator-facing refusal. Names the location it collides with and the
+*  shared root — a refusal that says only "conflict" makes the operator hunt. */
+function rootCollisionMessage(id, collision) {
+	return `Cannot save "${id}": it is ${collision.kind === "equal" ? `the same directory as "${collision.otherId}"` : `nested with "${collision.otherId}" (one is inside the other's tree)`}, and both are type "${collision.type}". Two locations of one type on the same disk share a class subtree, so every per-location figure double-counts and a deletion under one is a deletion under the other. Shared root: ${collision.sharedRoot}. Two locations of DIFFERENT types may share a root — that is how recordings and recordingsLow are configured by default.`;
+}
+//#endregion
 //#region src/builtins/storage-orchestrator/storage-orchestrator.service.ts
 /**
 * Routing core for the `storage-orchestrator` builtin.
@@ -1837,33 +2201,77 @@ var StorageOrchestratorService = class {
 			backfilled: backfill.length,
 			total: this.locations.size
 		} });
-		this.reportDisabledDefaults();
+		this.migrateOntoTheWriteSet(rows);
 	}
 	/**
-	* Shout about a persisted row that is BOTH the type default and disabled.
+	* ONE explicit migration onto the four-state model (D385), run once per boot
+	* against the rows that came off disk. Idempotent: the second boot finds
+	* nothing to do.
 	*
-	* `upsertLocation` can now produce this (enabled is the write set; `isDefault`
-	* is store residue). Hydrate also writes rows straight into the map, so a
-	* hand-edited store or a row written by another build can too. It matters
-	* because every bare-type ref still resolves through {@link getDefaultLocation}
-	* until Stage 5 of the enabled-write-set design: on such a row
-	* `storage.write({ location: 'eventMedia' })` and the migration coordinator's
-	* drain destination both point at a disk the operator turned off.
+	* Two steps, in order, and each one is a WRITE — the point is that "absent"
+	* stops existing rather than being re-interpreted on every read forever:
 	*
-	* 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.
+	*   1. A row with no `mode` is stamped with the mode its legacy flags imply
+	*      (`legacyModeOf`): `config.readOnly === true` → `readonly` and the
+	*      config key is DELETED; `enabled === false` → `readonly` (the
+	*      CONSERVATIVE direction — a state change must never start deleting
+	*      footage on its own); everything else → `active`. `withLocationMode`
+	*      derives `enabled` from the mode, so the two can never disagree, and
+	*      this subsumes the D383 pass that stamped flagless rows `enabled: true`.
+	*   2. A type left with NO write target — only reachable from a hand-edited
+	*      store or a row an older build wrote — gets one made `active`, chosen as
+	*      the row the RETIRED default flag named, else the `:default`-slugged
+	*      row, else the lexicographically first. Loudly: a class with no write
+	*      target records nowhere, and refusing to repair it here would leave the
+	*      hub silently unable to write with no operator action pending.
+	*
+	* An operator's explicit `readonly`/`drain`/`disabled` is never reversed by
+	* step 1 — only step 2 touches it, and only when the alternative is a class
+	* that cannot write at all.
+	*
+	* On the live hub every location is enabled with no `readOnly`, so step 1 is
+	* a no-op that stamps `active` and nothing else changes.
 	*/
-	reportDisabledDefaults() {
+	migrateOntoTheWriteSet(rows) {
+		const legacyDefaultOfType = /* @__PURE__ */ new Map();
+		for (const row of rows) if (row.isDefault === true) legacyDefaultOfType.set(row.type, row.id);
+		const stamped = [];
 		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
+			if (loc.mode !== void 0) continue;
+			this.persistMigrated(require_dist.withLocationMode(loc, require_dist.legacyModeOf(loc) ?? "active"));
+			stamped.push(loc.id);
+		}
+		const repaired = [];
+		for (const type of new Set([...this.locations.values()].map((l) => l.type))) {
+			const ofType = [...this.locations.values()].filter((l) => l.type === type);
+			if (ofType.some((l) => require_dist.isLocationEnabled(l))) continue;
+			const legacyDefault = legacyDefaultOfType.get(type);
+			const pick = ofType.find((l) => l.id === legacyDefault) ?? ofType.find((l) => l.id === `${type}:default`) ?? ofType.toSorted((a, b) => a.id.localeCompare(b.id))[0];
+			if (!pick) continue;
+			this.persistMigrated(require_dist.withLocationMode(pick, "active"));
+			repaired.push(pick.id);
+		}
+		if (stamped.length > 0 || repaired.length > 0) this.logger.info("storage-orchestrator: migrated locations onto the state model", { meta: {
+			stamped,
+			repaired
+		} });
+		for (const id of repaired) this.logger.warn("storage-orchestrator: a storage type had NO enabled location — re-enabled one so it can write. Every other location of that type stays read-only until you enable it.", { meta: { id } });
+	}
+	/** Apply one migrated row in memory and mirror it to the store. */
+	persistMigrated(next) {
+		const withStamp = {
+			...next,
+			updatedAt: Date.now()
+		};
+		this.locations.set(withStamp.id, withStamp);
+		const store = this.locationStore;
+		if (!store) return;
+		store.upsert(withStamp).catch((err) => {
+			this.logger.error("storage-orchestrator: state-model migration persist failed", { meta: {
+				id: withStamp.id,
+				error: err instanceof Error ? err.message : String(err)
 			} });
-		}
+		});
 	}
 	/**
 	* Inject the declaration-driven cardinality source. Called once by the
@@ -1918,7 +2326,7 @@ var StorageOrchestratorService = class {
 		const rows = await this.locationStore.loadAll();
 		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.reportDisabledDefaults();
+		this.migrateOntoTheWriteSet(rows);
 	}
 	/**
 	* Boot backfill (SP1): stamp `nodeId` on every persisted node-local
@@ -1967,40 +2375,50 @@ var StorageOrchestratorService = class {
 		const all = [...this.locations.values()];
 		return filter?.type ? all.filter((l) => l.type === filter.type) : all;
 	}
-	getDefaultLocation(type) {
-		for (const loc of this.locations.values()) if (loc.type === type && loc.isDefault) return loc;
-		return null;
+	/**
+	* The WRITE SET of a type: every enabled location of it, in stable id order.
+	* This replaced `getDefaultLocation` (D383) — a type does not have one write
+	* target any more, it has a pool, and every consumer that must pick one picks
+	* from here by its own rule (the recorder by headroom, a drain by an operator
+	* -named destination).
+	*/
+	writeTargets(type) {
+		return [...this.locations.values()].filter((loc) => loc.type === type && require_dist.isLocationEnabled(loc)).toSorted((a, b) => a.id.localeCompare(b.id));
 	}
 	/**
-	* Repoint several logical defaults as one in-memory commit. The migration
-	* coordinator persists its `repointing` phase before calling this method, so
-	* a process crash during the backing-store writes is recovered by replaying
-	* the same idempotent target set before anyone resumes writers.
+	* Change the WRITE SET as one compensated commit: each named location is
+	* enabled (it joins the pool) or disabled (it becomes read-only — still read,
+	* still played back, still age-swept, still drained).
+	*
+	* This is the cutover verb, and its only caller is the migration coordinator,
+	* which persists its `repointing` phase BEFORE calling so a crash mid-write
+	* is recovered by replaying the same idempotent set before writers resume.
+	*
+	* It moves ONLY the locations it is given: a cutover from A to C on a class
+	* that also writes to B leaves B in the pool, because the operator's pool is
+	* the authority and a migration is not a licence to shrink it. The commit is
+	* refused when it would leave a write-serving type with nothing enabled —
+	* the same refusal `upsertLocation` applies, judged on the RESULT so an
+	* enable and a disable in one commit are weighed together.
 	*/
-	async setDefaultLocations(targetByType) {
-		if (targetByType.size === 0) return;
+	async setWriteTargets(enabledByLocationId) {
+		if (enabledByLocationId.size === 0) return;
 		const now = Date.now();
 		const nextById = new Map(this.locations);
 		const touched = /* @__PURE__ */ new Map();
-		for (const [type, targetId] of targetByType) {
-			const target = nextById.get(targetId);
-			if (!target) throw new Error(`Storage location "${targetId}" not found`);
-			if (target.type !== type) throw new Error(`Storage location "${targetId}" is type "${target.type}", expected "${type}"`);
-			for (const [id, location] of nextById) {
-				if (location.type !== type) continue;
-				const isDefault = id === targetId;
-				const enable = isDefault && location.enabled === false;
-				if (location.isDefault === isDefault && !enable) continue;
-				const updated = {
-					...location,
-					isDefault,
-					...enable ? { enabled: true } : {},
-					updatedAt: now
-				};
-				nextById.set(id, updated);
-				touched.set(id, updated);
-			}
+		for (const [id, enabled] of enabledByLocationId) {
+			const location = nextById.get(id);
+			if (!location) throw new Error(`Storage location "${id}" not found`);
+			if (require_dist.isLocationEnabled(location) === enabled) continue;
+			const updated = require_dist.withLocationMode({
+				...location,
+				updatedAt: now
+			}, enabled ? "active" : "readonly");
+			nextById.set(id, updated);
+			touched.set(id, updated);
 		}
+		if (touched.size === 0) return;
+		refuseTypeWithoutWriteTarget(touched.values(), nextById.values());
 		if (this.locationStore) {
 			const previous = /* @__PURE__ */ new Map();
 			for (const id of touched.keys()) {
@@ -2020,13 +2438,10 @@ var StorageOrchestratorService = class {
 		for (const [id, location] of nextById) this.locations.set(id, location);
 	}
 	/**
-	* Insert or update a location. If `isDefault: true`, atomically
-	* demotes any other default for the same type — operators always see
-	* exactly one default per type.
+	* Insert or update a location.
 	*
-	* When a persistence store is wired (Task 6), the new record AND any
-	* implicitly-demoted siblings are persisted before the in-memory map
-	* mutation returns. Persistence errors propagate to the caller.
+	* When a persistence store is wired (Task 6), the record is mirrored to it;
+	* the mirror is fire-and-forget and its errors reach the logger.
 	*/
 	/**
 	* Refuse a `(location kind, provider)` pair the kind cannot use.
@@ -2102,40 +2517,24 @@ var StorageOrchestratorService = class {
 			...input,
 			nodeId: "hub"
 		};
-		input = {
-			...input,
-			...resolveEnabled(input, existing, this.hasAnyLocationOfType(input.type))
-		};
-		const next = {
+		this.refuseSameTypeRootCollision(input, existing);
+		const next = require_dist.withLocationMode({
 			...input,
 			createdAt: existing?.createdAt ?? now,
 			updatedAt: now
-		};
+		}, resolveUpsertMode(input, existing, this.hasAnyLocationOfType(input.type)));
 		refuseLastWriteTargetDisabled(existing, next, this.locations.values());
-		const demoted = [];
-		if (next.isDefault) {
-			for (const [otherId, otherLoc] of this.locations) if (otherLoc.type === next.type && otherLoc.id !== next.id && otherLoc.isDefault) {
-				const updated = {
-					...otherLoc,
-					isDefault: false,
-					updatedAt: now
-				};
-				this.locations.set(otherId, updated);
-				demoted.push(updated);
-			}
-		}
 		this.locations.set(next.id, next);
 		this.logger.debug("storage-orchestrator: upsertLocation", { meta: {
 			id: next.id,
 			type: next.type,
 			providerId: next.providerId,
-			isDefault: next.isDefault
+			mode: next.mode
 		} });
 		if (this.locationStore) {
 			const store = this.locationStore;
 			(async () => {
 				try {
-					for (const d of demoted) await store.upsert(d);
 					await store.upsert(next);
 				} catch (err) {
 					this.logger.error("storage-orchestrator: upsert persistence failed", { meta: {
@@ -2150,8 +2549,7 @@ var StorageOrchestratorService = class {
 	/**
 	* Remove a location. Refuses the last location of a type and the last
 	* enabled location of a type. `isSystem` is informational — a frozen
-	* recordings `:default` is deletable once a sibling is live. Deleting
-	* the flagged default promotes an enabled sibling. Occupancy still
+	* recordings `:default` is deletable once a sibling is live. Occupancy still
 	* refuses unless `force` is set; force never overrides uniqueness /
 	* last-enabled.
 	*/
@@ -2160,10 +2558,8 @@ var StorageOrchestratorService = class {
 		if (!loc) throw new Error(`Storage location "${id}" not found`);
 		const ofType = [...this.locations.values()].filter((l) => l.type === loc.type);
 		if (ofType.length <= 1) throw new Error(`Cannot delete "${id}" — it is the only location for type "${loc.type}"`);
-		const enabledOfType = ofType.filter((l) => l.enabled !== false);
-		if (loc.enabled !== false && enabledOfType.length <= 1) throw new Error(`Cannot delete "${id}" — it is the only enabled location for type "${loc.type}"`);
-		const successor = loc.isDefault === true ? ofType.find((l) => l.id !== id && l.enabled !== false) : void 0;
-		if (loc.isDefault === true && successor === void 0) throw new Error(`Cannot delete "${id}" — it is the only enabled location for type "${loc.type}"`);
+		const enabledOfType = ofType.filter((l) => require_dist.mayWriteToLocation(l));
+		if (require_dist.mayWriteToLocation(loc) && enabledOfType.length <= 1) throw new Error(`Cannot delete "${id}" — it is the only enabled location for type "${loc.type}"`);
 		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`);
@@ -2173,21 +2569,6 @@ var StorageOrchestratorService = class {
 				occupancy
 			} });
 		}
-		if (successor !== void 0 && successor.isDefault !== true) {
-			const now = Date.now();
-			const promoted = {
-				...successor,
-				isDefault: true,
-				updatedAt: now
-			};
-			this.locations.set(successor.id, promoted);
-			if (this.locationStore) this.locationStore.upsert(promoted).catch((err) => {
-				this.logger.error("storage-orchestrator: default promotion persist failed", { meta: {
-					id: successor.id,
-					error: err instanceof Error ? err.message : String(err)
-				} });
-			});
-		}
 		this.locations.delete(id);
 		if (this.locationStore) this.locationStore.delete(id).catch((err) => {
 			this.logger.error("storage-orchestrator: delete persistence failed", { meta: {
@@ -2266,9 +2647,17 @@ var StorageOrchestratorService = class {
 			if (!loc) throw new Error(`Storage location "${ref}" not found`);
 			return loc;
 		}
-		const def = this.getDefaultLocation(ref);
-		if (!def) throw new Error(`No default storage location configured for type "${ref}" — register one or pass a fully-qualified id (\`<type>:<slug>\`)`);
-		return def;
+		const ofType = [...this.locations.values()].filter((loc) => loc.type === ref);
+		if (ofType.length === 1) return ofType[0];
+		if (ofType.length === 0) throw new Error(`No storage location configured for type "${ref}" — register one or pass a fully-qualified id (\`<type>:<slug>\`)`);
+		const slugged = ofType.find((loc) => loc.id === `${ref}:default`);
+		if (!slugged) throw new Error(`Storage type "${ref}" has ${String(ofType.length)} locations (${ofType.map((loc) => loc.id).toSorted().join(", ")}) — a bare type ref is ambiguous, pass a fully-qualified id (\`<type>:<slug>\`)`);
+		this.logger.warn("storage-orchestrator: DEPRECATED bare-type ref on a type with several locations — resolved to the legacy `:default`-slugged row. Pass a fully-qualified location id.", { meta: {
+			ref,
+			resolved: slugged.id,
+			candidates: ofType.length
+		} });
+		return slugged;
 	}
 	/**
 	* Find the storage-provider that backs a given location — the entry point
@@ -2372,9 +2761,11 @@ var StorageOrchestratorService = class {
 	* declarations on a populated map is a no-op (each declared `id`
 	* already resolves to an existing `<id>:default`).
 	*
-	* Convention: the bare-type ref `'recordings'` resolves via
-	* `getDefaultLocation('recordings')` (walks `isDefault === true`); the
-	* actual stored `id` is `'recordings:default'` so it satisfies the
+	* The seeded row is born ENABLED — a fresh install must be able to write the
+	* moment it boots, and `enabled` is the only write switch there is (D383).
+	* The `:default` suffix is a NAME kept for idempotency across existing
+	* installs, not a flag: the stored `id` is `'recordings:default'` so it
+	* satisfies the
 	* `^[a-z][a-z0-9-]*:[a-z0-9-]+$` regex on `StorageLocationSchema.id`.
 	*
 	* `basePath` is the storage root (e.g. `<CAMSTACK_DATA>`). Each
@@ -2399,7 +2790,7 @@ var StorageOrchestratorService = class {
 				displayName: d.displayName,
 				providerId: input.providerId,
 				config: { basePath: base },
-				isDefault: true,
+				enabled: true,
 				isSystem: false
 			});
 			added++;
@@ -2409,6 +2800,34 @@ var StorageOrchestratorService = class {
 			basePath: input.basePath
 		} });
 	}
+	/**
+	* The same-type physical-root refusal (D389).
+	*
+	* An unresolvable root — another node's disk, a remote provider, a path that
+	* does not exist yet — WARNS and lets the write through. Refusing on a read
+	* that could not be taken blocks the operator on a doubt, and the recorder's
+	* demotion still catches what slips past (D49's spirit).
+	*/
+	refuseSameTypeRootCollision(input, existing) {
+		const verdict = findRootCollision(input, this.locations.values(), this.resolveRoot, existing);
+		if (verdict.outcome === "clear") return;
+		if (verdict.outcome === "unknown") {
+			this.logger.warn("storage-orchestrator: could not check this location for a same-type root collision — saving it anyway. A read that fails is not a refusal; the recorder demotes a same-root duplicate it later finds.", { meta: {
+				id: input.id,
+				type: input.type,
+				...verdict.unknown
+			} });
+			return;
+		}
+		throw new Error(rootCollisionMessage(input.id, verdict.collision));
+	}
+	/** Injectable so a test can drive symlinks and unresolvable paths without
+	*  touching a real filesystem. Production takes the shared derivation. */
+	resolveRoot = (basePath) => (0, _camstack_types_node.physicalRootOf)(basePath);
+	/** Test seam for {@link refuseSameTypeRootCollision}. */
+	setRootResolver(resolveRoot) {
+		this.resolveRoot = resolveRoot;
+	}
 	/** Internal: check whether any location of the given type exists. */
 	hasAnyLocationOfType(type) {
 		for (const loc of this.locations.values()) if (loc.type === type) return true;
@@ -2416,42 +2835,140 @@ var StorageOrchestratorService = class {
 	}
 };
 /**
-* Resolve `enabled` for one upsert — see the call site in `upsertLocation` for
-* the ordered rules. Pure: every input it needs is a parameter.
+* Resolve the MODE one upsert lands on (D385). Pure: every input it needs is a
+* parameter. Ordered rules:
+*
+*   1. An explicit `mode` always wins — the operator named the state.
+*   2. An explicit `enabled` (the retired switch, still on the wire for one
+*      release) means `active` / `readonly`. It can never select `drain` or
+*      `disabled`: those are states only the new field can ask for, so an old
+*      client cannot start erasing a disk or hide footage by accident.
+*   3. On an UPDATE, an omitted state preserves what is stored — a rename or a
+*      path edit must never flip a live write target, and must never cancel a
+*      drain in progress.
+*   4. On a CREATE, an omitted state is `readonly` — creating a disk must not
+*      start writing to it — UNLESS it is the FIRST location of its type, where
+*      there is nothing else that could serve.
 */
-function resolveEnabled(input, existing, typeAlreadyHasLocation) {
-	const requested = input.enabled ?? existing?.enabled;
-	if (requested === void 0) {
-		if (existing) return {};
-		return { enabled: input.isDefault || !typeAlreadyHasLocation };
+function resolveUpsertMode(input, existing, typeAlreadyHasLocation) {
+	if (input.mode !== void 0) {
+		if (input.enabled === void 0 || input.enabled === require_dist.modeMayWrite(input.mode)) return input.mode;
 	}
-	return { enabled: requested };
+	if (input.enabled !== void 0) return input.enabled ? "active" : "readonly";
+	if (existing) return require_dist.resolveLocationMode(existing);
+	return typeAlreadyHasLocation ? "readonly" : "active";
 }
 /** Types that may have zero enabled locations. Backups with none is sad, not illegal. */
 var OPTIONAL_WRITE_TYPES = new Set(["backups"]);
 /**
 * Refuse an UPDATE that would leave a write-serving type with no enabled
 * location. Creates are exempt (an explicit `enabled: false` on the first
-* location is already a named test). `isDefault` is not consulted — enabled
-* is the write set.
+* location is already a named test). Enabled IS the write set.
 */
 function refuseLastWriteTargetDisabled(existing, next, locations) {
 	if (OPTIONAL_WRITE_TYPES.has(next.type)) return;
-	if (next.enabled !== false) return;
+	if (require_dist.mayWriteToLocation(next)) return;
 	if (existing === void 0) return;
-	if (existing.enabled === false) return;
+	if (!require_dist.mayWriteToLocation(existing)) return;
 	for (const loc of locations) {
 		if (loc.id === next.id || loc.type !== next.type) continue;
-		if (loc.enabled !== false) return;
+		if (require_dist.mayWriteToLocation(loc)) return;
 	}
 	throw new Error(`Cannot disable "${next.id}": it is the last enabled location of type "${next.type}". Enable another location of this type first.`);
 }
+/**
+* The same refusal, judged on a whole COMMIT rather than one row: a
+* multi-location change (a cutover enables its destination and disables its
+* source in one go) must be weighed on its RESULT, or the disable half looks
+* like the last write target leaving while the enable half is already in the
+* same map.
+*/
+function refuseTypeWithoutWriteTarget(touched, result) {
+	const rows = [...result];
+	for (const type of new Set([...touched].map((loc) => loc.type))) {
+		if (OPTIONAL_WRITE_TYPES.has(type)) continue;
+		const ofType = rows.filter((loc) => loc.type === type);
+		if (ofType.length === 0) continue;
+		if (ofType.some((loc) => require_dist.isLocationEnabled(loc))) continue;
+		throw new Error(`Refusing the write-set change: it would leave type "${type}" with no enabled location. Enable one of ${ofType.map((loc) => loc.id).toSorted().join(", ")} first.`);
+	}
+}
+//#endregion
+//#region src/builtins/storage-orchestrator/drain-ratchet.ts
+/** The state a drain starts from. No deletion happens on this sweep. */
+function beginDrain(observation) {
+	return {
+		locationId: observation.locationId,
+		startedAtMs: observation.atMs,
+		startBytes: observation.usedBytes,
+		capBytes: observation.usedBytes,
+		lastPeerBytes: observation.peerUsedBytes,
+		lastSweepMs: observation.atMs,
+		observedGrowthBytes: 0,
+		observedElapsedMs: 0
+	};
+}
+/**
+* Advance the ratchet by one sweep. `previous` is `null` on the first sweep of
+* a drain (and after a state the caller cleared), which only ARMS the ratchet:
+* the first growth can be measured no earlier than the second sweep, and a cap
+* derived from no measurement would be a rate the operator never asked for.
+*/
+function stepDrain(previous, observation) {
+	if (previous === null) return {
+		state: beginDrain(observation),
+		capBytes: null,
+		drained: observation.usedBytes <= 0,
+		growthBytes: null
+	};
+	const growthBytes = previous.lastPeerBytes !== null && observation.peerUsedBytes !== null ? observation.peerUsedBytes - previous.lastPeerBytes : null;
+	const ceded = growthBytes !== null && growthBytes > 0 ? growthBytes : 0;
+	const nextCap = Math.max(0, Math.min(previous.capBytes, observation.usedBytes) - ceded);
+	const state = {
+		...previous,
+		capBytes: nextCap,
+		lastPeerBytes: observation.peerUsedBytes ?? previous.lastPeerBytes,
+		lastSweepMs: observation.atMs,
+		observedGrowthBytes: previous.observedGrowthBytes + ceded,
+		observedElapsedMs: growthBytes === null ? previous.observedElapsedMs : previous.observedElapsedMs + Math.max(0, observation.atMs - previous.lastSweepMs)
+	};
+	if (observation.usedBytes <= 0) return {
+		state: {
+			...state,
+			capBytes: 0
+		},
+		capBytes: null,
+		drained: true,
+		growthBytes
+	};
+	return {
+		state,
+		capBytes: nextCap,
+		drained: false,
+		growthBytes
+	};
+}
+/** Progress for a UI, derived from the persisted state and today's usage. */
+function drainProgressOf(state, usedBytes, nowMs) {
+	const bytesRemaining = Math.max(0, usedBytes);
+	const rateBytesPerMs = state.observedGrowthBytes > 0 && state.observedElapsedMs > 0 ? state.observedGrowthBytes / state.observedElapsedMs : null;
+	return {
+		locationId: state.locationId,
+		startedAtMs: state.startedAtMs,
+		startBytes: state.startBytes,
+		bytesRemaining,
+		drained: bytesRemaining <= 0,
+		estimatedEmptyAtMs: rateBytesPerMs === null || bytesRemaining <= 0 ? null : nowMs + Math.ceil(bytesRemaining / rateBytesPerMs)
+	};
+}
 //#endregion
 //#region src/builtins/storage-orchestrator/storage-pressure-manager.ts
 var DEFAULT_MAX_ROUNDS = 8;
 var DEFAULT_HYSTERESIS_PERCENT = 1;
 var StoragePressureManager = class {
 	deps;
+	/** Last sweep's drain progress, by location. Read-only surface for the UI. */
+	drainProgress = /* @__PURE__ */ new Map();
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -2493,6 +3010,73 @@ var StoragePressureManager = class {
 				} });
 			}
 		}
+		await this.sweepDrains();
+	}
+	/**
+	* The drain pass (D386). A `drain` location is excluded from nothing — it is
+	* given a monotonically descending effective usage cap and handed to the SAME
+	* `relieveToUsageCap` machinery every other cap uses. There is no second
+	* eviction path, and no operator-facing rate.
+	*/
+	async sweepDrains() {
+		const plan = await this.deps.getDrainPlan?.() ?? [];
+		const store = this.deps.drainState;
+		if (store === void 0) {
+			if (plan.length > 0) this.deps.logger.warn("storage drain: locations are draining but no durable state store is wired — the ratchet stays inert rather than restarting from scratch every boot", { meta: { locationIds: plan.map((e) => e.locationId) } });
+			this.drainProgress = /* @__PURE__ */ new Map();
+			return;
+		}
+		const persisted = new Map((await store.load()).map((state) => [state.locationId, state]));
+		const draining = new Set(plan.map((entry) => entry.locationId));
+		for (const locationId of persisted.keys()) {
+			if (draining.has(locationId)) continue;
+			await store.clear(locationId);
+			this.drainProgress.delete(locationId);
+			this.deps.logger.info("storage drain: stopped — location is no longer draining", { meta: { locationId } });
+		}
+		const nowMs = Date.now();
+		const progress = /* @__PURE__ */ new Map();
+		for (const entry of plan) try {
+			const usedBytes = await this.evictableUsageOf(entry.locationId);
+			const peerUsedBytes = entry.activePeerLocationIds.length === 0 ? null : await this.evictableUsageOfAll(entry.activePeerLocationIds);
+			const step = stepDrain(persisted.get(entry.locationId) ?? null, {
+				locationId: entry.locationId,
+				usedBytes,
+				peerUsedBytes,
+				atMs: nowMs
+			});
+			await store.save(step.state);
+			this.deps.logger.info("storage drain: sweep", { meta: {
+				locationId: entry.locationId,
+				usedBytes,
+				peerUsedBytes,
+				growthBytes: step.growthBytes,
+				capBytes: step.capBytes,
+				drained: step.drained
+			} });
+			if (step.capBytes !== null) await this.relieveToUsageCap(entry.locationId, step.capBytes);
+			progress.set(entry.locationId, drainProgressOf(step.state, await this.evictableUsageOf(entry.locationId), nowMs));
+		} catch (err) {
+			this.deps.logger.warn("storage drain: sweep failed for location", { meta: {
+				locationId: entry.locationId,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+		this.drainProgress = progress;
+	}
+	/** Progress for every draining location, as of the last sweep. The read a UI
+	*  asks for — it never triggers work of its own. */
+	drainProgressSnapshot() {
+		return [...this.drainProgress.values()];
+	}
+	/** Evictable bytes on one location, summed across every provider. */
+	async evictableUsageOf(locationId) {
+		const providers = this.deps.getEvictableProviders();
+		return (await Promise.all(providers.map(async (p) => (await p.getEvictableUsage({ locationId })).bytes))).reduce((sum, bytes) => sum + bytes, 0);
+	}
+	/** Evictable bytes across a set of locations. */
+	async evictableUsageOfAll(locationIds) {
+		return (await Promise.all(locationIds.map((id) => this.evictableUsageOf(id)))).reduce((sum, bytes) => sum + bytes, 0);
 	}
 	/** Evict oldest-first until the location's evictable usage fits `maxBytes`. */
 	async relieveToUsageCap(locationId, maxBytes) {
@@ -2610,6 +3194,7 @@ var StoragePressureManager = class {
 var STORAGE_PROVIDER_CAP_NAME = "storage-provider";
 var DATA_STORE_PROVIDER_CAP_NAME = "data-store-provider";
 var STORAGE_EVICTABLE_CAP_NAME = "storage-evictable";
+var STORAGE_OCCUPANCY_CAP_NAME = "storage-occupancy";
 /**
 * Single-node default: existing node-local locations live on the hub.
 * The boot backfill (SP1) stamps this on any node-local location seeded
@@ -2627,6 +3212,24 @@ var CAP_PROVIDER_REGISTERED_CATEGORY = "capability:provider-registered";
 var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 	service = null;
 	pressureManager = null;
+	/**
+	* How much of each location CamStack itself holds (D388).
+	*
+	* Built on first use rather than in a field initializer: `this.ctx` does not
+	* exist until `initialize()` runs, and a field initializer touching it throws
+	* in the constructor.
+	*/
+	occupancySlice = null;
+	get occupancy() {
+		if (this.occupancySlice) return this.occupancySlice;
+		this.occupancySlice = new LocationOccupancySlice({
+			logger: this.ctx.logger,
+			getProviders: () => this.ctx.kernel.capabilityRegistry?.getCollection(STORAGE_OCCUPANCY_CAP_NAME) ?? [],
+			locationIds: () => this.service?.listLocations().map((loc) => loc.id) ?? [],
+			now: () => Date.now()
+		});
+		return this.occupancySlice;
+	}
 	pressureTimer = null;
 	pressureSweepInFlight = false;
 	migration = null;
@@ -2685,16 +3288,15 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 		const provider = {
 			listLocations: async ({ type }) => {
 				const rows = type !== void 0 ? service.listLocations({ type }) : service.listLocations();
+				this.occupancy.serveAndRevalidate();
 				return Promise.all(rows.map(async (loc) => ({
 					...this.redacted(loc),
-					capacity: loc.enabled === false ? null : await this.localCapacityOf(loc)
+					...this.occupancy.ownedFor(loc.id) !== void 0 ? { owned: this.occupancy.ownedFor(loc.id) } : {},
+					capacity: require_dist.isLocationEnabled(loc) ? await this.localCapacityOf(loc) : null
 				})));
 			},
-			getDefaultLocation: async ({ type }) => {
-				const loc = service.getDefaultLocation(type);
-				return loc === null ? null : this.redacted(loc);
-			},
 			listLocationDeclarations: async () => service.listDeclarations(),
+			listDrainProgress: async () => this.drainProgress(),
 			upsertLocation: async (input) => {
 				const stored = service.getLocationById(input.id);
 				const config = restoreRedactedSecrets(input.config, stored?.config, this.secretKeysFor(input.providerId, stored?.config ?? {}));
@@ -2702,10 +3304,13 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 					...input,
 					config
 				});
+				this.announceLocationsChanged(saved.id, saved.type, "upsert");
 				return this.redacted(saved);
 			},
 			deleteLocation: async ({ id, force }) => {
+				const doomed = service.getLocationById(id);
 				await service.deleteLocation(id, { force: force === true });
+				this.announceLocationsChanged(id, doomed?.type ?? "", "delete");
 			},
 			testLocation: async ({ id }) => {
 				const loc = service.getLocationById(id);
@@ -2966,7 +3571,17 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 			getEvictableProviders: () => this.ctx.kernel.capabilityRegistry?.getCollection(STORAGE_EVICTABLE_CAP_NAME) ?? [],
 			getLocationThresholds: () => this.resolveLocationThresholds(),
 			getLocationMaxUsedBytes: () => this.resolveLocationMaxUsedBytes(),
-			getLocationDeviceKey: (id) => this.locationDeviceKey(id)
+			getLocationDeviceKey: (id) => this.locationDeviceKey(id),
+			getDrainPlan: () => Promise.resolve(this.resolveDrainPlan()),
+			drainState: {
+				load: async () => await this.resolveDrainStore()?.load() ?? [],
+				save: async (state) => {
+					await this.resolveDrainStore()?.save(state);
+				},
+				clear: async (locationId) => {
+					await this.resolveDrainStore()?.clear(locationId);
+				}
+			}
 		});
 		this.pressureTimer = setInterval(() => {
 			this.runPressureSweep();
@@ -3114,14 +3729,64 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 		const infos = await collectProviderInfos(this.storageProviders(), () => {});
 		const byProvider = new Map(infos.map((i) => [i.providerId, i]));
 		for (const loc of svc.listLocations()) {
+			if (!require_dist.mayReadLocation(loc)) continue;
 			const info = byProvider.get(loc.providerId);
 			if (!info || !info.shouldSaveDiskSpace) continue;
-			const override = loc.config["minFreePercent"];
-			const threshold = typeof override === "number" && Number.isFinite(override) && override >= 0 ? override : info.minFreePercent ?? 0;
+			const threshold = resolveMinFreePercent(loc.config, info.minFreePercent ?? 0, await this.localCapacityOf(loc), (message, meta) => this.logMinFreeRedundancyOnce(loc.id, message, meta));
 			if (threshold > 0) out.set(loc.id, threshold);
 		}
 		return out;
 	}
+	/** Location ids that have already logged the `minFreeGb` / `minFreePercent`
+	*  redundancy. The pressure sweep runs on a timer; the notice is worth
+	*  exactly one line per location per process, not one per minute. */
+	minFreeRedundancyLogged = /* @__PURE__ */ new Set();
+	logMinFreeRedundancyOnce(locationId, message, meta) {
+		if (this.minFreeRedundancyLogged.has(locationId)) return;
+		this.minFreeRedundancyLogged.add(locationId);
+		this.ctx.logger.warn(message, { meta: {
+			locationId,
+			...meta
+		} });
+	}
+	/**
+	* The draining locations and the ACTIVE peers of their class whose growth
+	* paces them (D386). Rebuilt every sweep from the live mode of every
+	* location, so this is also what STOPS a drain: a location the operator
+	* switched back simply stops appearing.
+	*/
+	drainStore = null;
+	/** The drain ratchet's durable home, once a data-store engine exists. Same
+	*  late-wiring window as the location table — on an agent it is never. */
+	resolveDrainStore() {
+		if (this.drainStore) return this.drainStore;
+		const engine = this.ctx.kernel.capabilityRegistry?.getCollection(DATA_STORE_PROVIDER_CAP_NAME)[0];
+		if (!engine) return null;
+		this.drainStore = new SqliteDrainStateStore(engine);
+		return this.drainStore;
+	}
+	drainPlanRefusalLogged = false;
+	resolveDrainPlan() {
+		const svc = this.service;
+		if (!svc) return [];
+		if (this.resolveDrainStore() === null) {
+			const draining = svc.listLocations().filter((l) => require_dist.evictionPolicyOfLocation(l) === "drain");
+			if (draining.length > 0 && !this.drainPlanRefusalLogged) {
+				this.drainPlanRefusalLogged = true;
+				this.ctx.logger.warn("storage-orchestrator: REFUSING to drain — this node has no data-store engine to persist the drain cap, and a cap recomputed at every boot would delete on a pace nobody chose", { meta: { locationIds: draining.map((l) => l.id) } });
+			}
+			return [];
+		}
+		const locations = svc.listLocations();
+		return locations.filter((loc) => require_dist.evictionPolicyOfLocation(loc) === "drain").map((loc) => ({
+			locationId: loc.id,
+			activePeerLocationIds: locations.filter((peer) => peer.type === loc.type && peer.id !== loc.id && require_dist.mayWriteToLocation(peer)).map((peer) => peer.id)
+		}));
+	}
+	/** Drain progress for every draining location, as of the last sweep. */
+	drainProgress() {
+		return this.pressureManager?.drainProgressSnapshot() ?? [];
+	}
 	/**
 	* What the provider's own schema declared secret, or `undefined` when this
 	* node has never heard from that provider. The distinction is the whole
@@ -3134,6 +3799,48 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 	secretKeysFor(providerId, config) {
 		return secretKeysForConfig(config, this.declaredSecretKeys(providerId));
 	}
+	/**
+	* Ring the doorbell: the SET of storage locations changed (D387).
+	*
+	* A consumer that resolves locations at boot had no way to learn that the
+	* operator added, edited or removed one — the recorder kept writing to the
+	* disk set it resolved hours ago, and an operator who added a second
+	* recordings disk in the admin UI got nothing until something unrelated
+	* happened to re-resolve.
+	*
+	* Telemetry, and deliberately so (D8/D11): it carries no row, it is allowed
+	* to be dropped, and every consumer re-reads `listLocations` for itself and
+	* converges on its own periodic path anyway. A bulk edit rings it once per
+	* row — coalescing is the consumer's job, not this one's.
+	*
+	* Never throws into the mutation that produced it: the location IS saved,
+	* and a bus that will not take a telemetry event must not turn that into a
+	* failed upsert.
+	*/
+	announceLocationsChanged(locationId, locationType, reason) {
+		try {
+			this.ctx.eventBus.emit({
+				id: (0, node_crypto.randomUUID)(),
+				timestamp: /* @__PURE__ */ new Date(),
+				source: {
+					type: "addon",
+					id: this.ctx.id
+				},
+				category: require_dist.EventCategory.StorageLocationsChanged,
+				data: {
+					locationId,
+					locationType,
+					reason
+				}
+			});
+		} catch (err) {
+			this.ctx.logger.warn("storage-orchestrator: could not announce the location change — consumers will converge on their own periodic path", { meta: {
+				locationId,
+				reason,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
 	/** A location with its provider's declared secrets replaced by the sentinel. */
 	redacted(location) {
 		return redactLocation(location, this.secretKeysFor(location.providerId, location.config));
@@ -3192,8 +3899,9 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 		const svc = this.service;
 		if (!svc) return out;
 		for (const loc of svc.listLocations()) {
+			if (!require_dist.mayReadLocation(loc)) continue;
 			const raw = loc.config["maxUsedGb"];
-			if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) out.set(loc.id, Math.floor(raw * 1024 ** 3));
+			if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) out.set(loc.id, require_dist.gbToBytes(raw));
 		}
 		return out;
 	}