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

package/dist/tree-index.mjs

@@ -0,0 +1,322 @@
+import { makeNsLog } from "@aigne/afs";
+
+//#region src/tree-index.ts
+/**
+* TreeIndex — typed interface for file metadata indexing.
+*
+* Replaces KeyValueStore for DID Space tree entries.
+* Implementations: MemoryTreeIndex (testing), D1TreeIndex (production).
+*/
+const log = makeNsLog("provider:did-space");
+/**
+* Stable code on a per-scope quota rejection (file-count OR byte quota,
+* upload-limits Phase 5 / T5.2). Surfaced via the thrown Error's `.code`
+* (single-put/delete) and the batch result entry's `.code` (batchPut) so a
+* consumer can distinguish quota from other failures — previously these were
+* message-only. The message text is preserved verbatim for parity.
+*/
+const STORAGE_QUOTA_EXCEEDED_CODE = "STORAGE_QUOTA_EXCEEDED";
+/** Build a quota-rejection Error carrying {@link STORAGE_QUOTA_EXCEEDED_CODE}. */
+function storageQuotaError(message) {
+	return Object.assign(new Error(message), { code: STORAGE_QUOTA_EXCEEDED_CODE });
+}
+/**
+* Parse a raw `entries.metadata` column value back into an object.
+*
+* Contract:
+* - NULL / empty / non-string → undefined (no metadata)
+* - valid JSON object → that object
+* - parse error or non-object JSON → undefined + console.warn (best-effort:
+*   one bad row must not break list/read of the whole collection)
+*/
+function parseTreeEntryMetadata(raw) {
+	if (raw == null) return void 0;
+	if (typeof raw !== "string" || raw.length === 0) return void 0;
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+		log.warn(`[did-space] entries.metadata is not a JSON object; treating as empty`);
+		return;
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		log.warn(`[did-space] failed to parse entries.metadata (${msg}); treating as empty`);
+		return;
+	}
+}
+/**
+* Serialize a TreeEntry.metadata object for storage in the
+* `entries.metadata` column.
+*
+* Contract:
+* - undefined / null / empty object → null (don't waste a JSON literal)
+* - non-empty object → JSON.stringify result
+*/
+function serializeTreeEntryMetadata(metadata) {
+	if (metadata == null) return null;
+	if (Object.keys(metadata).length === 0) return null;
+	return JSON.stringify(metadata);
+}
+/** Order-insensitive deep equality: object keys are unordered, array order matters. */
+function deepEqual(a, b) {
+	if (a === b) return true;
+	if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+	const aArr = Array.isArray(a);
+	const bArr = Array.isArray(b);
+	if (aArr !== bArr) return false;
+	if (aArr && bArr) {
+		if (a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (!deepEqual(a[i], b[i])) return false;
+		return true;
+	}
+	const ao = a;
+	const bo = b;
+	const ak = Object.keys(ao);
+	if (ak.length !== Object.keys(bo).length) return false;
+	for (const k of ak) {
+		if (!Object.hasOwn(bo, k)) return false;
+		if (!deepEqual(ao[k], bo[k])) return false;
+	}
+	return true;
+}
+/**
+* Are two TreeEntry.metadata objects equivalent for skip-if-unchanged purposes?
+* (did-space-metadata G4). This MUST be order-insensitive for object keys —
+* {@link serializeTreeEntryMetadata} is a bare `JSON.stringify` that preserves
+* insertion order, so its string equality would treat a key reorder as a
+* "change" and forge a phantom changelog row / sync churn (the very thing skip
+* exists to avoid). Empty / null / undefined all compare equal because they all
+* serialize to a NULL column. Used ONLY for the skip decision; storage still
+* uses {@link serializeTreeEntryMetadata} verbatim.
+*/
+function treeEntryMetadataEqual(a, b) {
+	const aEmpty = a == null || Object.keys(a).length === 0;
+	const bEmpty = b == null || Object.keys(b).length === 0;
+	if (aEmpty || bEmpty) return aEmpty && bEmpty;
+	return deepEqual(a, b);
+}
+/** UTF-8 safe base64 (btoa alone corrupts non-latin1 file names). */
+function b64encode(s) {
+	const bytes = new TextEncoder().encode(s);
+	let bin = "";
+	for (const b of bytes) bin += String.fromCharCode(b);
+	return btoa(bin);
+}
+function b64decode(s) {
+	const bin = atob(s);
+	return new TextDecoder().decode(Uint8Array.from(bin, (c) => c.charCodeAt(0)));
+}
+/** Build a v2 keyset cursor: `v2:<b64(json(sortValue))>:<b64(tie)>`. */
+function buildKeysetCursor(sortValue, tie) {
+	return `v2:${b64encode(JSON.stringify(sortValue))}:${b64encode(tie)}`;
+}
+/**
+* Parse a list cursor. Shared by all three TreeIndex impls so the
+* legacy-vs-v2 dance can never drift between them.
+*
+* - undefined → none
+* - `v2:`-prefixed → keyset cursor; REQUIRES `hasOrderBy` (a keyset cursor
+*   replayed onto a default-order listing would be a wrong page); malformed
+*   payloads throw a clean error instead of producing a wrong page.
+* - anything else → legacy plain cursor, accepted ONLY for default
+*   (no-orderBy) order.
+*/
+function parseTreeCursor(cursor, hasOrderBy) {
+	if (!cursor) return { kind: "none" };
+	if (cursor.startsWith("v2:")) {
+		if (!hasOrderBy) throw new Error("Invalid cursor: v2 keyset cursor requires a matching orderBy");
+		const parts = cursor.split(":");
+		if (parts.length !== 3 || !parts[1] || !parts[2]) throw new Error("Invalid cursor: malformed v2 keyset cursor");
+		let sortValue;
+		let tie;
+		try {
+			sortValue = JSON.parse(b64decode(parts[1]));
+			tie = b64decode(parts[2]);
+		} catch {
+			throw new Error("Invalid cursor: malformed v2 keyset cursor");
+		}
+		if (sortValue !== null && typeof sortValue !== "string" && typeof sortValue !== "number") throw new Error("Invalid cursor: malformed v2 keyset cursor");
+		return {
+			kind: "v2",
+			cursor: {
+				sortValue,
+				tie
+			}
+		};
+	}
+	if (hasOrderBy) throw new Error("Invalid cursor: legacy cursor cannot be combined with orderBy");
+	return {
+		kind: "legacy",
+		value: cursor
+	};
+}
+/**
+* Build the ORDER BY + keyset-resume WHERE for an ordered listing. Shared
+* by SQLiteTreeIndex and D1TreeIndex (identical SQL dialect).
+*
+* - Missing values sort LAST regardless of direction: nullable columns get
+*   a leading `(col IS NULL) ASC` term. Non-nullable columns skip it so the
+*   `(scope, parent, col, name)` indexes stay usable.
+* - Resume uses the expansion `col > ? OR (col = ? AND tie > ?)` (row-value
+*   free — works on every SQLite the runtimes target) plus NULL-run
+*   handling for nullable columns.
+*/
+function buildOrderedQueryParts(opts) {
+	const { col, nullable, tieCol, cursor } = opts;
+	const dir = opts.order === "desc" ? "DESC" : "ASC";
+	const op = opts.order === "desc" ? "<" : ">";
+	const orderSql = nullable ? `(${col} IS NULL) ASC, ${col} ${dir}, ${tieCol} ${dir}` : `${col} ${dir}, ${tieCol} ${dir}`;
+	if (!cursor) return {
+		cursorWhereSql: "",
+		cursorArgs: [],
+		orderSql
+	};
+	if (cursor.sortValue === null) {
+		if (!nullable) throw new Error("Invalid cursor: malformed v2 keyset cursor");
+		return {
+			cursorWhereSql: `(${col} IS NULL AND ${tieCol} ${op} ?)`,
+			cursorArgs: [cursor.tie],
+			orderSql
+		};
+	}
+	if (nullable) return {
+		cursorWhereSql: `((${col} IS NOT NULL AND (${col} ${op} ? OR (${col} = ? AND ${tieCol} ${op} ?))) OR ${col} IS NULL)`,
+		cursorArgs: [
+			cursor.sortValue,
+			cursor.sortValue,
+			cursor.tie
+		],
+		orderSql
+	};
+	return {
+		cursorWhereSql: `(${col} ${op} ? OR (${col} = ? AND ${tieCol} ${op} ?))`,
+		cursorArgs: [
+			cursor.sortValue,
+			cursor.sortValue,
+			cursor.tie
+		],
+		orderSql
+	};
+}
+/**
+* In-memory equivalents of the SQL ordering semantics, used by
+* MemoryTreeIndex so all three impls stay in lockstep.
+*/
+function compareTreeSortValues(a, b, order) {
+	if (a === null && b === null) return 0;
+	if (a === null) return 1;
+	if (b === null) return -1;
+	let cmp;
+	if (typeof a === "number" && typeof b === "number") cmp = a === b ? 0 : a < b ? -1 : 1;
+	else {
+		const as = String(a);
+		const bs = String(b);
+		cmp = as === bs ? 0 : as < bs ? -1 : 1;
+	}
+	return order === "desc" ? -cmp : cmp;
+}
+/** Keyset predicate mirroring {@link buildOrderedQueryParts}'s WHERE. */
+function keysetAfter(rowSort, rowTie, cursor, order) {
+	const tieAfter = order === "desc" ? rowTie < cursor.tie : rowTie > cursor.tie;
+	if (cursor.sortValue === null) return rowSort === null && tieAfter;
+	if (rowSort === null) return true;
+	const cmp = compareTreeSortValues(rowSort, cursor.sortValue, order);
+	if (cmp !== 0) return cmp > 0;
+	return tieAfter;
+}
+/**
+* Loop reference implementation of `batchPutEntries` — single-op semantics
+* per entry, in order. SQLite/memory indexes delegate here (semantic
+* equivalence with the merged D1 path is pinned by conformance).
+*/
+async function loopBatchPutEntries(index, entries, ctx) {
+	const results = [];
+	for (const { path, entry, opts } of entries) {
+		const existing = ctx?.preread?.has(path) ? ctx.preread.get(path) ?? null : await index.get(path);
+		if (opts.ifMatch !== void 0 && (!existing || existing.cid !== opts.ifMatch)) {
+			results.push({
+				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)) {
+			const wouldBeInline = index.inlineForEntry ? await index.inlineForEntry(entry) : void 0;
+			if (wouldBeInline === void 0 || (existing.content ?? null) === wouldBeInline) {
+				results.push({
+					path,
+					oldCid: existing.cid,
+					skipped: true
+				});
+				continue;
+			}
+		}
+		try {
+			const { oldCid } = await index.put(path, entry, { deviceId: opts.deviceId });
+			const liveSeq = await index.getPrefixWatermark?.(path) ?? void 0;
+			results.push({
+				path,
+				...oldCid !== void 0 ? { oldCid } : {},
+				...typeof liveSeq === "number" && liveSeq > 0 ? { liveSeq } : {}
+			});
+		} catch (err) {
+			const code = err?.code;
+			results.push({
+				path,
+				error: err instanceof Error ? err.message : String(err),
+				...typeof code === "string" ? { code } : {}
+			});
+		}
+	}
+	return results;
+}
+/** Loop reference implementation of `batchDeleteEntries` — see {@link loopBatchPutEntries}. */
+async function loopBatchDeleteEntries(index, entries, ctx) {
+	const results = [];
+	for (const { path, opts } of entries) {
+		const existing = ctx?.preread?.has(path) ? ctx.preread.get(path) ?? null : await index.get(path);
+		if (opts.ifMatch !== void 0 && (!existing || existing.cid !== opts.ifMatch)) {
+			results.push({
+				path,
+				conflict: {
+					currentCid: existing?.cid ?? null,
+					currentMtime: existing?.mtime ?? null,
+					currentDeviceId: null
+				}
+			});
+			continue;
+		}
+		if (!existing) {
+			results.push({
+				path,
+				notFound: true
+			});
+			continue;
+		}
+		try {
+			await index.delete(path, {
+				deviceId: opts.deviceId,
+				...opts.mtime !== void 0 ? { mtime: opts.mtime } : {}
+			});
+			const liveSeq = await index.getPrefixWatermark?.(path) ?? void 0;
+			results.push({
+				path,
+				deletedCid: existing.cid,
+				...typeof liveSeq === "number" && liveSeq > 0 ? { liveSeq } : {}
+			});
+		} catch (err) {
+			results.push({
+				path,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+	return results;
+}
+
+//#endregion
+export { STORAGE_QUOTA_EXCEEDED_CODE, buildKeysetCursor, buildOrderedQueryParts, compareTreeSortValues, keysetAfter, loopBatchDeleteEntries, loopBatchPutEntries, parseTreeCursor, parseTreeEntryMetadata, serializeTreeEntryMetadata, storageQuotaError, treeEntryMetadataEqual };
+//# sourceMappingURL=tree-index.mjs.map

package/dist/tree-index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-index.mjs","names":[],"sources":["../src/tree-index.ts"],"sourcesContent":["/**\n * TreeIndex — typed interface for file metadata indexing.\n *\n * Replaces KeyValueStore for DID Space tree entries.\n * Implementations: MemoryTreeIndex (testing), D1TreeIndex (production).\n */\n\nimport { makeNsLog } from \"@aigne/afs\";\nimport type { DirtyPathRow, ListDirtyPathOptions } from \"./dirty-path-queue.js\";\n\nconst log = makeNsLog(\"provider:did-space\");\n\n/**\n * Stable code on a per-scope quota rejection (file-count OR byte quota,\n * upload-limits Phase 5 / T5.2). Surfaced via the thrown Error's `.code`\n * (single-put/delete) and the batch result entry's `.code` (batchPut) so a\n * consumer can distinguish quota from other failures — previously these were\n * message-only. The message text is preserved verbatim for parity.\n */\nexport const STORAGE_QUOTA_EXCEEDED_CODE = \"STORAGE_QUOTA_EXCEEDED\";\n\n/** Build a quota-rejection Error carrying {@link STORAGE_QUOTA_EXCEEDED_CODE}. */\nexport function storageQuotaError(message: string): Error {\n  return Object.assign(new Error(message), { code: STORAGE_QUOTA_EXCEEDED_CODE });\n}\n\nexport interface TreeEntry {\n  cid: string;\n  size: number;\n  mtime: number;\n  ctime: number;\n  mimeType?: string;\n  /**\n   * Inline copy of the entry's bytes (Layer 0 inline-content capability, see\n   * `inline-content.ts`). cid-verified: when present, `hash(content) === cid`\n   * holds — the cid stays the identity; content is a co-located copy.\n   *\n   * On `put`: an index constructed with `inlineCache: \"on\"` stores text\n   * content ≤ its threshold (verified against cid, mismatch rejected);\n   * default-off indexes ignore the field (byte-identical legacy behavior).\n   * Passing NO content on overwrite clears any prior inline copy — the\n   * column can never go stale relative to the cid.\n   *\n   * On reads: `get` returns it when stored; `listEntries`/`listChildren`\n   * include it ONLY under `{ includeContent: true }` (default projection\n   * stays content-free).\n   */\n  content?: string;\n  /**\n   * Application metadata (planning/agent-hub/metadata-foundation.md).\n   * Stores `AFSWriteEntryPayload.meta` — application-level dimension\n   * fields the application uses for collection-query `meta.*` paths.\n   *\n   * Provider-computed fields (`kind / size / cid / mimeType`) are NOT in\n   * here — they live in their own TreeEntry properties / columns and the\n   * provider merges them on top at read time.\n   *\n   * On `put`: persisted as a JSON blob to the `entries.metadata` column.\n   * Undefined / empty object → stored as NULL.\n   *\n   * On reads: returned exactly as written (after provider-reserved fields\n   * are stripped by the application-layer write path).\n   */\n  metadata?: Record<string, unknown>;\n  /**\n   * Dedup-on-write secondary-index columns (#1159). Together they back the\n   * `(scope, dedup_scope, dedup_key)` partial UNIQUE index that resolves a\n   * dedup write to at-most-one entry — replacing the old cid-in-path scheme.\n   *\n   * - `dedupScope`: the COLLECTION the record dedups within (the write `path`\n   *   argument, e.g. `user/items`). Decoupled from the row's physical `parent`\n   *   so a flat `{coll}/{uuid}.json` and a legacy dir-per-record\n   *   `{coll}/{uuid}/item.json` dedup against the SAME scope.\n   * - `dedupKey`: the normalized identity value (e.g. `normalizeItemUrl(url)`).\n   *\n   * Set ONLY by the provider's dedup write path (and the reindex seam); a plain\n   * write leaves them undefined. On overwrite the SQL upserts COALESCE the\n   * existing value when the incoming entry omits them, so a non-dedup edit of a\n   * dedup row never drops it out of the index.\n   */\n  dedupScope?: string;\n  dedupKey?: string;\n}\n\n/**\n * Parse a raw `entries.metadata` column value back into an object.\n *\n * Contract:\n * - NULL / empty / non-string → undefined (no metadata)\n * - valid JSON object → that object\n * - parse error or non-object JSON → undefined + console.warn (best-effort:\n *   one bad row must not break list/read of the whole collection)\n */\nexport function parseTreeEntryMetadata(raw: unknown): Record<string, unknown> | undefined {\n  if (raw == null) return undefined;\n  if (typeof raw !== \"string\" || raw.length === 0) return undefined;\n  try {\n    const parsed = JSON.parse(raw);\n    if (parsed && typeof parsed === \"object\" && !Array.isArray(parsed)) {\n      return parsed as Record<string, unknown>;\n    }\n    log.warn(`[did-space] entries.metadata is not a JSON object; treating as empty`);\n    return undefined;\n  } catch (err) {\n    const msg = err instanceof Error ? err.message : String(err);\n    log.warn(`[did-space] failed to parse entries.metadata (${msg}); treating as empty`);\n    return undefined;\n  }\n}\n\n/**\n * Serialize a TreeEntry.metadata object for storage in the\n * `entries.metadata` column.\n *\n * Contract:\n * - undefined / null / empty object → null (don't waste a JSON literal)\n * - non-empty object → JSON.stringify result\n */\nexport function serializeTreeEntryMetadata(\n  metadata: Record<string, unknown> | undefined,\n): string | null {\n  if (metadata == null) return null;\n  const keys = Object.keys(metadata);\n  if (keys.length === 0) return null;\n  return JSON.stringify(metadata);\n}\n\n/** Order-insensitive deep equality: object keys are unordered, array order matters. */\nfunction deepEqual(a: unknown, b: unknown): boolean {\n  if (a === b) return true;\n  if (a === null || b === null || typeof a !== \"object\" || typeof b !== \"object\") return false;\n  const aArr = Array.isArray(a);\n  const bArr = Array.isArray(b);\n  if (aArr !== bArr) return false;\n  if (aArr && bArr) {\n    if (a.length !== b.length) return false;\n    for (let i = 0; i < a.length; i++) if (!deepEqual(a[i], b[i])) return false;\n    return true;\n  }\n  const ao = a as Record<string, unknown>;\n  const bo = b as Record<string, unknown>;\n  const ak = Object.keys(ao);\n  if (ak.length !== Object.keys(bo).length) return false;\n  for (const k of ak) {\n    if (!Object.hasOwn(bo, k)) return false;\n    if (!deepEqual(ao[k], bo[k])) return false;\n  }\n  return true;\n}\n\n/**\n * Are two TreeEntry.metadata objects equivalent for skip-if-unchanged purposes?\n * (did-space-metadata G4). This MUST be order-insensitive for object keys —\n * {@link serializeTreeEntryMetadata} is a bare `JSON.stringify` that preserves\n * insertion order, so its string equality would treat a key reorder as a\n * \"change\" and forge a phantom changelog row / sync churn (the very thing skip\n * exists to avoid). Empty / null / undefined all compare equal because they all\n * serialize to a NULL column. Used ONLY for the skip decision; storage still\n * uses {@link serializeTreeEntryMetadata} verbatim.\n */\nexport function treeEntryMetadataEqual(\n  a: Record<string, unknown> | undefined | null,\n  b: Record<string, unknown> | undefined | null,\n): boolean {\n  const aEmpty = a == null || Object.keys(a).length === 0;\n  const bEmpty = b == null || Object.keys(b).length === 0;\n  if (aEmpty || bEmpty) return aEmpty && bEmpty;\n  return deepEqual(a, b);\n}\n\nexport interface TreeIndexListOptions {\n  limit?: number;\n  cursor?: string;\n  /**\n   * Include each entry's inline `content` (when stored) in the result.\n   * Default OFF — the default SELECT never touches the content column, so\n   * every existing list path is zero-regression, zero extra bytes. Entries\n   * without an inline copy come back without `content` (best-effort).\n   */\n  includeContent?: boolean;\n  /**\n   * Sort column. `name` is `listChildren`'s historical hardcoded default,\n   * now explicit (the `entries` table has a `name` column, so `list` /\n   * `listEntries` map it naturally too).\n   *\n   * Semantics when set (all three impls, enforced by\n   * `test/tree-index-order.test.ts`):\n   * - tiebreak on the listing's unique key (`name` for `listChildren`,\n   *   `path` for `list`/`listEntries`), same direction;\n   * - missing values (NULL `mime_type`) sort LAST regardless of direction;\n   * - the resume cursor is the keyset v2 format (`v2:<b64>:<b64>`, see\n   *   {@link buildKeysetCursor}) so duplicate sort values never skip rows\n   *   across a page boundary;\n   * - a legacy (non-v2) cursor combined with `orderBy` is rejected.\n   *\n   * When UNSET the listing keeps its historical byte-identical behavior:\n   * `listChildren` orders by `name` with a plain name-string cursor;\n   * `list`/`listEntries` order by `path` with a plain sort-value cursor.\n   */\n  orderBy?: \"path\" | \"mtime\" | \"size\" | \"ctime\" | \"mimeType\" | \"name\";\n  order?: \"asc\" | \"desc\";\n}\n\n// ========== Keyset cursor v2 (did-space-sorting Phase 2) ==========\n\n/** Decoded keyset cursor: the last row's sort value + unique tiebreak value. */\nexport interface TreeKeysetCursor {\n  /** Raw sort-column value of the last row; `null` for NULL (missing) values. */\n  sortValue: string | number | null;\n  /** Unique tiebreak value of the last row (`name` or `path`). */\n  tie: string;\n}\n\n/** UTF-8 safe base64 (btoa alone corrupts non-latin1 file names). */\nfunction b64encode(s: string): string {\n  const bytes = new TextEncoder().encode(s);\n  let bin = \"\";\n  for (const b of bytes) bin += String.fromCharCode(b);\n  return btoa(bin);\n}\n\nfunction b64decode(s: string): string {\n  const bin = atob(s);\n  return new TextDecoder().decode(Uint8Array.from(bin, (c) => c.charCodeAt(0)));\n}\n\n/** Build a v2 keyset cursor: `v2:<b64(json(sortValue))>:<b64(tie)>`. */\nexport function buildKeysetCursor(sortValue: string | number | null, tie: string): string {\n  return `v2:${b64encode(JSON.stringify(sortValue))}:${b64encode(tie)}`;\n}\n\nexport type ParsedTreeCursor =\n  | { kind: \"none\" }\n  | { kind: \"legacy\"; value: string }\n  | { kind: \"v2\"; cursor: TreeKeysetCursor };\n\n/**\n * Parse a list cursor. Shared by all three TreeIndex impls so the\n * legacy-vs-v2 dance can never drift between them.\n *\n * - undefined → none\n * - `v2:`-prefixed → keyset cursor; REQUIRES `hasOrderBy` (a keyset cursor\n *   replayed onto a default-order listing would be a wrong page); malformed\n *   payloads throw a clean error instead of producing a wrong page.\n * - anything else → legacy plain cursor, accepted ONLY for default\n *   (no-orderBy) order.\n */\nexport function parseTreeCursor(cursor: string | undefined, hasOrderBy: boolean): ParsedTreeCursor {\n  if (!cursor) return { kind: \"none\" };\n  if (cursor.startsWith(\"v2:\")) {\n    if (!hasOrderBy) {\n      throw new Error(\"Invalid cursor: v2 keyset cursor requires a matching orderBy\");\n    }\n    const parts = cursor.split(\":\");\n    if (parts.length !== 3 || !parts[1] || !parts[2]) {\n      throw new Error(\"Invalid cursor: malformed v2 keyset cursor\");\n    }\n    let sortValue: unknown;\n    let tie: string;\n    try {\n      sortValue = JSON.parse(b64decode(parts[1]));\n      tie = b64decode(parts[2]);\n    } catch {\n      throw new Error(\"Invalid cursor: malformed v2 keyset cursor\");\n    }\n    if (sortValue !== null && typeof sortValue !== \"string\" && typeof sortValue !== \"number\") {\n      throw new Error(\"Invalid cursor: malformed v2 keyset cursor\");\n    }\n    return { kind: \"v2\", cursor: { sortValue, tie } };\n  }\n  if (hasOrderBy) {\n    throw new Error(\"Invalid cursor: legacy cursor cannot be combined with orderBy\");\n  }\n  return { kind: \"legacy\", value: cursor };\n}\n\n/** SQL fragments for an ordered, keyset-resumable listing. */\nexport interface OrderedQueryParts {\n  /** Extra WHERE condition (empty string when no cursor). */\n  cursorWhereSql: string;\n  cursorArgs: Array<string | number>;\n  /** ORDER BY clause body (without the `ORDER BY` keyword). */\n  orderSql: string;\n}\n\n/**\n * Build the ORDER BY + keyset-resume WHERE for an ordered listing. Shared\n * by SQLiteTreeIndex and D1TreeIndex (identical SQL dialect).\n *\n * - Missing values sort LAST regardless of direction: nullable columns get\n *   a leading `(col IS NULL) ASC` term. Non-nullable columns skip it so the\n *   `(scope, parent, col, name)` indexes stay usable.\n * - Resume uses the expansion `col > ? OR (col = ? AND tie > ?)` (row-value\n *   free — works on every SQLite the runtimes target) plus NULL-run\n *   handling for nullable columns.\n */\nexport function buildOrderedQueryParts(opts: {\n  col: string;\n  nullable: boolean;\n  order: \"asc\" | \"desc\";\n  tieCol: string;\n  cursor?: TreeKeysetCursor;\n}): OrderedQueryParts {\n  const { col, nullable, tieCol, cursor } = opts;\n  const dir = opts.order === \"desc\" ? \"DESC\" : \"ASC\";\n  const op = opts.order === \"desc\" ? \"<\" : \">\";\n  const orderSql = nullable\n    ? `(${col} IS NULL) ASC, ${col} ${dir}, ${tieCol} ${dir}`\n    : `${col} ${dir}, ${tieCol} ${dir}`;\n\n  if (!cursor) {\n    return { cursorWhereSql: \"\", cursorArgs: [], orderSql };\n  }\n  if (cursor.sortValue === null) {\n    if (!nullable) {\n      throw new Error(\"Invalid cursor: malformed v2 keyset cursor\");\n    }\n    // Resuming inside the trailing NULL run: only NULL rows past the tie.\n    return {\n      cursorWhereSql: `(${col} IS NULL AND ${tieCol} ${op} ?)`,\n      cursorArgs: [cursor.tie],\n      orderSql,\n    };\n  }\n  if (nullable) {\n    // Non-null cursor on a nullable column: the rest of the non-null run,\n    // then the entire NULL tail (NULLs sort last in BOTH directions).\n    return {\n      cursorWhereSql: `((${col} IS NOT NULL AND (${col} ${op} ? OR (${col} = ? AND ${tieCol} ${op} ?))) OR ${col} IS NULL)`,\n      cursorArgs: [cursor.sortValue, cursor.sortValue, cursor.tie],\n      orderSql,\n    };\n  }\n  return {\n    cursorWhereSql: `(${col} ${op} ? OR (${col} = ? AND ${tieCol} ${op} ?))`,\n    cursorArgs: [cursor.sortValue, cursor.sortValue, cursor.tie],\n    orderSql,\n  };\n}\n\n/**\n * In-memory equivalents of the SQL ordering semantics, used by\n * MemoryTreeIndex so all three impls stay in lockstep.\n */\nexport function compareTreeSortValues(\n  a: string | number | null,\n  b: string | number | null,\n  order: \"asc\" | \"desc\",\n): number {\n  // Missing sorts LAST regardless of direction.\n  if (a === null && b === null) return 0;\n  if (a === null) return 1;\n  if (b === null) return -1;\n  let cmp: number;\n  if (typeof a === \"number\" && typeof b === \"number\") {\n    cmp = a === b ? 0 : a < b ? -1 : 1;\n  } else {\n    const as = String(a);\n    const bs = String(b);\n    cmp = as === bs ? 0 : as < bs ? -1 : 1;\n  }\n  return order === \"desc\" ? -cmp : cmp;\n}\n\n/** Keyset predicate mirroring {@link buildOrderedQueryParts}'s WHERE. */\nexport function keysetAfter(\n  rowSort: string | number | null,\n  rowTie: string,\n  cursor: TreeKeysetCursor,\n  order: \"asc\" | \"desc\",\n): boolean {\n  const tieAfter = order === \"desc\" ? rowTie < cursor.tie : rowTie > cursor.tie;\n  if (cursor.sortValue === null) {\n    // Cursor in the NULL tail → only later NULL rows remain.\n    return rowSort === null && tieAfter;\n  }\n  if (rowSort === null) return true; // NULL tail comes after every non-null row\n  const cmp = compareTreeSortValues(rowSort, cursor.sortValue, order);\n  if (cmp !== 0) return cmp > 0;\n  return tieAfter;\n}\n\nexport interface TreeIndexListResult {\n  entries: Array<{ path: string }>;\n  hasMore: boolean;\n  cursor?: string;\n}\n\nexport interface TreeIndexListEntriesResult {\n  entries: Array<{ path: string } & TreeEntry>;\n  hasMore: boolean;\n  cursor?: string;\n}\n\n/**\n * Options for mutation methods (Task 2.4a — atomic changelog write).\n *\n * Every put/delete/putBatch/deleteByPrefix call carries:\n *   - `deviceId`: opaque per-device identifier persisted into the changelog row.\n *                 Required, non-empty, ≤ 128 bytes. Validated at runtime by\n *                 `validateDeviceId()` in `changelog-write.ts`.\n *   - `skipChangelog`: when `true`, the underlying TreeIndex writes the `entries`\n *                 row but skips the corresponding `changelog` INSERT. Used by\n *                 Task 2.4b to exempt blocklet-publish CLI uploads (the publish\n *                 flow is already batched and does not need per-file sync fan-out).\n *\n * Strict-TypeScript design: `opts` is a REQUIRED trailing parameter on every\n * mutation method (see `tree-index.ts`). Callers that go through the `TreeIndex`\n * interface (e.g. `CloudflareDIDSpace`, `DIDSpaceProvider`) get a compile-time\n * error if they omit `opts` — that is the enforcement point for Phase 2 sync.\n */\nexport interface PutOpts {\n  /** Required. Non-empty string ≤ 128 bytes. Written into `changelog.device_id`. */\n  deviceId: string;\n  /**\n   * Optional client mtime (unix millis) written into `changelog.mtime` for\n   * delete/deleteByPrefix rows (T1.5). When absent, implementations fall back to\n   * the server clock (`Date.now()`). `put` carries its mtime via the `TreeEntry`,\n   * so this only affects the delete paths where there is no entry to read it from.\n   */\n  mtime?: number;\n  /** When `true`, skip the `changelog` INSERT. Default `false`. */\n  skipChangelog?: boolean;\n}\n\n/**\n * In-memory shape of a `changelog` row.\n *\n * Matches the D1/libsql row shape 1:1 so MemoryTreeIndex tests can assert\n * against the same fields that production code will see on the wire. Exposed\n * via `MemoryTreeIndex.getChangelogSnapshot()` for unit tests.\n */\nexport interface ChangelogEntry {\n  /** Monotonically increasing row ID (1-based in MemoryTreeIndex; AUTOINCREMENT in D1). */\n  seq: number;\n  scope: string;\n  path: string;\n  op: \"put\" | \"delete\";\n  /** `null` on delete rows; non-null on put rows. */\n  cid: string | null;\n  /** `null` on first write; prior cid on overwrite/delete. */\n  old_cid: string | null;\n  /** `null` on delete rows; file size on put rows. */\n  size: number | null;\n  mtime: number;\n  device_id: string;\n}\n\n// ───────────────── batch sync fast path (afs-rpc-batch P3) ─────────────────\n//\n// NOTE: deliberately distinct from the legacy `putBatch` (reconcile/rsync):\n// putBatch returns void, shares ONE opts across the batch, has no\n// skip-if-unchanged / oldCid / conflict semantics, and bumps the watermark\n// once per collection root. The sync batch contract below is per-entry\n// throughout, and its watermark semantics match the single `put` (+1 per\n// write, each entry carrying back its own seq for change-event re-emission).\n\n/** Per-entry options for the batch sync fast path. */\nexport interface BatchEntryOpts {\n  /** Required. Written into `changelog.device_id` (echo prevention / LWW). */\n  deviceId: string;\n  /** Client mtime for DELETE changelog rows (put rows take mtime from the entry). */\n  mtime?: number;\n  /** Optimistic-concurrency precondition against the current entry cid. */\n  ifMatch?: string;\n}\n\nexport interface BatchPutEntry {\n  path: string;\n  entry: TreeEntry;\n  opts: BatchEntryOpts;\n}\n\nexport interface BatchDeleteEntry {\n  path: string;\n  opts: BatchEntryOpts;\n}\n\n/** Conflict triple — mirrors the single-op AFSConflictError fields\n *  (deviceId is null, exactly like the single write path which never reads it). */\nexport interface BatchEntryConflict {\n  currentCid: string | null;\n  currentMtime: number | null;\n  currentDeviceId: string | null;\n}\n\nexport interface BatchPutEntryResult {\n  path: string;\n  /** Prior cid when the path existed (drives the caller's GC enqueue). */\n  oldCid?: string;\n  /** Skip-if-unchanged hit: same cid+mimeType — no changelog row, no watermark bump. */\n  skipped?: boolean;\n  /** Present iff the entry failed its ifMatch precondition (nothing written). */\n  conflict?: BatchEntryConflict;\n  /** Non-conflict per-entry failure (e.g. quota) — message parity with single put. */\n  error?: string;\n  /**\n   * Stable code for a non-conflict failure (upload-limits Phase 5):\n   * `STORAGE_QUOTA_EXCEEDED` on a file-count OR byte-quota rejection. Lets a\n   * consumer distinguish quota from other per-entry errors (the single-put path\n   * carries it on the thrown Error's `.code`).\n   */\n  code?: string;\n  /** This entry's own watermark seq (+1 per write, batch-order ascending).\n   *  Absent for skip/conflict/error entries and root-level paths (no collection root). */\n  liveSeq?: number;\n}\n\nexport interface BatchDeleteEntryResult {\n  path: string;\n  /** The deleted entry's cid (drives the caller's GC enqueue). */\n  deletedCid?: string;\n  /** Path had no file entry — per-entry not-found, never aborts neighbors. */\n  notFound?: boolean;\n  conflict?: BatchEntryConflict;\n  error?: string;\n  liveSeq?: number;\n}\n\n/** Shared context: a caller-supplied preread snapshot (one IN query reused\n *  across the provider's preflight AND the index batch — design §4.3). */\nexport interface BatchIndexContext {\n  preread?: Map<string, TreeEntry | null>;\n}\n\n/**\n * Loop reference implementation of `batchPutEntries` — single-op semantics\n * per entry, in order. SQLite/memory indexes delegate here (semantic\n * equivalence with the merged D1 path is pinned by conformance).\n */\nexport async function loopBatchPutEntries(\n  index: TreeIndex,\n  entries: BatchPutEntry[],\n  ctx?: BatchIndexContext,\n): Promise<BatchPutEntryResult[]> {\n  const results: BatchPutEntryResult[] = [];\n  for (const { path, entry, opts } of entries) {\n    const existing = ctx?.preread?.has(path)\n      ? (ctx.preread.get(path) ?? null)\n      : await index.get(path);\n    if (opts.ifMatch !== undefined && (!existing || existing.cid !== opts.ifMatch)) {\n      results.push({\n        path,\n        conflict: {\n          currentCid: existing?.cid ?? null,\n          currentMtime: existing?.mtime ?? null,\n          currentDeviceId: null,\n        },\n      });\n      continue;\n    }\n    if (\n      existing &&\n      existing.cid === entry.cid &&\n      existing.mimeType === entry.mimeType &&\n      treeEntryMetadataEqual(existing.metadata, entry.metadata)\n    ) {\n      // Metadata-aware skip (did-space-metadata G4): a metadata-only overwrite\n      // keeps the same cid, so without this clause it would be wrongly skipped.\n      // Content-aware skip (mirror D1TreeIndex.batchPutEntries `:316`): when the\n      // index tracks inline content, skip ONLY if the stored column already\n      // matches what this write would store; an out-of-sync inline copy falls\n      // through to put() so the UPSERT re-fills it (closing the latent loop↔D1\n      // divergence). Indexes without inline support keep the legacy cid+mime skip.\n      const wouldBeInline = index.inlineForEntry ? await index.inlineForEntry(entry) : undefined;\n      if (wouldBeInline === undefined || (existing.content ?? null) === wouldBeInline) {\n        results.push({ path, oldCid: existing.cid, skipped: true });\n        continue;\n      }\n      // out of sync — fall through to put() to re-fill the inline column.\n    }\n    try {\n      const { oldCid } = await index.put(path, entry, { deviceId: opts.deviceId });\n      const liveSeq = (await index.getPrefixWatermark?.(path)) ?? undefined;\n      results.push({\n        path,\n        ...(oldCid !== undefined ? { oldCid } : {}),\n        ...(typeof liveSeq === \"number\" && liveSeq > 0 ? { liveSeq } : {}),\n      });\n    } catch (err) {\n      // Forward a stable `.code` (e.g. STORAGE_QUOTA_EXCEEDED from the byte/file\n      // quota) so a batch consumer can distinguish quota from other failures —\n      // parity with D1TreeIndex.batchPutEntries' explicit per-entry code.\n      const code = (err as { code?: unknown })?.code;\n      results.push({\n        path,\n        error: err instanceof Error ? err.message : String(err),\n        ...(typeof code === \"string\" ? { code } : {}),\n      });\n    }\n  }\n  return results;\n}\n\n/** Loop reference implementation of `batchDeleteEntries` — see {@link loopBatchPutEntries}. */\nexport async function loopBatchDeleteEntries(\n  index: TreeIndex,\n  entries: BatchDeleteEntry[],\n  ctx?: BatchIndexContext,\n): Promise<BatchDeleteEntryResult[]> {\n  const results: BatchDeleteEntryResult[] = [];\n  for (const { path, opts } of entries) {\n    const existing = ctx?.preread?.has(path)\n      ? (ctx.preread.get(path) ?? null)\n      : await index.get(path);\n    if (opts.ifMatch !== undefined && (!existing || existing.cid !== opts.ifMatch)) {\n      results.push({\n        path,\n        conflict: {\n          currentCid: existing?.cid ?? null,\n          currentMtime: existing?.mtime ?? null,\n          currentDeviceId: null,\n        },\n      });\n      continue;\n    }\n    if (!existing) {\n      results.push({ path, notFound: true });\n      continue;\n    }\n    try {\n      await index.delete(path, {\n        deviceId: opts.deviceId,\n        ...(opts.mtime !== undefined ? { mtime: opts.mtime } : {}),\n      });\n      const liveSeq = (await index.getPrefixWatermark?.(path)) ?? undefined;\n      results.push({\n        path,\n        deletedCid: existing.cid,\n        ...(typeof liveSeq === \"number\" && liveSeq > 0 ? { liveSeq } : {}),\n      });\n    } catch (err) {\n      results.push({ path, error: err instanceof Error ? err.message : String(err) });\n    }\n  }\n  return results;\n}\n\nexport interface TreeIndex {\n  /**\n   * Read a single file's metadata. `includeContent` (default true) projects the\n   * inline `content` copy; metadata-only callers (stat / list / readMeta) pass\n   * `false` to skip marshalling the inline bytes. A projection hint — an\n   * in-memory backend may still return content (zero marshalling cost there).\n   */\n  get(path: string, opts?: { includeContent?: boolean }): Promise<TreeEntry | null>;\n\n  /**\n   * Read a directory row's own `ctime`/`mtime`. Directory rows are scaffolded\n   * by the put path (`ancestorDirs` + `buildDirChainStmt`) with no `cid`, so\n   * {@link get} — which returns null for cid-less rows — never surfaces them.\n   * This is the read used to expose a directory's created/modified time on\n   * `stat` (the file path already returns them via {@link get}).\n   *\n   * `dirPath` is the trailing-slash index key (e.g. `user/photos/`), i.e. the\n   * value {@link treeListPrefix} produces. Returns null for a directory with\n   * no scaffolded row (the absolute scope root, or an as-yet-unwritten dir).\n   *\n   * Optional: callers MUST guard and simply omit the timestamps when an\n   * implementation does not provide it.\n   */\n  getDirTimes?(dirPath: string): Promise<{ ctime: number; mtime: number } | null>;\n\n  /**\n   * Batch metadata read for the sync fast path's ONE-query preflight\n   * (afs-rpc-batch §4.3). Returns a map with an entry for EVERY requested\n   * path (`null` when absent). Optional: callers fall back to per-path `get`.\n   */\n  getMany?(paths: string[]): Promise<Map<string, TreeEntry | null>>;\n\n  /**\n   * Batch `get(filePath)` + `hasChildren(dirPrefix)` in a single storage\n   * round-trip. Used by `readHandler` to cut miss-path D1 calls in half:\n   * a non-existent file previously paid `get` + `hasChildren` sequentially\n   * (2 HTTP round-trips); this collapses both into one batch call.\n   * Optional — callers fall back to sequential `get` + `hasChildren` when absent.\n   */\n  getAndHasChildren?(filePath: string, dirPrefix: string): Promise<[TreeEntry | null, boolean]>;\n\n  /**\n   * Batch sync fast path (afs-rpc-batch P3) — per-entry opts\n   * (deviceId/mtime/ifMatch) and per-entry results (oldCid / skipped /\n   * conflict / liveSeq). Entries arrive with UNIQUE paths (the core splits\n   * duplicate-path batches) so a one-shot preread is serial-equivalent.\n   * Watermark semantics match single `put`: +1 per written entry, each\n   * result carrying its own seq. See the section comment above for why this\n   * is NOT the legacy `putBatch`.\n   */\n  batchPutEntries?(\n    entries: BatchPutEntry[],\n    ctx?: BatchIndexContext,\n  ): Promise<BatchPutEntryResult[]>;\n\n  /** Delete twin of {@link batchPutEntries}. FILE entries only (no dir fallback). */\n  batchDeleteEntries?(\n    entries: BatchDeleteEntry[],\n    ctx?: BatchIndexContext,\n  ): Promise<BatchDeleteEntryResult[]>;\n\n  /** Write/update file metadata (ctime preserved by implementation). Returns previous CID if entry existed. */\n  put(path: string, entry: TreeEntry, opts: PutOpts): Promise<{ oldCid?: string }>;\n\n  /**\n   * Dedup-on-write lookup (#1159): resolve the single entry whose\n   * `(dedup_scope, dedup_key)` matches within this scope, or `null`. Backed by\n   * the `(scope, dedup_scope, dedup_key)` partial UNIQUE index → O(log n) point\n   * seek, never a `json_extract` full scan. Returns the entry's REAL path so the\n   * provider can merge into it in place.\n   *\n   * Optional during rollout: a TreeIndex without it makes the owning provider\n   * treat `dedupBy` writes as unsupported (explicit error, never silent).\n   */\n  findByDedupKey?(\n    dedupScope: string,\n    dedupKey: string,\n  ): Promise<({ path: string } & TreeEntry) | null>;\n\n  /**\n   * Populate the dedup columns of an EXISTING row WITHOUT rewriting its\n   * content/cid or emitting a changelog row — the one-time reindex/backfill seam\n   * (#1159, deferred script). Index-only UPDATE keyed on `(scope, path)`. No-op\n   * if the path has no row. Optional: reindex callers guard on its presence.\n   */\n  setDedupKey?(path: string, dedupScope: string, dedupKey: string, opts: PutOpts): Promise<void>;\n\n  /**\n   * Resolve the inline `content` this entry WOULD store under the index's\n   * configured inline policy (or `null` for \"store NULL\"). Exposed so\n   * {@link loopBatchPutEntries} can mirror D1's content-aware skip — a cid+mime\n   * match whose inline column is out of sync must fall through to `put()` to\n   * self-repair, instead of being early-skipped. Optional: indexes without\n   * inline support omit it and the loop keeps the legacy cid+mime skip.\n   */\n  inlineForEntry?(entry: TreeEntry): Promise<string | null>;\n\n  /** Delete a single file */\n  delete(path: string, opts: PutOpts): Promise<void>;\n\n  /** List entries under a prefix (for directory browsing) */\n  list(prefix: string, options?: TreeIndexListOptions): Promise<TreeIndexListResult>;\n\n  /** List entries with full metadata under a prefix */\n  listEntries(prefix: string, options?: TreeIndexListOptions): Promise<TreeIndexListEntriesResult>;\n\n  /** Check if prefix has any child entries (directory existence) */\n  hasChildren(prefix: string): Promise<boolean>;\n\n  /** Count entries under a prefix (exact value) */\n  count(prefix: string): Promise<number>;\n\n  /** Bulk-delete all entries under a prefix, return count deleted */\n  deleteByPrefix(prefix: string, opts: PutOpts): Promise<number>;\n\n  // ========== v2 methods (Phase 0) ==========\n\n  /** List direct children of a parent directory (uses parent index) */\n  listChildren(parent: string, options?: TreeIndexListOptions): Promise<TreeIndexListEntriesResult>;\n\n  /** Count direct children of a parent directory (exact, O(log n)) */\n  countChildren(parent: string): Promise<number>;\n\n  /**\n   * Count direct children for EACH of the given parent directories in one\n   * round-trip, returned as `Map<parentPath, count>` keyed by the same path\n   * form `listChildren` yields for a directory child (trailing-slash, and —\n   * for {@link PrefixedTreeIndex} — prefix-stripped).\n   *\n   * PAGE-BOUNDED by contract: callers pass only the directories on the page\n   * being listed, so the cost is Σ direct children of those dirs. This\n   * replaces the retired subtree-wide `countChildrenGrouped(prefix)`, whose\n   * `parent >= lo AND parent < hi` range scanned EVERY descendant (all\n   * depths) under the listed prefix on every list — ~100M+ D1 rows_read/day\n   * once a hot collection grew to ~1k dirs (2026-06 free-tier exhaustion).\n   *\n   * Optional: callers MUST fall back to per-path {@link countChildren} when\n   * an implementation does not provide it. The returned map omits empty\n   * directories (count 0) — look up with `map.get(path) ?? 0`.\n   */\n  countChildrenMany?(parents: string[]): Promise<Map<string, number>>;\n\n  /** Get aggregate stats (file count + total size) for a prefix */\n  aggregate(prefix: string): Promise<{ fileCount: number; totalSize: number }>;\n\n  /** Batch write entries in a transaction */\n  putBatch(entries: Array<{ path: string; entry: TreeEntry }>, opts: PutOpts): Promise<void>;\n\n  /** List entries modified since a timestamp */\n  listModifiedSince(\n    prefix: string,\n    since: number,\n    options?: TreeIndexListOptions,\n  ): Promise<TreeIndexListEntriesResult>;\n\n  /**\n   * Return the maximum changelog seq for this scope.\n   * Used by `DIDSpaceProvider.list(path, { maxDepth: -1 })` to include\n   * the snapshot waterline in `meta.cursor`. Returns 0 when the changelog\n   * is empty (no writes have been recorded yet).\n   */\n  getMaxSeq(): Promise<number>;\n\n  /**\n   * Read the per-prefix watermark `version` for a collection root (Live Update\n   * Resilience §11.4). `prefix` is a scope-relative path; the implementation\n   * reduces it to its first path segment (the `/user` first-level collection\n   * root) and returns that row's `version`, or `0` when no row exists yet\n   * (\"nothing written under this collection root\").\n   *\n   * This is the O(1) change-detector that web reconcile reads on every\n   * connection edge: it never scans the changelog and never grows with history\n   * or global write volume. Optional during rollout — a TreeIndex without it\n   * leaves the owning provider unable to emit `liveSeq` (consumer falls back to\n   * full re-list on every edge/poll, still correct).\n   *\n   * Tri-state return:\n   * - `null`  — the path has no collection root (no watermark key): the owner\n   *   emits NO `liveSeq`, consumers stay on the conservative full-refetch path.\n   * - `0`     — valid collection root with no writes yet: the owner emits\n   *   `liveSeq: \"0\"` so consumers baseline at 0 and DON'T refetch every poll\n   *   tick on a read-only collection (the first write bumps to 1 > 0).\n   * - `>0`    — the row's version.\n   */\n  getPrefixWatermark?(prefix: string): Promise<number | null>;\n\n  /**\n   * Return changelog rows with `seq > sinceSeq` (ascending), capped at `limit`.\n   *\n   * `cursor` is the highest **inner** seq this scan observed — NOT the seq of\n   * the last returned entry. This distinction matters for {@link\n   * PrefixedTreeIndex}: when a prefix filter drops every row on a page, the page\n   * returns `entries: []` but `cursor` still advances to the max inner seq so\n   * the caller never re-requests the same window (no infinite loop on empty\n   * pages). `hasMore` follows the inner pagination (\"are there more inner rows\n   * with seq > cursor\"), not \"are there more rows under this prefix\".\n   *\n   * On an empty changelog (or no rows past `sinceSeq`) returns\n   * `{ entries: [], hasMore: false, cursor: sinceSeq }` — cursor never goes\n   * backwards.\n   */\n  getChangelogSince(\n    sinceSeq: number,\n    limit: number,\n  ): Promise<{ entries: ChangelogEntry[]; hasMore: boolean; cursor: number }>;\n\n  /**\n   * Compaction watermark for this scope (Phase 1 of changelog compaction).\n   * Returns 0 when no compaction has ever run (safe permissive default).\n   */\n  getCompactedBelowSeq?(): Promise<number>;\n\n  /**\n   * Collection query over DIRECT children of `parent` (afs-collection-query\n   * Phase 1, design §3.5): typed where σ on the record document (doc-joined\n   * for dir-per-record, inline content for file-per-record), entry-column\n   * orderBy, exact post-WHERE total, keyset/offset pagination, groupBy\n   * counting. Spec semantics are locked to the core reference evaluator by\n   * conformance + the cross-backend lockstep test (`tree-query.ts`).\n   *\n   * Optional during rollout: implementations without it leave the owning\n   * provider undeclared (the root action then fails AFS_UNSUPPORTED).\n   */\n  query?(\n    parent: string,\n    spec: import(\"./tree-query.js\").TreeQuerySpec,\n  ): Promise<import(\"./tree-query.js\").TreeQueryResult>;\n\n  /**\n   * True if `cid` is referenced within THIS index's VIEW (read-**auth**,\n   * design §4.1) — three-way `entries.cid ∪ changelog.cid ∪ changelog.old_cid`,\n   * always `WHERE scope = ?`.\n   *\n   * `pathPrefix` (default `\"\"`) restricts the check to a sub-tree\n   * (`path >= lo AND path < hi`). {@link PrefixedTreeIndex} passes its own\n   * prefix so a blocklet/role provider authorizes ONLY cids its own fragment\n   * references (P0#2 blocklet isolation); the unprefixed space-root provider\n   * leaves it `\"\"` and stays whole-scope.\n   *\n   * This is the authorization check, distinct from the scope-blind,\n   * entries-only GC-liveness check `referencedAnywhere` (design §3, §4.4b).\n   * Returns false for empty `cid`.\n   */\n  isReferenced(cid: string, pathPrefix?: string): Promise<boolean>;\n\n  /**\n   * Batch read-auth (download plane, design §7.2): given a set of cids, return\n   * the SUBSET that is referenced within THIS index's VIEW — exactly the cids\n   * for which {@link isReferenced} would return `true`. A cid NOT in the result\n   * is `forbidden` (covers both unreferenced AND not-found — never distinguish).\n   *\n   * MUST be three-way-equivalent to per-cid `isReferenced`\n   * (`entries.cid ∪ changelog.cid ∪ changelog.old_cid`, scope-aware, optionally\n   * prefix-local) — a superseded cid that left `entries` but lives in\n   * `changelog.old_cid` MUST still be returned, or the read-auth invariant\n   * breaks (design Finding 2). The SQL backends shard the `IN (?,…)` list to\n   * stay under the bound-parameter cap (D1 = 100; the three-way UNION binds each\n   * cid 3×, so the per-query cid budget is small). Empty input → empty set, no\n   * query (avoid `IN ()`).\n   */\n  isReferencedMany(cids: string[], pathPrefix?: string): Promise<Set<string>>;\n\n  // ========== Source-side dirty queue (index-follower-dirty-path) ==========\n  //\n  // The `ds_dirty_path` projection of the changelog, drained by the index\n  // follower instead of replaying `/.changelog` (design §7). These three form\n  // the {@link import(\"./dirty-path-queue.js\").DirtyPathQueue} contract; a\n  // TreeIndex that implements all three IS a DirtyPathQueue structurally. They\n  // are RUNTIME-INTERNAL (never a public `/user` AFS action — design §7\n  // security boundary). Optional during rollout: raw backends (D1/SQLite/Memory)\n  // serve full-path rows; {@link PrefixedTreeIndex} adds the prefix on the way\n  // in and strips it off the returned `path`.\n\n  /** Ready dirty rows under `prefix` with `next_attempt_at <= now`, capped at `limit`. */\n  listDirtyPaths?(options: ListDirtyPathOptions): Promise<DirtyPathRow[]>;\n\n  /** Guarded ack: delete the dirty row iff its `latest_seq` still equals `latestSeq`. */\n  ackDirtyPath?(path: string, latestSeq: number): Promise<boolean>;\n\n  /** Guarded failure record: bump attempts + set last_error/next_attempt_at on the matching row. */\n  markDirtyPathError?(\n    path: string,\n    latestSeq: number,\n    error: string,\n    nextAttemptAt: number,\n  ): Promise<boolean>;\n}\n"],"mappings":"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"}