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

package/dist/d1-tree-index.mjs

@@ -0,0 +1,1094 @@
+import { CHANGELOG_INDEX_SQL, CHANGELOG_TABLE_SQL, PREFIX_WATERMARK_BUMP_SQL, PREFIX_WATERMARK_READ_SQL, PREFIX_WATERMARK_TABLE_SQL, SCOPE_META_FILE_COUNT_DELETE_ONE_SQL, SCOPE_META_FILE_COUNT_DELETE_RANGE_SQL, SCOPE_META_FILE_COUNT_TRIGGER_SQL, SCOPE_META_TABLE_SQL, SCOPE_META_TOTAL_BYTES_COLUMN_SQL, SCOPE_META_TOTAL_BYTES_DELETE_ONE_SQL, SCOPE_META_TOTAL_BYTES_DELETE_RANGE_SQL, SCOPE_META_TOTAL_BYTES_TRIGGER_SQL, watermarkPrefix, watermarkWritePrefix } from "./changelog-schema.mjs";
+import { resolveInlineConfig, resolveInlineContent } from "./inline-content.mjs";
+import { resolveParentDirStamp } from "./timestamp.mjs";
+import { STORAGE_QUOTA_EXCEEDED_CODE, buildKeysetCursor, buildOrderedQueryParts, parseTreeCursor, parseTreeEntryMetadata, serializeTreeEntryMetadata, storageQuotaError, treeEntryMetadataEqual } from "./tree-index.mjs";
+import { buildChildrenFrom, buildTreeQueryResultFromSql, buildTreeQueryStatements, mapAggregateRows } from "./tree-query.mjs";
+import { ENTRIES_CONTENT_TYPE_COLUMN_SQL, ENTRIES_CONTENT_TYPE_INDEX_DROP_SQL, ENTRIES_DEDUP_INDEX_SQL, ENTRIES_DEDUP_KEY_COLUMN_SQL, ENTRIES_DEDUP_SCOPE_COLUMN_SQL, ENTRIES_INDEX_SQL, ENTRIES_INLINE_CONTENT_COLUMN_SQL, ENTRIES_METADATA_COLUMN_SQL, ENTRIES_TABLE_SQL } from "./d1-schema.mjs";
+import { validateDeviceId } from "./changelog-write.mjs";
+import { prefixRange } from "./prefix-range.mjs";
+import { DIRTY_PATH_ACK_SQL, DIRTY_PATH_INDEX_SQL, DIRTY_PATH_LIST_SQL, DIRTY_PATH_MARK_ERROR_SQL, DIRTY_PATH_TABLE_SQL, DIRTY_PATH_TRIGGER_SQL } from "./dirty-path-schema.mjs";
+
+//#region src/d1-tree-index.ts
+/**
+* D1TreeIndex — D1 (SQLite) implementation of TreeIndex.
+*
+* Uses the `entries` table (v2 schema) with parent/name/kind columns
+* for efficient directory operations. WITHOUT ROWID for direct PK lookup.
+*
+* Each instance is scoped to a (scope) partition.
+*/
+/** Extract parent directory path from a file/dir path */
+function parentOf(path) {
+	if (!path) return "";
+	const clean = path.endsWith("/") ? path.slice(0, -1) : path;
+	const lastSlash = clean.lastIndexOf("/");
+	if (lastSlash <= 0) return "";
+	return clean.slice(0, lastSlash + 1);
+}
+/** Extract basename from a file/dir path */
+function nameOf(path) {
+	if (!path) return "";
+	const clean = path.endsWith("/") ? path.slice(0, -1) : path;
+	const lastSlash = clean.lastIndexOf("/");
+	return lastSlash < 0 ? clean : clean.slice(lastSlash + 1);
+}
+/** Collect all ancestor directory paths from a file path (deepest first) */
+function ancestorDirs(path) {
+	const dirs = [];
+	let current = path;
+	while (current.includes("/")) {
+		const slashIdx = current.lastIndexOf("/");
+		const dirPath = current.slice(0, slashIdx + 1);
+		if (!dirPath || dirPath === "/") break;
+		dirs.push(dirPath);
+		current = dirPath.slice(0, -1);
+	}
+	return dirs;
+}
+/**
+* Parent-dir-chain statements (Rule R2, feed-sort-createdat design §5.2).
+*
+* `DIR_INSERT_IGNORE_SQL` is the legacy "scaffold a dir if absent" — used for
+* the whole ancestor chain and for a direct parent whose write carries no
+* application `createdAt`. `DIR_STAMP_UPSERT_SQL` additionally overwrites the
+* existing dir row's ctime/mtime — used ONLY for the DIRECT parent when the
+* write carries a valid createdAt, so the feed's `orderBy ctime` (which sorts
+* the DIR row `e.ctime`) reflects the application createdAt. Both take the
+* SAME 6 binds: (scope, path, parent, name, ctime, mtime).
+*/
+const DIR_COLS = "(scope, path, parent, name, kind, size, ctime, mtime)";
+const DIR_INSERT_IGNORE_SQL = `INSERT OR IGNORE INTO ds_entries ${DIR_COLS}
+       VALUES (?, ?, ?, ?, 'dir', 0, ?, ?)`;
+const DIR_STAMP_UPSERT_SQL = `INSERT INTO ds_entries ${DIR_COLS}
+       VALUES (?, ?, ?, ?, 'dir', 0, ?, ?)
+       ON CONFLICT(scope, path) DO UPDATE SET ctime = excluded.ctime, mtime = excluded.mtime`;
+/**
+* Build the dir-chain statement for one `dirPath`: a Rule-R2 stamping UPSERT
+* when `stamp` is non-null (the direct parent of a createdAt-bearing write),
+* else the scaffold-only `INSERT OR IGNORE` at insert time `now`. Backend-
+* agnostic `{ sql, args }`; the D1 caller wraps with `prepare().bind()`, the
+* SQLite caller pushes it as-is.
+*/
+function buildDirChainStmt(scope, dirPath, stamp, now) {
+	const sql = stamp ? DIR_STAMP_UPSERT_SQL : DIR_INSERT_IGNORE_SQL;
+	const { ctime, mtime } = stamp ?? {
+		ctime: now,
+		mtime: now
+	};
+	return {
+		sql,
+		args: [
+			scope,
+			dirPath,
+			parentOf(dirPath),
+			nameOf(dirPath),
+			ctime,
+			mtime
+		]
+	};
+}
+/** Maximum file entries per scope (files only, excludes dirs) */
+const MAX_ENTRIES_PER_SCOPE = 1e6;
+/**
+* `isReferencedMany` IN-shard size for D1 (design §7.2, Finding 5). D1 caps a
+* query at 100 bound parameters. The three-way UNION binds each cid 3× plus
+* scope per branch (3 total), and 2 more per branch (lo/hi) when prefix-local:
+*   - whole-scope:  3N + 3      ≤ 100 → N ≤ 32
+*   - prefix-local: 3N + 3 + 6  ≤ 100 → N ≤ 30
+* 28 is the conservative single value covering both branches (never 30+).
+*/
+const D1_MANY_SHARD_SIZE = 28;
+var D1TreeIndex = class D1TreeIndex {
+	conn;
+	maxEntriesPerScope;
+	/** upload-limits Phase 5 byte quota (0 = disabled, the opt-in default). */
+	maxBytesPerScope;
+	inline;
+	constructor(db, scope, opts) {
+		this.db = db;
+		this.scope = scope;
+		this.conn = opts?.useReplica && typeof db.withSession === "function" ? db.withSession("first-unconstrained") : db;
+		this.maxEntriesPerScope = opts?.maxEntriesPerScope ?? MAX_ENTRIES_PER_SCOPE;
+		this.maxBytesPerScope = typeof opts?.maxBytesPerScope === "number" && opts.maxBytesPerScope > 0 ? opts.maxBytesPerScope : 0;
+		this.inline = resolveInlineConfig(opts);
+	}
+	/**
+	* Create entries table + indexes (v2 schema) AND the Phase 2 changelog table.
+	* Production: schema created by `wrangler d1 migrations apply`.
+	* Tests: call this in beforeEach with in-memory DB.
+	*
+	* Changelog DDL is sourced from `changelog-schema.ts` to keep the four
+	* runtimes (D1, desktop, Swift, Kotlin) byte-equivalent — see
+	* `scripts/check-changelog-ddl-parity.ts`. Schema-only here; producers come
+	* online in Task 2.4.
+	*/
+	async ensureTable() {
+		await this.db.batch([
+			this.db.prepare(ENTRIES_TABLE_SQL),
+			...ENTRIES_INDEX_SQL.map((sql) => this.db.prepare(sql)),
+			this.db.prepare(CHANGELOG_TABLE_SQL),
+			...CHANGELOG_INDEX_SQL.map((sql) => this.db.prepare(sql)),
+			this.db.prepare(SCOPE_META_TABLE_SQL),
+			...SCOPE_META_FILE_COUNT_TRIGGER_SQL.map((sql) => this.db.prepare(sql)),
+			this.db.prepare(PREFIX_WATERMARK_TABLE_SQL),
+			this.db.prepare(DIRTY_PATH_TABLE_SQL),
+			...DIRTY_PATH_INDEX_SQL.map((sql) => this.db.prepare(sql)),
+			...DIRTY_PATH_TRIGGER_SQL.map((sql) => this.db.prepare(sql))
+		]);
+		const { results } = await this.db.prepare("SELECT name FROM pragma_table_info('ds_entries')").all();
+		const colNames = new Set(results.map((r) => r.name));
+		if (!colNames.has("content")) try {
+			await this.db.prepare(ENTRIES_INLINE_CONTENT_COLUMN_SQL).run();
+		} catch (err) {
+			if (!(err instanceof Error ? err.message : String(err)).includes("duplicate column name")) throw err;
+		}
+		if (!colNames.has("metadata")) try {
+			await this.db.prepare(ENTRIES_METADATA_COLUMN_SQL).run();
+		} catch (err) {
+			if (!(err instanceof Error ? err.message : String(err)).includes("duplicate column name")) throw err;
+		}
+		if (!colNames.has("dedup_scope")) try {
+			await this.db.prepare(ENTRIES_DEDUP_SCOPE_COLUMN_SQL).run();
+		} catch (err) {
+			if (!(err instanceof Error ? err.message : String(err)).includes("duplicate column name")) throw err;
+		}
+		if (!colNames.has("dedup_key")) try {
+			await this.db.prepare(ENTRIES_DEDUP_KEY_COLUMN_SQL).run();
+		} catch (err) {
+			if (!(err instanceof Error ? err.message : String(err)).includes("duplicate column name")) throw err;
+		}
+		await this.db.prepare(ENTRIES_DEDUP_INDEX_SQL).run();
+		if (!colNames.has("content_type")) try {
+			await this.db.prepare(ENTRIES_CONTENT_TYPE_COLUMN_SQL).run();
+		} catch (err) {
+			if (!(err instanceof Error ? err.message : String(err)).includes("duplicate column name")) throw err;
+		}
+		await this.db.prepare(ENTRIES_CONTENT_TYPE_INDEX_DROP_SQL).run();
+		const scopeMetaCols = await this.db.prepare("SELECT name FROM pragma_table_info('ds_scope_meta')").all();
+		if (!new Set(scopeMetaCols.results.map((r) => r.name)).has("total_bytes")) try {
+			await this.db.prepare(SCOPE_META_TOTAL_BYTES_COLUMN_SQL).run();
+		} catch (err) {
+			if (!(err instanceof Error ? err.message : String(err)).includes("duplicate column name")) throw err;
+		}
+		await this.db.batch(SCOPE_META_TOTAL_BYTES_TRIGGER_SQL.map((sql) => this.db.prepare(sql)));
+	}
+	async get(path, opts) {
+		const contentCol = (opts?.includeContent ?? true) && this.inline.inlineCache === "on" ? ", content" : "";
+		const row = await this.conn.prepare(`SELECT cid, size, mtime, ctime, mime_type, metadata${contentCol} FROM ds_entries WHERE scope = ? AND path = ?`).bind(this.scope, path).first();
+		if (!row || !row.cid) return null;
+		const entry = {
+			cid: row.cid,
+			size: row.size,
+			mtime: row.mtime,
+			ctime: row.ctime,
+			mimeType: row.mime_type ?? void 0
+		};
+		if (row.content != null) entry.content = row.content;
+		const meta = parseTreeEntryMetadata(row.metadata);
+		if (meta) entry.metadata = meta;
+		return entry;
+	}
+	async getDirTimes(dirPath) {
+		const row = await this.conn.prepare("SELECT ctime, mtime FROM ds_entries WHERE scope = ? AND path = ?").bind(this.scope, dirPath).first();
+		return row ? {
+			ctime: row.ctime,
+			mtime: row.mtime
+		} : null;
+	}
+	/** Inline content this entry would store — parity with the loop reference impl. */
+	inlineForEntry(entry) {
+		return resolveInlineContent(entry, this.inline);
+	}
+	/** Point seek on the `(scope, dedup_scope, dedup_key)` partial UNIQUE index. */
+	async findByDedupKey(dedupScope, dedupKey) {
+		const row = await this.conn.prepare(`SELECT path, cid, size, mtime, ctime, mime_type, metadata
+         FROM ds_entries WHERE scope = ? AND dedup_scope = ? AND dedup_key = ? LIMIT 1`).bind(this.scope, dedupScope, dedupKey).first();
+		if (!row || !row.cid) return null;
+		const entry = {
+			path: row.path,
+			cid: row.cid,
+			size: row.size,
+			mtime: row.mtime,
+			ctime: row.ctime,
+			mimeType: row.mime_type ?? void 0
+		};
+		const meta = parseTreeEntryMetadata(row.metadata);
+		if (meta) entry.metadata = meta;
+		return entry;
+	}
+	/** Index-only backfill: set the dedup columns without touching content/changelog. */
+	async setDedupKey(path, dedupScope, dedupKey, opts) {
+		validateDeviceId(opts.deviceId);
+		await this.db.prepare("UPDATE ds_entries SET dedup_scope = ?, dedup_key = ? WHERE scope = ? AND path = ?").bind(dedupScope, dedupKey, this.scope, path).run();
+	}
+	/**
+	* Batch metadata read — one chunked `IN (…)` query per ≤90 paths (D1's
+	* 100-bind limit minus the scope bind, design §4.3). Result map carries an
+	* entry for EVERY requested path (`null` when absent), keyed verbatim.
+	*/
+	async getMany(paths) {
+		const map = /* @__PURE__ */ new Map();
+		for (const path of paths) map.set(path, null);
+		const contentCol = this.inline.inlineCache === "on" ? ", content" : "";
+		for (let offset = 0; offset < paths.length; offset += 90) {
+			const chunk = paths.slice(offset, offset + 90);
+			const { results } = await this.conn.prepare(`SELECT path, cid, size, mtime, ctime, mime_type, metadata${contentCol} FROM ds_entries
+           WHERE scope = ? AND kind = 'file' AND path IN (${chunk.map(() => "?").join(",")})`).bind(this.scope, ...chunk).all();
+			for (const row of results) {
+				if (!row.cid) continue;
+				const entry = {
+					cid: row.cid,
+					size: row.size,
+					mtime: row.mtime,
+					ctime: row.ctime,
+					mimeType: row.mime_type ?? void 0
+				};
+				if (row.content != null) entry.content = row.content;
+				const meta = parseTreeEntryMetadata(row.metadata);
+				if (meta) entry.metadata = meta;
+				map.set(row.path, entry);
+			}
+		}
+		return map;
+	}
+	/**
+	* Merged batch put (afs-rpc-batch §4.3 / §6.3) — the CF subrequest-budget
+	* fast path: ONE preread (caller-supplied or chunked IN), ONE capacity
+	* read, ONE atomic `db.batch` carrying every surviving entry's
+	* changelog+upsert (+1 watermark bump per write), then ONE watermark
+	* readback per distinct collection root to attribute per-entry seqs
+	* (`liveSeq[i] = final − N + 1 + i`, skip/conflict entries take no seq).
+	*
+	* Statement order inside the batch mirrors single `put`: dirs first, then
+	* per entry changelog INSERT (correlated old_cid subquery reads the
+	* pre-upsert cid) BEFORE its upsert — D1 preserves batch statement order.
+	*/
+	async batchPutEntries(entries, ctx) {
+		if (entries.length === 0) return [];
+		for (const e of entries) validateDeviceId(e.opts.deviceId);
+		const preread = ctx?.preread ?? await this.getMany(entries.map((e) => e.path));
+		const results = new Array(entries.length);
+		const live = [];
+		let newFileCount = 0;
+		for (let i = 0; i < entries.length; i++) {
+			const { path, entry, opts } = entries[i];
+			const existing = preread.get(path) ?? null;
+			if (opts.ifMatch !== void 0 && (!existing || existing.cid !== opts.ifMatch)) {
+				results[i] = {
+					path,
+					conflict: {
+						currentCid: existing?.cid ?? null,
+						currentMtime: existing?.mtime ?? null,
+						currentDeviceId: null
+					}
+				};
+				continue;
+			}
+			if (existing && existing.cid === entry.cid && existing.mimeType === entry.mimeType && treeEntryMetadataEqual(existing.metadata, entry.metadata)) {
+				if (this.inline.inlineCache !== "on") {
+					results[i] = {
+						path,
+						oldCid: existing.cid,
+						skipped: true
+					};
+					continue;
+				}
+				const wouldBeInline = await resolveInlineContent(entry, this.inline);
+				if ((existing.content ?? null) === wouldBeInline) {
+					results[i] = {
+						path,
+						oldCid: existing.cid,
+						skipped: true
+					};
+					continue;
+				}
+			}
+			if (!existing) newFileCount++;
+			live.push(i);
+		}
+		if (newFileCount > 0) {
+			const currentCount = await this.getScopeFileCount();
+			let remaining = this.maxEntriesPerScope - currentCount;
+			if (remaining < newFileCount) {
+				const surviving = [];
+				for (const i of live) if (!(preread.get(entries[i].path) ?? null)) if (remaining > 0) {
+					remaining--;
+					surviving.push(i);
+				} else results[i] = {
+					path: entries[i].path,
+					error: `Storage quota exceeded: scope "${this.scope}" has reached the ${this.maxEntriesPerScope} file limit`,
+					code: STORAGE_QUOTA_EXCEEDED_CODE
+				};
+				else surviving.push(i);
+				live.length = 0;
+				live.push(...surviving);
+			}
+		}
+		if (this.maxBytesPerScope > 0 && live.length > 0) {
+			const total = await this.getScopeTotalBytes();
+			let used = 0;
+			const surviving = [];
+			for (const i of live) {
+				const e = entries[i];
+				const newBytes = e.entry.size - (preread.get(e.path)?.size ?? 0);
+				if (newBytes > 0 && total + used + newBytes > this.maxBytesPerScope) results[i] = {
+					path: e.path,
+					error: `Storage quota exceeded: scope "${this.scope}" has reached the ${this.maxBytesPerScope}-byte limit`,
+					code: STORAGE_QUOTA_EXCEEDED_CODE
+				};
+				else {
+					if (newBytes > 0) used += newBytes;
+					surviving.push(i);
+				}
+			}
+			live.length = 0;
+			live.push(...surviving);
+		}
+		if (live.length === 0) return results;
+		const now = Date.now();
+		const stmts = [];
+		const dirStamps = /* @__PURE__ */ new Map();
+		const allDirs = /* @__PURE__ */ new Set();
+		for (const i of live) {
+			const path = entries[i].path;
+			const stamp = resolveParentDirStamp(entries[i].entry.metadata);
+			if (stamp) dirStamps.set(parentOf(path), stamp);
+			for (const dirPath of ancestorDirs(path)) {
+				if (allDirs.has(dirPath)) break;
+				allDirs.add(dirPath);
+			}
+		}
+		for (const dirPath of allDirs) {
+			const { sql, args } = buildDirChainStmt(this.scope, dirPath, dirStamps.get(dirPath) ?? null, now);
+			stmts.push(this.db.prepare(sql).bind(...args));
+		}
+		const writesByPrefix = /* @__PURE__ */ new Map();
+		for (const i of live) {
+			const { path, entry, opts } = entries[i];
+			stmts.push(this.db.prepare(`INSERT INTO ds_changelog (scope, path, op, cid, old_cid, size, mtime, device_id)
+             VALUES (?, ?, 'put', ?, (SELECT cid FROM ds_entries WHERE scope = ? AND path = ?), ?, ?, ?)`).bind(this.scope, path, entry.cid, this.scope, path, entry.size, entry.mtime, opts.deviceId));
+			stmts.push(await this.buildFileUpsert(path, entry));
+			const wmPrefix = watermarkWritePrefix(path);
+			if (wmPrefix !== null) {
+				stmts.push(this.db.prepare(PREFIX_WATERMARK_BUMP_SQL).bind(this.scope, wmPrefix));
+				const order = writesByPrefix.get(wmPrefix) ?? [];
+				order.push(i);
+				writesByPrefix.set(wmPrefix, order);
+			}
+		}
+		await this.db.batch(stmts);
+		for (const [wmPrefix, order] of writesByPrefix) {
+			const final = (await this.conn.prepare(PREFIX_WATERMARK_READ_SQL).bind(this.scope, wmPrefix).first())?.version ?? 0;
+			order.forEach((i, j) => {
+				const existing = preread.get(entries[i].path) ?? null;
+				results[i] = {
+					path: entries[i].path,
+					...existing ? { oldCid: existing.cid } : {},
+					liveSeq: final - order.length + 1 + j
+				};
+			});
+		}
+		for (const i of live) if (!results[i]) {
+			const existing = preread.get(entries[i].path) ?? null;
+			results[i] = {
+				path: entries[i].path,
+				...existing ? { oldCid: existing.cid } : {}
+			};
+		}
+		return results;
+	}
+	/**
+	* Merged batch delete — same shape as {@link batchPutEntries} without the
+	* R2 leg: ONE preread, ONE atomic `db.batch` (per entry: changelog INSERT
+	* SELECT + file_count decrement + DELETE, +1 watermark bump), then empty-
+	* parent cleanup over the DISTINCT ancestor chain. FILE entries only.
+	*/
+	async batchDeleteEntries(entries, ctx) {
+		if (entries.length === 0) return [];
+		for (const e of entries) validateDeviceId(e.opts.deviceId);
+		const preread = ctx?.preread ?? await this.getMany(entries.map((e) => e.path));
+		const results = new Array(entries.length);
+		const live = [];
+		for (let i = 0; i < entries.length; i++) {
+			const { path, opts } = entries[i];
+			const existing = preread.get(path) ?? null;
+			if (opts.ifMatch !== void 0 && (!existing || existing.cid !== opts.ifMatch)) {
+				results[i] = {
+					path,
+					conflict: {
+						currentCid: existing?.cid ?? null,
+						currentMtime: existing?.mtime ?? null,
+						currentDeviceId: null
+					}
+				};
+				continue;
+			}
+			if (!existing) {
+				results[i] = {
+					path,
+					notFound: true
+				};
+				continue;
+			}
+			live.push(i);
+		}
+		if (live.length === 0) return results;
+		const stmts = [];
+		const writesByPrefix = /* @__PURE__ */ new Map();
+		for (const i of live) {
+			const { path, opts } = entries[i];
+			stmts.push(this.db.prepare(`INSERT INTO ds_changelog (scope, path, op, cid, old_cid, size, mtime, device_id)
+             SELECT ?, ?, 'delete', NULL, cid, NULL, ?, ?
+             FROM ds_entries WHERE scope = ? AND path = ? AND cid IS NOT NULL`).bind(this.scope, path, opts.mtime ?? Date.now(), opts.deviceId, this.scope, path));
+			stmts.push(this.db.prepare(SCOPE_META_FILE_COUNT_DELETE_ONE_SQL).bind(this.scope, this.scope, path));
+			stmts.push(this.db.prepare(SCOPE_META_TOTAL_BYTES_DELETE_ONE_SQL).bind(this.scope, path, this.scope));
+			stmts.push(this.db.prepare("DELETE FROM ds_entries WHERE scope = ? AND path = ?").bind(this.scope, path));
+			const wmPrefix = watermarkWritePrefix(path);
+			if (wmPrefix !== null) {
+				stmts.push(this.db.prepare(PREFIX_WATERMARK_BUMP_SQL).bind(this.scope, wmPrefix));
+				const order = writesByPrefix.get(wmPrefix) ?? [];
+				order.push(i);
+				writesByPrefix.set(wmPrefix, order);
+			}
+		}
+		await this.db.batch(stmts);
+		for (const [wmPrefix, order] of writesByPrefix) {
+			const final = (await this.conn.prepare(PREFIX_WATERMARK_READ_SQL).bind(this.scope, wmPrefix).first())?.version ?? 0;
+			order.forEach((i, j) => {
+				results[i] = {
+					path: entries[i].path,
+					deletedCid: (preread.get(entries[i].path) ?? null)?.cid,
+					liveSeq: final - order.length + 1 + j
+				};
+			});
+		}
+		for (const i of live) if (!results[i]) results[i] = {
+			path: entries[i].path,
+			deletedCid: (preread.get(entries[i].path) ?? null)?.cid
+		};
+		const dirs = /* @__PURE__ */ new Set();
+		for (const i of live) for (const dirPath of ancestorDirs(entries[i].path)) dirs.add(dirPath);
+		const ordered = [...dirs].sort((a, b) => b.length - a.length);
+		for (const dirPath of ordered) {
+			if (await this.db.prepare("SELECT 1 FROM ds_entries WHERE scope = ? AND parent = ? LIMIT 1").bind(this.scope, dirPath).first()) continue;
+			await this.db.prepare("DELETE FROM ds_entries WHERE scope = ? AND path = ?").bind(this.scope, dirPath).run();
+		}
+		return results;
+	}
+	async put(path, entry, opts) {
+		validateDeviceId(opts.deviceId);
+		parentOf(path);
+		nameOf(path);
+		const now = Date.now();
+		const existing = await this.get(path);
+		if (existing && existing.cid === entry.cid && existing.mimeType === entry.mimeType && treeEntryMetadataEqual(existing.metadata, entry.metadata)) {
+			if (this.inline.inlineCache !== "on") return { oldCid: existing.cid };
+			const wouldBeInline = await resolveInlineContent(entry, this.inline);
+			if ((existing.content ?? null) === wouldBeInline) return { oldCid: existing.cid };
+		}
+		if (!existing) {
+			if (await this.getScopeFileCount() >= this.maxEntriesPerScope) throw storageQuotaError(`Storage quota exceeded: scope "${this.scope}" has reached the ${this.maxEntriesPerScope} file limit`);
+		}
+		if (this.maxBytesPerScope > 0) {
+			const newBytes = entry.size - (existing?.size ?? 0);
+			if (newBytes > 0) {
+				if (await this.getScopeTotalBytes() + newBytes > this.maxBytesPerScope) throw storageQuotaError(`Storage quota exceeded: scope "${this.scope}" has reached the ${this.maxBytesPerScope}-byte limit`);
+			}
+		}
+		const stmts = [];
+		const dirStamp = resolveParentDirStamp(entry.metadata);
+		const directParent = parentOf(path);
+		for (const dirPath of ancestorDirs(path)) {
+			const { sql, args } = buildDirChainStmt(this.scope, dirPath, dirStamp && dirPath === directParent ? dirStamp : null, now);
+			stmts.push(this.db.prepare(sql).bind(...args));
+		}
+		if (!opts.skipChangelog) stmts.push(this.db.prepare(`INSERT INTO ds_changelog (scope, path, op, cid, old_cid, size, mtime, device_id)
+             VALUES (?, ?, 'put', ?, (SELECT cid FROM ds_entries WHERE scope = ? AND path = ?), ?, ?, ?)`).bind(this.scope, path, entry.cid, this.scope, path, entry.size, entry.mtime, opts.deviceId));
+		stmts.push(await this.buildFileUpsert(path, entry));
+		if (!opts.skipChangelog) {
+			const wmPrefix = watermarkWritePrefix(path);
+			if (wmPrefix !== null) stmts.push(this.db.prepare(PREFIX_WATERMARK_BUMP_SQL).bind(this.scope, wmPrefix));
+		}
+		await this.db.batch(stmts);
+		return { oldCid: existing?.cid };
+	}
+	/**
+	* Build the file-row UPSERT. Inline-enabled indexes always write the
+	* content column (inline copy or NULL — an overwrite without inline content
+	* MUST clear any prior copy so the column never goes stale relative to the
+	* new cid); default-off indexes keep the byte-identical legacy statement
+	* (and never touch a not-yet-migrated database's missing column).
+	*/
+	async buildFileUpsert(path, entry) {
+		const metadataValue = serializeTreeEntryMetadata(entry.metadata);
+		const dedupScopeValue = entry.dedupScope ?? null;
+		const dedupKeyValue = entry.dedupKey ?? null;
+		if (this.inline.inlineCache !== "on") return this.db.prepare(`INSERT INTO ds_entries (scope, path, parent, name, kind, cid, size, mime_type, ctime, mtime, metadata, dedup_scope, dedup_key)
+           VALUES (?, ?, ?, ?, 'file', ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(scope, path) DO UPDATE SET
+             cid = excluded.cid,
+             size = excluded.size,
+             mtime = excluded.mtime,
+             mime_type = excluded.mime_type,
+             metadata = excluded.metadata,
+             dedup_scope = COALESCE(excluded.dedup_scope, ds_entries.dedup_scope),
+             dedup_key = COALESCE(excluded.dedup_key, ds_entries.dedup_key)`).bind(this.scope, path, parentOf(path), nameOf(path), entry.cid, entry.size, entry.mimeType ?? null, entry.ctime, entry.mtime, metadataValue, dedupScopeValue, dedupKeyValue);
+		const inlineContent = await resolveInlineContent(entry, this.inline);
+		return this.db.prepare(`INSERT INTO ds_entries (scope, path, parent, name, kind, cid, size, mime_type, ctime, mtime, content, metadata, dedup_scope, dedup_key)
+         VALUES (?, ?, ?, ?, 'file', ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(scope, path) DO UPDATE SET
+           cid = excluded.cid,
+           size = excluded.size,
+           mtime = excluded.mtime,
+           mime_type = excluded.mime_type,
+           content = excluded.content,
+           metadata = excluded.metadata,
+           dedup_scope = COALESCE(excluded.dedup_scope, ds_entries.dedup_scope),
+           dedup_key = COALESCE(excluded.dedup_key, ds_entries.dedup_key)`).bind(this.scope, path, parentOf(path), nameOf(path), entry.cid, entry.size, entry.mimeType ?? null, entry.ctime, entry.mtime, inlineContent, metadataValue, dedupScopeValue, dedupKeyValue);
+	}
+	async delete(path, opts) {
+		validateDeviceId(opts.deviceId);
+		const stmts = [];
+		if (!opts.skipChangelog) stmts.push(this.db.prepare(`INSERT INTO ds_changelog (scope, path, op, cid, old_cid, size, mtime, device_id)
+             SELECT ?, ?, 'delete', NULL, cid, NULL, ?, ?
+             FROM ds_entries WHERE scope = ? AND path = ? AND cid IS NOT NULL`).bind(this.scope, path, opts.mtime ?? Date.now(), opts.deviceId, this.scope, path));
+		stmts.push(this.db.prepare(SCOPE_META_FILE_COUNT_DELETE_ONE_SQL).bind(this.scope, this.scope, path));
+		stmts.push(this.db.prepare(SCOPE_META_TOTAL_BYTES_DELETE_ONE_SQL).bind(this.scope, path, this.scope));
+		stmts.push(this.db.prepare("DELETE FROM ds_entries WHERE scope = ? AND path = ?").bind(this.scope, path));
+		if (!opts.skipChangelog) {
+			const wmPrefix = watermarkWritePrefix(path);
+			if (wmPrefix !== null) stmts.push(this.db.prepare(PREFIX_WATERMARK_BUMP_SQL).bind(this.scope, wmPrefix));
+		}
+		await this.db.batch(stmts);
+		await this.cleanEmptyParents(path);
+	}
+	/** Walk up parent chain, removing directory entries that have no remaining children */
+	async cleanEmptyParents(path) {
+		for (const dirPath of ancestorDirs(path)) {
+			if (await this.db.prepare("SELECT 1 FROM ds_entries WHERE scope = ? AND parent = ? LIMIT 1").bind(this.scope, dirPath).first()) break;
+			await this.db.prepare("DELETE FROM ds_entries WHERE scope = ? AND path = ?").bind(this.scope, dirPath).run();
+		}
+	}
+	static VALID_ORDER_BY = {
+		path: "path",
+		mtime: "mtime",
+		size: "size",
+		ctime: "ctime",
+		mimeType: "mime_type",
+		name: "name"
+	};
+	/** The only nullable sortable column — NULLs sort last (see tree-index.ts). */
+	static NULLABLE_ORDER_COLUMNS = new Set(["mime_type"]);
+	async list(prefix, options) {
+		const limit = options?.limit ?? 1e3;
+		const orderByKey = options?.orderBy ?? "path";
+		const order = options?.order ?? "asc";
+		const cursor = options?.cursor;
+		const col = D1TreeIndex.VALID_ORDER_BY[orderByKey];
+		if (!col) throw new Error(`Invalid orderBy: ${orderByKey}`);
+		if (limit === 0) return {
+			entries: [],
+			hasMore: false
+		};
+		const [lo, hi] = prefixRange(prefix);
+		const params = [
+			this.scope,
+			lo,
+			hi
+		];
+		let sql = `SELECT path, ${col} as _sort FROM ds_entries WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file'`;
+		if (cursor) {
+			sql += ` AND ${col} ${order === "asc" ? ">" : "<"} ?`;
+			params.push(cursor);
+		}
+		sql += ` ORDER BY ${col} ${order} LIMIT ?`;
+		params.push(limit + 1);
+		const { results } = await this.conn.prepare(sql).bind(...params).all();
+		const hasMore = results.length > limit;
+		const selected = hasMore ? results.slice(0, limit) : results;
+		return {
+			entries: selected.map((r) => ({ path: r.path })),
+			hasMore,
+			cursor: hasMore && selected.length > 0 ? String(selected[selected.length - 1]._sort) : void 0
+		};
+	}
+	async listEntries(prefix, options) {
+		const limit = options?.limit ?? 1e3;
+		const hasOrderBy = options?.orderBy !== void 0;
+		const orderByKey = options?.orderBy ?? "path";
+		const order = options?.order === "desc" ? "desc" : "asc";
+		const col = D1TreeIndex.VALID_ORDER_BY[orderByKey];
+		if (!col) throw new Error(`Invalid orderBy: ${orderByKey}`);
+		if (limit === 0) return {
+			entries: [],
+			hasMore: false
+		};
+		const parsed = parseTreeCursor(options?.cursor, hasOrderBy);
+		const [lo, hi] = prefixRange(prefix);
+		const params = [
+			this.scope,
+			lo,
+			hi
+		];
+		let sql = `SELECT path, cid, size, mtime, ctime, mime_type${options?.includeContent ? ", content" : ""}, ${col} as _sort FROM ds_entries${col === "path" ? " INDEXED BY idx_entries_kind" : ""} WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file'`;
+		if (hasOrderBy) {
+			const parts = buildOrderedQueryParts({
+				col,
+				nullable: D1TreeIndex.NULLABLE_ORDER_COLUMNS.has(col),
+				order,
+				tieCol: "path",
+				cursor: parsed.kind === "v2" ? parsed.cursor : void 0
+			});
+			if (parts.cursorWhereSql) {
+				sql += ` AND ${parts.cursorWhereSql}`;
+				params.push(...parts.cursorArgs);
+			}
+			sql += ` ORDER BY ${parts.orderSql} LIMIT ?`;
+		} else {
+			if (parsed.kind === "legacy") {
+				sql += ` AND ${col} ${order === "asc" ? ">" : "<"} ?`;
+				params.push(parsed.value);
+			}
+			sql += ` ORDER BY ${col} ${order} LIMIT ?`;
+		}
+		params.push(limit + 1);
+		const { results } = await this.conn.prepare(sql).bind(...params).all();
+		const hasMore = results.length > limit;
+		const selected = hasMore ? results.slice(0, limit) : results;
+		const last = selected[selected.length - 1];
+		return {
+			entries: selected.map((r) => {
+				const e = {
+					path: r.path,
+					cid: r.cid,
+					size: r.size,
+					mtime: r.mtime,
+					ctime: r.ctime,
+					mimeType: r.mime_type ?? void 0
+				};
+				if (options?.includeContent && r.content != null) e.content = r.content;
+				return e;
+			}),
+			hasMore,
+			cursor: !hasMore || !last ? void 0 : hasOrderBy ? buildKeysetCursor(last._sort ?? null, last.path) : String(last._sort)
+		};
+	}
+	async hasChildren(prefix) {
+		const [lo, hi] = prefixRange(prefix);
+		return await this.conn.prepare("SELECT 1 FROM ds_entries WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file' LIMIT 1").bind(this.scope, lo, hi).first() !== null;
+	}
+	async getAndHasChildren(filePath, dirPrefix) {
+		const contentCol = this.inline.inlineCache === "on" ? ", content" : "";
+		const [lo, hi] = prefixRange(dirPrefix);
+		const batchResults = await this.db.batch([this.db.prepare(`SELECT cid, size, mtime, ctime, mime_type, metadata${contentCol} FROM ds_entries WHERE scope = ? AND path = ?`).bind(this.scope, filePath), this.db.prepare("SELECT 1 FROM ds_entries WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file' LIMIT 1").bind(this.scope, lo, hi)]);
+		const getResult = batchResults[0];
+		const hasChildResult = batchResults[1];
+		const row = getResult.results[0];
+		let entry = null;
+		if (row?.cid) {
+			entry = {
+				cid: row.cid,
+				size: row.size,
+				mtime: row.mtime,
+				ctime: row.ctime,
+				mimeType: row.mime_type ?? void 0
+			};
+			if (row.content != null) entry.content = row.content;
+			const meta = parseTreeEntryMetadata(row.metadata);
+			if (meta) entry.metadata = meta;
+		}
+		return [entry, (hasChildResult.results?.length ?? 0) > 0];
+	}
+	async count(prefix) {
+		const [lo, hi] = prefixRange(prefix);
+		return (await this.conn.prepare("SELECT COUNT(*) as cnt FROM ds_entries WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file'").bind(this.scope, lo, hi).first())?.cnt ?? 0;
+	}
+	/**
+	* O(1) read of the trigger-maintained file count for this scope, used by the
+	* `put()` capacity guard. A missing `scope_meta` row means "no files counted
+	* yet" → 0, which is also the correct answer for a brand-new scope and the
+	* safe (permissive) fallback for a scope not yet backfilled. This replaces
+	* the per-write full-scope `count("")` scan — the source of the O(N²)
+	* `rows_read` blow-up that exhausted the D1 free tier during bulk sync.
+	*/
+	async getScopeFileCount() {
+		return (await this.conn.prepare("SELECT file_count FROM ds_scope_meta WHERE scope = ?").bind(this.scope).first())?.file_count ?? 0;
+	}
+	/**
+	* O(1) read of the trigger-maintained byte total for this scope, used by the
+	* Phase 5 byte-quota guard (only when `maxBytesPerScope > 0`). Same O(1)
+	* contract as {@link getScopeFileCount} — never a `SELECT SUM(size)` scan.
+	* Missing row → 0 (new/un-backfilled scope; permissive).
+	*/
+	async getScopeTotalBytes() {
+		return (await this.conn.prepare("SELECT total_bytes FROM ds_scope_meta WHERE scope = ?").bind(this.scope).first())?.total_bytes ?? 0;
+	}
+	async getCompactedBelowSeq() {
+		return (await this.conn.prepare("SELECT compacted_below_seq FROM ds_scope_meta WHERE scope = ?").bind(this.scope).first())?.compacted_below_seq ?? 0;
+	}
+	async deleteByPrefix(prefix, opts) {
+		validateDeviceId(opts.deviceId);
+		const [lo, hi] = prefixRange(prefix);
+		const stmts = [];
+		if (!opts.skipChangelog) {
+			const now = opts.mtime ?? Date.now();
+			stmts.push(this.db.prepare(`INSERT INTO ds_changelog (scope, path, op, cid, old_cid, size, mtime, device_id)
+             SELECT ?, path, 'delete', NULL, cid, NULL, ?, ?
+             FROM ds_entries INDEXED BY idx_entries_kind
+             WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file' AND cid IS NOT NULL`).bind(this.scope, now, opts.deviceId, this.scope, lo, hi));
+		}
+		stmts.push(this.db.prepare(SCOPE_META_FILE_COUNT_DELETE_RANGE_SQL).bind(this.scope, lo, hi, this.scope));
+		stmts.push(this.db.prepare(SCOPE_META_TOTAL_BYTES_DELETE_RANGE_SQL).bind(this.scope, lo, hi, this.scope));
+		if (!opts.skipChangelog) {
+			const wmPrefix = watermarkPrefix(prefix);
+			if (wmPrefix !== null) stmts.push(this.db.prepare(PREFIX_WATERMARK_BUMP_SQL).bind(this.scope, wmPrefix));
+		}
+		stmts.push(this.db.prepare("DELETE FROM ds_entries WHERE scope = ? AND path >= ? AND path < ?").bind(this.scope, lo, hi));
+		const batchResults = await this.db.batch(stmts);
+		return batchResults[batchResults.length - 1].meta.changes;
+	}
+	async listChildren(parent, options) {
+		const limit = options?.limit ?? 1e3;
+		const order = options?.order === "desc" ? "desc" : "asc";
+		if (limit === 0) return {
+			entries: [],
+			hasMore: false
+		};
+		const hasOrderBy = options?.orderBy !== void 0;
+		const parsed = parseTreeCursor(options?.cursor, hasOrderBy);
+		const params = [this.scope, parent];
+		const includeContent = options?.includeContent === true;
+		const t = "e.";
+		const from = buildChildrenFrom(void 0);
+		const fromClause = from.sql;
+		const contentCol = includeContent ? `, ${t}content` : "";
+		params.unshift(...from.args);
+		const mapChild = (r) => {
+			const e = {
+				path: r.path,
+				cid: r.cid ?? "",
+				size: r.size,
+				mtime: r.mtime,
+				ctime: r.ctime,
+				mimeType: r.mime_type ?? void 0
+			};
+			if (includeContent && r.content != null) e.content = r.content;
+			return e;
+		};
+		if (hasOrderBy) {
+			const col = D1TreeIndex.VALID_ORDER_BY[options.orderBy];
+			if (!col) throw new Error(`Invalid orderBy: ${options?.orderBy}`);
+			const parts = buildOrderedQueryParts({
+				col: `${t}${col}`,
+				nullable: D1TreeIndex.NULLABLE_ORDER_COLUMNS.has(col),
+				order,
+				tieCol: `${t}name`,
+				cursor: parsed.kind === "v2" ? parsed.cursor : void 0
+			});
+			let sql$1 = `SELECT ${t}path, ${t}cid, ${t}size, ${t}mtime, ${t}ctime, ${t}mime_type, ${t}name${contentCol}, ${t}${col} as _sort ${fromClause} WHERE ${t}scope = ? AND ${t}parent = ?`;
+			if (parts.cursorWhereSql) {
+				sql$1 += ` AND ${parts.cursorWhereSql}`;
+				params.push(...parts.cursorArgs);
+			}
+			sql$1 += ` ORDER BY ${parts.orderSql} LIMIT ?`;
+			params.push(limit + 1);
+			const { results: results$1 } = await this.conn.prepare(sql$1).bind(...params).all();
+			const hasMore$1 = results$1.length > limit;
+			const selected$1 = hasMore$1 ? results$1.slice(0, limit) : results$1;
+			const last = selected$1[selected$1.length - 1];
+			return {
+				entries: selected$1.map(mapChild),
+				hasMore: hasMore$1,
+				cursor: hasMore$1 && last ? buildKeysetCursor(last._sort ?? null, last.name) : void 0
+			};
+		}
+		let sql = `SELECT ${t}path, ${t}cid, ${t}size, ${t}mtime, ${t}ctime, ${t}mime_type, ${t}name${contentCol}, ${t}name as _sort ${fromClause} WHERE ${t}scope = ? AND ${t}parent = ?`;
+		if (parsed.kind === "legacy") {
+			sql += ` AND ${t}name ${order === "asc" ? ">" : "<"} ?`;
+			params.push(parsed.value);
+		}
+		sql += ` ORDER BY ${t}name ${order} LIMIT ?`;
+		params.push(limit + 1);
+		const { results } = await this.conn.prepare(sql).bind(...params).all();
+		const hasMore = results.length > limit;
+		const selected = hasMore ? results.slice(0, limit) : results;
+		return {
+			entries: selected.map(mapChild),
+			hasMore,
+			cursor: hasMore && selected.length > 0 ? String(selected[selected.length - 1].name) : void 0
+		};
+	}
+	async countChildren(parent) {
+		return (await this.conn.prepare("SELECT COUNT(*) as cnt FROM ds_entries WHERE scope = ? AND parent = ?").bind(this.scope, parent).first())?.cnt ?? 0;
+	}
+	/**
+	* Collection query (afs-collection-query Phase 2) — same shared compiler +
+	* result builder as SQLiteTreeIndex (tree-query.ts), executed over the
+	* replica-aware `this.conn`: query is read-class and follows the SAME
+	* replica routing policy as list (AFS_D1_READ_REPLICA gate upstream picks
+	* the session; no separate consistency standard — design T2.1).
+	*/
+	async query(parent, spec) {
+		const statements = buildTreeQueryStatements({
+			scope: this.scope,
+			parent,
+			spec
+		});
+		if (statements.aggregate) {
+			const [aggRes, countRow$1] = await Promise.all([this.conn.prepare(statements.aggregate.select.sql).bind(...statements.aggregate.select.args).all(), this.conn.prepare(statements.aggregate.countGroups.sql).bind(...statements.aggregate.countGroups.args).first()]);
+			const aggregateGroups = mapAggregateRows(aggRes.results, statements.aggregate.groupKeys, statements.aggregate.aggregations);
+			return {
+				rows: [],
+				total: statements.aggregate.groupKeys.length === 0 ? 1 : countRow$1?.cnt ?? 0,
+				aggregateGroups
+			};
+		}
+		const [rowsRes, countRow, groupsRes, seekRow] = await Promise.all([
+			this.conn.prepare(statements.rows.sql).bind(...statements.rows.args).all(),
+			statements.count ? this.conn.prepare(statements.count.sql).bind(...statements.count.args).first() : Promise.resolve(void 0),
+			statements.groups ? this.conn.prepare(statements.groups.sql).bind(...statements.groups.args).all() : Promise.resolve(void 0),
+			statements.seek ? this.conn.prepare(statements.seek.sql).bind(...statements.seek.args).first() : Promise.resolve(void 0)
+		]);
+		const seekOffset = statements.seek ? seekRow?.rn ?? -1 : void 0;
+		return buildTreeQueryResultFromSql({
+			rawRows: rowsRes.results,
+			total: statements.count ? countRow?.cnt ?? 0 : -1,
+			groupRows: groupsRes?.results,
+			spec,
+			orderField: statements.order.field,
+			seekOffset
+		});
+	}
+	/**
+	* Page-bounded grouped child counts: ONE chunked `parent IN (…)` aggregate
+	* per ≤90 parents (D1's 100-bind limit minus the scope bind — same chunking
+	* as `getMany`), index-only seeks on `idx_entries_children(scope, parent,
+	* name)`. rows_read is bounded by the listed page's direct grandchildren.
+	*
+	* Predecessor (`countChildrenGrouped(prefix)`) used a `parent >= lo AND
+	* parent < hi` range — a scan/group over EVERY descendant under the listed
+	* prefix on EVERY list. Once the aside user space grew to ~1.8k dirs, each
+	* list of any ancestor dir read ~3.8k rows; at list frequency that burned
+	* ~100M D1 rows_read/day (42× the free tier).
+	*/
+	async countChildrenMany(parents) {
+		const map = /* @__PURE__ */ new Map();
+		for (let offset = 0; offset < parents.length; offset += 90) {
+			const chunk = parents.slice(offset, offset + 90);
+			const { results } = await this.conn.prepare(`SELECT parent, COUNT(*) as cnt FROM ds_entries WHERE scope = ? AND parent IN (${chunk.map(() => "?").join(",")}) GROUP BY parent`).bind(this.scope, ...chunk).all();
+			for (const row of results) map.set(row.parent, row.cnt);
+		}
+		return map;
+	}
+	async aggregate(prefix) {
+		const [lo, hi] = prefixRange(prefix);
+		const row = await this.conn.prepare(`SELECT COUNT(*) as file_count, COALESCE(SUM(size), 0) as total_size
+         FROM ds_entries INDEXED BY idx_entries_kind WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file'`).bind(this.scope, lo, hi).first();
+		return {
+			fileCount: row?.file_count ?? 0,
+			totalSize: row?.total_size ?? 0
+		};
+	}
+	async putBatch(entries, opts) {
+		if (entries.length === 0) return;
+		validateDeviceId(opts.deviceId);
+		const now = Date.now();
+		const stmts = [];
+		const dirStamps = /* @__PURE__ */ new Map();
+		const allDirs = /* @__PURE__ */ new Set();
+		for (const { path, entry } of entries) {
+			const stamp = resolveParentDirStamp(entry.metadata);
+			if (stamp) dirStamps.set(parentOf(path), stamp);
+			for (const dirPath of ancestorDirs(path)) {
+				if (allDirs.has(dirPath)) break;
+				allDirs.add(dirPath);
+			}
+		}
+		for (const dirPath of allDirs) {
+			const { sql, args } = buildDirChainStmt(this.scope, dirPath, dirStamps.get(dirPath) ?? null, now);
+			stmts.push(this.db.prepare(sql).bind(...args));
+		}
+		for (const { path, entry } of entries) {
+			if (!opts.skipChangelog) stmts.push(this.db.prepare(`INSERT INTO ds_changelog (scope, path, op, cid, old_cid, size, mtime, device_id)
+               VALUES (?, ?, 'put', ?, (SELECT cid FROM ds_entries WHERE scope = ? AND path = ?), ?, ?, ?)`).bind(this.scope, path, entry.cid, this.scope, path, entry.size, entry.mtime, opts.deviceId));
+			stmts.push(await this.buildFileUpsert(path, entry));
+		}
+		if (!opts.skipChangelog) {
+			const wmPrefixes = /* @__PURE__ */ new Set();
+			for (const { path } of entries) {
+				const wmPrefix = watermarkWritePrefix(path);
+				if (wmPrefix !== null) wmPrefixes.add(wmPrefix);
+			}
+			for (const wmPrefix of wmPrefixes) stmts.push(this.db.prepare(PREFIX_WATERMARK_BUMP_SQL).bind(this.scope, wmPrefix));
+		}
+		await this.db.batch(stmts);
+	}
+	/**
+	* Read the per-prefix watermark version (Live Update Resilience §11.4).
+	* Reduces `prefix` to its first path segment (collection root) and returns
+	* that row's `version`, or 0 when no row exists. Replica-aware via `this.conn`
+	* — but reconcile passes a primary-pinned index for read-your-watermark
+	* (DEC-5; see CloudflareDIDSpace.getInstanceSpace consistency option).
+	*/
+	async getPrefixWatermark(prefix) {
+		const wmPrefix = watermarkPrefix(prefix);
+		if (wmPrefix === null) return null;
+		return (await this.conn.prepare(PREFIX_WATERMARK_READ_SQL).bind(this.scope, wmPrefix).first())?.version ?? 0;
+	}
+	async listModifiedSince(prefix, since, options) {
+		const limit = options?.limit ?? 1e3;
+		const order = options?.order ?? "asc";
+		const cursor = options?.cursor;
+		if (limit === 0) return {
+			entries: [],
+			hasMore: false
+		};
+		const [lo, hi] = prefixRange(prefix);
+		const params = [
+			this.scope,
+			lo,
+			hi,
+			since
+		];
+		let sql = `SELECT path, cid, size, mtime, ctime, mime_type FROM ds_entries INDEXED BY idx_entries_kind
+               WHERE scope = ? AND path >= ? AND path < ? AND mtime > ? AND kind = 'file'`;
+		if (cursor) {
+			sql += ` AND path ${order === "asc" ? ">" : "<"} ?`;
+			params.push(cursor);
+		}
+		sql += ` ORDER BY path ${order} LIMIT ?`;
+		params.push(limit + 1);
+		const { results } = await this.conn.prepare(sql).bind(...params).all();
+		const hasMore = results.length > limit;
+		const selected = hasMore ? results.slice(0, limit) : results;
+		return {
+			entries: selected.map((r) => ({
+				path: r.path,
+				cid: r.cid,
+				size: r.size,
+				mtime: r.mtime,
+				ctime: r.ctime,
+				mimeType: r.mime_type ?? void 0
+			})),
+			hasMore,
+			cursor: hasMore && selected.length > 0 ? String(selected[selected.length - 1].path) : void 0
+		};
+	}
+	async getMaxSeq() {
+		const [row, compactedBelow] = await Promise.all([this.conn.prepare("SELECT MAX(seq) as maxSeq FROM ds_changelog WHERE scope = ?").bind(this.scope).first(), this.getCompactedBelowSeq()]);
+		return Math.max(row?.maxSeq ?? 0, compactedBelow);
+	}
+	/**
+	* Read-auth reference check (design §4.1) — three-way, scoped, optionally
+	* prefix-local. See {@link TreeIndex.isReferenced}.
+	*/
+	async isReferenced(cid, pathPrefix = "") {
+		if (!cid) return false;
+		if (pathPrefix === "") return await this.conn.prepare(`SELECT 1 FROM (
+             SELECT 1 FROM ds_entries   WHERE scope = ? AND cid     = ?
+             UNION ALL
+             SELECT 1 FROM ds_changelog WHERE scope = ? AND cid     = ?
+             UNION ALL
+             SELECT 1 FROM ds_changelog WHERE scope = ? AND old_cid = ?
+           ) LIMIT 1`).bind(this.scope, cid, this.scope, cid, this.scope, cid).first() !== null;
+		const [lo, hi] = prefixRange(pathPrefix);
+		return await this.conn.prepare(`SELECT 1 FROM (
+           SELECT 1 FROM ds_entries   WHERE scope = ? AND cid     = ? AND path >= ? AND path < ?
+           UNION ALL
+           SELECT 1 FROM ds_changelog WHERE scope = ? AND cid     = ? AND path >= ? AND path < ?
+           UNION ALL
+           SELECT 1 FROM ds_changelog WHERE scope = ? AND old_cid = ? AND path >= ? AND path < ?
+         ) LIMIT 1`).bind(this.scope, cid, lo, hi, this.scope, cid, lo, hi, this.scope, cid, lo, hi).first() !== null;
+	}
+	/**
+	* Batch read-auth (design §7.2 / §14) — three-way-equivalent to per-cid
+	* {@link isReferenced}, sharded under D1's 100-param cap (see
+	* {@link D1_MANY_SHARD_SIZE}). Returns the referenced subset of `cids`.
+	*/
+	async isReferencedMany(cids, pathPrefix = "") {
+		const referenced = /* @__PURE__ */ new Set();
+		const unique = [...new Set(cids.filter((c) => c))];
+		if (unique.length === 0) return referenced;
+		const usePrefix = pathPrefix !== "";
+		const [lo, hi] = usePrefix ? prefixRange(pathPrefix) : ["", ""];
+		for (let i = 0; i < unique.length; i += D1_MANY_SHARD_SIZE) {
+			const shard = unique.slice(i, i + D1_MANY_SHARD_SIZE);
+			const ph = shard.map(() => "?").join(",");
+			const tail = usePrefix ? "AND path >= ? AND path < ?" : "";
+			const sql = `SELECT cid     AS c FROM ds_entries   WHERE scope = ? AND cid     IN (${ph}) ${tail}
+                   UNION
+                   SELECT cid     AS c FROM ds_changelog WHERE scope = ? AND cid     IN (${ph}) ${tail}
+                   UNION
+                   SELECT old_cid AS c FROM ds_changelog WHERE scope = ? AND old_cid IN (${ph}) ${tail}`;
+			const bind = [];
+			for (let b = 0; b < 3; b++) {
+				bind.push(this.scope, ...shard);
+				if (usePrefix) bind.push(lo, hi);
+			}
+			const { results } = await this.conn.prepare(sql).bind(...bind).all();
+			for (const row of results) if (row.c) referenced.add(row.c);
+		}
+		return referenced;
+	}
+	async getChangelogSince(sinceSeq, limit) {
+		const safeLimit = limit > 0 ? limit : 0;
+		if (safeLimit === 0) return {
+			entries: [],
+			hasMore: false,
+			cursor: sinceSeq
+		};
+		const { results } = await this.conn.prepare(`SELECT seq, scope, path, op, cid, old_cid, size, mtime, device_id
+         FROM ds_changelog WHERE scope = ? AND seq > ? ORDER BY seq ASC LIMIT ?`).bind(this.scope, sinceSeq, safeLimit + 1).all();
+		const hasMore = results.length > safeLimit;
+		const page = hasMore ? results.slice(0, safeLimit) : results;
+		return {
+			entries: page,
+			hasMore,
+			cursor: page.length > 0 ? page[page.length - 1].seq : sinceSeq
+		};
+	}
+	/**
+	* Ready dirty rows under `prefix` for this scope. `next_attempt_at <= now`
+	* skips poison rows still in backoff; the `(scope, next_attempt_at,
+	* updated_at)` index serves the ordered seek. Reads go through `this.conn`, so
+	* a follower constructed primary-bound (`useReplica:false`, Phase 3) gets
+	* read-your-write; a replica-routed instance would return replica state — the
+	* runtime is responsible for pinning primary for the dirty follower.
+	*/
+	async listDirtyPaths(options) {
+		const now = options.now ?? Date.now();
+		const limit = options.limit > 0 ? options.limit : 0;
+		if (limit === 0) return [];
+		const [lo, hi] = prefixRange(options.prefix);
+		const { results } = await this.conn.prepare(DIRTY_PATH_LIST_SQL).bind(this.scope, lo, hi, now, limit).all();
+		return results.map((r) => ({
+			path: r.path,
+			latestSeq: Number(r.latest_seq),
+			op: r.op,
+			cid: r.cid,
+			mtime: Number(r.mtime),
+			attempts: Number(r.attempts)
+		}));
+	}
+	/**
+	* Guarded ack (design §8): delete the dirty row ONLY if its `latest_seq` is
+	* still the one we processed. A concurrent write bumps latest_seq (trigger),
+	* so a stale worker's DELETE affects 0 rows → returns false, and the newer
+	* dirty row survives for the next tick. Writes go to primary (`this.db`).
+	*/
+	async ackDirtyPath(path, latestSeq) {
+		return ((await this.db.prepare(DIRTY_PATH_ACK_SQL).bind(this.scope, path, latestSeq).run()).meta?.changes ?? 0) > 0;
+	}
+	/**
+	* Guarded failure record (design §8): bump attempts, stamp last_error +
+	* next_attempt_at, SAME `latest_seq` guard so a fresh write's reset (trigger
+	* sets attempts=0) is never clobbered by a late error from the prior attempt.
+	*/
+	async markDirtyPathError(path, latestSeq, error, nextAttemptAt) {
+		return ((await this.db.prepare(DIRTY_PATH_MARK_ERROR_SQL).bind(error, nextAttemptAt, this.scope, path, latestSeq).run()).meta?.changes ?? 0) > 0;
+	}
+};
+
+//#endregion
+export { D1TreeIndex, MAX_ENTRIES_PER_SCOPE, ancestorDirs, buildDirChainStmt, nameOf, parentOf };
+//# sourceMappingURL=d1-tree-index.mjs.map