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

package/dist/sqlite-tree-index.cjs

@@ -0,0 +1,901 @@
+const require_changelog_schema = require('./changelog-schema.cjs');
+const require_inline_content = require('./inline-content.cjs');
+const require_timestamp = require('./timestamp.cjs');
+const require_tree_index = require('./tree-index.cjs');
+const require_tree_query = require('./tree-query.cjs');
+const require_changelog_write = require('./changelog-write.cjs');
+const require_prefix_range = require('./prefix-range.cjs');
+const require_dirty_path_schema = require('./dirty-path-schema.cjs');
+const require_d1_tree_index = require('./d1-tree-index.cjs');
+
+//#region src/sqlite-tree-index.ts
+/**
+* `isReferencedMany` IN-shard size for libsql/SQLite (design §7.2). SQLite's
+* default bound-param cap is ~999; the three-way UNION binds each cid 3×, so
+* 300 cids ⇒ ≤ ~906 params — comfortably under the cap on both branches.
+*/
+const SQLITE_MANY_SHARD_SIZE = 300;
+const VALID_ORDER_BY = {
+	path: "path",
+	mtime: "mtime",
+	size: "size",
+	ctime: "ctime",
+	mimeType: "mime_type",
+	name: "name"
+};
+/** The only nullable sortable column — NULLs must sort last (see tree-index.ts). */
+const NULLABLE_ORDER_COLUMNS = new Set(["mime_type"]);
+/** libsql returns INTEGER columns as number|bigint; coerce to a JS number. */
+function num(v) {
+	return typeof v === "bigint" ? Number(v) : v ?? 0;
+}
+/** Raw sort-column value of a row for the keyset cursor (NULL stays null). */
+function sortValueOf(row, col) {
+	const v = row[col];
+	if (v == null) return null;
+	if (typeof v === "bigint") return Number(v);
+	return v;
+}
+function mapChildRow(r) {
+	const e = {
+		path: r.path,
+		cid: r.cid ?? "",
+		size: num(r.size),
+		mtime: num(r.mtime),
+		ctime: num(r.ctime),
+		mimeType: r.mime_type ?? void 0
+	};
+	if (r.content != null) e.content = r.content;
+	return e;
+}
+var SQLiteTreeIndex = class {
+	client;
+	maxEntriesPerScope;
+	/** upload-limits Phase 5 byte quota (0 = disabled, the opt-in default). */
+	maxBytesPerScope;
+	inline;
+	constructor(db, scope, opts) {
+		this.scope = scope;
+		this.client = db.rawClient;
+		this.maxEntriesPerScope = opts?.maxEntriesPerScope ?? require_d1_tree_index.MAX_ENTRIES_PER_SCOPE;
+		this.maxBytesPerScope = typeof opts?.maxBytesPerScope === "number" && opts.maxBytesPerScope > 0 ? opts.maxBytesPerScope : 0;
+		this.inline = require_inline_content.resolveInlineConfig(opts);
+	}
+	/**
+	* Current Σ size of this scope's file rows (upload-limits Phase 5 byte quota).
+	* SQLite (local Node) has no D1 rows_read billing, so a direct `SUM(size)` is
+	* fine here — same pattern as the file-count quota's `count("")` scan (the
+	* trigger-maintained `scope_meta.total_bytes` is a D1-only optimization).
+	*/
+	async scopeTotalBytes() {
+		const r = await this.client.execute({
+			sql: "SELECT COALESCE(SUM(size), 0) as total FROM ds_entries WHERE scope = ? AND kind = 'file'",
+			args: [this.scope]
+		});
+		return Number(r.rows[0]?.total ?? 0);
+	}
+	async get(path, opts) {
+		const contentCol = (opts?.includeContent ?? true) && this.inline.inlineCache === "on" ? ", content" : "";
+		const row = (await this.client.execute({
+			sql: `SELECT cid, size, mtime, ctime, mime_type, metadata${contentCol} FROM ds_entries WHERE scope = ? AND path = ?`,
+			args: [this.scope, path]
+		})).rows[0];
+		if (!row || row.cid == null) return null;
+		const entry = {
+			cid: row.cid,
+			size: num(row.size),
+			mtime: num(row.mtime),
+			ctime: num(row.ctime),
+			mimeType: row.mime_type ?? void 0
+		};
+		if (row.content != null) entry.content = row.content;
+		const meta = require_tree_index.parseTreeEntryMetadata(row.metadata);
+		if (meta) entry.metadata = meta;
+		return entry;
+	}
+	async getDirTimes(dirPath) {
+		const row = (await this.client.execute({
+			sql: "SELECT ctime, mtime FROM ds_entries WHERE scope = ? AND path = ?",
+			args: [this.scope, dirPath]
+		})).rows[0];
+		return row ? {
+			ctime: num(row.ctime),
+			mtime: num(row.mtime)
+		} : null;
+	}
+	async put(path, entry, opts) {
+		require_changelog_write.validateDeviceId(opts.deviceId);
+		const existing = await this.get(path);
+		if (existing && existing.cid === entry.cid && existing.mimeType === entry.mimeType && require_tree_index.treeEntryMetadataEqual(existing.metadata, entry.metadata)) {
+			if (this.inline.inlineCache !== "on") return { oldCid: existing.cid };
+			const wouldBeInline = await require_inline_content.resolveInlineContent(entry, this.inline);
+			if ((existing.content ?? null) === wouldBeInline) return { oldCid: existing.cid };
+		}
+		if (!existing) {
+			if (await this.count("") >= this.maxEntriesPerScope) throw require_tree_index.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.scopeTotalBytes() + newBytes > this.maxBytesPerScope) throw require_tree_index.storageQuotaError(`Storage quota exceeded: scope "${this.scope}" has reached the ${this.maxBytesPerScope}-byte limit`);
+			}
+		}
+		const now = Date.now();
+		const stmts = [];
+		const dirStamp = require_timestamp.resolveParentDirStamp(entry.metadata);
+		const directParent = require_d1_tree_index.parentOf(path);
+		for (const dirPath of require_d1_tree_index.ancestorDirs(path)) stmts.push(require_d1_tree_index.buildDirChainStmt(this.scope, dirPath, dirStamp && dirPath === directParent ? dirStamp : null, now));
+		if (!opts.skipChangelog) stmts.push({
+			sql: CHANGELOG_INSERT_SQL_WITH_SUBQUERY,
+			args: [
+				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 = require_changelog_schema.watermarkWritePrefix(path);
+			if (wmPrefix !== null) stmts.push({
+				sql: require_changelog_schema.PREFIX_WATERMARK_BUMP_SQL,
+				args: [this.scope, wmPrefix]
+			});
+		}
+		await this.client.batch(stmts, "write");
+		return { oldCid: existing?.cid };
+	}
+	/** Inline content this entry would store — drives loopBatchPutEntries' content-aware skip. */
+	inlineForEntry(entry) {
+		return require_inline_content.resolveInlineContent(entry, this.inline);
+	}
+	/** Point seek on the `(scope, dedup_scope, dedup_key)` partial UNIQUE index. */
+	async findByDedupKey(dedupScope, dedupKey) {
+		const row = (await this.client.execute({
+			sql: `SELECT path, cid, size, mtime, ctime, mime_type, metadata
+            FROM ds_entries WHERE scope = ? AND dedup_scope = ? AND dedup_key = ? LIMIT 1`,
+			args: [
+				this.scope,
+				dedupScope,
+				dedupKey
+			]
+		})).rows[0];
+		if (!row || row.cid == null) return null;
+		const entry = {
+			path: row.path,
+			cid: row.cid,
+			size: num(row.size),
+			mtime: num(row.mtime),
+			ctime: num(row.ctime),
+			mimeType: row.mime_type ?? void 0
+		};
+		const meta = require_tree_index.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) {
+		require_changelog_write.validateDeviceId(opts.deviceId);
+		await this.client.execute({
+			sql: "UPDATE ds_entries SET dedup_scope = ?, dedup_key = ? WHERE scope = ? AND path = ?",
+			args: [
+				dedupScope,
+				dedupKey,
+				this.scope,
+				path
+			]
+		});
+	}
+	async getPrefixWatermark(prefix) {
+		const wmPrefix = require_changelog_schema.watermarkPrefix(prefix);
+		if (wmPrefix === null) return null;
+		return num((await this.client.execute({
+			sql: require_changelog_schema.PREFIX_WATERMARK_READ_SQL,
+			args: [this.scope, wmPrefix]
+		})).rows[0]?.version);
+	}
+	/**
+	* 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 base = [
+			this.scope,
+			path,
+			require_d1_tree_index.parentOf(path),
+			require_d1_tree_index.nameOf(path),
+			entry.cid,
+			entry.size,
+			entry.mimeType ?? null,
+			entry.ctime,
+			entry.mtime
+		];
+		const metadataValue = require_tree_index.serializeTreeEntryMetadata(entry.metadata);
+		const dedupScopeValue = entry.dedupScope ?? null;
+		const dedupKeyValue = entry.dedupKey ?? null;
+		if (this.inline.inlineCache !== "on") return {
+			sql: `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)`,
+			args: [
+				...base,
+				metadataValue,
+				dedupScopeValue,
+				dedupKeyValue
+			]
+		};
+		const inlineContent = await require_inline_content.resolveInlineContent(entry, this.inline);
+		return {
+			sql: `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)`,
+			args: [
+				...base,
+				inlineContent,
+				metadataValue,
+				dedupScopeValue,
+				dedupKeyValue
+			]
+		};
+	}
+	async delete(path, opts) {
+		require_changelog_write.validateDeviceId(opts.deviceId);
+		const stmts = [];
+		if (!opts.skipChangelog) stmts.push({
+			sql: `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`,
+			args: [
+				this.scope,
+				path,
+				opts.mtime ?? Date.now(),
+				opts.deviceId,
+				this.scope,
+				path
+			]
+		});
+		stmts.push({
+			sql: "DELETE FROM ds_entries WHERE scope = ? AND path = ?",
+			args: [this.scope, path]
+		});
+		if (!opts.skipChangelog) {
+			const wmPrefix = require_changelog_schema.watermarkWritePrefix(path);
+			if (wmPrefix !== null) stmts.push({
+				sql: require_changelog_schema.PREFIX_WATERMARK_BUMP_SQL,
+				args: [this.scope, wmPrefix]
+			});
+		}
+		await this.client.batch(stmts, "write");
+		await this.cleanEmptyParents(path);
+	}
+	async cleanEmptyParents(path) {
+		for (const dirPath of require_d1_tree_index.ancestorDirs(path)) {
+			if ((await this.client.execute({
+				sql: "SELECT 1 FROM ds_entries WHERE scope = ? AND parent = ? LIMIT 1",
+				args: [this.scope, dirPath]
+			})).rows.length > 0) break;
+			await this.client.execute({
+				sql: "DELETE FROM ds_entries WHERE scope = ? AND path = ?",
+				args: [this.scope, dirPath]
+			});
+		}
+	}
+	async list(prefix, options) {
+		const limit = options?.limit ?? 1e3;
+		const col = VALID_ORDER_BY[options?.orderBy ?? "path"];
+		if (!col) throw new Error(`Invalid orderBy: ${options?.orderBy}`);
+		const order = options?.order ?? "asc";
+		if (limit === 0) return {
+			entries: [],
+			hasMore: false
+		};
+		const [lo, hi] = require_prefix_range.prefixRange(prefix);
+		const args = [
+			this.scope,
+			lo,
+			hi
+		];
+		let sql = `SELECT path, ${col} as _sort FROM ds_entries WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file'`;
+		if (options?.cursor) {
+			sql += ` AND ${col} ${order === "asc" ? ">" : "<"} ?`;
+			args.push(options.cursor);
+		}
+		sql += ` ORDER BY ${col} ${order} LIMIT ?`;
+		args.push(limit + 1);
+		const result = await this.client.execute({
+			sql,
+			args
+		});
+		const hasMore = result.rows.length > limit;
+		const rows = hasMore ? result.rows.slice(0, limit) : result.rows;
+		return {
+			entries: rows.map((r) => ({ path: r.path })),
+			hasMore,
+			cursor: hasMore && rows.length > 0 ? String(rows[rows.length - 1]._sort) : void 0
+		};
+	}
+	async listEntries(prefix, options) {
+		const limit = options?.limit ?? 1e3;
+		const hasOrderBy = options?.orderBy !== void 0;
+		const col = VALID_ORDER_BY[options?.orderBy ?? "path"];
+		if (!col) throw new Error(`Invalid orderBy: ${options?.orderBy}`);
+		const order = options?.order === "desc" ? "desc" : "asc";
+		if (limit === 0) return {
+			entries: [],
+			hasMore: false
+		};
+		const parsed = require_tree_index.parseTreeCursor(options?.cursor, hasOrderBy);
+		const [lo, hi] = require_prefix_range.prefixRange(prefix);
+		const args = [
+			this.scope,
+			lo,
+			hi
+		];
+		let sql = `SELECT path, cid, size, mtime, ctime, mime_type${options?.includeContent ? ", content" : ""} FROM ds_entries${col === "path" ? " INDEXED BY idx_entries_kind" : ""} WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file'`;
+		if (hasOrderBy) {
+			const parts = require_tree_index.buildOrderedQueryParts({
+				col,
+				nullable: NULLABLE_ORDER_COLUMNS.has(col),
+				order,
+				tieCol: "path",
+				cursor: parsed.kind === "v2" ? parsed.cursor : void 0
+			});
+			if (parts.cursorWhereSql) {
+				sql += ` AND ${parts.cursorWhereSql}`;
+				args.push(...parts.cursorArgs);
+			}
+			sql += ` ORDER BY ${parts.orderSql} LIMIT ?`;
+		} else {
+			if (parsed.kind === "legacy") {
+				sql += ` AND ${col} ${order === "asc" ? ">" : "<"} ?`;
+				args.push(parsed.value);
+			}
+			sql += ` ORDER BY ${col} ${order} LIMIT ?`;
+		}
+		args.push(limit + 1);
+		const result = await this.client.execute({
+			sql,
+			args
+		});
+		const hasMore = result.rows.length > limit;
+		const rows = hasMore ? result.rows.slice(0, limit) : result.rows;
+		const last = rows[rows.length - 1];
+		const cursor = !hasMore || !last ? void 0 : hasOrderBy ? require_tree_index.buildKeysetCursor(sortValueOf(last, col), last.path) : String(last.path);
+		return {
+			entries: rows.map((r) => {
+				const e = {
+					path: r.path,
+					cid: r.cid,
+					size: num(r.size),
+					mtime: num(r.mtime),
+					ctime: num(r.ctime),
+					mimeType: r.mime_type ?? void 0
+				};
+				if (options?.includeContent && r.content != null) e.content = r.content;
+				return e;
+			}),
+			hasMore,
+			cursor
+		};
+	}
+	async hasChildren(prefix) {
+		const [lo, hi] = require_prefix_range.prefixRange(prefix);
+		return (await this.client.execute({
+			sql: "SELECT 1 FROM ds_entries WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file' LIMIT 1",
+			args: [
+				this.scope,
+				lo,
+				hi
+			]
+		})).rows.length > 0;
+	}
+	async count(prefix) {
+		const [lo, hi] = require_prefix_range.prefixRange(prefix);
+		return num((await this.client.execute({
+			sql: "SELECT COUNT(*) as cnt FROM ds_entries WHERE scope = ? AND path >= ? AND path < ? AND kind = 'file'",
+			args: [
+				this.scope,
+				lo,
+				hi
+			]
+		})).rows[0]?.cnt);
+	}
+	async deleteByPrefix(prefix, opts) {
+		require_changelog_write.validateDeviceId(opts.deviceId);
+		const [lo, hi] = require_prefix_range.prefixRange(prefix);
+		const stmts = [];
+		if (!opts.skipChangelog) stmts.push({
+			sql: `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`,
+			args: [
+				this.scope,
+				opts.mtime ?? Date.now(),
+				opts.deviceId,
+				this.scope,
+				lo,
+				hi
+			]
+		});
+		if (!opts.skipChangelog) {
+			const wmPrefix = require_changelog_schema.watermarkPrefix(prefix);
+			if (wmPrefix !== null) stmts.push({
+				sql: require_changelog_schema.PREFIX_WATERMARK_BUMP_SQL,
+				args: [this.scope, wmPrefix]
+			});
+		}
+		stmts.push({
+			sql: "DELETE FROM ds_entries WHERE scope = ? AND path >= ? AND path < ?",
+			args: [
+				this.scope,
+				lo,
+				hi
+			]
+		});
+		const results = await this.client.batch(stmts, "write");
+		return num(results[results.length - 1]?.rowsAffected);
+	}
+	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 = require_tree_index.parseTreeCursor(options?.cursor, hasOrderBy);
+		const includeContent = options?.includeContent === true;
+		const t = "e.";
+		const from = require_tree_query.buildChildrenFrom(void 0);
+		const args = [
+			...from.args,
+			this.scope,
+			parent
+		];
+		let sql = `SELECT ${t}path, ${t}cid, ${t}size, ${t}mtime, ${t}ctime, ${t}mime_type, ${t}name${includeContent ? `, ${t}content` : ""} ${from.sql} WHERE ${t}scope = ? AND ${t}parent = ?`;
+		if (hasOrderBy) {
+			const col = VALID_ORDER_BY[options.orderBy];
+			if (!col) throw new Error(`Invalid orderBy: ${options?.orderBy}`);
+			const parts = require_tree_index.buildOrderedQueryParts({
+				col: `${t}${col}`,
+				nullable: NULLABLE_ORDER_COLUMNS.has(col),
+				order,
+				tieCol: `${t}name`,
+				cursor: parsed.kind === "v2" ? parsed.cursor : void 0
+			});
+			if (parts.cursorWhereSql) {
+				sql += ` AND ${parts.cursorWhereSql}`;
+				args.push(...parts.cursorArgs);
+			}
+			sql += ` ORDER BY ${parts.orderSql} LIMIT ?`;
+			args.push(limit + 1);
+			const result$1 = await this.client.execute({
+				sql,
+				args
+			});
+			const hasMore$1 = result$1.rows.length > limit;
+			const rows$1 = hasMore$1 ? result$1.rows.slice(0, limit) : result$1.rows;
+			const last = rows$1[rows$1.length - 1];
+			return {
+				entries: rows$1.map((r) => mapChildRow(r)),
+				hasMore: hasMore$1,
+				cursor: hasMore$1 && last ? require_tree_index.buildKeysetCursor(sortValueOf(last, col), last.name) : void 0
+			};
+		}
+		if (parsed.kind === "legacy") {
+			sql += ` AND ${t}name ${order === "asc" ? ">" : "<"} ?`;
+			args.push(parsed.value);
+		}
+		sql += ` ORDER BY ${t}name ${order} LIMIT ?`;
+		args.push(limit + 1);
+		const result = await this.client.execute({
+			sql,
+			args
+		});
+		const hasMore = result.rows.length > limit;
+		const rows = hasMore ? result.rows.slice(0, limit) : result.rows;
+		return {
+			entries: rows.map((r) => mapChildRow(r)),
+			hasMore,
+			cursor: hasMore && rows.length > 0 ? String(rows[rows.length - 1].name) : void 0
+		};
+	}
+	async countChildren(parent) {
+		return num((await this.client.execute({
+			sql: "SELECT COUNT(*) as cnt FROM ds_entries WHERE scope = ? AND parent = ?",
+			args: [this.scope, parent]
+		})).rows[0]?.cnt);
+	}
+	/** Collection query (afs-collection-query Phase 1) — see tree-query.ts. */
+	async query(parent, spec) {
+		const statements = require_tree_query.buildTreeQueryStatements({
+			scope: this.scope,
+			parent,
+			spec
+		});
+		if (statements.aggregate) {
+			const [aggRes, countRes$1] = await Promise.all([this.client.execute({
+				sql: statements.aggregate.select.sql,
+				args: statements.aggregate.select.args
+			}), this.client.execute({
+				sql: statements.aggregate.countGroups.sql,
+				args: statements.aggregate.countGroups.args
+			})]);
+			const aggregateGroups = require_tree_query.mapAggregateRows(aggRes.rows, statements.aggregate.groupKeys, statements.aggregate.aggregations);
+			return {
+				rows: [],
+				total: statements.aggregate.groupKeys.length === 0 ? 1 : num(countRes$1.rows[0]?.cnt),
+				aggregateGroups
+			};
+		}
+		const [rowsRes, countRes, groupsRes, seekRes] = await Promise.all([
+			this.client.execute({
+				sql: statements.rows.sql,
+				args: statements.rows.args
+			}),
+			statements.count ? this.client.execute({
+				sql: statements.count.sql,
+				args: statements.count.args
+			}) : Promise.resolve(void 0),
+			statements.groups ? this.client.execute({
+				sql: statements.groups.sql,
+				args: statements.groups.args
+			}) : Promise.resolve(void 0),
+			statements.seek ? this.client.execute({
+				sql: statements.seek.sql,
+				args: statements.seek.args
+			}) : Promise.resolve(void 0)
+		]);
+		const seekOffset = statements.seek ? seekRes && seekRes.rows.length > 0 ? num(seekRes.rows[0]?.rn) : -1 : void 0;
+		return require_tree_query.buildTreeQueryResultFromSql({
+			rawRows: rowsRes.rows,
+			total: countRes ? num(countRes.rows[0]?.cnt) : -1,
+			groupRows: groupsRes?.rows.map((r) => ({
+				t: r.t,
+				v: r.v,
+				cnt: r.cnt
+			})),
+			spec,
+			orderField: statements.order.field,
+			seekOffset
+		});
+	}
+	/** Page-bounded grouped child counts — see D1TreeIndex.countChildrenMany
+	*  (same ≤90-per-chunk shape kept for cross-backend statement parity). */
+	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 result = await this.client.execute({
+				sql: `SELECT parent, COUNT(*) as cnt FROM ds_entries WHERE scope = ? AND parent IN (${chunk.map(() => "?").join(",")}) GROUP BY parent`,
+				args: [this.scope, ...chunk]
+			});
+			for (const r of result.rows) map.set(r.parent, num(r.cnt));
+		}
+		return map;
+	}
+	async aggregate(prefix) {
+		const [lo, hi] = require_prefix_range.prefixRange(prefix);
+		const row = (await this.client.execute({
+			sql: `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'`,
+			args: [
+				this.scope,
+				lo,
+				hi
+			]
+		})).rows[0];
+		return {
+			fileCount: num(row?.file_count),
+			totalSize: num(row?.total_size)
+		};
+	}
+	/** Batch metadata read — loop over get (no IN-merge needed off-CF). */
+	async getMany(paths) {
+		const map = /* @__PURE__ */ new Map();
+		for (const path of paths) map.set(path, await this.get(path));
+		return map;
+	}
+	/** Batch sync fast path — loop reference semantics (conformance-pinned
+	*  equivalent of the merged D1 implementation). */
+	async batchPutEntries(entries, ctx) {
+		return require_tree_index.loopBatchPutEntries(this, entries, ctx);
+	}
+	/** Delete twin of {@link batchPutEntries} (loop reference semantics). */
+	async batchDeleteEntries(entries, ctx) {
+		return require_tree_index.loopBatchDeleteEntries(this, entries, ctx);
+	}
+	async putBatch(entries, opts) {
+		if (entries.length === 0) return;
+		require_changelog_write.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 = require_timestamp.resolveParentDirStamp(entry.metadata);
+			if (stamp) dirStamps.set(require_d1_tree_index.parentOf(path), stamp);
+			for (const dirPath of require_d1_tree_index.ancestorDirs(path)) {
+				if (allDirs.has(dirPath)) break;
+				allDirs.add(dirPath);
+			}
+		}
+		for (const dirPath of allDirs) stmts.push(require_d1_tree_index.buildDirChainStmt(this.scope, dirPath, dirStamps.get(dirPath) ?? null, now));
+		for (const { path, entry } of entries) {
+			if (!opts.skipChangelog) stmts.push({
+				sql: CHANGELOG_INSERT_SQL_WITH_SUBQUERY,
+				args: [
+					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 = require_changelog_schema.watermarkWritePrefix(path);
+				if (wmPrefix !== null) wmPrefixes.add(wmPrefix);
+			}
+			for (const wmPrefix of wmPrefixes) stmts.push({
+				sql: require_changelog_schema.PREFIX_WATERMARK_BUMP_SQL,
+				args: [this.scope, wmPrefix]
+			});
+		}
+		await this.client.batch(stmts, "write");
+	}
+	async listModifiedSince(prefix, since, options) {
+		const limit = options?.limit ?? 1e3;
+		const order = options?.order ?? "asc";
+		if (limit === 0) return {
+			entries: [],
+			hasMore: false
+		};
+		const [lo, hi] = require_prefix_range.prefixRange(prefix);
+		const args = [
+			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 (options?.cursor) {
+			sql += ` AND path ${order === "asc" ? ">" : "<"} ?`;
+			args.push(options.cursor);
+		}
+		sql += ` ORDER BY path ${order} LIMIT ?`;
+		args.push(limit + 1);
+		const result = await this.client.execute({
+			sql,
+			args
+		});
+		const hasMore = result.rows.length > limit;
+		const rows = hasMore ? result.rows.slice(0, limit) : result.rows;
+		return {
+			entries: rows.map((r) => ({
+				path: r.path,
+				cid: r.cid,
+				size: num(r.size),
+				mtime: num(r.mtime),
+				ctime: num(r.ctime),
+				mimeType: r.mime_type ?? void 0
+			})),
+			hasMore,
+			cursor: hasMore && rows.length > 0 ? String(rows[rows.length - 1].path) : void 0
+		};
+	}
+	async getMaxSeq() {
+		const [result, compactedBelow] = await Promise.all([this.client.execute({
+			sql: "SELECT MAX(seq) as maxSeq FROM ds_changelog WHERE scope = ?",
+			args: [this.scope]
+		}), this.getCompactedBelowSeq()]);
+		return Math.max(num(result.rows[0]?.maxSeq), 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.client.execute({
+			sql: `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`,
+			args: [
+				this.scope,
+				cid,
+				this.scope,
+				cid,
+				this.scope,
+				cid
+			]
+		})).rows.length > 0;
+		const [lo, hi] = require_prefix_range.prefixRange(pathPrefix);
+		return (await this.client.execute({
+			sql: `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`,
+			args: [
+				this.scope,
+				cid,
+				lo,
+				hi,
+				this.scope,
+				cid,
+				lo,
+				hi,
+				this.scope,
+				cid,
+				lo,
+				hi
+			]
+		})).rows.length > 0;
+	}
+	/**
+	* Batch read-auth (design §7.2 / §14) — three-way-equivalent to per-cid
+	* {@link isReferenced}, sharded (see {@link SQLITE_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 ? require_prefix_range.prefixRange(pathPrefix) : ["", ""];
+		for (let i = 0; i < unique.length; i += SQLITE_MANY_SHARD_SIZE) {
+			const shard = unique.slice(i, i + SQLITE_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 args = [];
+			for (let b = 0; b < 3; b++) {
+				args.push(this.scope, ...shard);
+				if (usePrefix) args.push(lo, hi);
+			}
+			const result = await this.client.execute({
+				sql,
+				args
+			});
+			for (const row of result.rows) {
+				const c = row.c;
+				if (c) referenced.add(c);
+			}
+		}
+		return referenced;
+	}
+	async getChangelogSince(sinceSeq, limit) {
+		const safeLimit = limit > 0 ? limit : 0;
+		if (safeLimit === 0) return {
+			entries: [],
+			hasMore: false,
+			cursor: sinceSeq
+		};
+		const result = await this.client.execute({
+			sql: `SELECT seq, scope, path, op, cid, old_cid, size, mtime, device_id
+            FROM ds_changelog WHERE scope = ? AND seq > ? ORDER BY seq ASC LIMIT ?`,
+			args: [
+				this.scope,
+				sinceSeq,
+				safeLimit + 1
+			]
+		});
+		const hasMore = result.rows.length > safeLimit;
+		const entries = (hasMore ? result.rows.slice(0, safeLimit) : result.rows).map((r) => ({
+			seq: num(r.seq),
+			scope: r.scope,
+			path: r.path,
+			op: r.op,
+			cid: r.cid ?? null,
+			old_cid: r.old_cid ?? null,
+			size: r.size == null ? null : num(r.size),
+			mtime: num(r.mtime),
+			device_id: r.device_id
+		}));
+		return {
+			entries,
+			hasMore,
+			cursor: entries.length > 0 ? entries[entries.length - 1].seq : sinceSeq
+		};
+	}
+	async getCompactedBelowSeq() {
+		return 0;
+	}
+	async listDirtyPaths(options) {
+		const now = options.now ?? Date.now();
+		const limit = options.limit > 0 ? options.limit : 0;
+		if (limit === 0) return [];
+		const [lo, hi] = require_prefix_range.prefixRange(options.prefix);
+		const { rows } = await this.client.execute({
+			sql: require_dirty_path_schema.DIRTY_PATH_LIST_SQL,
+			args: [
+				this.scope,
+				lo,
+				hi,
+				now,
+				limit
+			]
+		});
+		return rows.map((r) => ({
+			path: String(r.path),
+			latestSeq: Number(r.latest_seq),
+			op: String(r.op),
+			cid: r.cid == null ? null : String(r.cid),
+			mtime: Number(r.mtime),
+			attempts: Number(r.attempts)
+		}));
+	}
+	async ackDirtyPath(path, latestSeq) {
+		return ((await this.client.execute({
+			sql: require_dirty_path_schema.DIRTY_PATH_ACK_SQL,
+			args: [
+				this.scope,
+				path,
+				latestSeq
+			]
+		})).rowsAffected ?? 0) > 0;
+	}
+	async markDirtyPathError(path, latestSeq, error, nextAttemptAt) {
+		return ((await this.client.execute({
+			sql: require_dirty_path_schema.DIRTY_PATH_MARK_ERROR_SQL,
+			args: [
+				error,
+				nextAttemptAt,
+				this.scope,
+				path,
+				latestSeq
+			]
+		})).rowsAffected ?? 0) > 0;
+	}
+};
+/**
+* Put-path changelog INSERT with a correlated subquery reading the pre-write
+* cid as old_cid (mirrors D1TreeIndex). Distinct from the plain
+* `CHANGELOG_INSERT_SQL` in changelog-write.ts which takes old_cid as a bound
+* param (used by MetadataDB.upsertEntry, which pre-reads old_cid separately).
+*/
+const CHANGELOG_INSERT_SQL_WITH_SUBQUERY = `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 = ?), ?, ?, ?)`;
+
+//#endregion
+exports.SQLiteTreeIndex = SQLiteTreeIndex;