sensemaking 0.11.5 → 0.12.1

package/dist/esm/cli/shared.d.ts

@@ -1,6 +1,7 @@
 import type { ParseArgsOptionsConfig } from 'node:util';
 import type { ResolvedConfig, SearchOverrides } from '../config.js';
 import type { OpenResult } from '../db.js';
+import type { RowFormat } from '../output.js';
 import type { Ctx } from './types.js';
 export declare const FORMAT: ParseArgsOptionsConfig;
 export declare const CONFIG: ParseArgsOptionsConfig;
@@ -9,6 +10,7 @@ export declare const SEARCH_FLAGS: ParseArgsOptionsConfig;
 type Values = Record<string, string | boolean | string[] | undefined>;
 export declare function scopeOf(values: Values): SearchOverrides;
 export declare function formatOf(values: Values): 'table' | 'json';
+export declare function rowFormatOf(values: Values): RowFormat;
 export declare function parse(argv: string[], usage: string, options: ParseArgsOptionsConfig): {
     values: Values;
     positionals: string[];
@@ -16,5 +18,5 @@ export declare function parse(argv: string[], usage: string, options: ParseArgsO
 export declare function parseK(k: string | undefined, usageError: (message: string) => never): number | undefined;
 export declare function printWarnings(warnings: string[]): void;
 export declare function withDb(ctx: Ctx, configPath: string | undefined, fn: (db: OpenResult['db'], cfg: ResolvedConfig) => void | Promise<void>): Promise<void>;
-export declare function runSql(cfg: ResolvedConfig, sql: string, params: string[], format: 'table' | 'json', label: string, preset?: string): void;
+export declare function runSql(cfg: ResolvedConfig, sql: string, params: string[], format: RowFormat, label: string, preset?: string): void;
 export {};

package/dist/esm/cli/shared.js

@@ -1,7 +1,7 @@
 import { parseArgs } from 'node:util';
 import { resolvePreset } from '../config.js';
 import { open } from '../db.js';
-import { printRows } from '../output.js';
+import { printRowStream } from '../output.js';
 import { searchError } from '../search-error.js';
 // Spreadable option fragments -- one flag name keeps one meaning across every command's table.
 export const FORMAT = {
@@ -57,8 +57,28 @@ export function scopeOf(values) {
         noExclude: values['no-exclude'] === true
     };
 }
+// An unrecognised value used to fall through to `table`, so a typo looked like it worked.
+// parseArgs is strict about flag names; this is the same strictness for the value.
+function pickFormat(values, allowed) {
+    const format = String(values.format);
+    if (allowed.includes(format)) return format;
+    console.error(`unknown --format "${format}"; expected ${allowed.join(', ')}`);
+    process.exit(2);
+}
 export function formatOf(values) {
-    return values.format === 'json' ? 'json' : 'table';
+    return pickFormat(values, [
+        'table',
+        'json'
+    ]);
+}
+// csv is a row set rendered as rows; map, peek, status, and path render structures instead,
+// and take formatOf.
+export function rowFormatOf(values) {
+    return pickFormat(values, [
+        'table',
+        'json',
+        'csv'
+    ]);
 }
 // Per-command parseArgs: strict (a foreign flag exits 2), and every table gets --help for free.
 export function parse(argv, usage, options) {
@@ -144,9 +164,17 @@ export function runSql(cfg, sql, params, format, label, preset) {
     const { db, warnings } = open(cfg);
     printWarnings(warnings);
     if (preset !== undefined) bindScope(db, cfg, preset);
-    let rows;
+    // Streamed rather than collected: `sql` is the one caller whose result size is the
+    // statement's business, not this package's, so the rows are never held here in bulk.
+    // columns() reads the statement's own metadata, so a 0-row csv still has its header.
+    // A mid-stream SQLite error (e.g. SQLITE_BUSY outlasting busy_timeout) can still leave
+    // partial output; the nonzero exit code is the caller's signal, output completeness is not
+    // guaranteed on failure.
     try {
-        rows = db.prepare(sql).all(...params);
+        const statement = db.prepare(sql);
+        statement.setReadBigInts(true); // int64 past 2^53 arrives as BigInt instead of throwing at step time
+        const columns = statement.columns().map((c)=>c.name);
+        printRowStream(statement.iterate(...params), format, columns);
     } catch (err) {
         db.close();
         // A saved query or ad-hoc SQL can carry `content MATCH ?` too, so the same FTS5
@@ -155,6 +183,5 @@ export function runSql(cfg, sql, params, format, label, preset) {
         if (/\bMATCH\b/i.test(sql)) throw searchError(err, params.join(' '));
         throw err;
     }
-    printRows(rows, format);
     db.close();
 }

package/dist/esm/cli/shared.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/shared.ts"],"sourcesContent":["import type { ParseArgsOptionsConfig } from 'node:util';\nimport { parseArgs } from 'node:util';\nimport type { ResolvedConfig, SearchOverrides } from '../config.ts';\nimport { resolvePreset } from '../config.ts';\nimport type { OpenResult } from '../db.ts';\nimport { open } from '../db.ts';\nimport type { Row } from '../output.ts';\nimport { printRows } from '../output.ts';\nimport { searchError } from '../search-error.ts';\nimport type { Ctx } from './types.ts';\n\n// Spreadable option fragments -- one flag name keeps one meaning across every command's table.\nexport const FORMAT: ParseArgsOptionsConfig = { format: { type: 'string', default: 'table' } };\nexport const CONFIG: ParseArgsOptionsConfig = { config: { type: 'string' } };\n// The scope vocabulary every scoped command shares: named preset, ad hoc include/exclude\n// globs, a where SQL condition. search adds k on top.\nexport const SCOPE: ParseArgsOptionsConfig = {\n  where: { type: 'string' },\n  preset: { type: 'string' },\n  include: { type: 'string', multiple: true },\n  exclude: { type: 'string', multiple: true },\n  // Widening, which no other flag can express: --include and --exclude each override their\n  // own side of the preset, so neither can drop an exclusion the preset declares.\n  'no-exclude': { type: 'boolean', default: false },\n};\nexport const SEARCH_FLAGS: ParseArgsOptionsConfig = { ...SCOPE, k: { type: 'string' } };\n\ntype Values = Record<string, string | boolean | string[] | undefined>;\n\n// The SCOPE fragment's parsed values as the overrides every scoped command passes down. One\n// place to read them, so a new scope field is added to the fragment and here, not in each\n// command's call.\nexport function scopeOf(values: Values): SearchOverrides {\n  return {\n    preset: values.preset as string | undefined,\n    include: values.include as string[] | undefined,\n    exclude: values.exclude as string[] | undefined,\n    where: values.where as string | undefined,\n    noExclude: values['no-exclude'] === true,\n  };\n}\n\nexport function formatOf(values: Values): 'table' | 'json' {\n  return values.format === 'json' ? 'json' : 'table';\n}\n\n// Per-command parseArgs: strict (a foreign flag exits 2), and every table gets --help for free.\nexport function parse(argv: string[], usage: string, options: ParseArgsOptionsConfig): { values: Values; positionals: string[] } {\n  let values: Values;\n  let positionals: string[];\n  try {\n    ({ values, positionals } = parseArgs({\n      args: argv,\n      options: { ...options, help: { type: 'boolean', default: false, short: 'h' } },\n      strict: true,\n      allowPositionals: true,\n    }));\n  } catch (err) {\n    console.error((err as Error).message);\n    console.error(usage);\n    process.exit(2);\n  }\n  if (values.help) {\n    console.log(usage);\n    process.exit(0);\n  }\n  return { values, positionals };\n}\n\n// --k must be a positive integer: SQLite reads a bound LIMIT of -1 as \"unlimited\" and 0 as\n// \"nothing\", and parseInt would silently truncate \"5.9\" -- all three are caller mistakes\n// worth a usage error, matching the config-level SavedSearch validation.\nexport function parseK(k: string | undefined, usageError: (message: string) => never): number | undefined {\n  if (k === undefined) return undefined;\n  const parsed = Number(k);\n  if (!Number.isInteger(parsed) || parsed <= 0) usageError(`--k expects a positive integer, got \"${k}\"`);\n  return parsed;\n}\n\n// Shared open-query-close envelope for commands that touch the tree.\n\nexport function printWarnings(warnings: string[]): void {\n  for (const w of warnings) console.warn(w);\n}\n\nexport async function withDb(ctx: Ctx, configPath: string | undefined, fn: (db: OpenResult['db'], cfg: ResolvedConfig) => void | Promise<void>): Promise<void> {\n  const cfg = ctx.resolveConfig(configPath);\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n  try {\n    await fn(db, cfg);\n  } finally {\n    db.close();\n  }\n}\n\n// `--preset` on SQL binds the scope rather than applying it: the statement joins `scope`\n// itself. Filtering behind the query's back is not available -- the obvious version, temp views\n// shadowing the base tables, cannot cover `content`, because FTS5 `MATCH` uses the table name\n// as a hidden column and a view has none. A flag that silently scoped three tables of four\n// would look scoped and not be. See plans/vault-field-report-fixes.md item F.\nfunction bindScope(db: OpenResult['db'], cfg: ResolvedConfig, preset: string): void {\n  const { name } = resolvePreset(cfg, preset); // unknown names throw, listing what is declared\n  db.exec('DROP TABLE IF EXISTS temp.scope');\n  db.exec('CREATE TEMP TABLE scope (\"path\" TEXT PRIMARY KEY)');\n  db.prepare('INSERT INTO temp.scope (\"path\") SELECT \"path\" FROM preset_files WHERE preset = ?').run(name);\n}\n\n// An unbound `?` silently binds NULL, so mismatched param counts fail loudly instead.\nexport function runSql(cfg: ResolvedConfig, sql: string, params: string[], format: 'table' | 'json', label: string, preset?: string): void {\n  const placeholderCount = (sql.match(/\\?/g) ?? []).length;\n  if (params.length !== placeholderCount) {\n    console.error(`${label} expects ${placeholderCount} parameter(s), got ${params.length}`);\n    process.exit(2);\n  }\n  // Naming a preset and never joining it would return the whole index while reading as scoped,\n  // which is the one hazard of binding rather than applying. Refuse instead.\n  if (preset !== undefined && !/\\bscope\\b/i.test(sql)) {\n    console.error(`--preset binds a temporary \"scope\" table of the preset's paths, and ${label} never joins it, so the preset would have no effect`);\n    console.error(`add: JOIN scope ON scope.\"path\" = <table>.\"path\"`);\n    process.exit(2);\n  }\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n  if (preset !== undefined) bindScope(db, cfg, preset);\n  let rows: Row[];\n  try {\n    rows = db.prepare(sql).all(...params) as Row[];\n  } catch (err) {\n    db.close();\n    // A saved query or ad-hoc SQL can carry `content MATCH ?` too, so the same FTS5\n    // punctuation trap applies -- the bound parameters are the search terms there. SQL\n    // without MATCH gets its error verbatim; search advice on a plain typo would mislead.\n    if (/\\bMATCH\\b/i.test(sql)) throw searchError(err as Error, params.join(' '));\n    throw err;\n  }\n  printRows(rows, format);\n  db.close();\n}\n"],"names":["parseArgs","resolvePreset","open","printRows","searchError","FORMAT","format","type","default","CONFIG","config","SCOPE","where","preset","include","multiple","exclude","SEARCH_FLAGS","k","scopeOf","values","noExclude","formatOf","parse","argv","usage","options","positionals","args","help","short","strict","allowPositionals","err","console","error","message","process","exit","log","parseK","usageError","undefined","parsed","Number","isInteger","printWarnings","warnings","w","warn","withDb","ctx","configPath","fn","cfg","resolveConfig","db","close","bindScope","name","exec","prepare","run","runSql","sql","params","label","placeholderCount","match","length","test","rows","all","join"],"mappings":"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"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/shared.ts"],"sourcesContent":["import type { ParseArgsOptionsConfig } from 'node:util';\nimport { parseArgs } from 'node:util';\nimport type { ResolvedConfig, SearchOverrides } from '../config.ts';\nimport { resolvePreset } from '../config.ts';\nimport type { OpenResult } from '../db.ts';\nimport { open } from '../db.ts';\nimport type { Row, RowFormat } from '../output.ts';\nimport { printRowStream } from '../output.ts';\nimport { searchError } from '../search-error.ts';\nimport type { Ctx } from './types.ts';\n\n// Spreadable option fragments -- one flag name keeps one meaning across every command's table.\nexport const FORMAT: ParseArgsOptionsConfig = { format: { type: 'string', default: 'table' } };\nexport const CONFIG: ParseArgsOptionsConfig = { config: { type: 'string' } };\n// The scope vocabulary every scoped command shares: named preset, ad hoc include/exclude\n// globs, a where SQL condition. search adds k on top.\nexport const SCOPE: ParseArgsOptionsConfig = {\n  where: { type: 'string' },\n  preset: { type: 'string' },\n  include: { type: 'string', multiple: true },\n  exclude: { type: 'string', multiple: true },\n  // Widening, which no other flag can express: --include and --exclude each override their\n  // own side of the preset, so neither can drop an exclusion the preset declares.\n  'no-exclude': { type: 'boolean', default: false },\n};\nexport const SEARCH_FLAGS: ParseArgsOptionsConfig = { ...SCOPE, k: { type: 'string' } };\n\ntype Values = Record<string, string | boolean | string[] | undefined>;\n\n// The SCOPE fragment's parsed values as the overrides every scoped command passes down. One\n// place to read them, so a new scope field is added to the fragment and here, not in each\n// command's call.\nexport function scopeOf(values: Values): SearchOverrides {\n  return {\n    preset: values.preset as string | undefined,\n    include: values.include as string[] | undefined,\n    exclude: values.exclude as string[] | undefined,\n    where: values.where as string | undefined,\n    noExclude: values['no-exclude'] === true,\n  };\n}\n\n// An unrecognised value used to fall through to `table`, so a typo looked like it worked.\n// parseArgs is strict about flag names; this is the same strictness for the value.\nfunction pickFormat<T extends string>(values: Values, allowed: readonly T[]): T {\n  const format = String(values.format);\n  if ((allowed as readonly string[]).includes(format)) return format as T;\n  console.error(`unknown --format \"${format}\"; expected ${allowed.join(', ')}`);\n  process.exit(2);\n}\n\nexport function formatOf(values: Values): 'table' | 'json' {\n  return pickFormat(values, ['table', 'json'] as const);\n}\n\n// csv is a row set rendered as rows; map, peek, status, and path render structures instead,\n// and take formatOf.\nexport function rowFormatOf(values: Values): RowFormat {\n  return pickFormat(values, ['table', 'json', 'csv'] as const);\n}\n\n// Per-command parseArgs: strict (a foreign flag exits 2), and every table gets --help for free.\nexport function parse(argv: string[], usage: string, options: ParseArgsOptionsConfig): { values: Values; positionals: string[] } {\n  let values: Values;\n  let positionals: string[];\n  try {\n    ({ values, positionals } = parseArgs({\n      args: argv,\n      options: { ...options, help: { type: 'boolean', default: false, short: 'h' } },\n      strict: true,\n      allowPositionals: true,\n    }));\n  } catch (err) {\n    console.error((err as Error).message);\n    console.error(usage);\n    process.exit(2);\n  }\n  if (values.help) {\n    console.log(usage);\n    process.exit(0);\n  }\n  return { values, positionals };\n}\n\n// --k must be a positive integer: SQLite reads a bound LIMIT of -1 as \"unlimited\" and 0 as\n// \"nothing\", and parseInt would silently truncate \"5.9\" -- all three are caller mistakes\n// worth a usage error, matching the config-level SavedSearch validation.\nexport function parseK(k: string | undefined, usageError: (message: string) => never): number | undefined {\n  if (k === undefined) return undefined;\n  const parsed = Number(k);\n  if (!Number.isInteger(parsed) || parsed <= 0) usageError(`--k expects a positive integer, got \"${k}\"`);\n  return parsed;\n}\n\n// Shared open-query-close envelope for commands that touch the tree.\n\nexport function printWarnings(warnings: string[]): void {\n  for (const w of warnings) console.warn(w);\n}\n\nexport async function withDb(ctx: Ctx, configPath: string | undefined, fn: (db: OpenResult['db'], cfg: ResolvedConfig) => void | Promise<void>): Promise<void> {\n  const cfg = ctx.resolveConfig(configPath);\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n  try {\n    await fn(db, cfg);\n  } finally {\n    db.close();\n  }\n}\n\n// `--preset` on SQL binds the scope rather than applying it: the statement joins `scope`\n// itself. Filtering behind the query's back is not available -- the obvious version, temp views\n// shadowing the base tables, cannot cover `content`, because FTS5 `MATCH` uses the table name\n// as a hidden column and a view has none. A flag that silently scoped three tables of four\n// would look scoped and not be. See plans/vault-field-report-fixes.md item F.\nfunction bindScope(db: OpenResult['db'], cfg: ResolvedConfig, preset: string): void {\n  const { name } = resolvePreset(cfg, preset); // unknown names throw, listing what is declared\n  db.exec('DROP TABLE IF EXISTS temp.scope');\n  db.exec('CREATE TEMP TABLE scope (\"path\" TEXT PRIMARY KEY)');\n  db.prepare('INSERT INTO temp.scope (\"path\") SELECT \"path\" FROM preset_files WHERE preset = ?').run(name);\n}\n\n// An unbound `?` silently binds NULL, so mismatched param counts fail loudly instead.\nexport function runSql(cfg: ResolvedConfig, sql: string, params: string[], format: RowFormat, label: string, preset?: string): void {\n  const placeholderCount = (sql.match(/\\?/g) ?? []).length;\n  if (params.length !== placeholderCount) {\n    console.error(`${label} expects ${placeholderCount} parameter(s), got ${params.length}`);\n    process.exit(2);\n  }\n  // Naming a preset and never joining it would return the whole index while reading as scoped,\n  // which is the one hazard of binding rather than applying. Refuse instead.\n  if (preset !== undefined && !/\\bscope\\b/i.test(sql)) {\n    console.error(`--preset binds a temporary \"scope\" table of the preset's paths, and ${label} never joins it, so the preset would have no effect`);\n    console.error(`add: JOIN scope ON scope.\"path\" = <table>.\"path\"`);\n    process.exit(2);\n  }\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n  if (preset !== undefined) bindScope(db, cfg, preset);\n  // Streamed rather than collected: `sql` is the one caller whose result size is the\n  // statement's business, not this package's, so the rows are never held here in bulk.\n  // columns() reads the statement's own metadata, so a 0-row csv still has its header.\n  // A mid-stream SQLite error (e.g. SQLITE_BUSY outlasting busy_timeout) can still leave\n  // partial output; the nonzero exit code is the caller's signal, output completeness is not\n  // guaranteed on failure.\n  try {\n    const statement = db.prepare(sql);\n    statement.setReadBigInts(true); // int64 past 2^53 arrives as BigInt instead of throwing at step time\n    const columns = statement.columns().map((c) => c.name);\n    printRowStream(statement.iterate(...params) as Iterable<Row>, format, columns);\n  } catch (err) {\n    db.close();\n    // A saved query or ad-hoc SQL can carry `content MATCH ?` too, so the same FTS5\n    // punctuation trap applies -- the bound parameters are the search terms there. SQL\n    // without MATCH gets its error verbatim; search advice on a plain typo would mislead.\n    if (/\\bMATCH\\b/i.test(sql)) throw searchError(err as Error, params.join(' '));\n    throw err;\n  }\n  db.close();\n}\n"],"names":["parseArgs","resolvePreset","open","printRowStream","searchError","FORMAT","format","type","default","CONFIG","config","SCOPE","where","preset","include","multiple","exclude","SEARCH_FLAGS","k","scopeOf","values","noExclude","pickFormat","allowed","String","includes","console","error","join","process","exit","formatOf","rowFormatOf","parse","argv","usage","options","positionals","args","help","short","strict","allowPositionals","err","message","log","parseK","usageError","undefined","parsed","Number","isInteger","printWarnings","warnings","w","warn","withDb","ctx","configPath","fn","cfg","resolveConfig","db","close","bindScope","name","exec","prepare","run","runSql","sql","params","label","placeholderCount","match","length","test","statement","setReadBigInts","columns","map","c","iterate"],"mappings":"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"}

package/dist/esm/cli/sql.js

@@ -1,5 +1,5 @@
 import { USAGE } from './index.js';
-import { CONFIG, FORMAT, formatOf, parse, runSql } from './shared.js';
+import { CONFIG, FORMAT, parse, rowFormatOf, runSql } from './shared.js';
 const sqlCmd = (ctx)=>{
     const usage = `usage: ${ctx.name} ${USAGE.sql}`;
     const { values, positionals } = parse(ctx.argv, usage, {
@@ -11,7 +11,7 @@ const sqlCmd = (ctx)=>{
     });
     const [sql, ...params] = positionals;
     if (!sql) ctx.usageError(usage);
-    const format = formatOf(values);
+    const format = rowFormatOf(values);
     runSql(ctx.resolveConfig(values.config), sql, params, format, 'ad-hoc statement', values.preset);
 };
 export default sqlCmd;

package/dist/esm/cli/sql.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/sql.ts"],"sourcesContent":["import { USAGE } from './index.ts';\nimport { CONFIG, FORMAT, formatOf, parse, runSql } from './shared.ts';\nimport type { Command } from './types.ts';\n\nconst sqlCmd: Command = (ctx) => {\n  const usage = `usage: ${ctx.name} ${USAGE.sql}`;\n  const { values, positionals } = parse(ctx.argv, usage, { ...FORMAT, ...CONFIG, preset: { type: 'string' } });\n  const [sql, ...params] = positionals;\n  if (!sql) ctx.usageError(usage);\n  const format = formatOf(values);\n  runSql(ctx.resolveConfig(values.config as string | undefined), sql, params, format, 'ad-hoc statement', values.preset as string | undefined);\n};\nexport default sqlCmd;\n"],"names":["USAGE","CONFIG","FORMAT","formatOf","parse","runSql","sqlCmd","ctx","usage","name","sql","values","positionals","argv","preset","type","params","usageError","format","resolveConfig","config"],"mappings":"AAAA,SAASA,KAAK,QAAQ,aAAa;AACnC,SAASC,MAAM,EAAEC,MAAM,EAAEC,QAAQ,EAAEC,KAAK,EAAEC,MAAM,QAAQ,cAAc;AAGtE,MAAMC,SAAkB,CAACC;IACvB,MAAMC,QAAQ,CAAC,OAAO,EAAED,IAAIE,IAAI,CAAC,CAAC,EAAET,MAAMU,GAAG,EAAE;IAC/C,MAAM,EAAEC,MAAM,EAAEC,WAAW,EAAE,GAAGR,MAAMG,IAAIM,IAAI,EAAEL,OAAO;QAAE,GAAGN,MAAM;QAAE,GAAGD,MAAM;QAAEa,QAAQ;YAAEC,MAAM;QAAS;IAAE;IAC1G,MAAM,CAACL,KAAK,GAAGM,OAAO,GAAGJ;IACzB,IAAI,CAACF,KAAKH,IAAIU,UAAU,CAACT;IACzB,MAAMU,SAASf,SAASQ;IACxBN,OAAOE,IAAIY,aAAa,CAACR,OAAOS,MAAM,GAAyBV,KAAKM,QAAQE,QAAQ,oBAAoBP,OAAOG,MAAM;AACvH;AACA,eAAeR,OAAO"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/sql.ts"],"sourcesContent":["import { USAGE } from './index.ts';\nimport { CONFIG, FORMAT, parse, rowFormatOf, runSql } from './shared.ts';\nimport type { Command } from './types.ts';\n\nconst sqlCmd: Command = (ctx) => {\n  const usage = `usage: ${ctx.name} ${USAGE.sql}`;\n  const { values, positionals } = parse(ctx.argv, usage, { ...FORMAT, ...CONFIG, preset: { type: 'string' } });\n  const [sql, ...params] = positionals;\n  if (!sql) ctx.usageError(usage);\n  const format = rowFormatOf(values);\n  runSql(ctx.resolveConfig(values.config as string | undefined), sql, params, format, 'ad-hoc statement', values.preset as string | undefined);\n};\nexport default sqlCmd;\n"],"names":["USAGE","CONFIG","FORMAT","parse","rowFormatOf","runSql","sqlCmd","ctx","usage","name","sql","values","positionals","argv","preset","type","params","usageError","format","resolveConfig","config"],"mappings":"AAAA,SAASA,KAAK,QAAQ,aAAa;AACnC,SAASC,MAAM,EAAEC,MAAM,EAAEC,KAAK,EAAEC,WAAW,EAAEC,MAAM,QAAQ,cAAc;AAGzE,MAAMC,SAAkB,CAACC;IACvB,MAAMC,QAAQ,CAAC,OAAO,EAAED,IAAIE,IAAI,CAAC,CAAC,EAAET,MAAMU,GAAG,EAAE;IAC/C,MAAM,EAAEC,MAAM,EAAEC,WAAW,EAAE,GAAGT,MAAMI,IAAIM,IAAI,EAAEL,OAAO;QAAE,GAAGN,MAAM;QAAE,GAAGD,MAAM;QAAEa,QAAQ;YAAEC,MAAM;QAAS;IAAE;IAC1G,MAAM,CAACL,KAAK,GAAGM,OAAO,GAAGJ;IACzB,IAAI,CAACF,KAAKH,IAAIU,UAAU,CAACT;IACzB,MAAMU,SAASd,YAAYO;IAC3BN,OAAOE,IAAIY,aAAa,CAACR,OAAOS,MAAM,GAAyBV,KAAKM,QAAQE,QAAQ,oBAAoBP,OAAOG,MAAM;AACvH;AACA,eAAeR,OAAO"}

package/dist/esm/cli.js

@@ -22,7 +22,7 @@ function packageVersion() {
 function usage(name) {
     const lines = Object.values(USAGE).map((u)=>`       ${name} ${u}`);
     return [
-        `usage: ${name} <name> [params...] [--format table|json] [--config path]`,
+        `usage: ${name} <name> [params...] [--format table|json|csv] [--config path]`,
         ...lines,
         `       ${name} --list`,
         `       ${name} --version`
@@ -40,6 +40,19 @@ function resolveConfigFor(name, configPath) {
 }
 // Thrown errors -> exit 1 with the message verbatim; usage errors exit 2 directly.
 export default async function cli(argv, name) {
+    // stdout is a pipe whenever the caller pipes or redirects, and a reader that goes away
+    // (`| head`) makes every later write fail. The failure arrives asynchronously, after the
+    // write loop has already returned: console.log absorbs it, process.stdout.write (what the
+    // streaming formats use) does not, so with no listener the process dies on an unhandled
+    // 'error' event having already done its work. Neither throwing nor exiting is safe from
+    // here. The event is async, so a throw is an uncaught exception rather than something
+    // bin/cli.js can catch, and process.exit() would skip the cleanup `sense watch` runs on the
+    // way out, leaving a heartbeat behind that makes a dead watcher look alive.
+    process.stdout.on('error', (err)=>{
+        if (err.code === 'EPIPE') return;
+        console.error(`sense: ${err.message}`);
+        process.exitCode = 1;
+    });
     const first = argv[0];
     // No command word, or the first token looks like a flag: the only flags this level knows.
     if (!first || first.startsWith('-')) {

package/dist/esm/cli.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli.ts"],"sourcesContent":["import { createRequire } from 'node:module';\nimport { parseArgs } from 'node:util';\nimport { COMMANDS, USAGE } from './cli/index.ts';\nimport type { Ctx } from './cli/types.ts';\nimport { loadConfig, SUPPORTED_CONFIG_VERSION } from './config.ts';\n\n// Parsing and dispatch only; commands lazy-load from src/cli/, so nothing heavy is imported\n// here. Flags parse per command -- this file handles only --version/--help/--list/--config.\n\n// Works from dist/cjs and dist/esm alike: walk up past the dist type-marker package.json.\nfunction packageVersion(): string {\n  const load = createRequire(import.meta.url);\n  for (const rel of ['../package.json', '../../package.json', '../../../package.json']) {\n    try {\n      const pkg = load(rel) as { name?: string; version?: string };\n      if (pkg.name === 'sensemaking' && pkg.version) return pkg.version;\n    } catch {}\n  }\n  return 'unknown';\n}\n\nfunction usage(name: string): string {\n  const lines = Object.values(USAGE).map((u) => `       ${name} ${u}`);\n  return [`usage: ${name} <name> [params...] [--format table|json] [--config path]`, ...lines, `       ${name} --list`, `       ${name} --version`].join('\\n');\n}\n\nfunction resolveConfigFor(name: string, configPath: string | undefined) {\n  const cfg = loadConfig(configPath);\n  if (cfg.migratedFrom !== undefined) {\n    console.warn(`${name}: migrated ${cfg.configPath} from config version ${cfg.migratedFrom} to ${SUPPORTED_CONFIG_VERSION}`);\n  }\n  if (cfg.unknownKeys !== undefined) {\n    console.warn(`${name}: ${cfg.configPath} sets ${cfg.unknownKeys.join(', ')}, which this build does not read (no effect); see schema.json for the keys it does`);\n  }\n  return cfg;\n}\n\n// Thrown errors -> exit 1 with the message verbatim; usage errors exit 2 directly.\nexport default async function cli(argv: string[], name: string): Promise<void> {\n  const first = argv[0];\n\n  // No command word, or the first token looks like a flag: the only flags this level knows.\n  if (!first || first.startsWith('-')) {\n    let values: Record<string, string | boolean | undefined>;\n    try {\n      ({ values } = parseArgs({\n        args: argv,\n        options: {\n          version: { type: 'boolean', default: false, short: 'v' },\n          help: { type: 'boolean', default: false, short: 'h' },\n          list: { type: 'boolean', default: false },\n          config: { type: 'string' },\n        },\n        allowPositionals: true,\n      }));\n    } catch (err) {\n      console.error((err as Error).message);\n      console.error(usage(name));\n      process.exit(2);\n    }\n\n    try {\n      if (values.version) {\n        console.log(packageVersion());\n        return;\n      }\n      if (values.help) {\n        console.log(usage(name));\n        return;\n      }\n      if (values.list) {\n        const queries = resolveConfigFor(name, values.config as string | undefined).queries;\n        for (const queryName of Object.keys(queries).sort()) {\n          // Every entry names its verb, so --list can label both kinds rather than only\n          // marking the exception.\n          console.log(`${queryName}  (${'search' in queries[queryName] ? 'search' : 'sql'})`);\n        }\n        return;\n      }\n    } catch (err) {\n      console.error((err as Error).message);\n      process.exit(1);\n    }\n\n    console.error(usage(name));\n    process.exit(2);\n  }\n\n  // Breaking renames get one release of a pointer instead of an \"unknown\" error: find ->\n  // search, and query -> sql (which took its name back from the search sense of \"query\").\n  const RENAMED: Record<string, string> = { find: 'search', query: 'sql' };\n  if (RENAMED[first]) {\n    console.error(`${name}: ${first} is now ${RENAMED[first]}`);\n    console.error(usage(name));\n    process.exit(2);\n  }\n\n  const ctx: Ctx = {\n    name,\n    argv: argv.slice(1),\n    resolveConfig: (configPath) => resolveConfigFor(name, configPath),\n    usageError(message) {\n      console.error(message);\n      process.exit(2);\n    },\n  };\n\n  try {\n    const load = COMMANDS[first];\n    if (load) await (await load()).default(ctx);\n    else await (await import('./cli/named.ts')).default(ctx, first);\n  } catch (err) {\n    console.error((err as Error).message);\n    process.exit(1);\n  }\n}\n"],"names":["createRequire","parseArgs","COMMANDS","USAGE","loadConfig","SUPPORTED_CONFIG_VERSION","packageVersion","load","url","rel","pkg","name","version","usage","lines","Object","values","map","u","join","resolveConfigFor","configPath","cfg","migratedFrom","undefined","console","warn","unknownKeys","cli","argv","first","startsWith","args","options","type","default","short","help","list","config","allowPositionals","err","error","message","process","exit","log","queries","queryName","keys","sort","RENAMED","find","query","ctx","slice","resolveConfig","usageError"],"mappings":"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"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli.ts"],"sourcesContent":["import { createRequire } from 'node:module';\nimport { parseArgs } from 'node:util';\nimport { COMMANDS, USAGE } from './cli/index.ts';\nimport type { Ctx } from './cli/types.ts';\nimport { loadConfig, SUPPORTED_CONFIG_VERSION } from './config.ts';\n\n// Parsing and dispatch only; commands lazy-load from src/cli/, so nothing heavy is imported\n// here. Flags parse per command -- this file handles only --version/--help/--list/--config.\n\n// Works from dist/cjs and dist/esm alike: walk up past the dist type-marker package.json.\nfunction packageVersion(): string {\n  const load = createRequire(import.meta.url);\n  for (const rel of ['../package.json', '../../package.json', '../../../package.json']) {\n    try {\n      const pkg = load(rel) as { name?: string; version?: string };\n      if (pkg.name === 'sensemaking' && pkg.version) return pkg.version;\n    } catch {}\n  }\n  return 'unknown';\n}\n\nfunction usage(name: string): string {\n  const lines = Object.values(USAGE).map((u) => `       ${name} ${u}`);\n  return [`usage: ${name} <name> [params...] [--format table|json|csv] [--config path]`, ...lines, `       ${name} --list`, `       ${name} --version`].join('\\n');\n}\n\nfunction resolveConfigFor(name: string, configPath: string | undefined) {\n  const cfg = loadConfig(configPath);\n  if (cfg.migratedFrom !== undefined) {\n    console.warn(`${name}: migrated ${cfg.configPath} from config version ${cfg.migratedFrom} to ${SUPPORTED_CONFIG_VERSION}`);\n  }\n  if (cfg.unknownKeys !== undefined) {\n    console.warn(`${name}: ${cfg.configPath} sets ${cfg.unknownKeys.join(', ')}, which this build does not read (no effect); see schema.json for the keys it does`);\n  }\n  return cfg;\n}\n\n// Thrown errors -> exit 1 with the message verbatim; usage errors exit 2 directly.\nexport default async function cli(argv: string[], name: string): Promise<void> {\n  // stdout is a pipe whenever the caller pipes or redirects, and a reader that goes away\n  // (`| head`) makes every later write fail. The failure arrives asynchronously, after the\n  // write loop has already returned: console.log absorbs it, process.stdout.write (what the\n  // streaming formats use) does not, so with no listener the process dies on an unhandled\n  // 'error' event having already done its work. Neither throwing nor exiting is safe from\n  // here. The event is async, so a throw is an uncaught exception rather than something\n  // bin/cli.js can catch, and process.exit() would skip the cleanup `sense watch` runs on the\n  // way out, leaving a heartbeat behind that makes a dead watcher look alive.\n  process.stdout.on('error', (err: NodeJS.ErrnoException) => {\n    if (err.code === 'EPIPE') return;\n    console.error(`sense: ${err.message}`);\n    process.exitCode = 1;\n  });\n\n  const first = argv[0];\n\n  // No command word, or the first token looks like a flag: the only flags this level knows.\n  if (!first || first.startsWith('-')) {\n    let values: Record<string, string | boolean | undefined>;\n    try {\n      ({ values } = parseArgs({\n        args: argv,\n        options: {\n          version: { type: 'boolean', default: false, short: 'v' },\n          help: { type: 'boolean', default: false, short: 'h' },\n          list: { type: 'boolean', default: false },\n          config: { type: 'string' },\n        },\n        allowPositionals: true,\n      }));\n    } catch (err) {\n      console.error((err as Error).message);\n      console.error(usage(name));\n      process.exit(2);\n    }\n\n    try {\n      if (values.version) {\n        console.log(packageVersion());\n        return;\n      }\n      if (values.help) {\n        console.log(usage(name));\n        return;\n      }\n      if (values.list) {\n        const queries = resolveConfigFor(name, values.config as string | undefined).queries;\n        for (const queryName of Object.keys(queries).sort()) {\n          // Every entry names its verb, so --list can label both kinds rather than only\n          // marking the exception.\n          console.log(`${queryName}  (${'search' in queries[queryName] ? 'search' : 'sql'})`);\n        }\n        return;\n      }\n    } catch (err) {\n      console.error((err as Error).message);\n      process.exit(1);\n    }\n\n    console.error(usage(name));\n    process.exit(2);\n  }\n\n  // Breaking renames get one release of a pointer instead of an \"unknown\" error: find ->\n  // search, and query -> sql (which took its name back from the search sense of \"query\").\n  const RENAMED: Record<string, string> = { find: 'search', query: 'sql' };\n  if (RENAMED[first]) {\n    console.error(`${name}: ${first} is now ${RENAMED[first]}`);\n    console.error(usage(name));\n    process.exit(2);\n  }\n\n  const ctx: Ctx = {\n    name,\n    argv: argv.slice(1),\n    resolveConfig: (configPath) => resolveConfigFor(name, configPath),\n    usageError(message) {\n      console.error(message);\n      process.exit(2);\n    },\n  };\n\n  try {\n    const load = COMMANDS[first];\n    if (load) await (await load()).default(ctx);\n    else await (await import('./cli/named.ts')).default(ctx, first);\n  } catch (err) {\n    console.error((err as Error).message);\n    process.exit(1);\n  }\n}\n"],"names":["createRequire","parseArgs","COMMANDS","USAGE","loadConfig","SUPPORTED_CONFIG_VERSION","packageVersion","load","url","rel","pkg","name","version","usage","lines","Object","values","map","u","join","resolveConfigFor","configPath","cfg","migratedFrom","undefined","console","warn","unknownKeys","cli","argv","process","stdout","on","err","code","error","message","exitCode","first","startsWith","args","options","type","default","short","help","list","config","allowPositionals","exit","log","queries","queryName","keys","sort","RENAMED","find","query","ctx","slice","resolveConfig","usageError"],"mappings":"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"}

package/dist/esm/commands.d.ts

@@ -32,6 +32,7 @@ export interface TreeMap {
     presets: PresetCoverage[];
     hubs: Row[];
     recent: Row[];
+    recentCaveat: string | null;
 }
 export declare function mapTree(db: DatabaseSync, cfg: ResolvedConfig, overrides?: SearchOverrides): TreeMap;
 export declare function resolveNote(paths: string[], arg: string): string;

package/dist/esm/commands.js

@@ -1,15 +1,18 @@
 import { readFileSync } from 'node:fs';
 import { join, matchesGlob } from 'node:path';
 import posix from 'node:path/posix';
-import { anyPresetEmbeds, embedEnabled, featureEnabled, featureStates, presetNames, presetSemanticEnabled, resolveSearch } from './config.js';
+import { anyPresetEmbeds, contentTokenize, embedEnabled, featureEnabled, featureStates, presetNames, presetSemanticEnabled, resolveSearch } from './config.js';
 import { SenseError } from './errors.js';
 import { embedPending, hasEmbedding, modelPresent, semanticCandidates, similarNotes } from './features/embed.js';
 import { linkEdges } from './features/index.js';
 import { personalizedRank } from './graph.js';
 import { searchError } from './search-error.js';
+import { segmentMatch } from './segment.js';
 // The three commands: mapTree (orient), search (locate), peek (structure).
 // Each returns data; cli.ts renders. All of them degrade when a feature is off.
-const WEIGHTED_BM25 = 'bm25(content, 10.0, 5.0, 1.0)';
+// Mirrors the main columns onto the sidecars, so a title match found through title_seg ranks
+// like a title match found through title, not like a body match.
+const WEIGHTED_BM25 = 'bm25(content, 10.0, 5.0, 1.0, 0, 10.0, 5.0, 1.0)';
 const RRF_K = 60;
 // snippet() re-tokenizes each candidate doc, superlinearly: ~10s for one 1MB doc
 // (BENCHMARKING.md). Past this bound, rows get the linear JS excerpt instead.
@@ -124,43 +127,59 @@ function scopeHasEmbeddings(db, cfg, scopedPaths) {
 export async function search(db, cfg, terms, opts = {}) {
     var _hits_get, _chunkLines_get, _chunkSimilarity_get;
     const effective = resolveSearch(cfg, opts);
-    const { k, include, exclude } = effective;
+    const { k } = effective;
     const allPaths = db.prepare('SELECT "path" FROM frontmatter').all().map((r)=>r.path);
-    // A preset scope reads the coverage reconcile indexed; re-matching globs here could disagree
-    // with it. Only ad-hoc scope flags, which have no persisted coverage, pay the JS match.
-    const adHocScope = opts.include !== undefined || opts.exclude !== undefined || opts.noExclude === true;
-    const scopedPaths = adHocScope ? new Set(allPaths.filter((p)=>inScope(p, include, exclude))) : new Set(db.prepare('SELECT "path" FROM preset_files WHERE preset = ?').all(effective.presetName).map((r)=>r.path));
-    // A scope narrower than the whole index needs a bigger candidate pool before filtering, or
-    // filtering can starve k even though enough in-scope matches exist further down the ranked
-    // list that a plain over-fetch wouldn't have reached.
-    const scopeActive = scopedPaths.size < allPaths.length;
-    const fetch = scopeActive ? Math.max(k * 5, 50) : Math.max(k * 3, 30);
+    const scopePaths = rawScope(db, cfg, opts, allPaths);
+    const scopeActive = scopePaths.size < allPaths.length;
+    // The set every candidate pool must be filtered to before truncation: scope narrowed by
+    // --where, the same composition scopedPaths() gives the other commands. Runs the same where
+    // fragment matchSql does, so a bad column gets the same attributed error either way.
+    let allowedPaths;
+    try {
+        allowedPaths = narrowByWhere(db, scopePaths, effective.where);
+    } catch (err) {
+        throw searchError(err, terms, effective.where);
+    }
+    const fetch = Math.max(k * 3, 30);
     // Asking for vectors without a model is a misconfiguration, not a mode: degrading would make
     // the same search answer differently before and after a download. semantic:false never asks.
     const wantsVectors = effective.semantic && anyPresetEmbeds(cfg);
     if (wantsVectors && !modelPresent(cfg)) {
         throw new SenseError('EMBED_MODEL_MISSING', `preset "${effective.presetName}" searches with vectors, but the embedding model is not available; run \`sense download\`, or set "semantic": false on that preset to search on words and links`);
     }
-    const semanticEnabled = wantsVectors && scopeHasEmbeddings(db, cfg, scopedPaths);
-    // Terms pass verbatim to MATCH; invalid syntax errors rather than being rewritten. --where
+    const semanticEnabled = wantsVectors && scopeHasEmbeddings(db, cfg, allowedPaths);
+    // Terms pass to MATCH as written, with one transform: a run of text whose language marks no
+    // word boundaries becomes a quoted grapheme phrase (and a title:/summary:/text: qualifier
+    // ahead of it retargets its _seg column), matching how it was indexed. Text that already
+    // carries boundaries comes through untouched, so this is a no-op for the languages that
+    // never needed it. Gated on the same predicate that decided whether the sidecars were
+    // populated (contentTokenize(cfg) === undefined), so index and query can't disagree. Invalid
+    // syntax still errors rather than being rewritten.
+    // --where
     // applies inside the candidate query (a post-filter would drop matches ranked past the pool)
     // and again on the final select, for link-derived rows.
     const scope = effective.where;
     const whereJoin = scope ? `JOIN frontmatter f ON f."path" = content.path` : '';
     const whereCond = scope ? `AND (${scope})` : '';
+    // A scope narrower than the whole index must filter the candidate pool before LIMIT, not
+    // after -- otherwise scoped notes ranking below the global top-`fetch` never reach the
+    // filter. A join against a temp table, not a bound parameter list: real scopes run to
+    // thousands of paths, past SQLITE_MAX_VARIABLE_NUMBER on older builds.
+    if (scopeActive) materializeScope(db, '_search_scope', scopePaths);
+    const scopeCond = scopeActive ? `AND content.path IN (SELECT "path" FROM _search_scope)` : '';
     // Docs past SNIPPET_BOUND skip snippet() entirely -- SQLite
     // short-circuits the untaken CASE branch, so it's never invoked on them.
-    const matchSql = `SELECT content.path AS path, CASE WHEN length(content.text) <= ${SNIPPET_BOUND} THEN snippet(content, -1, '«', '»', '…', 10) ELSE NULL END AS hit FROM content ${whereJoin} WHERE content MATCH ? ${whereCond} ORDER BY ${WEIGHTED_BM25} LIMIT ${fetch}`;
+    // Column 2 (text), not -1 (best column): -1 could surface a _seg sidecar as the excerpt,
+    // which is machine-spaced and not what the author wrote. A row that matches only in a
+    // sidecar gets an unhighlighted text excerpt below instead -- a stated cost.
+    const matchSql = `SELECT content.path AS path, CASE WHEN length(content.text) <= ${SNIPPET_BOUND} THEN snippet(content, 2, '«', '»', '…', 10) ELSE NULL END AS hit FROM content ${whereJoin} WHERE content MATCH ? ${whereCond} ${scopeCond} ORDER BY ${WEIGHTED_BM25} LIMIT ${fetch}`;
+    const query = contentTokenize(cfg) === undefined ? segmentMatch(terms) : terms;
     let matchRows;
     try {
-        matchRows = db.prepare(matchSql).all(terms);
+        matchRows = db.prepare(matchSql).all(query);
     } catch (err) {
         throw searchError(err, terms, scope);
     }
-    // Scope filtering happens in JS, on each candidate list, rather than in SQL: FTS5 match,
-    // link expansion, and vector search all run unscoped above (cheap to over-fetch), then get
-    // filtered here against the effective include/exclude before ranking is finalized.
-    matchRows = matchRows.filter((r)=>scopedPaths.has(r.path));
     const hits = new Map(matchRows.map((r)=>[
             r.path,
             r.hit
@@ -186,7 +205,7 @@ export async function search(db, cfg, terms, opts = {}) {
             ]));
         const ranked = [
             ...personalizedRank(allPaths, edges, seeds)
-        ].filter(([path, score])=>score > 1e-9 && scopedPaths.has(path)).sort((a, b)=>b[1] - a[1]).slice(0, fetch);
+        ].filter(([path, score])=>score > 1e-9 && allowedPaths.has(path)).sort((a, b)=>b[1] - a[1]).slice(0, fetch);
         ranked.forEach(([path], i)=>{
             const existing = candidates.get(path);
             if (existing) {
@@ -205,7 +224,7 @@ export async function search(db, cfg, terms, opts = {}) {
     const chunkLines = new Map();
     const chunkSimilarity = new Map();
     if (semanticEnabled) {
-        const vec = (await semanticCandidates(db, cfg, terms, fetch)).filter((v)=>scopedPaths.has(v.path));
+        const vec = await semanticCandidates(db, cfg, terms, fetch, allowedPaths);
         vec.forEach(({ path, lines, similarity }, i)=>{
             chunkLines.set(path, lines);
             chunkSimilarity.set(path, similarity);
@@ -225,8 +244,9 @@ export async function search(db, cfg, terms, opts = {}) {
     db.exec('CREATE TEMP TABLE _search ("path" TEXT PRIMARY KEY, score REAL, via TEXT, hit TEXT, lines TEXT, similarity REAL)');
     const insert = db.prepare('INSERT INTO _search ("path", score, via, hit, lines, similarity) VALUES (?, ?, ?, ?, ?, ?)');
     for (const [path, c] of candidates)insert.run(path, c.score, c.via, (_hits_get = hits.get(path)) !== null && _hits_get !== void 0 ? _hits_get : null, (_chunkLines_get = chunkLines.get(path)) !== null && _chunkLines_get !== void 0 ? _chunkLines_get : null, (_chunkSimilarity_get = chunkSimilarity.get(path)) !== null && _chunkSimilarity_get !== void 0 ? _chunkSimilarity_get : null);
-    // Already scope-filtered above; the final select reapplies --where only for link-derived
-    // rows, which never passed through whereCond.
+    // All three candidate paths (match, link, vector) already filtered to scope+where before
+    // reaching _search; this reapplies --where anyway since the join to frontmatter is already
+    // needed for the path column.
     const where = scope ? `WHERE (${scope})` : '';
     // lines is always present now: semantic rows carry their chunk's range, oversized-doc
     // lexical rows gain one below, everything else stays null. similarity stays semantic-only.
@@ -251,15 +271,18 @@ export async function search(db, cfg, terms, opts = {}) {
     }
     return rows;
 }
-// The scope resolver for non-search commands (path, peek, map): same coverage rule search()
-// applies (preset_files for a named preset, JS glob matching for an ad hoc include/exclude),
-// then narrowed by the resolved `where`.
-export function scopedPaths(db, cfg, overrides) {
+// Scope only (no --where): preset_files for a named preset, JS glob matching for an ad hoc
+// include/exclude override. Shared by scopedPaths() and search(), which also needs the
+// pre-where set to size the candidate-pool filter.
+function rawScope(db, cfg, overrides, allPaths) {
     const effective = resolveSearch(cfg, overrides);
-    const { include, exclude, where } = effective;
-    const allPaths = db.prepare('SELECT "path" FROM frontmatter').all().map((r)=>r.path);
+    const { include, exclude } = effective;
     const adHocScope = overrides.include !== undefined || overrides.exclude !== undefined || overrides.noExclude === true;
-    const paths = adHocScope ? new Set(allPaths.filter((p)=>inScope(p, include, exclude))) : new Set(db.prepare('SELECT "path" FROM preset_files WHERE preset = ?').all(effective.presetName).map((r)=>r.path));
+    if (!adHocScope) return new Set(db.prepare('SELECT "path" FROM preset_files WHERE preset = ?').all(effective.presetName).map((r)=>r.path));
+    const paths = allPaths !== null && allPaths !== void 0 ? allPaths : db.prepare('SELECT "path" FROM frontmatter').all().map((r)=>r.path);
+    return new Set(paths.filter((p)=>inScope(p, include, exclude)));
+}
+function narrowByWhere(db, paths, where) {
     if (!where) return paths;
     const whereRows = db.prepare(`SELECT "path" FROM frontmatter f WHERE (${where})`).all();
     const wherePaths = new Set(whereRows.map((r)=>r.path));
@@ -267,6 +290,12 @@ export function scopedPaths(db, cfg, overrides) {
         ...paths
     ].filter((p)=>wherePaths.has(p)));
 }
+// The scope resolver for non-search commands (path, peek, map): same coverage rule search()
+// applies, then narrowed by the resolved `where`.
+export function scopedPaths(db, cfg, overrides) {
+    const effective = resolveSearch(cfg, overrides);
+    return narrowByWhere(db, rawScope(db, cfg, overrides), effective.where);
+}
 // Indexing derives from presets, so the derivation stays visible. Read from preset_files, not
 // recomputed from globs, so it reflects the cache rather than the config.
 export function presetCoverage(db, cfg) {
@@ -297,15 +326,18 @@ function chunk(items, size) {
     for(let i = 0; i < items.length; i += size)out.push(items.slice(i, i + size));
     return out;
 }
-// Materializes the resolved scope into a temp table (same shape as traverse.ts's
-// allowed_nodes) so every mapTree query can join/filter against it cheaply.
-function setupMapScope(db, paths) {
-    db.exec('DROP TABLE IF EXISTS _map_scope');
-    db.exec('CREATE TEMP TABLE _map_scope ("path" TEXT PRIMARY KEY)');
-    db.prepare('INSERT INTO _map_scope SELECT DISTINCT value FROM json_each(?1)').run(JSON.stringify([
+// Materializes a path set into a named temp table (same shape as traverse.ts's allowed_nodes)
+// so a query can join/filter against it cheaply instead of binding a parameter per path.
+function materializeScope(db, table, paths) {
+    db.exec(`DROP TABLE IF EXISTS ${table}`);
+    db.exec(`CREATE TEMP TABLE ${table} ("path" TEXT PRIMARY KEY)`);
+    db.prepare(`INSERT INTO ${table} SELECT DISTINCT value FROM json_each(?1)`).run(JSON.stringify([
         ...paths
     ]));
 }
+function setupMapScope(db, paths) {
+    materializeScope(db, '_map_scope', paths);
+}
 // What is this scope: fixed-size output regardless of tree size. Coverage and features stay
 // global -- they describe the tree, not the current question.
 export function mapTree(db, cfg, overrides = {}) {
@@ -336,6 +368,10 @@ export function mapTree(db, cfg, overrides = {}) {
     const fields = allFields.slice(0, 20);
     const hubs = featureEnabled(cfg, 'rank') ? db.prepare(`SELECT f."path" AS path, round(f."_rank" * 100, 2) AS rank, content.title FROM frontmatter f JOIN content ON content.path = f."path" WHERE f."_rank" IS NOT NULL ${scopeAnd} ORDER BY f."_rank" DESC LIMIT 8`).all() : [];
     const recent = db.prepare(`SELECT "path", datetime("_mtime" / 1000, 'unixepoch') AS modified FROM frontmatter ${scopeWhere} ORDER BY "_mtime" DESC LIMIT 5`).all();
+    // A fresh clone/copy stamps files with checkout time, not edit history; second granularity
+    // matches the `recent` table above and is coarse enough to catch that without an exact-ms match.
+    const topSecond = db.prepare(`SELECT COUNT(*) AS n FROM frontmatter ${scopeWhere} GROUP BY CAST("_mtime" / 1000 AS INTEGER) ORDER BY n DESC LIMIT 1`).get();
+    const recentCaveat = topSecond && docs.count > 1 && topSecond.n > docs.count / 2 ? `${topSecond.n} of ${docs.count} files share one modified second, so recency likely reflects a checkout or copy, not edit history` : null;
     return {
         docs,
         fields,
@@ -343,7 +379,8 @@ export function mapTree(db, cfg, overrides = {}) {
         features: featureStates(cfg),
         presets: presetCoverage(db, cfg),
         hubs,
-        recent
+        recent,
+        recentCaveat
     };
 }
 // Note resolution shared by peek and path: an exact path, or a unique basename (case