sensemaking 0.23.0 → 0.24.0

package/dist/esm/cli/shared.js

@@ -44,6 +44,12 @@ export const SEARCH_FLAGS = {
     ...SCOPE,
     k: {
         type: 'string'
+    },
+    'snippet-char-limit': {
+        type: 'string'
+    },
+    'snippet-count-limit': {
+        type: 'string'
     }
 };
 // The SCOPE fragment's parsed values as the overrides every scoped command passes down.
@@ -120,6 +126,19 @@ export function parseK(k, usageError) {
     if (!Number.isInteger(parsed) || parsed <= 0) usageError(`--k expects a positive integer, got "${k}"`);
     return parsed;
 }
+// Same positive-integer rule as --k, beside it since both flags come from SEARCH_FLAGS.
+export function parseSnippetCharLimit(value, usageError) {
+    if (value === undefined) return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) usageError(`--snippet-char-limit expects a positive integer, got "${value}"`);
+    return parsed;
+}
+export function parseSnippetCountLimit(value, usageError) {
+    if (value === undefined) return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) usageError(`--snippet-count-limit expects a positive integer, got "${value}"`);
+    return parsed;
+}
 // Shared open-query-close envelope for commands that touch the tree.
 export function printWarnings(warnings) {
     for (const w of warnings)console.warn(w);

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/index.ts';\nimport { resolvePreset } from '../config/index.ts';\nimport { columnHint } from '../output/column-hint.ts';\nimport type { Row, RowFormat } from '../output/output.ts';\nimport { printRowStream } from '../output/output.ts';\nimport { searchError } from '../output/search-error.ts';\nimport type { OpenResult } from '../store/index.ts';\nimport { openStore } from '../store/index.ts';\nimport type { Store } from '../store/types.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.\n// One place to read them: a new scope field is added to the fragment and here, not per-command.\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// parseArgs is strict about flag names; this applies the same strictness to the value.\n// An unrecognised --format is a usage error, not a silent fallback to `table`.\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 \"nothing\", and parseInt would silently truncate \"5.9\".\n// All three are caller mistakes 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: (store: OpenResult['store'], cfg: ResolvedConfig) => void | Promise<void>): Promise<void> {\n  const cfg = ctx.resolveConfig(configPath);\n  const { store, warnings } = await openStore(cfg);\n  printWarnings(warnings);\n  try {\n    await fn(store, cfg);\n  } finally {\n    await store.close();\n  }\n}\n\n// `--preset` on SQL binds a temp `scope` table rather than transparently filtering: temp views shadowing the base tables can't cover `content`, since FTS5 MATCH treats the table name as a hidden column.\n// A flag that silently scoped three tables of four would look scoped and not be.\nasync function bindScope(store: Store, cfg: ResolvedConfig, preset: string): Promise<void> {\n  const { name } = resolvePreset(cfg, preset); // unknown names throw, listing what is declared\n  await store.exec('DROP TABLE IF EXISTS temp.scope');\n  await store.exec('CREATE TEMP TABLE scope (\"path\" TEXT PRIMARY KEY)');\n  const insert = await store.prepare('INSERT INTO temp.scope (\"path\") SELECT \"path\" FROM preset_files WHERE preset = ?');\n  await insert.run(name);\n}\n\n// An unbound `?` silently binds NULL, so mismatched param counts fail loudly instead.\nexport async function runSql(cfg: ResolvedConfig, sql: string, params: string[], format: RowFormat, label: string, preset?: string): Promise<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 { store, warnings } = await openStore(cfg);\n  printWarnings(warnings);\n  if (preset !== undefined) await bindScope(store, cfg, preset);\n  // Streamed, not collected: `sql`'s result size is the caller's business, not ours. columns() reads the statement's own metadata, so a 0-row csv gets a header too.\n  // A mid-stream SQLite error (e.g. SQLITE_BUSY outlasting busy_timeout) may leave partial output; the nonzero exit code is the failure signal, not a completeness guarantee.\n  try {\n    const statement = await store.raw.prepare(sql);\n    const columns = statement.columns().map((c) => c.name);\n    await printRowStream(statement.iterate(...params) as AsyncIterable<Row>, format, columns);\n  } catch (err) {\n    const hinted = columnHint(await store.docs.columns(), err as Error); // columns read while the store is still open\n    await store.close();\n    // A saved query or ad-hoc SQL can carry `content MATCH ?` too, so the same FTS5 punctuation trap applies to its bound parameters.\n    // SQL without MATCH gets its error verbatim; search advice on a plain typo would mislead.\n    if (/\\bMATCH\\b/i.test(sql)) throw searchError(hinted, params.join(' '));\n    throw hinted;\n  }\n  await store.close();\n}\n"],"names":["parseArgs","resolvePreset","columnHint","printRowStream","searchError","openStore","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","store","close","bindScope","name","exec","insert","prepare","run","runSql","sql","params","label","placeholderCount","match","length","test","statement","raw","columns","map","c","iterate","hinted","docs"],"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/index.ts';\nimport { resolvePreset } from '../config/index.ts';\nimport { columnHint } from '../output/column-hint.ts';\nimport type { Row, RowFormat } from '../output/output.ts';\nimport { printRowStream } from '../output/output.ts';\nimport { searchError } from '../output/search-error.ts';\nimport type { OpenResult } from '../store/index.ts';\nimport { openStore } from '../store/index.ts';\nimport type { Store } from '../store/types.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' }, 'snippet-char-limit': { type: 'string' }, 'snippet-count-limit': { 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.\n// One place to read them: a new scope field is added to the fragment and here, not per-command.\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// parseArgs is strict about flag names; this applies the same strictness to the value.\n// An unrecognised --format is a usage error, not a silent fallback to `table`.\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 \"nothing\", and parseInt would silently truncate \"5.9\".\n// All three are caller mistakes 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// Same positive-integer rule as --k, beside it since both flags come from SEARCH_FLAGS.\nexport function parseSnippetCharLimit(value: string | undefined, usageError: (message: string) => never): number | undefined {\n  if (value === undefined) return undefined;\n  const parsed = Number(value);\n  if (!Number.isInteger(parsed) || parsed <= 0) usageError(`--snippet-char-limit expects a positive integer, got \"${value}\"`);\n  return parsed;\n}\n\nexport function parseSnippetCountLimit(value: string | undefined, usageError: (message: string) => never): number | undefined {\n  if (value === undefined) return undefined;\n  const parsed = Number(value);\n  if (!Number.isInteger(parsed) || parsed <= 0) usageError(`--snippet-count-limit expects a positive integer, got \"${value}\"`);\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: (store: OpenResult['store'], cfg: ResolvedConfig) => void | Promise<void>): Promise<void> {\n  const cfg = ctx.resolveConfig(configPath);\n  const { store, warnings } = await openStore(cfg);\n  printWarnings(warnings);\n  try {\n    await fn(store, cfg);\n  } finally {\n    await store.close();\n  }\n}\n\n// `--preset` on SQL binds a temp `scope` table rather than transparently filtering: temp views shadowing the base tables can't cover `content`, since FTS5 MATCH treats the table name as a hidden column.\n// A flag that silently scoped three tables of four would look scoped and not be.\nasync function bindScope(store: Store, cfg: ResolvedConfig, preset: string): Promise<void> {\n  const { name } = resolvePreset(cfg, preset); // unknown names throw, listing what is declared\n  await store.exec('DROP TABLE IF EXISTS temp.scope');\n  await store.exec('CREATE TEMP TABLE scope (\"path\" TEXT PRIMARY KEY)');\n  const insert = await store.prepare('INSERT INTO temp.scope (\"path\") SELECT \"path\" FROM preset_files WHERE preset = ?');\n  await insert.run(name);\n}\n\n// An unbound `?` silently binds NULL, so mismatched param counts fail loudly instead.\nexport async function runSql(cfg: ResolvedConfig, sql: string, params: string[], format: RowFormat, label: string, preset?: string): Promise<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 { store, warnings } = await openStore(cfg);\n  printWarnings(warnings);\n  if (preset !== undefined) await bindScope(store, cfg, preset);\n  // Streamed, not collected: `sql`'s result size is the caller's business, not ours. columns() reads the statement's own metadata, so a 0-row csv gets a header too.\n  // A mid-stream SQLite error (e.g. SQLITE_BUSY outlasting busy_timeout) may leave partial output; the nonzero exit code is the failure signal, not a completeness guarantee.\n  try {\n    const statement = await store.raw.prepare(sql);\n    const columns = statement.columns().map((c) => c.name);\n    await printRowStream(statement.iterate(...params) as AsyncIterable<Row>, format, columns);\n  } catch (err) {\n    const hinted = columnHint(await store.docs.columns(), err as Error); // columns read while the store is still open\n    await store.close();\n    // A saved query or ad-hoc SQL can carry `content MATCH ?` too, so the same FTS5 punctuation trap applies to its bound parameters.\n    // SQL without MATCH gets its error verbatim; search advice on a plain typo would mislead.\n    if (/\\bMATCH\\b/i.test(sql)) throw searchError(hinted, params.join(' '));\n    throw hinted;\n  }\n  await store.close();\n}\n"],"names":["parseArgs","resolvePreset","columnHint","printRowStream","searchError","openStore","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","parseSnippetCharLimit","value","parseSnippetCountLimit","printWarnings","warnings","w","warn","withDb","ctx","configPath","fn","cfg","resolveConfig","store","close","bindScope","name","exec","insert","prepare","run","runSql","sql","params","label","placeholderCount","match","length","test","statement","raw","columns","map","c","iterate","hinted","docs"],"mappings":"AACA,SAASA,SAAS,QAAQ,YAAY;AAEtC,SAASC,aAAa,QAAQ,qBAAqB;AACnD,SAASC,UAAU,QAAQ,2BAA2B;AAEtD,SAASC,cAAc,QAAQ,sBAAsB;AACrD,SAASC,WAAW,QAAQ,4BAA4B;AAExD,SAASC,SAAS,QAAQ,oBAAoB;AAI9C,+FAA+F;AAC/F,OAAO,MAAMC,SAAiC;IAAEC,QAAQ;QAAEC,MAAM;QAAUC,SAAS;IAAQ;AAAE,EAAE;AAC/F,OAAO,MAAMC,SAAiC;IAAEC,QAAQ;QAAEH,MAAM;IAAS;AAAE,EAAE;AAC7E,yFAAyF;AACzF,sDAAsD;AACtD,OAAO,MAAMI,QAAgC;IAC3CC,OAAO;QAAEL,MAAM;IAAS;IACxBM,QAAQ;QAAEN,MAAM;IAAS;IACzBO,SAAS;QAAEP,MAAM;QAAUQ,UAAU;IAAK;IAC1CC,SAAS;QAAET,MAAM;QAAUQ,UAAU;IAAK;IAC1C,yFAAyF;IACzF,gFAAgF;IAChF,cAAc;QAAER,MAAM;QAAWC,SAAS;IAAM;AAClD,EAAE;AACF,OAAO,MAAMS,eAAuC;IAAE,GAAGN,KAAK;IAAEO,GAAG;QAAEX,MAAM;IAAS;IAAG,sBAAsB;QAAEA,MAAM;IAAS;IAAG,uBAAuB;QAAEA,MAAM;IAAS;AAAE,EAAE;AAI7K,wFAAwF;AACxF,gGAAgG;AAChG,OAAO,SAASY,QAAQC,MAAc;IACpC,OAAO;QACLP,QAAQO,OAAOP,MAAM;QACrBC,SAASM,OAAON,OAAO;QACvBE,SAASI,OAAOJ,OAAO;QACvBJ,OAAOQ,OAAOR,KAAK;QACnBS,WAAWD,MAAM,CAAC,aAAa,KAAK;IACtC;AACF;AAEA,uFAAuF;AACvF,+EAA+E;AAC/E,SAASE,WAA6BF,MAAc,EAAEG,OAAqB;IACzE,MAAMjB,SAASkB,OAAOJ,OAAOd,MAAM;IACnC,IAAI,AAACiB,QAA8BE,QAAQ,CAACnB,SAAS,OAAOA;IAC5DoB,QAAQC,KAAK,CAAC,CAAC,kBAAkB,EAAErB,OAAO,YAAY,EAAEiB,QAAQK,IAAI,CAAC,OAAO;IAC5EC,QAAQC,IAAI,CAAC;AACf;AAEA,OAAO,SAASC,SAASX,MAAc;IACrC,OAAOE,WAAWF,QAAQ;QAAC;QAAS;KAAO;AAC7C;AAEA,4FAA4F;AAC5F,qBAAqB;AACrB,OAAO,SAASY,YAAYZ,MAAc;IACxC,OAAOE,WAAWF,QAAQ;QAAC;QAAS;QAAQ;KAAM;AACpD;AAEA,gGAAgG;AAChG,OAAO,SAASa,MAAMC,IAAc,EAAEC,KAAa,EAAEC,OAA+B;IAClF,IAAIhB;IACJ,IAAIiB;IACJ,IAAI;QACD,CAAA,EAAEjB,MAAM,EAAEiB,WAAW,EAAE,GAAGtC,UAAU;YACnCuC,MAAMJ;YACNE,SAAS;gBAAE,GAAGA,OAAO;gBAAEG,MAAM;oBAAEhC,MAAM;oBAAWC,SAAS;oBAAOgC,OAAO;gBAAI;YAAE;YAC7EC,QAAQ;YACRC,kBAAkB;QACpB,EAAC;IACH,EAAE,OAAOC,KAAK;QACZjB,QAAQC,KAAK,CAAC,AAACgB,IAAcC,OAAO;QACpClB,QAAQC,KAAK,CAACQ;QACdN,QAAQC,IAAI,CAAC;IACf;IACA,IAAIV,OAAOmB,IAAI,EAAE;QACfb,QAAQmB,GAAG,CAACV;QACZN,QAAQC,IAAI,CAAC;IACf;IACA,OAAO;QAAEV;QAAQiB;IAAY;AAC/B;AAEA,kJAAkJ;AAClJ,uGAAuG;AACvG,OAAO,SAASS,OAAO5B,CAAqB,EAAE6B,UAAsC;IAClF,IAAI7B,MAAM8B,WAAW,OAAOA;IAC5B,MAAMC,SAASC,OAAOhC;IACtB,IAAI,CAACgC,OAAOC,SAAS,CAACF,WAAWA,UAAU,GAAGF,WAAW,CAAC,qCAAqC,EAAE7B,EAAE,CAAC,CAAC;IACrG,OAAO+B;AACT;AAEA,wFAAwF;AACxF,OAAO,SAASG,sBAAsBC,KAAyB,EAAEN,UAAsC;IACrG,IAAIM,UAAUL,WAAW,OAAOA;IAChC,MAAMC,SAASC,OAAOG;IACtB,IAAI,CAACH,OAAOC,SAAS,CAACF,WAAWA,UAAU,GAAGF,WAAW,CAAC,sDAAsD,EAAEM,MAAM,CAAC,CAAC;IAC1H,OAAOJ;AACT;AAEA,OAAO,SAASK,uBAAuBD,KAAyB,EAAEN,UAAsC;IACtG,IAAIM,UAAUL,WAAW,OAAOA;IAChC,MAAMC,SAASC,OAAOG;IACtB,IAAI,CAACH,OAAOC,SAAS,CAACF,WAAWA,UAAU,GAAGF,WAAW,CAAC,uDAAuD,EAAEM,MAAM,CAAC,CAAC;IAC3H,OAAOJ;AACT;AAEA,qEAAqE;AAErE,OAAO,SAASM,cAAcC,QAAkB;IAC9C,KAAK,MAAMC,KAAKD,SAAU9B,QAAQgC,IAAI,CAACD;AACzC;AAEA,OAAO,eAAeE,OAAOC,GAAQ,EAAEC,UAA8B,EAAEC,EAA6E;IAClJ,MAAMC,MAAMH,IAAII,aAAa,CAACH;IAC9B,MAAM,EAAEI,KAAK,EAAET,QAAQ,EAAE,GAAG,MAAMpD,UAAU2D;IAC5CR,cAAcC;IACd,IAAI;QACF,MAAMM,GAAGG,OAAOF;IAClB,SAAU;QACR,MAAME,MAAMC,KAAK;IACnB;AACF;AAEA,2MAA2M;AAC3M,iFAAiF;AACjF,eAAeC,UAAUF,KAAY,EAAEF,GAAmB,EAAElD,MAAc;IACxE,MAAM,EAAEuD,IAAI,EAAE,GAAGpE,cAAc+D,KAAKlD,SAAS,gDAAgD;IAC7F,MAAMoD,MAAMI,IAAI,CAAC;IACjB,MAAMJ,MAAMI,IAAI,CAAC;IACjB,MAAMC,SAAS,MAAML,MAAMM,OAAO,CAAC;IACnC,MAAMD,OAAOE,GAAG,CAACJ;AACnB;AAEA,sFAAsF;AACtF,OAAO,eAAeK,OAAOV,GAAmB,EAAEW,GAAW,EAAEC,MAAgB,EAAErE,MAAiB,EAAEsE,KAAa,EAAE/D,MAAe;QACtG6D;IAA1B,MAAMG,mBAAmB,EAACH,aAAAA,IAAII,KAAK,CAAC,oBAAVJ,wBAAAA,aAAoB,EAAE,EAAEK,MAAM;IACxD,IAAIJ,OAAOI,MAAM,KAAKF,kBAAkB;QACtCnD,QAAQC,KAAK,CAAC,GAAGiD,MAAM,SAAS,EAAEC,iBAAiB,mBAAmB,EAAEF,OAAOI,MAAM,EAAE;QACvFlD,QAAQC,IAAI,CAAC;IACf;IACA,6FAA6F;IAC7F,2EAA2E;IAC3E,IAAIjB,WAAWmC,aAAa,CAAC,aAAagC,IAAI,CAACN,MAAM;QACnDhD,QAAQC,KAAK,CAAC,CAAC,oEAAoE,EAAEiD,MAAM,mDAAmD,CAAC;QAC/IlD,QAAQC,KAAK,CAAC,CAAC,gDAAgD,CAAC;QAChEE,QAAQC,IAAI,CAAC;IACf;IACA,MAAM,EAAEmC,KAAK,EAAET,QAAQ,EAAE,GAAG,MAAMpD,UAAU2D;IAC5CR,cAAcC;IACd,IAAI3C,WAAWmC,WAAW,MAAMmB,UAAUF,OAAOF,KAAKlD;IACtD,mKAAmK;IACnK,4KAA4K;IAC5K,IAAI;QACF,MAAMoE,YAAY,MAAMhB,MAAMiB,GAAG,CAACX,OAAO,CAACG;QAC1C,MAAMS,UAAUF,UAAUE,OAAO,GAAGC,GAAG,CAAC,CAACC,IAAMA,EAAEjB,IAAI;QACrD,MAAMlE,eAAe+E,UAAUK,OAAO,IAAIX,SAA+BrE,QAAQ6E;IACnF,EAAE,OAAOxC,KAAK;QACZ,MAAM4C,SAAStF,WAAW,MAAMgE,MAAMuB,IAAI,CAACL,OAAO,IAAIxC,MAAe,6CAA6C;QAClH,MAAMsB,MAAMC,KAAK;QACjB,kIAAkI;QAClI,0FAA0F;QAC1F,IAAI,aAAac,IAAI,CAACN,MAAM,MAAMvE,YAAYoF,QAAQZ,OAAO/C,IAAI,CAAC;QAClE,MAAM2D;IACR;IACA,MAAMtB,MAAMC,KAAK;AACnB"}

package/dist/esm/commands/map.js

@@ -29,8 +29,8 @@ export async function mapTree(store, cfg, overrides = {}) {
         for (const group of chunk(columns, MAP_COLUMN_CHUNK))allFields.push(...await store.docs.fieldStats(group, scopeWhere));
         allFields.sort((a, b)=>b.coverage - a.coverage);
         const fields = allFields.slice(0, 20);
-        const hubs = featureEnabled(cfg, 'rank') ? await (await store.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 = (await (await store.prepare(`SELECT "path", "_mtime" AS mtime FROM frontmatter ${scopeWhere} ORDER BY "_mtime" DESC LIMIT 5`)).all()).map((r)=>({
+        const hubs = featureEnabled(cfg, 'rank') ? await (await store.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, f."path" ASC LIMIT 8`)).all() : [];
+        const recent = (await (await store.prepare(`SELECT "path", "_mtime" AS mtime FROM frontmatter ${scopeWhere} ORDER BY "_mtime" DESC, "path" ASC LIMIT 5`)).all()).map((r)=>({
                 path: r.path,
                 modified: utcSecond(r.mtime)
             }));

package/dist/esm/commands/map.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/commands/map.ts"],"sourcesContent":["import type { FeatureName, ResolvedConfig, SearchOverrides } from '../config/index.ts';\nimport { featureEnabled, featureStates } from '../config/index.ts';\nimport type { Row } from '../output/output.ts';\nimport type { FieldStat, Store } from '../store/types.ts';\nimport { INTERNAL_COLUMNS, scopedPaths, setupMapScope } from './scope.ts';\nimport type { PresetCoverage } from './status.ts';\nimport { presetCoverage } from './status.ts';\n\nexport interface TreeMap {\n  docs: { count: number; bytes: number };\n  fields: Row[]; // top 20 by coverage; fieldsTotal carries the real count\n  fieldsTotal: number;\n  features: { on: FeatureName[]; off: FeatureName[] };\n  presets: PresetCoverage[];\n  hubs: Row[];\n  recent: Row[];\n  recentCaveat: string | null;\n}\n\n// A result row is capped at SQLITE_MAX_COLUMN (2000, default); two aggregate expressions per\n// field keeps a chunk's row width safely under that regardless of how many fields the tree has.\nconst MAP_COLUMN_CHUNK = 300;\n\n// \"YYYY-MM-DD HH:MM:SS\" UTC, the exact shape sqlite's datetime(ms / 1000, 'unixepoch') prints;\n// formatted in JS so the query stays dialect-free.\nfunction utcSecond(ms: number): string {\n  return new Date(ms).toISOString().slice(0, 19).replace('T', ' ');\n}\n\nfunction chunk<T>(items: T[], size: number): T[][] {\n  const out: T[][] = [];\n  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));\n  return out;\n}\n\n// What is this scope: fixed-size output regardless of tree size. Coverage and features stay\n// global -- they describe the tree, not the current question.\nexport async function mapTree(store: Store, cfg: ResolvedConfig, overrides: SearchOverrides = {}): Promise<TreeMap> {\n  return store.transaction(async () => {\n    await setupMapScope(store, await scopedPaths(store, cfg, overrides));\n    const scopeWhere = 'WHERE \"path\" IN (SELECT \"path\" FROM _map_scope)';\n    const scopeAnd = 'AND f.\"path\" IN (SELECT \"path\" FROM _map_scope)';\n\n    const docs = (await (await store.prepare(`SELECT COUNT(*) AS count, COALESCE(SUM(\"_size\"), 0) AS bytes FROM frontmatter ${scopeWhere}`)).get()) as { count: number; bytes: number };\n\n    const columns = (await store.docs.columns()).filter((name) => !INTERNAL_COLUMNS.has(name));\n    // Observed types, not declared: a field can be text in most notes and numeric in a few, so\n    // every distinct type observed across the scope is reported, not just the first.\n    const allFields: FieldStat[] = [];\n    for (const group of chunk(columns, MAP_COLUMN_CHUNK)) allFields.push(...(await store.docs.fieldStats(group, scopeWhere)));\n    allFields.sort((a, b) => b.coverage - a.coverage);\n    const fields = allFields.slice(0, 20) as unknown as Row[];\n\n    const hubs = featureEnabled(cfg, 'rank') ? ((await (await store.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()) as Row[]) : [];\n\n    const recent = ((await (await store.prepare(`SELECT \"path\", \"_mtime\" AS mtime FROM frontmatter ${scopeWhere} ORDER BY \"_mtime\" DESC LIMIT 5`)).all()) as Array<{ path: string; mtime: number }>).map((r) => ({ path: r.path, modified: utcSecond(r.mtime) }));\n\n    // A fresh clone/copy stamps files with checkout time, not edit history; second granularity\n    // matches the `recent` table above and is coarse enough to catch that without an exact-ms match.\n    const topSecond = (await (await store.prepare(`SELECT COUNT(*) AS n FROM frontmatter ${scopeWhere} GROUP BY CAST(\"_mtime\" / 1000 AS INTEGER) ORDER BY n DESC LIMIT 1`)).get()) as { n: number } | undefined;\n    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;\n\n    return { docs, fields, fieldsTotal: allFields.length, features: featureStates(cfg), presets: await presetCoverage(store, cfg), hubs, recent, recentCaveat };\n  });\n}\n"],"names":["featureEnabled","featureStates","INTERNAL_COLUMNS","scopedPaths","setupMapScope","presetCoverage","MAP_COLUMN_CHUNK","utcSecond","ms","Date","toISOString","slice","replace","chunk","items","size","out","i","length","push","mapTree","store","cfg","overrides","transaction","scopeWhere","scopeAnd","docs","prepare","get","columns","filter","name","has","allFields","group","fieldStats","sort","a","b","coverage","fields","hubs","all","recent","map","r","path","modified","mtime","topSecond","recentCaveat","count","n","fieldsTotal","features","presets"],"mappings":"AACA,SAASA,cAAc,EAAEC,aAAa,QAAQ,qBAAqB;AAGnE,SAASC,gBAAgB,EAAEC,WAAW,EAAEC,aAAa,QAAQ,aAAa;AAE1E,SAASC,cAAc,QAAQ,cAAc;AAa7C,6FAA6F;AAC7F,gGAAgG;AAChG,MAAMC,mBAAmB;AAEzB,+FAA+F;AAC/F,mDAAmD;AACnD,SAASC,UAAUC,EAAU;IAC3B,OAAO,IAAIC,KAAKD,IAAIE,WAAW,GAAGC,KAAK,CAAC,GAAG,IAAIC,OAAO,CAAC,KAAK;AAC9D;AAEA,SAASC,MAASC,KAAU,EAAEC,IAAY;IACxC,MAAMC,MAAa,EAAE;IACrB,IAAK,IAAIC,IAAI,GAAGA,IAAIH,MAAMI,MAAM,EAAED,KAAKF,KAAMC,IAAIG,IAAI,CAACL,MAAMH,KAAK,CAACM,GAAGA,IAAIF;IACzE,OAAOC;AACT;AAEA,4FAA4F;AAC5F,8DAA8D;AAC9D,OAAO,eAAeI,QAAQC,KAAY,EAAEC,GAAmB,EAAEC,YAA6B,CAAC,CAAC;IAC9F,OAAOF,MAAMG,WAAW,CAAC;QACvB,MAAMpB,cAAciB,OAAO,MAAMlB,YAAYkB,OAAOC,KAAKC;QACzD,MAAME,aAAa;QACnB,MAAMC,WAAW;QAEjB,MAAMC,OAAQ,MAAM,AAAC,CAAA,MAAMN,MAAMO,OAAO,CAAC,CAAC,8EAA8E,EAAEH,YAAY,CAAA,EAAGI,GAAG;QAE5I,MAAMC,UAAU,AAAC,CAAA,MAAMT,MAAMM,IAAI,CAACG,OAAO,EAAC,EAAGC,MAAM,CAAC,CAACC,OAAS,CAAC9B,iBAAiB+B,GAAG,CAACD;QACpF,2FAA2F;QAC3F,iFAAiF;QACjF,MAAME,YAAyB,EAAE;QACjC,KAAK,MAAMC,SAAStB,MAAMiB,SAASxB,kBAAmB4B,UAAUf,IAAI,IAAK,MAAME,MAAMM,IAAI,CAACS,UAAU,CAACD,OAAOV;QAC5GS,UAAUG,IAAI,CAAC,CAACC,GAAGC,IAAMA,EAAEC,QAAQ,GAAGF,EAAEE,QAAQ;QAChD,MAAMC,SAASP,UAAUvB,KAAK,CAAC,GAAG;QAElC,MAAM+B,OAAO1C,eAAesB,KAAK,UAAY,MAAM,AAAC,CAAA,MAAMD,MAAMO,OAAO,CAAC,CAAC,iKAAiK,EAAEF,SAAS,gCAAgC,CAAC,CAAA,EAAGiB,GAAG,KAAgB,EAAE;QAE9S,MAAMC,SAAS,AAAE,CAAA,MAAM,AAAC,CAAA,MAAMvB,MAAMO,OAAO,CAAC,CAAC,kDAAkD,EAAEH,WAAW,+BAA+B,CAAC,CAAA,EAAGkB,GAAG,EAAC,EAA8CE,GAAG,CAAC,CAACC,IAAO,CAAA;gBAAEC,MAAMD,EAAEC,IAAI;gBAAEC,UAAUzC,UAAUuC,EAAEG,KAAK;YAAE,CAAA;QAE1P,2FAA2F;QAC3F,iGAAiG;QACjG,MAAMC,YAAa,MAAM,AAAC,CAAA,MAAM7B,MAAMO,OAAO,CAAC,CAAC,sCAAsC,EAAEH,WAAW,kEAAkE,CAAC,CAAA,EAAGI,GAAG;QAC3K,MAAMsB,eAAeD,aAAavB,KAAKyB,KAAK,GAAG,KAAKF,UAAUG,CAAC,GAAG1B,KAAKyB,KAAK,GAAG,IAAI,GAAGF,UAAUG,CAAC,CAAC,IAAI,EAAE1B,KAAKyB,KAAK,CAAC,iGAAiG,CAAC,GAAG;QAExN,OAAO;YAAEzB;YAAMc;YAAQa,aAAapB,UAAUhB,MAAM;YAAEqC,UAAUtD,cAAcqB;YAAMkC,SAAS,MAAMnD,eAAegB,OAAOC;YAAMoB;YAAME;YAAQO;QAAa;IAC5J;AACF"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/commands/map.ts"],"sourcesContent":["import type { FeatureName, ResolvedConfig, SearchOverrides } from '../config/index.ts';\nimport { featureEnabled, featureStates } from '../config/index.ts';\nimport type { Row } from '../output/output.ts';\nimport type { FieldStat, Store } from '../store/types.ts';\nimport { INTERNAL_COLUMNS, scopedPaths, setupMapScope } from './scope.ts';\nimport type { PresetCoverage } from './status.ts';\nimport { presetCoverage } from './status.ts';\n\nexport interface TreeMap {\n  docs: { count: number; bytes: number };\n  fields: Row[]; // top 20 by coverage; fieldsTotal carries the real count\n  fieldsTotal: number;\n  features: { on: FeatureName[]; off: FeatureName[] };\n  presets: PresetCoverage[];\n  hubs: Row[];\n  recent: Row[];\n  recentCaveat: string | null;\n}\n\n// A result row is capped at SQLITE_MAX_COLUMN (2000, default); two aggregate expressions per\n// field keeps a chunk's row width safely under that regardless of how many fields the tree has.\nconst MAP_COLUMN_CHUNK = 300;\n\n// \"YYYY-MM-DD HH:MM:SS\" UTC, the exact shape sqlite's datetime(ms / 1000, 'unixepoch') prints;\n// formatted in JS so the query stays dialect-free.\nfunction utcSecond(ms: number): string {\n  return new Date(ms).toISOString().slice(0, 19).replace('T', ' ');\n}\n\nfunction chunk<T>(items: T[], size: number): T[][] {\n  const out: T[][] = [];\n  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));\n  return out;\n}\n\n// What is this scope: fixed-size output regardless of tree size. Coverage and features stay\n// global -- they describe the tree, not the current question.\nexport async function mapTree(store: Store, cfg: ResolvedConfig, overrides: SearchOverrides = {}): Promise<TreeMap> {\n  return store.transaction(async () => {\n    await setupMapScope(store, await scopedPaths(store, cfg, overrides));\n    const scopeWhere = 'WHERE \"path\" IN (SELECT \"path\" FROM _map_scope)';\n    const scopeAnd = 'AND f.\"path\" IN (SELECT \"path\" FROM _map_scope)';\n\n    const docs = (await (await store.prepare(`SELECT COUNT(*) AS count, COALESCE(SUM(\"_size\"), 0) AS bytes FROM frontmatter ${scopeWhere}`)).get()) as { count: number; bytes: number };\n\n    const columns = (await store.docs.columns()).filter((name) => !INTERNAL_COLUMNS.has(name));\n    // Observed types, not declared: a field can be text in most notes and numeric in a few, so\n    // every distinct type observed across the scope is reported, not just the first.\n    const allFields: FieldStat[] = [];\n    for (const group of chunk(columns, MAP_COLUMN_CHUNK)) allFields.push(...(await store.docs.fieldStats(group, scopeWhere)));\n    allFields.sort((a, b) => b.coverage - a.coverage);\n    const fields = allFields.slice(0, 20) as unknown as Row[];\n\n    const hubs = featureEnabled(cfg, 'rank')\n      ? ((await (await store.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, f.\"path\" ASC LIMIT 8`)).all()) as Row[])\n      : [];\n\n    const recent = ((await (await store.prepare(`SELECT \"path\", \"_mtime\" AS mtime FROM frontmatter ${scopeWhere} ORDER BY \"_mtime\" DESC, \"path\" ASC LIMIT 5`)).all()) as Array<{ path: string; mtime: number }>).map((r) => ({ path: r.path, modified: utcSecond(r.mtime) }));\n\n    // A fresh clone/copy stamps files with checkout time, not edit history; second granularity\n    // matches the `recent` table above and is coarse enough to catch that without an exact-ms match.\n    const topSecond = (await (await store.prepare(`SELECT COUNT(*) AS n FROM frontmatter ${scopeWhere} GROUP BY CAST(\"_mtime\" / 1000 AS INTEGER) ORDER BY n DESC LIMIT 1`)).get()) as { n: number } | undefined;\n    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;\n\n    return { docs, fields, fieldsTotal: allFields.length, features: featureStates(cfg), presets: await presetCoverage(store, cfg), hubs, recent, recentCaveat };\n  });\n}\n"],"names":["featureEnabled","featureStates","INTERNAL_COLUMNS","scopedPaths","setupMapScope","presetCoverage","MAP_COLUMN_CHUNK","utcSecond","ms","Date","toISOString","slice","replace","chunk","items","size","out","i","length","push","mapTree","store","cfg","overrides","transaction","scopeWhere","scopeAnd","docs","prepare","get","columns","filter","name","has","allFields","group","fieldStats","sort","a","b","coverage","fields","hubs","all","recent","map","r","path","modified","mtime","topSecond","recentCaveat","count","n","fieldsTotal","features","presets"],"mappings":"AACA,SAASA,cAAc,EAAEC,aAAa,QAAQ,qBAAqB;AAGnE,SAASC,gBAAgB,EAAEC,WAAW,EAAEC,aAAa,QAAQ,aAAa;AAE1E,SAASC,cAAc,QAAQ,cAAc;AAa7C,6FAA6F;AAC7F,gGAAgG;AAChG,MAAMC,mBAAmB;AAEzB,+FAA+F;AAC/F,mDAAmD;AACnD,SAASC,UAAUC,EAAU;IAC3B,OAAO,IAAIC,KAAKD,IAAIE,WAAW,GAAGC,KAAK,CAAC,GAAG,IAAIC,OAAO,CAAC,KAAK;AAC9D;AAEA,SAASC,MAASC,KAAU,EAAEC,IAAY;IACxC,MAAMC,MAAa,EAAE;IACrB,IAAK,IAAIC,IAAI,GAAGA,IAAIH,MAAMI,MAAM,EAAED,KAAKF,KAAMC,IAAIG,IAAI,CAACL,MAAMH,KAAK,CAACM,GAAGA,IAAIF;IACzE,OAAOC;AACT;AAEA,4FAA4F;AAC5F,8DAA8D;AAC9D,OAAO,eAAeI,QAAQC,KAAY,EAAEC,GAAmB,EAAEC,YAA6B,CAAC,CAAC;IAC9F,OAAOF,MAAMG,WAAW,CAAC;QACvB,MAAMpB,cAAciB,OAAO,MAAMlB,YAAYkB,OAAOC,KAAKC;QACzD,MAAME,aAAa;QACnB,MAAMC,WAAW;QAEjB,MAAMC,OAAQ,MAAM,AAAC,CAAA,MAAMN,MAAMO,OAAO,CAAC,CAAC,8EAA8E,EAAEH,YAAY,CAAA,EAAGI,GAAG;QAE5I,MAAMC,UAAU,AAAC,CAAA,MAAMT,MAAMM,IAAI,CAACG,OAAO,EAAC,EAAGC,MAAM,CAAC,CAACC,OAAS,CAAC9B,iBAAiB+B,GAAG,CAACD;QACpF,2FAA2F;QAC3F,iFAAiF;QACjF,MAAME,YAAyB,EAAE;QACjC,KAAK,MAAMC,SAAStB,MAAMiB,SAASxB,kBAAmB4B,UAAUf,IAAI,IAAK,MAAME,MAAMM,IAAI,CAACS,UAAU,CAACD,OAAOV;QAC5GS,UAAUG,IAAI,CAAC,CAACC,GAAGC,IAAMA,EAAEC,QAAQ,GAAGF,EAAEE,QAAQ;QAChD,MAAMC,SAASP,UAAUvB,KAAK,CAAC,GAAG;QAElC,MAAM+B,OAAO1C,eAAesB,KAAK,UAC3B,MAAM,AAAC,CAAA,MAAMD,MAAMO,OAAO,CAAC,CAAC,iKAAiK,EAAEF,SAAS,8CAA8C,CAAC,CAAA,EAAGiB,GAAG,KAC/P,EAAE;QAEN,MAAMC,SAAS,AAAE,CAAA,MAAM,AAAC,CAAA,MAAMvB,MAAMO,OAAO,CAAC,CAAC,kDAAkD,EAAEH,WAAW,2CAA2C,CAAC,CAAA,EAAGkB,GAAG,EAAC,EAA8CE,GAAG,CAAC,CAACC,IAAO,CAAA;gBAAEC,MAAMD,EAAEC,IAAI;gBAAEC,UAAUzC,UAAUuC,EAAEG,KAAK;YAAE,CAAA;QAEtQ,2FAA2F;QAC3F,iGAAiG;QACjG,MAAMC,YAAa,MAAM,AAAC,CAAA,MAAM7B,MAAMO,OAAO,CAAC,CAAC,sCAAsC,EAAEH,WAAW,kEAAkE,CAAC,CAAA,EAAGI,GAAG;QAC3K,MAAMsB,eAAeD,aAAavB,KAAKyB,KAAK,GAAG,KAAKF,UAAUG,CAAC,GAAG1B,KAAKyB,KAAK,GAAG,IAAI,GAAGF,UAAUG,CAAC,CAAC,IAAI,EAAE1B,KAAKyB,KAAK,CAAC,iGAAiG,CAAC,GAAG;QAExN,OAAO;YAAEzB;YAAMc;YAAQa,aAAapB,UAAUhB,MAAM;YAAEqC,UAAUtD,cAAcqB;YAAMkC,SAAS,MAAMnD,eAAegB,OAAOC;YAAMoB;YAAME;YAAQO;QAAa;IAC5J;AACF"}

package/dist/esm/commands/search.d.ts

@@ -1,6 +1,13 @@
 import type { ResolvedConfig } from '../config/index.js';
 import type { Row } from '../output/output.js';
 import type { Store } from '../store/types.js';
+export declare const SNIPPET_CHAR_LIMIT_DEFAULT = 80;
+export declare const SNIPPET_COUNT_LIMIT_DEFAULT = 1;
+export declare function computeSnippets(text: string, terms: string[], charLimit: number, countLimit: number): {
+    snippets: string[];
+    offset: number;
+};
+export declare function lineNumberAt(text: string, offset: number): number;
 export interface SearchOptions {
     k?: number;
     where?: string;
@@ -8,5 +15,8 @@ export interface SearchOptions {
     include?: string[];
     exclude?: string[];
     noExclude?: boolean;
+    snippetCharLimit?: number;
+    snippetCountLimit?: number;
 }
+export declare function hydrateSearchRows(store: Store, cfg: ResolvedConfig, rows: Row[], matchedPaths: Set<string>, terms: string, opts?: Pick<SearchOptions, 'snippetCharLimit' | 'snippetCountLimit'>): Promise<void>;
 export declare function search(store: Store, cfg: ResolvedConfig, terms: string, opts?: SearchOptions): Promise<Row[]>;

package/dist/esm/commands/search.js

@@ -1,96 +1,266 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { stemmer } from 'stemmer';
 import { embedConfig, featureEnabled, resolveSearch } from '../config/index.js';
 import { localModelMissing, MODEL_FILENAMES } from '../embed/store.js';
 import { SenseError } from '../errors.js';
-import { searchError } from '../output/search-error.js';
+import { bareTermSyntaxError, searchError } from '../output/search-error.js';
+import { foldForSearch, hasUnspacedRun, searchTokens, unspacedRuns } from '../text/segment.js';
 import { materializeScope, narrowByWhere, rawScope, scopeHasEmbeddings } from './scope.js';
 import { linksCandidates, vectorsCandidates, wordsCandidates } from './signals.js';
-// snippet() re-tokenizes each candidate doc, superlinearly: ~10s for one 1MB doc
-// (benchmark/reports/2026-08-23-0.13.2-hub-release-battery.md). Past this bound, rows get the JS excerpt.
-const EXCERPT_WINDOW = 160;
-// Bare terms from an FTS5 query string: strips operators/quoting so the oversized-doc excerpt
-// scan matches the same words the query matched on, not FTS5 syntax.
+// Default budget behind --snippet-char-limit/--snippet-count-limit: the limit is whatever the
+// caller passes, these only say what happens when they pass nothing (DESIGN.md "Search snippets").
+export const SNIPPET_CHAR_LIMIT_DEFAULT = 80;
+export const SNIPPET_COUNT_LIMIT_DEFAULT = 1;
+// Bare terms from an FTS5 query string: strips operators/quoting, not real terms, so the
+// snippet scan matches what the query matched -- FTS5 operators are uppercase-only, so this is too.
 function extractBareTerms(query) {
-    const cleaned = query.replace(/"/g, ' ').replace(/[()*]/g, ' ').replace(/\b(AND|OR|NOT|NEAR)\b(\/\d+)?/gi, ' ');
+    const cleaned = query.replace(/"/g, ' ').replace(/[()*]/g, ' ').replace(/\b(AND|OR|NOT|NEAR)\b(\/\d+)?/g, ' ');
     return cleaned.split(/\s+/).map((tok)=>tok.replace(/^[A-Za-z_]\w*:/, '')) // column filter, e.g. title:term
-    .map((tok)=>tok.toLowerCase().trim()).filter((tok)=>tok.length > 0);
+    .flatMap((tok)=>searchTokens(tok).map(({ text })=>text)).map((tok)=>tok.toLowerCase().trim()).filter((tok)=>tok.length > 0);
 }
-function findOccurrences(haystackLower, terms) {
+// House convention (src/chunk/group.ts): Intl.Segmenter word boundaries, not a bare \b, which
+// is ASCII-only. Built on first use: construction is a few ms, paid only when a term matches.
+let wordSegmenter;
+function findOccurrences(text, terms) {
     const occ = [];
-    for (const term of terms){
-        let idx = 0;
-        for(;;){
-            const found = haystackLower.indexOf(term, idx);
-            if (found === -1) break;
-            occ.push({
-                start: found,
-                end: found + term.length,
+    const textLower = text.toLowerCase();
+    // Unspaced scripts (UNSPACED_SCRIPTS) mark no word boundaries: the sense-setup skill promises
+    // substring semantics there, so a matching term is found wherever it occurs in the run.
+    const unspacedTerms = terms.filter(hasUnspacedRun);
+    if (unspacedTerms.length > 0) {
+        for (const run of unspacedRuns(text)){
+            const runLower = textLower.slice(run.start, run.end);
+            for (const term of unspacedTerms){
+                let idx = 0;
+                for(;;){
+                    const found = runLower.indexOf(term, idx);
+                    if (found === -1) break;
+                    occ.push({
+                        start: run.start + found,
+                        end: run.start + found + term.length,
+                        term
+                    });
+                    idx = found + term.length;
+                }
+            }
+        }
+    }
+    // Spaced scripts: a word is marked when its porter stem equals a query term's stem, the same
+    // algorithm both indexes tokenize with (sqlite's TOKENIZE = 'porter unicode61'; duckdb's fts default).
+    const spacedTerms = terms.filter((t)=>!hasUnspacedRun(t));
+    if (spacedTerms.length > 0) {
+        const termByStem = new Map(spacedTerms.map((t)=>[
+                stemmer(foldForSearch(t)),
+                t
+            ]));
+        const stemInitials = new Set(Array.from(termByStem.keys(), (term)=>term[0]));
+        for (const match of searchTokens(text)){
+            const segment = match.text;
+            if (match.unspaced) continue;
+            const folded = foldForSearch(segment);
+            // Porter stemming changes suffixes only, so a different initial cannot match a query stem.
+            if (!stemInitials.has(folded[0])) continue;
+            const term = termByStem.get(stemmer(folded));
+            if (term !== undefined) occ.push({
+                start: match.start,
+                end: match.end,
                 term
             });
-            idx = found + term.length;
         }
     }
-    // Longest span first at equal start, so "tests" beats its substring "test" and the
-    // whole word gets highlighted; the emit loop then absorbs the shorter overlap.
     return occ.sort((a, b)=>a.start - b.start || b.end - a.end);
 }
-// Slides a window over the sorted occurrences, same semantics as FTS5's own best-window
-// pick: most distinct terms, ties broken by most total hits.
-function bestWindowStart(occ, windowSize) {
-    let best = occ[0].start;
-    let bestDistinct = 0;
-    let bestCount = 0;
+// Segment boundaries of the whole text, word granularity: the only cut points a snippet edge
+// may land on. One rule for every script (DESIGN.md "Cutting") -- a regex \b is ASCII-only and
+// would mis-cut Japanese, Chinese and Thai, which Intl.Segmenter divides by dictionary instead.
+function wordBoundaries(text) {
+    wordSegmenter !== null && wordSegmenter !== void 0 ? wordSegmenter : wordSegmenter = new Intl.Segmenter('en', {
+        granularity: 'word'
+    });
+    const bounds = [
+        0
+    ];
+    for (const { index, segment } of wordSegmenter.segment(text))bounds.push(index + segment.length);
+    return bounds;
+}
+// bounds is sorted: snaps are binary searches, since each runs once per candidate window.
+function snapForward(bounds, pos) {
+    let lo = 0;
+    let hi = bounds.length - 1;
+    while(lo < hi){
+        const mid = lo + hi >> 1;
+        if (bounds[mid] < pos) lo = mid + 1;
+        else hi = mid;
+    }
+    return bounds[lo];
+}
+function snapBackward(bounds, pos) {
+    let lo = 0;
+    let hi = bounds.length - 1;
+    let result = bounds[0];
+    while(lo < hi){
+        const mid = lo + hi + 1 >> 1;
+        if (bounds[mid] <= pos) {
+            lo = mid;
+            result = bounds[mid];
+        } else hi = mid - 1;
+    }
+    return result;
+}
+function firstBoundAfter(bounds, pos) {
+    let lo = 0;
+    let hi = bounds.length;
+    while(lo < hi){
+        const mid = lo + hi >> 1;
+        if (bounds[mid] <= pos) lo = mid + 1;
+        else hi = mid;
+    }
+    return bounds[lo];
+}
+// A raw, unmarked upper bound: [start, end) inside [anchor, anchor+charLimit), edges on
+// boundaries. Markup (guillemets, ellipses) added on top of this can push the rendered result
+// past charLimit, which is what fitEnd() below corrects for; this is only the starting guess.
+// A single segment spanning the whole target window (a word longer than the char limit) is the
+// one case where holding the boundary rule means the budget is not a hard ceiling.
+function cutWindow(text, bounds, anchor, charLimit) {
+    var _firstBoundAfter;
+    const rawEnd = Math.min(text.length, anchor + charLimit);
+    const start = snapForward(bounds, anchor);
+    let end = snapBackward(bounds, rawEnd);
+    if (end <= start) end = (_firstBoundAfter = firstBoundAfter(bounds, start)) !== null && _firstBoundAfter !== void 0 ? _firstBoundAfter : text.length;
+    return {
+        start,
+        end: Math.min(end, text.length)
+    };
+}
+// The largest boundary <= upperBound, > floor, whose rendered [*, end) fits charLimit. Markup
+// only ever adds characters as end grows, so rendered length is non-decreasing in end and
+// shrinking from upperBound is guaranteed to find the true fit rather than guess at it.
+// `floor` is the one end this never shrinks past (the anchor's own marked word, or the first
+// word in the unmarked fallback): DESIGN.md's budget is a ceiling except here, where returning
+// nothing is worse than a single word that overruns it.
+function fitEnd(render, bounds, floor, upperBound, charLimit) {
+    let lo = 0;
+    let hi = bounds.length - 1;
+    while(lo < hi){
+        const mid = lo + hi + 1 >> 1;
+        if (bounds[mid] <= upperBound) lo = mid;
+        else hi = mid - 1;
+    }
+    for(; lo >= 0 && bounds[lo] > floor; lo--){
+        if (render(bounds[lo]).length <= charLimit) return bounds[lo];
+    }
+    return floor;
+}
+// occ is start-sorted: a window's first candidate occurrence is a binary search, not a walk.
+function firstOccAtOrAfter(occ, pos) {
+    let lo = 0;
+    let hi = occ.length;
+    while(lo < hi){
+        const mid = lo + hi >> 1;
+        if (occ[mid].start < pos) lo = mid + 1;
+        else hi = mid;
+    }
+    return lo;
+}
+function renderWindow(text, occ, win) {
+    let out = '';
+    let cursor = win.start;
+    for(let i = firstOccAtOrAfter(occ, win.start); i < occ.length && occ[i].start < win.end; i++){
+        const o = occ[i];
+        if (o.end > win.end) continue;
+        // Occurrences of duplicate or substring-overlapping terms ("test tests") can overlap;
+        // emitting each would duplicate document text. Keep the first, absorb the rest.
+        if (o.start < cursor) continue;
+        out += `${text.slice(cursor, o.start)}«${text.slice(o.start, o.end)}»`;
+        cursor = o.end;
+    }
+    out += text.slice(cursor, win.end);
+    const prefix = win.start > 0 ? '…' : '';
+    const suffix = win.end < text.length ? '…' : '';
+    return `${prefix}${out.replace(/\s+/g, ' ')}${suffix}`;
+}
+// Scores every occurrence-anchored candidate window: most distinct terms wins, ties broken by
+// most total hits -- coverage now that occurrences are real words, not the false-fragment counts
+// a substring scan produced. Selection itself is unevaluated (DESIGN.md "Selection, unsettled").
+// The window's `end` is fitted to the *rendered* text, markup included, not the raw span: a
+// window dense with marks (every guillemet pair adds two characters) shrinks to fit the same
+// budget a sparse one fills almost exactly.
+function scoreWindows(occ, bounds, text, charLimit) {
+    const candidates = [];
     for(let i = 0; i < occ.length; i++){
-        const winEnd = occ[i].start + windowSize;
+        const winEnd = occ[i].start + charLimit;
         const seen = new Set();
         let count = 0;
         for(let j = i; j < occ.length && occ[j].start < winEnd; j++){
             seen.add(occ[j].term);
             count++;
         }
-        if (seen.size > bestDistinct || seen.size === bestDistinct && count > bestCount) {
-            best = occ[i].start;
-            bestDistinct = seen.size;
-            bestCount = count;
-        }
+        const start = snapForward(bounds, occ[i].start);
+        const floor = Math.max(start, occ[i].end);
+        const upperBound = Math.max(floor, cutWindow(text, bounds, occ[i].start, charLimit).end);
+        const end = fitEnd((e)=>renderWindow(text, occ, {
+                start,
+                end: e
+            }), bounds, floor, upperBound, charLimit);
+        candidates.push({
+            start,
+            end,
+            distinct: seen.size,
+            count
+        });
+    }
+    return candidates;
+}
+function overlaps(a, b) {
+    return a.start < b.end && b.start < a.end;
+}
+// Same scoring function as a single snippet, kept rather than discarded (DESIGN.md "Several
+// snippets per note"): rank by score, take the top non-overlapping windows, then reorder to the
+// note's own order, since several passages from one note read as an abridged note.
+function selectWindows(candidates, countLimit) {
+    const ranked = candidates.slice().sort((a, b)=>b.distinct - a.distinct || b.count - a.count);
+    const chosen = [];
+    for (const c of ranked){
+        if (chosen.length >= countLimit) break;
+        if (chosen.some((s)=>overlaps(s, c))) continue;
+        chosen.push(c);
     }
-    return best;
+    chosen.sort((a, b)=>a.start - b.start);
+    return {
+        chosen,
+        best: ranked[0]
+    };
 }
-// snippet()-shaped excerpt: matched terms wrapped in «», … at cut edges. Linear in doc
-// length, only run for rows actually returned (<= k), unlike snippet()'s per-row cost.
-function computeExcerpt(text, terms) {
-    const occ = findOccurrences(text.toLowerCase(), terms);
+// Builds bounded marked passages and returns the best window's offset for section lookup.
+export function computeSnippets(text, terms, charLimit, countLimit) {
+    const occ = findOccurrences(text, terms);
+    const bounds = wordBoundaries(text);
     if (occ.length === 0) {
-        // Raw substring scan, not porter-stemmed: a doc matched only through a stemmed variant
-        // finds no occurrence here, so fall back to the doc's start, unmarked.
-        const end = Math.min(text.length, EXCERPT_WINDOW);
+        var _bounds_find;
+        // A term matched only via title/summary, not this body text, finds no occurrence here;
+        // fall back to the doc's start, unmarked.
+        const render = (end)=>`${text.slice(0, end).replace(/\s+/g, ' ').trim()}${end < text.length ? '…' : ''}`;
+        const floor = (_bounds_find = bounds.find((b)=>b > 0)) !== null && _bounds_find !== void 0 ? _bounds_find : text.length;
+        const upperBound = Math.max(floor, cutWindow(text, bounds, 0, charLimit).end);
+        const end = fitEnd(render, bounds, floor, upperBound, charLimit);
         return {
-            excerpt: `${text.slice(0, end).replace(/\s+/g, ' ').trim()}${end < text.length ? '…' : ''}`,
+            snippets: [
+                render(end)
+            ],
             offset: 0
         };
     }
-    const start = bestWindowStart(occ, EXCERPT_WINDOW);
-    const end = Math.min(text.length, start + EXCERPT_WINDOW);
-    let out = '';
-    let cursor = start;
-    for (const o of occ){
-        if (o.start < start || o.end > end) continue;
-        // Occurrences of duplicate or substring-overlapping terms ("test tests") can overlap;
-        // emitting each would duplicate document text. Keep the first, absorb the rest.
-        if (o.start < cursor) continue;
-        out += `${text.slice(cursor, o.start)}«${text.slice(o.start, o.end)}»`;
-        cursor = o.end;
-    }
-    out += text.slice(cursor, end);
-    const prefix = start > 0 ? '…' : '';
-    const suffix = end < text.length ? '…' : '';
+    const candidates = scoreWindows(occ, bounds, text, charLimit);
+    const { chosen, best } = selectWindows(candidates, countLimit);
     return {
-        excerpt: `${prefix}${out.replace(/\s+/g, ' ')}${suffix}`,
-        offset: start
+        snippets: chosen.map((win)=>renderWindow(text, occ, win)),
+        offset: best.start
     };
 }
-function lineNumberAt(text, offset) {
+// Converts an offset in the original text to its one-based line number.
+export function lineNumberAt(text, offset) {
     let line = 1;
     for(let i = 0; i < offset; i++)if (text.charCodeAt(i) === 10) line++;
     return line;
@@ -100,6 +270,26 @@ async function lineRangeFor(store, path, line) {
     const row = await stmt.get(path, line, line);
     return row ? `L${row.start_line}-${row.end_line}` : null;
 }
+// Hydrates already-ranked rows with snippets and containing-section ranges without reranking.
+export async function hydrateSearchRows(store, cfg, rows, matchedPaths, terms, opts = {}) {
+    var _opts_snippetCharLimit, _opts_snippetCountLimit;
+    if (matchedPaths.size === 0) return;
+    const bareTerms = extractBareTerms(terms);
+    const charLimit = (_opts_snippetCharLimit = opts.snippetCharLimit) !== null && _opts_snippetCharLimit !== void 0 ? _opts_snippetCharLimit : SNIPPET_CHAR_LIMIT_DEFAULT;
+    const countLimit = (_opts_snippetCountLimit = opts.snippetCountLimit) !== null && _opts_snippetCountLimit !== void 0 ? _opts_snippetCountLimit : SNIPPET_COUNT_LIMIT_DEFAULT;
+    for (const row of rows){
+        if (!matchedPaths.has(row.path)) continue;
+        let text;
+        try {
+            text = readFileSync(join(cfg.baseDir, row.path), 'utf8');
+        } catch  {
+            continue; // vanished since the match; leave snippets/lines empty rather than throw
+        }
+        const { snippets, offset } = computeSnippets(text, bareTerms, charLimit, countLimit);
+        row.snippets = snippets;
+        if (row.lines == null) row.lines = featureEnabled(cfg, 'sections') ? await lineRangeFor(store, row.path, lineNumberAt(text, offset)) : null;
+    }
+}
 // The declared or defaulted signals compose via RRF; `via` names which ones produced each row.
 // `opts` arrives already resolved (config.ts:resolveSearch).
 export async function search(store, cfg, terms, opts = {}) {
@@ -138,22 +328,24 @@ export async function search(store, cfg, terms, opts = {}) {
     const scopeCond = scopeActive ? `AND content.path IN (SELECT "path" FROM _search_scope)` : '';
     const candidates = new Map();
     let matchRows = [];
-    // A query that is only whitespace has no searchable words: zero lexical rows, and the other
-    // signals compose normally.
-    if (signals.words !== undefined && terms.trim() !== '') {
+    const hasEmptyPhrase = [
+        ...terms.matchAll(/"([^"]*)"/g)
+    ].some((match)=>!/[\p{L}\p{N}_]/u.test(match[1]));
+    const hasBareSyntaxOnly = /[()]/u.test(terms.replace(/"[^"]*"/g, ' '));
+    // A query that is only whitespace or punctuation has no lexical rows; other declared signals
+    // compose normally. In particular, unspaced-script punctuation can rewrite to an empty MATCH.
+    if (signals.words !== undefined && terms.trim() !== '' && (/[\p{L}\p{N}_]/u.test(terms) || hasBareSyntaxOnly) && !hasEmptyPhrase) {
+        const syntaxError = bareTermSyntaxError(terms);
+        if (syntaxError) throw syntaxError;
         try {
             matchRows = await wordsCandidates(store, candidates, terms, whereJoin, whereCond, scopeCond, fetch, signals.words);
         } catch (err) {
             throw searchError(err, terms, scope);
         }
     }
-    const hits = new Map(matchRows.map((r)=>[
-            r.path,
-            r.hit
-        ]));
-    // hit === null here means the bound suppressed snippet(), not "no match" -- distinguish
-    // from via='link' rows (never in matchRows, so absent from this set) below.
-    const oversized = new Set(matchRows.filter((r)=>r.hit === null).map((r)=>r.path));
+    // Every store's lexical `snippets` is NULL; the snippet text is always computed below.
+    // Distinguish from via='link' rows, which never appear in matchRows.
+    const matchedPaths = new Set(matchRows.map((r)=>r.path));
     if (signals.links !== undefined) await linksCandidates(store, candidates, matchRows, allPaths, allowedPaths, fetch, signals.links);
     let chunkLines = new Map();
     let chunkSimilarity = new Map();
@@ -163,17 +355,16 @@ export async function search(store, cfg, terms, opts = {}) {
     await store.exec('DROP TABLE IF EXISTS _search');
     // DOUBLE, not REAL: sqlite's REAL is an 8-byte double but duckdb's is a 4-byte float, and the
     // rounded score/similarity are printed at full precision in rows.
-    await store.exec('CREATE TEMP TABLE _search ("path" TEXT PRIMARY KEY, score DOUBLE, via TEXT, hit TEXT, lines TEXT, similarity DOUBLE)');
+    await store.exec('CREATE TEMP TABLE _search ("path" TEXT PRIMARY KEY, score DOUBLE, via TEXT, lines TEXT, similarity DOUBLE)');
     if (candidates.size > 0) {
-        await store.runBatch('INSERT INTO _search ("path", score, via, hit, lines, similarity) VALUES (?, ?, ?, ?, ?, ?)', [
+        await store.runBatch('INSERT INTO _search ("path", score, via, lines, similarity) VALUES (?, ?, ?, ?, ?)', [
             ...candidates
         ].map(([path, c])=>{
-            var _hits_get, _chunkLines_get, _chunkSimilarity_get;
+            var _chunkLines_get, _chunkSimilarity_get;
             return [
                 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
             ];
@@ -182,27 +373,16 @@ export async function search(store, cfg, terms, opts = {}) {
     // Reapplies --where even though _search is already scope+where filtered, since the join to
     // frontmatter is already needed for the path column.
     const where = scope ? `WHERE (${scope})` : '';
-    // lines: semantic rows carry their chunk's range, oversized-doc lexical rows gain one
-    // below, everything else stays null; similarity stays semantic-only.
+    // lines: semantic rows carry their chunk's range, lexical rows gain one below,
+    // everything else stays null; similarity stays semantic-only.
     const similarityCol = semanticEnabled ? ', _search.similarity' : '';
-    const selectStmt = await store.prepare(`SELECT f."path" AS path, content.title, content.summary, _search.hit, _search.via, round(_search.score, 4) AS score, _search.lines${similarityCol}
+    // NULL AS snippets holds this column's position (between summary and via) for every row;
+    // overwritten below, always to an array, never left null (DESIGN.md).
+    const selectStmt = await store.prepare(`SELECT f."path" AS path, content.title, content.summary, NULL AS snippets, _search.via, round(_search.score, 4) AS score, _search.lines${similarityCol}
        FROM _search JOIN frontmatter f ON f."path" = _search."path" JOIN content ON content.path = _search."path"
        ${where} ORDER BY _search.score DESC LIMIT ?`);
     const rows = await selectStmt.all(k);
-    if (oversized.size > 0) {
-        const bareTerms = extractBareTerms(terms);
-        for (const row of rows){
-            if (row.hit !== null || !oversized.has(row.path)) continue;
-            let text;
-            try {
-                text = readFileSync(join(cfg.baseDir, row.path), 'utf8');
-            } catch  {
-                continue; // vanished since the match; leave hit/lines null rather than throw
-            }
-            const { excerpt, offset } = computeExcerpt(text, bareTerms);
-            row.hit = excerpt;
-            if (row.lines == null) row.lines = featureEnabled(cfg, 'sections') ? await lineRangeFor(store, row.path, lineNumberAt(text, offset)) : null;
-        }
-    }
+    for (const row of rows)row.snippets = [];
+    await hydrateSearchRows(store, cfg, rows, matchedPaths, terms, opts);
     return rows;
 }