@camstack/system 1.2.202 → 1.2.203

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

@@ -1,7 +1,8 @@
-import { At as storageCapability, E as StorageMigrationJobSchema, L as collectSecretConfigKeys, Ot as settingsStoreCapability, Rt as BaseAddon, T as StorageLocationTypeSchema, g as REDACTED_SECRET, in as parseJsonObject, jt as storageMigrationCapability, m as LegacyStorageLocationDefaultSchema, rt as isLocationEnabled, w as StorageCleanupJobSchema } from "../../dist-CiHYspij.mjs";
+import { $ as evictionPolicyOfLocation, At as resolveLocationMode, D as StorageMigrationJobSchema, E as StorageLocationTypeSchema, It as settingsStoreCapability, Jt as BaseAddon, Kt as withLocationMode, R as collectSecretConfigKeys, Rt as storageCapability, T as StorageLocationModeSchema, bn as EventCategory, ft as legacyModeOf, g as REDACTED_SECRET, m as LegacyStorageLocationDefaultSchema, mn as parseJsonObject, ot as isLocationEnabled, rt as gbToBytes, vt as mayReadLocation, w as StorageCleanupJobSchema, xt as modeMayWrite, yt as mayWriteToLocation, zt as storageMigrationCapability } from "../../dist-DcMUcdeq.mjs";
 import { t as HUB_CAP_FWD_ACTION } from "../../hub-cap-forward-BdT320dq.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
+import { containsOrEquals, physicalRootOf } from "@camstack/types/node";
 import * as fs from "node:fs/promises";
 import { opendir, readdir } from "node:fs/promises";
 import * as path$1 from "node:path";
@@ -38,6 +39,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}),
@@ -182,6 +194,7 @@ 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,
@@ -211,9 +224,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 = 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,
@@ -222,6 +238,7 @@ function mapRowToLocation(row) {
 		config,
 		...nodeId !== void 0 ? { nodeId } : {},
 		...enabled !== void 0 ? { enabled } : {},
+		...mode !== void 0 ? { mode } : {},
 		...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),
@@ -571,7 +588,8 @@ var StorageMigrationCoordinator = class {
 				const remaining = residue.filter((entry) => entry.storageClass === storageClass);
 				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 first.`);
+					const target = this.deps.locations.getLocationById(entry.toLocationId);
+					if (target !== void 0 && !mayWriteToLocation(target)) throw new Error(`The "${storageClass}" drain destination "${entry.toLocationId}" is not a write target (mode: ${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,
@@ -903,12 +921,9 @@ var StorageMigrationCoordinator = class {
 		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 || !mayWriteToLocation(loc)) continue;
 			const { createdAt: _c, updatedAt: _u, capacity: _cap, ...rest } = loc;
-			this.deps.locations.upsertLocation({
-				...rest,
-				enabled: false
-			});
+			this.deps.locations.upsertLocation(withLocationMode(rest, "readonly"));
 		}
 	}
 	/**
@@ -1179,6 +1194,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.
@@ -1390,6 +1535,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 = 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
@@ -1522,8 +1800,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 evictionPolicyOfLocation(location) === "never";
 }
 /**
 * One operator-facing cleanup of leftover analytics rows/blobs, optional
@@ -1684,6 +1967,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 (containsOrEquals(otherRoot.key, root.key)) return {
+			outcome: "collides",
+			collision: {
+				otherId: other.id,
+				type: next.type,
+				sharedRoot: otherRoot.key,
+				kind: "nested"
+			}
+		};
+		if (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.
@@ -1844,38 +2199,41 @@ var StorageOrchestratorService = class {
 		this.migrateOntoTheWriteSet(rows);
 	}
 	/**
-	* ONE explicit migration onto the enabled write set (D383), run once per
-	* boot against the rows that came off disk. Idempotent: the second boot finds
+	* 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.
 	*
 	* 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:
 	*
-	*   1. A flagless row (persisted before `enabled` existed) is stamped
-	*      `enabled: true`. Absence already meant active, so this preserves
-	*      behaviour exactly; it is the operator's "the initial locations are
-	*      enabled" spelled into the store.
-	*   2. A type left with NO enabled row — only reachable from a hand-edited
-	*      store or a row an older build wrote — gets one enabled back, chosen as
+	*   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 `enabled: false` is never reversed by step 1 — only
-	* step 2 touches it, and only when the alternative is a class that cannot
-	* write at all.
+	* 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.
 	*/
 	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.enabled !== void 0) continue;
-			this.persistMigrated({
-				...loc,
-				enabled: true
-			});
+			if (loc.mode !== void 0) continue;
+			this.persistMigrated(withLocationMode(loc, legacyModeOf(loc) ?? "active"));
 			stamped.push(loc.id);
 		}
 		const repaired = [];
@@ -1885,13 +2243,10 @@ var StorageOrchestratorService = class {
 			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({
-				...pick,
-				enabled: true
-			});
+			this.persistMigrated(withLocationMode(pick, "active"));
 			repaired.push(pick.id);
 		}
-		if (stamped.length > 0 || repaired.length > 0) this.logger.info("storage-orchestrator: migrated locations onto the enabled write set", { meta: {
+		if (stamped.length > 0 || repaired.length > 0) this.logger.info("storage-orchestrator: migrated locations onto the state model", { meta: {
 			stamped,
 			repaired
 		} });
@@ -1907,7 +2262,7 @@ var StorageOrchestratorService = class {
 		const store = this.locationStore;
 		if (!store) return;
 		store.upsert(withStamp).catch((err) => {
-			this.logger.error("storage-orchestrator: write-set migration persist failed", { meta: {
+			this.logger.error("storage-orchestrator: state-model migration persist failed", { meta: {
 				id: withStamp.id,
 				error: err instanceof Error ? err.message : String(err)
 			} });
@@ -2049,12 +2404,11 @@ var StorageOrchestratorService = class {
 		for (const [id, enabled] of enabledByLocationId) {
 			const location = nextById.get(id);
 			if (!location) throw new Error(`Storage location "${id}" not found`);
-			if (location.enabled === enabled) continue;
-			const updated = {
+			if (isLocationEnabled(location) === enabled) continue;
+			const updated = withLocationMode({
 				...location,
-				enabled,
 				updatedAt: now
-			};
+			}, enabled ? "active" : "readonly");
 			nextById.set(id, updated);
 			touched.set(id, updated);
 		}
@@ -2158,22 +2512,19 @@ var StorageOrchestratorService = class {
 			...input,
 			nodeId: "hub"
 		};
-		input = {
-			...input,
-			...resolveEnabled(input, existing, this.hasAnyLocationOfType(input.type))
-		};
-		const next = {
+		this.refuseSameTypeRootCollision(input, existing);
+		const next = withLocationMode({
 			...input,
 			createdAt: existing?.createdAt ?? now,
 			updatedAt: now
-		};
+		}, resolveUpsertMode(input, existing, this.hasAnyLocationOfType(input.type)));
 		refuseLastWriteTargetDisabled(existing, next, this.locations.values());
 		this.locations.set(next.id, next);
 		this.logger.debug("storage-orchestrator: upsertLocation", { meta: {
 			id: next.id,
 			type: next.type,
 			providerId: next.providerId,
-			enabled: next.enabled
+			mode: next.mode
 		} });
 		if (this.locationStore) {
 			const store = this.locationStore;
@@ -2202,8 +2553,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 enabledOfType = ofType.filter((l) => mayWriteToLocation(l));
+		if (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`);
@@ -2444,6 +2795,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) => 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;
@@ -2451,16 +2830,28 @@ 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: !typeAlreadyHasLocation };
+function resolveUpsertMode(input, existing, typeAlreadyHasLocation) {
+	if (input.mode !== void 0) {
+		if (input.enabled === void 0 || input.enabled === modeMayWrite(input.mode)) return input.mode;
 	}
-	return { enabled: requested };
+	if (input.enabled !== void 0) return input.enabled ? "active" : "readonly";
+	if (existing) return 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"]);
@@ -2471,12 +2862,12 @@ var OPTIONAL_WRITE_TYPES = new Set(["backups"]);
 */
 function refuseLastWriteTargetDisabled(existing, next, locations) {
 	if (OPTIONAL_WRITE_TYPES.has(next.type)) return;
-	if (next.enabled !== false) return;
+	if (mayWriteToLocation(next)) return;
 	if (existing === void 0) return;
-	if (existing.enabled === false) return;
+	if (!mayWriteToLocation(existing)) return;
 	for (const loc of locations) {
 		if (loc.id === next.id || loc.type !== next.type) continue;
-		if (loc.enabled !== false) return;
+		if (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.`);
 }
@@ -2498,11 +2889,81 @@ function refuseTypeWithoutWriteTarget(touched, result) {
 	}
 }
 //#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;
 	}
@@ -2544,6 +3005,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) {
@@ -2661,6 +3189,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
@@ -2678,6 +3207,24 @@ var CAP_PROVIDER_REGISTERED_CATEGORY = "capability:provider-registered";
 var StorageOrchestratorAddon = class extends 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;
@@ -2736,12 +3283,15 @@ var StorageOrchestratorAddon = class extends 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),
+					...this.occupancy.ownedFor(loc.id) !== void 0 ? { owned: this.occupancy.ownedFor(loc.id) } : {},
 					capacity: isLocationEnabled(loc) ? await this.localCapacityOf(loc) : null
 				})));
 			},
 			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 ?? {}));
@@ -2749,10 +3299,13 @@ var StorageOrchestratorAddon = class extends 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);
@@ -3013,7 +3566,17 @@ var StorageOrchestratorAddon = class extends 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();
@@ -3161,14 +3724,64 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 		const infos = await collectProviderInfos(this.storageProviders(), () => {});
 		const byProvider = new Map(infos.map((i) => [i.providerId, i]));
 		for (const loc of svc.listLocations()) {
+			if (!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) => 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) => evictionPolicyOfLocation(loc) === "drain").map((loc) => ({
+			locationId: loc.id,
+			activePeerLocationIds: locations.filter((peer) => peer.type === loc.type && peer.id !== loc.id && 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
@@ -3181,6 +3794,48 @@ var StorageOrchestratorAddon = class extends 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: randomUUID(),
+				timestamp: /* @__PURE__ */ new Date(),
+				source: {
+					type: "addon",
+					id: this.ctx.id
+				},
+				category: 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));
@@ -3239,8 +3894,9 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 		const svc = this.service;
 		if (!svc) return out;
 		for (const loc of svc.listLocations()) {
+			if (!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, gbToBytes(raw));
 		}
 		return out;
 	}