@camstack/system 1.0.2

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

@@ -0,0 +1,1128 @@
+import * as path$1 from "node:path";
+import { BaseAddon, StorageLocationTypeSchema, parseJsonObject, storageCapability } from "@camstack/types";
+import * as fs from "node:fs/promises";
+import { buildStorageLocationRegistry } from "@camstack/system";
+//#region src/builtins/storage-orchestrator/storage-orchestrator.service.ts
+var StorageOrchestratorService = class {
+	logger;
+	getProviders;
+	locationStore;
+	locations = /* @__PURE__ */ new Map();
+	/**
+	* Declaration-driven cardinality source, injected by the addon after
+	* the kernel aggregates `storageLocations` declarations. `null` until
+	* `setRegistry` runs — `upsertLocation` then treats every type as
+	* `'multi'` (no singleton enforcement), the safe default for the
+	* in-memory-only / early-boot path.
+	*/
+	registry = null;
+	/**
+	* Injected `providerId → nodeLocal` resolver (see {@link NodeLocalResolver}).
+	* `null` until {@link setNodeLocalResolver} runs — `upsertLocation` then
+	* skips the node-local requirement check entirely (every provider is
+	* treated as node-agnostic), the safe default for the in-memory-only /
+	* early-boot path that predates the resolver wiring.
+	*/
+	nodeLocalResolver = null;
+	constructor(logger, getProviders, locationStore = null) {
+		this.logger = logger;
+		this.getProviders = getProviders;
+		this.locationStore = locationStore;
+	}
+	/** True once a persistence store is wired (constructor or {@link attachStore}). */
+	hasStore() {
+		return this.locationStore !== null;
+	}
+	/**
+	* Late-bind the persistence store (production boot: the `settings-store`
+	* cap registers after the orchestrator initializes, so the service runs
+	* in-memory-only until then). Idempotent — a second call once a store is
+	* wired is a no-op.
+	*
+	* Reconciles both directions so operator edits survive a reboot:
+	*   1. hydrate — DB rows win over any early in-memory seed (restores
+	*      operator config like `minFreePercent` that the pre-store boot
+	*      can't see), with the same `isSystem` upgrade as {@link initialize};
+	*   2. backfill — in-memory locations the DB doesn't have yet (the
+	*      pre-store seed defaults on a fresh install) are persisted, so the
+	*      store becomes the durable source of truth from here on.
+	*/
+	async attachStore(store) {
+		if (this.locationStore) return;
+		this.locationStore = store;
+		const rows = await store.loadAll();
+		const dbIds = new Set(rows.map((r) => r.id));
+		for (const loc of rows) {
+			const upgraded = !loc.isSystem && loc.id === `${loc.type}:default` ? {
+				...loc,
+				isSystem: true
+			} : loc;
+			this.locations.set(upgraded.id, upgraded);
+			if (upgraded !== loc) store.upsert(upgraded).catch(() => {});
+		}
+		const backfill = [...this.locations.values()].filter((l) => !dbIds.has(l.id));
+		for (const loc of backfill) store.upsert(loc).catch((err) => {
+			this.logger.warn("storage-orchestrator: attachStore backfill persist failed", { meta: {
+				id: loc.id,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		});
+		this.logger.info("storage-orchestrator: store attached + reconciled", { meta: {
+			hydrated: rows.length,
+			backfilled: backfill.length,
+			total: this.locations.size
+		} });
+	}
+	/**
+	* Inject the declaration-driven cardinality source. Called once by the
+	* addon after the kernel aggregates every addon's `storageLocations`
+	* declarations into a `StorageLocationRegistry`.
+	*/
+	setRegistry(registry) {
+		this.registry = registry;
+	}
+	/**
+	* Inject the synchronous `providerId → nodeLocal` resolver (SP1). Called
+	* by the addon from a cached snapshot of every `storage-provider`'s
+	* `getProviderInfo().nodeLocal`, refreshed when the provider collection
+	* changes. Powers the node-local upsert guard and the boot backfill.
+	*/
+	setNodeLocalResolver(resolver) {
+		this.nodeLocalResolver = resolver;
+	}
+	/**
+	* The full set of addon-declared storage locations, as aggregated by
+	* the kernel and injected via {@link setRegistry}. Powers the admin-UI
+	* Data screen's per-declaration grouping. Empty until the registry is
+	* injected (early-boot / in-memory-only path).
+	*/
+	listDeclarations() {
+		return this.registry ? this.registry.list() : [];
+	}
+	/**
+	* Hydrate the in-memory map from the persistence layer. Called once
+	* by the addon during `onInitialize`, before the eager seed pass.
+	* Idempotent — running it twice with the same store contents
+	* produces the same map. No-op when the service was constructed
+	* without a store.
+	*
+	* Errors loading individual rows are tolerated: the bad row is
+	* skipped and logged so a single corrupted record doesn't lock the
+	* whole orchestrator out of boot. (The store-side validation pass
+	* before insert means only schema-invalid SQL state can produce
+	* such a row.)
+	*/
+	async initialize() {
+		if (!this.locationStore) return;
+		const rows = await this.locationStore.loadAll();
+		let upgraded = 0;
+		for (const loc of rows) if (!loc.isSystem && loc.id === `${loc.type}:default`) {
+			const upgradedLoc = {
+				...loc,
+				isSystem: true
+			};
+			this.locations.set(upgradedLoc.id, upgradedLoc);
+			this.locationStore.upsert(upgradedLoc).catch((err) => {
+				this.logger.warn("storage-orchestrator: isSystem upgrade persist failed", { meta: {
+					id: upgradedLoc.id,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			});
+			upgraded++;
+		} else this.locations.set(loc.id, loc);
+		this.logger.info("storage-orchestrator: hydrated locations from store", { meta: {
+			loaded: this.locations.size,
+			isSystemUpgraded: upgraded
+		} });
+	}
+	/**
+	* Boot backfill (SP1): stamp `nodeId` on every persisted node-local
+	* location that lacks one. Single-node deployments seeded their
+	* filesystem locations before `nodeId` existed — they live on `hubNodeId`
+	* (the hub). Node-agnostic (remote) locations are left untouched: their
+	* absent `nodeId` is correct (reachable from any node).
+	*
+	* Idempotent — a location that already carries a `nodeId` (any value) is
+	* never re-touched, so re-running on a populated map (or a re-boot) is a
+	* no-op. A plain local update, not versioned-migration machinery: only
+	* the rows missing `nodeId` are mutated + persisted.
+	*
+	* No-op until the node-local resolver is wired (it classifies which
+	* providers are node-local).
+	*/
+	async backfillNodeIds(hubNodeId) {
+		const resolver = this.nodeLocalResolver;
+		if (!resolver) return;
+		let stamped = 0;
+		for (const [id, loc] of [...this.locations]) {
+			if (loc.nodeId) continue;
+			if (resolver(loc.providerId) !== true) continue;
+			const updated = {
+				...loc,
+				nodeId: hubNodeId,
+				updatedAt: Date.now()
+			};
+			this.locations.set(id, updated);
+			stamped++;
+			if (this.locationStore) try {
+				await this.locationStore.upsert(updated);
+			} catch (err) {
+				this.logger.error("storage-orchestrator: nodeId backfill persist failed", { meta: {
+					id,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			}
+		}
+		if (stamped > 0) this.logger.info("storage-orchestrator: backfilled nodeId on node-local locations", { meta: {
+			stamped,
+			hubNodeId
+		} });
+	}
+	listLocations(filter) {
+		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;
+	}
+	/**
+	* 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.
+	*
+	* 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.
+	*/
+	upsertLocation(input) {
+		const now = Date.now();
+		const existing = this.locations.get(input.id);
+		if (!existing) {
+			if ((this.registry?.cardinalityOf(input.type) ?? "multi") === "single") {
+				const already = [...this.locations.values()].find((l) => l.type === input.type);
+				if (already) throw new Error(`Storage type "${input.type}" is single — only one location allowed (existing: "${already.id}"). Edit it instead of adding a new one.`);
+			}
+		}
+		if (this.nodeLocalResolver?.(input.providerId) === true && !input.nodeId) input = {
+			...input,
+			nodeId: "hub"
+		};
+		if (existing?.isSystem === true) input = {
+			...input,
+			isSystem: true
+		};
+		const next = {
+			...input,
+			createdAt: existing?.createdAt ?? now,
+			updatedAt: now
+		};
+		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
+		} });
+		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: {
+						id: next.id,
+						error: err instanceof Error ? err.message : String(err)
+					} });
+				}
+			})();
+		}
+		return next;
+	}
+	/**
+	* Remove a location. Refuses to remove the default of a type unless a
+	* sibling default exists (defensive — `upsertLocation` already ensures
+	* at most one default per type, but the logic guards against future
+	* bypass paths e.g. SQLite migration that imports two defaults).
+	*
+	* Persistence (Task 6) mirrors the delete asynchronously, with errors
+	* routed to the logger — see `upsertLocation` for the rationale.
+	*/
+	deleteLocation(id) {
+		const loc = this.locations.get(id);
+		if (!loc) throw new Error(`Storage location "${id}" not found`);
+		if (loc.isSystem) throw new Error(`Storage location "${id}" is system-managed and cannot be deleted. Edit its config (path / providerId) instead.`);
+		if (loc.isDefault) {
+			if (![...this.locations.values()].find((l) => l.type === loc.type && l.id !== id && l.isDefault)) throw new Error(`Cannot delete default location "${id}" for type "${loc.type}" — promote another location to default first`);
+		}
+		this.locations.delete(id);
+		if (this.locationStore) this.locationStore.delete(id).catch((err) => {
+			this.logger.error("storage-orchestrator: delete persistence failed", { meta: {
+				id,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		});
+	}
+	/**
+	* Remove system-seeded locations whose type is no longer declared by any
+	* addon (stale defaults from a removed location type). Operator-added
+	* (non-system) locations of an undeclared type are KEPT but warned — the
+	* operator owns them. Requires the registry to be set first.
+	*
+	* FAIL-SAFE: if the registry is EMPTY (no addon declared any location), we
+	* refuse to prune anything. An empty registry almost always means
+	* declarations failed to load (boot ordering, a stale install) — pruning
+	* "everything undeclared" in that state would wipe every system location
+	* (data/logs/recordings/…). Better to keep stale rows than destroy live ones.
+	*/
+	pruneUndeclaredSystemLocations() {
+		if (!this.registry) return;
+		if (this.registry.list().length === 0) {
+			this.logger.warn("storage-orchestrator: skipping prune — no location declarations loaded (fail-safe)");
+			return;
+		}
+		for (const [id, loc] of [...this.locations]) {
+			if (this.registry.cardinalityOf(loc.type) !== null) continue;
+			if (loc.isSystem) {
+				this.locations.delete(id);
+				if (this.locationStore) this.locationStore.delete(id).catch((err) => {
+					this.logger.error("storage-orchestrator: prune persistence failed", { meta: {
+						id,
+						error: err instanceof Error ? err.message : String(err)
+					} });
+				});
+				this.logger.info("storage-orchestrator: pruned stale system location", { meta: {
+					id,
+					type: loc.type
+				} });
+			} else this.logger.warn("storage-orchestrator: location of undeclared type kept (operator-owned)", { meta: {
+				id,
+				type: loc.type
+			} });
+		}
+	}
+	/**
+	* Resolve a `StorageLocationRef` to a concrete `StorageLocation`.
+	*  - bare type (e.g. `'backups'`) → default location of that type
+	*  - fully-qualified id (e.g. `'backups:nas-01'`) → that exact instance
+	*
+	* Throws an actionable error when nothing matches — every consumer of
+	* the singleton `storage` cap funnels through here, so the error
+	* message is what operators see when the orchestrator's view of the
+	* world doesn't match expectations.
+	*/
+	resolveRef(ref) {
+		if (ref.includes(":")) {
+			const loc = this.locations.get(ref);
+			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;
+	}
+	/**
+	* Find the storage-provider that backs a given location. Lookup is by
+	* `location.providerId` against `getProviderInfo().providerId` from
+	* each registered collection provider. Throws with both the missing
+	* providerId and the offending location id so the operator can pick
+	* the right place to fix the config.
+	*/
+	async getProviderFor(location) {
+		const providers = this.getProviders();
+		for (const p of providers) if ((await p.getProviderInfo()).providerId === location.providerId) return p;
+		throw new Error(`No storage-provider registered for providerId "${location.providerId}" (location "${location.id}")`);
+	}
+	/** Convenience: lookup by id (returns `undefined` if not found). */
+	getLocationById(id) {
+		return this.locations.get(id);
+	}
+	/**
+	* Seed one default `StorageLocation` per addon-declared location that
+	* doesn't already have one. Idempotent — re-running with the same
+	* 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
+	* `^[a-z][a-z0-9-]*:[a-z0-9-]+$` regex on `StorageLocationSchema.id`.
+	*
+	* `basePath` is the storage root (e.g. `<CAMSTACK_DATA>`). Each
+	* location's `config.basePath` is `<basePath>/<id>`, except when the
+	* declaration sets `defaultsTo` — then it inherits the resolved root of
+	* the referenced location's default instance (sharing the same root
+	* directory for derivative slots like `recordingsLow` → `recordings`).
+	*/
+	seedDefaults(input) {
+		let added = 0;
+		const rootOf = (id) => path$1.join(input.basePath, id);
+		for (const d of input.declarations) {
+			if (this.hasAnyLocationOfType(d.id)) continue;
+			const base = d.defaultsTo ? this.getLocationById(`${d.defaultsTo}:default`)?.config["basePath"] ?? rootOf(d.defaultsTo) : rootOf(d.id);
+			this.upsertLocation({
+				id: `${d.id}:default`,
+				type: d.id,
+				displayName: d.displayName,
+				providerId: input.providerId,
+				config: { basePath: base },
+				isDefault: true,
+				isSystem: true
+			});
+			added++;
+		}
+		if (added > 0) this.logger.info("storage-orchestrator: seeded default locations", { meta: {
+			added,
+			basePath: input.basePath
+		} });
+	}
+	/** 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;
+		return false;
+	}
+};
+//#endregion
+//#region src/builtins/storage-orchestrator/location-store.ts
+var STORAGE_LOCATIONS_TABLE = "storage_locations";
+/**
+* Reserved key under which the cluster `nodeId` (SP1) is persisted INSIDE
+* the `config` JSON blob. Storing it in the blob rather than a dedicated
+* column avoids a destructive `ensureTable` DROP+recreate on deploy (a
+* newly-declared column counts as a missing column → the structured
+* backend drops the table, wiping operator location customizations such
+* as `recordings:default`'s `minFreePercent`). The double-underscore
+* prefix keeps it out of the provider-facing config namespace
+* (`basePath`, `minFreePercent`, …) — the mapper strips it on read so
+* API consumers and providers never see it.
+*/
+var NODE_ID_CONFIG_KEY = "__nodeId";
+var STORAGE_LOCATIONS_SCHEMA = {
+	columns: [
+		{
+			name: "id",
+			type: "TEXT",
+			primaryKey: true
+		},
+		{
+			name: "type",
+			type: "TEXT",
+			notNull: true
+		},
+		{
+			name: "display_name",
+			type: "TEXT",
+			notNull: true
+		},
+		{
+			name: "provider_id",
+			type: "TEXT",
+			notNull: true
+		},
+		{
+			name: "config",
+			type: "TEXT",
+			notNull: true,
+			defaultValue: "{}"
+		},
+		{
+			name: "is_default",
+			type: "INTEGER",
+			notNull: true,
+			defaultValue: 0
+		},
+		{
+			name: "is_system",
+			type: "INTEGER",
+			notNull: true,
+			defaultValue: 0
+		},
+		{
+			name: "created_at",
+			type: "INTEGER",
+			notNull: true
+		},
+		{
+			name: "updated_at",
+			type: "INTEGER",
+			notNull: true
+		}
+	],
+	indexes: [{
+		name: "idx_storage_locations_type",
+		columns: ["type"]
+	}]
+};
+/**
+* SQLite-backed implementation of `ILocationStore` — uses the
+* `settings-store` cap's structured-table surface (`ensureTable` /
+* `tableInsert` / `tableUpdate` / `tableDelete` / `tableQuery`). Wired
+* to the live `ISettingsBackend` provider obtained from
+* `kernel.capabilityRegistry.getSingleton('settings-store')`.
+*
+* The cap-router surface (`ctx.api.settingsStore.*`) does NOT expose
+* the `tableXxx` methods — they're only on the raw `ISettingsBackend`.
+* Same constraint that drives `IntegrationRegistry` to take a direct
+* provider reference instead of going through the cap.
+*/
+var SqliteLocationStore = class {
+	backend;
+	tableEnsured = false;
+	constructor(backend) {
+		this.backend = backend;
+	}
+	/**
+	* Lazy `ensureTable` — keeps the constructor cheap and async-free.
+	* Called from every mutation/read path; the backend's `ensureTable`
+	* is itself idempotent (additive migration), so repeated calls are
+	* effectively no-ops after the first.
+	*/
+	async ensureTable() {
+		if (this.tableEnsured) return;
+		if (!this.backend.ensureTable) throw new Error("SqliteLocationStore: settings backend does not implement ensureTable — expected the SQLite settings backend, got a backend without structured-table support");
+		await this.backend.ensureTable(STORAGE_LOCATIONS_TABLE, STORAGE_LOCATIONS_SCHEMA);
+		this.tableEnsured = true;
+	}
+	async loadAll() {
+		await this.ensureTable();
+		if (!this.backend.tableQuery) return [];
+		const rows = await this.backend.tableQuery(STORAGE_LOCATIONS_TABLE, { orderBy: {
+			field: "created_at",
+			direction: "asc"
+		} });
+		const out = [];
+		for (const row of rows) {
+			const mapped = mapRowToLocation(row);
+			if (mapped) out.push(mapped);
+		}
+		return out;
+	}
+	/**
+	* Replace-or-insert. Implemented as `delete` + `insert` rather than
+	* the conditional `tableUpdate` path because the orchestrator
+	* serializes every mutation through the in-memory map before
+	* dispatching to the store — there's no contention to lose, and the
+	* delete-then-insert path is unconditionally simpler.
+	*/
+	async upsert(loc) {
+		await this.ensureTable();
+		if (!this.backend.tableDelete || !this.backend.tableInsert) throw new Error("SqliteLocationStore: backend missing tableDelete/tableInsert");
+		await this.backend.tableDelete(STORAGE_LOCATIONS_TABLE, { id: loc.id });
+		await this.backend.tableInsert(STORAGE_LOCATIONS_TABLE, mapLocationToRow(loc));
+	}
+	async delete(id) {
+		await this.ensureTable();
+		if (!this.backend.tableDelete) throw new Error("SqliteLocationStore: backend missing tableDelete");
+		await this.backend.tableDelete(STORAGE_LOCATIONS_TABLE, { id });
+	}
+};
+function mapLocationToRow(loc) {
+	const storedConfig = loc.nodeId !== void 0 ? {
+		...loc.config,
+		[NODE_ID_CONFIG_KEY]: loc.nodeId
+	} : { ...loc.config };
+	return {
+		id: loc.id,
+		type: loc.type,
+		display_name: loc.displayName,
+		provider_id: loc.providerId,
+		config: JSON.stringify(storedConfig),
+		is_default: loc.isDefault ? 1 : 0,
+		is_system: loc.isSystem ? 1 : 0,
+		created_at: loc.createdAt,
+		updated_at: loc.updatedAt
+	};
+}
+/**
+* Decode a row read from the structured table. Returns `null` when the
+* row's `type` doesn't parse against the Zod enum — the caller skips
+* the row and logs. Defensive against schema drift across upgrades
+* (e.g. an older build wrote a since-removed `recordings-archive`
+* type and the new build no longer recognises it).
+*/
+function mapRowToLocation(row) {
+	const typeRaw = row["type"];
+	const parsedType = StorageLocationTypeSchema.safeParse(typeRaw);
+	if (!parsedType.success) return null;
+	const type = parsedType.data;
+	const id = String(row["id"] ?? "");
+	if (!id) return null;
+	const configRaw = row["config"];
+	const storedConfig = typeof configRaw === "string" && configRaw.length > 0 ? parseJsonObject(configRaw) ?? {} : {};
+	const nodeIdRaw = storedConfig[NODE_ID_CONFIG_KEY];
+	const nodeId = typeof nodeIdRaw === "string" && nodeIdRaw.length > 0 ? nodeIdRaw : void 0;
+	const config = { ...storedConfig };
+	delete config[NODE_ID_CONFIG_KEY];
+	return {
+		id,
+		type,
+		displayName: String(row["display_name"] ?? ""),
+		providerId: String(row["provider_id"] ?? ""),
+		config,
+		...nodeId !== void 0 ? { nodeId } : {},
+		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)
+	};
+}
+//#endregion
+//#region src/builtins/storage-orchestrator/provider-discovery.ts
+async function collectProviderInfos(providers, onError) {
+	const out = [];
+	for (const [index, p] of providers.entries()) try {
+		const info = await p.getProviderInfo();
+		out.push(info);
+	} catch (err) {
+		onError(p, err, index);
+	}
+	return out;
+}
+//#endregion
+//#region src/builtins/storage-orchestrator/storage-pressure-manager.ts
+var DEFAULT_MAX_ROUNDS = 8;
+var DEFAULT_HYSTERESIS_PERCENT = 1;
+var StoragePressureManager = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** Relieve every managed location currently under its threshold. */
+	async sweep() {
+		const thresholds = await this.deps.getLocationThresholds();
+		for (const [locationId, threshold] of thresholds) {
+			if (threshold <= 0) continue;
+			try {
+				await this.relieveLocation(locationId, threshold);
+			} catch (err) {
+				this.deps.logger.warn("storage pressure: relief failed for location", { meta: {
+					locationId,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			}
+		}
+	}
+	async relieveLocation(locationId, threshold) {
+		const maxRounds = this.deps.maxRounds ?? DEFAULT_MAX_ROUNDS;
+		const hysteresis = this.deps.hysteresisPercent ?? DEFAULT_HYSTERESIS_PERCENT;
+		for (let round = 0; round < maxRounds; round++) {
+			const free = await this.deps.getFreePercent(locationId);
+			if (free >= threshold) return;
+			const total = await this.deps.getVolumeTotalBytes(locationId);
+			const deficitPercent = threshold - free + hysteresis;
+			const targetBytes = Math.ceil(total * deficitPercent / 100);
+			if (targetBytes <= 0) return;
+			const providers = this.deps.getEvictableProviders();
+			const usages = await Promise.all(providers.map(async (p) => ({
+				p,
+				bytes: (await p.getEvictableUsage({ locationId })).bytes
+			})));
+			const totalEvictable = usages.reduce((s, u) => s + u.bytes, 0);
+			if (totalEvictable <= 0) {
+				this.deps.logger.debug("storage pressure: breach but no evictable data on location", { meta: {
+					locationId,
+					freePercent: free,
+					threshold
+				} });
+				return;
+			}
+			let reclaimed = 0;
+			for (const u of usages) {
+				if (u.bytes <= 0) continue;
+				const share = Math.max(1, Math.ceil(targetBytes * u.bytes / totalEvictable));
+				const res = await u.p.evict({
+					locationId,
+					targetBytes: share
+				});
+				reclaimed += res.reclaimedBytes;
+			}
+			this.deps.logger.info("storage pressure: relief round", { meta: {
+				locationId,
+				round,
+				freePercent: free,
+				threshold,
+				targetBytes,
+				reclaimedBytes: reclaimed
+			} });
+			if (reclaimed <= 0) return;
+		}
+	}
+};
+//#endregion
+//#region src/builtins/storage-orchestrator/storage-orchestrator.addon.ts
+/**
+* `storage-orchestrator` builtin — singleton owner of the consumer-
+* facing `storage` cap.
+*
+* Responsibilities:
+*   - Hold the `locationId → StorageLocation` map (in-memory; Task 6
+*     adds persistence).
+*   - Resolve `StorageLocationRef` → concrete `StorageLocation`.
+*   - Dispatch every cap method to the right `storage-provider`
+*     (collection cap, registered by `filesystem-storage` and future
+*     SFTP / S3 / WebDAV addons).
+*   - Track ownership of upload / download sessions so chunked I/O
+*     (which carries no `location` after the first hop) can route
+*     subsequent chunks to the same provider.
+*   - First-boot seed defaults from addon-declared location types (Task 5).
+*     Re-runs on every `capability:provider-registered` event so providers
+*     that register after the orchestrator boots also get seeded — the
+*     `hasAnyLocationOfType` guard makes the operation idempotent.
+*
+* Task 6 will plug a persistence backend in front of the in-memory map.
+* Task 7 will migrate consumers off the legacy storage shim.
+*/
+var STORAGE_PROVIDER_CAP_NAME = "storage-provider";
+var STORAGE_EVICTABLE_CAP_NAME = "storage-evictable";
+/**
+* Single-node default: existing node-local locations live on the hub.
+* The boot backfill (SP1) stamps this on any node-local location seeded
+* before `nodeId` existed.
+*/
+var HUB_NODE_ID = "hub";
+/** How often the pressure manager re-evaluates free space per location. */
+var PRESSURE_SWEEP_INTERVAL_MS = 6e4;
+/**
+* Raw event category emitted by `CapabilityRegistry.registerProvider` —
+* not in the typed `EventCategory` enum because it lives in the kernel
+* infra layer (every cap-bound event is a custom-shape payload).
+*/
+var CAP_PROVIDER_REGISTERED_CATEGORY = "capability:provider-registered";
+var StorageOrchestratorAddon = class extends BaseAddon {
+	service = null;
+	pressureManager = null;
+	pressureTimer = null;
+	pressureSweepInFlight = false;
+	/**
+	* `uploadId` → providerId. Populated on `beginUpload`, consulted on
+	* every subsequent `writeChunk` / `finalizeUpload` / `abortUpload`,
+	* cleared on terminal calls. The provider holds the actual session
+	* state (open file descriptor, buffered offsets, …) — we just
+	* remember which provider owns it.
+	*/
+	uploadOwners = /* @__PURE__ */ new Map();
+	/** Symmetric to `uploadOwners` for download sessions. */
+	downloadOwners = /* @__PURE__ */ new Map();
+	/**
+	* Cached `providerId → nodeLocal` snapshot (SP1). Backs the orchestrator's
+	* synchronous `NodeLocalResolver` — `getProviderInfo()` is async, so we
+	* keep a sync cache and refresh it whenever the provider collection
+	* changes (alongside the seed pass). Absent providerId → resolver returns
+	* `undefined` (treated as node-agnostic).
+	*/
+	nodeLocalByProvider = /* @__PURE__ */ new Map();
+	/**
+	* Disposers run on `onShutdown` — currently the eventBus subscription
+	* for `capability:provider-registered` events used by the lazy seed
+	* fallback. Stored separately from the `BaseAddon` disposer chain so
+	* it can be inspected in tests.
+	*/
+	seedSubscriptionDisposers = [];
+	constructor() {
+		super({});
+	}
+	async onInitialize() {
+		const getProviders = () => {
+			const reg = this.ctx.kernel.capabilityRegistry;
+			if (!reg) return [];
+			return reg.getCollection(STORAGE_PROVIDER_CAP_NAME);
+		};
+		const locationStore = this.resolveLocationStore();
+		const service = new StorageOrchestratorService(this.ctx.logger, getProviders, locationStore);
+		this.service = service;
+		service.setNodeLocalResolver((providerId) => this.nodeLocalByProvider.get(providerId));
+		await service.initialize();
+		const provider = {
+			listLocations: async ({ type }) => {
+				return type !== void 0 ? service.listLocations({ type }) : service.listLocations();
+			},
+			getDefaultLocation: async ({ type }) => service.getDefaultLocation(type),
+			listLocationDeclarations: async () => service.listDeclarations(),
+			upsertLocation: async (input) => service.upsertLocation(input),
+			deleteLocation: async ({ id }) => {
+				service.deleteLocation(id);
+			},
+			testLocation: async ({ id }) => {
+				const loc = service.getLocationById(id);
+				if (!loc) return {
+					ok: false,
+					error: `Location "${id}" not found`
+				};
+				try {
+					return (await service.getProviderFor(loc)).testLocation({ config: loc.config });
+				} catch (err) {
+					return {
+						ok: false,
+						error: err instanceof Error ? err.message : String(err)
+					};
+				}
+			},
+			listProviders: async () => {
+				return collectProviderInfos(getProviders(), (_provider, err, index) => {
+					this.ctx.logger.warn("storage-orchestrator: getProviderInfo failed", { meta: {
+						providerIndex: index,
+						error: err instanceof Error ? err.message : String(err)
+					} });
+				});
+			},
+			testConfig: async ({ providerId, config }) => {
+				const providers = getProviders();
+				for (const p of providers) try {
+					if ((await p.getProviderInfo()).providerId !== providerId) continue;
+					return p.testLocation({ config });
+				} catch (err) {
+					return {
+						ok: false,
+						error: err instanceof Error ? err.message : String(err)
+					};
+				}
+				return {
+					ok: false,
+					error: `No storage-provider registered for providerId "${providerId}"`
+				};
+			},
+			resolve: async ({ location, relativePath }) => {
+				const loc = service.resolveRef(location);
+				return (await service.getProviderFor(loc)).resolve({
+					location: loc,
+					relativePath
+				});
+			},
+			write: async ({ location, relativePath, data }) => {
+				const loc = service.resolveRef(location);
+				return (await service.getProviderFor(loc)).write({
+					location: loc,
+					relativePath,
+					data
+				});
+			},
+			read: async ({ location, relativePath }) => {
+				const loc = service.resolveRef(location);
+				return (await service.getProviderFor(loc)).read({
+					location: loc,
+					relativePath
+				});
+			},
+			exists: async ({ location, relativePath }) => {
+				const loc = service.resolveRef(location);
+				return (await service.getProviderFor(loc)).exists({
+					location: loc,
+					relativePath
+				});
+			},
+			list: async ({ location, prefix }) => {
+				const loc = service.resolveRef(location);
+				const p = await service.getProviderFor(loc);
+				return prefix !== void 0 ? p.list({
+					location: loc,
+					prefix
+				}) : p.list({ location: loc });
+			},
+			delete: async ({ location, relativePath }) => {
+				const loc = service.resolveRef(location);
+				return (await service.getProviderFor(loc)).delete({
+					location: loc,
+					relativePath
+				});
+			},
+			getAvailableSpace: async ({ location }) => {
+				const loc = service.resolveRef(location);
+				return (await service.getProviderFor(loc)).getAvailableSpace({ location: loc });
+			},
+			beginUpload: async ({ location, relativePath, sizeBytes }) => {
+				const loc = service.resolveRef(location);
+				const p = await service.getProviderFor(loc);
+				const result = sizeBytes !== void 0 ? await p.beginUpload({
+					location: loc,
+					relativePath,
+					sizeBytes
+				}) : await p.beginUpload({
+					location: loc,
+					relativePath
+				});
+				this.uploadOwners.set(result.uploadId, loc.providerId);
+				return result;
+			},
+			writeChunk: async (input) => {
+				return (await this.resolveByUploadId(input.uploadId)).writeChunk(input);
+			},
+			finalizeUpload: async (input) => {
+				const p = await this.resolveByUploadId(input.uploadId);
+				try {
+					return await p.finalizeUpload(input);
+				} finally {
+					this.uploadOwners.delete(input.uploadId);
+				}
+			},
+			abortUpload: async (input) => {
+				const p = await this.resolveByUploadId(input.uploadId);
+				try {
+					return await p.abortUpload(input);
+				} finally {
+					this.uploadOwners.delete(input.uploadId);
+				}
+			},
+			beginDownload: async ({ location, relativePath }) => {
+				const loc = service.resolveRef(location);
+				const result = await (await service.getProviderFor(loc)).beginDownload({
+					location: loc,
+					relativePath
+				});
+				this.downloadOwners.set(result.downloadId, loc.providerId);
+				return result;
+			},
+			readChunk: async (input) => {
+				return (await this.resolveByDownloadId(input.downloadId)).readChunk(input);
+			},
+			endDownload: async (input) => {
+				const p = await this.resolveByDownloadId(input.downloadId);
+				try {
+					return await p.endDownload(input);
+				} finally {
+					this.downloadOwners.delete(input.downloadId);
+				}
+			}
+		};
+		await this.seedFromDeclarations();
+		const eventBus = this.ctx.eventBus;
+		if (eventBus) {
+			const unsub = eventBus.subscribe({ category: CAP_PROVIDER_REGISTERED_CATEGORY }, (event) => {
+				this.ensureStoreWired();
+				if (event.data?.capability !== STORAGE_PROVIDER_CAP_NAME) return;
+				this.seedFromDeclarations();
+			});
+			this.seedSubscriptionDisposers.push(unsub);
+		}
+		this.ensureStoreWired();
+		this.pressureManager = new StoragePressureManager({
+			logger: this.ctx.logger,
+			getFreePercent: (id) => this.locationFreePercent(id),
+			getVolumeTotalBytes: (id) => this.locationVolumeTotalBytes(id),
+			getEvictableProviders: () => this.ctx.kernel.capabilityRegistry?.getCollection(STORAGE_EVICTABLE_CAP_NAME) ?? [],
+			getLocationThresholds: () => this.resolveLocationThresholds()
+		});
+		this.pressureTimer = setInterval(() => {
+			this.runPressureSweep();
+		}, PRESSURE_SWEEP_INTERVAL_MS);
+		this.ctx.logger.info("Storage orchestrator initialized");
+		return [{
+			capability: storageCapability,
+			provider
+		}];
+	}
+	async onShutdown() {
+		for (const dispose of this.seedSubscriptionDisposers) try {
+			dispose();
+		} catch {}
+		this.seedSubscriptionDisposers.length = 0;
+		if (this.pressureTimer) {
+			clearInterval(this.pressureTimer);
+			this.pressureTimer = null;
+		}
+		this.pressureManager = null;
+		this.uploadOwners.clear();
+		this.downloadOwners.clear();
+		this.service = null;
+	}
+	/**
+	* Resolve the live `ISettingsBackend` from the capability registry
+	* and wrap it in a `SqliteLocationStore`. Returns `null` when the
+	* settings-store cap isn't registered yet — the service falls back
+	* to in-memory only. Production boot order (sqlite-settings runs
+	* before the orchestrator) makes this the rare path.
+	*/
+	resolveLocationStore(quiet = false) {
+		const reg = this.ctx.kernel.capabilityRegistry;
+		if (!reg) return null;
+		const backend = reg.getSingleton("settings-store");
+		if (!backend) {
+			if (!quiet) this.ctx.logger.warn("storage-orchestrator: no settings-store provider yet — running in-memory until it registers");
+			return null;
+		}
+		if (!backend.ensureTable || !backend.tableInsert) {
+			if (!quiet) this.ctx.logger.warn("storage-orchestrator: settings backend lacks structured-table support — running in-memory only");
+			return null;
+		}
+		return new SqliteLocationStore(backend);
+	}
+	/**
+	* Late-wire the persistence store once the `settings-store` cap registers.
+	* Production boot order means the store is usually absent at
+	* `onInitialize`; this runs on every `capability:provider-registered`
+	* event until it succeeds. Single-flighted + idempotent (the service
+	* ignores a second attach). Without this, operator edits (e.g. a
+	* location's `minFreePercent`) live only in memory and are wiped on every
+	* restart — the service never hydrates from / persists to SQLite.
+	*/
+	storeWireInFlight = null;
+	async ensureStoreWired() {
+		const service = this.service;
+		if (!service || service.hasStore()) return;
+		if (this.storeWireInFlight) return this.storeWireInFlight;
+		const store = this.resolveLocationStore(true);
+		if (!store) return;
+		this.ctx.logger.info("storage-orchestrator: settings-store now available — wiring persistence");
+		this.storeWireInFlight = service.attachStore(store).then(() => this.seedFromDeclarations()).catch((err) => {
+			this.ctx.logger.error("storage-orchestrator: attachStore failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		}).finally(() => {
+			this.storeWireInFlight = null;
+		});
+		return this.storeWireInFlight;
+	}
+	storageProviders() {
+		const reg = this.ctx.kernel.capabilityRegistry;
+		if (!reg) return [];
+		return reg.getCollection(STORAGE_PROVIDER_CAP_NAME);
+	}
+	/** Single-flighted pressure sweep — never overlaps a slow eviction round. */
+	async runPressureSweep() {
+		if (this.pressureSweepInFlight || !this.pressureManager) return;
+		this.pressureSweepInFlight = true;
+		try {
+			await this.pressureManager.sweep();
+		} catch (err) {
+			this.ctx.logger.warn("storage pressure sweep failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		} finally {
+			this.pressureSweepInFlight = false;
+		}
+	}
+	/**
+	* locationId → resolved `minFreePercent`. The policy is intrinsic to the
+	* location's provider (`shouldSaveDiskSpace` gates the guard, `minFreePercent`
+	* is the default), overridable per-location via `config.minFreePercent`.
+	* Locations with the guard off (or threshold 0) are omitted. Moved here from
+	* the recorder so disk-pressure is a single core concern.
+	*/
+	async resolveLocationThresholds() {
+		const out = /* @__PURE__ */ new Map();
+		const svc = this.service;
+		if (!svc) return out;
+		const infos = await collectProviderInfos(this.storageProviders(), () => {});
+		const byProvider = new Map(infos.map((i) => [i.providerId, i]));
+		for (const loc of svc.listLocations()) {
+			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;
+			if (threshold > 0) out.set(loc.id, threshold);
+		}
+		return out;
+	}
+	locationBasePath(locationId) {
+		const bp = (this.service?.listLocations().find((l) => l.id === locationId))?.config["basePath"];
+		return typeof bp === "string" && bp.length > 0 ? bp : null;
+	}
+	/** Free capacity (%) on a location's volume via `statfs`; 100 (guard inert) when unstattable. */
+	async locationFreePercent(locationId) {
+		const bp = this.locationBasePath(locationId);
+		if (!bp) return 100;
+		try {
+			const st = await fs.statfs(bp);
+			if (st.blocks <= 0) return 100;
+			return st.bavail / st.blocks * 100;
+		} catch {
+			return 100;
+		}
+	}
+	/** Total bytes on a location's volume via `statfs`; 0 when unstattable. */
+	async locationVolumeTotalBytes(locationId) {
+		const bp = this.locationBasePath(locationId);
+		if (!bp) return 0;
+		try {
+			const st = await fs.statfs(bp);
+			return st.blocks * st.bsize;
+		} catch {
+			return 0;
+		}
+	}
+	/**
+	* Seed default storage locations from the addon-declared
+	* `storageLocations`, aggregated by the kernel into a
+	* `StorageLocationRegistry`. Idempotent — re-running on a populated
+	* map is a no-op (each declared id's `<id>:default` is already in the
+	* service's map).
+	*
+	* `basePath` is the filesystem storage root, falling back to
+	* `process.env.CAMSTACK_DATA ?? path.resolve(process.cwd(), 'camstack-data')`.
+	* Every declared default is attributed to the `filesystem-storage`
+	* provider; operators repoint individual locations (or add remote
+	* SFTP/S3/WebDAV instances) through the admin UI afterwards.
+	*/
+	async seedFromDeclarations() {
+		if (!this.service) return;
+		await this.refreshNodeLocalCache();
+		const registry = buildStorageLocationRegistry(this.ctx.kernel.listStorageLocationDeclarations?.() ?? []);
+		this.service.setRegistry(registry);
+		this.service.pruneUndeclaredSystemLocations();
+		const basePath = process.env["CAMSTACK_DATA"] ?? path$1.resolve(process.cwd(), "camstack-data");
+		this.service.seedDefaults({
+			providerId: "filesystem-storage",
+			basePath,
+			declarations: registry.list()
+		});
+		await this.service.backfillNodeIds(HUB_NODE_ID);
+	}
+	/**
+	* Rebuild the `providerId → nodeLocal` cache from every registered
+	* `storage-provider`'s `getProviderInfo()`. Cheap registry scan; runs on
+	* boot and on every provider-registered reconcile. Failed probes are
+	* skipped (the provider stays absent → treated as node-agnostic).
+	*/
+	async refreshNodeLocalCache() {
+		const reg = this.ctx.kernel.capabilityRegistry;
+		if (!reg) return;
+		const infos = await collectProviderInfos(reg.getCollection(STORAGE_PROVIDER_CAP_NAME), (_p, err, index) => {
+			this.ctx.logger.warn("storage-orchestrator: getProviderInfo failed (nodeLocal cache)", { meta: {
+				providerIndex: index,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		});
+		for (const info of infos) this.nodeLocalByProvider.set(info.providerId, info.nodeLocal);
+	}
+	async resolveByUploadId(uploadId) {
+		const providerId = this.uploadOwners.get(uploadId);
+		if (!providerId) throw new Error(`Unknown uploadId "${uploadId}" — orchestrator has no record of beginUpload`);
+		return this.providerByProviderId(providerId, `uploadId "${uploadId}"`);
+	}
+	async resolveByDownloadId(downloadId) {
+		const providerId = this.downloadOwners.get(downloadId);
+		if (!providerId) throw new Error(`Unknown downloadId "${downloadId}" — orchestrator has no record of beginDownload`);
+		return this.providerByProviderId(providerId, `downloadId "${downloadId}"`);
+	}
+	/**
+	* Look up a `storage-provider` by `providerId` only — used for
+	* upload / download dispatch where the original `StorageLocation` is
+	* no longer in scope. Throws if the provider has gone away (e.g.
+	* addon unloaded mid-session).
+	*/
+	async providerByProviderId(providerId, sessionDescriptor) {
+		if (!this.service) throw new Error("storage-orchestrator: service not initialized");
+		const probe = {
+			id: `__session:${sessionDescriptor}`,
+			type: "data",
+			displayName: sessionDescriptor,
+			providerId,
+			config: {},
+			isDefault: false,
+			isSystem: false,
+			createdAt: 0,
+			updatedAt: 0
+		};
+		return this.service.getProviderFor(probe);
+	}
+};
+//#endregion
+export { StorageOrchestratorAddon, StorageOrchestratorAddon as default, StorageOrchestratorService as n, SqliteLocationStore as t };