@mulmoclaude/core 0.22.1 → 0.23.1

package/dist/{server-Bd8l1bhv.js → server-D2ibbixF.js}

@@ -1,10 +1,12 @@
-import { B as isFieldDrivenEvery, C as backlinkRows, D as actionVisible, E as rollupValue, F as AGENT_INGEST_KIND, I as COMPUTED_TYPES, L as FEED_SCHEDULES, M as SAFE_SLUG_PATTERN, N as isSafeRecordId, P as isSafeSlug, R as INGEST_KINDS, T as projectBacklinkRow, b as resolveIcon, d as parseIsoDateTime, g as deriveAll, j as SAFE_RECORD_ID_PATTERN, t as defangForPrompt, u as parseIsoDate, w as coerceNumeric, x as selectDynamicRecord, y as firstDateField, z as embedTargetId } from "./promptSafety-DyG3EuC7.js";
+import { B as isFieldDrivenEvery, C as backlinkRows, D as actionVisible, E as rollupValue, F as AGENT_INGEST_KIND, I as COMPUTED_TYPES, L as FEED_SCHEDULES, M as SAFE_SLUG_PATTERN, N as isSafeRecordId, P as isSafeSlug, R as INGEST_KINDS, T as projectBacklinkRow, V as isReadOnlySchema, b as resolveIcon, d as parseIsoDateTime, g as deriveAll, j as SAFE_RECORD_ID_PATTERN, t as defangForPrompt, u as parseIsoDate, w as coerceNumeric, x as selectDynamicRecord, y as firstDateField, z as embedTargetId } from "./promptSafety-rDWA9_JS.js";
 import { isSafeActionTemplatePath, isSafeCustomViewI18nPath, isSafeCustomViewPath } from "./collection/paths.js";
 import { dataSkillDir, mirrorSkillWrite } from "./skill-bridge/index.js";
 import path from "node:path";
 import { promises, realpathSync } from "node:fs";
-import { cp, lstat, mkdir, open, readFile, readdir, rm, rmdir, stat, unlink, writeFile } from "node:fs/promises";
-import { randomBytes, randomUUID } from "node:crypto";
+import { cp, lstat, mkdir, open, readFile, readdir, rename, rm, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import iconv from "iconv-lite";
 import { z } from "zod";
 //#region src/collection/server/host.ts
 var current = null;
@@ -572,7 +574,7 @@ function promptPathsFor(collection, workspaceRoot) {
 	const skillDir = (rel === "" || rel.startsWith("..") ? collection.skillDir : rel).split(path.sep).join("/");
 	return {
 		slug: collection.slug,
-		dataPath: collection.schema.dataPath,
+		dataPath: collection.schema.dataPath ?? collection.schema.dataSource?.path ?? "",
 		skillDir
 	};
 }
@@ -635,6 +637,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 = z.object({
+	op: z.enum([
+		"count",
+		"sum",
+		"avg",
+		"min",
+		"max"
+	]),
+	column: 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 = z.object({
+	field: z.string().min(1),
+	op: z.enum([
+		"eq",
+		"ne",
+		"in",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"contains"
+	]),
+	value: z.union([
+		z.string(),
+		z.number(),
+		z.boolean(),
+		z.array(z.union([
+			z.string(),
+			z.number(),
+			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 = z.object({
+	/** A `groupBy` column or an aggregate alias — membership enforced by
+	*  the whole-query refine below. */
+	field: z.string().min(1),
+	dir: 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 = z.object({
+	groupBy: z.array(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: z.record(z.string().regex(SAFE_ALIAS_PATTERN, "aggregate aliases must be simple identifiers (letters/digits/underscore)"), QueryAggregateZ).optional(),
+	where: z.array(QueryWhereZ).max(16).optional(),
+	orderBy: z.array(QueryOrderZ).max(4).optional(),
+	limit: 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 path.join(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 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 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 readdir(cacheDir());
+		await Promise.all(entries.filter((name) => name.startsWith(`${key}-`) && name !== keepBasename).map((name) => unlink(path.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 = createHash("sha256").update(absPath).digest("hex").slice(0, 16);
+	const cached = path.join(cacheDir(), `${key}-${Math.trunc(info.mtimeMs)}-${info.size}.csv`);
+	if (!await pathExists$1(cached)) {
+		const whole = await readFile(absPath);
+		const encoding = fallbackEncoding(whole);
+		const text = iconv.decode(whole, encoding);
+		await mkdir(cacheDir(), {
+			recursive: true,
+			mode: 448
+		});
+		const tmp = `${cached}.${randomBytes(4).toString("hex")}.tmp`;
+		await writeFile(tmp, text, {
+			encoding: "utf-8",
+			mode: 384
+		});
+		await rename(tmp, cached);
+		log.info("collections", "decoded non-UTF-8 dataSource file to cache", {
+			path: absPath,
+			encoding
+		});
+		await evictSupersededCache(key, path.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 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 !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 (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 mkdir(cacheDir(), {
+		recursive: true,
+		mode: 448
+	});
+	const jsonlPath = path.join(cacheDir(), `q-${randomBytes(8).toString("hex")}.jsonl`);
+	try {
+		const nullPads = Object.fromEntries(absentReferencedColumns(rows, query).map((column) => [column, null]));
+		const handle = await 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 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. */
@@ -751,6 +1333,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 = [];
@@ -1400,10 +1983,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 = z.object({
+	type: z.literal("csv"),
+	path: z.string().min(1)
+});
 var CollectionSchemaZ = z.object({
 	title: z.string().min(1),
 	icon: z.string().min(1),
-	dataPath: z.string().min(1),
+	dataPath: z.string().min(1).optional(),
+	dataSource: DataSourceZ.optional(),
 	primaryKey: z.string().min(1),
 	singleton: z.string().trim().min(1).optional(),
 	fields: z.record(z.string(), FieldSpecZ),
@@ -1423,6 +2020,15 @@ var CollectionSchemaZ = 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 || isSafeRecordId(schema.singleton), {
 	message: "schema `singleton` must be a valid item id (alphanumeric / hyphen / underscore / interior dot, no `..` or path separators)",
 	path: ["singleton"]
@@ -1548,6 +2154,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:
 *
@@ -1557,7 +2169,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
@@ -1577,7 +2190,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`
@@ -1625,7 +2255,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", {
@@ -1639,6 +2270,7 @@ async function loadOneCollection(skillsRoot, slug, source, workspaceRoot) {
 		source,
 		schema,
 		dataDir: acceptance.dataDir,
+		...acceptance.dataSourceFile !== void 0 ? { dataSourceFile: acceptance.dataSourceFile } : {},
 		skillDir: path.join(skillsRoot, safeName)
 	};
 }
@@ -1710,7 +2342,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) {
@@ -1765,6 +2398,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 {
@@ -1773,7 +2420,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)
 	};
 }
@@ -1819,7 +2466,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];
@@ -1937,7 +2584,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 ?? firstDateField(source.schema);
 		const recordsById = buildRecordsById(ordered, source.schema.primaryKey);
 		return resolveIcon(selectDynamicRecord(ordered, spec.source, orderBy, recordsById), spec, schema.icon, recordsById);
@@ -2235,6 +2882,20 @@ function isDataDirSafe(dataDir, slug, workspaceRoot) {
 	const resolved = path.resolve(dataDir);
 	return acceptableRoots.some((root) => resolved === root || resolved.startsWith(root + path.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}\`)
@@ -2255,18 +2916,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`. */
@@ -2489,14 +3145,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);
 	}
@@ -2600,7 +3257,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)"}: ${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) {
@@ -2699,7 +3384,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.
@@ -2721,7 +3407,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");
@@ -2742,76 +3428,83 @@ 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",
+				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",
-				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: "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
-export { resolveTemplatePath as $, validateCollectionRecords as A, promptPathsFor as B, discoverCollections as C, CollectionSchemaZ as D, toSummary as E, buildCollectionActionSeedPrompt as F, resolveCreateItemId as G, readCustomViewI18n as H, deleteItem as I, SCHEMA_FILE$1 as J, writeItem as K, generateItemId as L, compileRecordZ as M, recordFieldProblem as N, applyMutateAction as O, buildActionSeedPrompt as P, resolveDataDir as Q, isRegularFile as R, acceptParsedSchema as S, toDetail as T, readItem as U, readCustomViewHtml as V, readSkillTemplate as W, isContainedInWorkspace as X, isContainedInRoot as Y, itemFilePath as Z, errorMessage as _, deleteCollection as a, log as at, buildWorkspaceOntology as b, computeSuccessor as c, isTriggerDue as d, safeRecordId as et, maybeSpawnSuccessor as f, ONE_SECOND_MS as g, successorId as h, deleteCustomView as i, getWorkspaceRoot as it, validateRecordObject as j, firstMutateParamProblem as k, daysInMonth as l, resolveEvery as m, MAX_UNSELECTIVE_ITEMS as n, collectionsRegistriesConfigPath as nt, deleteCollectionRefusalMessage as o, publishCollectionChange as ot, parseCivil as p, writeFileAtomic as q, makeManageCollectionTool as r, configureCollectionHost as rt, advanceTriggerDate as s, setCollectionChangePublisher as st, MAX_SCHEMA_ISSUES as t, safeSlugName as tt, formatCivil as u, computeCollectionIcon as v, loadCollection as w, schemaRelations as x, enrichItems as y, listItems as z };
+export { isRegularFile as $, validateCollectionRecords as A, decodeCsvRecordId as B, discoverCollections as C, CollectionSchemaZ as D, toSummary as E, collectionWritable as F, compileJsonlQuery as G, encodeCsvRecordId as H, readOnlyRefusal as I, MAX_QUERY_ROWS as J, CollectionQueryZ as K, storeFor as L, compileRecordZ as M, recordFieldProblem as N, applyMutateAction as O, runQueryOverRows as P, generateItemId as Q, MAX_CSV_ROWS as R, acceptParsedSchema as S, setCollectionChangePublisher as St, toDetail as T, normalizeCsvValue as U, dedupeByRecordId as V, compileCsvQuery as W, buildCollectionActionSeedPrompt as X, buildActionSeedPrompt as Y, deleteItem as Z, errorMessage as _, collectionsRegistriesConfigPath as _t, deleteCollection as a, readSkillTemplate as at, buildWorkspaceOntology as b, log as bt, computeSuccessor as c, writeFileAtomic as ct, isTriggerDue as d, isContainedInWorkspace as dt, listItems as et, maybeSpawnSuccessor as f, itemFilePath as ft, ONE_SECOND_MS as g, safeSlugName as gt, successorId as h, safeRecordId as ht, deleteCustomView as i, readItem as it, validateRecordObject as j, firstMutateParamProblem as k, daysInMonth as l, SCHEMA_FILE$1 as lt, resolveEvery as m, resolveTemplatePath as mt, MAX_UNSELECTIVE_ITEMS as n, readCustomViewHtml as nt, deleteCollectionRefusalMessage as o, resolveCreateItemId as ot, parseCivil as p, resolveDataDir as pt, DEFAULT_QUERY_ROWS as q, makeManageCollectionTool as r, readCustomViewI18n as rt, advanceTriggerDate as s, writeItem as st, MAX_SCHEMA_ISSUES as t, promptPathsFor as tt, formatCivil as u, isContainedInRoot as ut, computeCollectionIcon as v, configureCollectionHost as vt, loadCollection as w, schemaRelations as x, publishCollectionChange as xt, enrichItems as y, getWorkspaceRoot as yt, csvRowToItem as z };
 
-//# sourceMappingURL=server-Bd8l1bhv.js.map
+//# sourceMappingURL=server-D2ibbixF.js.map