@mulmoclaude/core 0.22.1 → 0.23.1

package/dist/{server-Bh-DPK-H.cjs → server-Jaogu3Ky.cjs}

@@ -1,5 +1,5 @@
 const require_rolldown_runtime = require("./rolldown-runtime-D6vf50IK.cjs");
-const require_promptSafety = require("./promptSafety-DN5V__Ku.cjs");
+const require_promptSafety = require("./promptSafety-DRd15gQ6.cjs");
 const require_collection_paths = require("./collection/paths.cjs");
 const require_skill_bridge_index = require("./skill-bridge/index.cjs");
 let node_path = require("node:path");
@@ -7,6 +7,9 @@ node_path = require_rolldown_runtime.__toESM(node_path, 1);
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
 let node_crypto = require("node:crypto");
+let node_os = require("node:os");
+let iconv_lite = require("iconv-lite");
+iconv_lite = require_rolldown_runtime.__toESM(iconv_lite, 1);
 let zod = require("zod");
 //#region src/collection/server/host.ts
 var current = null;
@@ -574,7 +577,7 @@ function promptPathsFor(collection, workspaceRoot) {
 	const skillDir = (rel === "" || rel.startsWith("..") ? collection.skillDir : rel).split(node_path.default.sep).join("/");
 	return {
 		slug: collection.slug,
-		dataPath: collection.schema.dataPath,
+		dataPath: collection.schema.dataPath ?? collection.schema.dataSource?.path ?? "",
 		skillDir
 	};
 }
@@ -637,6 +640,586 @@ ${dataJson}
 ${templateText}`;
 }
 //#endregion
+//#region src/collection/core/queryZ.ts
+/** Result-column aliases double as SQL identifiers and JSON keys — keep
+*  them to a conservative identifier charset so neither side needs
+*  escaping gymnastics. */
+var SAFE_ALIAS_PATTERN = /^[A-Za-z_]\w{0,63}$/;
+/** Hard ceiling on returned rows; `limit` clamps below it. A group-by on
+*  a near-unique column would otherwise return one row per source row —
+*  the exact materialization the aggregate path exists to avoid. */
+var MAX_QUERY_ROWS = 1e4;
+/** Default row cap when the query declares no `limit`. */
+var DEFAULT_QUERY_ROWS = 1e3;
+/** One aggregate column: `count` (rows; `column` optional to count
+*  non-null cells) or `sum`/`avg`/`min`/`max` over a named CSV column. */
+var QueryAggregateZ = zod.z.object({
+	op: zod.z.enum([
+		"count",
+		"sum",
+		"avg",
+		"min",
+		"max"
+	]),
+	column: zod.z.string().min(1).optional()
+}).refine((aggregate) => aggregate.op === "count" || aggregate.column !== void 0, {
+	message: "`column` is required for every aggregate op except `count`",
+	path: ["column"]
+});
+/** One filter condition. Same op vocabulary as the schema-level `where`
+*  (`core/where.ts`) so authors learn one set; values may be typed
+*  (number / boolean) since CSV columns are. `in` requires an array
+*  value, every other op a scalar. */
+var QueryWhereZ = zod.z.object({
+	field: zod.z.string().min(1),
+	op: zod.z.enum([
+		"eq",
+		"ne",
+		"in",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"contains"
+	]),
+	value: zod.z.union([
+		zod.z.string(),
+		zod.z.number(),
+		zod.z.boolean(),
+		zod.z.array(zod.z.union([
+			zod.z.string(),
+			zod.z.number(),
+			zod.z.boolean()
+		])).min(1).max(100)
+	])
+}).refine((cond) => cond.op === "in" === Array.isArray(cond.value), {
+	message: "`in` requires an array value (the allowed set); every other op requires a scalar value",
+	path: ["value"]
+});
+var QueryOrderZ = zod.z.object({
+	/** A `groupBy` column or an aggregate alias — membership enforced by
+	*  the whole-query refine below. */
+	field: zod.z.string().min(1),
+	dir: zod.z.enum(["asc", "desc"]).optional()
+});
+/** The whole query. At least one of `groupBy` / `aggregates` must be
+*  present: bare `groupBy` is a DISTINCT listing, bare `aggregates` a
+*  whole-file scalar row, together a grouped aggregation. */
+var CollectionQueryZ = zod.z.object({
+	groupBy: zod.z.array(zod.z.string().min(1)).max(8).refine((columns) => new Set(columns.map((column) => column.toLowerCase())).size === columns.length, { message: "`groupBy` columns must be unique (case-insensitively — SQL identifiers ignore case)" }).optional(),
+	aggregates: zod.z.record(zod.z.string().regex(SAFE_ALIAS_PATTERN, "aggregate aliases must be simple identifiers (letters/digits/underscore)"), QueryAggregateZ).optional(),
+	where: zod.z.array(QueryWhereZ).max(16).optional(),
+	orderBy: zod.z.array(QueryOrderZ).max(4).optional(),
+	limit: zod.z.number().int().min(1).max(MAX_QUERY_ROWS).optional()
+}).refine((query) => (query.groupBy?.length ?? 0) > 0 || Object.keys(query.aggregates ?? {}).length > 0, {
+	message: "declare at least one of `groupBy` (columns to bucket by) or `aggregates` (values to compute)",
+	path: ["groupBy"]
+}).refine((query) => Object.keys(query.aggregates ?? {}).length <= 32, {
+	message: `\`aggregates\` supports at most 32 entries`,
+	path: ["aggregates"]
+}).refine((query) => {
+	const groupLower = new Set((query.groupBy ?? []).map((column) => column.toLowerCase()));
+	const seen = /* @__PURE__ */ new Set();
+	return Object.keys(query.aggregates ?? {}).every((alias) => {
+		const lower = alias.toLowerCase();
+		if (groupLower.has(lower) || seen.has(lower)) return false;
+		seen.add(lower);
+		return true;
+	});
+}, {
+	message: "aggregate aliases must be unique and must not collide with `groupBy` column names (case-insensitively — SQL identifiers ignore case)",
+	path: ["aggregates"]
+}).refine((query) => {
+	const sortable = /* @__PURE__ */ new Set([...query.groupBy ?? [], ...Object.keys(query.aggregates ?? {})]);
+	return (query.orderBy ?? []).every((order) => sortable.has(order.field));
+}, {
+	message: "every `orderBy.field` must be a `groupBy` column or an aggregate alias",
+	path: ["orderBy"]
+});
+//#endregion
+//#region src/collection/server/csvQuery.ts
+/** Double-quote a SQL identifier (CSV column name / result alias). */
+function quoteIdent(name) {
+	return `"${name.replaceAll("\"", "\"\"")}"`;
+}
+/** Single-quote a SQL string literal (a `types={...}` struct key). */
+function quoteLiteral(value) {
+	return `'${value.replaceAll("'", "''")}'`;
+}
+/** The `read_csv` argument list shared by every CSV query: the (prepared)
+*  path plus a `types` pin forcing the key column to VARCHAR — without it
+*  DuckDB's sniffer turns `001` into BIGINT 1, so leading zeros vanish
+*  and distinct keys collapse. */
+function readCsvArgs(primaryKey) {
+	return `?, types={${quoteLiteral(primaryKey)}: 'VARCHAR'}`;
+}
+/** One aggregate's SQL expression. `sum`/`avg` TRY_CAST to DOUBLE so a
+*  column the sniffer kept as VARCHAR (mixed values) aggregates over its
+*  numeric cells instead of erroring; non-numeric cells become NULL and
+*  are skipped — standard BI tolerance. `min`/`max` stay native (they are
+*  meaningful on strings and dates too). */
+function aggregateExpr(aggregate) {
+	const { op, column } = aggregate;
+	if (op === "count") return column === void 0 ? "count(*)" : `count(${quoteIdent(column)})`;
+	if (op === "sum" || op === "avg") return `${op}(TRY_CAST(${quoteIdent(column ?? "")} AS DOUBLE))`;
+	return `${op}(${quoteIdent(column ?? "")})`;
+}
+/** One where condition → SQL fragment + its bound parameters. String
+*  equality compares against `CAST(col AS VARCHAR)` so a sniffer-typed
+*  column still matches its textual value; numeric/boolean values compare
+*  natively (DuckDB coerces the column side). */
+function whereFragment(cond) {
+	const column = quoteIdent(cond.field);
+	const asText = `CAST(${column} AS VARCHAR)`;
+	if (cond.op === "in") {
+		const values = cond.value;
+		return {
+			sql: `${values.every((value) => typeof value === "string") ? asText : column} IN (${values.map(() => "?").join(", ")})`,
+			params: values
+		};
+	}
+	if (cond.op === "contains") return {
+		sql: `contains(${asText}, ?)`,
+		params: [String(cond.value)]
+	};
+	const operator = {
+		eq: "=",
+		ne: "<>",
+		gt: ">",
+		gte: ">=",
+		lt: "<",
+		lte: "<="
+	}[cond.op];
+	return {
+		sql: `${typeof cond.value === "string" && (cond.op === "eq" || cond.op === "ne") ? asText : column} ${operator} ?`,
+		params: [cond.value]
+	};
+}
+/** Compile a validated query against `fromSql` (a table-function call
+*  whose FIRST placeholder is the source path — the executor binds it).
+*  Returns the SQL and the where-value parameters that follow the path.
+*  Callers MUST have run `CollectionQueryZ` first; this function trusts
+*  the shape (aliases already charset-checked, orderBy membership already
+*  enforced). */
+function compileQuery(query, fromSql) {
+	const groupBy = query.groupBy ?? [];
+	const aggregates = Object.entries(query.aggregates ?? {});
+	const selectList = [...groupBy.map(quoteIdent), ...aggregates.map(([alias, aggregate]) => `${aggregateExpr(aggregate)} AS ${quoteIdent(alias)}`)];
+	const where = (query.where ?? []).map(whereFragment);
+	const clauses = [`SELECT ${selectList.join(", ")}`, `FROM ${fromSql}`];
+	if (where.length > 0) clauses.push(`WHERE ${where.map((fragment) => fragment.sql).join(" AND ")}`);
+	if (groupBy.length > 0) clauses.push(`GROUP BY ${groupBy.map(quoteIdent).join(", ")}`);
+	const orderBy = (query.orderBy ?? []).map((order) => quoteIdent(order.field) + (order.dir === "desc" ? " DESC" : " ASC"));
+	if (orderBy.length > 0) clauses.push(`ORDER BY ${orderBy.join(", ")}`);
+	clauses.push(`LIMIT ${query.limit ?? 1e3}`);
+	return {
+		sql: clauses.join(" "),
+		params: where.flatMap((fragment) => fragment.params)
+	};
+}
+/** Compile against a CSV file (the dataSource store's engine). */
+function compileCsvQuery(query, primaryKey) {
+	return compileQuery(query, `read_csv(${readCsvArgs(primaryKey)})`);
+}
+/** Compile against a JSONL file of ENRICHED records — the file-backed
+*  collections' engine (see `jsonlQuery.ts`). No VARCHAR key pin needed:
+*  enriched record ids are already strings. `sample_size=-1` makes the
+*  schema inference scan EVERY line — with the default sample, a sparse
+*  optional/derived field first appearing past the sample would not be
+*  inferred as a column and the query would binder-error on it (Codex P2
+*  on #2165). The full scan costs nothing extra here: aggregation reads
+*  the whole file anyway. */
+function compileJsonlQuery(query) {
+	return compileQuery(query, `read_json(?, format='newline_delimited', sample_size=-1)`);
+}
+//#endregion
+//#region src/collection/server/csvStore.ts
+/** `list()` row cap. Over-cap files are truncated with a warn — the v1
+*  contract is "browse + per-record views", not full-table analytics. */
+var MAX_CSV_ROWS = 5e3;
+/** Record ids minted from non-safe key values: `id0x` + utf-8 hex. Raw key
+*  values that themselves match this pattern are ALSO encoded, so the
+*  encoded namespace never collides with a raw value (injective mapping). */
+var ENCODED_ID_PATTERN = /^id0x([0-9a-f]+)$/;
+/** A CSV key value → the record id it's addressed by. Safe values pass
+*  through untouched; everything else (and anything shaped like an encoded
+*  id) becomes `id0x<hex>`. Pure + exported for unit tests. */
+function encodeCsvRecordId(rawKey) {
+	if (safeRecordId(rawKey) === rawKey && !ENCODED_ID_PATTERN.test(rawKey)) return rawKey;
+	return `id0x${Buffer.from(rawKey, "utf-8").toString("hex")}`;
+}
+/** A record id → the CSV key value to look up. Inverse of
+*  `encodeCsvRecordId` for encoded ids; anything else is already the raw
+*  value. Pure + exported for unit tests. */
+function decodeCsvRecordId(itemId) {
+	const match = ENCODED_ID_PATTERN.exec(itemId);
+	if (!match) return itemId;
+	return Buffer.from(match[1], "hex").toString("utf-8");
+}
+/** Normalize one DuckDB JS value into a JSON-safe record value: BigInt →
+*  number (string beyond the safe range), DATE/TIMESTAMP → ISO string
+*  (date-only when the clock is exactly UTC midnight, matching the `date`
+*  field contract), exotic DuckDB values → their string form. Pure +
+*  exported for unit tests. */
+function normalizeCsvValue(value) {
+	if (typeof value === "bigint") return value <= BigInt(Number.MAX_SAFE_INTEGER) && value >= BigInt(-Number.MAX_SAFE_INTEGER) ? Number(value) : value.toString();
+	if (value instanceof Date) {
+		const iso = value.toISOString();
+		return iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : iso;
+	}
+	if (value !== null && typeof value === "object") return String(value);
+	return value;
+}
+/** One raw DuckDB row → a CollectionItem, or null when the key cell is
+*  missing/empty (the row can't be addressed). The primaryKey field is
+*  OVERWRITTEN with the (possibly encoded) record id so `item[primaryKey]`
+*  and the record's address never drift — same invariant the file store's
+*  write path enforces. Pure + exported for unit tests. */
+function csvRowToItem(row, primaryKey) {
+	const normalized = Object.fromEntries(Object.entries(row).map(([key, value]) => [key, normalizeCsvValue(value)]));
+	const rawKey = normalized[primaryKey];
+	if (rawKey === null || rawKey === void 0 || String(rawKey) === "") return null;
+	return {
+		...normalized,
+		[primaryKey]: encodeCsvRecordId(String(rawKey))
+	};
+}
+/** Dedupe by record id, LAST row wins (matches `csvRead`'s last-match
+*  pick). Returns the surviving items in first-seen order. Pure +
+*  exported for unit tests. */
+function dedupeByRecordId(items, primaryKey) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const item of items) byId.set(String(item[primaryKey]), item);
+	return {
+		items: [...byId.values()],
+		duplicates: items.length - byId.size
+	};
+}
+/** True when a thrown DuckDB error is the `types` pin naming a column the
+*  CSV doesn't have — the schema/file-mismatch case the caller downgrades
+*  to "empty collection + warn" instead of a 500. */
+function isMissingKeyColumnError(err) {
+	return String(err).includes("do not exist in the CSV");
+}
+/** Bytes sniffed for UTF-8 validity. The trailing 3 bytes of the sample
+*  are dropped so a multibyte char split at the boundary can't produce a
+*  false negative on a valid file. */
+var SNIFF_BYTES = 1024 * 1024;
+function isValidUtf8(buf) {
+	try {
+		new TextDecoder("utf-8", { fatal: true }).decode(buf);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Detect the (best-effort) encoding of a non-UTF-8 buffer. BOMs decide
+*  UTF-16; otherwise cp932 (the Shift_JIS superset — Excel-exported
+*  Japanese CSVs are the primary non-UTF-8 case this feature serves). */
+function fallbackEncoding(buf) {
+	if (buf.length >= 2 && buf[0] === 255 && buf[1] === 254) return "utf-16le";
+	if (buf.length >= 2 && buf[0] === 254 && buf[1] === 255) return "utf-16be";
+	return "cp932";
+}
+function cacheDir() {
+	return node_path.default.join((0, node_os.tmpdir)(), "mulmoclaude-csv-utf8");
+}
+/** Read only the first `bytes` of a file — the encoding sniff must not
+*  pull a multi-hundred-MB CSV into memory on the (common) UTF-8 path. */
+async function readHead(absPath, bytes) {
+	const handle = await (0, node_fs_promises.open)(absPath, "r");
+	try {
+		const { size } = await handle.stat();
+		const buf = Buffer.alloc(Math.min(bytes, size));
+		await handle.read(buf, 0, buf.length, 0);
+		return buf;
+	} finally {
+		await handle.close();
+	}
+}
+/** Decode the whole file into a UTF-8 cache copy and return its path.
+*  Cache key = (path, mtime, size), so a replaced CSV re-decodes and an
+*  unchanged one never does. */
+async function pathExists$1(target) {
+	try {
+		await (0, node_fs_promises.stat)(target);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Best-effort removal of older decode-cache entries for the same source
+*  path — a frequently-replaced large CSV would otherwise accumulate one
+*  full copy per (mtime, size) forever. Runs AFTER the current copy is
+*  published; a concurrent reader holding an old fd is unaffected
+*  (unlink-while-open is safe on POSIX). */
+async function evictSupersededCache(key, keepBasename) {
+	try {
+		const entries = await (0, node_fs_promises.readdir)(cacheDir());
+		await Promise.all(entries.filter((name) => name.startsWith(`${key}-`) && name !== keepBasename).map((name) => (0, node_fs_promises.unlink)(node_path.default.join(cacheDir(), name)).catch(() => void 0)));
+	} catch {}
+}
+/** Decode the whole file into a UTF-8 cache copy and return its path.
+*  Cache key = (path, mtime, size), so a replaced CSV re-decodes and an
+*  unchanged one never does; superseded copies are evicted. The cache
+*  lives in the SHARED OS tmpdir, so the dir is 0700 and files 0600 —
+*  decoded rows must not be readable by other local users. */
+async function decodeToCache(absPath, info) {
+	const key = (0, node_crypto.createHash)("sha256").update(absPath).digest("hex").slice(0, 16);
+	const cached = node_path.default.join(cacheDir(), `${key}-${Math.trunc(info.mtimeMs)}-${info.size}.csv`);
+	if (!await pathExists$1(cached)) {
+		const whole = await (0, node_fs_promises.readFile)(absPath);
+		const encoding = fallbackEncoding(whole);
+		const text = iconv_lite.default.decode(whole, encoding);
+		await (0, node_fs_promises.mkdir)(cacheDir(), {
+			recursive: true,
+			mode: 448
+		});
+		const tmp = `${cached}.${(0, node_crypto.randomBytes)(4).toString("hex")}.tmp`;
+		await (0, node_fs_promises.writeFile)(tmp, text, {
+			encoding: "utf-8",
+			mode: 384
+		});
+		await (0, node_fs_promises.rename)(tmp, cached);
+		log.info("collections", "decoded non-UTF-8 dataSource file to cache", {
+			path: absPath,
+			encoding
+		});
+		await evictSupersededCache(key, node_path.default.basename(cached));
+	}
+	return cached;
+}
+/** Re-validate the dataSource file at READ time, mirroring the JSON
+*  store's per-read defenses: realpath containment (a symlink swapped in
+*  after discovery must not walk out of the workspace) and an lstat
+*  regular-file check (a symlink leaf is refused outright, even one
+*  pointing inside the workspace — same rule as `isRegularFile` on
+*  record files). Returns the stat info, or null for "no readable file"
+*  (ENOENT / refused), which callers render as an empty collection. */
+async function safeCsvStat(absPath, workspaceRoot) {
+	if (!isContainedInRoot(absPath, workspaceRoot)) {
+		log.warn("collections", "dataSource read refused: path escapes workspace", { path: absPath });
+		return null;
+	}
+	let info;
+	try {
+		info = await (0, node_fs_promises.lstat)(absPath);
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw err;
+	}
+	if (!info.isFile()) {
+		log.warn("collections", "dataSource read refused: not a regular file (symlink?)", { path: absPath });
+		return null;
+	}
+	return info;
+}
+/** Return a path DuckDB can read as UTF-8: the original file when it
+*  already is UTF-8 (the cheap, common case — only the head is sniffed),
+*  else a decoded cache copy (see `decodeToCache`). Returns null when
+*  there is no readable file (missing, symlink, or containment-refused —
+*  see `safeCsvStat`), which callers render as an empty collection. */
+async function ensureUtf8CsvPath(absPath, workspaceRoot) {
+	const info = await safeCsvStat(absPath, workspaceRoot);
+	if (info === null) return null;
+	const head = await readHead(absPath, SNIFF_BYTES);
+	const sample = head.length === SNIFF_BYTES ? head.subarray(0, SNIFF_BYTES - 3) : head;
+	if (!(head.length >= 2 && (head[0] === 255 && head[1] === 254 || head[0] === 254 && head[1] === 255)) && isValidUtf8(sample)) return absPath;
+	return decodeToCache(absPath, info);
+}
+var instancePromise = null;
+/** Lazily create one shared in-memory DuckDB instance. The dynamic import
+*  keeps the native module OUT of core's load path — a platform where the
+*  prebuilt binding is missing degrades to a per-query error on dataSource
+*  collections only, never a broken core. A failed init is retried on the
+*  next call (the promise is reset). */
+async function duckDbInstance() {
+	if (instancePromise === null) instancePromise = import("@duckdb/node-api").then((mod) => mod.DuckDBInstance.create(":memory:"));
+	try {
+		return await instancePromise;
+	} catch (err) {
+		instancePromise = null;
+		throw new Error(`DuckDB is unavailable on this host (@duckdb/node-api failed to load: ${String(err)}) — dataSource collections cannot be read`);
+	}
+}
+async function queryCsv(sql, params) {
+	const connection = await (await duckDbInstance()).connect();
+	try {
+		return (await connection.runAndReadAll(sql, params)).getRowObjectsJS();
+	} finally {
+		connection.disconnectSync();
+	}
+}
+/** Every row of the CSV as records — capped, deduped, id-encoded. The
+*  key column is pinned to VARCHAR (see `readCsvArgs`). `workspaceRoot`
+*  drives the per-read containment check; omitted, the configured host
+*  root is used. */
+async function csvList(absPath, primaryKey, workspaceRoot) {
+	const utf8Path = await ensureUtf8CsvPath(absPath, workspaceRoot ?? getWorkspaceRoot());
+	if (utf8Path === null) return [];
+	let rows;
+	try {
+		rows = await queryCsv(`SELECT * FROM read_csv(${readCsvArgs(primaryKey)}) LIMIT 5001`, [utf8Path]);
+	} catch (err) {
+		if (!isMissingKeyColumnError(err)) throw err;
+		log.warn("collections", "dataSource CSV has no primaryKey column — every row is skipped", {
+			path: absPath,
+			primaryKey
+		});
+		return [];
+	}
+	if (rows.length > 5e3) {
+		log.warn("collections", "dataSource CSV truncated to row cap", {
+			path: absPath,
+			cap: MAX_CSV_ROWS
+		});
+		rows.length = MAX_CSV_ROWS;
+	}
+	const items = rows.map((row) => csvRowToItem(row, primaryKey)).filter((item) => item !== null);
+	const skipped = rows.length - items.length;
+	if (skipped > 0) log.warn("collections", "dataSource CSV rows skipped (empty key cell)", {
+		path: absPath,
+		skipped
+	});
+	const deduped = dedupeByRecordId(items, primaryKey);
+	if (deduped.duplicates > 0) log.warn("collections", "dataSource CSV has duplicate key values (last row wins)", {
+		path: absPath,
+		duplicates: deduped.duplicates
+	});
+	return deduped.items;
+}
+/** The scan-order ordinal column the last-match read adds. Underscore
+*  prefix keeps it out of any plausible CSV header namespace; it is
+*  stripped from the returned record either way. */
+var ROW_ORDINAL = "__mc_row";
+/** One record by id. The comparison value rides as a prepared-statement
+*  parameter, and the LAST matching row is selected IN DuckDB (scan-order
+*  ordinal + LIMIT 1) — a CSV with thousands of duplicate keys must not
+*  materialize them all for one detail read. Consistent with csvList's
+*  last-wins dedupe. */
+async function csvRead(absPath, primaryKey, itemId, workspaceRoot) {
+	const utf8Path = await ensureUtf8CsvPath(absPath, workspaceRoot ?? getWorkspaceRoot());
+	if (utf8Path === null) return null;
+	const rawKey = decodeCsvRecordId(itemId);
+	const last = (await queryCsv(`SELECT * FROM (SELECT *, row_number() OVER () AS ${quoteIdent(ROW_ORDINAL)} FROM read_csv(${readCsvArgs(primaryKey)})) WHERE CAST(${quoteIdent(primaryKey)} AS VARCHAR) = ? ORDER BY ${quoteIdent(ROW_ORDINAL)} DESC LIMIT 1`, [utf8Path, rawKey])).at(0);
+	if (last === void 0) return null;
+	const { [ROW_ORDINAL]: __ordinal, ...record } = last;
+	return csvRowToItem(record, primaryKey);
+}
+/** Run a validated aggregation query (the structured DSL — see
+*  `core/queryZ.ts`) over the WHOLE file: no row cap on the scan (a
+*  capped aggregate would be a wrong number), only the result-row LIMIT
+*  the compiler emits. Values are normalized like list/read rows so a
+*  chart consumer gets plain JSON scalars. */
+async function csvRunQuery(absPath, primaryKey, query, workspaceRoot) {
+	const utf8Path = await ensureUtf8CsvPath(absPath, workspaceRoot ?? getWorkspaceRoot());
+	if (utf8Path === null) return [];
+	const { sql, params } = compileCsvQuery(query, primaryKey);
+	return (await queryCsv(sql, [utf8Path, ...params])).map((row) => Object.fromEntries(Object.entries(row).map(([key, value]) => [key, normalizeCsvValue(value)])));
+}
+//#endregion
+//#region src/collection/server/store.ts
+/** True when the collection accepts UI/tool writes. A `dataSource`
+*  collection is read-only: updates happen by editing/replacing the
+*  data file itself. Every write entry point checks this BEFORE calling
+*  `writeItem`/`deleteItem` — server-enforced, not just UI-hidden. */
+function collectionWritable(collection) {
+	return !require_promptSafety.isReadOnlySchema(collection.schema);
+}
+/** The one-line refusal write paths surface (HTTP 405 / MCP error text). */
+function readOnlyRefusal(slug) {
+	return `collection '${slug}' is read-only (backed by an external dataSource) — update the data file itself instead`;
+}
+/** Pick the store implementation for a discovered collection. A
+*  `dataSource` schema whose `dataSourceFile` failed to resolve yields a
+*  read-only EMPTY store rather than falling back to the (writable) file
+*  store — a half-loaded read-only collection must never become writable. */
+function storeFor(collection, opts = {}) {
+	if (require_promptSafety.isReadOnlySchema(collection.schema)) {
+		const file = collection.dataSourceFile;
+		const key = collection.schema.primaryKey;
+		return {
+			capabilities: { writable: false },
+			list: () => file === void 0 ? Promise.resolve([]) : csvList(file, key, opts.workspaceRoot),
+			read: (itemId) => file === void 0 ? Promise.resolve(null) : csvRead(file, key, itemId, opts.workspaceRoot),
+			query: (query) => file === void 0 ? Promise.resolve([]) : csvRunQuery(file, key, query, opts.workspaceRoot)
+		};
+	}
+	return {
+		capabilities: { writable: true },
+		list: () => listItems(collection.dataDir, opts),
+		read: (itemId) => readItem(collection.dataDir, itemId, opts)
+	};
+}
+//#endregion
+//#region src/collection/server/jsonlQuery.ts
+/** SQL semantics for an aggregate-only query over ZERO rows: one scalar
+*  row (`count` = 0, everything else NULL) — the same shape the CSV path
+*  produces for a header-only file, so callers reading `rows[0]` never
+*  break on storage kind or emptiness. A grouped query over zero rows is
+*  zero groups (`[]`), also matching SQL. Synthesized here because DuckDB
+*  has no empty file to infer a schema from. */
+function emptyCollectionResult(query) {
+	if ((query.groupBy?.length ?? 0) > 0) return [];
+	const aggregates = Object.entries(query.aggregates ?? {});
+	return [Object.fromEntries(aggregates.map(([alias, aggregate]) => [alias, aggregate.op === "count" ? 0 : null]))];
+}
+/** The SOURCE columns a query reads: groupBy columns, aggregate input
+*  columns, and where fields. (orderBy resolves to groupBy columns or
+*  aggregate ALIASES — never to a new source column — so it adds none.) */
+function referencedSourceColumns(query) {
+	const columns = new Set(query.groupBy ?? []);
+	for (const aggregate of Object.values(query.aggregates ?? {})) if (aggregate.column !== void 0) columns.add(aggregate.column);
+	for (const cond of query.where ?? []) columns.add(cond.field);
+	return [...columns];
+}
+/** Referenced columns that appear in NO row — a freshly-added optional
+*  field, or a derived field whose inputs no record has yet. DuckDB only
+*  infers columns from keys that occur in the JSONL, so without help a
+*  valid query on such a field binder-errors here while the CSV path
+*  (whose header always declares the column) returns NULLs. Padding the
+*  FIRST line with `col: null` makes the column exist (full-scan
+*  inference unions keys across lines) with matching NULL semantics. */
+function absentReferencedColumns(rows, query) {
+	const present = /* @__PURE__ */ new Set();
+	for (const row of rows) for (const key of Object.keys(row)) present.add(key);
+	return referencedSourceColumns(query).filter((column) => !present.has(column));
+}
+/** Run a validated query over enriched collection rows. */
+async function runQueryOverRows(rows, query) {
+	if (rows.length === 0) return emptyCollectionResult(query);
+	await (0, node_fs_promises.mkdir)(cacheDir(), {
+		recursive: true,
+		mode: 448
+	});
+	const jsonlPath = node_path.default.join(cacheDir(), `q-${(0, node_crypto.randomBytes)(8).toString("hex")}.jsonl`);
+	try {
+		const nullPads = Object.fromEntries(absentReferencedColumns(rows, query).map((column) => [column, null]));
+		const handle = await (0, node_fs_promises.open)(jsonlPath, "wx", 384);
+		try {
+			let first = true;
+			for (const row of rows) {
+				await handle.write(`${JSON.stringify(first ? {
+					...nullPads,
+					...row
+				} : row)}\n`);
+				first = false;
+			}
+		} finally {
+			await handle.close();
+		}
+		const { sql, params } = compileJsonlQuery(query);
+		return (await queryCsv(sql, [jsonlPath, ...params])).map((row) => Object.fromEntries(Object.entries(row).map(([key, value]) => [key, normalizeCsvValue(value)])));
+	} finally {
+		await (0, node_fs_promises.unlink)(jsonlPath).catch((err) => {
+			if (err.code !== "ENOENT") log.warn("collections", "temp JSONL cleanup failed", {
+				path: jsonlPath,
+				error: String(err)
+			});
+		});
+	}
+}
+//#endregion
 //#region src/collection/core/recordZ.ts
 /** The emptiness rule shared by `required` and the "only check present
 *  values" gate. NOT a truthiness check — `0` and `false` are filled. */
@@ -753,6 +1336,7 @@ async function listRecordFilenames(dataDir, workspaceRoot) {
 	}
 }
 async function validateCollectionRecords(collection, opts = {}) {
+	if (collection.schema.dataSource !== void 0) return [];
 	const workspaceRoot = opts.workspaceRoot ?? getWorkspaceRoot();
 	const entries = await listRecordFilenames(collection.dataDir, workspaceRoot);
 	const issues = [];
@@ -1402,10 +1986,24 @@ function fieldDrivenFromFieldCarried(schema) {
 	}
 	return (carry ?? []).includes(driven.fromField);
 }
+/** External-data collection: the records ARE the rows of a user-supplied
+*  data file (v1: CSV), queried through DuckDB — never copied into
+*  `<dataDir>/<id>.json` files. Declaring `dataSource` makes the collection
+*  **read-only** in every UI/tool write path; updates happen by replacing /
+*  editing the file itself (file-watch republishes the views). `path` is
+*  workspace-relative and containment-checked exactly like `dataPath`. The
+*  row-id column is the schema's existing `primaryKey` — there is
+*  deliberately no second key concept here.
+*  See plans/feat-collection-csv-duckdb-source.md. */
+var DataSourceZ = zod.z.object({
+	type: zod.z.literal("csv"),
+	path: zod.z.string().min(1)
+});
 var CollectionSchemaZ = zod.z.object({
 	title: zod.z.string().min(1),
 	icon: zod.z.string().min(1),
-	dataPath: zod.z.string().min(1),
+	dataPath: zod.z.string().min(1).optional(),
+	dataSource: DataSourceZ.optional(),
 	primaryKey: zod.z.string().min(1),
 	singleton: zod.z.string().trim().min(1).optional(),
 	fields: zod.z.record(zod.z.string(), FieldSpecZ),
@@ -1425,6 +2023,15 @@ var CollectionSchemaZ = zod.z.object({
 	notifyWhen: WhenZ.optional(),
 	ingest: IngestZ.optional(),
 	dynamicIcon: DynamicIconSpecZ.optional()
+}).refine((schema) => schema.dataPath !== void 0 !== (schema.dataSource !== void 0), {
+	message: "declare exactly one of `dataPath` (native JSON records) or `dataSource` (external read-only data file), never both or neither",
+	path: ["dataPath"]
+}).refine((schema) => schema.dataSource === void 0 || schema.singleton === void 0 && schema.ingest === void 0 && schema.spawn === void 0, {
+	message: "a `dataSource` collection is read-only — it cannot declare `singleton`, `ingest`, or `spawn` (all of them write records)",
+	path: ["dataSource"]
+}).refine((schema) => schema.dataSource === void 0 || [...schema.actions ?? [], ...schema.collectionActions ?? []].every((action) => action.kind !== "mutate"), {
+	message: "a `dataSource` collection is read-only — its actions cannot use `kind: \"mutate\"` (a host write); use `chat`/`agent` actions instead",
+	path: ["dataSource"]
 }).refine((schema) => schema.singleton === void 0 || require_promptSafety.isSafeRecordId(schema.singleton), {
 	message: "schema `singleton` must be a valid item id (alphanumeric / hyphen / underscore / interior dot, no `..` or path separators)",
 	path: ["singleton"]
@@ -1550,6 +2157,12 @@ function applyFeedSchemaDefaults(parsed, slug) {
 		dataPath: `data/feeds/${slug}`
 	};
 }
+/** The conventional per-slug records dir a `dataSource` collection gets as
+*  its `dataDir` (records never live there, but archive/delete paths stay
+*  well-defined — same shape the registry's R3 normalization uses). */
+function conventionalDataPath(slug) {
+	return `data/collections/${slug}/items`;
+}
 /** The acceptance gates discovery applies AFTER `CollectionSchemaZ` parses,
 *  before a schema becomes a live collection:
 *
@@ -1559,7 +2172,8 @@ function applyFeedSchemaDefaults(parsed, slug) {
 *    edit is dropped with no error;
 *  - a `feed` schema must declare an `ingest` block (else it's a dead,
 *    non-refreshable card);
-*  - `dataPath` must resolve INSIDE the workspace.
+*  - `dataPath` — or a `dataSource`'s `path` — must resolve INSIDE the
+*    workspace (same realpath containment for both).
 *
 *  Exported so `manageCollection`'s `putSchema` can run the SAME gates before
 *  it reports success — a schema that passes `CollectionSchemaZ` but fails one
@@ -1579,7 +2193,24 @@ function acceptParsedSchema(schema, opts) {
 		ok: false,
 		reason: "a feed schema must declare an `ingest` block"
 	};
-	const dataDir = resolveDataDir(schema.dataPath, opts.workspaceRoot);
+	if (schema.dataSource !== void 0) {
+		const dataSourceFile = resolveDataDir(schema.dataSource.path, opts.workspaceRoot);
+		if (dataSourceFile === null) return {
+			ok: false,
+			reason: `dataSource.path '${schema.dataSource.path}' escapes the workspace`
+		};
+		const dataDir = resolveDataDir(conventionalDataPath(opts.slug), opts.workspaceRoot);
+		if (dataDir === null) return {
+			ok: false,
+			reason: `slug '${opts.slug}' yields no workspace-contained data dir`
+		};
+		return {
+			ok: true,
+			dataDir,
+			dataSourceFile
+		};
+	}
+	const dataDir = resolveDataDir(schema.dataPath ?? "", opts.workspaceRoot);
 	if (dataDir === null) return {
 		ok: false,
 		reason: `dataPath '${schema.dataPath}' escapes the workspace`
@@ -1627,7 +2258,8 @@ async function loadOneCollection(skillsRoot, slug, source, workspaceRoot) {
 	const schema = parsed.data;
 	const acceptance = acceptParsedSchema(schema, {
 		source,
-		workspaceRoot
+		workspaceRoot,
+		slug: safeName
 	});
 	if (!acceptance.ok) {
 		log.warn("collections", "schema.json rejected after validation, skipping", {
@@ -1641,6 +2273,7 @@ async function loadOneCollection(skillsRoot, slug, source, workspaceRoot) {
 		source,
 		schema,
 		dataDir: acceptance.dataDir,
+		...acceptance.dataSourceFile !== void 0 ? { dataSourceFile: acceptance.dataSourceFile } : {},
 		skillDir: node_path.default.join(skillsRoot, safeName)
 	};
 }
@@ -1712,7 +2345,8 @@ function toSummary(collection) {
 		slug: collection.slug,
 		title: collection.schema.title,
 		icon: collection.schema.icon,
-		source: collection.source
+		source: collection.source,
+		...collection.schema.dataSource !== void 0 ? { readonly: true } : {}
 	};
 }
 function toDetail(collection) {
@@ -1767,6 +2401,20 @@ async function countRecordFiles(dataDir, workspaceRoot) {
 		return 0;
 	}
 }
+/** A collection's record count for the ontology. File-backed: the cheap
+*  readdir count. `dataSource`-backed: the row count via the CSV store
+*  (subject to its row cap) — the dataDir is a phantom there, so the
+*  readdir count would always misreport 0. Fail-soft to 0 like
+*  `countRecordFiles` (an unreadable file / missing DuckDB must not
+*  break the whole ontology). */
+async function countRecords(collection, workspaceRoot) {
+	if (!collectionWritable(collection)) try {
+		return (await storeFor(collection, { workspaceRoot }).list()).length;
+	} catch {
+		return 0;
+	}
+	return countRecordFiles(collection.dataDir, workspaceRoot);
+}
 async function toOntologyEntry(collection, workspaceRoot) {
 	const { schema } = collection;
 	return {
@@ -1775,7 +2423,7 @@ async function toOntologyEntry(collection, workspaceRoot) {
 		icon: schema.icon,
 		primaryKey: schema.primaryKey,
 		displayField: schema.displayField ?? schema.primaryKey,
-		recordCount: await countRecordFiles(collection.dataDir, workspaceRoot),
+		recordCount: await countRecords(collection, workspaceRoot),
 		relations: schemaRelations(schema)
 	};
 }
@@ -1821,7 +2469,7 @@ function uniqueBacklinkSources(schema) {
 async function loadTarget(slug, opts) {
 	const target = await loadCollection(slug, opts);
 	if (!target) return null;
-	const items = await listItems(target.dataDir, { workspaceRoot: opts.workspaceRoot });
+	const items = await storeFor(target, { workspaceRoot: opts.workspaceRoot }).list();
 	const byId = {};
 	for (const item of items) {
 		const itemId = item[target.schema.primaryKey];
@@ -1939,7 +2587,7 @@ async function computeCollectionIcon(collection, opts = {}) {
 	try {
 		const source = await loadCollection(spec.source.collection, opts);
 		if (!source) return spec.fallback ?? schema.icon;
-		const ordered = sortByPrimaryKey(await listItems(source.dataDir, { workspaceRoot: opts.workspaceRoot }), source.schema.primaryKey);
+		const ordered = sortByPrimaryKey(await storeFor(source, { workspaceRoot: opts.workspaceRoot }).list(), source.schema.primaryKey);
 		const orderBy = spec.source.orderBy ?? require_promptSafety.firstDateField(source.schema);
 		const recordsById = buildRecordsById(ordered, source.schema.primaryKey);
 		return require_promptSafety.resolveIcon(require_promptSafety.selectDynamicRecord(ordered, spec.source, orderBy, recordsById), spec, schema.icon, recordsById);
@@ -2237,6 +2885,20 @@ function isDataDirSafe(dataDir, slug, workspaceRoot) {
 	const resolved = node_path.default.resolve(dataDir);
 	return acceptableRoots.some((root) => resolved === root || resolved.startsWith(root + node_path.default.sep));
 }
+/** Step 2 of the restore doc — how to bring the records back. A
+*  `dataSource` collection has no record files to copy (its rows live in
+*  the external data file, which the delete never touches). */
+function restoreRecordsStep(schema) {
+	if (schema.dataPath === void 0) return `2. Records: nothing to copy. This is a \`dataSource\` collection —
+   its records are the rows of \`${schema.dataSource?.path}\`, which the
+   delete never touched.`;
+	return `2. Copy the item data: \`cp\` every file under \`records/\` into
+   \`${schema.dataPath}/\`. The records are part of the collection and
+   must be restored. They are plain data files (NOT bridged), so use
+   \`cp\` — the Write-tool rule in step 1 applies ONLY to the skill
+   files, not to these records (there may be many; copy them, do not
+   Write them one by one).`;
+}
 function buildRestoreDoc(collection) {
 	const { slug, schema } = collection;
 	return `# Restore "${schema.title}" (collection \`${slug}\`)
@@ -2257,18 +2919,13 @@ Follow these steps to restore it.
    \`.claude/skills/\` directly is not an option either: that path is
    permission-gated.)
 
-2. Copy the item data: \`cp\` every file under \`records/\` into
-   \`${schema.dataPath}/\`. The records are part of the collection and
-   must be restored. They are plain data files (NOT bridged), so use
-   \`cp\` — the Write-tool rule in step 1 applies ONLY to the skill
-   files, not to these records (there may be many; copy them, do not
-   Write them one by one).
+${restoreRecordsStep(schema)}
 
 3. Confirm the collection reappears at \`/collections/${slug}\`.
 
 - slug: \`${slug}\`
 - title: ${schema.title}
-- dataPath: \`${schema.dataPath}\`
+- dataPath: \`${schema.dataPath ?? `(dataSource) ${schema.dataSource?.path}`}\`
 `;
 }
 /** Copy one skill copy + the records + RESTORE.md into `archiveDir`. */
@@ -2491,14 +3148,15 @@ async function recordIssuesWarning(collection, deps) {
 	return `${issues.length} record file(s) have data problems and are missing from this result. Fix each (Read → correct → Write):\n${lines}`;
 }
 async function loadRequestedItems(collection, ids, deps) {
+	const store = storeFor(collection, { workspaceRoot: deps.workspaceRoot });
 	if (!ids) return {
-		items: await listItems(collection.dataDir, { workspaceRoot: deps.workspaceRoot }),
+		items: await store.list(),
 		missing: []
 	};
 	const items = [];
 	const missing = [];
 	for (const recordId of ids) {
-		const item = await readItem(collection.dataDir, recordId, { workspaceRoot: deps.workspaceRoot }).catch(() => null);
+		const item = await store.read(recordId).catch(() => null);
 		if (item) items.push(item);
 		else missing.push(recordId);
 	}
@@ -2602,7 +3260,35 @@ async function putOneItem(collection, record, mode, deps) {
 	if (result.kind === "conflict") return reject(itemId, `'${itemId}' already exists — mode "create" refuses overwrite; use "upsert" to update it`);
 	return reject(itemId, "write refused: the collection's data dir escapes the workspace");
 }
+/** Aggregation over a collection via the structured query DSL
+*  (`core/queryZ.ts`) — the paved road for counts / sums / group-bys
+*  that a row listing can't answer honestly. Two engines behind one
+*  shape: a dataSource collection queries its CSV natively through the
+*  store (`store.query`, uncapped whole-file scan); a file-backed
+*  collection aggregates its ENRICHED records (computed fields —
+*  `derived` / `rollup` / `toggle` — are real columns) through the same
+*  compiled SQL over a temp JSONL (`runQueryOverRows`). */
+async function handleQueryItems(collection, queryArg, deps) {
+	const parsed = CollectionQueryZ.safeParse(queryArg);
+	if (!parsed.success) return `manageCollection: \`query\` rejected — fix and retry:\n${parsed.error.issues.slice(0, 20).map((issue) => `- ${issue.path.map(String).join(".") || "(root)"}: ${require_promptSafety.defangForPrompt(issue.message)}`).join("\n")}`;
+	const store = storeFor(collection, { workspaceRoot: deps.workspaceRoot });
+	if (store.query) {
+		const rows = await store.query(parsed.data);
+		return JSON.stringify({
+			collection: collection.slug,
+			count: rows.length,
+			rows
+		});
+	}
+	const rows = await runQueryOverRows(await enrichItems(collection, await store.list(), deps), parsed.data);
+	return JSON.stringify({
+		collection: collection.slug,
+		count: rows.length,
+		rows
+	});
+}
 async function handlePutItems(collection, args, deps) {
+	if (!collectionWritable(collection)) return `manageCollection: ${readOnlyRefusal(collection.slug)} (its records are the rows of '${collection.schema.dataSource?.path}'; edit that file to change the data).`;
 	const written = [];
 	const rejected = [];
 	for (const record of args.items) {
@@ -2701,7 +3387,8 @@ function schemaDiscoveryGate(schema, base) {
 	const primaryField = schema.fields[schema.primaryKey];
 	if (!primaryField) return `primaryKey '${schema.primaryKey}' is not one of the declared fields`;
 	if (primaryField.primary !== true) return `the primaryKey field '${schema.primaryKey}' must be flagged \`primary: true\``;
-	if (resolveDataDir(schema.dataPath, base) === null) return `dataPath '${schema.dataPath}' escapes the workspace`;
+	if (schema.dataPath !== void 0 && resolveDataDir(schema.dataPath, base) === null) return `dataPath '${schema.dataPath}' escapes the workspace`;
+	if (schema.dataSource !== void 0 && resolveDataDir(schema.dataSource.path, base) === null) return `dataSource.path '${schema.dataSource.path}' escapes the workspace`;
 	return null;
 }
 /** Validate a schema against CollectionSchemaZ and, on success, persist it.
@@ -2723,7 +3410,7 @@ async function handlePutSchema(slug, schemaArg, deps) {
 		written: true
 	});
 }
-var MANAGE_COLLECTION_PROMPT = "Use `manageCollection` instead of raw Read/Write/Edit when working with a collection's records OR its schema (raw file I/O stays available as the escape hatch). Before authoring or changing a collection's `schema.json`, call `schemaDocs` to load the field/DSL reference, then read with `getSchema` and write with `putSchema` — `putSchema` validates the whole schema before writing and returns actionable errors instead of silently failing discovery's validation. `getItems` is the only way to see computed values — `derived` fields (e.g. a portfolio's value), `toggle` projections, and `embed` records are host-computed and never present in the stored JSON files. On large collections pass `ids` and/or `fields` to keep the result small. For a question that spans collections (\"which clients have unpaid invoices?\"), start with `getOntology`: it lists every collection with its primaryKey, record count, and outbound `ref`/`embed` relations, so you know which collections to join before reading any records. `putItems` validates every row against the schema before writing (required fields, enum values, primaryKey = record id) and returns `{ written, rejected }`; fix each rejected row using its `problem` text and retry just those rows. Never include computed fields in a row you write. To update a few fields of an existing record, use `mode: \"merge\"` with a partial row ({ id, <changed fields> }) — the default upsert replaces the WHOLE record, so a partial upsert would silently erase every optional field it omits.";
+var MANAGE_COLLECTION_PROMPT = "Use `manageCollection` instead of raw Read/Write/Edit when working with a collection's records OR its schema (raw file I/O stays available as the escape hatch). Before authoring or changing a collection's `schema.json`, call `schemaDocs` to load the field/DSL reference, then read with `getSchema` and write with `putSchema` — `putSchema` validates the whole schema before writing and returns actionable errors instead of silently failing discovery's validation. `getItems` is the only way to see computed values — `derived` fields (e.g. a portfolio's value), `toggle` projections, and `embed` records are host-computed and never present in the stored JSON files. On large collections pass `ids` and/or `fields` to keep the result small. For a question that spans collections (\"which clients have unpaid invoices?\"), start with `getOntology`: it lists every collection with its primaryKey, record count, and outbound `ref`/`embed` relations, so you know which collections to join before reading any records. `putItems` validates every row against the schema before writing (required fields, enum values, primaryKey = record id) and returns `{ written, rejected }`; fix each rejected row using its `problem` text and retry just those rows. Never include computed fields in a row you write. To update a few fields of an existing record, use `mode: \"merge\"` with a partial row ({ id, <changed fields> }) — the default upsert replaces the WHOLE record, so a partial upsert would silently erase every optional field it omits. Answer aggregation questions (counts, sums, averages, group-bys) with `queryItems` on ANY collection — on a dataSource (CSV) collection it scans the whole file (getItems is row-capped, so aggregates computed from its output can be silently wrong on large files); on a file-backed collection it aggregates the enriched records, so computed fields (derived/rollup/toggle) are queryable columns.";
 /** Validate getItems' optional `ids`/`fields` args, then delegate. */
 async function dispatchGetItems(collection, args, deps) {
 	const ids = optionalStringArray(args.ids, "ids");
@@ -2744,82 +3431,113 @@ async function manageCollectionHandler(deps, args) {
 	if (!slug) return "manageCollection: `slug` is required (the collection's slug).";
 	if (action === "getSchema") return handleGetSchema(slug, deps);
 	if (action === "putSchema") return handlePutSchema(slug, args.schema, deps);
-	if (action !== "getItems" && action !== "putItems") return "manageCollection: `action` must be \"getItems\", \"putItems\", \"getOntology\", \"schemaDocs\", \"getSchema\", or \"putSchema\".";
+	if (action !== "getItems" && action !== "putItems" && action !== "queryItems") return "manageCollection: `action` must be \"getItems\", \"putItems\", \"queryItems\", \"getOntology\", \"schemaDocs\", \"getSchema\", or \"putSchema\".";
 	const collection = await loadCollection(slug, deps);
 	if (!collection) return unknownCollection(slug);
 	if (action === "getItems") return dispatchGetItems(collection, args, deps);
+	if (action === "queryItems") return handleQueryItems(collection, args.query, deps);
 	const parsed = parsePutItems(args, slug);
 	if (typeof parsed === "string") return parsed;
 	return handlePutItems(collection, parsed, deps);
 }
-function makeManageCollectionTool(deps = {}) {
-	return {
-		definition: {
-			name: "manageCollection",
-			description: "Read and write a schema-driven collection through the host — both its records and its structure. getItems returns records WITH computed values (derived formulas, toggles, embeds) the stored JSON files don't contain; putItems validates each row against the schema before writing. getOntology maps the whole workspace: every collection with its record count and outbound ref/embed relations — call it first for cross-collection questions. schemaDocs returns the collection-authoring reference; getSchema/putSchema read and validate-then-write the collection's schema.json. Prefer it over raw file I/O on collections.",
-			inputSchema: {
+var MANAGE_COLLECTION_DEFINITION = {
+	name: "manageCollection",
+	description: "Read and write a schema-driven collection through the host — both its records and its structure. getItems returns records WITH computed values (derived formulas, toggles, embeds) the stored JSON files don't contain; putItems validates each row against the schema before writing. getOntology maps the whole workspace: every collection with its record count and outbound ref/embed relations — call it first for cross-collection questions. schemaDocs returns the collection-authoring reference; getSchema/putSchema read and validate-then-write the collection's schema.json. Prefer it over raw file I/O on collections.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			action: {
+				type: "string",
+				enum: [
+					"getItems",
+					"putItems",
+					"queryItems",
+					"getOntology",
+					"schemaDocs",
+					"getSchema",
+					"putSchema"
+				],
+				description: "What to do."
+			},
+			slug: {
+				type: "string",
+				description: "The collection's slug (its directory name, e.g. `stock-quotes`). Required for everything except schemaDocs and getOntology."
+			},
+			ids: {
+				type: "array",
+				items: { type: "string" },
+				description: "getItems: only these record ids (primary-key values). Omit for all records."
+			},
+			fields: {
+				type: "array",
+				items: { type: "string" },
+				description: "getItems: only these fields per record (the primary key is always included). Omit for all fields. Use on large collections."
+			},
+			items: {
+				type: "array",
+				items: { type: "object" },
+				description: "putItems: the record objects to store. Each must carry the schema's primaryKey value (it doubles as the filename)."
+			},
+			mode: {
+				type: "string",
+				enum: [
+					"upsert",
+					"create",
+					"merge"
+				],
+				description: "putItems: \"upsert\" (default) replaces existing records WHOLE; \"create\" rejects rows whose id already exists; \"merge\" updates only the fields a row carries, keeping the rest of the existing record (rejects unknown ids). Use \"merge\" when changing a few fields."
+			},
+			schema: {
 				type: "object",
-				properties: {
-					action: {
-						type: "string",
-						enum: [
-							"getItems",
-							"putItems",
-							"getOntology",
-							"schemaDocs",
-							"getSchema",
-							"putSchema"
-						],
-						description: "What to do."
-					},
-					slug: {
-						type: "string",
-						description: "The collection's slug (its directory name, e.g. `stock-quotes`). Required for everything except schemaDocs and getOntology."
-					},
-					ids: {
-						type: "array",
-						items: { type: "string" },
-						description: "getItems: only these record ids (primary-key values). Omit for all records."
-					},
-					fields: {
-						type: "array",
-						items: { type: "string" },
-						description: "getItems: only these fields per record (the primary key is always included). Omit for all fields. Use on large collections."
-					},
-					items: {
-						type: "array",
-						items: { type: "object" },
-						description: "putItems: the record objects to store. Each must carry the schema's primaryKey value (it doubles as the filename)."
-					},
-					mode: {
-						type: "string",
-						enum: [
-							"upsert",
-							"create",
-							"merge"
-						],
-						description: "putItems: \"upsert\" (default) replaces existing records WHOLE; \"create\" rejects rows whose id already exists; \"merge\" updates only the fields a row carries, keeping the rest of the existing record (rejects unknown ids). Use \"merge\" when changing a few fields."
-					},
-					schema: {
-						type: "object",
-						description: "putSchema: the full collection schema object (same shape as schema.json — title, icon, dataPath, primaryKey, fields, …). Call getSchema first for the current one, and schemaDocs for the field DSL."
-					}
-				},
-				required: ["action"]
+				description: "putSchema: the full collection schema object (same shape as schema.json — title, icon, dataPath, primaryKey, fields, …). Call getSchema first for the current one, and schemaDocs for the field DSL."
+			},
+			query: {
+				type: "object",
+				description: "queryItems: a structured aggregation query — `{ groupBy?: [\"col\"], aggregates?: { alias: { op: \"count\"|\"sum\"|\"avg\"|\"min\"|\"max\", column? } }, where?: [{ field, op, value }], orderBy?: [{ field, dir? }], limit? }`. At least one of groupBy/aggregates. On a dataSource (CSV) collection it scans the WHOLE file uncapped (unlike getItems); on a file-backed collection it aggregates the ENRICHED records, so computed fields (derived/rollup/toggle) are queryable columns. Use it for counts / sums / averages / group-bys instead of arithmetic over getItems output."
 			}
 		},
+		required: ["action"]
+	}
+};
+function makeManageCollectionTool(deps = {}) {
+	return {
+		definition: MANAGE_COLLECTION_DEFINITION,
 		alwaysActive: true,
 		prompt: MANAGE_COLLECTION_PROMPT,
 		handler: (args) => manageCollectionHandler(deps, args)
 	};
 }
 //#endregion
+Object.defineProperty(exports, "CollectionQueryZ", {
+	enumerable: true,
+	get: function() {
+		return CollectionQueryZ;
+	}
+});
 Object.defineProperty(exports, "CollectionSchemaZ", {
 	enumerable: true,
 	get: function() {
 		return CollectionSchemaZ;
 	}
 });
+Object.defineProperty(exports, "DEFAULT_QUERY_ROWS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_QUERY_ROWS;
+	}
+});
+Object.defineProperty(exports, "MAX_CSV_ROWS", {
+	enumerable: true,
+	get: function() {
+		return MAX_CSV_ROWS;
+	}
+});
+Object.defineProperty(exports, "MAX_QUERY_ROWS", {
+	enumerable: true,
+	get: function() {
+		return MAX_QUERY_ROWS;
+	}
+});
 Object.defineProperty(exports, "MAX_SCHEMA_ISSUES", {
 	enumerable: true,
 	get: function() {
@@ -2880,12 +3598,30 @@ Object.defineProperty(exports, "buildWorkspaceOntology", {
 		return buildWorkspaceOntology;
 	}
 });
+Object.defineProperty(exports, "collectionWritable", {
+	enumerable: true,
+	get: function() {
+		return collectionWritable;
+	}
+});
 Object.defineProperty(exports, "collectionsRegistriesConfigPath", {
 	enumerable: true,
 	get: function() {
 		return collectionsRegistriesConfigPath;
 	}
 });
+Object.defineProperty(exports, "compileCsvQuery", {
+	enumerable: true,
+	get: function() {
+		return compileCsvQuery;
+	}
+});
+Object.defineProperty(exports, "compileJsonlQuery", {
+	enumerable: true,
+	get: function() {
+		return compileJsonlQuery;
+	}
+});
 Object.defineProperty(exports, "compileRecordZ", {
 	enumerable: true,
 	get: function() {
@@ -2910,12 +3646,30 @@ Object.defineProperty(exports, "configureCollectionHost", {
 		return configureCollectionHost;
 	}
 });
+Object.defineProperty(exports, "csvRowToItem", {
+	enumerable: true,
+	get: function() {
+		return csvRowToItem;
+	}
+});
 Object.defineProperty(exports, "daysInMonth", {
 	enumerable: true,
 	get: function() {
 		return daysInMonth;
 	}
 });
+Object.defineProperty(exports, "decodeCsvRecordId", {
+	enumerable: true,
+	get: function() {
+		return decodeCsvRecordId;
+	}
+});
+Object.defineProperty(exports, "dedupeByRecordId", {
+	enumerable: true,
+	get: function() {
+		return dedupeByRecordId;
+	}
+});
 Object.defineProperty(exports, "deleteCollection", {
 	enumerable: true,
 	get: function() {
@@ -2946,6 +3700,12 @@ Object.defineProperty(exports, "discoverCollections", {
 		return discoverCollections;
 	}
 });
+Object.defineProperty(exports, "encodeCsvRecordId", {
+	enumerable: true,
+	get: function() {
+		return encodeCsvRecordId;
+	}
+});
 Object.defineProperty(exports, "enrichItems", {
 	enumerable: true,
 	get: function() {
@@ -3042,6 +3802,12 @@ Object.defineProperty(exports, "maybeSpawnSuccessor", {
 		return maybeSpawnSuccessor;
 	}
 });
+Object.defineProperty(exports, "normalizeCsvValue", {
+	enumerable: true,
+	get: function() {
+		return normalizeCsvValue;
+	}
+});
 Object.defineProperty(exports, "parseCivil", {
 	enumerable: true,
 	get: function() {
@@ -3078,6 +3844,12 @@ Object.defineProperty(exports, "readItem", {
 		return readItem;
 	}
 });
+Object.defineProperty(exports, "readOnlyRefusal", {
+	enumerable: true,
+	get: function() {
+		return readOnlyRefusal;
+	}
+});
 Object.defineProperty(exports, "readSkillTemplate", {
 	enumerable: true,
 	get: function() {
@@ -3114,6 +3886,12 @@ Object.defineProperty(exports, "resolveTemplatePath", {
 		return resolveTemplatePath;
 	}
 });
+Object.defineProperty(exports, "runQueryOverRows", {
+	enumerable: true,
+	get: function() {
+		return runQueryOverRows;
+	}
+});
 Object.defineProperty(exports, "safeRecordId", {
 	enumerable: true,
 	get: function() {
@@ -3138,6 +3916,12 @@ Object.defineProperty(exports, "setCollectionChangePublisher", {
 		return setCollectionChangePublisher;
 	}
 });
+Object.defineProperty(exports, "storeFor", {
+	enumerable: true,
+	get: function() {
+		return storeFor;
+	}
+});
 Object.defineProperty(exports, "successorId", {
 	enumerable: true,
 	get: function() {
@@ -3181,4 +3965,4 @@ Object.defineProperty(exports, "writeItem", {
 	}
 });
 
-//# sourceMappingURL=server-Bh-DPK-H.cjs.map
+//# sourceMappingURL=server-Jaogu3Ky.cjs.map