@ucdjs/ucd-store 0.0.1 → 1.0.1-beta.2

package/dist/index.mjs

@@ -0,0 +1,1356 @@
+import { a as isUCDStoreInternalContext, c as UCDStoreBridgeUnsupportedOperation, d as UCDStoreGenericError, f as UCDStoreVersionNotFoundError, i as extractFilterPatterns, l as UCDStoreFileNotFoundError, n as createInternalContext, o as UCDStoreApiFallbackError, r as createPublicContext, s as UCDStoreBaseError, u as UCDStoreFilterError } from "./context-DfX5D4Fb.mjs";
+import { UCDJS_API_BASE_URL, UCDJS_STORE_BASE_URL } from "@ucdjs/env";
+import { patheBasename, patheDirname, patheJoin, patheResolve } from "@ucdjs/path-utils";
+import { createConcurrencyLimiter, createDebugger, createPathFilter, discoverEndpointsFromConfig, filterTreeStructure, flattenFilePaths, getDefaultUCDEndpointConfig, normalizeTreeForFiltering, tryOr, wrapTry } from "@ucdjs-internal/shared";
+import { createUCDClientWithConfig } from "@ucdjs/client";
+import { computeFileHash, computeFileHashWithoutUCDHeader, getLockfilePath, readLockfile, readLockfileOrUndefined, readSnapshotOrUndefined, writeLockfile, writeSnapshot } from "@ucdjs/lockfile";
+import defu from "defu";
+import { hasUCDFolderPath } from "@unicode-utils/core";
+import { prependLeadingSlash } from "@luxass/utils";
+import { assertCapability, hasCapability } from "@ucdjs/fs-bridge";
+
+//#region src/files/get.ts
+const debug$10 = createDebugger("ucdjs:ucd-store:files:get");
+/**
+* Retrieves a specific file for a Unicode version from the local store.
+* By default, only reads files that are actually present in the store.
+* Optionally caches the file to local FS after fetching from API (if allowApi is enabled).
+*
+* @this {InternalUCDStoreContext} - Internal store context with client, filters, FS bridge, and configuration
+* @param {string} version - The Unicode version containing the file
+* @param {string} filePath - The path to the file within the version
+* @param {GetFileOptions} [options] - Optional filters, cache behavior, and API fallback
+* @returns {Promise<OperationResult<string, StoreError>>} Operation result with file content or error
+*/
+async function _getFile(version, filePath, options) {
+	return wrapTry(async () => {
+		if (!this.versions.resolved.includes(version)) throw new UCDStoreVersionNotFoundError(version);
+		if (!this.filter(filePath, options?.filters)) {
+			debug$10?.("File '%s' does not pass filters", filePath);
+			throw new UCDStoreFilterError(`File '${filePath}' does not pass filters`, {
+				excludePattern: options?.filters?.exclude || [],
+				includePattern: options?.filters?.include || [],
+				filePath
+			});
+		}
+		const localPath = patheJoin(version, filePath);
+		debug$10?.("Checking local file existence:", localPath);
+		if (await this.fs.exists(localPath)) {
+			debug$10?.("Local file exists:", localPath);
+			const content = await tryOr({
+				try: this.fs.read(localPath),
+				err: (err) => {
+					debug$10?.("Failed to read local file:", localPath, err);
+					if (!options?.allowApi) throw new UCDStoreGenericError(`Failed to read file '${filePath}' from local store`, {
+						version,
+						filePath
+					});
+				}
+			});
+			if (content != null) {
+				debug$10?.("Returning local file content:", localPath);
+				return content;
+			}
+		}
+		if (!options?.allowApi) throw new UCDStoreGenericError(`File '${filePath}' does not exist in local store`, {
+			version,
+			filePath
+		});
+		debug$10?.("Fetching file from API:", filePath);
+		const remotePath = patheJoin(version, hasUCDFolderPath(version) ? "ucd" : "", filePath);
+		const result = await this.client.files.get(remotePath);
+		if (result.error) throw new UCDStoreApiFallbackError({
+			version,
+			filePath,
+			status: result.error.status,
+			reason: "fetch-failed",
+			message: `Failed to fetch file '${filePath}': ${result.error.message}`
+		});
+		if (result.data == null) throw new UCDStoreApiFallbackError({
+			version,
+			filePath,
+			reason: "no-data"
+		});
+		let content;
+		if (typeof result.data === "string") content = result.data;
+		else content = JSON.stringify(result.data);
+		return content;
+	});
+}
+function getFile(thisOrContext, versionOrPath, pathOrOptions, options) {
+	if (isUCDStoreInternalContext(thisOrContext)) return _getFile.call(thisOrContext, versionOrPath, pathOrOptions, options);
+	return _getFile.call(this, thisOrContext, versionOrPath, pathOrOptions);
+}
+
+//#endregion
+//#region src/files/list.ts
+const debug$9 = createDebugger("ucdjs:ucd-store:files:list");
+/**
+* Build a lookup of normalized paths to original paths.
+* This allows us to filter using normalized paths but return original paths.
+*/
+function buildPathMapping(version, originalEntries, normalizedEntries) {
+	const originalPaths = flattenFilePaths(originalEntries);
+	const normalizedPaths = flattenFilePaths(normalizedEntries);
+	const mapping = /* @__PURE__ */ new Map();
+	for (let i = 0; i < normalizedPaths.length; i++) {
+		const normalizedPath = normalizedPaths[i];
+		const originalPath = originalPaths[i];
+		if (normalizedPath && originalPath) mapping.set(normalizedPath, originalPath);
+	}
+	return mapping;
+}
+/**
+* Lists all file paths for a Unicode version. The operation prefers the
+* configured file system bridge and can optionally fall back to the API when
+* the bridge path is missing or cannot be read.
+*
+* Returns full paths (e.g., "/16.0.0/UnicodeData.txt"), not just filenames.
+*
+* @this {InternalUCDStoreContext} - Internal store context
+* @param version Unicode version to list files for
+* @param options Optional filters and `allowApi` fallback behavior
+* @returns Operation result containing full file paths or an error
+*/
+async function _listFiles(version, options) {
+	return wrapTry(async () => {
+		if (!this.versions.resolved.includes(version)) throw new UCDStoreVersionNotFoundError(version);
+		const filesPath = version;
+		debug$9?.("Using files path:", filesPath, "for version:", version);
+		if (await this.fs.exists(filesPath)) try {
+			const entries = await this.fs.listdir(filesPath, true);
+			debug$9?.("Listed entries from store for version:", version);
+			const normalizedEntries = normalizeTreeForFiltering(version, entries);
+			const pathMapping = buildPathMapping(version, entries, normalizedEntries);
+			const originalPaths = flattenFilePaths(filterTreeStructure(this.filter, normalizedEntries, options?.filters)).map((normalizedPath) => {
+				const original = pathMapping.get(normalizedPath);
+				if (!original) return `/${version}/${normalizedPath.replace(/^\/+/, "")}`;
+				return original;
+			});
+			debug$9?.("Listed %d files from store for version: %s", originalPaths.length, version);
+			return originalPaths;
+		} catch (err) {
+			debug$9?.("Failed to list directory:", filesPath, err);
+			if (!options?.allowApi) return [];
+		}
+		if (!options?.allowApi) {
+			debug$9?.("Directory does not exist and allowApi is false:", filesPath);
+			return [];
+		}
+		debug$9?.("Fetching file tree from API for version:", version);
+		const result = await this.client.versions.getFileTree(version);
+		if (result.error) throw new UCDStoreApiFallbackError({
+			version,
+			filePath: "file-tree",
+			reason: "fetch-failed",
+			status: result.error.status
+		});
+		if (result.data == null) throw new UCDStoreApiFallbackError({
+			version,
+			filePath: "file-tree",
+			reason: "no-data"
+		});
+		const normalizedTree = normalizeTreeForFiltering(version, result.data);
+		const pathMapping = buildPathMapping(version, result.data, normalizedTree);
+		return flattenFilePaths(filterTreeStructure(this.filter, normalizedTree, options?.filters)).map((normalizedPath) => {
+			const original = pathMapping.get(normalizedPath);
+			if (!original) return `/${version}/${normalizedPath.replace(/^\/+/, "")}`;
+			return original;
+		});
+	});
+}
+function listFiles(thisOrContext, versionOrOptions, options) {
+	if (isUCDStoreInternalContext(thisOrContext)) return _listFiles.call(thisOrContext, versionOrOptions, options);
+	return _listFiles.call(this, thisOrContext, versionOrOptions);
+}
+
+//#endregion
+//#region src/files/tree.ts
+const debug$8 = createDebugger("ucdjs:ucd-store:files:tree");
+/**
+* Converts FSEntry array to UnicodeFileTreeNode array by adding lastModified field.
+*/
+function fsEntryToFileTreeNode(entries) {
+	return entries.map((entry) => {
+		if (entry.type === "directory") return {
+			type: "directory",
+			name: entry.name,
+			path: entry.path,
+			lastModified: null,
+			children: fsEntryToFileTreeNode(entry.children)
+		};
+		return {
+			type: "file",
+			name: entry.name,
+			path: entry.path,
+			lastModified: null
+		};
+	});
+}
+/**
+* Retrieves the file tree for a specific Unicode version from the local store.
+* By default, only returns the tree structure for files actually present in the store.
+* Applies global filters and optional method-specific filters to the tree.
+*
+* @this {InternalUCDStoreContext} - Internal store context with client, filters, FS bridge, and configuration
+* @param {string} version - The Unicode version to fetch the file tree for
+* @param {GetFileTreeOptions} [options] - Optional filters and API fallback behavior
+* @returns {Promise<OperationResult<UnicodeFileTreeNode[], StoreError>>} Operation result with filtered file tree or error
+*/
+async function _getFileTree(version, options) {
+	return wrapTry(async () => {
+		if (!this.versions.resolved.includes(version)) throw new UCDStoreVersionNotFoundError(version);
+		const localPath = version;
+		if (await this.fs.exists(localPath)) try {
+			const normalizedEntries = normalizeTreeForFiltering(version, fsEntryToFileTreeNode(await this.fs.listdir(localPath, true)));
+			return filterTreeStructure(this.filter, normalizedEntries, {
+				exclude: options?.filters?.exclude,
+				include: options?.filters?.include
+			});
+		} catch (err) {
+			debug$8?.("Failed to list local directory:", localPath, err);
+			if (!options?.allowApi) return [];
+		}
+		if (!options?.allowApi) {
+			debug$8?.("Directory does not exist locally and allowApi is false:", localPath);
+			return [];
+		}
+		debug$8?.("Fetching file tree from API for version:", version);
+		const result = await this.client.versions.getFileTree(version);
+		if (result.error) throw new UCDStoreApiFallbackError({
+			version,
+			filePath: "file-tree",
+			reason: "fetch-failed",
+			status: result.error.status
+		});
+		if (result.data == null) throw new UCDStoreApiFallbackError({
+			version,
+			filePath: "file-tree",
+			reason: "no-data"
+		});
+		const normalizedTree = normalizeTreeForFiltering(version, result.data);
+		return filterTreeStructure(this.filter, normalizedTree, {
+			exclude: options?.filters?.exclude,
+			include: options?.filters?.include
+		});
+	});
+}
+function getFileTree(thisOrContext, versionOrOptions, options) {
+	if (isUCDStoreInternalContext(thisOrContext)) return _getFileTree.call(thisOrContext, versionOrOptions, options);
+	return _getFileTree.call(this, thisOrContext, versionOrOptions);
+}
+
+//#endregion
+//#region src/utils/reports.ts
+function createEmptyFileCounts() {
+	return {
+		total: 0,
+		success: 0,
+		skipped: 0,
+		failed: 0
+	};
+}
+function createEmptyOperationMetrics() {
+	return {
+		successRate: 0,
+		cacheHitRate: 0,
+		failureRate: 0,
+		averageTimePerFile: 0
+	};
+}
+function createEmptyStorageMetrics() {
+	return {
+		totalSize: "0 B",
+		averageFileSize: "0 B"
+	};
+}
+function createEmptySummary(duration = 0) {
+	return {
+		duration,
+		counts: createEmptyFileCounts(),
+		metrics: createEmptyOperationMetrics(),
+		storage: createEmptyStorageMetrics()
+	};
+}
+function computeMetrics(counts, duration) {
+	const total = counts.total;
+	return {
+		successRate: total > 0 ? counts.success / total * 100 : 0,
+		cacheHitRate: total > 0 ? counts.skipped / total * 100 : 0,
+		failureRate: total > 0 ? counts.failed / total * 100 : 0,
+		averageTimePerFile: total > 0 ? duration / total : 0
+	};
+}
+function formatBytes(bytes) {
+	if (bytes === 0) return "0 B";
+	const sizes = [
+		"B",
+		"KB",
+		"MB",
+		"GB",
+		"TB"
+	];
+	const i = Math.floor(Math.log(bytes) / Math.log(1024));
+	const clampedI = Math.max(0, Math.min(i, sizes.length - 1));
+	return `${(bytes / 1024 ** clampedI).toFixed(2)} ${sizes[clampedI]}`;
+}
+function computeStorageMetrics(totalBytes, successCount) {
+	return {
+		totalSize: formatBytes(totalBytes),
+		averageFileSize: successCount > 0 ? formatBytes(totalBytes / successCount) : "0 B"
+	};
+}
+function aggregateFileCounts(versionReports) {
+	const counts = createEmptyFileCounts();
+	for (const report of versionReports.values()) {
+		counts.total += report.counts.total;
+		counts.success += report.counts.success;
+		counts.skipped += report.counts.skipped;
+		counts.failed += report.counts.failed;
+	}
+	return counts;
+}
+function createSummaryFromVersionReports(versionReports, duration, totalBytes) {
+	const counts = aggregateFileCounts(versionReports);
+	return {
+		duration,
+		counts,
+		metrics: computeMetrics(counts, duration),
+		storage: computeStorageMetrics(totalBytes, counts.success)
+	};
+}
+
+//#endregion
+//#region src/reports/analyze.ts
+const debug$7 = createDebugger("ucdjs:ucd-store:analyze");
+/**
+* Analyzes Unicode data in the store.
+*
+* @this {InternalUCDStoreContext} - Internal store context with client, filters, FS bridge, and configuration
+* @param {AnalyzeOptions} [options] - Analyze options
+* @returns {Promise<OperationResult<AnalysisReport, StoreError>>} Operation result
+*/
+async function _analyze(options) {
+	return wrapTry(async () => {
+		const startTime = Date.now();
+		const versionReports = /* @__PURE__ */ new Map();
+		const versionsToAnalyze = options?.versions ?? this.versions.resolved;
+		for (const version of versionsToAnalyze) {
+			if (!this.versions.resolved.includes(version)) continue;
+			const versionStartTime = Date.now();
+			const errors = [];
+			let expectedFiles = [];
+			try {
+				expectedFiles = await this.getExpectedFilePaths(version);
+				debug$7?.("Found expected files while analyzing: %O", expectedFiles.map((f) => f.storePath));
+			} catch (err) {
+				errors.push({
+					name: "expected-files",
+					filePath: prependLeadingSlash(version),
+					reason: err instanceof Error ? err.message : String(err)
+				});
+			}
+			let [actualFilePaths, listFilesError] = await listFiles(this, version, {
+				allowApi: false,
+				filters: options?.filters
+			});
+			if (listFilesError != null) {
+				errors.push({
+					name: "list-files",
+					filePath: prependLeadingSlash(version),
+					reason: listFilesError.message
+				});
+				actualFilePaths = [];
+			}
+			actualFilePaths = (actualFilePaths || []).filter((filePath) => !filePath.endsWith("snapshot.json"));
+			debug$7?.("Actual files while analyzing: %O", actualFilePaths);
+			const expectedStorePathsSet = new Set(expectedFiles.map((f) => f.storePath));
+			const actualFilePathsSet = new Set(actualFilePaths);
+			const expectedFilesByStorePath = new Map(expectedFiles.map((f) => [f.storePath, f]));
+			const presentFiles = [];
+			const orphanedFiles = [];
+			const missingFiles = [];
+			const fileTypes = {};
+			debug$7?.("Started analyzing files");
+			for (const actualFile of actualFilePathsSet) {
+				const ext = getExtension(actualFile);
+				fileTypes[ext] ??= 0;
+				fileTypes[ext] += 1;
+				if (expectedStorePathsSet.has(actualFile)) {
+					const expectedFile = expectedFilesByStorePath.get(actualFile);
+					presentFiles.push({
+						name: expectedFile?.name || actualFile.split("/").pop() || actualFile,
+						filePath: actualFile
+					});
+				} else orphanedFiles.push({
+					name: actualFile.split("/").pop() || actualFile,
+					filePath: actualFile
+				});
+			}
+			for (const expectedFile of expectedFiles) if (!actualFilePathsSet.has(expectedFile.storePath)) missingFiles.push({
+				name: expectedFile.name,
+				filePath: expectedFile.storePath
+			});
+			debug$7?.("Finished analyzing files");
+			presentFiles.sort((a, b) => a.name.localeCompare(b.name));
+			orphanedFiles.sort((a, b) => a.name.localeCompare(b.name));
+			missingFiles.sort((a, b) => a.name.localeCompare(b.name));
+			const isComplete = orphanedFiles.length === 0 && missingFiles.length === 0 && errors.length === 0;
+			const counts = {
+				total: expectedFiles.length,
+				success: presentFiles.length,
+				skipped: orphanedFiles.length,
+				failed: missingFiles.length
+			};
+			const metrics = computeMetrics(counts, Date.now() - versionStartTime);
+			const versionReport = {
+				version,
+				isComplete,
+				files: {
+					present: presentFiles,
+					orphaned: orphanedFiles,
+					missing: missingFiles
+				},
+				counts,
+				metrics,
+				errors,
+				fileTypes
+			};
+			versionReports.set(version, versionReport);
+		}
+		const summary = createSummaryFromVersionReports(versionReports, Date.now() - startTime, 0);
+		return {
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			versions: versionReports,
+			summary
+		};
+	});
+}
+function analyze(thisOrContext, options) {
+	if (isUCDStoreInternalContext(thisOrContext)) return _analyze.call(thisOrContext, options);
+	return _analyze.call(this, thisOrContext);
+}
+function getExtension(filePath) {
+	const match = filePath.match(/\.[^/.]+$/);
+	return match ? match[0] : "no_extension";
+}
+
+//#endregion
+//#region src/reports/compare.ts
+const debug$6 = createDebugger("ucdjs:ucd-store:compare");
+/**
+* Resolves comparison mode into separate modes for from/to versions.
+*/
+function resolveModes(mode) {
+	if (!mode) return {
+		fromMode: "prefer-local",
+		toMode: "prefer-local"
+	};
+	if (Array.isArray(mode)) return {
+		fromMode: mode[0],
+		toMode: mode[1]
+	};
+	return {
+		fromMode: mode,
+		toMode: mode
+	};
+}
+/**
+* Converts a mode to the allowApi option for listFiles/getFile.
+* - "prefer-local": allowApi = true (try local first, fall back to API)
+* - "local": allowApi = false (only local)
+* - "api": allowApi = true (API-only, handled by forcing fetch from API)
+*/
+function modeToAllowApi(mode) {
+	return mode !== "local";
+}
+/**
+* Normalizes a file path by removing the version prefix.
+* Handles paths like "/16.0.0/UnicodeData.txt" or "16.0.0/UnicodeData.txt"
+*/
+function normalizeFilePath(filePath, version) {
+	const versionPrefix = `/${version}/`;
+	const versionPrefixNoSlash = `${version}/`;
+	if (filePath.startsWith(versionPrefix)) return filePath.slice(versionPrefix.length);
+	if (filePath.startsWith(versionPrefixNoSlash)) return filePath.slice(versionPrefixNoSlash.length);
+	return filePath.replace(/^\/+/, "");
+}
+/**
+* Compares two versions in the store and returns a report describing added/removed/modified/unchanged files.
+*
+* The comparison uses content hashes (SHA-256 with Unicode header stripped) to determine
+* if files have actually changed content, not just metadata like version numbers in headers.
+*
+* @this {InternalUCDStoreContext} - Internal store context with client, filters, FS bridge, and configuration
+* @param {CompareOptions} options - Compare options with from/to versions
+* @returns {Promise<OperationResult<VersionComparison, StoreError>>} Operation result with comparison report
+*/
+async function _compare(options) {
+	return wrapTry(async () => {
+		if (!options) throw new UCDStoreGenericError("Options with `from` and `to` versions are required");
+		const { from, to } = options;
+		if (!from || !to) throw new UCDStoreGenericError("Both `from` and `to` versions must be specified");
+		if (!this.versions.resolved.includes(from)) throw new UCDStoreVersionNotFoundError(from);
+		if (!this.versions.resolved.includes(to)) throw new UCDStoreVersionNotFoundError(to);
+		const { fromMode, toMode } = resolveModes(options.mode);
+		const includeHashes = options.includeFileHashes !== false;
+		const concurrency = options.concurrency ?? 5;
+		debug$6?.("Comparing %s -> %s (modes: %s, %s, includeHashes: %s)", from, to, fromMode, toMode, includeHashes);
+		const [fromFilesRaw, fromError] = await listFiles(this, from, {
+			allowApi: modeToAllowApi(fromMode),
+			filters: options.filters
+		});
+		if (fromError) throw fromError;
+		const [toFilesRaw, toError] = await listFiles(this, to, {
+			allowApi: modeToAllowApi(toMode),
+			filters: options.filters
+		});
+		if (toError) throw toError;
+		const fromFiles = (fromFilesRaw || []).map((p) => normalizeFilePath(p, from)).filter((p) => p !== "snapshot.json");
+		const toFiles = (toFilesRaw || []).map((p) => normalizeFilePath(p, to)).filter((p) => p !== "snapshot.json");
+		debug$6?.("From version %s has %d files, to version %s has %d files", from, fromFiles.length, to, toFiles.length);
+		const fromSet = new Set(fromFiles);
+		const toSet = new Set(toFiles);
+		const added = toFiles.filter((p) => !fromSet.has(p)).sort();
+		const removed = fromFiles.filter((p) => !toSet.has(p)).sort();
+		const common = fromFiles.filter((p) => toSet.has(p)).sort();
+		debug$6?.("Added: %d, Removed: %d, Common: %d", added.length, removed.length, common.length);
+		const modified = [];
+		const changes = [];
+		let unchangedCount = 0;
+		if (includeHashes && common.length > 0) {
+			const limit = createConcurrencyLimiter(concurrency);
+			await Promise.all(common.map((file) => limit(async () => {
+				const [fromContent, fromFileError] = await getFile(this, from, file, { allowApi: modeToAllowApi(fromMode) });
+				if (fromFileError) {
+					debug$6?.("Failed to get file %s from version %s: %s", file, from, fromFileError.message);
+					throw fromFileError;
+				}
+				const [toContent, toFileError] = await getFile(this, to, file, { allowApi: modeToAllowApi(toMode) });
+				if (toFileError) {
+					debug$6?.("Failed to get file %s from version %s: %s", file, to, toFileError.message);
+					throw toFileError;
+				}
+				const fromHash = await computeFileHashWithoutUCDHeader(fromContent);
+				const toHash = await computeFileHashWithoutUCDHeader(toContent);
+				const fromSize = new TextEncoder().encode(fromContent).length;
+				const toSize = new TextEncoder().encode(toContent).length;
+				if (fromHash !== toHash) {
+					modified.push(file);
+					changes.push({
+						file,
+						changeType: "content-changed",
+						from: {
+							size: fromSize,
+							hash: fromHash
+						},
+						to: {
+							size: toSize,
+							hash: toHash
+						}
+					});
+					debug$6?.("File %s modified: %s -> %s (sizes: %d -> %d)", file, fromHash.slice(0, 16), toHash.slice(0, 16), fromSize, toSize);
+				} else unchangedCount++;
+			})));
+		} else unchangedCount = common.length;
+		const result = {
+			from,
+			to,
+			added: Object.freeze(added),
+			removed: Object.freeze(removed),
+			modified: Object.freeze(modified.sort()),
+			unchanged: unchangedCount,
+			changes: Object.freeze(changes.sort((a, b) => a.file.localeCompare(b.file)))
+		};
+		debug$6?.("Comparison complete: %d added, %d removed, %d modified, %d unchanged", result.added.length, result.removed.length, result.modified.length, result.unchanged);
+		return result;
+	});
+}
+function compare(thisOrContext, options) {
+	if (isUCDStoreInternalContext(thisOrContext)) return _compare.call(thisOrContext, options);
+	return _compare.call(this, thisOrContext);
+}
+
+//#endregion
+//#region src/tasks/mirror.ts
+const debug$5 = createDebugger("ucdjs:ucd-store:mirror");
+/**
+* Helper to create a ReportFile from file information.
+*/
+function createReportFile(name, filePath) {
+	return {
+		name,
+		filePath: `/${filePath}`
+	};
+}
+/**
+* Helper to create a version report with empty initial state.
+*/
+function createVersionReport(version) {
+	return {
+		version,
+		files: {
+			downloaded: [],
+			skipped: [],
+			failed: []
+		},
+		counts: {
+			total: 0,
+			success: 0,
+			skipped: 0,
+			failed: 0
+		},
+		metrics: {
+			successRate: 0,
+			cacheHitRate: 0,
+			failureRate: 0,
+			averageTimePerFile: 0
+		},
+		errors: []
+	};
+}
+/**
+* Updates a version report's counts and metrics based on its file lists.
+*/
+function finalizeVersionReport(report, duration) {
+	report.counts = {
+		total: report.files.downloaded.length + report.files.skipped.length + report.files.failed.length,
+		success: report.files.downloaded.length,
+		skipped: report.files.skipped.length,
+		failed: report.files.failed.length
+	};
+	report.metrics = computeMetrics(report.counts, duration);
+}
+/**
+* Mirrors Unicode data files from the API to local storage.
+* Downloads actual Unicode data files for specified versions.
+*
+* @this {InternalUCDStoreContext} - Internal store context with client, filters, FS bridge, and configuration
+* @param {MirrorOptions} [options] - Mirror options
+* @returns {Promise<OperationResult<MirrorReport, StoreError>>} Operation result
+*/
+async function _mirror(options) {
+	return wrapTry(async () => {
+		if (!hasCapability(this.fs, ["mkdir", "write"])) throw new UCDStoreGenericError("Filesystem does not support required write operations for mirroring.");
+		debug$5?.("Starting mirror operation with context: %O", this);
+		const versions = options?.versions ?? this.versions.resolved;
+		const concurrency = options?.concurrency ?? 5;
+		const force = options?.force ?? false;
+		if (versions.length === 0) {
+			debug$5?.("No versions to mirror");
+			return {
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				versions: /* @__PURE__ */ new Map(),
+				summary: createEmptySummary(0)
+			};
+		}
+		const startTime = Date.now();
+		const limit = createConcurrencyLimiter(concurrency);
+		debug$5?.(`Starting mirror for ${versions.length} version(s) with concurrency=${concurrency}`);
+		const versionedReports = /* @__PURE__ */ new Map();
+		for (const version of versions) versionedReports.set(version, createVersionReport(version));
+		const directoriesToCreate = /* @__PURE__ */ new Set();
+		const filesQueue = [];
+		for (const version of versions) {
+			debug$5?.(`Fetching file tree for version ${version}`);
+			const result = await this.client.versions.getFileTree(version);
+			debug$5?.(`Fetched file tree for version ${version}`);
+			if (result.error) throw new UCDStoreGenericError(`Failed to fetch file tree for version '${version}': ${result.error.message}`, {
+				version,
+				status: result.error.status
+			});
+			debug$5?.(`Processing file tree for version ${version}: %O`, result.data);
+			if (result.data == null) throw new UCDStoreGenericError(`Failed to fetch file tree for version '${version}': no data returned`, { version });
+			const normalizedTree = normalizeTreeForFiltering(version, result.data);
+			const filePaths = flattenFilePaths(filterTreeStructure(this.filter, normalizedTree, options?.filters));
+			debug$5?.(`Found ${filePaths.length} files for version ${version} after filtering`);
+			if (!versionedReports.has(version)) throw new UCDStoreGenericError(`Internal error: missing version report for ${version}`);
+			const versionResult = versionedReports.get(version);
+			for (const filePath of filePaths) {
+				const normalized = filePath.replace(/^\/+/, "");
+				const localPath = patheJoin(version, normalized);
+				const remotePath = patheJoin(version, hasUCDFolderPath(version) ? "ucd" : "", normalized);
+				directoriesToCreate.add(patheDirname(localPath));
+				debug$5?.(`Queueing file for mirroring: version=${version}, filePath=${filePath}, normalized=${normalized}, localPath=${localPath}, remotePath=${remotePath}`);
+				filesQueue.push({
+					name: normalized,
+					version,
+					filePath: normalized,
+					localPath,
+					remotePath,
+					versionResult
+				});
+			}
+		}
+		const totalFiles = filesQueue.length;
+		debug$5?.(`Total files to mirror: ${totalFiles}, directories to create: ${directoriesToCreate.size}`);
+		let totalDownloadedSize = 0;
+		await Promise.all([...directoriesToCreate].map(async (dir) => {
+			if (!await this.fs.exists(dir)) await this.fs.mkdir(dir);
+		}));
+		await Promise.all(filesQueue.map((item) => limit(async () => {
+			try {
+				if (!force && await this.fs.exists(item.localPath)) {
+					item.versionResult.files.skipped.push(createReportFile(item.name, item.localPath));
+					return;
+				}
+				debug$5?.(`Fetching file ${item.remotePath} from API`);
+				const { data, error, response } = await this.client.files.get(item.remotePath);
+				if (error) throw new UCDStoreGenericError(`Failed to fetch file '${item.filePath}': ${error.message}`);
+				if (!data) throw new UCDStoreGenericError(`Failed to fetch file '${item.filePath}': no data returned`);
+				const contentSize = +(response?.headers.get("content-length") ?? "0");
+				const contentType = response?.headers.get("content-type");
+				let content;
+				if (typeof data === "string") content = data;
+				else if (typeof data === "object" && !Array.isArray(data) && Object.prototype.toString.call(data) === "[object Object]" && contentType === "application/json") content = JSON.stringify(data);
+				else throw new UCDStoreGenericError(`Failed to mirror file '${item.filePath}': unsupported data type received`);
+				await this.fs.write(item.localPath, content);
+				item.versionResult.files.downloaded.push(createReportFile(item.name, item.localPath));
+				totalDownloadedSize += contentSize;
+			} catch (err) {
+				item.versionResult.files.failed.push(createReportFile(item.name, item.localPath));
+				item.versionResult.errors.push({
+					name: item.name,
+					filePath: prependLeadingSlash(item.localPath),
+					reason: err instanceof Error ? err.message : String(err)
+				});
+				debug$5?.(`Failed to mirror file ${item.remotePath} for version ${item.version}:`, err);
+			}
+		})));
+		const duration = Date.now() - startTime;
+		for (const report of versionedReports.values()) {
+			finalizeVersionReport(report, duration / versions.length);
+			report.files.downloaded.sort((a, b) => a.name.localeCompare(b.name));
+			report.files.skipped.sort((a, b) => a.name.localeCompare(b.name));
+			report.files.failed.sort((a, b) => a.name.localeCompare(b.name));
+		}
+		const lockfile = await readLockfileOrUndefined(this.fs, this.lockfile.path);
+		const updatedLockfileVersions = lockfile ? { ...lockfile.versions } : {};
+		const now = /* @__PURE__ */ new Date();
+		for (const [version, report] of versionedReports.entries()) {
+			const allFiles = [...report.files.downloaded, ...report.files.skipped];
+			debug$5?.(`Preparing snapshot for version ${version}, total files: ${allFiles.length}`);
+			debug$5?.(`Files: %O`, allFiles);
+			if (allFiles.length > 0) {
+				debug$5?.(`Creating snapshot for version ${version}`);
+				const snapshotFiles = {};
+				let totalSize = 0;
+				for (const localFile of allFiles) {
+					const normalizedPath = localFile.filePath.startsWith(`${version}/`) ? localFile.filePath.slice(version.length + 1) : localFile.filePath;
+					debug$5?.(`Processing file for snapshot: version=${version}, localPath=${localFile.filePath}, normalizedPath=${normalizedPath}`);
+					const fileContent = await this.fs.read(localFile.filePath);
+					if (fileContent) {
+						const hash = await computeFileHashWithoutUCDHeader(fileContent);
+						const fileHash = await computeFileHash(fileContent);
+						const size = new TextEncoder().encode(fileContent).length;
+						snapshotFiles[normalizedPath] = {
+							hash,
+							fileHash,
+							size
+						};
+						totalSize += size;
+					}
+				}
+				await writeSnapshot(this.fs, version, {
+					unicodeVersion: version,
+					files: snapshotFiles
+				});
+				const existingEntry = updatedLockfileVersions[version];
+				updatedLockfileVersions[version] = {
+					path: `${version}/snapshot.json`,
+					fileCount: allFiles.length,
+					totalSize,
+					createdAt: existingEntry?.createdAt ?? now,
+					updatedAt: now
+				};
+			}
+		}
+		if (Object.keys(updatedLockfileVersions).length > 0) {
+			const filters = extractFilterPatterns(this.filter) ?? lockfile?.filters;
+			await writeLockfile(this.fs, this.lockfile.path, {
+				lockfileVersion: 1,
+				createdAt: lockfile?.createdAt ?? now,
+				updatedAt: now,
+				versions: updatedLockfileVersions,
+				filters
+			});
+		}
+		const aggregatedCounts = {
+			total: 0,
+			success: 0,
+			skipped: 0,
+			failed: 0
+		};
+		for (const report of versionedReports.values()) {
+			aggregatedCounts.total += report.counts.total;
+			aggregatedCounts.success += report.counts.success;
+			aggregatedCounts.skipped += report.counts.skipped;
+			aggregatedCounts.failed += report.counts.failed;
+		}
+		const summary = {
+			duration,
+			counts: aggregatedCounts,
+			metrics: computeMetrics(aggregatedCounts, duration),
+			storage: computeStorageMetrics(totalDownloadedSize, aggregatedCounts.success)
+		};
+		debug$5?.(`Mirror completed: %d downloaded, %d skipped, %d failed in ${duration}ms`, summary.counts.success, summary.counts.skipped, summary.counts.failed);
+		return {
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			versions: versionedReports,
+			summary
+		};
+	});
+}
+function mirror(thisOrContext, options) {
+	if (isUCDStoreInternalContext(thisOrContext)) return _mirror.call(thisOrContext, options);
+	return _mirror.call(this, thisOrContext);
+}
+
+//#endregion
+//#region src/tasks/sync.ts
+const debug$4 = createDebugger("ucdjs:ucd-store:sync");
+/**
+* Synchronizes the store lockfile with available versions from API and mirrors files.
+* Updates lockfile, downloads missing files, and optionally removes orphaned files/unavailable versions.
+*
+* @this {InternalUCDStoreContext} - Internal store context
+* @param {SyncOptions} [options] - Sync options
+* @returns {Promise<OperationResult<SyncResult, StoreError>>} Operation result
+*/
+async function _sync(options) {
+	return wrapTry(async () => {
+		const startTime = Date.now();
+		if (!hasCapability(this.fs, ["mkdir", "write"])) throw new UCDStoreGenericError("Filesystem does not support required write operations for syncing.");
+		const concurrency = options?.concurrency ?? 5;
+		const force = options?.force ?? false;
+		const removeUnavailable = options?.removeUnavailable ?? false;
+		const cleanOrphaned = options?.cleanOrphaned ?? false;
+		debug$4?.("Fetching available versions from API");
+		const availableVersionsFromApi = await getVersionsFromApi(this);
+		debug$4?.(`Found ${availableVersionsFromApi.length} available versions from API`);
+		const lockfile = await readLockfileOrUndefined(this.fs, this.lockfile.path);
+		const currentVersions = new Set(lockfile ? Object.keys(lockfile.versions) : []);
+		const availableVersionsSet = new Set(availableVersionsFromApi);
+		const versionsToConsider = options?.versions && options.versions.length > 0 ? options.versions.filter((v) => availableVersionsSet.has(v)) : availableVersionsFromApi;
+		if (options?.versions && options.versions.length > 0) {
+			const invalidVersions = options.versions.filter((v) => !availableVersionsSet.has(v));
+			if (invalidVersions.length > 0) {
+				if (invalidVersions.length === 1) throw new UCDStoreVersionNotFoundError(invalidVersions[0]);
+				throw new UCDStoreGenericError(`Requested versions are not available in API: ${invalidVersions.join(", ")}`);
+			}
+		}
+		const added = versionsToConsider.filter((v) => !currentVersions.has(v));
+		const unchanged = Array.from(currentVersions).filter((v) => {
+			if (removeUnavailable && !availableVersionsSet.has(v)) return false;
+			if (!removeUnavailable) return true;
+			return availableVersionsSet.has(v);
+		});
+		let removed = [];
+		let finalVersions;
+		if (removeUnavailable) {
+			removed = Array.from(currentVersions).filter((v) => !availableVersionsSet.has(v));
+			if (options?.versions && options.versions.length > 0) finalVersions = [...new Set([...Array.from(currentVersions).filter((v) => availableVersionsSet.has(v)), ...versionsToConsider])];
+			else finalVersions = availableVersionsFromApi;
+		} else finalVersions = [...new Set([...currentVersions, ...added])];
+		debug$4?.(`Lockfile update: ${added.length} added, ${removed.length} removed, ${unchanged.length} unchanged`);
+		if (lockfile || added.length > 0 || removed.length > 0) {
+			const { extractFilterPatterns } = await import("./context-DfX5D4Fb.mjs").then((n) => n.t);
+			const filters = extractFilterPatterns(this.filter) ?? lockfile?.filters;
+			const now = /* @__PURE__ */ new Date();
+			await writeLockfile(this.fs, this.lockfile.path, {
+				lockfileVersion: 1,
+				createdAt: lockfile?.createdAt ?? now,
+				updatedAt: now,
+				versions: Object.fromEntries(finalVersions.map((v) => {
+					return [v, lockfile?.versions[v] ?? {
+						path: `${v}/snapshot.json`,
+						fileCount: 0,
+						totalSize: 0,
+						createdAt: now,
+						updatedAt: now
+					}];
+				})),
+				filters
+			});
+		}
+		let versionsToSync;
+		if (options?.versions) versionsToSync = options.versions;
+		else if (force) versionsToSync = finalVersions;
+		else versionsToSync = finalVersions.filter((v) => {
+			const entry = lockfile?.versions[v];
+			return !entry || entry.fileCount === 0;
+		});
+		debug$4?.(`Determining versions to sync: ${versionsToSync.join(", ")}`);
+		debug$4?.(`Validating versions to sync: ${versionsToSync.join(", ")}`);
+		const emptyMirrorReport = {
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			versions: /* @__PURE__ */ new Map(),
+			summary: createEmptySummary(0)
+		};
+		if (versionsToSync.length === 0) {
+			debug$4?.("No versions to sync", { versionsToSync });
+			const syncDuration = Date.now() - startTime;
+			return {
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				added,
+				removed,
+				unchanged,
+				versions: finalVersions,
+				mirrorReport: emptyMirrorReport,
+				removedFiles: /* @__PURE__ */ new Map(),
+				summary: createEmptySummary(syncDuration)
+			};
+		}
+		debug$4?.(`Starting sync for ${versionsToSync.length} version(s) with concurrency=${concurrency}, force=${force}`);
+		const [mirrorReport, mirrorError] = await mirror(this, {
+			versions: versionsToSync,
+			force,
+			concurrency,
+			filters: options?.filters
+		});
+		if (mirrorError) throw mirrorError;
+		const removedFiles = /* @__PURE__ */ new Map();
+		if (cleanOrphaned) {
+			const limit = createConcurrencyLimiter(concurrency);
+			for (const version of versionsToSync) {
+				let expectedFilesPaths = [];
+				const snapshot = await readSnapshotOrUndefined(this.fs, version);
+				if (snapshot && snapshot.files) expectedFilesPaths = Object.keys(snapshot.files);
+				else expectedFilesPaths = (await this.getExpectedFilePaths(version)).map((f) => f.storePath);
+				const filteredExpectedFilesPaths = expectedFilesPaths.filter((filePath) => this.filter(filePath, options?.filters));
+				const expectedFilesPathsSet = new Set(filteredExpectedFilesPaths);
+				const [actualFilesPaths, listFilesError] = await listFiles(this, version, {
+					allowApi: false,
+					filters: options?.filters
+				});
+				if (listFilesError) {
+					debug$4?.(`Failed to list files for version ${version} when checking orphaned files:`, listFilesError);
+					continue;
+				}
+				debug$4?.("Actual files for version %s: %O", version, actualFilesPaths);
+				debug$4?.("Expected files for version %s: %O", version, filteredExpectedFilesPaths);
+				const orphanedFiles = actualFilesPaths.filter((filePath) => !filePath.endsWith("snapshot.json")).filter((filePath) => !expectedFilesPathsSet.has(filePath));
+				debug$4?.("Orphaned files for version %s: %O", version, orphanedFiles);
+				if (orphanedFiles.length > 0) {
+					removedFiles.set(version, []);
+					await Promise.all(orphanedFiles.map((filePath) => limit(async () => {
+						try {
+							if (await this.fs.exists(filePath)) {
+								await this.fs.rm(filePath);
+								removedFiles.get(version).push({
+									name: patheBasename(filePath),
+									filePath: prependLeadingSlash(filePath)
+								});
+								debug$4?.(`Removed orphaned file: ${filePath} for version ${version}`);
+							}
+						} catch (err) {
+							debug$4?.(`Failed to remove orphaned file ${filePath} for version ${version}:`, err);
+						}
+					})));
+				}
+			}
+		}
+		const syncDuration = Date.now() - startTime;
+		const summary = mirrorReport?.summary ?? createEmptySummary(syncDuration);
+		summary.duration = syncDuration;
+		return {
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			added,
+			removed,
+			unchanged,
+			versions: finalVersions,
+			mirrorReport: mirrorReport ?? emptyMirrorReport,
+			removedFiles,
+			summary
+		};
+	});
+}
+function sync(thisOrContext, options) {
+	if (isUCDStoreInternalContext(thisOrContext)) return _sync.call(thisOrContext, options);
+	return _sync.call(this, thisOrContext);
+}
+async function getVersionsFromApi(context) {
+	const configResult = await context.client.config.get();
+	let availableVersionsFromApi = [];
+	if (configResult.error || !configResult.data) throw new Error("Failed to fetch versions from API");
+	else availableVersionsFromApi = configResult.data.versions;
+	return availableVersionsFromApi;
+}
+
+//#endregion
+//#region src/utils/lockfile.ts
+const debug$3 = createDebugger("ucdjs:ucd-store:init-lockfile");
+/**
+* Initializes a new store lockfile by validating versions against the API
+* and creating the initial lockfile (if the bridge supports writing).
+*
+* This only creates the lockfile structure - it does NOT download any files.
+* Use `mirror()` to download the actual Unicode data files.
+*
+* @param {InternalUCDStoreContext} context - The internal store context
+* @throws {UCDStoreGenericError} If API fetch fails or versions are invalid
+*/
+async function initLockfile(context) {
+	const { fs, filter } = context;
+	const versions = context.versions.resolved;
+	debug$3?.("Starting lockfile initialization for versions:", versions);
+	const availableVersions = await context.versions.apiVersions();
+	if (availableVersions.length === 0) throw new UCDStoreGenericError("Failed to fetch Unicode versions: no versions available from API");
+	debug$3?.(`Fetched ${availableVersions.length} available versions from API`);
+	const missingVersions = versions.filter((v) => !availableVersions.includes(v));
+	if (missingVersions.length > 0) {
+		debug$3?.("✗ Validation failed - missing versions:", missingVersions);
+		throw new UCDStoreGenericError(`Some requested versions are not available in the API: ${missingVersions.join(", ")}`);
+	}
+	debug$3?.("✓ All requested versions are available");
+	if (!await fs.exists(".")) {
+		debug$3?.("Creating store root directory");
+		assertCapability(fs, "mkdir");
+		await fs.mkdir(".");
+	} else debug$3?.("Base directory already exists");
+	if (context.lockfile.supports && context.lockfile.path) {
+		debug$3?.(`Writing lockfile to: ${context.lockfile.path}`);
+		const filters = filter ? extractFilterPatterns(filter) : void 0;
+		const now = /* @__PURE__ */ new Date();
+		await writeLockfile(fs, context.lockfile.path, {
+			lockfileVersion: 1,
+			createdAt: now,
+			updatedAt: now,
+			versions: Object.fromEntries(versions.map((v) => [v, {
+				path: `${v}/snapshot.json`,
+				fileCount: 0,
+				totalSize: 0,
+				createdAt: now,
+				updatedAt: now
+			}])),
+			filters
+		});
+		debug$3?.("✓ Lockfile written");
+	} else debug$3?.("Skipping lockfile write - bridge does not support writing");
+	debug$3?.("✓ Lockfile initialization completed successfully");
+}
+
+//#endregion
+//#region src/utils/validate.ts
+const debug$2 = createDebugger("ucdjs:ucd-store:validate");
+/**
+* Validates that the provided versions are available in the API.
+* This is a pure validation function with no lockfile dependency.
+*
+* @param {ValidateVersionsOptions} options - Validation options
+* @returns {Promise<ValidateVersionsResult>} Validation result
+* @throws {UCDStoreGenericError} If API fetch fails
+*/
+async function validateVersions(options) {
+	const { client, versions } = options;
+	debug$2?.("Starting version validation for:", versions);
+	const apiResponseResult = await client.versions.list();
+	if (apiResponseResult.error) throw new UCDStoreGenericError(`Failed to fetch Unicode versions during validation: ${apiResponseResult.error.message}${apiResponseResult.error.status ? ` (status ${apiResponseResult.error.status})` : ""}`);
+	if (!apiResponseResult.data) throw new UCDStoreGenericError("Failed to fetch Unicode versions during validation: no data returned");
+	const availableVersions = apiResponseResult.data.map(({ version }) => version);
+	debug$2?.(`Fetched ${availableVersions.length} available versions from API`);
+	const validVersions = versions.filter((v) => availableVersions.includes(v));
+	const invalidVersions = versions.filter((v) => !availableVersions.includes(v));
+	const valid = invalidVersions.length === 0;
+	debug$2?.(valid ? "✓ Validation passed" : "✗ Validation failed", {
+		valid: validVersions.length,
+		invalid: invalidVersions.length
+	});
+	if (invalidVersions.length > 0) debug$2?.("Invalid versions:", invalidVersions);
+	return {
+		valid,
+		validatedVersions: versions,
+		availableVersions,
+		validVersions,
+		invalidVersions
+	};
+}
+
+//#endregion
+//#region src/utils/verify.ts
+const debug$1 = createDebugger("ucdjs:ucd-store:verify");
+/**
+* Verifies that store versions are available in the API.
+*
+* If the store supports lockfiles and one exists, it verifies the lockfile versions.
+* Otherwise, it validates the store's configured versions directly against the API.
+*
+* @param {InternalUCDStoreContext} context - Internal store context
+* @returns {Promise<VerifyResult>} Verification result with comparison details
+* @throws {UCDStoreGenericError} If lockfile read or API fetch fails
+*/
+async function verify(context) {
+	const { client, fs } = context;
+	const { supports: supportsLockfile, exists: lockfileExists, path: lockfilePath } = context.lockfile;
+	const versions = context.versions.resolved;
+	if (supportsLockfile && lockfileExists && lockfilePath) {
+		debug$1?.("Starting lockfile verification");
+		const lockfile = await tryOr({
+			try: () => readLockfile(fs, lockfilePath),
+			err: (err) => {
+				throw new UCDStoreGenericError(`Failed to read lockfile at ${lockfilePath}: ${err.message}`);
+			}
+		});
+		const lockfileVersions = Object.keys(lockfile.versions || {});
+		debug$1?.(`Found ${lockfileVersions.length} versions in lockfile:`, lockfileVersions);
+		const validationResult = await validateVersions({
+			client,
+			versions: lockfileVersions
+		});
+		const extraVersions = validationResult.availableVersions.filter((v) => !lockfileVersions.includes(v));
+		debug$1?.(validationResult.valid ? "✓ Lockfile verification passed" : "✗ Lockfile verification failed", {
+			invalid: validationResult.invalidVersions.length,
+			extra: extraVersions.length
+		});
+		return {
+			valid: validationResult.valid,
+			source: "lockfile",
+			verifiedVersions: lockfileVersions,
+			availableVersions: validationResult.availableVersions,
+			invalidVersions: validationResult.invalidVersions,
+			extraVersions
+		};
+	}
+	debug$1?.("Starting store version validation (no lockfile)");
+	const validationResult = await validateVersions({
+		client,
+		versions
+	});
+	debug$1?.(validationResult.valid ? "✓ Version validation passed" : "✗ Version validation failed", { invalid: validationResult.invalidVersions.length });
+	return {
+		valid: validationResult.valid,
+		source: "store",
+		verifiedVersions: versions,
+		availableVersions: validationResult.availableVersions,
+		invalidVersions: validationResult.invalidVersions,
+		extraVersions: []
+	};
+}
+
+//#endregion
+//#region src/store.ts
+const debug = createDebugger("ucdjs:ucd-store");
+async function createUCDStore(options) {
+	debug?.("Creating UCD Store with options", options);
+	const { baseUrl, globalFilters, fs: fsFactory, fsOptions, versions, endpointConfig, requireExistingStore, verify: shouldVerify, versionStrategy } = defu(options, {
+		baseUrl: UCDJS_API_BASE_URL,
+		globalFilters: {},
+		versions: [],
+		requireExistingStore: true,
+		verify: true,
+		versionStrategy: "strict"
+	});
+	const filter = createPathFilter(globalFilters);
+	let resolvedEndpointConfig = endpointConfig;
+	let client = options.client;
+	if (!resolvedEndpointConfig && !client) {
+		debug?.("No endpoint config or client provided, will attempt to discover.");
+		resolvedEndpointConfig = await retrieveEndpointConfiguration(baseUrl);
+	}
+	if (!client) {
+		debug?.("No client provided, creating UCD client with resolved endpoint config.");
+		client = createUCDClientWithConfig(baseUrl, resolvedEndpointConfig);
+	}
+	const discoveryContext = {
+		baseUrl,
+		endpointConfig: resolvedEndpointConfig,
+		versions: resolvedEndpointConfig?.versions ?? []
+	};
+	const resolvedFsOptions = typeof fsOptions === "function" ? fsOptions(discoveryContext) : fsOptions;
+	const fs = resolvedFsOptions !== void 0 ? fsFactory(resolvedFsOptions) : fsFactory();
+	const supportsLockfile = fs.optionalCapabilities?.write === true;
+	const lockfilePath = supportsLockfile ? getLockfilePath() : null;
+	debug?.("Lockfile support:", supportsLockfile, "path:", lockfilePath);
+	const configVersions = resolvedEndpointConfig?.versions ?? [];
+	const lockfileExists = supportsLockfile ? await fs.exists(lockfilePath) : false;
+	debug?.("Lockfile exists:", lockfileExists);
+	let storeVersions = versions;
+	const internalContext = createInternalContext({
+		client,
+		filter,
+		fs,
+		lockfile: {
+			supports: supportsLockfile,
+			exists: lockfileExists,
+			path: lockfilePath ?? ""
+		},
+		versions: {
+			userProvided: versions,
+			configFile: configVersions
+		}
+	});
+	const versionsToValidate = versions.length > 0 ? versions : configVersions;
+	if (versionsToValidate.length > 0) {
+		const apiVersions = await internalContext.versions.apiVersions();
+		if (apiVersions.length === 0) debug?.("Warning: Could not fetch API versions for validation, skipping early check");
+		else {
+			const invalidVersions = versionsToValidate.filter((v) => !apiVersions.includes(v));
+			if (invalidVersions.length > 0) throw new UCDStoreGenericError(`${versions.length > 0 ? "Provided" : "Config"} versions are not available in API: ${invalidVersions.join(", ")}. Available versions: ${apiVersions.slice(0, 5).join(", ")}${apiVersions.length > 5 ? "..." : ""}`);
+			debug?.("✓ Early version validation passed");
+		}
+	}
+	if (internalContext.lockfile.exists && internalContext.lockfile.path) {
+		const lockfile = await readLockfileOrUndefined(fs, internalContext.lockfile.path);
+		const lockfileVersions = lockfile ? Object.keys(lockfile.versions) : [];
+		debug?.("Lockfile versions:", lockfileVersions);
+		if (versions.length > 0) storeVersions = await handleVersionConflict(versionStrategy, versions, lockfileVersions, fs, internalContext.lockfile.path, configVersions, filter);
+		else if (lockfileVersions.length > 0) {
+			storeVersions = lockfileVersions;
+			debug?.("Using versions from lockfile:", storeVersions);
+		} else if (configVersions.length) {
+			storeVersions = configVersions;
+			debug?.("Using versions from config:", storeVersions);
+		}
+		internalContext.versions.resolved = storeVersions;
+		internalContext.lockfile.exists = true;
+	}
+	if (!internalContext.lockfile.exists && internalContext.lockfile.supports) {
+		if (requireExistingStore) throw new UCDStoreGenericError(`Store lockfile not found at ${internalContext.lockfile.path}. Initialize the store first or set requireExistingStore: false to create automatically.`);
+		if (!storeVersions.length && configVersions.length) {
+			storeVersions = configVersions;
+			debug?.("Using versions from config for initialization:", storeVersions);
+		}
+		internalContext.versions.resolved = storeVersions;
+		await initLockfile(internalContext);
+		internalContext.lockfile.exists = true;
+	}
+	if (!internalContext.lockfile.supports) {
+		if (!storeVersions.length && configVersions.length) {
+			storeVersions = configVersions;
+			debug?.("Read-only bridge: using versions from config:", storeVersions);
+		}
+		if (!storeVersions.length) throw new UCDStoreGenericError("No versions provided for read-only file system bridge. Provide versions in options or ensure endpoint config is available.");
+		internalContext.versions.resolved = storeVersions;
+		debug?.("Read-only bridge initialized with versions:", storeVersions);
+	}
+	if (shouldVerify && internalContext.versions.resolved.length > 0) {
+		const verifyResult = await verify(internalContext);
+		if (!verifyResult.valid) throw new UCDStoreGenericError(`${verifyResult.source === "lockfile" ? "Lockfile" : "Version"} verification failed: ${verifyResult.invalidVersions.length} version(s) are not available in API: ${verifyResult.invalidVersions.join(", ")}`);
+		debug?.(`✓ Verification passed (source: ${verifyResult.source})`);
+	}
+	const publicContext = createPublicContext(internalContext);
+	return Object.assign(publicContext, {
+		files: {
+			get: getFile.bind(internalContext),
+			list: listFiles.bind(internalContext),
+			tree: getFileTree.bind(internalContext)
+		},
+		mirror: mirror.bind(internalContext),
+		sync: sync.bind(internalContext),
+		analyze: analyze.bind(internalContext),
+		compare: compare.bind(internalContext)
+	});
+}
+async function retrieveEndpointConfiguration(baseUrl = UCDJS_API_BASE_URL) {
+	debug?.("Attempting to discover endpoint configuration from", baseUrl);
+	return discoverEndpointsFromConfig(baseUrl).catch((err) => {
+		debug?.("Failed to discover endpoint config, using default:", err);
+		return getDefaultUCDEndpointConfig();
+	});
+}
+async function handleVersionConflict(strategy, providedVersions, lockfileVersions, fs, lockfilePath, _configVersions, filter) {
+	const now = /* @__PURE__ */ new Date();
+	switch (strategy) {
+		case "merge": {
+			const mergedVersions = Array.from(new Set([...lockfileVersions, ...providedVersions]));
+			const existing = await readLockfileOrUndefined(fs, lockfilePath);
+			const { writeLockfile } = await import("@ucdjs/lockfile");
+			const { extractFilterPatterns } = await import("./context-DfX5D4Fb.mjs").then((n) => n.t);
+			const filters = filter ? extractFilterPatterns(filter) : existing?.filters;
+			await writeLockfile(fs, lockfilePath, {
+				lockfileVersion: 1,
+				createdAt: existing?.createdAt ?? now,
+				updatedAt: now,
+				versions: Object.fromEntries(mergedVersions.map((v) => {
+					return [v, existing?.versions[v] ?? {
+						path: `${v}/snapshot.json`,
+						fileCount: 0,
+						totalSize: 0,
+						createdAt: now,
+						updatedAt: now
+					}];
+				})),
+				filters
+			});
+			debug?.("Merge mode: combined versions", mergedVersions);
+			return mergedVersions;
+		}
+		case "overwrite": {
+			const existing = await readLockfileOrUndefined(fs, lockfilePath);
+			const { writeLockfile } = await import("@ucdjs/lockfile");
+			const { extractFilterPatterns } = await import("./context-DfX5D4Fb.mjs").then((n) => n.t);
+			const filters = filter ? extractFilterPatterns(filter) : existing?.filters;
+			await writeLockfile(fs, lockfilePath, {
+				lockfileVersion: 1,
+				createdAt: existing?.createdAt ?? now,
+				updatedAt: now,
+				versions: Object.fromEntries(providedVersions.map((v) => {
+					return [v, existing?.versions[v] ?? {
+						path: `${v}/snapshot.json`,
+						fileCount: 0,
+						totalSize: 0,
+						createdAt: now,
+						updatedAt: now
+					}];
+				})),
+				filters
+			});
+			debug?.("Overwrite mode: replaced lockfile with provided versions", providedVersions);
+			return providedVersions;
+		}
+		default:
+			if (!arraysEqual(providedVersions, lockfileVersions)) throw new UCDStoreGenericError(`Version mismatch: lockfile has [${lockfileVersions.join(", ")}], provided [${providedVersions.join(", ")}]. Use versionStrategy: "merge" or "overwrite" to resolve.`);
+			debug?.("Strict mode: versions match lockfile");
+			return lockfileVersions;
+	}
+}
+function arraysEqual(a, b) {
+	if (a.length !== b.length) return false;
+	const setA = new Set(a);
+	const setB = new Set(b);
+	if (setA.size !== setB.size) return false;
+	for (const val of setA) if (!setB.has(val)) return false;
+	return true;
+}
+
+//#endregion
+//#region src/factory.ts
+/**
+* Creates a UCD store backed by the Node.js FileSystemBridge.
+* @template BridgeOptionsSchema extends z.ZodType
+* @param {NodeUCDStoreOptions<BridgeOptionsSchema>} [options] Store options; provide basePath to set the filesystem root.
+* @returns {Promise<UCDStore>} A ready-to-use store instance.
+* @throws {Error} If the Node.js FileSystemBridge could not be loaded.
+*/
+async function createNodeUCDStore(options = {}) {
+	const nodeFs = await import("@ucdjs/fs-bridge/bridges/node").then((m) => m.default);
+	if (!nodeFs) throw new Error("Node.js FileSystemBridge could not be loaded");
+	const { basePath, ...storeOptions } = options;
+	const resolvedBasePath = basePath ? patheResolve(basePath) : patheResolve("./");
+	return createUCDStore({
+		...storeOptions,
+		fs: nodeFs,
+		fsOptions: { basePath: resolvedBasePath }
+	});
+}
+/**
+* Creates a UCD store backed by the HTTP FileSystemBridge.
+* @template BridgeOptionsSchema extends z.ZodType
+* @param {HTTPUCDStoreOptions<BridgeOptionsSchema>} [options] Store options; provide baseUrl to override the default.
+* @returns {Promise<UCDStore>} A ready-to-use store instance.
+* @throws {Error} If the HTTP FileSystemBridge could not be loaded.
+*/
+async function createHTTPUCDStore(options = {}) {
+	const httpFsBridge = await import("@ucdjs/fs-bridge/bridges/http").then((m) => m.default);
+	if (!httpFsBridge) throw new Error("HTTP FileSystemBridge could not be loaded");
+	const { bridgeBaseUrl, ...storeOptions } = options;
+	const resolvedBridgeBaseUrl = bridgeBaseUrl ?? UCDJS_STORE_BASE_URL;
+	return createUCDStore({
+		...storeOptions,
+		fs: httpFsBridge,
+		fsOptions: { baseUrl: resolvedBridgeBaseUrl }
+	});
+}
+
+//#endregion
+export { UCDStoreBaseError, UCDStoreBridgeUnsupportedOperation, UCDStoreFileNotFoundError, UCDStoreGenericError, UCDStoreVersionNotFoundError, createHTTPUCDStore, createNodeUCDStore, createUCDStore, validateVersions };