@camstack/system 1.0.2

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

@@ -0,0 +1,2220 @@
+import { o as __toESM } from "../../chunk-CNf5ZN-e.mjs";
+import { t as require_tar } from "../../tar-ByMOPNM0.mjs";
+import * as fs from "node:fs";
+import * as path$1 from "node:path";
+import { BaseAddon, EventCategory, backupCapability } from "@camstack/types";
+import { randomUUID } from "node:crypto";
+import * as fsp from "node:fs/promises";
+import * as zlib from "node:zlib";
+//#region src/builtins/system-backup/system-backup.service.ts
+var import_tar = /* @__PURE__ */ __toESM(require_tar());
+/**
+* Default set of paths considered part of a "system backup". Includes
+* everything that isn't pure backend code — config, sqlite, addons
+* (runtime overlay), addons-data (per-addon private dir), TLS certs,
+* auto-update marker.
+*
+* Excluded by default: recordings/, media/, models/, logs/, cache/
+* (too large or fully recreatable).
+*/
+var DEFAULT_BACKUP_LOCATIONS = [
+	"config.yaml",
+	"addons",
+	"addons-data",
+	"tls",
+	"auto-update.json"
+];
+/** Path of the manifest file embedded inside every archive. */
+var ARCHIVE_MANIFEST_NAME = ".camstack-backup-manifest.json";
+/**
+* System-level archive primitives. Construct one per server boot;
+* methods are pure I/O.
+*/
+var SystemBackupService = class {
+	dataDir;
+	logger;
+	constructor(dataDir, logger) {
+		this.dataDir = dataDir;
+		this.logger = logger;
+	}
+	/**
+	* Snapshot the current size + file count of each well-known
+	* location. Used by the admin UI to render an opt-in checklist
+	* before triggering a backup, and by `createArchive` to derive the
+	* embedded manifest.
+	*/
+	statLocations(locations = DEFAULT_BACKUP_LOCATIONS) {
+		return locations.map((loc) => {
+			const abs = path$1.isAbsolute(loc) ? loc : path$1.join(this.dataDir, loc);
+			if (!fs.existsSync(abs)) return {
+				name: loc,
+				sizeBytes: 0,
+				fileCount: 0,
+				present: false
+			};
+			const walked = walkAbs(abs, abs);
+			return {
+				name: loc,
+				sizeBytes: walked.reduce((acc, e) => acc + e.sizeBytes, 0),
+				fileCount: walked.filter((e) => e.kind === "file").length,
+				present: true
+			};
+		});
+	}
+	/**
+	* Create a tar.gz of the given locations. Uses the `tar` npm package
+	* (used by npm itself) instead of shelling out — gives us:
+	*
+	*   - Symlink dereference (`follow: true`) so dev mode's
+	*     `addons/<name> → packages/<name>` overlay archives content,
+	*     not just link stubs.
+	*   - Programmatic walk → we build a manifest of every entry while
+	*     copying so the archive can self-describe.
+	*
+	* Locations that don't exist are silently skipped. Throws if zero
+	* locations would be included.
+	*/
+	async createArchive(opts) {
+		const requested = opts.locations ?? DEFAULT_BACKUP_LOCATIONS;
+		const present = [];
+		for (const loc of requested) {
+			const abs = path$1.isAbsolute(loc) ? loc : path$1.join(this.dataDir, loc);
+			if (fs.existsSync(abs)) present.push(loc);
+			else this.logger.debug("createArchive: skipping missing location", { meta: { location: loc } });
+		}
+		if (present.length === 0) throw new Error(`createArchive: no locations from {${requested.join(", ")}} exist under ${this.dataDir}`);
+		fs.mkdirSync(path$1.dirname(opts.archivePath), { recursive: true });
+		const entries = [];
+		for (const loc of present) {
+			const abs = path$1.join(this.dataDir, loc);
+			const stat = fs.statSync(abs);
+			if (stat.isDirectory()) for (const e of walkAbs(abs, this.dataDir)) entries.push(e);
+			else entries.push(toArchiveEntry(abs, this.dataDir, stat));
+		}
+		const manifest = {
+			archiveVersion: 1,
+			createdAt: Date.now(),
+			dataDir: this.dataDir,
+			locations: present,
+			entries,
+			totalBytes: entries.reduce((acc, e) => acc + e.sizeBytes, 0),
+			totalFiles: entries.filter((e) => e.kind === "file").length
+		};
+		const manifestStagePath = `${opts.archivePath}.${process.pid}.manifest.json`;
+		fs.writeFileSync(manifestStagePath, JSON.stringify(manifest, null, 2), "utf-8");
+		this.logger.info("createArchive: tarring", { meta: {
+			archivePath: opts.archivePath,
+			locations: present,
+			totalFiles: manifest.totalFiles,
+			totalBytes: manifest.totalBytes
+		} });
+		try {
+			const stagedInDataDir = path$1.join(this.dataDir, ARCHIVE_MANIFEST_NAME);
+			fs.copyFileSync(manifestStagePath, stagedInDataDir);
+			try {
+				await import_tar.create({
+					file: opts.archivePath,
+					gzip: true,
+					cwd: this.dataDir,
+					follow: true,
+					portable: true
+				}, [ARCHIVE_MANIFEST_NAME, ...present]);
+			} finally {
+				try {
+					fs.rmSync(stagedInDataDir, { force: true });
+				} catch {}
+			}
+		} finally {
+			try {
+				fs.rmSync(manifestStagePath, { force: true });
+			} catch {}
+		}
+		const sizeBytes = fs.statSync(opts.archivePath).size;
+		return {
+			archivePath: opts.archivePath,
+			includedLocations: present,
+			sizeBytes,
+			manifest
+		};
+	}
+	/**
+	* Read the embedded manifest from a previously-created archive
+	* without extracting payload files. Streams the tar.gz, parses the
+	* one entry we care about, then aborts.
+	*/
+	async readArchiveManifest(archivePath) {
+		if (!fs.existsSync(archivePath)) throw new Error(`readArchiveManifest: ${archivePath} does not exist`);
+		return new Promise((resolve, reject) => {
+			const chunks = [];
+			let found = false;
+			let resolved = false;
+			const parser = new import_tar.Parse({ onentry: (entry) => {
+				if (entry.path === ".camstack-backup-manifest.json" && !found) {
+					found = true;
+					entry.on("data", (chunk) => chunks.push(chunk));
+					entry.on("end", () => {
+						try {
+							const json = Buffer.concat(chunks).toString("utf-8");
+							const parsed = JSON.parse(json);
+							resolved = true;
+							resolve(parsed);
+						} catch (err) {
+							resolved = true;
+							reject(err instanceof Error ? err : new Error(String(err)));
+						}
+					});
+				} else entry.resume();
+			} });
+			parser.on("end", () => {
+				if (!resolved) resolve(found ? null : null);
+			});
+			const gunzip = zlib.createGunzip();
+			gunzip.on("error", (err) => {
+				if (!resolved) {
+					resolved = true;
+					reject(err);
+				}
+			});
+			const reader = fs.createReadStream(archivePath);
+			reader.on("error", (err) => {
+				if (!resolved) {
+					resolved = true;
+					reject(err);
+				}
+			});
+			reader.pipe(gunzip).pipe(parser);
+		});
+	}
+	/**
+	* Extract a previously-created archive over `targetDir`. Used at boot
+	* by the restore hook — never call from a running server (would
+	* corrupt sqlite mid-run).
+	*
+	* `locations` is an optional whitelist: only entries whose path
+	* starts with one of the locations get extracted. Used by the
+	* partial-restore flow where the operator picks a subset of the
+	* archive contents to apply (e.g. "restore my devices but keep
+	* my current TLS certs").
+	*/
+	async extractArchive(opts) {
+		if (!fs.existsSync(opts.archivePath)) throw new Error(`extractArchive: ${opts.archivePath} does not exist`);
+		fs.mkdirSync(opts.targetDir, { recursive: true });
+		this.logger.info("extractArchive: untarring", { meta: {
+			archivePath: opts.archivePath,
+			targetDir: opts.targetDir,
+			locations: opts.locations
+		} });
+		const allowedPrefixes = opts.locations ? opts.locations.map(normalizeLocation) : null;
+		await import_tar.extract({
+			file: opts.archivePath,
+			cwd: opts.targetDir,
+			filter: (p) => {
+				if (p === ".camstack-backup-manifest.json" || p === `./.camstack-backup-manifest.json`) return false;
+				if (!allowedPrefixes) return true;
+				const normalized = p.replace(/^\.\//, "");
+				return allowedPrefixes.some((prefix) => entryMatchesLocation(normalized, prefix));
+			}
+		});
+	}
+	/**
+	* Schedule a restore for the next boot by writing a marker file.
+	* `locations` (optional) carries through to the boot-time
+	* extractArchive call so the operator's "restore only X and Y"
+	* choice survives the process restart.
+	*/
+	scheduleRestoreMarker(opts) {
+		if (!fs.existsSync(opts.archivePath)) throw new Error(`scheduleRestoreMarker: ${opts.archivePath} missing`);
+		const markerPath = this.getRestoreMarkerPath();
+		const marker = {
+			archivePath: opts.archivePath,
+			requestedAt: Date.now(),
+			source: opts.source,
+			...opts.locations ? { locations: [...opts.locations] } : {}
+		};
+		fs.mkdirSync(path$1.dirname(markerPath), { recursive: true });
+		fs.writeFileSync(markerPath, JSON.stringify(marker, null, 2), { mode: 384 });
+		return markerPath;
+	}
+	/** Read the pending-restore marker if one is present. */
+	readPendingMarker() {
+		const markerPath = this.getRestoreMarkerPath();
+		if (!fs.existsSync(markerPath)) return null;
+		try {
+			const raw = fs.readFileSync(markerPath, "utf-8");
+			const parsed = JSON.parse(raw);
+			if (typeof parsed === "object" && parsed != null && typeof parsed.archivePath === "string") return parsed;
+		} catch (err) {
+			this.logger.warn("readPendingMarker: malformed marker — ignoring", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		}
+		return null;
+	}
+	/** Drop the marker after a successful boot-time restore. */
+	clearPendingMarker() {
+		const markerPath = this.getRestoreMarkerPath();
+		if (fs.existsSync(markerPath)) fs.rmSync(markerPath, { force: true });
+	}
+	getRestoreMarkerPath() {
+		return path$1.join(this.dataDir, ".pending-restore.json");
+	}
+};
+/**
+* Recursively walk a directory and produce one `ArchiveEntry` per
+* filesystem node. `dataDir` is used to compute the archive-relative
+* path. Symlinks are dereferenced (matches the `follow: true` flag we
+* pass to tar.create).
+*/
+function walkAbs(absRoot, dataDir) {
+	const out = [];
+	walkRec(absRoot, dataDir, out);
+	return out;
+}
+function walkRec(abs, dataDir, out) {
+	let stat;
+	try {
+		stat = fs.statSync(abs);
+	} catch {
+		return;
+	}
+	out.push(toArchiveEntry(abs, dataDir, stat));
+	if (stat.isDirectory()) {
+		let children;
+		try {
+			children = fs.readdirSync(abs);
+		} catch {
+			return;
+		}
+		for (const child of children) walkRec(path$1.join(abs, child), dataDir, out);
+	}
+}
+function toArchiveEntry(abs, dataDir, stat) {
+	const rel = path$1.relative(dataDir, abs).replace(/\\/g, "/");
+	const kind = stat.isDirectory() ? "dir" : stat.isSymbolicLink() ? "symlink" : "file";
+	return {
+		path: rel || path$1.basename(abs),
+		kind,
+		sizeBytes: kind === "file" ? stat.size : 0,
+		mtime: stat.mtimeMs
+	};
+}
+/**
+* Strip leading `./` and trailing `/` so location prefix matching is
+* order-of-comparison invariant. Same shape on both sides of the
+* `entry.path.startsWith(prefix)` test in the extract filter.
+*/
+function normalizeLocation(loc) {
+	return loc.replace(/^\.\//, "").replace(/\/+$/, "");
+}
+/**
+* Match an archive entry path against a location whitelist prefix.
+* `addons` matches `addons` (file) and `addons/foo/bar.txt` (path
+* inside the dir). The trailing `/` test is what prevents `addons`
+* from spuriously matching `addons-data`.
+*/
+function entryMatchesLocation(entryPath, prefix) {
+	return entryPath === prefix || entryPath.startsWith(`${prefix}/`);
+}
+//#endregion
+//#region src/builtins/backup-orchestrator/destination-policy.ts
+var TABLE_NAME = "backup_destination_policies";
+var BACKUP_DESTINATION_POLICIES_SCHEMA = { columns: [
+	{
+		name: "location_id",
+		type: "TEXT",
+		primaryKey: true
+	},
+	{
+		name: "enabled",
+		type: "INTEGER",
+		notNull: true,
+		defaultValue: 1
+	},
+	{
+		name: "retention_count",
+		type: "INTEGER",
+		notNull: true,
+		defaultValue: 7
+	},
+	{
+		name: "label",
+		type: "TEXT"
+	},
+	{
+		name: "cron",
+		type: "TEXT"
+	},
+	{
+		name: "last_run_at",
+		type: "INTEGER"
+	}
+] };
+var BackupDestinationPolicyService = class {
+	backend;
+	tableEnsured = false;
+	constructor(backend) {
+		this.backend = backend;
+	}
+	/**
+	* Lazy `ensureTable` — called from every read/write path. The
+	* settings backend's own `ensureTable` is idempotent (additive
+	* migration), so repeated calls collapse to a no-op after the first.
+	* This keeps the constructor synchronous and avoids a separate
+	* `initialize()` step that callers could forget.
+	*/
+	async initialize() {
+		await this.ensureTable();
+	}
+	async ensureTable() {
+		if (this.tableEnsured) return;
+		if (!this.backend.ensureTable) throw new Error("BackupDestinationPolicyService: settings backend does not implement ensureTable — expected the SQLite settings backend, got a backend without structured-table support");
+		await this.backend.ensureTable(TABLE_NAME, BACKUP_DESTINATION_POLICIES_SCHEMA);
+		this.tableEnsured = true;
+	}
+	async list() {
+		await this.ensureTable();
+		if (!this.backend.tableQuery) return [];
+		const rows = await this.backend.tableQuery(TABLE_NAME, { orderBy: {
+			field: "location_id",
+			direction: "asc"
+		} });
+		const out = [];
+		for (const row of rows) {
+			const mapped = mapRowToPolicy(row);
+			if (mapped) out.push(mapped);
+		}
+		return out;
+	}
+	async get(locationId) {
+		await this.ensureTable();
+		if (!this.backend.tableGet) return null;
+		const row = await this.backend.tableGet(TABLE_NAME, { location_id: locationId });
+		return row ? mapRowToPolicy(row) : null;
+	}
+	/**
+	* Replace-or-insert. Implemented as `delete` + `insert` (mirrors the
+	* `SqliteLocationStore` contract) so backends that don't surface
+	* `tableUpdate` still work.
+	*/
+	async upsert(p) {
+		await this.ensureTable();
+		if (!this.backend.tableDelete || !this.backend.tableInsert) throw new Error("BackupDestinationPolicyService: backend missing tableDelete/tableInsert");
+		await this.backend.tableDelete(TABLE_NAME, { location_id: p.locationId });
+		await this.backend.tableInsert(TABLE_NAME, mapPolicyToRow(p));
+	}
+	async delete(locationId) {
+		await this.ensureTable();
+		if (!this.backend.tableDelete) throw new Error("BackupDestinationPolicyService: backend missing tableDelete");
+		await this.backend.tableDelete(TABLE_NAME, { location_id: locationId });
+	}
+	/**
+	* Auto-create a default policy for a `backups` location seen for the
+	* first time (returns the existing policy unchanged when present).
+	* The orchestrator calls this lazily on the first `listDestinations`
+	* pass so newly-added storage locations are surfaced as enabled
+	* destinations without an explicit configuration step.
+	*
+	* Defaults are passed by the orchestrator (currently:
+	* `retentionCount=7` + `cron='0 3 * * *'`) so a fresh destination
+	* starts running daily at 03:00 with 7 archives kept. Operator can
+	* tune both inline on the destinations table.
+	*/
+	async ensureDefault(locationId, defaults) {
+		const existing = await this.get(locationId);
+		if (existing) return existing;
+		const fresh = {
+			locationId,
+			enabled: true,
+			retentionCount: defaults.retentionCount,
+			...defaults.cron !== void 0 ? { cron: defaults.cron } : {}
+		};
+		await this.upsert(fresh);
+		return fresh;
+	}
+};
+function mapPolicyToRow(p) {
+	return {
+		location_id: p.locationId,
+		enabled: p.enabled ? 1 : 0,
+		retention_count: p.retentionCount,
+		label: p.label ?? null,
+		cron: p.cron ?? null,
+		last_run_at: p.lastRunAt ?? null
+	};
+}
+/**
+* Decode a row pulled from the structured table. Defensive against
+* schema drift / partial migrations: returns `null` on missing
+* `location_id` so corrupt rows skip the result list rather than
+* throwing the whole orchestrator down at boot.
+*/
+function mapRowToPolicy(row) {
+	const locationId = String(row["location_id"] ?? "");
+	if (!locationId) return null;
+	const labelRaw = row["label"];
+	const label = typeof labelRaw === "string" && labelRaw.length > 0 ? labelRaw : void 0;
+	const cronRaw = row["cron"];
+	const cron = typeof cronRaw === "string" && cronRaw.length > 0 ? cronRaw : void 0;
+	const lastRunRaw = row["last_run_at"];
+	const lastRunAt = typeof lastRunRaw === "number" && lastRunRaw > 0 ? lastRunRaw : void 0;
+	return {
+		locationId,
+		enabled: row["enabled"] === 1 || row["enabled"] === true,
+		retentionCount: Number(row["retention_count"] ?? 0),
+		...label !== void 0 ? { label } : {},
+		...cron !== void 0 ? { cron } : {},
+		...lastRunAt !== void 0 ? { lastRunAt } : {}
+	};
+}
+//#endregion
+//#region src/builtins/backup-orchestrator/manifest-store.ts
+/** File path (relative to the location root) where the index lives. */
+var MANIFESTS_FILENAME = "manifests.json";
+/**
+* Read the per-location manifest. Returns an empty manifest on first
+* use (when `manifests.json` doesn't exist) or when the file is
+* unreadable / corrupt — operators see destination state degrade
+* gracefully rather than the orchestrator crashing.
+*/
+async function readLocationManifest(api, locationId) {
+	if (!await api.exists.query({
+		location: locationId,
+		relativePath: "manifests.json"
+	}).catch(() => false)) return EMPTY_MANIFEST;
+	let bytes;
+	try {
+		bytes = await api.read.query({
+			location: locationId,
+			relativePath: MANIFESTS_FILENAME
+		});
+	} catch {
+		return EMPTY_MANIFEST;
+	}
+	return parseManifestBytes(bytes);
+}
+async function writeLocationManifest(api, locationId, manifest) {
+	const json = JSON.stringify(manifest, null, 2);
+	const bytes = new TextEncoder().encode(json);
+	await api.write.mutate({
+		location: locationId,
+		relativePath: MANIFESTS_FILENAME,
+		data: bytes
+	});
+}
+/**
+* Decode the raw bytes of `manifests.json`. Falls back to an empty
+* manifest on JSON-parse / shape-validation failure — same defensive
+* stance as the legacy `LocalBackupService.ensureManifestsLoaded`.
+*/
+function parseManifestBytes(bytes) {
+	try {
+		const text = new TextDecoder().decode(bytes);
+		if (text.trim().length === 0) return EMPTY_MANIFEST;
+		return normalizeManifest(JSON.parse(text));
+	} catch {
+		return EMPTY_MANIFEST;
+	}
+}
+/**
+* Coerce an arbitrary parsed JSON shape into the canonical manifest
+* type. Bogus archive entries are silently dropped (a corrupt row
+* shouldn't lock the whole location out of operator visibility).
+*/
+function normalizeManifest(raw) {
+	if (typeof raw !== "object" || raw == null) return EMPTY_MANIFEST;
+	const obj = raw;
+	const archives = [];
+	if (Array.isArray(obj.archives)) for (const a of obj.archives) {
+		if (typeof a !== "object" || a == null) continue;
+		const cand = a;
+		if (typeof cand["id"] !== "string" || typeof cand["filename"] !== "string") continue;
+		if (typeof cand["createdAt"] !== "number" || typeof cand["sizeBytes"] !== "number") continue;
+		const manifest = cand["manifest"];
+		if (typeof manifest !== "object" || manifest == null) continue;
+		const entry = {
+			id: String(cand["id"]),
+			filename: String(cand["filename"]),
+			createdAt: Number(cand["createdAt"]),
+			sizeBytes: Number(cand["sizeBytes"]),
+			...typeof cand["label"] === "string" ? { label: cand["label"] } : {},
+			manifest
+		};
+		archives.push(entry);
+	}
+	return {
+		version: 1,
+		archives
+	};
+}
+var EMPTY_MANIFEST = {
+	version: 1,
+	archives: []
+};
+/**
+* Build a `ManifestArchiveEntry` from the raw inputs collected during
+* a successful upload. Pure transform — no I/O — kept here so the
+* triggerBackup path stays terse.
+*/
+function buildArchiveEntry(input) {
+	return {
+		id: input.id,
+		filename: input.filename,
+		createdAt: input.createdAt,
+		sizeBytes: input.sizeBytes,
+		...input.label !== void 0 ? { label: input.label } : {},
+		manifest: input.manifest
+	};
+}
+/**
+* Pure retention split: given an archive list and the operator's
+* `retentionCount`, return `{ keep, drop }` where `keep` is the most-
+* recent N archives (newest first) and `drop` is the older overflow.
+*
+* `retentionCount <= 0` is treated as "no pruning" — defensive against
+* a config value that would otherwise wipe every archive on the next
+* write.
+*/
+function applyRetention(archives, retentionCount) {
+	if (retentionCount <= 0) return {
+		keep: archives,
+		drop: []
+	};
+	const sorted = [...archives].toSorted((a, b) => b.createdAt - a.createdAt);
+	if (sorted.length <= retentionCount) return {
+		keep: sorted,
+		drop: []
+	};
+	return {
+		keep: sorted.slice(0, retentionCount),
+		drop: sorted.slice(retentionCount)
+	};
+}
+/**
+* Per-location async mutex. The orchestrator owns one instance and
+* funnels every read-modify-write of `manifests.json` through it so
+* parallel destination uploads (within the same location) commit in
+* arrival order. Across locations the operations run in parallel —
+* each location keys its own promise chain.
+*/
+var LocationManifestLock = class {
+	chains = /* @__PURE__ */ new Map();
+	async run(locationId, fn) {
+		const previous = this.chains.get(locationId) ?? Promise.resolve();
+		let resolveNext;
+		const next = new Promise((res) => {
+			resolveNext = res;
+		});
+		this.chains.set(locationId, previous.then(() => next));
+		try {
+			await previous;
+			return await fn();
+		} finally {
+			resolveNext();
+			const tail = this.chains.get(locationId);
+			if (tail) Promise.resolve(tail).then(() => {
+				if (this.chains.get(locationId) === tail) this.chains.delete(locationId);
+			}).catch(() => {});
+		}
+	}
+};
+//#endregion
+//#region src/builtins/backup-orchestrator/download-helpers.ts
+/**
+* Chunked-download helper for the backup orchestrator (Task 12 of
+* the storage-unification refactor).
+*
+* Streams an archive from a destination `StorageLocation` into a
+* local filesystem path via the consumer-facing `storage` cap. Pulled
+* out of `backup-orchestrator.addon.ts` so it can be unit-tested with
+* an in-memory fake `AddonApi['storage']` slice — the addon is hard
+* to bootstrap in vitest because of the BaseAddon ceremony.
+*
+* Cleanup contract:
+*  - Successful run leaves the cache file in place + calls
+*    `endDownload`.
+*  - Mid-stream failure destroys the writeStream, removes the
+*    partial cache file, and best-effort calls `endDownload` so the
+*    storage provider's session bookkeeping doesn't leak.
+*/
+async function downloadArchiveToCache(input) {
+	const { downloadId, sizeBytes } = await input.api.beginDownload.mutate({
+		location: input.locationId,
+		relativePath: input.filename
+	});
+	const writeStream = fs.createWriteStream(input.cachePath);
+	let offset = 0;
+	try {
+		while (offset < sizeBytes) {
+			const remaining = sizeBytes - offset;
+			const length = Math.min(input.chunkBytes, remaining);
+			const chunk = await input.api.readChunk.query({
+				downloadId,
+				offset,
+				length
+			});
+			if (chunk.byteLength === 0) throw new Error(`backup restore: empty chunk at offset ${offset}/${sizeBytes} from "${input.locationId}/${input.filename}"`);
+			writeStream.write(chunk);
+			offset += chunk.byteLength;
+		}
+		await new Promise((resolve, reject) => {
+			writeStream.end((err) => {
+				if (err) reject(err);
+				else resolve();
+			});
+		});
+		try {
+			await input.api.endDownload.mutate({ downloadId });
+		} catch (err) {
+			input.logger.warn("backup restore: endDownload failed (ignoring)", { meta: {
+				downloadId,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	} catch (err) {
+		await new Promise((resolve) => {
+			writeStream.once("close", () => resolve());
+			writeStream.destroy();
+		});
+		try {
+			await fsp.rm(input.cachePath, { force: true });
+		} catch {}
+		try {
+			await input.api.endDownload.mutate({ downloadId });
+		} catch {}
+		throw err;
+	}
+}
+//#endregion
+//#region ../../node_modules/croner/dist/croner.js
+function T(s) {
+	return Date.UTC(s.y, s.m - 1, s.d, s.h, s.i, s.s);
+}
+function D(s, e) {
+	return s.y === e.y && s.m === e.m && s.d === e.d && s.h === e.h && s.i === e.i && s.s === e.s;
+}
+function A(s, e) {
+	let t = new Date(Date.parse(s));
+	if (isNaN(t)) throw new Error("Invalid ISO8601 passed to timezone parser.");
+	let r = s.substring(9);
+	return r.includes("Z") || r.includes("+") || r.includes("-") ? b(t.getUTCFullYear(), t.getUTCMonth() + 1, t.getUTCDate(), t.getUTCHours(), t.getUTCMinutes(), t.getUTCSeconds(), "Etc/UTC") : b(t.getFullYear(), t.getMonth() + 1, t.getDate(), t.getHours(), t.getMinutes(), t.getSeconds(), e);
+}
+function v(s, e, t) {
+	return k(A(s, e), t);
+}
+function k(s, e) {
+	let t = new Date(T(s)), r = g(t, s.tz), a = T(s) - T(r), o = new Date(t.getTime() + a), h = g(o, s.tz);
+	if (D(h, s)) {
+		let u = /* @__PURE__ */ new Date(o.getTime() - 36e5);
+		return D(g(u, s.tz), s) ? u : o;
+	}
+	let l = new Date(o.getTime() + T(s) - T(h));
+	if (D(g(l, s.tz), s)) return l;
+	if (e) throw new Error("Invalid date passed to fromTZ()");
+	return o.getTime() > l.getTime() ? o : l;
+}
+function g(s, e) {
+	let t, r;
+	try {
+		t = new Intl.DateTimeFormat("en-US", {
+			timeZone: e,
+			year: "numeric",
+			month: "numeric",
+			day: "numeric",
+			hour: "numeric",
+			minute: "numeric",
+			second: "numeric",
+			hour12: !1
+		}), r = t.formatToParts(s);
+	} catch (i) {
+		let a = i instanceof Error ? i.message : String(i);
+		throw new RangeError(`toTZ: Invalid timezone '${e}' or date. Please provide a valid IANA timezone (e.g., 'America/New_York', 'Europe/Stockholm'). Original error: ${a}`);
+	}
+	let n = {
+		year: 0,
+		month: 0,
+		day: 0,
+		hour: 0,
+		minute: 0,
+		second: 0
+	};
+	for (let i of r) (i.type === "year" || i.type === "month" || i.type === "day" || i.type === "hour" || i.type === "minute" || i.type === "second") && (n[i.type] = parseInt(i.value, 10));
+	if (isNaN(n.year) || isNaN(n.month) || isNaN(n.day) || isNaN(n.hour) || isNaN(n.minute) || isNaN(n.second)) throw new Error(`toTZ: Failed to parse all date components from timezone '${e}'. This may indicate an invalid date or timezone configuration. Parsed components: ${JSON.stringify(n)}`);
+	return n.hour === 24 && (n.hour = 0), {
+		y: n.year,
+		m: n.month,
+		d: n.day,
+		h: n.hour,
+		i: n.minute,
+		s: n.second,
+		tz: e
+	};
+}
+function b(s, e, t, r, n, i, a) {
+	return {
+		y: s,
+		m: e,
+		d: t,
+		h: r,
+		i: n,
+		s: i,
+		tz: a
+	};
+}
+var O = [
+	1,
+	2,
+	4,
+	8,
+	16
+], C = class {
+	pattern;
+	timezone;
+	mode;
+	alternativeWeekdays;
+	sloppyRanges;
+	second;
+	minute;
+	hour;
+	day;
+	month;
+	dayOfWeek;
+	year;
+	lastDayOfMonth;
+	lastWeekday;
+	nearestWeekdays;
+	starDOM;
+	starDOW;
+	starYear;
+	useAndLogic;
+	constructor(e, t, r) {
+		this.pattern = e, this.timezone = t, this.mode = r?.mode ?? "auto", this.alternativeWeekdays = r?.alternativeWeekdays ?? !1, this.sloppyRanges = r?.sloppyRanges ?? !1, this.second = Array(60).fill(0), this.minute = Array(60).fill(0), this.hour = Array(24).fill(0), this.day = Array(31).fill(0), this.month = Array(12).fill(0), this.dayOfWeek = Array(7).fill(0), this.year = Array(1e4).fill(0), this.lastDayOfMonth = !1, this.lastWeekday = !1, this.nearestWeekdays = Array(31).fill(0), this.starDOM = !1, this.starDOW = !1, this.starYear = !1, this.useAndLogic = !1, this.parse();
+	}
+	parse() {
+		if (!(typeof this.pattern == "string" || this.pattern instanceof String)) throw new TypeError("CronPattern: Pattern has to be of type string.");
+		this.pattern.indexOf("@") >= 0 && (this.pattern = this.handleNicknames(this.pattern).trim());
+		let e = this.pattern.match(/\S+/g) || [""], t = e.length;
+		if (e.length < 5 || e.length > 7) throw new TypeError("CronPattern: invalid configuration format ('" + this.pattern + "'), exactly five, six, or seven space separated parts are required.");
+		if (this.mode !== "auto") {
+			let n;
+			switch (this.mode) {
+				case "5-part":
+					n = 5;
+					break;
+				case "6-part":
+					n = 6;
+					break;
+				case "7-part":
+					n = 7;
+					break;
+				case "5-or-6-parts":
+					n = [5, 6];
+					break;
+				case "6-or-7-parts":
+					n = [6, 7];
+					break;
+				default: n = 0;
+			}
+			if (!(Array.isArray(n) ? n.includes(t) : t === n)) {
+				let a = Array.isArray(n) ? n.join(" or ") : n.toString();
+				throw new TypeError(`CronPattern: mode '${this.mode}' requires exactly ${a} parts, but pattern '${this.pattern}' has ${t} parts.`);
+			}
+		}
+		if (e.length === 5 && e.unshift("0"), e.length === 6 && e.push("*"), e[3].toUpperCase() === "LW" ? (this.lastWeekday = !0, e[3] = "") : e[3].toUpperCase().indexOf("L") >= 0 && (e[3] = e[3].replace(/L/gi, ""), this.lastDayOfMonth = !0), e[3] == "*" && (this.starDOM = !0), e[6] == "*" && (this.starYear = !0), e[4].length >= 3 && (e[4] = this.replaceAlphaMonths(e[4])), e[5].length >= 3 && (e[5] = this.alternativeWeekdays ? this.replaceAlphaDaysQuartz(e[5]) : this.replaceAlphaDays(e[5])), e[5].startsWith("+") && (this.useAndLogic = !0, e[5] = e[5].substring(1), e[5] === "")) throw new TypeError("CronPattern: Day-of-week field cannot be empty after '+' modifier.");
+		switch (e[5] == "*" && (this.starDOW = !0), this.pattern.indexOf("?") >= 0 && (e[0] = e[0].replace(/\?/g, "*"), e[1] = e[1].replace(/\?/g, "*"), e[2] = e[2].replace(/\?/g, "*"), e[3] = e[3].replace(/\?/g, "*"), e[4] = e[4].replace(/\?/g, "*"), e[5] = e[5].replace(/\?/g, "*"), e[6] && (e[6] = e[6].replace(/\?/g, "*"))), this.mode) {
+			case "5-part":
+				e[0] = "0", e[6] = "*";
+				break;
+			case "6-part":
+				e[6] = "*";
+				break;
+			case "5-or-6-parts":
+				e[6] = "*";
+				break;
+			case "6-or-7-parts": break;
+			case "7-part":
+			case "auto": break;
+		}
+		this.throwAtIllegalCharacters(e), this.partToArray("second", e[0], 0, 1), this.partToArray("minute", e[1], 0, 1), this.partToArray("hour", e[2], 0, 1), this.partToArray("day", e[3], -1, 1), this.partToArray("month", e[4], -1, 1);
+		let r = this.alternativeWeekdays ? -1 : 0;
+		this.partToArray("dayOfWeek", e[5], r, 63), this.partToArray("year", e[6], 0, 1), !this.alternativeWeekdays && this.dayOfWeek[7] && (this.dayOfWeek[0] = this.dayOfWeek[7]);
+	}
+	partToArray(e, t, r, n) {
+		let i = this[e], a = e === "day" && this.lastDayOfMonth, o = e === "day" && this.lastWeekday;
+		if (t === "" && !a && !o) throw new TypeError("CronPattern: configuration entry " + e + " (" + t + ") is empty, check for trailing spaces.");
+		if (t === "*") return i.fill(n);
+		let h = t.split(",");
+		if (h.length > 1) for (let l = 0; l < h.length; l++) this.partToArray(e, h[l], r, n);
+		else t.indexOf("-") !== -1 && t.indexOf("/") !== -1 ? this.handleRangeWithStepping(t, e, r, n) : t.indexOf("-") !== -1 ? this.handleRange(t, e, r, n) : t.indexOf("/") !== -1 ? this.handleStepping(t, e, r, n) : t !== "" && this.handleNumber(t, e, r, n);
+	}
+	throwAtIllegalCharacters(e) {
+		for (let t = 0; t < e.length; t++) if ((t === 3 ? /[^/*0-9,\-WwLl]+/ : t === 5 ? /[^/*0-9,\-#Ll]+/ : /[^/*0-9,\-]+/).test(e[t])) throw new TypeError("CronPattern: configuration entry " + t + " (" + e[t] + ") contains illegal characters.");
+	}
+	handleNumber(e, t, r, n) {
+		let i = this.extractNth(e, t), a = e.toUpperCase().includes("W");
+		if (t !== "day" && a) throw new TypeError("CronPattern: Nearest weekday modifier (W) only allowed in day-of-month.");
+		a && (t = "nearestWeekdays");
+		let o = parseInt(i[0], 10) + r;
+		if (isNaN(o)) throw new TypeError("CronPattern: " + t + " is not a number: '" + e + "'");
+		this.setPart(t, o, i[1] || n);
+	}
+	setPart(e, t, r) {
+		if (!Object.prototype.hasOwnProperty.call(this, e)) throw new TypeError("CronPattern: Invalid part specified: " + e);
+		if (e === "dayOfWeek") {
+			if (t === 7 && (t = 0), t < 0 || t > 6) throw new RangeError("CronPattern: Invalid value for dayOfWeek: " + t);
+			this.setNthWeekdayOfMonth(t, r);
+			return;
+		}
+		if (e === "second" || e === "minute") {
+			if (t < 0 || t >= 60) throw new RangeError("CronPattern: Invalid value for " + e + ": " + t);
+		} else if (e === "hour") {
+			if (t < 0 || t >= 24) throw new RangeError("CronPattern: Invalid value for " + e + ": " + t);
+		} else if (e === "day" || e === "nearestWeekdays") {
+			if (t < 0 || t >= 31) throw new RangeError("CronPattern: Invalid value for " + e + ": " + t);
+		} else if (e === "month") {
+			if (t < 0 || t >= 12) throw new RangeError("CronPattern: Invalid value for " + e + ": " + t);
+		} else if (e === "year" && (t < 1 || t >= 1e4)) throw new RangeError("CronPattern: Invalid value for " + e + ": " + t + " (supported range: 1-9999)");
+		this[e][t] = r;
+	}
+	validateNotNaN(e, t) {
+		if (isNaN(e)) throw new TypeError(t);
+	}
+	validateRange(e, t, r, n, i) {
+		if (e > t) throw new TypeError("CronPattern: From value is larger than to value: '" + i + "'");
+		if (r !== void 0) {
+			if (r === 0) throw new TypeError("CronPattern: Syntax error, illegal stepping: 0");
+			if (r > this[n].length) throw new TypeError("CronPattern: Syntax error, steps cannot be greater than maximum value of part (" + this[n].length + ")");
+		}
+	}
+	handleRangeWithStepping(e, t, r, n) {
+		if (e.toUpperCase().includes("W")) throw new TypeError("CronPattern: Syntax error, W is not allowed in ranges with stepping.");
+		let i = this.extractNth(e, t), a = i[0].match(/^(\d+)-(\d+)\/(\d+)$/);
+		if (a === null) throw new TypeError("CronPattern: Syntax error, illegal range with stepping: '" + e + "'");
+		let [, o, h, l] = a, y = parseInt(o, 10) + r, u = parseInt(h, 10) + r, d = parseInt(l, 10);
+		this.validateNotNaN(y, "CronPattern: Syntax error, illegal lower range (NaN)"), this.validateNotNaN(u, "CronPattern: Syntax error, illegal upper range (NaN)"), this.validateNotNaN(d, "CronPattern: Syntax error, illegal stepping: (NaN)"), this.validateRange(y, u, d, t, e);
+		for (let c = y; c <= u; c += d) this.setPart(t, c, i[1] || n);
+	}
+	extractNth(e, t) {
+		let r = e, n;
+		if (r.includes("#")) {
+			if (t !== "dayOfWeek") throw new Error("CronPattern: nth (#) only allowed in day-of-week field");
+			n = r.split("#")[1], r = r.split("#")[0];
+		} else if (r.toUpperCase().endsWith("L")) {
+			if (t !== "dayOfWeek") throw new Error("CronPattern: L modifier only allowed in day-of-week field (use L alone for day-of-month)");
+			n = "L", r = r.slice(0, -1);
+		}
+		return [r, n];
+	}
+	handleRange(e, t, r, n) {
+		if (e.toUpperCase().includes("W")) throw new TypeError("CronPattern: Syntax error, W is not allowed in a range.");
+		let i = this.extractNth(e, t), a = i[0].split("-");
+		if (a.length !== 2) throw new TypeError("CronPattern: Syntax error, illegal range: '" + e + "'");
+		let o = parseInt(a[0], 10) + r, h = parseInt(a[1], 10) + r;
+		this.validateNotNaN(o, "CronPattern: Syntax error, illegal lower range (NaN)"), this.validateNotNaN(h, "CronPattern: Syntax error, illegal upper range (NaN)"), this.validateRange(o, h, void 0, t, e);
+		for (let l = o; l <= h; l++) this.setPart(t, l, i[1] || n);
+	}
+	handleStepping(e, t, r, n) {
+		if (e.toUpperCase().includes("W")) throw new TypeError("CronPattern: Syntax error, W is not allowed in parts with stepping.");
+		let i = this.extractNth(e, t), a = i[0].split("/");
+		if (a.length !== 2) throw new TypeError("CronPattern: Syntax error, illegal stepping: '" + e + "'");
+		if (this.sloppyRanges) a[0] === "" && (a[0] = "*");
+		else {
+			if (a[0] === "") throw new TypeError("CronPattern: Syntax error, stepping with missing prefix ('" + e + "') is not allowed. Use wildcard (*/step) or range (min-max/step) instead.");
+			if (a[0] !== "*") throw new TypeError("CronPattern: Syntax error, stepping with numeric prefix ('" + e + "') is not allowed. Use wildcard (*/step) or range (min-max/step) instead.");
+		}
+		let o = 0;
+		a[0] !== "*" && (o = parseInt(a[0], 10) + r);
+		let h = parseInt(a[1], 10);
+		this.validateNotNaN(h, "CronPattern: Syntax error, illegal stepping: (NaN)"), this.validateRange(0, this[t].length - 1, h, t, e);
+		for (let l = o; l < this[t].length; l += h) this.setPart(t, l, i[1] || n);
+	}
+	replaceAlphaDays(e) {
+		return e.replace(/-sun/gi, "-7").replace(/sun/gi, "0").replace(/mon/gi, "1").replace(/tue/gi, "2").replace(/wed/gi, "3").replace(/thu/gi, "4").replace(/fri/gi, "5").replace(/sat/gi, "6");
+	}
+	replaceAlphaDaysQuartz(e) {
+		return e.replace(/sun/gi, "1").replace(/mon/gi, "2").replace(/tue/gi, "3").replace(/wed/gi, "4").replace(/thu/gi, "5").replace(/fri/gi, "6").replace(/sat/gi, "7");
+	}
+	replaceAlphaMonths(e) {
+		return e.replace(/jan/gi, "1").replace(/feb/gi, "2").replace(/mar/gi, "3").replace(/apr/gi, "4").replace(/may/gi, "5").replace(/jun/gi, "6").replace(/jul/gi, "7").replace(/aug/gi, "8").replace(/sep/gi, "9").replace(/oct/gi, "10").replace(/nov/gi, "11").replace(/dec/gi, "12");
+	}
+	handleNicknames(e) {
+		let t = e.trim().toLowerCase();
+		if (t === "@yearly" || t === "@annually") return "0 0 1 1 *";
+		if (t === "@monthly") return "0 0 1 * *";
+		if (t === "@weekly") return "0 0 * * 0";
+		if (t === "@daily" || t === "@midnight") return "0 0 * * *";
+		if (t === "@hourly") return "0 * * * *";
+		if (t === "@reboot") throw new TypeError("CronPattern: @reboot is not supported in this environment. This is an event-based trigger that requires system startup detection.");
+		return e;
+	}
+	setNthWeekdayOfMonth(e, t) {
+		if (typeof t != "number" && t.toUpperCase() === "L") this.dayOfWeek[e] = this.dayOfWeek[e] | 32;
+		else if (t === 63) this.dayOfWeek[e] = 63;
+		else if (t < 6 && t > 0) this.dayOfWeek[e] = this.dayOfWeek[e] | O[t - 1];
+		else throw new TypeError(`CronPattern: nth weekday out of range, should be 1-5 or L. Value: ${t}, Type: ${typeof t}`);
+	}
+};
+var P = [
+	31,
+	28,
+	31,
+	30,
+	31,
+	30,
+	31,
+	31,
+	30,
+	31,
+	30,
+	31
+], f = [
+	[
+		"month",
+		"year",
+		0
+	],
+	[
+		"day",
+		"month",
+		-1
+	],
+	[
+		"hour",
+		"day",
+		0
+	],
+	[
+		"minute",
+		"hour",
+		0
+	],
+	[
+		"second",
+		"minute",
+		0
+	]
+], m = class s {
+	tz;
+	ms;
+	second;
+	minute;
+	hour;
+	day;
+	month;
+	year;
+	constructor(e, t) {
+		if (this.tz = t, e && e instanceof Date) if (!isNaN(e)) this.fromDate(e);
+		else throw new TypeError("CronDate: Invalid date passed to CronDate constructor");
+		else if (e == null) this.fromDate(/* @__PURE__ */ new Date());
+		else if (e && typeof e == "string") this.fromString(e);
+		else if (e instanceof s) this.fromCronDate(e);
+		else throw new TypeError("CronDate: Invalid type (" + typeof e + ") passed to CronDate constructor");
+	}
+	getLastDayOfMonth(e, t) {
+		return t !== 1 ? P[t] : new Date(Date.UTC(e, t + 1, 0)).getUTCDate();
+	}
+	getLastWeekday(e, t) {
+		let r = this.getLastDayOfMonth(e, t), i = new Date(Date.UTC(e, t, r)).getUTCDay();
+		return i === 0 ? r - 2 : i === 6 ? r - 1 : r;
+	}
+	getNearestWeekday(e, t, r) {
+		let n = this.getLastDayOfMonth(e, t);
+		if (r > n) return -1;
+		let a = new Date(Date.UTC(e, t, r)).getUTCDay();
+		return a === 0 ? r === n ? r - 2 : r + 1 : a === 6 ? r === 1 ? r + 2 : r - 1 : r;
+	}
+	isNthWeekdayOfMonth(e, t, r, n) {
+		let a = new Date(Date.UTC(e, t, r)).getUTCDay(), o = 0;
+		for (let h = 1; h <= r; h++) new Date(Date.UTC(e, t, h)).getUTCDay() === a && o++;
+		if (n & 63 && O[o - 1] & n) return !0;
+		if (n & 32) {
+			let h = this.getLastDayOfMonth(e, t);
+			for (let l = r + 1; l <= h; l++) if (new Date(Date.UTC(e, t, l)).getUTCDay() === a) return !1;
+			return !0;
+		}
+		return !1;
+	}
+	fromDate(e) {
+		if (this.tz !== void 0) if (typeof this.tz == "number") this.ms = e.getUTCMilliseconds(), this.second = e.getUTCSeconds(), this.minute = e.getUTCMinutes() + this.tz, this.hour = e.getUTCHours(), this.day = e.getUTCDate(), this.month = e.getUTCMonth(), this.year = e.getUTCFullYear(), this.apply();
+		else try {
+			let t = g(e, this.tz);
+			this.ms = e.getMilliseconds(), this.second = t.s, this.minute = t.i, this.hour = t.h, this.day = t.d, this.month = t.m - 1, this.year = t.y;
+		} catch (t) {
+			let r = t instanceof Error ? t.message : String(t);
+			throw new TypeError(`CronDate: Failed to convert date to timezone '${this.tz}'. This may happen with invalid timezone names or dates. Original error: ${r}`);
+		}
+		else this.ms = e.getMilliseconds(), this.second = e.getSeconds(), this.minute = e.getMinutes(), this.hour = e.getHours(), this.day = e.getDate(), this.month = e.getMonth(), this.year = e.getFullYear();
+	}
+	fromCronDate(e) {
+		this.tz = e.tz, this.year = e.year, this.month = e.month, this.day = e.day, this.hour = e.hour, this.minute = e.minute, this.second = e.second, this.ms = e.ms;
+	}
+	apply() {
+		if (this.month > 11 || this.month < 0 || this.day > P[this.month] || this.day < 1 || this.hour > 59 || this.minute > 59 || this.second > 59 || this.hour < 0 || this.minute < 0 || this.second < 0) {
+			let e = new Date(Date.UTC(this.year, this.month, this.day, this.hour, this.minute, this.second, this.ms));
+			return this.ms = e.getUTCMilliseconds(), this.second = e.getUTCSeconds(), this.minute = e.getUTCMinutes(), this.hour = e.getUTCHours(), this.day = e.getUTCDate(), this.month = e.getUTCMonth(), this.year = e.getUTCFullYear(), !0;
+		} else return !1;
+	}
+	fromString(e) {
+		if (typeof this.tz == "number") {
+			let t = v(e);
+			this.ms = t.getUTCMilliseconds(), this.second = t.getUTCSeconds(), this.minute = t.getUTCMinutes(), this.hour = t.getUTCHours(), this.day = t.getUTCDate(), this.month = t.getUTCMonth(), this.year = t.getUTCFullYear(), this.apply();
+		} else return this.fromDate(v(e, this.tz));
+	}
+	findNext(e, t, r, n) {
+		return this._findMatch(e, t, r, n, 1);
+	}
+	_findMatch(e, t, r, n, i) {
+		let a = this[t], o;
+		r.lastDayOfMonth && (o = this.getLastDayOfMonth(this.year, this.month));
+		let h = !r.starDOW && t == "day" ? new Date(Date.UTC(this.year, this.month, 1, 0, 0, 0, 0)).getUTCDay() : void 0, l = this[t] + n, y = i === 1 ? (u) => u < r[t].length : (u) => u >= 0;
+		for (let u = l; y(u); u += i) {
+			let d = r[t][u];
+			if (t === "day" && !d) {
+				for (let c = 0; c < r.nearestWeekdays.length; c++) if (r.nearestWeekdays[c]) {
+					let M = this.getNearestWeekday(this.year, this.month, c - n);
+					if (M === -1) continue;
+					if (M === u - n) {
+						d = 1;
+						break;
+					}
+				}
+			}
+			if (t === "day" && r.lastWeekday) {
+				let c = this.getLastWeekday(this.year, this.month);
+				u - n === c && (d = 1);
+			}
+			if (t === "day" && r.lastDayOfMonth && u - n == o && (d = 1), t === "day" && !r.starDOW) {
+				let c = r.dayOfWeek[(h + (u - n - 1)) % 7];
+				if (c && c & 63) c = this.isNthWeekdayOfMonth(this.year, this.month, u - n, c) ? 1 : 0;
+				else if (c) throw new Error(`CronDate: Invalid value for dayOfWeek encountered. ${c}`);
+				r.useAndLogic ? d = d && c : !e.domAndDow && !r.starDOM ? d = d || c : d = d && c;
+			}
+			if (d) return this[t] = u - n, a !== this[t] ? 2 : 1;
+		}
+		return 3;
+	}
+	recurse(e, t, r) {
+		if (r === 0 && !e.starYear) {
+			if (this.year >= 0 && this.year < e.year.length && e.year[this.year] === 0) {
+				let i = -1;
+				for (let a = this.year + 1; a < e.year.length && a < 1e4; a++) if (e.year[a] === 1) {
+					i = a;
+					break;
+				}
+				if (i === -1) return null;
+				this.year = i, this.month = 0, this.day = 1, this.hour = 0, this.minute = 0, this.second = 0, this.ms = 0;
+			}
+			if (this.year >= 1e4) return null;
+		}
+		let n = this.findNext(t, f[r][0], e, f[r][2]);
+		if (n > 1) {
+			let i = r + 1;
+			for (; i < f.length;) this[f[i][0]] = -f[i][2], i++;
+			if (n === 3) {
+				if (this[f[r][1]]++, this[f[r][0]] = -f[r][2], this.apply(), r === 0 && !e.starYear) {
+					for (; this.year >= 0 && this.year < e.year.length && e.year[this.year] === 0 && this.year < 1e4;) this.year++;
+					if (this.year >= 1e4 || this.year >= e.year.length) return null;
+				}
+				return this.recurse(e, t, 0);
+			} else if (this.apply()) return this.recurse(e, t, r - 1);
+		}
+		return r += 1, r >= f.length ? this : (e.starYear ? this.year >= 3e3 : this.year >= 1e4) ? null : this.recurse(e, t, r);
+	}
+	increment(e, t, r) {
+		return this.second += t.interval !== void 0 && t.interval > 1 && r ? t.interval : 1, this.ms = 0, this.apply(), this.recurse(e, t, 0);
+	}
+	decrement(e, t) {
+		return this.second -= t.interval !== void 0 && t.interval > 1 ? t.interval : 1, this.ms = 0, this.apply(), this.recurseBackward(e, t, 0, 0);
+	}
+	recurseBackward(e, t, r, n = 0) {
+		if (n > 1e4) return null;
+		if (r === 0 && !e.starYear) {
+			if (this.year >= 0 && this.year < e.year.length && e.year[this.year] === 0) {
+				let a = -1;
+				for (let o = this.year - 1; o >= 0; o--) if (e.year[o] === 1) {
+					a = o;
+					break;
+				}
+				if (a === -1) return null;
+				this.year = a, this.month = 11, this.day = 31, this.hour = 23, this.minute = 59, this.second = 59, this.ms = 0;
+			}
+			if (this.year < 0) return null;
+		}
+		let i = this.findPrevious(t, f[r][0], e, f[r][2]);
+		if (i > 1) {
+			let a = r + 1;
+			for (; a < f.length;) {
+				let o = f[a][0], h = f[a][2], l = this.getMaxPatternValue(o, e, h);
+				this[o] = l, a++;
+			}
+			if (i === 3) {
+				if (this[f[r][1]]--, r === 0) {
+					let y = this.getLastDayOfMonth(this.year, this.month);
+					this.day > y && (this.day = y);
+				}
+				if (r === 1) if (this.day <= 0) this.day = 1;
+				else {
+					let y = this.year, u = this.month;
+					for (; u < 0;) u += 12, y--;
+					for (; u > 11;) u -= 12, y++;
+					let d = u !== 1 ? P[u] : new Date(Date.UTC(y, u + 1, 0)).getUTCDate();
+					this.day > d && (this.day = d);
+				}
+				this.apply();
+				let o = f[r][0], h = f[r][2], l = this.getMaxPatternValue(o, e, h);
+				if (o === "day") {
+					let y = this.getLastDayOfMonth(this.year, this.month);
+					this[o] = Math.min(l, y);
+				} else this[o] = l;
+				if (this.apply(), r === 0) {
+					let y = f[1][2], u = this.getMaxPatternValue("day", e, y), d = this.getLastDayOfMonth(this.year, this.month), c = Math.min(u, d);
+					c !== this.day && (this.day = c, this.hour = this.getMaxPatternValue("hour", e, f[2][2]), this.minute = this.getMaxPatternValue("minute", e, f[3][2]), this.second = this.getMaxPatternValue("second", e, f[4][2]));
+				}
+				if (r === 0 && !e.starYear) {
+					for (; this.year >= 0 && this.year < e.year.length && e.year[this.year] === 0;) this.year--;
+					if (this.year < 0) return null;
+				}
+				return this.recurseBackward(e, t, 0, n + 1);
+			} else if (this.apply()) return this.recurseBackward(e, t, r - 1, n + 1);
+		}
+		return r += 1, r >= f.length ? this : this.year < 0 ? null : this.recurseBackward(e, t, r, n + 1);
+	}
+	getMaxPatternValue(e, t, r) {
+		if (e === "day" && t.lastDayOfMonth) return this.getLastDayOfMonth(this.year, this.month);
+		if (e === "day" && !t.starDOW) return this.getLastDayOfMonth(this.year, this.month);
+		for (let n = t[e].length - 1; n >= 0; n--) if (t[e][n]) return n - r;
+		return t[e].length - 1 - r;
+	}
+	findPrevious(e, t, r, n) {
+		return this._findMatch(e, t, r, n, -1);
+	}
+	getDate(e) {
+		return e || this.tz === void 0 ? new Date(this.year, this.month, this.day, this.hour, this.minute, this.second, this.ms) : typeof this.tz == "number" ? new Date(Date.UTC(this.year, this.month, this.day, this.hour, this.minute - this.tz, this.second, this.ms)) : k(b(this.year, this.month + 1, this.day, this.hour, this.minute, this.second, this.tz), !1);
+	}
+	getTime() {
+		return this.getDate(!1).getTime();
+	}
+	match(e, t) {
+		if (!e.starYear && (this.year < 0 || this.year >= e.year.length || e.year[this.year] === 0)) return !1;
+		for (let r = 0; r < f.length; r++) {
+			let n = f[r][0], i = f[r][2], a = this[n];
+			if (a + i < 0 || a + i >= e[n].length) return !1;
+			let o = e[n][a + i];
+			if (n === "day") {
+				if (!o) {
+					for (let h = 0; h < e.nearestWeekdays.length; h++) if (e.nearestWeekdays[h]) {
+						let l = this.getNearestWeekday(this.year, this.month, h - i);
+						if (l !== -1 && l === a) {
+							o = 1;
+							break;
+						}
+					}
+				}
+				if (e.lastWeekday) a === this.getLastWeekday(this.year, this.month) && (o = 1);
+				if (e.lastDayOfMonth) a === this.getLastDayOfMonth(this.year, this.month) && (o = 1);
+				if (!e.starDOW) {
+					let h = new Date(Date.UTC(this.year, this.month, 1, 0, 0, 0, 0)).getUTCDay(), l = e.dayOfWeek[(h + (a - 1)) % 7];
+					l && l & 63 && (l = this.isNthWeekdayOfMonth(this.year, this.month, a, l) ? 1 : 0), e.useAndLogic ? o = o && l : !t.domAndDow && !e.starDOM ? o = o || l : o = o && l;
+				}
+			}
+			if (!o) return !1;
+		}
+		return !0;
+	}
+};
+function R(s) {
+	if (s === void 0 && (s = {}), delete s.name, s.legacyMode !== void 0 && s.domAndDow === void 0 ? s.domAndDow = !s.legacyMode : s.domAndDow === void 0 && (s.domAndDow = !1), s.legacyMode = !s.domAndDow, s.paused = s.paused === void 0 ? !1 : s.paused, s.maxRuns = s.maxRuns === void 0 ? Infinity : s.maxRuns, s.catch = s.catch === void 0 ? !1 : s.catch, s.interval = s.interval === void 0 ? 0 : parseInt(s.interval.toString(), 10), s.utcOffset = s.utcOffset === void 0 ? void 0 : parseInt(s.utcOffset.toString(), 10), s.dayOffset = s.dayOffset === void 0 ? 0 : parseInt(s.dayOffset.toString(), 10), s.unref = s.unref === void 0 ? !1 : s.unref, s.mode = s.mode === void 0 ? "auto" : s.mode, s.alternativeWeekdays = s.alternativeWeekdays === void 0 ? !1 : s.alternativeWeekdays, s.sloppyRanges = s.sloppyRanges === void 0 ? !1 : s.sloppyRanges, ![
+		"auto",
+		"5-part",
+		"6-part",
+		"7-part",
+		"5-or-6-parts",
+		"6-or-7-parts"
+	].includes(s.mode)) throw new Error("CronOptions: mode must be one of 'auto', '5-part', '6-part', '7-part', '5-or-6-parts', or '6-or-7-parts'.");
+	if (s.startAt && (s.startAt = new m(s.startAt, s.timezone)), s.stopAt && (s.stopAt = new m(s.stopAt, s.timezone)), s.interval !== null) {
+		if (isNaN(s.interval)) throw new Error("CronOptions: Supplied value for interval is not a number");
+		if (s.interval < 0) throw new Error("CronOptions: Supplied value for interval can not be negative");
+	}
+	if (s.utcOffset !== void 0) {
+		if (isNaN(s.utcOffset)) throw new Error("CronOptions: Invalid value passed for utcOffset, should be number representing minutes offset from UTC.");
+		if (s.utcOffset < -870 || s.utcOffset > 870) throw new Error("CronOptions: utcOffset out of bounds.");
+		if (s.utcOffset !== void 0 && s.timezone) throw new Error("CronOptions: Combining 'utcOffset' with 'timezone' is not allowed.");
+	}
+	if (s.unref !== !0 && s.unref !== !1) throw new Error("CronOptions: Unref should be either true, false or undefined(false).");
+	if (s.dayOffset !== void 0 && s.dayOffset !== 0 && isNaN(s.dayOffset)) throw new Error("CronOptions: Invalid value passed for dayOffset, should be a number representing days to offset.");
+	return s;
+}
+function p(s) {
+	return Object.prototype.toString.call(s) === "[object Function]" || typeof s == "function" || s instanceof Function;
+}
+function _(s) {
+	return p(s);
+}
+function x(s) {
+	typeof Deno < "u" && typeof Deno.unrefTimer < "u" ? Deno.unrefTimer(s) : s && typeof s.unref < "u" && s.unref();
+}
+var W = 30 * 1e3, w = [], E = class {
+	name;
+	options;
+	_states;
+	fn;
+	getTz() {
+		return this.options.timezone || this.options.utcOffset;
+	}
+	applyDayOffset(e) {
+		if (this.options.dayOffset !== void 0 && this.options.dayOffset !== 0) {
+			let t = this.options.dayOffset * 24 * 60 * 60 * 1e3;
+			return new Date(e.getTime() + t);
+		}
+		return e;
+	}
+	constructor(e, t, r) {
+		let n, i;
+		if (p(t)) i = t;
+		else if (typeof t == "object") n = t;
+		else if (t !== void 0) throw new Error("Cron: Invalid argument passed for optionsIn. Should be one of function, or object (options).");
+		if (p(r)) i = r;
+		else if (typeof r == "object") n = r;
+		else if (r !== void 0) throw new Error("Cron: Invalid argument passed for funcIn. Should be one of function, or object (options).");
+		if (this.name = n?.name, this.options = R(n), this._states = {
+			kill: !1,
+			blocking: !1,
+			previousRun: void 0,
+			currentRun: void 0,
+			once: void 0,
+			currentTimeout: void 0,
+			maxRuns: n ? n.maxRuns : void 0,
+			paused: n ? n.paused : !1,
+			pattern: new C("* * * * *", void 0, { mode: "auto" })
+		}, e && (e instanceof Date || typeof e == "string" && e.indexOf(":") > 0) ? this._states.once = new m(e, this.getTz()) : this._states.pattern = new C(e, this.options.timezone, {
+			mode: this.options.mode,
+			alternativeWeekdays: this.options.alternativeWeekdays,
+			sloppyRanges: this.options.sloppyRanges
+		}), this.name) {
+			if (w.find((o) => o.name === this.name)) throw new Error("Cron: Tried to initialize new named job '" + this.name + "', but name already taken.");
+			w.push(this);
+		}
+		return i !== void 0 && _(i) && (this.fn = i, this.schedule()), this;
+	}
+	nextRun(e) {
+		let t = this._next(e);
+		return t ? this.applyDayOffset(t.getDate(!1)) : null;
+	}
+	nextRuns(e, t) {
+		this._states.maxRuns !== void 0 && e > this._states.maxRuns && (e = this._states.maxRuns);
+		let r = t || this._states.currentRun || void 0;
+		return this._enumerateRuns(e, r, "next");
+	}
+	previousRuns(e, t) {
+		return this._enumerateRuns(e, t || void 0, "previous");
+	}
+	_enumerateRuns(e, t, r) {
+		let n = [], i = t ? new m(t, this.getTz()) : null, a = r === "next" ? this._next : this._previous;
+		for (; e--;) {
+			let o = a.call(this, i);
+			if (!o) break;
+			let h = o.getDate(!1);
+			n.push(this.applyDayOffset(h)), i = o;
+		}
+		return n;
+	}
+	match(e) {
+		if (this._states.once) {
+			let r = new m(e, this.getTz());
+			r.ms = 0;
+			let n = new m(this._states.once, this.getTz());
+			return n.ms = 0, r.getTime() === n.getTime();
+		}
+		let t = new m(e, this.getTz());
+		return t.ms = 0, t.match(this._states.pattern, this.options);
+	}
+	getPattern() {
+		if (!this._states.once) return this._states.pattern ? this._states.pattern.pattern : void 0;
+	}
+	getOnce() {
+		return this._states.once ? this._states.once.getDate() : null;
+	}
+	isRunning() {
+		let e = this.nextRun(this._states.currentRun), t = !this._states.paused, r = this.fn !== void 0, n = !this._states.kill;
+		return t && r && n && e !== null;
+	}
+	isStopped() {
+		return this._states.kill;
+	}
+	isBusy() {
+		return this._states.blocking;
+	}
+	currentRun() {
+		return this._states.currentRun ? this._states.currentRun.getDate() : null;
+	}
+	previousRun() {
+		return this._states.previousRun ? this._states.previousRun.getDate() : null;
+	}
+	msToNext(e) {
+		let t = this._next(e);
+		return t ? e instanceof m || e instanceof Date ? t.getTime() - e.getTime() : t.getTime() - new m(e).getTime() : null;
+	}
+	stop() {
+		this._states.kill = !0, this._states.currentTimeout && clearTimeout(this._states.currentTimeout);
+		let e = w.indexOf(this);
+		e >= 0 && w.splice(e, 1);
+	}
+	pause() {
+		return this._states.paused = !0, !this._states.kill;
+	}
+	resume() {
+		return this._states.paused = !1, !this._states.kill;
+	}
+	schedule(e) {
+		if (e && this.fn) throw new Error("Cron: It is not allowed to schedule two functions using the same Croner instance.");
+		e && (this.fn = e);
+		let t = this.msToNext(), r = this.nextRun(this._states.currentRun);
+		return t == null || isNaN(t) || r === null ? this : (t > W && (t = W), this._states.currentTimeout = setTimeout(() => this._checkTrigger(r), t), this._states.currentTimeout && this.options.unref && x(this._states.currentTimeout), this);
+	}
+	async _trigger(e) {
+		this._states.blocking = !0, this._states.currentRun = new m(void 0, this.getTz());
+		try {
+			if (this.options.catch) try {
+				this.fn !== void 0 && await this.fn(this, this.options.context);
+			} catch (t) {
+				if (p(this.options.catch)) try {
+					this.options.catch(t, this);
+				} catch {}
+			}
+			else this.fn !== void 0 && await this.fn(this, this.options.context);
+		} finally {
+			this._states.previousRun = new m(e, this.getTz()), this._states.blocking = !1;
+		}
+	}
+	async trigger() {
+		await this._trigger();
+	}
+	runsLeft() {
+		return this._states.maxRuns;
+	}
+	_checkTrigger(e) {
+		let t = /* @__PURE__ */ new Date(), r = !this._states.paused && t.getTime() >= e.getTime(), n = this._states.blocking && this.options.protect;
+		r && !n ? (this._states.maxRuns !== void 0 && this._states.maxRuns--, this._trigger()) : r && n && p(this.options.protect) && setTimeout(() => this.options.protect(this), 0), this.schedule();
+	}
+	_next(e) {
+		let t = !!(e || this._states.currentRun), r = !1;
+		!e && this.options.startAt && this.options.interval && ([e, t] = this._calculatePreviousRun(e, t), r = !e), e = new m(e, this.getTz()), this.options.startAt && e && e.getTime() < this.options.startAt.getTime() && (e = this.options.startAt);
+		let n = this._states.once || new m(e, this.getTz());
+		return !r && n !== this._states.once && (n = n.increment(this._states.pattern, this.options, t)), this._states.once && this._states.once.getTime() <= e.getTime() || n === null || this._states.maxRuns !== void 0 && this._states.maxRuns <= 0 || this._states.kill || this.options.stopAt && n.getTime() >= this.options.stopAt.getTime() ? null : n;
+	}
+	_previous(e) {
+		let t = new m(e, this.getTz());
+		this.options.stopAt && t.getTime() > this.options.stopAt.getTime() && (t = this.options.stopAt);
+		let r = new m(t, this.getTz());
+		return this._states.once ? this._states.once.getTime() < t.getTime() ? this._states.once : null : (r = r.decrement(this._states.pattern, this.options), r === null || this.options.startAt && r.getTime() < this.options.startAt.getTime() ? null : r);
+	}
+	_calculatePreviousRun(e, t) {
+		let r = new m(void 0, this.getTz()), n = e;
+		if (this.options.startAt.getTime() <= r.getTime()) {
+			n = this.options.startAt;
+			let i = n.getTime() + this.options.interval * 1e3;
+			for (; i <= r.getTime();) n = new m(n, this.getTz()).increment(this._states.pattern, this.options, !0), i = n.getTime() + this.options.interval * 1e3;
+			t = !0;
+		}
+		return n === null && (n = void 0), [n, t];
+	}
+};
+//#endregion
+//#region src/builtins/backup-orchestrator/cron-helpers.ts
+/**
+* Cron helpers — wraps `croner` so the orchestrator + the `previewNextRuns`
+* cap method share one validation + next-run-computation surface.
+*
+* `croner` is the opinionated node cron library we standardize on
+* server-side: pure JS, native TypeScript types, supports the full
+* 5-field POSIX cron grammar plus seconds (6-field), DST-aware, and
+* exposes `nextRun()` / `nextRuns(N)` for peeking without scheduling.
+* The orchestrator uses the peeking API (it has its own polling
+* loop); future surfaces (e.g. event-driven retention sweeps) can
+* register an actual scheduled `Cron(pattern, fn)` and let croner
+* own the timer.
+*/
+/**
+* Validate a cron expression and return its next firing time strictly
+* after `after`, expressed as ms-epoch. Returns `null` when the
+* expression has no future runs (croner returns null e.g. for
+* fully-bounded patterns that have already elapsed). Throws when the
+* expression is syntactically invalid — callers are expected to
+* surface that to the operator.
+*/
+function computeNextDue(cron, after) {
+	const next = new E(cron, { paused: true }).nextRun(new Date(after));
+	return next ? next.getTime() : null;
+}
+/**
+* Validate without computing — returns true when `cron` parses, false
+* otherwise. Used by the cap-router input zod schema's `.refine`
+* callback to reject malformed expressions at the boundary instead
+* of at scheduler-tick time.
+*/
+function isValidCron(cron) {
+	try {
+		new E(cron, { paused: true });
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Peek the next N firing times after `after` (default: now). Used by
+* the admin UI's CronEditor preview pane — operators see the next
+* 3–5 runs as they edit the expression so a wrong pattern is
+* obvious before save.
+*/
+function previewNextRuns(cron, count, after) {
+	const job = new E(cron, { paused: true });
+	const baseline = after !== void 0 ? new Date(after) : /* @__PURE__ */ new Date();
+	const out = [];
+	let cursor = baseline;
+	for (let i = 0; i < count; i++) {
+		cursor = job.nextRun(cursor);
+		if (!cursor) break;
+		out.push(cursor.getTime());
+	}
+	return out;
+}
+//#endregion
+//#region src/builtins/backup-orchestrator/backup-orchestrator.addon.ts
+/**
+* `backup-orchestrator` builtin — singleton owner of the `backup` cap.
+*
+* Responsibilities:
+*   - Schedule (cron-like timer at top of hour, daily/weekly cadence)
+*   - Per-destination policy (enable/disable, retention count, label)
+*     persisted in `backup_destination_policies` (this builtin owns
+*     the table).
+*   - Archive build (one tar.gz with embedded manifest, fanned out to
+*     every selected `backups`-typed `StorageLocation` via the
+*     consumer-facing `storage` cap's chunked upload protocol).
+*   - Aggregate listing/restore/delete across destinations — operates
+*     on the per-location `manifests.json` index file, not the
+*     archives directly.
+*
+* Storage routing: destinations are
+* `api.storage.listLocations({ type: 'backups' })` — every operator-
+* visible `backups` location IS a destination. The orchestrator joins
+* that list with the `backup_destination_policies` table to surface
+* `enabled` / `retentionCount` / `label`. The actual archive bytes
+* travel through `api.storage.beginUpload` / `writeChunk` /
+* `finalizeUpload`, with the staging archive built into the `cache`
+* location.
+*/
+/**
+* Hardcoded seed for newly-discovered `backups` locations. Operators
+* tune retention per-destination after creation via the destinations
+* table. Promoted from a configurable global to a constant when the
+* orchestrator's settings panel was retired (per-destination cron +
+* inline retention input on the destinations row replaces every knob
+* the panel used to expose).
+*/
+var DEFAULT_RETENTION_COUNT = 7;
+/**
+* Default cron stamped on a freshly-discovered `backups` location.
+* Operators can edit it from the destination row; setting empty in
+* the editor flips the destination back to manual-only. Daily 03:00
+* server-local mirrors the previous global default.
+*/
+var DEFAULT_CRON = "0 3 * * *";
+var SCHEDULE_TICK_MS = 6e4;
+/**
+* Build the human-facing archive label. Every archive always carries
+* the destination id and the creation date — useful in restore wizards
+* + cross-destination listings where UUIDs are unreadable.
+*
+* Format: `${destinationId} · ${YYYY-MM-DD HH:mm}[${suffix}]`. Suffix is
+* an optional operator-provided tag (e.g. "before-migration") appended
+* after another middot. UTC is intentional — labels are also written
+* into the per-location manifest which travels across timezones with
+* the backup.
+*/
+function formatArchiveLabel(destinationId, createdAt, suffix) {
+	const d = new Date(createdAt);
+	const pad = (n) => String(n).padStart(2, "0");
+	const stamp = `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}`;
+	const trimmed = suffix?.trim();
+	return trimmed ? `${destinationId} · ${stamp} · ${trimmed}` : `${destinationId} · ${stamp}`;
+}
+/**
+* Chunk size for the read-stream that feeds the chunked upload pipe.
+* 8 MiB is well under the WS frame limit (16 MiB on tRPC) with headroom.
+*/
+var UPLOAD_CHUNK_BYTES = 8 * 1024 * 1024;
+/** Manifest id this addon registers under (must match `package.json`). */
+var ORCHESTRATOR_ADDON_ID = "backup-orchestrator";
+var BackupOrchestratorAddon = class extends BaseAddon {
+	systemBackup = null;
+	policies = null;
+	dataDir = "";
+	scheduleTimer = null;
+	/**
+	* Baseline used as the "after" anchor when a policy has a cron but
+	* has never run yet (no `lastRunAt`). Set on orchestrator boot so a
+	* pattern that fires every minute doesn't immediately replay every
+	* historical "missed" run from epoch 0.
+	*/
+	scheduleBaselineAt = Date.now();
+	manifestLock = new LocationManifestLock();
+	constructor() {
+		super({});
+	}
+	async onInitialize() {
+		const envDataPath = process.env["CAMSTACK_DATA"];
+		const fallbackLocation = await this.ctx.api.storage.resolve.query({
+			location: "data",
+			relativePath: ""
+		}).catch(() => null);
+		this.dataDir = envDataPath ?? (fallbackLocation ? parentDir(fallbackLocation) : "camstack-data");
+		this.systemBackup = new SystemBackupService(this.dataDir, this.ctx.logger);
+		this.policies = this.resolvePolicyService();
+		if (this.policies) try {
+			await this.policies.initialize();
+		} catch (err) {
+			this.ctx.logger.error("backup-orchestrator: policy table init failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			this.policies = null;
+		}
+		const provider = {
+			listDestinations: () => this.listDestinations(),
+			list: () => this.aggregatedList(),
+			listLocations: () => this.systemBackup.statLocations(),
+			trigger: (input) => this.triggerBackup(input),
+			getEntries: (input) => this.getEntries(input),
+			restore: (input) => this.scheduleRestore(input),
+			delete: (input) => this.deleteArchive(input),
+			listArchives: (input) => this.listArchives(input),
+			upsertDestinationPolicy: (input) => this.upsertDestinationPolicy(input),
+			previewSchedule: (input) => this.previewSchedule(input)
+		};
+		this.startScheduleTimer();
+		this.ctx.logger.info("Backup orchestrator initialized", { meta: {
+			dataDir: this.dataDir,
+			policies: this.policies !== null
+		} });
+		return [{
+			capability: backupCapability,
+			provider
+		}];
+	}
+	async onShutdown() {
+		this.stopScheduleTimer();
+		this.systemBackup = null;
+		this.policies = null;
+	}
+	/**
+	* Aggregate destinations from `api.storage.listLocations({ type: 'backups' })`
+	* joined with the per-destination policy table. New locations get an
+	* `ensureDefault` policy seeded transparently (enabled=true,
+	* retentionCount=defaultRetentionCount). Pre-existing operator-edited
+	* policies are preserved by the `ensureDefault` idempotency.
+	*/
+	async listDestinations() {
+		const locations = await this.fetchBackupLocations();
+		const policies = await this.loadPoliciesIndexed(locations.map((l) => l.id));
+		const lastSuccess = await Promise.all(locations.map(async (loc) => {
+			try {
+				const manifest = await readLocationManifest(this.storageApi(), loc.id);
+				return [loc.id, latestArchiveOf(manifest)];
+			} catch {
+				return [loc.id, void 0];
+			}
+		}));
+		const lastSuccessByLoc = new Map(lastSuccess);
+		return locations.map((loc) => this.toDestinationWire(loc, policies.get(loc.id), lastSuccessByLoc.get(loc.id)));
+	}
+	async fetchBackupLocations() {
+		try {
+			return await this.ctx.api.storage.listLocations.query({ type: "backups" });
+		} catch (err) {
+			this.ctx.logger.error("backup-orchestrator: listLocations failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			return [];
+		}
+	}
+	/**
+	* Load every persisted policy and key it by `locationId`, while
+	* lazily seeding a default for any `locationId` we haven't seen
+	* before. Idempotent — `ensureDefault` no-ops on already-persisted
+	* rows. Falls back to the in-memory default policy when the policy
+	* service isn't wired (no settings-store backend available).
+	*/
+	async loadPoliciesIndexed(locationIds) {
+		const out = /* @__PURE__ */ new Map();
+		if (!this.policies) {
+			for (const id of locationIds) out.set(id, this.fallbackPolicy(id));
+			return out;
+		}
+		const persisted = await this.policies.list().catch((err) => {
+			this.ctx.logger.warn("backup-orchestrator: policy list failed — using defaults", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			return [];
+		});
+		for (const p of persisted) out.set(p.locationId, p);
+		for (const id of locationIds) {
+			if (out.has(id)) continue;
+			try {
+				const fresh = await this.policies.ensureDefault(id, {
+					retentionCount: DEFAULT_RETENTION_COUNT,
+					cron: DEFAULT_CRON
+				});
+				out.set(id, fresh);
+			} catch (err) {
+				this.ctx.logger.warn("backup-orchestrator: ensureDefault failed", { meta: {
+					locationId: id,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+				out.set(id, this.fallbackPolicy(id));
+			}
+		}
+		return out;
+	}
+	fallbackPolicy(locationId) {
+		return {
+			locationId,
+			enabled: true,
+			retentionCount: DEFAULT_RETENTION_COUNT,
+			cron: DEFAULT_CRON
+		};
+	}
+	toDestinationWire(loc, policy, latest) {
+		const effective = policy ?? this.fallbackPolicy(loc.id);
+		const subId = extractSlug(loc.id);
+		const displayName = effective.label && effective.label.length > 0 ? effective.label : loc.displayName;
+		return {
+			id: loc.id,
+			addonId: ORCHESTRATOR_ADDON_ID,
+			subId,
+			displayName,
+			kind: kindFromProviderId(loc.providerId),
+			triggerSupported: effective.enabled,
+			restoreSupported: true,
+			enabled: effective.enabled,
+			retentionCount: effective.retentionCount,
+			...effective.label !== void 0 ? { label: effective.label } : {},
+			...latest !== void 0 ? { lastSuccessAt: latest.createdAt } : {},
+			...latest !== void 0 ? { lastSuccessSizeBytes: latest.sizeBytes } : {},
+			...effective.cron !== void 0 ? { cron: effective.cron } : {},
+			...effective.lastRunAt !== void 0 ? { lastRunAt: effective.lastRunAt } : {},
+			...effective.cron !== void 0 && effective.cron.trim().length > 0 ? { nextRunAt: this.safeNextDue(effective.cron, effective.lastRunAt) } : {}
+		};
+	}
+	/**
+	* Compute next-due ms-epoch for a cron, or `undefined` on parse error.
+	* Catches so a single malformed cron doesn't blank out the whole
+	* destinations list at the cap surface.
+	*/
+	safeNextDue(cron, after) {
+		try {
+			return computeNextDue(cron, after ?? this.scheduleBaselineAt) ?? void 0;
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Aggregate listing — read every `backups` location's `manifests.json`
+	* and return one wire entry per archive, tagged with `destinationId`.
+	* Failures on individual locations are logged and skipped so a single
+	* unreachable destination doesn't blank out the whole UI.
+	*/
+	async aggregatedList() {
+		const locations = await this.fetchBackupLocations();
+		const out = [];
+		for (const loc of locations) {
+			let manifest;
+			try {
+				manifest = await readLocationManifest(this.storageApi(), loc.id);
+			} catch (err) {
+				this.ctx.logger.warn("backup list: manifest read failed", { meta: {
+					locationId: loc.id,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+				continue;
+			}
+			for (const a of manifest.archives) {
+				const entry = {
+					id: a.id,
+					destinationId: loc.id,
+					createdAt: a.createdAt,
+					sizeBytes: a.sizeBytes,
+					...a.label !== void 0 ? { label: a.label } : {},
+					locations: [...a.manifest.locations]
+				};
+				out.push(entry);
+			}
+		}
+		return out;
+	}
+	/**
+	* Build a single archive in the `cache` storage location, then push
+	* it to every selected destination via the storage cap's chunked
+	* upload protocol. Per-destination errors are logged and counted
+	* via allSettled semantics — one bad sink doesn't kill the run. The
+	* cache file is deleted in `finally` so a crash mid-fanout doesn't
+	* leak.
+	*/
+	async triggerBackup(input) {
+		if (!this.systemBackup) throw new Error("orchestrator not initialized");
+		const targets = await this.resolveTargets(input?.destinations);
+		if (targets.length === 0) {
+			this.ctx.logger.warn("backup trigger: no destinations selected");
+			return [];
+		}
+		const policies = await this.loadPoliciesIndexed(targets.map((t) => t.id));
+		const archiveId = randomUUID();
+		const archiveFilename = `${archiveId}.tar.gz`;
+		const cacheRelativePath = `${archiveId}.tar.gz`;
+		const cachePath = await this.ctx.api.storage.resolve.query({
+			location: "cache",
+			relativePath: cacheRelativePath
+		});
+		const result = await this.systemBackup.createArchive({
+			archivePath: cachePath,
+			...input?.locations ? { locations: input.locations } : {}
+		});
+		try {
+			const entries = [];
+			const createdAt = Date.now();
+			for (const dest of targets) try {
+				const policy = policies.get(dest.id) ?? this.fallbackPolicy(dest.id);
+				const stored = await this.uploadAndIndex({
+					locationId: dest.id,
+					archiveId,
+					archiveFilename,
+					cachePath,
+					sizeBytes: result.sizeBytes,
+					archiveManifest: result.manifest,
+					retentionCount: policy.retentionCount,
+					createdAt,
+					label: formatArchiveLabel(dest.id, createdAt, input?.label)
+				});
+				entries.push(stored);
+				this.ctx.eventBus.emit({
+					id: randomUUID(),
+					timestamp: /* @__PURE__ */ new Date(),
+					source: {
+						type: "addon",
+						id: "backup-orchestrator"
+					},
+					category: EventCategory.BackupCompleted,
+					data: {
+						destinationId: dest.id,
+						backupId: stored.id,
+						sizeMB: Math.round((stored.sizeBytes ?? 0) / (1024 * 1024))
+					}
+				});
+			} catch (err) {
+				this.ctx.logger.error("backup trigger: destination failed", { meta: {
+					destinationId: dest.id,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			}
+			return entries;
+		} finally {
+			try {
+				await fsp.rm(cachePath, { force: true });
+			} catch {}
+		}
+	}
+	/**
+	* Push the staged archive to a single destination via chunked
+	* upload, then update the per-location manifest. Applies the
+	* destination's retention policy as part of the same lock-protected
+	* manifest mutation so the deletes never race with a concurrent
+	* append.
+	*
+	* Throws on upload / manifest failure — caller logs and continues to
+	* the next destination so a single bad sink doesn't fail the run.
+	*/
+	async uploadAndIndex(input) {
+		const { uploadId } = await this.ctx.api.storage.beginUpload.mutate({
+			location: input.locationId,
+			relativePath: input.archiveFilename,
+			sizeBytes: input.sizeBytes
+		});
+		try {
+			let offset = 0;
+			const stream = fs.createReadStream(input.cachePath, { highWaterMark: UPLOAD_CHUNK_BYTES });
+			for await (const rawChunk of stream) {
+				const chunk = toBufferChunk(rawChunk);
+				const data = new Uint8Array(chunk.byteLength);
+				data.set(chunk);
+				await this.ctx.api.storage.writeChunk.mutate({
+					uploadId,
+					offset,
+					data
+				});
+				offset += data.byteLength;
+			}
+			await this.ctx.api.storage.finalizeUpload.mutate({ uploadId });
+		} catch (err) {
+			try {
+				await this.ctx.api.storage.abortUpload.mutate({ uploadId });
+			} catch {}
+			throw err;
+		}
+		const entry = buildArchiveEntry({
+			id: input.archiveId,
+			filename: input.archiveFilename,
+			createdAt: input.createdAt,
+			sizeBytes: input.sizeBytes,
+			label: input.label,
+			manifest: input.archiveManifest
+		});
+		await this.manifestLock.run(input.locationId, async () => {
+			const { keep, drop } = applyRetention([...(await readLocationManifest(this.storageApi(), input.locationId)).archives, entry], input.retentionCount);
+			for (const stale of drop) try {
+				await this.ctx.api.storage.delete.mutate({
+					location: input.locationId,
+					relativePath: stale.filename
+				});
+			} catch (err) {
+				this.ctx.logger.warn("backup retention: storage delete failed (continuing)", { meta: {
+					destinationId: input.locationId,
+					backupId: stale.id,
+					filename: stale.filename,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			}
+			const next = {
+				version: 1,
+				archives: keep
+			};
+			await writeLocationManifest(this.storageApi(), input.locationId, next);
+		});
+		return {
+			id: input.archiveId,
+			destinationId: input.locationId,
+			createdAt: input.createdAt,
+			sizeBytes: input.sizeBytes,
+			label: input.label,
+			locations: [...input.archiveManifest.locations]
+		};
+	}
+	/**
+	* List archives at a single destination — newest-first. Reads only
+	* the per-location `manifests.json` (no per-archive tarball read);
+	* the orchestrator already snapshots each archive's locations into
+	* the manifest at upload time.
+	*/
+	async listArchives(input) {
+		let manifest;
+		try {
+			manifest = await readLocationManifest(this.storageApi(), input.destinationId);
+		} catch (err) {
+			this.ctx.logger.warn("backup listArchives: manifest read failed", { meta: {
+				destinationId: input.destinationId,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+			return [];
+		}
+		return [...manifest.archives].toSorted((a, b) => b.createdAt - a.createdAt).map((a) => ({
+			id: a.id,
+			filename: a.filename,
+			createdAt: a.createdAt,
+			sizeBytes: a.sizeBytes,
+			...a.label !== void 0 ? { label: a.label } : {},
+			locations: [...a.manifest.locations]
+		}));
+	}
+	/**
+	* Upsert the per-destination policy row. Used by the admin-UI
+	* destinations table — toggle enabled / change retention / set
+	* label / set cron schedule. No-ops with a logged warning if the
+	* settings backend lacks structured-table support (no persistence
+	* available).
+	*
+	* Validates `cron` server-side: a malformed expression rejects the
+	* upsert with an actionable error so the operator sees the problem
+	* at save time instead of at scheduler-tick time. Empty / undefined
+	* `cron` clears any prior schedule (manual-only).
+	*/
+	async upsertDestinationPolicy(input) {
+		if (!this.policies) {
+			this.ctx.logger.warn("backup upsertDestinationPolicy: no settings-store backend — change will not persist", { meta: { locationId: input.locationId } });
+			return;
+		}
+		const cron = typeof input.cron === "string" ? input.cron.trim() : "";
+		if (cron.length > 0 && !isValidCron(cron)) throw new Error(`Invalid cron expression: "${cron}"`);
+		const existing = await this.policies.get(input.locationId).catch(() => null);
+		await this.policies.upsert({
+			locationId: input.locationId,
+			enabled: input.enabled,
+			retentionCount: input.retentionCount,
+			...input.label !== void 0 ? { label: input.label } : {},
+			...cron.length > 0 ? { cron } : {},
+			...existing?.lastRunAt !== void 0 ? { lastRunAt: existing.lastRunAt } : {}
+		});
+	}
+	/**
+	* Validate a cron expression and peek the next N firing times. The
+	* admin UI's CronEditor calls this on every keystroke (debounced)
+	* to render a live "next-run" preview — invalid expressions surface
+	* the parse error inline instead of waiting for save.
+	*/
+	async previewSchedule(input) {
+		const trimmed = input.cron.trim();
+		if (trimmed.length === 0) return {
+			ok: false,
+			error: "Cron expression is empty",
+			nextRuns: []
+		};
+		try {
+			return {
+				ok: true,
+				nextRuns: previewNextRuns(trimmed, input.count ?? 5)
+			};
+		} catch (err) {
+			return {
+				ok: false,
+				error: err instanceof Error ? err.message : "Invalid cron expression",
+				nextRuns: []
+			};
+		}
+	}
+	async getEntries(input) {
+		try {
+			return (await readLocationManifest(this.storageApi(), input.destinationId)).archives.find((a) => a.id === input.backupId)?.manifest ?? null;
+		} catch (err) {
+			this.ctx.logger.warn("backup getEntries: manifest read failed", { meta: {
+				destinationId: input.destinationId,
+				backupId: input.backupId,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+			return null;
+		}
+	}
+	async deleteArchive(input) {
+		await this.manifestLock.run(input.destinationId, async () => {
+			const manifest = await readLocationManifest(this.storageApi(), input.destinationId);
+			const target = manifest.archives.find((a) => a.id === input.backupId);
+			if (!target) throw new Error(`backup delete: backup "${input.backupId}" not found at "${input.destinationId}"`);
+			try {
+				await this.ctx.api.storage.delete.mutate({
+					location: input.destinationId,
+					relativePath: target.filename
+				});
+			} catch (err) {
+				this.ctx.logger.warn("backup delete: storage delete failed (continuing manifest cleanup)", { meta: {
+					destinationId: input.destinationId,
+					filename: target.filename,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			}
+			const next = {
+				version: 1,
+				archives: manifest.archives.filter((a) => a.id !== input.backupId)
+			};
+			await writeLocationManifest(this.storageApi(), input.destinationId, next);
+		});
+	}
+	/**
+	* Schedule a restore for the next boot. Pulls the archive bytes
+	* down from the destination's storage location via the chunked-
+	* download protocol into the `cache` location, then writes the
+	* usual restore marker against the cached path so the boot-time
+	* apply hook (in server-backend launcher) extracts before any
+	* addon starts.
+	*
+	* `locations` (optional) is propagated into the marker as a
+	* whitelist — only those top-level locations get extracted.
+	*/
+	async scheduleRestore(input) {
+		if (!this.systemBackup) throw new Error("orchestrator not initialized");
+		const entry = (await readLocationManifest(this.storageApi(), input.destinationId)).archives.find((a) => a.id === input.backupId);
+		if (!entry) throw new Error(`backup restore: backup "${input.backupId}" not found at location "${input.destinationId}"`);
+		const cachePath = await this.ctx.api.storage.resolve.query({
+			location: "cache",
+			relativePath: `restore-${input.backupId}.tar.gz`
+		});
+		await downloadArchiveToCache({
+			api: this.ctx.api.storage,
+			locationId: input.destinationId,
+			filename: entry.filename,
+			cachePath,
+			chunkBytes: UPLOAD_CHUNK_BYTES,
+			logger: this.ctx.logger
+		});
+		this.systemBackup.scheduleRestoreMarker({
+			archivePath: cachePath,
+			source: input.backupId,
+			...input.locations ? { locations: input.locations } : {}
+		});
+		this.ctx.eventBus.emit({
+			id: randomUUID(),
+			timestamp: /* @__PURE__ */ new Date(),
+			source: {
+				type: "addon",
+				id: "backup-orchestrator"
+			},
+			category: EventCategory.BackupRestored,
+			data: {
+				backupId: input.backupId,
+				destinationId: input.destinationId
+			}
+		});
+	}
+	/**
+	* Resolve a target destination set: caller-provided list wins;
+	* otherwise fall back to every destination flagged as enabled in
+	* its policy row (`triggerSupported !== false` after the policy
+	* join). The old "global enabledDestinations override" was retired
+	* along with the orchestrator settings panel — per-destination
+	* `enabled` toggles in the destinations table are now the only
+	* routing knob.
+	*/
+	async resolveTargets(requested) {
+		const all = await this.listDestinations();
+		if (requested && requested.length > 0) return all.filter((d) => requested.includes(d.id));
+		return all.filter((d) => d.triggerSupported !== false);
+	}
+	startScheduleTimer() {
+		if (this.scheduleTimer) return;
+		this.scheduleTimer = setInterval(() => {
+			this.onScheduleTick();
+		}, SCHEDULE_TICK_MS);
+	}
+	stopScheduleTimer() {
+		if (!this.scheduleTimer) return;
+		clearInterval(this.scheduleTimer);
+		this.scheduleTimer = null;
+	}
+	/**
+	* Per-destination cron-based scheduling. Walks every enabled
+	* destination policy that carries a `cron` expression, computes the
+	* next due time after `lastRunAt` (or the orchestrator's first-tick
+	* baseline if never run), and fires a backup targeting that single
+	* destination when due. Each destination keeps its own cadence —
+	* an offsite SFTP can run weekly while local stays nightly without
+	* any global setting.
+	*
+	* Errors per destination are isolated; one misconfigured cron
+	* doesn't block the others. The policy's `lastRunAt` is updated
+	* BEFORE the trigger to dedupe (the tick runs every
+	* SCHEDULE_TICK_MS — without the up-front update a long-running
+	* upload could overlap with the next tick's same-due check).
+	*/
+	async onScheduleTick() {
+		if (!this.policies) return;
+		const policies = await this.policies.list();
+		const now = Date.now();
+		for (const p of policies) {
+			if (!p.enabled || !p.cron || p.cron.trim().length === 0) continue;
+			let due;
+			try {
+				due = computeNextDue(p.cron, p.lastRunAt ?? this.scheduleBaselineAt);
+			} catch (err) {
+				this.ctx.logger.warn("Invalid cron — skipping destination", { meta: {
+					locationId: p.locationId,
+					cron: p.cron,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+				continue;
+			}
+			if (due === null || due > now) continue;
+			const stamped = {
+				...p,
+				lastRunAt: now
+			};
+			try {
+				await this.policies.upsert(stamped);
+			} catch (err) {
+				this.ctx.logger.warn("Failed to persist scheduled-run timestamp", { meta: {
+					locationId: p.locationId,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			}
+			try {
+				this.ctx.logger.info("Scheduled backup firing for destination", { meta: {
+					locationId: p.locationId,
+					cron: p.cron,
+					dueAt: due
+				} });
+				await this.triggerBackup({ destinations: [p.locationId] });
+			} catch (err) {
+				this.ctx.logger.error("Scheduled backup failed", { meta: {
+					locationId: p.locationId,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			}
+		}
+	}
+	resolvePolicyService() {
+		const reg = this.ctx.kernel.capabilityRegistry;
+		if (!reg) return null;
+		const backend = reg.getSingleton("settings-store");
+		if (!backend) {
+			this.ctx.logger.warn("backup-orchestrator: no settings-store provider — destination policies will not persist");
+			return null;
+		}
+		if (!backend.ensureTable || !backend.tableInsert) {
+			this.ctx.logger.warn("backup-orchestrator: settings backend lacks structured-table support — destination policies will not persist");
+			return null;
+		}
+		return new BackupDestinationPolicyService(backend);
+	}
+	/**
+	* Narrow `ctx.api.storage` to the subset the manifest helpers need.
+	* Lets the helpers be unit-tested with a Map-backed fake without
+	* pulling in the full `AddonApi` shape.
+	*/
+	storageApi() {
+		return this.ctx.api.storage;
+	}
+};
+/**
+* Map a `storage-provider` providerId to an operator-friendly `kind`
+* the admin UI uses for destination cards. Falls back to the raw
+* provider id so unknown providers still surface (operator sees
+* `webdav-storage` instead of a blank slot).
+*/
+function kindFromProviderId(providerId) {
+	switch (providerId) {
+		case "filesystem-storage": return "local";
+		case "s3-storage": return "s3";
+		case "sftp-storage": return "sftp";
+		case "webdav-storage": return "webdav";
+		default: return providerId;
+	}
+}
+/**
+* Extract the slug part of a `<type>:<slug>` storage-location id.
+* Defensive: if the id doesn't contain a colon (shouldn't happen given
+* the regex on `StorageLocationSchema.id`) we return the whole string.
+*/
+function extractSlug(id) {
+	const colon = id.indexOf(":");
+	return colon < 0 ? id : id.slice(colon + 1);
+}
+/**
+* Narrow a `for await` chunk from `fs.createReadStream` to a
+* `Buffer`. The stream yields `string | Buffer` per its public type
+* even though the no-encoding overload always emits `Buffer`. The
+* runtime check + clear error keeps eslint's no-unsafe-* rules happy
+* without resorting to `as Buffer`.
+*/
+function toBufferChunk(value) {
+	if (Buffer.isBuffer(value)) return value;
+	if (value instanceof Uint8Array) return value;
+	throw new Error("backup upload: unexpected non-binary chunk from read stream");
+}
+/**
+* Return the most-recent archive in a location manifest, or undefined
+* when the location has no archives yet. Pure transform — no I/O.
+*/
+function latestArchiveOf(manifest) {
+	if (manifest.archives.length === 0) return void 0;
+	let newest = manifest.archives[0];
+	for (const a of manifest.archives) if (a.createdAt > newest.createdAt) newest = a;
+	return newest;
+}
+/**
+* Tiny `path.dirname`-equivalent that only depends on `/` and `\`.
+* Avoids a `node:path` import in this module purely so the
+* destination-policy.ts and manifest-store.ts neighbours stay node-
+* builtin-free at the import surface.
+*/
+function parentDir(p) {
+	const sep = p.includes("/") ? "/" : "\\";
+	const i = p.lastIndexOf(sep);
+	return i <= 0 ? "" : p.slice(0, i);
+}
+//#endregion
+export { BackupOrchestratorAddon, BackupOrchestratorAddon as default };