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

package/dist/tree-query.mjs

@@ -0,0 +1,648 @@
+import { buildKeysetCursor, buildOrderedQueryParts, compareTreeSortValues, keysetAfter, parseTreeCursor, parseTreeEntryMetadata } from "./tree-index.mjs";
+import { AFSValidationError, TIME_BUCKET_KEY, aggregateGroupKeyNames, evaluateCollectionQuery, normalizeWhere, resolveFieldPath, whereMatchesItem } from "@aigne/afs";
+
+//#region src/tree-query.ts
+/**
+* TreeQuery — the shared collection-query engine for the did-space TreeIndex
+* family (afs-collection-query Phase 1, design §3.5).
+*
+* One compilation layer, three executors:
+* - SQL builder (`buildTreeQueryStatements`) shared verbatim by
+*   SQLiteTreeIndex and (Phase 2) D1TreeIndex — identical dialect
+*   (json_extract / json_each / json_type all available on both).
+* - JS executor (`runTreeQueryInMemory`) for MemoryTreeIndex, built on the
+*   SAME helpers the SQL path uses for ordering/keyset (`tree-index.ts`) and
+*   the canonical core `where` semantics (`whereMatches` from @aigne/afs) —
+*   conformance + the lockstep test pin all backends to one behavior.
+*
+* Semantics contract (must match `evaluateCollectionQuery` in @aigne/afs):
+* - string comparisons fold case; numbers/booleans are type-strict
+* - `notIn` includes records where the field is missing/null
+* - `contains` requires an array field; missing/non-array never match
+* - groupBy unnests arrays; missing/null/non-primitive group under `null`;
+*   string group keys are folded to lower case
+* - keyset cursor: v2 format shared with list (`v2:<b64>:<b64>`), tie on the
+*   child's unique `name`; WHERE applies before pagination so total is the
+*   exact filtered count
+*/
+const ENGINE_ORDER_COLUMNS = {
+	name: "name",
+	path: "path",
+	size: "size",
+	ctime: "ctime",
+	mtime: "mtime",
+	mimeType: "mime_type"
+};
+const DEFAULT_QUERY_LIMIT = 1e3;
+/**
+* Provider-level constraints on the (already core-validated) spec that the
+* tree engine enforces uniformly. Strict contract: reject, never ignore.
+*
+* Aggregate-mode orderBy is a totally different field set (group keys +
+* `as` names) — those have already been validated by the core; nothing
+* more for the engine to assert here.
+*/
+function assertTreeQuerySpec(spec) {
+	if (spec.text !== void 0) throw new AFSValidationError("Invalid query spec: text: not supported by this provider");
+	if (spec.aggregations) return;
+	if (spec.orderBy && spec.orderBy.length > 1) throw new AFSValidationError("Invalid query spec: orderBy: this provider supports a single sort key");
+	const field = spec.orderBy?.[0]?.[0];
+	if (field !== void 0 && !ENGINE_ORDER_COLUMNS[field] && !field.startsWith("meta.")) throw new AFSValidationError(`Invalid query spec: orderBy: unsupported field ${field}`);
+}
+/** Effective single sort key: requested tuple or the children default (name asc). */
+function effectiveOrder(spec) {
+	const tuple = spec.orderBy?.[0];
+	return {
+		field: tuple?.[0] ?? "name",
+		order: tuple?.[1] ?? "asc"
+	};
+}
+/** Quoted JSON path for a core-validated dot-path (segments are [\w-]+). */
+function jsonPathOf(field) {
+	return `$.${field.split(".").map((seg) => `"${seg}"`).join(".")}`;
+}
+/**
+* Resolve a where/orderBy field to its source JSON column expression and the
+* `$.path` argument to `json_extract`. `meta.*` paths dispatch to the
+* `entries.metadata` column (planning/agent-hub/metadata-foundation.md);
+* everything else stays on the record (inline content JSON).
+*
+* `doc` (doc-mode = dir-per-record) decides where `meta.*` reads from:
+* application metadata is persisted on the FILE row (`cf.metadata`), not on
+* the parent dir row (`e.metadata`), so a doc-mode meta.* filter MUST read
+* `cf` first and fall back to the dir row — the SAME precedence the orderBy
+* path already uses (`COALESCE(cf.metadata, e.metadata)`). Without this a
+* meta.* WHERE/groupBy/aggregate on a `{uuid}/item.json` collection reads the
+* dir row's (always NULL) metadata and never matches. In file mode `e` IS the
+* record file, so `e.metadata` is correct and `cf` doesn't exist in the FROM.
+*/
+function fieldSource(field, rec, doc) {
+	if (field.startsWith("meta.")) return {
+		src: doc ? "COALESCE(cf.metadata, e.metadata)" : "e.metadata",
+		path: jsonPathOf(field.slice(5))
+	};
+	return {
+		src: rec,
+		path: jsonPathOf(field)
+	};
+}
+/**
+* Compile one where leaf against the record expression. Type-strict by spec
+* value type, case-folded for strings — mirrors `whereMatches`.
+*/
+function compileLeaf(rec, leaf, doc) {
+	const { src, path: p } = fieldSource(leaf.field, rec, doc);
+	const eqCond = (value) => {
+		if (typeof value === "boolean") return {
+			sql: `json_type(${src}, ?) = '${value ? "true" : "false"}'`,
+			args: [p]
+		};
+		if (typeof value === "number") return {
+			sql: `(json_type(${src}, ?) IN ('integer','real') AND json_extract(${src}, ?) = ?)`,
+			args: [
+				p,
+				p,
+				value
+			]
+		};
+		return {
+			sql: `(json_type(${src}, ?) = 'text' AND lower(json_extract(${src}, ?)) = lower(?))`,
+			args: [
+				p,
+				p,
+				value
+			]
+		};
+	};
+	if ("eq" in leaf) return eqCond(leaf.eq);
+	if ("in" in leaf || "notIn" in leaf) {
+		const parts = (leaf.in ?? leaf.notIn).map((v) => eqCond(v));
+		const inSql = `(${parts.map((f) => f.sql).join(" OR ")})`;
+		const inArgs = parts.flatMap((f) => f.args);
+		if ("in" in leaf) return {
+			sql: inSql,
+			args: inArgs
+		};
+		return {
+			sql: `(json_type(${src}, ?) IS NULL OR json_type(${src}, ?) = 'null' OR NOT ${inSql})`,
+			args: [
+				p,
+				p,
+				...inArgs
+			]
+		};
+	}
+	if ("contains" in leaf) {
+		const v = leaf.contains;
+		const member = typeof v === "number" ? {
+			sql: `(je.type IN ('integer','real') AND je.value = ?)`,
+			args: [v]
+		} : {
+			sql: `(je.type = 'text' AND lower(je.value) = lower(?))`,
+			args: [v]
+		};
+		return {
+			sql: `(json_type(${src}, ?) = 'array' AND EXISTS (SELECT 1 FROM json_each(json_extract(${src}, ?)) je WHERE ${member.sql}))`,
+			args: [
+				p,
+				p,
+				...member.args
+			]
+		};
+	}
+	const op = "gte" in leaf ? ">=" : "<=";
+	const bound = "gte" in leaf ? leaf.gte : leaf.lte;
+	if (typeof bound === "number") return {
+		sql: `(json_type(${src}, ?) IN ('integer','real') AND json_extract(${src}, ?) ${op} ?)`,
+		args: [
+			p,
+			p,
+			bound
+		]
+	};
+	return {
+		sql: `(json_type(${src}, ?) = 'text' AND lower(json_extract(${src}, ?)) ${op} lower(?))`,
+		args: [
+			p,
+			p,
+			bound
+		]
+	};
+}
+/**
+* Build the three statements (page rows / exact count / optional groups) for
+* a collection query over direct children of `parent` in `scope`.
+*
+* Candidate rows:
+* - doc form: ALL direct children; record = LEFT-JOINed `<dir>/<doc>` inline
+*   content (file children have no record — `notIn` still matches them, the
+*   same as the reference evaluator's missing-field semantics).
+* - file form: direct FILE children; record = the row's own inline content.
+*
+* Malformed/missing inline JSON collapses to NULL record (json_valid guard),
+* never an engine error.
+*/
+/**
+* THE single source of the children-candidates FROM clause — the doc
+* sub-file LEFT JOIN used by the query engine (`listChildren` shares it in
+* the join-free `buildChildrenFrom(undefined)` form post-T4.3), so the
+* dir-per-record join condition can never drift. The `e.kind = 'dir'` join
+* condition is
+* load-bearing: without it a FILE row `items/foo` would join
+* `items/fooitem.json` if such a path happened to exist.
+*/
+const CHILDREN_INDEX = "idx_entries_children";
+/**
+* Index that serves `ORDER BY <field>` NATIVELY for a `(scope, parent)`
+* children query (E-S-R rule: equality columns then the sort column). ctime /
+* mtime each have a matching `(scope, parent, <col>, name)` index so the sort
+* is index-only and `LIMIT` terminates early instead of reading the whole
+* directory into a temp b-tree. name / size / mimeType / meta.* have no such
+* index → keep `idx_entries_children` (they still sort, but that is unchanged
+* pre-existing behavior, not the aside feed's hot ctime path).
+*
+* Guard: `idx_entries_children` alone forces the (scope,parent,name) index,
+* which cannot order by ctime — so it silently reintroduced the exact
+* `USE TEMP B-TREE FOR ORDER BY` full-directory scan feed-sort-createdat
+* removed (regression caught by e2e-driver-s3-orderby). This routes the ROWS
+* query back onto the ordered index; the count/groups/aggregate FROM keeps the
+* children index (no ORDER BY there — the children hint bounds correctly).
+*/
+function orderedChildrenIndex(orderField) {
+	if (orderField === "ctime") return "idx_entries_parent_ctime";
+	if (orderField === "mtime") return "idx_entries_parent_mtime";
+	return CHILDREN_INDEX;
+}
+function buildChildrenFrom(docFile, indexName = CHILDREN_INDEX) {
+	const hint = ` INDEXED BY ${indexName}`;
+	if (!docFile) return {
+		sql: `FROM ds_entries e${hint}`,
+		args: []
+	};
+	return {
+		sql: `FROM ds_entries e${hint} LEFT JOIN ds_entries cf ON e.kind = 'dir' AND cf.scope = e.scope AND cf.path = e.path || ?`,
+		args: [docFile]
+	};
+}
+/**
+* SQL expression producing the canonical `time_bucket` string for a unix-ms
+* source expression. Matches the JS `bucketizeTimestamp()` shape exactly so
+* SQL ↔ memory backends stay byte-equal in the lockstep test:
+*
+* - `day` / `month` / `year` map to direct `strftime` formats.
+* - `week` produces ISO 8601 `YYYY-Www` via a Thursday-anchor formula. SQLite
+*   has no `%V`, so we shift the date to its ISO Thursday with the
+*   `'-3 days', 'weekday 4'` modifier pair, then count weeks from Jan-4's
+*   Thursday of that ISO year (which is always in ISO week 1).
+*
+* `srcExpr` MUST be a SQL expression evaluating to a unix-ms integer (caller
+* guarantees — we wrap with `cast(... as integer) / 1000` for the
+* `'unixepoch'` modifier).
+*/
+function buildTimeBucketExpr(srcExpr, granularity) {
+	const unix = `(cast(${srcExpr} as integer) / 1000)`;
+	switch (granularity) {
+		case "day": return `strftime('%Y-%m-%d', ${unix}, 'unixepoch')`;
+		case "month": return `strftime('%Y-%m', ${unix}, 'unixepoch')`;
+		case "year": return `strftime('%Y', ${unix}, 'unixepoch')`;
+		case "week": {
+			const thu = `date(${unix}, 'unixepoch', '-3 days', 'weekday 4')`;
+			const isoYear = `strftime('%Y', ${thu})`;
+			return `(${isoYear} || '-W' || printf('%02d', ${`cast(((julianday(${thu}) - julianday(${`date(${isoYear} || '-01-04', '-3 days', 'weekday 4')`})) / 7) + 1 as integer)`}))`;
+		}
+	}
+}
+/**
+* Resolve a group-key dimension name to a SQL expression. `time_bucket` is
+* synthesized from `spec.timeBucketField` (default `meta.timestamp`).
+* Everything else is a field dot-path that goes through `fieldSource()` so
+* `meta.*` lands on `entries.metadata` and content paths stay on the
+* record. Returns the column expression and (for `time_bucket`) any
+* pre-extraction expression with the granularity baked in.
+*/
+function groupKeyExpr(name, spec, rec) {
+	const doc = !!spec.doc;
+	if (name === TIME_BUCKET_KEY) {
+		const { src: src$1, path: p$1 } = fieldSource(spec.timeBucketField ?? "meta.timestamp", rec, doc);
+		return buildTimeBucketExpr(`json_extract(${src$1}, '${p$1}')`, spec.timeGranularity);
+	}
+	const { src, path: p } = fieldSource(name, rec, doc);
+	return `json_extract(${src}, '${p}')`;
+}
+/**
+* Compile one aggregation op to its SQL expression. Numeric ops cast to
+* REAL to match the JS reference's `Number(v)` semantics — non-numeric
+* strings/null collapse to 0, BigNumber.toString() roundtrips correctly.
+* `count` is `COUNT(*)` (counts rows, including those with NULL fields).
+*/
+function aggregateOpExpr(op, rec, doc) {
+	if (op.op === "count") return "COUNT(*)";
+	const { src, path: p } = fieldSource(op.field, rec, doc);
+	const num = `CAST(json_extract(${src}, '${p}') AS REAL)`;
+	switch (op.op) {
+		case "sum": return `COALESCE(SUM(${num}), 0)`;
+		case "avg": return `AVG(${num})`;
+		case "max": return `MAX(${num})`;
+		case "min": return `MIN(${num})`;
+	}
+}
+function buildTreeQueryStatements(opts) {
+	const { scope, parent, spec } = opts;
+	const doc = spec.doc;
+	const { field, order } = effectiveOrder(spec);
+	const rawRec = doc ? "cf.content" : "e.content";
+	const rec = `(CASE WHEN ${rawRec} IS NOT NULL AND json_valid(${rawRec}) THEN ${rawRec} ELSE NULL END)`;
+	let col;
+	let colExpr;
+	let nullable;
+	if (field.startsWith("meta.")) {
+		const metaPath = jsonPathOf(field.slice(5));
+		colExpr = doc ? `COALESCE(json_extract(cf.metadata, '${metaPath}'), json_extract(e.metadata, '${metaPath}'))` : `json_extract(e.metadata, '${metaPath}')`;
+		col = colExpr;
+		nullable = true;
+	} else {
+		col = ENGINE_ORDER_COLUMNS[field];
+		colExpr = `e.${col}`;
+		nullable = col === "mime_type";
+	}
+	const from = buildChildrenFrom(doc);
+	const fromSql = from.sql;
+	const fromArgs = from.args;
+	const rowsFrom = buildChildrenFrom(doc, orderedChildrenIndex(field));
+	const baseWhere = ["e.scope = ?", "e.parent = ?"];
+	const baseArgs = [scope, parent];
+	if (!doc) baseWhere.push("e.kind = 'file'");
+	const whereLeaves = normalizeWhere(spec.where);
+	for (const leaf of whereLeaves) {
+		const frag = compileLeaf(rec, leaf, !!doc);
+		baseWhere.push(frag.sql);
+		baseArgs.push(...frag.args);
+	}
+	const whereSql = baseWhere.join(" AND ");
+	const parsed = parseTreeCursor(spec.cursor, true);
+	const parts = buildOrderedQueryParts({
+		col: colExpr,
+		nullable,
+		order,
+		tieCol: "e.name",
+		cursor: parsed.kind === "v2" ? parsed.cursor : void 0
+	});
+	const limit = spec.count ? 0 : spec.limit ?? DEFAULT_QUERY_LIMIT;
+	const offset = spec.offset ?? 0;
+	let rowsSql = `SELECT e.path, e.name, e.kind, e.cid, e.size, e.mtime, e.ctime, e.mime_type, e.metadata AS metadata${doc ? ", cf.content AS cf_content, cf.cid AS cf_cid, cf.metadata AS cf_metadata" : ", e.content AS content"} ${rowsFrom.sql} WHERE ${whereSql}`;
+	const rowsArgs = [...rowsFrom.args, ...baseArgs];
+	if (parts.cursorWhereSql) {
+		rowsSql += ` AND ${parts.cursorWhereSql}`;
+		rowsArgs.push(...parts.cursorArgs);
+	}
+	rowsSql += ` ORDER BY ${parts.orderSql} LIMIT ? OFFSET ?`;
+	rowsArgs.push(limit + 1, offset);
+	const countFrom = doc && whereLeaves.length === 0 ? buildChildrenFrom(void 0) : from;
+	const statements = {
+		rows: {
+			sql: rowsSql,
+			args: rowsArgs
+		},
+		count: spec.skipTotal ? void 0 : {
+			sql: `SELECT COUNT(*) AS cnt ${countFrom.sql} WHERE ${whereSql}`,
+			args: [...countFrom.args, ...baseArgs]
+		},
+		order: {
+			field,
+			order,
+			col
+		}
+	};
+	if (spec.aggregations) {
+		const groupKeys = aggregateGroupKeyNames(spec);
+		const keySelects = [];
+		for (let i = 0; i < groupKeys.length; i++) keySelects.push(`${groupKeyExpr(groupKeys[i], spec, rec)} AS k_${i}`);
+		const aggSelects = [];
+		for (const agg of spec.aggregations) aggSelects.push(`${aggregateOpExpr(agg, rec, !!doc)} AS ${agg.as}`);
+		const asSet = new Set(spec.aggregations.map((a) => a.as));
+		const groupSet = new Map(groupKeys.map((k, i) => [k, `k_${i}`]));
+		const orderParts = [];
+		for (const [orderField, dir] of spec.orderBy ?? []) {
+			const expr = groupSet.get(orderField) ?? (asSet.has(orderField) ? orderField : null);
+			if (expr) orderParts.push(`${expr} IS NULL ${dir === "asc" ? "ASC" : "DESC"}, ${expr} ${dir === "asc" ? "ASC" : "DESC"}`);
+		}
+		for (let i = 0; i < groupKeys.length; i++) orderParts.push(`k_${i} ASC`);
+		const orderSql = orderParts.length > 0 ? ` ORDER BY ${orderParts.join(", ")}` : "";
+		const groupBySql = groupKeys.length > 0 ? ` GROUP BY ${groupKeys.map((_, i) => `k_${i}`).join(", ")}` : "";
+		const aggLimit = spec.limit ?? DEFAULT_QUERY_LIMIT;
+		const aggOffset = spec.offset ?? 0;
+		const aggregateRowsSql = `SELECT ${[...keySelects, ...aggSelects].join(", ")} ${fromSql} WHERE ${whereSql}${groupBySql}${orderSql} LIMIT ? OFFSET ?`;
+		const countGroupsSql = groupKeys.length === 0 ? `SELECT 1 AS cnt ${fromSql} WHERE ${whereSql}` : `SELECT COUNT(*) AS cnt FROM (SELECT ${keySelects.join(", ")} ${fromSql} WHERE ${whereSql} GROUP BY ${groupKeys.map((_, i) => `k_${i}`).join(", ")})`;
+		statements.aggregate = {
+			select: {
+				sql: aggregateRowsSql,
+				args: [
+					...fromArgs,
+					...baseArgs,
+					aggLimit,
+					aggOffset
+				]
+			},
+			countGroups: {
+				sql: countGroupsSql,
+				args: groupKeys.length === 0 ? [...fromArgs, ...baseArgs] : [...fromArgs, ...baseArgs]
+			},
+			groupKeys,
+			aggregations: spec.aggregations
+		};
+		return statements;
+	}
+	if (typeof spec.groupBy === "string") {
+		const gp = jsonPathOf(spec.groupBy);
+		statements.groups = {
+			sql: `SELECT je.type AS t, CASE WHEN je.type = 'text' THEN lower(je.value) ELSE je.value END AS v, COUNT(*) AS cnt ${fromSql}, json_each(CASE json_type(${rec}, ?) WHEN 'array' THEN json_extract(${rec}, ?) WHEN 'true' THEN '[true]' WHEN 'false' THEN '[false]' ELSE json_array(json_extract(${rec}, ?)) END) je WHERE ${whereSql} GROUP BY t, v`,
+			args: [
+				...fromArgs,
+				gp,
+				gp,
+				gp,
+				...baseArgs
+			]
+		};
+	}
+	if (spec.seekId !== void 0) statements.seek = {
+		sql: `SELECT rn FROM (SELECT e.name AS nm, (ROW_NUMBER() OVER (ORDER BY ${parts.orderSql}) - 1) AS rn ${fromSql} WHERE ${whereSql}) AS _seek WHERE _seek.nm = ?`,
+		args: [
+			...fromArgs,
+			...baseArgs,
+			spec.seekId
+		]
+	};
+	return statements;
+}
+/**
+* Assemble a TreeQueryResult from raw SQL rows — shared by SQLiteTreeIndex
+* and D1TreeIndex so row mapping / hasMore slicing / keyset-cursor
+* construction stay one implementation across SQL backends. `rawRows` is
+* the (limit+1)-sized page from `TreeQueryStatements.rows`.
+*/
+function buildTreeQueryResultFromSql(opts) {
+	const { rawRows, total, groupRows, spec, orderField, seekOffset } = opts;
+	const limit = spec.count ? 0 : spec.limit ?? DEFAULT_QUERY_LIMIT;
+	const num = (v) => typeof v === "bigint" ? Number(v) : v ?? 0;
+	const hasMore = rawRows.length > limit;
+	const rows = (hasMore ? rawRows.slice(0, limit) : rawRows).map((r) => {
+		const row = {
+			path: r.path,
+			name: r.name,
+			kind: r.kind === "dir" ? "dir" : "file",
+			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) row.content = r.content;
+		if (r.cf_content != null) {
+			row.content = r.cf_content;
+			row.contentCid = r.cf_cid ?? void 0;
+		}
+		const meta = parseTreeEntryMetadata(r.cf_metadata ?? r.metadata);
+		if (meta !== void 0) row.metadata = meta;
+		return row;
+	});
+	const result = {
+		rows,
+		total
+	};
+	if (groupRows) result.groups = mapGroupRows(groupRows);
+	const last = rows[rows.length - 1];
+	if (hasMore && last && !spec.count) result.cursor = buildKeysetCursor(rowSortValue(last, orderField), last.name);
+	if (seekOffset !== void 0) result.seekOffset = seekOffset;
+	return result;
+}
+/** Sort-column value of a row (NULL mimeType stays null — sorts last). */
+function rowSortValue(row, field) {
+	if (field.startsWith("meta.")) {
+		let cur = row.metadata;
+		for (const seg of field.slice(5).split(".")) {
+			if (cur == null || typeof cur !== "object" || Array.isArray(cur)) return null;
+			cur = cur[seg];
+		}
+		if (cur == null) return null;
+		if (typeof cur === "string" || typeof cur === "number") return cur;
+		return String(cur);
+	}
+	switch (field) {
+		case "name": return row.name;
+		case "path": return row.path;
+		case "mimeType": return row.mimeType ?? null;
+		case "size": return row.size;
+		case "ctime": return row.ctime;
+		case "mtime": return row.mtime;
+		default: return null;
+	}
+}
+/** Canonical group ordering: count desc, then String(value) asc. */
+function sortGroups(groups) {
+	return groups.sort((a, b) => b.count - a.count || String(a.value).localeCompare(String(b.value)));
+}
+/**
+* Map raw aggregate-mode SQL rows into the canonical `AFSAggregateGroup[]`.
+* Each row has `k_0..k_N` for group dimensions (in `groupKeys` order) plus
+* each aggregation alias. Numeric aggregates that come back as bigint are
+* coerced to Number so callers don't have to worry about wire types.
+*/
+function mapAggregateRows(rows, groupKeys, aggregations) {
+	const coerce = (v) => {
+		if (typeof v === "bigint") return Number(v);
+		return v;
+	};
+	return rows.map((r) => {
+		const key = {};
+		for (let i = 0; i < groupKeys.length; i++) {
+			const v = coerce(r[`k_${i}`]);
+			key[groupKeys[i]] = v === null || v === void 0 ? null : typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? v : String(v);
+		}
+		const out = { key };
+		for (const agg of aggregations) {
+			const raw = coerce(r[agg.as]);
+			if (agg.op === "count") out[agg.as] = typeof raw === "number" ? raw : 0;
+			else if (agg.op === "sum") out[agg.as] = typeof raw === "number" ? raw : 0;
+			else out[agg.as] = typeof raw === "number" ? raw : null;
+		}
+		return out;
+	});
+}
+/** Map raw group rows (t, v, cnt) into the canonical groups array. */
+function mapGroupRows(rows) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const r of rows) {
+		const t = String(r.t);
+		let value;
+		if (t === "text") value = String(r.v);
+		else if (t === "integer" || t === "real") value = Number(r.v);
+		else if (t === "true") value = true;
+		else if (t === "false") value = false;
+		else value = null;
+		const key = `${typeof value}:${String(value)}`;
+		const count = typeof r.cnt === "bigint" ? Number(r.cnt) : r.cnt;
+		const existing = merged.get(key);
+		if (existing) existing.count += count;
+		else merged.set(key, {
+			value,
+			count
+		});
+	}
+	return sortGroups([...merged.values()]);
+}
+/** Parse a record text into a JSON value; malformed → undefined (no record). */
+function parseRecordText(text) {
+	if (text === void 0) return void 0;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+function foldPrimitive(value) {
+	if (typeof value === "string") return value.toLowerCase();
+	if (typeof value === "number" || typeof value === "boolean") return value;
+	return null;
+}
+/** Group-count with unnest semantics over parsed records (lockstep with SQL). */
+function computeGroups(records, groupBy) {
+	const counts = /* @__PURE__ */ new Map();
+	const bump = (raw) => {
+		const value = foldPrimitive(raw);
+		const key = `${typeof value}:${String(value)}`;
+		const existing = counts.get(key);
+		if (existing) existing.count += 1;
+		else counts.set(key, {
+			value,
+			count: 1
+		});
+	};
+	for (const record of records) {
+		const value = resolveFieldPath(record, groupBy);
+		if (Array.isArray(value)) for (const member of value) bump(member);
+		else bump(value ?? null);
+	}
+	return sortGroups([...counts.values()]);
+}
+/**
+* Project `select` fields out of a parsed record (nested shape for
+* dot-paths) — same projection rule as the core reference evaluator.
+*/
+function projectRecordFields(record, select) {
+	const out = {};
+	for (const field of select) {
+		const value = resolveFieldPath(record, field);
+		if (value === void 0) continue;
+		const segments = field.split(".");
+		let target = out;
+		for (let i = 0; i < segments.length - 1; i++) {
+			const seg = segments[i];
+			if (typeof target[seg] !== "object" || target[seg] === null) target[seg] = {};
+			target = target[seg];
+		}
+		target[segments.at(-1)] = value;
+	}
+	return out;
+}
+/**
+* Execute a tree query over in-memory candidates — semantics locked to the
+* SQL path by the lockstep test. `where` uses `whereMatchesItem` so that
+* `meta.*` paths resolve against the candidate's `metadata` column the same
+* way the SQL path reads `entries.metadata`.
+*/
+function runTreeQueryInMemory(candidates, spec) {
+	const filtered = spec.where ? candidates.filter((c) => whereMatchesItem({
+		entry: {
+			id: c.path,
+			path: c.path,
+			meta: c.metadata
+		},
+		record: c.record
+	}, spec.where)) : [...candidates];
+	if (spec.aggregations) {
+		const result$1 = evaluateCollectionQuery(filtered.map((c) => ({
+			entry: {
+				id: c.path,
+				path: c.path,
+				meta: c.metadata
+			},
+			record: c.record
+		})), spec);
+		return {
+			rows: [],
+			total: result$1.total,
+			aggregateGroups: result$1.aggregateGroups
+		};
+	}
+	const total = spec.skipTotal ? -1 : filtered.length;
+	const groups = typeof spec.groupBy === "string" ? computeGroups(filtered.map((c) => c.record), spec.groupBy) : void 0;
+	const { field, order } = effectiveOrder(spec);
+	filtered.sort((a, b) => {
+		const cmp = compareTreeSortValues(rowSortValue(a, field), rowSortValue(b, field), order);
+		if (cmp !== 0) return cmp;
+		const tie = a.name === b.name ? 0 : a.name < b.name ? -1 : 1;
+		return order === "desc" ? -tie : tie;
+	});
+	const parsed = parseTreeCursor(spec.cursor, true);
+	const afterCursor = parsed.kind === "v2" ? filtered.filter((row) => keysetAfter(rowSortValue(row, field), row.name, parsed.cursor, order)) : filtered;
+	let seekOffset;
+	if (spec.seekId !== void 0) seekOffset = filtered.findIndex((c) => c.name === spec.seekId);
+	const offset = spec.offset ?? 0;
+	const limit = spec.count ? 0 : spec.limit ?? DEFAULT_QUERY_LIMIT;
+	const page = afterCursor.slice(offset, offset + limit);
+	const hasMore = offset + limit < afterCursor.length;
+	const last = page[page.length - 1];
+	const result = {
+		rows: page.map(({ record: _record, ...row }) => row),
+		total
+	};
+	if (groups) result.groups = groups;
+	if (hasMore && last && !spec.count) result.cursor = buildKeysetCursor(rowSortValue(last, field), last.name);
+	if (seekOffset !== void 0) result.seekOffset = seekOffset;
+	return result;
+}
+
+//#endregion
+export { assertTreeQuerySpec, buildChildrenFrom, buildTreeQueryResultFromSql, buildTreeQueryStatements, mapAggregateRows, parseRecordText, projectRecordFields, runTreeQueryInMemory };
+//# sourceMappingURL=tree-query.mjs.map