@camstack/core 0.1.15 → 0.1.17

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

@@ -0,0 +1,746 @@
+import * as path from "node:path";
+import { BaseAddon, DEFAULT_LOCATION_SUBDIRS, STORAGE_LOCATION_CARDINALITY, StorageLocationTypeSchema, parseJsonObject, storageCapability } from "@camstack/types";
+//#region src/builtins/storage-orchestrator/storage-orchestrator.service.ts
+var StorageOrchestratorService = class {
+	locations = /* @__PURE__ */ new Map();
+	constructor(logger, getProviders, locationStore = null) {
+		this.logger = logger;
+		this.getProviders = getProviders;
+		this.locationStore = locationStore;
+	}
+	/**
+	* 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
+		} });
+	}
+	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 (STORAGE_LOCATION_CARDINALITY[input.type] === "singleton") {
+				const already = [...this.locations.values()].find((l) => l.type === input.type);
+				if (already) throw new Error(`Storage type "${input.type}" is singleton — only one location allowed (existing: "${already.id}"). Edit it instead of adding a new one.`);
+			}
+		}
+		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)
+			} });
+		});
+	}
+	/**
+	* 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 parsed = StorageLocationTypeSchema.safeParse(ref);
+		if (!parsed.success) throw new Error(`Invalid storage location ref "${ref}" — expected a StorageLocationType or a fully-qualified id (\`<type>:<slug>\`)`);
+		const def = this.getDefaultLocation(parsed.data);
+		if (!def) throw new Error(`No default storage location configured for type "${parsed.data}" — 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 `supportedTypes` entry that
+	* doesn't already have one. Idempotent — re-running with the same
+	* provider info on a populated map is a no-op (each entry already
+	* resolves on `id === <type>:default`).
+	*
+	* Convention: the bare-type ref `'backups'` resolves via
+	* `getDefaultLocation('backups')` (walks `isDefault === true`); the
+	* actual stored `id` is `'backups:default'` so it satisfies the
+	* `^[a-z][a-z0-9-]*:[a-z0-9-]+$` regex on `StorageLocationSchema.id`.
+	*
+	* `basePath` is the provider's storage root (e.g. the filesystem
+	* provider's `<CAMSTACK_DATA>` dir). Each location's `config.basePath`
+	* is set to `<basePath>/<DEFAULT_LOCATION_SUBDIRS[type]>` — except
+	* when the subdir is already absolute (today only `cache` →
+	* `/tmp/camstack-cache`), in which case it's used verbatim. The
+	* filesystem provider re-derives the same path on its own — this
+	* config field is purely an operator-visible record of what was
+	* provisioned. Task 7 will refactor providers to honour the
+	* location's `config.basePath` directly.
+	*/
+	seedDefaults(input) {
+		let added = 0;
+		for (const type of input.supportedTypes) {
+			if (this.hasAnyLocationOfType(type)) continue;
+			const subdir = DEFAULT_LOCATION_SUBDIRS[type];
+			const fullPath = path.isAbsolute(subdir) ? subdir : path.join(input.basePath, subdir);
+			const id = `${type}:default`;
+			this.upsertLocation({
+				id,
+				type,
+				displayName: DEFAULT_DISPLAY_NAMES[type],
+				providerId: input.providerId,
+				config: { basePath: fullPath },
+				isDefault: true,
+				isSystem: true
+			});
+			added++;
+		}
+		if (added > 0) this.logger.info("storage-orchestrator: seeded default locations", { meta: {
+			providerId: input.providerId,
+			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;
+	}
+};
+/**
+* Operator-facing names for the default seeded location of each
+* `StorageLocationType`. Kept in this module (not in `interfaces/`)
+* because they're a concern of the orchestrator's seed step — operator
+* UI reads `location.displayName` after seeding.
+*/
+var DEFAULT_DISPLAY_NAMES = {
+	"data": "Local Data",
+	"media": "Local Media",
+	"recordings": "Local Recordings",
+	"recordings-high": "Local Recordings (High)",
+	"recordings-low": "Local Recordings (Low)",
+	"recordings-clips": "Local Recordings (Clips)",
+	"event-images": "Local Event Images",
+	"models": "Local Models",
+	"addons-data": "Local Addons Data",
+	"cache": "Local Cache",
+	"logs": "Local Logs",
+	"backups": "Local Backups"
+};
+//#endregion
+//#region src/builtins/storage-orchestrator/location-store.ts
+var STORAGE_LOCATIONS_TABLE = "storage_locations";
+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 {
+	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) {
+	return {
+		id: loc.id,
+		type: loc.type,
+		display_name: loc.displayName,
+		provider_id: loc.providerId,
+		config: JSON.stringify(loc.config),
+		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 config = typeof configRaw === "string" && configRaw.length > 0 ? parseJsonObject(configRaw) ?? {} : {};
+	return {
+		id,
+		type,
+		displayName: String(row["display_name"] ?? ""),
+		providerId: String(row["provider_id"] ?? ""),
+		config,
+		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/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 each provider's
+*     `getProviderInfo().supportedLocationTypes` (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";
+/**
+* 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;
+	/**
+	* `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();
+	/**
+	* 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;
+		await service.initialize();
+		const provider = {
+			listLocations: async ({ type }) => {
+				return type !== void 0 ? service.listLocations({ type }) : service.listLocations();
+			},
+			getDefaultLocation: async ({ type }) => service.getDefaultLocation(type),
+			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 () => {
+				const providers = getProviders();
+				const out = [];
+				for (const p of providers) try {
+					const info = await p.getProviderInfo();
+					out.push({
+						providerId: info.providerId,
+						displayName: info.displayName,
+						supportedLocationTypes: info.supportedLocationTypes,
+						configSchema: info.configSchema
+					});
+				} catch (err) {
+					this.ctx.logger.warn("storage-orchestrator: getProviderInfo failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+				}
+				return out;
+			},
+			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.seedFromAllProviders();
+		const eventBus = this.ctx.eventBus;
+		if (eventBus) {
+			const unsub = eventBus.subscribe({ category: CAP_PROVIDER_REGISTERED_CATEGORY }, (event) => {
+				if (event.data?.capability !== STORAGE_PROVIDER_CAP_NAME) return;
+				this.seedFromAllProviders();
+			});
+			this.seedSubscriptionDisposers.push(unsub);
+		}
+		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;
+		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() {
+		const reg = this.ctx.kernel.capabilityRegistry;
+		if (!reg) return null;
+		const backend = reg.getSingleton("settings-store");
+		if (!backend) {
+			this.ctx.logger.warn("storage-orchestrator: no settings-store provider — running in-memory only");
+			return null;
+		}
+		if (!backend.ensureTable || !backend.tableInsert) {
+			this.ctx.logger.warn("storage-orchestrator: settings backend lacks structured-table support — running in-memory only");
+			return null;
+		}
+		return new SqliteLocationStore(backend);
+	}
+	/**
+	* Walk every registered `storage-provider` collection provider and
+	* call `service.seedDefaults` for each. Idempotent — re-running on
+	* a populated map is a no-op (each location's `id` is already in the
+	* service's map).
+	*
+	* `basePath` is derived per-call:
+	*   - Filesystem providers (and any provider whose `getProviderInfo`
+	*     doesn't include a `basePath` field) fall back to
+	*     `process.env.CAMSTACK_DATA ?? path.resolve(process.cwd(), 'camstack-data')`.
+	*   - Future remote providers (SFTP/S3/WebDAV) will report their own
+	*     base path through the wizard config — they're not relevant for
+	*     first-boot seeding (operators add them through the admin UI).
+	*/
+	async seedFromAllProviders() {
+		if (!this.service) return;
+		const reg = this.ctx.kernel.capabilityRegistry;
+		if (!reg) return;
+		const providers = reg.getCollection(STORAGE_PROVIDER_CAP_NAME);
+		if (providers.length === 0) return;
+		const basePath = process.env["CAMSTACK_DATA"] ?? path.resolve(process.cwd(), "camstack-data");
+		for (const p of providers) try {
+			const info = await p.getProviderInfo();
+			this.service.seedDefaults({
+				providerId: info.providerId,
+				supportedTypes: info.supportedLocationTypes,
+				basePath
+			});
+		} catch (err) {
+			this.ctx.logger.warn("storage-orchestrator: seed failed for provider", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		}
+	}
+	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 };
+
+//# sourceMappingURL=storage-orchestrator.addon.mjs.map