@aigne/afs-did-space 1.12.0-beta.5

package/dist/rsync.d.mts

@@ -0,0 +1,157 @@
+import { MetadataDB } from "./metadata-db.mjs";
+import { AFS } from "@aigne/afs";
+
+//#region src/rsync.d.ts
+interface FileFingerprint {
+  path: string;
+  size: number;
+  cid?: string;
+  mtime?: number;
+}
+interface SyncManifest {
+  /**
+   * Legacy file list field — kept REQUIRED for backward compatibility
+   * with existing consumers (rsync.ts pipeline, computeDiff, e2e tests).
+   *
+   * Task 3.2: as of the G5.b manifest endpoint rewrite, the server now
+   * also returns this same data under the `entries` field plus a fresh
+   * `manifestSeq` cursor. New code should prefer `entries` + `manifestSeq`
+   * but reading `files` continues to work — both arrays carry identical
+   * data, they are two views of the same underlying snapshot.
+   */
+  files: FileFingerprint[];
+  /**
+   * Task 3.2 — canonical "entries" view of the same data as `files`.
+   * Optional because clients constructing a manifest locally (e.g.
+   * `buildManifestFromDB`) may omit it; the wire format from the server
+   * always includes it.
+   */
+  entries?: FileFingerprint[];
+  /**
+   * Task 3.2 — server-provided changelog cursor at the moment the
+   * manifest was assembled. After reading the manifest a client can
+   * call `GET /sync/changes?since=manifestSeq` to fetch all subsequent
+   * deltas without missing or replaying entries (CTE single-shot
+   * snapshot — entries and manifestSeq come from the same point-in-time
+   * read).
+   *
+   * Optional because client-constructed manifests have no server seq.
+   * 0 is a valid value (empty changelog == nothing has been written
+   * to this scope yet).
+   */
+  manifestSeq?: number;
+  createdAt: number;
+}
+interface SyncDiffEntry {
+  path: string;
+  reason: "added" | "modified" | "deleted";
+}
+interface SyncDiff {
+  entries: SyncDiffEntry[];
+  stats: {
+    added: number;
+    modified: number;
+    deleted: number;
+    unchanged: number;
+  };
+}
+interface SyncProgress {
+  phase: "scanning" | "diffing" | "transferring" | "verifying" | "done" | "failed";
+  filesTotal: number;
+  filesProcessed: number;
+  bytesTotal: number;
+  bytesTransferred: number;
+  errors: Array<{
+    path: string;
+    error: string;
+  }>;
+  startedAt: number;
+  updatedAt: number;
+}
+interface SyncResult {
+  success: boolean;
+  diff: SyncDiff;
+  transferred: number;
+  verified: boolean;
+  errors: Array<{
+    path: string;
+    error: string;
+  }>;
+  durationMs: number;
+}
+interface SyncOptions {
+  delete?: boolean;
+  dryRun?: boolean;
+  verify?: boolean;
+  concurrency?: number;
+  onProgress?: (progress: SyncProgress) => void;
+  /** Filter function to exclude paths from sync. Return true to include. */
+  pathFilter?: (path: string) => boolean;
+  /**
+   * If provided, fetch the src manifest from a remote server endpoint instead of
+   * paginating through srcAfs. Useful when the remote side has a manifest endpoint.
+   */
+  srcFetchManifest?: (basePath: string, since?: number) => Promise<SyncManifest>;
+  /**
+   * If provided, fetch the dst manifest from a remote server endpoint instead of
+   * paginating through dstAfs. Useful when the remote side has a manifest endpoint.
+   */
+  dstFetchManifest?: (basePath: string, since?: number) => Promise<SyncManifest>;
+  /**
+   * Phase 3: If provided, enable checkpoint-based resume-on-failure.
+   * transferFiles() will persist progress to sync_checkpoint table and resume
+   * from the last completed file if interrupted.
+   */
+  checkpointOptions?: {
+    metadataDb: MetadataDB;
+    direction: string;
+    remoteUrl: string;
+    basePath: string;
+  };
+}
+interface BuildManifestOptions {
+  /**
+   * If provided, fetch manifest from a remote server endpoint instead of
+   * paginating through the AFS. The `afs` parameter is unused when this is set.
+   */
+  fetchManifest?: (basePath: string, since?: number) => Promise<SyncManifest>;
+  /** Only return files modified after this timestamp (ms). Passed to fetchManifest. */
+  since?: number;
+  /**
+   * Phase 2: If provided (together with localRootPath + localScope), build the
+   * manifest by calling reconcile() then querying _metadata.db directly.
+   * This replaces the O(N) full stat+read+CID scan with an O(1) SQL query.
+   */
+  localMetadataDb?: MetadataDB;
+  /** Root directory of the user's DID space (required when localMetadataDb is set). */
+  localRootPath?: string;
+  /** userDid / scope for the entries query (required when localMetadataDb is set). */
+  localScope?: string;
+  /**
+   * Task 1.3: explicit opt-out — skip both the explicit DB params and the
+   * metadata context attached by DIDSpace, and fall through to the legacy
+   * AFS pagination path. Used for back-compat testing + rare callers that
+   * must re-scan the filesystem from scratch.
+   */
+  skipLocalMetadataDb?: boolean;
+}
+/**
+ * Fetch a file manifest from a remote server's POST /api/space/manifest endpoint.
+ *
+ * This replaces the N-request paginated list + per-file CID read with a single
+ * request that returns the complete manifest directly from the server's D1 index.
+ *
+ * @param baseUrl    Server base URL (e.g. "https://computer.afsd.dev")
+ * @param authHeader Authorization header value (e.g. "Bearer <token>")
+ * @param basePath   Path within the space (e.g. "/" or "/blocklets/z1blk/")
+ * @param since      Optional: only return files modified after this ms timestamp
+ * @param fetchFn    Optional fetch override (for testing)
+ */
+declare function fetchRemoteManifest(baseUrl: string, authHeader: string, basePath: string, since?: number, fetchFn?: typeof globalThis.fetch): Promise<SyncManifest>;
+declare function buildManifest(afs: AFS, basePath: string, options?: BuildManifestOptions): Promise<SyncManifest>;
+declare function computeDiff(src: SyncManifest, dst: SyncManifest, options?: Pick<SyncOptions, "delete">): SyncDiff;
+declare function runWithConcurrency(tasks: Array<() => Promise<void>>, limit: number): Promise<void>;
+declare function syncDIDSpace(srcAfs: AFS, dstAfs: AFS, basePath: string, options?: SyncOptions): Promise<SyncResult>;
+//#endregion
+export { BuildManifestOptions, FileFingerprint, SyncDiff, SyncDiffEntry, SyncManifest, SyncOptions, SyncProgress, SyncResult, buildManifest, computeDiff, fetchRemoteManifest, runWithConcurrency, syncDIDSpace };
+//# sourceMappingURL=rsync.d.mts.map

package/dist/rsync.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsync.d.mts","names":[],"sources":["../src/rsync.ts"],"mappings":";;;;UAuCiB,eAAA;EACf,IAAA;EACA,IAAA;EACA,GAAA;EACA,KAAA;AAAA;AAAA,UAGe,YAAA;EAgCN;;AAGX;;;;;AAKA;;;EA7BE,KAAA,EAAO,eAAA;EA8BP;;;;;;EAvBA,OAAA,GAAU,eAAA;EAwB0D;;AAGtE;;;;;;;;;;EAdE,WAAA;EACA,SAAA;AAAA;AAAA,UAGe,aAAA;EACf,IAAA;EACA,MAAA;AAAA;AAAA,UAGe,QAAA;EACf,OAAA,EAAS,aAAA;EACT,KAAA;IAAS,KAAA;IAAe,QAAA;IAAkB,OAAA;IAAiB,SAAA;EAAA;AAAA;AAAA,UAG5C,YAAA;EACf,KAAA;EACA,UAAA;EACA,cAAA;EACA,UAAA;EACA,gBAAA;EACA,MAAA,EAAQ,KAAA;IAAQ,IAAA;IAAc,KAAA;EAAA;EAC9B,SAAA;EACA,SAAA;AAAA;AAAA,UAGe,UAAA;EACf,OAAA;EACA,IAAA,EAAM,QAAA;EACN,WAAA;EACA,QAAA;EACA,MAAA,EAAQ,KAAA;IAAQ,IAAA;IAAc,KAAA;EAAA;EAC9B,UAAA;AAAA;AAAA,UAGe,WAAA;EACf,MAAA;EACA,MAAA;EACA,MAAA;EACA,WAAA;EACA,UAAA,IAAc,QAAA,EAAU,YAAA;EAOiC;EALzD,UAAA,IAAc,IAAA;EAUd;;;;EALA,gBAAA,IAAoB,QAAA,UAAkB,KAAA,cAAmB,OAAA,CAAQ,YAAA;EAWjE;;;;EANA,gBAAA,IAAoB,QAAA,UAAkB,KAAA,cAAmB,OAAA,CAAQ,YAAA;EAU/D;;;AAIJ;;EARE,iBAAA;IACE,UAAA,EAAY,UAAA;IACZ,SAAA;IACA,SAAA;IACA,QAAA;EAAA;AAAA;AAAA,UAIa,oBAAA;EAKoB;;;;EAAnC,aAAA,IAAiB,QAAA,UAAkB,KAAA,cAAmB,OAAA,CAAQ,YAAA;EAQ5C;EANlB,KAAA;EAUA;;;;AA6BF;EAjCE,eAAA,GAAkB,UAAA;;EAElB,aAAA;EAqCS;EAnCT,UAAA;EAmCQ;;;;;;EA5BR,mBAAA;AAAA;;;;;;AAoEF;;;;;;;iBA9CsB,mBAAA,CACpB,OAAA,UACA,UAAA,UACA,QAAA,UACA,KAAA,WACA,OAAA,UAAgB,UAAA,CAAW,KAAA,GAC1B,OAAA,CAAQ,YAAA;AAAA,iBAwCW,aAAA,CACpB,GAAA,EAAK,GAAA,EACL,QAAA,UACA,OAAA,GAAU,oBAAA,GACT,OAAA,CAAQ,YAAA;AAAA,iBAwFK,WAAA,CACd,GAAA,EAAK,YAAA,EACL,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,IAAA,CAAK,WAAA,cACd,QAAA;AAAA,iBA4LmB,kBAAA,CACpB,KAAA,EAAO,KAAA,OAAY,OAAA,SACnB,KAAA,WACC,OAAA;AAAA,iBAyDmB,YAAA,CACpB,MAAA,EAAQ,GAAA,EACR,MAAA,EAAQ,GAAA,EACR,QAAA,UACA,OAAA,GAAU,WAAA,GACT,OAAA,CAAQ,UAAA"}

package/dist/rsync.mjs

@@ -0,0 +1,397 @@
+import { computeCID } from "./cid.mjs";
+import { getMetadataContext } from "./afs-metadata-context.mjs";
+import { resolveAFSContent } from "./rsync-content.mjs";
+
+//#region src/rsync.ts
+/**
+* Compute how many files to sample for verification.
+* Formula: max(1, min(100, ceil(totalTransferred / 10)))
+*/
+function computeSampleCount(totalTransferred) {
+	if (totalTransferred === 0) return 0;
+	return Math.max(1, Math.min(100, Math.ceil(totalTransferred / 10)));
+}
+/**
+* Select a random sample of `count` items from `files`.
+* Uses partial Fisher-Yates shuffle. Returns a copy.
+*/
+function sampleFiles(files, count) {
+	if (count >= files.length) return [...files];
+	const shuffled = [...files];
+	for (let i = 0; i < count; i++) {
+		const j = i + Math.floor(Math.random() * (shuffled.length - i));
+		[shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+	}
+	return shuffled.slice(0, count);
+}
+/** Content-decoding helpers shared with the local metadata subscriber. */
+const resolveContent = resolveAFSContent;
+/**
+* Fetch a file manifest from a remote server's POST /api/space/manifest endpoint.
+*
+* This replaces the N-request paginated list + per-file CID read with a single
+* request that returns the complete manifest directly from the server's D1 index.
+*
+* @param baseUrl    Server base URL (e.g. "https://computer.afsd.dev")
+* @param authHeader Authorization header value (e.g. "Bearer <token>")
+* @param basePath   Path within the space (e.g. "/" or "/blocklets/z1blk/")
+* @param since      Optional: only return files modified after this ms timestamp
+* @param fetchFn    Optional fetch override (for testing)
+*/
+async function fetchRemoteManifest(baseUrl, authHeader, basePath, since, fetchFn = globalThis.fetch) {
+	const url = `${baseUrl.replace(/\/$/, "")}/api/space/manifest`;
+	const body = { basePath };
+	if (since !== void 0) body.since = since;
+	const response = await fetchFn(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Authorization: authHeader
+		},
+		body: JSON.stringify(body)
+	});
+	if (!response.ok) throw new Error(`fetchRemoteManifest failed: ${response.status} ${response.statusText} from ${url}`);
+	const raw = await response.json();
+	const files = raw.entries ?? raw.files ?? [];
+	return {
+		files,
+		entries: files,
+		manifestSeq: raw.manifestSeq,
+		createdAt: raw.createdAt
+	};
+}
+const BUILD_MANIFEST_PAGE_SIZE = 1e3;
+async function buildManifest(afs, basePath, options) {
+	if (options?.fetchManifest) return options.fetchManifest(basePath, options.since);
+	if (options?.localMetadataDb && options.localRootPath && options.localScope) return buildManifestFromDB(options.localMetadataDb, options.localRootPath, options.localScope, basePath);
+	if (!options?.skipLocalMetadataDb) {
+		const ctx = getMetadataContext(afs);
+		if (ctx) return buildManifestFromDB(ctx.metadataDb, ctx.userDir, ctx.scope, basePath);
+	}
+	const SYSTEM_VIRTUAL_PATHS = new Set([
+		"/.knowledge",
+		"/.meta",
+		"/.actions"
+	]);
+	const allEntries = [];
+	let offset = 0;
+	let pageEntries = [];
+	do {
+		const batch = await afs.list(basePath, {
+			maxDepth: 99,
+			limit: BUILD_MANIFEST_PAGE_SIZE,
+			offset
+		});
+		pageEntries = basePath === "/" ? batch.data.filter((e) => !SYSTEM_VIRTUAL_PATHS.has(e.path)) : batch.data;
+		allEntries.push(...pageEntries);
+		offset += pageEntries.length;
+	} while (pageEntries.length === BUILD_MANIFEST_PAGE_SIZE);
+	const files = [];
+	for (const entry of allEntries) {
+		if (entry.meta?.childrenCount != null) continue;
+		let cid = entry.meta?.cid;
+		if (!cid) try {
+			const readResult = await afs.read(entry.path);
+			const content = readResult.data?.content;
+			if (content != null) cid = await computeCID(resolveContent(content, readResult.data?.meta));
+		} catch {}
+		files.push({
+			path: entry.path,
+			size: entry.meta?.size ?? 0,
+			cid,
+			mtime: entry.updatedAt?.getTime()
+		});
+	}
+	return {
+		files,
+		createdAt: Date.now()
+	};
+}
+function computeDiff(src, dst, options) {
+	const dstMap = /* @__PURE__ */ new Map();
+	for (const f of dst.files) dstMap.set(f.path, f);
+	const entries = [];
+	let added = 0;
+	let modified = 0;
+	let unchanged = 0;
+	const seenPaths = /* @__PURE__ */ new Set();
+	for (const srcFile of src.files) {
+		seenPaths.add(srcFile.path);
+		const dstFile = dstMap.get(srcFile.path);
+		if (!dstFile) {
+			entries.push({
+				path: srcFile.path,
+				reason: "added"
+			});
+			added++;
+			continue;
+		}
+		if (isModified(srcFile, dstFile)) {
+			entries.push({
+				path: srcFile.path,
+				reason: "modified"
+			});
+			modified++;
+		} else unchanged++;
+	}
+	let deleted = 0;
+	if (options?.delete) {
+		for (const dstFile of dst.files) if (!seenPaths.has(dstFile.path)) {
+			entries.push({
+				path: dstFile.path,
+				reason: "deleted"
+			});
+			deleted++;
+		}
+	}
+	return {
+		entries,
+		stats: {
+			added,
+			modified,
+			deleted,
+			unchanged
+		}
+	};
+}
+function isModified(src, dst) {
+	if (src.cid && dst.cid) return src.cid !== dst.cid;
+	return src.size !== dst.size;
+}
+async function transferFiles(srcAfs, dstAfs, diff, options) {
+	const concurrency = options?.concurrency ?? 5;
+	const dryRun = options?.dryRun ?? false;
+	const errors = [];
+	let transferred = 0;
+	let sessionId = null;
+	const completedPaths = /* @__PURE__ */ new Set();
+	const checkpointOpts = options?.checkpointOptions;
+	if (checkpointOpts && !dryRun) {
+		const { metadataDb, direction, remoteUrl, basePath } = checkpointOpts;
+		const existing = await metadataDb.getActiveCheckpoint(direction, remoteUrl, basePath);
+		if (existing) {
+			sessionId = existing.session_id;
+			try {
+				const parsed = JSON.parse(existing.completed);
+				if (Array.isArray(parsed)) {
+					for (const p of parsed) if (typeof p === "string") completedPaths.add(p);
+				}
+			} catch {
+				await metadataDb.updateCheckpointCompleted(sessionId, []);
+			}
+		} else {
+			sessionId = crypto.randomUUID();
+			await metadataDb.createCheckpoint({
+				session_id: sessionId,
+				direction,
+				remote_url: remoteUrl,
+				base_path: basePath,
+				status: "active",
+				diff_json: JSON.stringify(diff.entries),
+				completed: "[]",
+				created_at: Date.now(),
+				updated_at: Date.now()
+			});
+		}
+	}
+	const progress = {
+		phase: "transferring",
+		filesTotal: diff.entries.length,
+		filesProcessed: 0,
+		bytesTotal: 0,
+		bytesTransferred: 0,
+		errors: [],
+		startedAt: Date.now(),
+		updatedAt: Date.now()
+	};
+	const toTransfer = diff.entries.filter((e) => e.reason === "added" || e.reason === "modified");
+	const toDelete = diff.entries.filter((e) => e.reason === "deleted");
+	const transferOne = async (entry) => {
+		if (completedPaths.has(entry.path)) {
+			transferred++;
+			progress.filesProcessed++;
+			progress.updatedAt = Date.now();
+			options?.onProgress?.(progress);
+			return;
+		}
+		try {
+			if (dryRun) return;
+			const readResult = await srcAfs.read(entry.path);
+			const rawContent = readResult.data?.content;
+			if (rawContent == null) throw new Error(`Failed to read ${entry.path}: no content`);
+			const content = resolveContent(rawContent, readResult.data?.meta);
+			await dstAfs.write(entry.path, { content });
+			transferred++;
+			progress.bytesTransferred += readResult.data?.meta?.size ?? 0;
+			if (sessionId && checkpointOpts) {
+				completedPaths.add(entry.path);
+				await checkpointOpts.metadataDb.updateCheckpointCompleted(sessionId, [...completedPaths]);
+			}
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			errors.push({
+				path: entry.path,
+				error: msg
+			});
+		} finally {
+			progress.filesProcessed++;
+			progress.updatedAt = Date.now();
+			progress.errors = [...errors];
+			options?.onProgress?.(progress);
+		}
+	};
+	await runWithConcurrency(toTransfer.map((e) => () => transferOne(e)), concurrency);
+	for (const entry of toDelete) {
+		if (dryRun) continue;
+		try {
+			await dstAfs.delete(entry.path);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			errors.push({
+				path: entry.path,
+				error: msg
+			});
+		} finally {
+			progress.filesProcessed++;
+			progress.updatedAt = Date.now();
+			progress.errors = [...errors];
+			options?.onProgress?.(progress);
+		}
+	}
+	if (sessionId && checkpointOpts) await checkpointOpts.metadataDb.completeCheckpoint(sessionId);
+	return {
+		transferred,
+		errors
+	};
+}
+async function runWithConcurrency(tasks, limit) {
+	const executing = /* @__PURE__ */ new Set();
+	for (const task of tasks) {
+		const p = task().then(() => {
+			executing.delete(p);
+		});
+		executing.add(p);
+		if (executing.size >= limit) await Promise.race(executing);
+	}
+	await Promise.all(executing);
+}
+/**
+* Verify sync by sampling transferred files and comparing CIDs.
+*
+* Phase 3 change: instead of full buildManifest on dst, we sample
+* max(1, min(100, ceil(transferred/10))) files from the transferred set,
+* read each from dst, compute its CID, and compare against srcManifest CID.
+*
+* @param dstAfs          Destination AFS to read files from
+* @param transferredFiles FileFingerprints from srcManifest for transferred files
+*/
+async function verifySync(dstAfs, transferredFiles) {
+	if (transferredFiles.length === 0) return true;
+	const sample = sampleFiles(transferredFiles, computeSampleCount(transferredFiles.length));
+	for (const srcFile of sample) {
+		if (!srcFile.cid) continue;
+		try {
+			const readResult = await dstAfs.read(srcFile.path);
+			const rawContent = readResult.data?.content;
+			if (rawContent == null) return false;
+			if (await computeCID(resolveContent(rawContent, readResult.data?.meta)) !== srcFile.cid) return false;
+		} catch {
+			return false;
+		}
+	}
+	return true;
+}
+async function syncDIDSpace(srcAfs, dstAfs, basePath, options) {
+	const startTime = Date.now();
+	const verify = options?.verify ?? true;
+	const progress = {
+		phase: "scanning",
+		filesTotal: 0,
+		filesProcessed: 0,
+		bytesTotal: 0,
+		bytesTransferred: 0,
+		errors: [],
+		startedAt: startTime,
+		updatedAt: startTime
+	};
+	options?.onProgress?.(progress);
+	let [srcManifest, dstManifest] = await Promise.all([buildManifest(srcAfs, basePath, options?.srcFetchManifest ? { fetchManifest: options.srcFetchManifest } : void 0), buildManifest(dstAfs, basePath, options?.dstFetchManifest ? { fetchManifest: options.dstFetchManifest } : void 0)]);
+	if (options?.pathFilter) {
+		const pf = options.pathFilter;
+		srcManifest = {
+			...srcManifest,
+			files: srcManifest.files.filter((f) => pf(f.path))
+		};
+		dstManifest = {
+			...dstManifest,
+			files: dstManifest.files.filter((f) => pf(f.path))
+		};
+	}
+	progress.phase = "diffing";
+	progress.updatedAt = Date.now();
+	options?.onProgress?.(progress);
+	const diff = computeDiff(srcManifest, dstManifest, options);
+	progress.phase = "transferring";
+	progress.filesTotal = diff.entries.filter((e) => e.reason !== "deleted").length;
+	progress.updatedAt = Date.now();
+	options?.onProgress?.(progress);
+	const { transferred, errors } = await transferFiles(srcAfs, dstAfs, diff, options);
+	let verified = false;
+	if (verify && !options?.dryRun) {
+		progress.phase = "verifying";
+		progress.updatedAt = Date.now();
+		options?.onProgress?.(progress);
+		const transferredPaths = new Set(diff.entries.filter((e) => e.reason === "added" || e.reason === "modified").map((e) => e.path));
+		verified = await verifySync(dstAfs, srcManifest.files.filter((f) => transferredPaths.has(f.path)));
+	}
+	progress.phase = errors.length > 0 ? "failed" : "done";
+	progress.updatedAt = Date.now();
+	options?.onProgress?.(progress);
+	return {
+		success: errors.length === 0,
+		diff,
+		transferred,
+		verified,
+		errors,
+		durationMs: Date.now() - startTime
+	};
+}
+/**
+* Build a manifest purely from `_metadata.db` (the index is the source of
+* truth after the Node backend moved to content-addressed storage, Phase 3).
+*
+* The old `reconcile({ rootPath })` FS-scan prelude is GONE: there is no
+* verbatim file tree to walk anymore — content lives at `objects/{cid}` and the
+* index already reflects every write (the provider writes entries atomically).
+* Reconciling against the CAS layout would mis-scan internal object files.
+* `rootPath` is retained in the signature for caller compatibility but unused.
+*/
+async function buildManifestFromDB(metadataDb, _rootPath, scope, basePath) {
+	const dbBasePath = afsBasePathToDbPrefix(basePath);
+	return {
+		files: (await metadataDb.getFiles(scope, dbBasePath)).map((row) => ({
+			path: `/${row.path}`,
+			size: row.size,
+			cid: row.cid ?? void 0,
+			mtime: row.mtime
+		})),
+		createdAt: Date.now()
+	};
+}
+/**
+* Convert an AFS basePath to a MetadataDB path prefix.
+*
+* Examples:
+*   "/"          → undefined (match all)
+*   "/appDid"    → "appDid/"
+*   "/appDid/"   → "appDid/"
+*/
+function afsBasePathToDbPrefix(basePath) {
+	const stripped = basePath.replace(/^\/+/, "").replace(/\/*$/, "");
+	if (!stripped) return void 0;
+	return `${stripped}/`;
+}
+
+//#endregion
+export { buildManifest, computeDiff, fetchRemoteManifest, runWithConcurrency, syncDIDSpace };
+//# sourceMappingURL=rsync.mjs.map

package/dist/rsync.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsync.mjs","names":[],"sources":["../src/rsync.ts"],"sourcesContent":["/**\n * DIDSpace rsync — single-direction incremental sync between AFS instances.\n *\n * Pipeline: Snapshot → Diff → Transfer → Verify\n */\n\nimport type { AFS, AFSEntry } from \"@aigne/afs\";\nimport { getMetadataContext } from \"./afs-metadata-context.js\";\nimport { computeCID } from \"./cid.js\";\nimport type { MetadataDB } from \"./metadata-db.js\";\nimport { resolveAFSContent } from \"./rsync-content.js\";\n\n// ========== Sampling helpers (exported for testing) ==========\n\n/**\n * Compute how many files to sample for verification.\n * Formula: max(1, min(100, ceil(totalTransferred / 10)))\n */\nexport function computeSampleCount(totalTransferred: number): number {\n  if (totalTransferred === 0) return 0;\n  return Math.max(1, Math.min(100, Math.ceil(totalTransferred / 10)));\n}\n\n/**\n * Select a random sample of `count` items from `files`.\n * Uses partial Fisher-Yates shuffle. Returns a copy.\n */\nexport function sampleFiles(files: FileFingerprint[], count: number): FileFingerprint[] {\n  if (count >= files.length) return [...files];\n  const shuffled = [...files];\n  for (let i = 0; i < count; i++) {\n    const j = i + Math.floor(Math.random() * (shuffled.length - i));\n    [shuffled[i], shuffled[j]] = [shuffled[j]!, shuffled[i]!];\n  }\n  return shuffled.slice(0, count);\n}\n\n// ========== Types ==========\n\nexport interface FileFingerprint {\n  path: string;\n  size: number;\n  cid?: string;\n  mtime?: number;\n}\n\nexport interface SyncManifest {\n  /**\n   * Legacy file list field — kept REQUIRED for backward compatibility\n   * with existing consumers (rsync.ts pipeline, computeDiff, e2e tests).\n   *\n   * Task 3.2: as of the G5.b manifest endpoint rewrite, the server now\n   * also returns this same data under the `entries` field plus a fresh\n   * `manifestSeq` cursor. New code should prefer `entries` + `manifestSeq`\n   * but reading `files` continues to work — both arrays carry identical\n   * data, they are two views of the same underlying snapshot.\n   */\n  files: FileFingerprint[];\n  /**\n   * Task 3.2 — canonical \"entries\" view of the same data as `files`.\n   * Optional because clients constructing a manifest locally (e.g.\n   * `buildManifestFromDB`) may omit it; the wire format from the server\n   * always includes it.\n   */\n  entries?: FileFingerprint[];\n  /**\n   * Task 3.2 — server-provided changelog cursor at the moment the\n   * manifest was assembled. After reading the manifest a client can\n   * call `GET /sync/changes?since=manifestSeq` to fetch all subsequent\n   * deltas without missing or replaying entries (CTE single-shot\n   * snapshot — entries and manifestSeq come from the same point-in-time\n   * read).\n   *\n   * Optional because client-constructed manifests have no server seq.\n   * 0 is a valid value (empty changelog == nothing has been written\n   * to this scope yet).\n   */\n  manifestSeq?: number;\n  createdAt: number;\n}\n\nexport interface SyncDiffEntry {\n  path: string;\n  reason: \"added\" | \"modified\" | \"deleted\";\n}\n\nexport interface SyncDiff {\n  entries: SyncDiffEntry[];\n  stats: { added: number; modified: number; deleted: number; unchanged: number };\n}\n\nexport interface SyncProgress {\n  phase: \"scanning\" | \"diffing\" | \"transferring\" | \"verifying\" | \"done\" | \"failed\";\n  filesTotal: number;\n  filesProcessed: number;\n  bytesTotal: number;\n  bytesTransferred: number;\n  errors: Array<{ path: string; error: string }>;\n  startedAt: number;\n  updatedAt: number;\n}\n\nexport interface SyncResult {\n  success: boolean;\n  diff: SyncDiff;\n  transferred: number;\n  verified: boolean;\n  errors: Array<{ path: string; error: string }>;\n  durationMs: number;\n}\n\nexport interface SyncOptions {\n  delete?: boolean;\n  dryRun?: boolean;\n  verify?: boolean;\n  concurrency?: number;\n  onProgress?: (progress: SyncProgress) => void;\n  /** Filter function to exclude paths from sync. Return true to include. */\n  pathFilter?: (path: string) => boolean;\n  /**\n   * If provided, fetch the src manifest from a remote server endpoint instead of\n   * paginating through srcAfs. Useful when the remote side has a manifest endpoint.\n   */\n  srcFetchManifest?: (basePath: string, since?: number) => Promise<SyncManifest>;\n  /**\n   * If provided, fetch the dst manifest from a remote server endpoint instead of\n   * paginating through dstAfs. Useful when the remote side has a manifest endpoint.\n   */\n  dstFetchManifest?: (basePath: string, since?: number) => Promise<SyncManifest>;\n  /**\n   * Phase 3: If provided, enable checkpoint-based resume-on-failure.\n   * transferFiles() will persist progress to sync_checkpoint table and resume\n   * from the last completed file if interrupted.\n   */\n  checkpointOptions?: {\n    metadataDb: MetadataDB;\n    direction: string;\n    remoteUrl: string;\n    basePath: string;\n  };\n}\n\nexport interface BuildManifestOptions {\n  /**\n   * If provided, fetch manifest from a remote server endpoint instead of\n   * paginating through the AFS. The `afs` parameter is unused when this is set.\n   */\n  fetchManifest?: (basePath: string, since?: number) => Promise<SyncManifest>;\n  /** Only return files modified after this timestamp (ms). Passed to fetchManifest. */\n  since?: number;\n  /**\n   * Phase 2: If provided (together with localRootPath + localScope), build the\n   * manifest by calling reconcile() then querying _metadata.db directly.\n   * This replaces the O(N) full stat+read+CID scan with an O(1) SQL query.\n   */\n  localMetadataDb?: MetadataDB;\n  /** Root directory of the user's DID space (required when localMetadataDb is set). */\n  localRootPath?: string;\n  /** userDid / scope for the entries query (required when localMetadataDb is set). */\n  localScope?: string;\n  /**\n   * Task 1.3: explicit opt-out — skip both the explicit DB params and the\n   * metadata context attached by DIDSpace, and fall through to the legacy\n   * AFS pagination path. Used for back-compat testing + rare callers that\n   * must re-scan the filesystem from scratch.\n   */\n  skipLocalMetadataDb?: boolean;\n}\n\n// ========== Content helpers ==========\n\n/** Content-decoding helpers shared with the local metadata subscriber. */\nconst resolveContent = resolveAFSContent;\n\n// ========== fetchRemoteManifest ==========\n\n/**\n * Fetch a file manifest from a remote server's POST /api/space/manifest endpoint.\n *\n * This replaces the N-request paginated list + per-file CID read with a single\n * request that returns the complete manifest directly from the server's D1 index.\n *\n * @param baseUrl    Server base URL (e.g. \"https://computer.afsd.dev\")\n * @param authHeader Authorization header value (e.g. \"Bearer <token>\")\n * @param basePath   Path within the space (e.g. \"/\" or \"/blocklets/z1blk/\")\n * @param since      Optional: only return files modified after this ms timestamp\n * @param fetchFn    Optional fetch override (for testing)\n */\nexport async function fetchRemoteManifest(\n  baseUrl: string,\n  authHeader: string,\n  basePath: string,\n  since?: number,\n  fetchFn: typeof globalThis.fetch = globalThis.fetch,\n): Promise<SyncManifest> {\n  const url = `${baseUrl.replace(/\\/$/, \"\")}/api/space/manifest`;\n  const body: { basePath: string; since?: number } = { basePath };\n  if (since !== undefined) body.since = since;\n\n  const response = await fetchFn(url, {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      Authorization: authHeader,\n    },\n    body: JSON.stringify(body),\n  });\n\n  if (!response.ok) {\n    throw new Error(\n      `fetchRemoteManifest failed: ${response.status} ${response.statusText} from ${url}`,\n    );\n  }\n\n  // Task 3.2: server response shape is `{ files, entries, manifestSeq, createdAt }`.\n  // Both `files` and `entries` carry the same payload — `files` for legacy\n  // consumers, `entries` for new code. Normalize so the returned object\n  // always has both populated (even when talking to an older server that\n  // only provides `files`), so downstream code can pick whichever it\n  // prefers without nil-checking.\n  const raw = (await response.json()) as SyncManifest;\n  const files = raw.entries ?? raw.files ?? [];\n  return {\n    files,\n    entries: files,\n    manifestSeq: raw.manifestSeq,\n    createdAt: raw.createdAt,\n  };\n}\n\n// ========== buildManifest ==========\n\nconst BUILD_MANIFEST_PAGE_SIZE = 1000;\n\nexport async function buildManifest(\n  afs: AFS,\n  basePath: string,\n  options?: BuildManifestOptions,\n): Promise<SyncManifest> {\n  // Remote branch: use the manifest endpoint for a single-request manifest\n  if (options?.fetchManifest) {\n    return options.fetchManifest(basePath, options.since);\n  }\n\n  // Local DB branch (Phase 2, explicit): reconcile + SQL query instead of full AFS scan\n  if (options?.localMetadataDb && options.localRootPath && options.localScope) {\n    return buildManifestFromDB(\n      options.localMetadataDb,\n      options.localRootPath,\n      options.localScope,\n      basePath,\n    );\n  }\n\n  // Task 1.3: Local DB branch (implicit) — if the caller didn't pass explicit\n  // DB params but DIDSpace attached a metadata context to this AFS, use that\n  // for the default O(1) SQL path. `skipLocalMetadataDb` opts out for\n  // back-compat callers that need the legacy paginated scan.\n  if (!options?.skipLocalMetadataDb) {\n    const ctx = getMetadataContext(afs);\n    if (ctx) {\n      return buildManifestFromDB(ctx.metadataDb, ctx.userDir, ctx.scope, basePath);\n    }\n  }\n\n  // Fallback: paginate through all entries to handle spaces with >1000 files.\n  // AFS._list(\"/\") appends 3 system virtual entries (/.knowledge, /.meta, /.actions) to every\n  // page AFTER the provider returns its limit-capped results. The provider (AFSFS or D1) returns\n  // exactly BUILD_MANIFEST_PAGE_SIZE real entries; AFS then adds 3 virtual → page size = 1003.\n  // We filter virtual entries and use the filtered count (always 1000 on full pages) for both\n  // offset advancement and loop termination. This correctly handles both local AFSFS and\n  // remote D1 cases (where the server also adds 3 virtual before the client AFS adds 3 more).\n  const SYSTEM_VIRTUAL_PATHS = new Set([\"/.knowledge\", \"/.meta\", \"/.actions\"]);\n  const allEntries: AFSEntry[] = [];\n  let offset = 0;\n  let pageEntries: AFSEntry[] = [];\n  do {\n    const batch = await afs.list(basePath, {\n      maxDepth: 99,\n      limit: BUILD_MANIFEST_PAGE_SIZE,\n      offset,\n    });\n    pageEntries =\n      basePath === \"/\" ? batch.data.filter((e) => !SYSTEM_VIRTUAL_PATHS.has(e.path)) : batch.data;\n    allEntries.push(...pageEntries);\n    offset += pageEntries.length;\n  } while (pageEntries.length === BUILD_MANIFEST_PAGE_SIZE);\n\n  const files: FileFingerprint[] = [];\n\n  for (const entry of allEntries) {\n    // Skip directories (childrenCount present means it's a container)\n    if (entry.meta?.childrenCount != null) {\n      continue;\n    }\n\n    let cid: string | undefined = entry.meta?.cid;\n\n    // Compute CID for files lacking CID metadata (e.g. local AFSFS files).\n    // Enables same-size content change detection via CID comparison.\n    if (!cid) {\n      try {\n        const readResult = await afs.read(entry.path);\n        const content = readResult.data?.content;\n        if (content != null) {\n          cid = await computeCID(resolveContent(content, readResult.data?.meta));\n        }\n      } catch {\n        // File may have been deleted between list and read (race condition).\n        // Skip CID computation — next sync will re-detect.\n      }\n    }\n\n    files.push({\n      path: entry.path,\n      size: entry.meta?.size ?? 0,\n      cid,\n      mtime: entry.updatedAt?.getTime(),\n    });\n  }\n\n  return { files, createdAt: Date.now() };\n}\n\n// ========== computeDiff ==========\n\nexport function computeDiff(\n  src: SyncManifest,\n  dst: SyncManifest,\n  options?: Pick<SyncOptions, \"delete\">,\n): SyncDiff {\n  const dstMap = new Map<string, FileFingerprint>();\n  for (const f of dst.files) {\n    dstMap.set(f.path, f);\n  }\n\n  const entries: SyncDiffEntry[] = [];\n  let added = 0;\n  let modified = 0;\n  let unchanged = 0;\n  const seenPaths = new Set<string>();\n\n  for (const srcFile of src.files) {\n    seenPaths.add(srcFile.path);\n    const dstFile = dstMap.get(srcFile.path);\n\n    if (!dstFile) {\n      entries.push({ path: srcFile.path, reason: \"added\" });\n      added++;\n      continue;\n    }\n\n    if (isModified(srcFile, dstFile)) {\n      entries.push({ path: srcFile.path, reason: \"modified\" });\n      modified++;\n    } else {\n      unchanged++;\n    }\n  }\n\n  let deleted = 0;\n  if (options?.delete) {\n    for (const dstFile of dst.files) {\n      if (!seenPaths.has(dstFile.path)) {\n        entries.push({ path: dstFile.path, reason: \"deleted\" });\n        deleted++;\n      }\n    }\n  }\n\n  return { entries, stats: { added, modified, deleted, unchanged } };\n}\n\nfunction isModified(src: FileFingerprint, dst: FileFingerprint): boolean {\n  // If both have CID, use content hash (most accurate)\n  if (src.cid && dst.cid) {\n    return src.cid !== dst.cid;\n  }\n  // Without CID, use size as the only reliable signal.\n  // mtime is unreliable across backends (write creates new mtime).\n  return src.size !== dst.size;\n}\n\n// ========== transferFiles ==========\n\nexport async function transferFiles(\n  srcAfs: AFS,\n  dstAfs: AFS,\n  diff: SyncDiff,\n  options?: SyncOptions,\n): Promise<Pick<SyncResult, \"transferred\" | \"errors\">> {\n  const concurrency = options?.concurrency ?? 5;\n  const dryRun = options?.dryRun ?? false;\n  const errors: Array<{ path: string; error: string }> = [];\n  let transferred = 0;\n\n  // ── Phase 3: Checkpoint setup ─────────────────────────────────\n  let sessionId: string | null = null;\n  const completedPaths = new Set<string>();\n  const checkpointOpts = options?.checkpointOptions;\n\n  if (checkpointOpts && !dryRun) {\n    const { metadataDb, direction, remoteUrl, basePath } = checkpointOpts;\n    const existing = await metadataDb.getActiveCheckpoint(direction, remoteUrl, basePath);\n\n    if (existing) {\n      sessionId = existing.session_id;\n      try {\n        const parsed = JSON.parse(existing.completed);\n        if (Array.isArray(parsed)) {\n          for (const p of parsed) {\n            if (typeof p === \"string\") completedPaths.add(p);\n          }\n        }\n      } catch {\n        // Corrupt completed JSON — treat as empty (re-transfer all)\n        await metadataDb.updateCheckpointCompleted(sessionId, []);\n      }\n    } else {\n      sessionId = crypto.randomUUID();\n      await metadataDb.createCheckpoint({\n        session_id: sessionId,\n        direction,\n        remote_url: remoteUrl,\n        base_path: basePath,\n        status: \"active\",\n        diff_json: JSON.stringify(diff.entries),\n        completed: \"[]\",\n        created_at: Date.now(),\n        updated_at: Date.now(),\n      });\n    }\n  }\n  // ── End checkpoint setup ──────────────────────────────────────\n\n  const progress: SyncProgress = {\n    phase: \"transferring\",\n    filesTotal: diff.entries.length,\n    filesProcessed: 0,\n    bytesTotal: 0,\n    bytesTransferred: 0,\n    errors: [],\n    startedAt: Date.now(),\n    updatedAt: Date.now(),\n  };\n\n  const toTransfer = diff.entries.filter((e) => e.reason === \"added\" || e.reason === \"modified\");\n  const toDelete = diff.entries.filter((e) => e.reason === \"deleted\");\n\n  // Transfer files with concurrency limit\n  const transferOne = async (entry: SyncDiffEntry): Promise<void> => {\n    // Skip already-completed paths on checkpoint resume\n    if (completedPaths.has(entry.path)) {\n      transferred++;\n      progress.filesProcessed++;\n      progress.updatedAt = Date.now();\n      options?.onProgress?.(progress);\n      return;\n    }\n\n    try {\n      if (dryRun) return;\n      const readResult = await srcAfs.read(entry.path);\n      const rawContent = readResult.data?.content;\n      if (rawContent == null) {\n        throw new Error(`Failed to read ${entry.path}: no content`);\n      }\n      const content = resolveContent(rawContent, readResult.data?.meta);\n      await dstAfs.write(entry.path, { content });\n      transferred++;\n      progress.bytesTransferred += readResult.data?.meta?.size ?? 0;\n\n      // Persist completed path to checkpoint\n      if (sessionId && checkpointOpts) {\n        completedPaths.add(entry.path);\n        await checkpointOpts.metadataDb.updateCheckpointCompleted(sessionId, [...completedPaths]);\n      }\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      errors.push({ path: entry.path, error: msg });\n    } finally {\n      progress.filesProcessed++;\n      progress.updatedAt = Date.now();\n      progress.errors = [...errors];\n      options?.onProgress?.(progress);\n    }\n  };\n\n  // Simple concurrency limiter\n  await runWithConcurrency(\n    toTransfer.map((e) => () => transferOne(e)),\n    concurrency,\n  );\n\n  // Handle deletions\n  for (const entry of toDelete) {\n    if (dryRun) continue;\n    try {\n      await dstAfs.delete(entry.path);\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      errors.push({ path: entry.path, error: msg });\n    } finally {\n      progress.filesProcessed++;\n      progress.updatedAt = Date.now();\n      progress.errors = [...errors];\n      options?.onProgress?.(progress);\n    }\n  }\n\n  // Mark checkpoint done after all transfers complete\n  if (sessionId && checkpointOpts) {\n    await checkpointOpts.metadataDb.completeCheckpoint(sessionId);\n  }\n\n  return { transferred, errors };\n}\n\nexport async function runWithConcurrency(\n  tasks: Array<() => Promise<void>>,\n  limit: number,\n): Promise<void> {\n  const executing = new Set<Promise<void>>();\n  for (const task of tasks) {\n    const p = task().then(() => {\n      executing.delete(p);\n    });\n    executing.add(p);\n    if (executing.size >= limit) {\n      await Promise.race(executing);\n    }\n  }\n  await Promise.all(executing);\n}\n\n// ========== verifySync ==========\n\n/**\n * Verify sync by sampling transferred files and comparing CIDs.\n *\n * Phase 3 change: instead of full buildManifest on dst, we sample\n * max(1, min(100, ceil(transferred/10))) files from the transferred set,\n * read each from dst, compute its CID, and compare against srcManifest CID.\n *\n * @param dstAfs          Destination AFS to read files from\n * @param transferredFiles FileFingerprints from srcManifest for transferred files\n */\nexport async function verifySync(\n  dstAfs: AFS,\n  transferredFiles: FileFingerprint[],\n): Promise<boolean> {\n  if (transferredFiles.length === 0) return true;\n\n  const sampleCount = computeSampleCount(transferredFiles.length);\n  const sample = sampleFiles(transferredFiles, sampleCount);\n\n  for (const srcFile of sample) {\n    // Only verify files that have a known CID — can't verify without reference\n    if (!srcFile.cid) continue;\n\n    try {\n      const readResult = await dstAfs.read(srcFile.path);\n      const rawContent = readResult.data?.content;\n      if (rawContent == null) return false;\n\n      const content = resolveContent(rawContent, readResult.data?.meta);\n      const dstCid = await computeCID(content);\n      if (dstCid !== srcFile.cid) return false;\n    } catch {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n// ========== syncDIDSpace ==========\n\nexport async function syncDIDSpace(\n  srcAfs: AFS,\n  dstAfs: AFS,\n  basePath: string,\n  options?: SyncOptions,\n): Promise<SyncResult> {\n  const startTime = Date.now();\n  const verify = options?.verify ?? true;\n\n  const progress: SyncProgress = {\n    phase: \"scanning\",\n    filesTotal: 0,\n    filesProcessed: 0,\n    bytesTotal: 0,\n    bytesTransferred: 0,\n    errors: [],\n    startedAt: startTime,\n    updatedAt: startTime,\n  };\n  options?.onProgress?.(progress);\n\n  // Phase 1: Snapshot (use remote manifest fetchers when provided)\n  let [srcManifest, dstManifest] = await Promise.all([\n    buildManifest(\n      srcAfs,\n      basePath,\n      options?.srcFetchManifest ? { fetchManifest: options.srcFetchManifest } : undefined,\n    ),\n    buildManifest(\n      dstAfs,\n      basePath,\n      options?.dstFetchManifest ? { fetchManifest: options.dstFetchManifest } : undefined,\n    ),\n  ]);\n\n  // Apply path filter if provided (e.g. exclude vault/db from sync)\n  if (options?.pathFilter) {\n    const pf = options.pathFilter;\n    srcManifest = { ...srcManifest, files: srcManifest.files.filter((f) => pf(f.path)) };\n    dstManifest = { ...dstManifest, files: dstManifest.files.filter((f) => pf(f.path)) };\n  }\n\n  // Phase 2: Diff\n  progress.phase = \"diffing\";\n  progress.updatedAt = Date.now();\n  options?.onProgress?.(progress);\n\n  const diff = computeDiff(srcManifest, dstManifest, options);\n\n  // Phase 3: Transfer\n  progress.phase = \"transferring\";\n  progress.filesTotal = diff.entries.filter((e) => e.reason !== \"deleted\").length;\n  progress.updatedAt = Date.now();\n  options?.onProgress?.(progress);\n\n  const { transferred, errors } = await transferFiles(srcAfs, dstAfs, diff, options);\n\n  // Phase 4: Verify — sample the transferred files\n  let verified = false;\n  if (verify && !options?.dryRun) {\n    progress.phase = \"verifying\";\n    progress.updatedAt = Date.now();\n    options?.onProgress?.(progress);\n\n    // Build the list of transferred file fingerprints from srcManifest\n    const transferredPaths = new Set(\n      diff.entries\n        .filter((e) => e.reason === \"added\" || e.reason === \"modified\")\n        .map((e) => e.path),\n    );\n    const transferredFiles = srcManifest.files.filter((f) => transferredPaths.has(f.path));\n    verified = await verifySync(dstAfs, transferredFiles);\n  }\n\n  progress.phase = errors.length > 0 ? \"failed\" : \"done\";\n  progress.updatedAt = Date.now();\n  options?.onProgress?.(progress);\n\n  return {\n    success: errors.length === 0,\n    diff,\n    transferred,\n    verified,\n    errors,\n    durationMs: Date.now() - startTime,\n  };\n}\n\n// ========== buildManifestFromDB (Phase 2) ==========\n\n/**\n * Build a manifest purely from `_metadata.db` (the index is the source of\n * truth after the Node backend moved to content-addressed storage, Phase 3).\n *\n * The old `reconcile({ rootPath })` FS-scan prelude is GONE: there is no\n * verbatim file tree to walk anymore — content lives at `objects/{cid}` and the\n * index already reflects every write (the provider writes entries atomically).\n * Reconciling against the CAS layout would mis-scan internal object files.\n * `rootPath` is retained in the signature for caller compatibility but unused.\n */\nasync function buildManifestFromDB(\n  metadataDb: MetadataDB,\n  _rootPath: string,\n  scope: string,\n  basePath: string,\n): Promise<SyncManifest> {\n  // Convert AFS basePath to DB path prefix\n  // AFS: \"/\" or \"/appDid\"  →  DB: undefined or \"appDid/\"\n  const dbBasePath = afsBasePathToDbPrefix(basePath);\n\n  const dbFiles = await metadataDb.getFiles(scope, dbBasePath);\n\n  const files: FileFingerprint[] = dbFiles.map((row) => ({\n    path: `/${row.path}`, // restore leading slash for AFS path convention\n    size: row.size,\n    cid: row.cid ?? undefined,\n    mtime: row.mtime,\n  }));\n\n  return { files, createdAt: Date.now() };\n}\n\n/**\n * Convert an AFS basePath to a MetadataDB path prefix.\n *\n * Examples:\n *   \"/\"          → undefined (match all)\n *   \"/appDid\"    → \"appDid/\"\n *   \"/appDid/\"   → \"appDid/\"\n */\nfunction afsBasePathToDbPrefix(basePath: string): string | undefined {\n  const stripped = basePath.replace(/^\\/+/, \"\").replace(/\\/*$/, \"\");\n  if (!stripped) return undefined;\n  return `${stripped}/`;\n}\n"],"mappings":"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"}