sensemaking 0.7.0 → 0.7.2

package/dist/esm/verbs.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/verbs.ts"],"sourcesContent":["import posix from 'node:path/posix';\nimport type { DatabaseSync } from 'node:sqlite';\nimport type { Config, FeatureName } from './config.ts';\nimport { featureEnabled, featureStates } from './config.ts';\nimport { SenseError } from './errors.ts';\nimport { semanticCandidates } from './features/embed.ts';\nimport { linkEdges } from './features/index.ts';\nimport { personalizedRank } from './graph.ts';\nimport type { Row } from './output.ts';\n\n// The three layer verbs: mapTree (orient), find (locate), peek (structure).\n// Each returns data; cli.ts renders. All of them degrade when a feature is off.\n\nconst WEIGHTED_BM25 = 'bm25(content, 10.0, 5.0, 1.0)';\nconst RRF_K = 60;\n\n// FTS5 reads these as operators, so a bare term containing one is a syntax error or --\n// worse -- a column filter: `end-to-end` parses as a filter on column `to`, and SQLite\n// reports `no such column: to`, which is a true statement about the parse and a false\n// one about the input. Both field reports on 0.6.0 misdiagnosed that message.\nconst FTS5_OPERATORS = /[-'\"/.:^*()]/;\n\nfunction searchError(err: Error, terms: string, scope?: string): Error {\n  const message = err.message;\n  if (!/no such column|fts5: syntax error|malformed MATCH/.test(message)) return err;\n  const suspects = (terms.match(/\\S+/g) ?? []).filter((t) => !t.startsWith('\"') && FTS5_OPERATORS.test(t));\n  // Blame the terms only when the failing token actually came from one -- a typo'd column\n  // in --where (or the tree's default scope) raises \"no such column\" through this same\n  // statement, and naming a term for it would state a false fact about the input.\n  const col = /no such column: (\\S+)/.exec(message)?.[1];\n  const fromTerms = col === undefined ? suspects.length > 0 : suspects.some((t) => t.split(/[^\\p{L}\\p{N}]+/u).includes(col));\n  if (fromTerms && suspects.length > 0) {\n    return new SenseError('SEARCH_SYNTAX', `${message} -- the punctuation in ${suspects.map((t) => `\\`${t}\\``).join(', ')} is FTS5 syntax, not literal text; search for it literally by double-quoting: '\"${suspects[0]}\"'. Searchable columns are title, summary, text.`);\n  }\n  if (col !== undefined && scope !== undefined) {\n    return new SenseError('SEARCH_SYNTAX', `${message} -- the where condition (${scope}) references it; frontmatter columns are listed by sense query \"SELECT name FROM pragma_table_info('frontmatter')\".`);\n  }\n  return new SenseError('SEARCH_SYNTAX', `${message} -- searchable columns are title, summary, text; frontmatter fields are queried with --where or sense query (list them with pragma_table_info('frontmatter')).`);\n}\n\nexport interface FindOptions {\n  k?: number;\n  where?: string; // SQL fragment against frontmatter alias `f`, e.g. \"f.status = 'active'\"\n  semantic?: boolean; // invoke vector expansion (requires features.embed); rows gain via 'vector' and a lines column\n}\n\n// Layer 1: BM25 + link-graph expansion, fused by reciprocal rank. `via` says which\n// signal produced each row so the agent knows what evidence it is trusting.\n// Semantic expansion is per-query opt-in: without opts.semantic the result is\n// byte-for-byte independent of the embed feature.\nexport async function find(db: DatabaseSync, cfg: Config, terms: string, opts: FindOptions = {}): Promise<Row[]> {\n  const k = opts.k ?? 10;\n  const fetch = Math.max(k * 3, 30);\n\n  // Terms pass verbatim to FTS5 MATCH: bare words AND-join, operators are the caller's.\n  // Invalid syntax propagates as an error, zero matches return zero -- no silent rewrites.\n  // --where applies inside the candidate query (a post-filter over the top-N would drop\n  // matches ranked past the pool) and again on the final select for link-derived rows.\n  // An explicit --where replaces the tree's declared default rather than ANDing with it,\n  // so a caller can always widen back to the whole tree.\n  const scope = opts.where ?? cfg.defaults?.find?.where;\n  const whereJoin = scope ? `JOIN frontmatter f ON f.\"path\" = content.path` : '';\n  const whereCond = scope ? `AND (${scope})` : '';\n  const matchSql = `SELECT content.path AS path, snippet(content, -1, '«', '»', '…', 10) AS hit FROM content ${whereJoin} WHERE content MATCH ? ${whereCond} ORDER BY ${WEIGHTED_BM25} LIMIT ${fetch}`;\n  let matchRows: Array<{ path: string; hit: string }>;\n  try {\n    matchRows = db.prepare(matchSql).all(terms) as Array<{ path: string; hit: string }>;\n  } catch (err) {\n    throw searchError(err as Error, terms, scope);\n  }\n\n  const hits = new Map(matchRows.map((r) => [r.path, r.hit]));\n  const candidates = new Map<string, { score: number; via: string }>();\n  matchRows.forEach((r, i) => {\n    candidates.set(r.path, { score: 1 / (RRF_K + i), via: 'match' });\n  });\n\n  const edges = featureEnabled(cfg, 'links') && matchRows.length > 0 ? linkEdges(db) : [];\n  if (edges.length > 0) {\n    // `linked` gates the label only, not the score: PPR restart mass gives every seed a\n    // nonzero rank even without an incident edge, which is not link evidence — but dropping\n    // that mass from the score list reweights fusion toward connectivity and measurably\n    // wrecks ranking on link-dense corpora (FEVER hit@10 0.997 -> 0.907; fusion-tuning.md).\n    const linked = new Set(edges.flat());\n    const nodes = (db.prepare('SELECT \"path\" FROM frontmatter').all() as Array<{ path: string }>).map((r) => r.path);\n    const seeds = new Map(matchRows.map((r, i) => [r.path, 1 / (i + 1)]));\n    const ranked = [...personalizedRank(nodes, edges, seeds)]\n      .filter(([, score]) => score > 1e-9)\n      .sort((a, b) => b[1] - a[1])\n      .slice(0, fetch);\n    ranked.forEach(([path], i) => {\n      const existing = candidates.get(path);\n      if (existing) {\n        existing.score += 1 / (RRF_K + i);\n        if (linked.has(path)) existing.via = 'match+link';\n      } else {\n        candidates.set(path, { score: 1 / (RRF_K + i), via: 'link' });\n      }\n    });\n  }\n\n  // Vector expansion, invoked only: a third RRF list at the swept flat-region constants\n  // (weight 1, pool = fetch). Each row carries its best chunk's line range.\n  const chunkLines = new Map<string, string>();\n  const chunkSimilarity = new Map<string, number>();\n  if (opts.semantic) {\n    const vec = await semanticCandidates(db, cfg, terms, fetch);\n    vec.forEach(({ path, lines, similarity }, i) => {\n      chunkLines.set(path, lines);\n      chunkSimilarity.set(path, similarity);\n      const existing = candidates.get(path);\n      if (existing) {\n        existing.score += 1 / (RRF_K + i);\n        existing.via = `${existing.via}+vector`;\n      } else {\n        candidates.set(path, { score: 1 / (RRF_K + i), via: 'vector' });\n      }\n    });\n  }\n\n  db.exec('DROP TABLE IF EXISTS _find');\n  db.exec('CREATE TEMP TABLE _find (\"path\" TEXT PRIMARY KEY, score REAL, via TEXT, hit TEXT, lines TEXT, similarity REAL)');\n  const insert = db.prepare('INSERT INTO _find (\"path\", score, via, hit, lines, similarity) VALUES (?, ?, ?, ?, ?, ?)');\n  for (const [path, c] of candidates) insert.run(path, c.score, c.via, hits.get(path) ?? null, chunkLines.get(path) ?? null, chunkSimilarity.get(path) ?? null);\n\n  const where = scope ? `WHERE ${scope}` : '';\n  const linesCol = opts.semantic ? ', _find.lines, _find.similarity' : '';\n  return db\n    .prepare(\n      `SELECT f.\"path\" AS path, content.title, content.summary, _find.hit, _find.via, round(_find.score, 4) AS score${linesCol}\n       FROM _find JOIN frontmatter f ON f.\"path\" = _find.\"path\" JOIN content ON content.path = _find.\"path\"\n       ${where} ORDER BY _find.score DESC LIMIT ?`\n    )\n    .all(k) as Row[];\n}\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  hubs: Row[];\n  recent: Row[];\n}\n\nconst INTERNAL_COLUMNS = new Set(['path', '_mtime', '_size', '_rank']);\n\n// Layer 0: what is this tree. Fixed-size output regardless of tree size.\nexport function mapTree(db: DatabaseSync, cfg: Config): TreeMap {\n  const docs = db.prepare('SELECT COUNT(*) AS count, COALESCE(SUM(\"_size\"), 0) AS bytes FROM frontmatter').get() as { count: number; bytes: number };\n\n  const columns = (db.prepare('PRAGMA table_info(frontmatter)').all() as Array<{ name: string }>).map((r) => r.name).filter((name) => !INTERNAL_COLUMNS.has(name));\n  const allFields = columns\n    .map((name) => {\n      const quoted = `\"${name.split('\"').join('\"\"')}\"`;\n      // Observed storage class, not a declared one: these columns are added dynamically and\n      // SQLite types per value, so a field can be text in most notes and numeric in a few.\n      // Listing every distinct type makes both the type and any drift visible.\n      const { n, types } = db.prepare(`SELECT COUNT(${quoted}) AS n, GROUP_CONCAT(DISTINCT typeof(${quoted})) AS types FROM frontmatter WHERE ${quoted} IS NOT NULL`).get() as { n: number; types: string | null };\n      return { field: name, coverage: n, type: types ?? '' };\n    })\n    .sort((a, b) => (b.coverage as number) - (a.coverage as number)) as Row[];\n  const fields = allFields.slice(0, 20);\n\n  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 ORDER BY f.\"_rank\" DESC LIMIT 8`).all() as Row[]) : [];\n\n  const recent = db.prepare(`SELECT \"path\", datetime(\"_mtime\" / 1000, 'unixepoch') AS modified FROM frontmatter ORDER BY \"_mtime\" DESC LIMIT 5`).all() as Row[];\n\n  return { docs, fields, fieldsTotal: allFields.length, features: featureStates(cfg), hubs, recent };\n}\n\nexport interface Peek {\n  path: string;\n  tokens: number;\n  frontmatter: Row;\n  sections: Row[];\n  outbound: string[];\n  backlinks: string[];\n  unresolved: string[];\n  // Totals before truncation: a hub can have thousands of backlinks, and peek's whole\n  // point is bounded output. Query the links table directly for the full list.\n  outboundTotal: number;\n  backlinksTotal: number;\n  unresolvedTotal: number;\n  off: FeatureName[]; // disabled features whose blocks are omitted (not empty)\n}\n\nconst PEEK_LINK_LIMIT = 20;\n\n// Layer 2: everything about one note except its prose -- frontmatter, outline with line\n// ranges + token estimates (so the follow-up Read is a range, not the file), links both ways.\nexport function peek(db: DatabaseSync, cfg: Config, pathArg: string): Peek {\n  const paths = (db.prepare('SELECT \"path\" FROM frontmatter').all() as Array<{ path: string }>).map((r) => r.path);\n  let path = paths.find((p) => p === pathArg);\n  if (!path) {\n    const base = posix.basename(pathArg).replace(/\\.md$/i, '').toLowerCase();\n    const matches = paths.filter((p) => posix.basename(p).replace(/\\.md$/i, '').toLowerCase() === base);\n    if (matches.length === 1) path = matches[0];\n    else if (matches.length > 1) throw new SenseError('NOTE_AMBIGUOUS', `\"${pathArg}\" is ambiguous: ${matches.join(', ')}`);\n    else throw new SenseError('NOTE_NOT_FOUND', `no note matches \"${pathArg}\"`);\n  }\n\n  const row = db.prepare('SELECT * FROM frontmatter WHERE \"path\" = ?').get(path) as Row;\n  const frontmatter: Row = {};\n  for (const [key, value] of Object.entries(row)) {\n    if (!INTERNAL_COLUMNS.has(key) && value !== null) frontmatter[key] = value;\n  }\n\n  const sections = featureEnabled(cfg, 'sections') ? (db.prepare('SELECT level, heading, start_line, end_line, tokens FROM sections WHERE \"path\" = ? ORDER BY idx').all(path) as Row[]) : [];\n\n  let outbound: string[] = [];\n  let backlinks: string[] = [];\n  let unresolved: string[] = [];\n  let backlinksTotal = 0;\n  if (featureEnabled(cfg, 'links')) {\n    const out = db.prepare('SELECT target, dst FROM links WHERE src = ? ORDER BY target').all(path) as Array<{ target: string; dst: string | null }>;\n    outbound = [...new Set(out.filter((l) => l.dst !== null).map((l) => l.dst as string))];\n    unresolved = out.filter((l) => l.dst === null).map((l) => l.target);\n    backlinksTotal = (db.prepare('SELECT COUNT(DISTINCT src) AS n FROM links WHERE dst = ?').get(path) as { n: number }).n;\n    backlinks = (db.prepare('SELECT DISTINCT src FROM links WHERE dst = ? ORDER BY src LIMIT ?').all(path, PEEK_LINK_LIMIT) as Array<{ src: string }>).map((r) => r.src);\n  }\n\n  return {\n    path,\n    tokens: Math.ceil(((row._size as number) ?? 0) / 4),\n    frontmatter,\n    sections,\n    outbound: outbound.slice(0, PEEK_LINK_LIMIT),\n    backlinks,\n    unresolved: unresolved.slice(0, PEEK_LINK_LIMIT),\n    outboundTotal: outbound.length,\n    backlinksTotal,\n    unresolvedTotal: unresolved.length,\n    off: (['sections', 'links'] as FeatureName[]).filter((name) => !featureEnabled(cfg, name)),\n  };\n}\n"],"names":["posix","featureEnabled","featureStates","SenseError","semanticCandidates","linkEdges","personalizedRank","WEIGHTED_BM25","RRF_K","FTS5_OPERATORS","searchError","err","terms","scope","message","test","suspects","match","filter","t","startsWith","col","exec","fromTerms","undefined","length","some","split","includes","map","join","find","db","cfg","opts","hits","chunkLines","chunkSimilarity","k","fetch","Math","max","where","defaults","whereJoin","whereCond","matchSql","matchRows","prepare","all","Map","r","path","hit","candidates","forEach","i","set","score","via","edges","linked","Set","flat","nodes","seeds","ranked","sort","a","b","slice","existing","get","has","semantic","vec","lines","similarity","insert","c","run","linesCol","INTERNAL_COLUMNS","mapTree","docs","columns","name","allFields","quoted","n","types","field","coverage","type","fields","hubs","recent","fieldsTotal","features","PEEK_LINK_LIMIT","peek","pathArg","row","paths","p","base","basename","replace","toLowerCase","matches","frontmatter","key","value","Object","entries","sections","outbound","backlinks","unresolved","backlinksTotal","out","l","dst","target","src","tokens","ceil","_size","outboundTotal","unresolvedTotal","off"],"mappings":"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"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/verbs.ts"],"sourcesContent":["import posix from 'node:path/posix';\nimport type { DatabaseSync } from 'node:sqlite';\nimport type { Config, FeatureName } from './config.ts';\nimport { featureEnabled, featureStates } from './config.ts';\nimport { SenseError } from './errors.ts';\nimport { semanticCandidates } from './features/embed.ts';\nimport { linkEdges } from './features/index.ts';\nimport { personalizedRank } from './graph.ts';\nimport type { Row } from './output.ts';\nimport { searchError } from './search-error.ts';\n\n// The three layer verbs: mapTree (orient), find (locate), peek (structure).\n// Each returns data; cli.ts renders. All of them degrade when a feature is off.\n\nconst WEIGHTED_BM25 = 'bm25(content, 10.0, 5.0, 1.0)';\nconst RRF_K = 60;\n\nexport interface FindOptions {\n  k?: number;\n  where?: string; // SQL fragment against frontmatter alias `f`, e.g. \"f.status = 'active'\"\n  semantic?: boolean; // invoke vector expansion (requires features.embed); rows gain via 'vector' and a lines column\n}\n\n// Layer 1: BM25 + link-graph expansion, fused by reciprocal rank. `via` says which\n// signal produced each row so the agent knows what evidence it is trusting.\n// Semantic expansion is per-query opt-in: without opts.semantic the result is\n// byte-for-byte independent of the embed feature.\nexport async function find(db: DatabaseSync, cfg: Config, terms: string, opts: FindOptions = {}): Promise<Row[]> {\n  const k = opts.k ?? 10;\n  const fetch = Math.max(k * 3, 30);\n\n  // Terms pass verbatim to FTS5 MATCH: bare words AND-join, operators are the caller's.\n  // Invalid syntax propagates as an error, zero matches return zero -- no silent rewrites.\n  // --where applies inside the candidate query (a post-filter over the top-N would drop\n  // matches ranked past the pool) and again on the final select for link-derived rows.\n  // An explicit --where replaces the tree's declared default rather than ANDing with it,\n  // so a caller can always widen back to the whole tree.\n  const scope = opts.where ?? cfg.defaults?.find?.where;\n  const whereJoin = scope ? `JOIN frontmatter f ON f.\"path\" = content.path` : '';\n  const whereCond = scope ? `AND (${scope})` : '';\n  const matchSql = `SELECT content.path AS path, snippet(content, -1, '«', '»', '…', 10) AS hit FROM content ${whereJoin} WHERE content MATCH ? ${whereCond} ORDER BY ${WEIGHTED_BM25} LIMIT ${fetch}`;\n  let matchRows: Array<{ path: string; hit: string }>;\n  try {\n    matchRows = db.prepare(matchSql).all(terms) as Array<{ path: string; hit: string }>;\n  } catch (err) {\n    throw searchError(err as Error, terms, scope);\n  }\n\n  const hits = new Map(matchRows.map((r) => [r.path, r.hit]));\n  const candidates = new Map<string, { score: number; via: string }>();\n  matchRows.forEach((r, i) => {\n    candidates.set(r.path, { score: 1 / (RRF_K + i), via: 'match' });\n  });\n\n  const edges = featureEnabled(cfg, 'links') && matchRows.length > 0 ? linkEdges(db) : [];\n  if (edges.length > 0) {\n    // `linked` gates the label only, not the score: PPR restart mass gives every seed a\n    // nonzero rank even without an incident edge, which is not link evidence — but dropping\n    // that mass from the score list reweights fusion toward connectivity and measurably\n    // wrecks ranking on link-dense corpora (FEVER hit@10 0.997 -> 0.907; fusion-tuning.md).\n    const linked = new Set(edges.flat());\n    const nodes = (db.prepare('SELECT \"path\" FROM frontmatter').all() as Array<{ path: string }>).map((r) => r.path);\n    const seeds = new Map(matchRows.map((r, i) => [r.path, 1 / (i + 1)]));\n    const ranked = [...personalizedRank(nodes, edges, seeds)]\n      .filter(([, score]) => score > 1e-9)\n      .sort((a, b) => b[1] - a[1])\n      .slice(0, fetch);\n    ranked.forEach(([path], i) => {\n      const existing = candidates.get(path);\n      if (existing) {\n        existing.score += 1 / (RRF_K + i);\n        if (linked.has(path)) existing.via = 'match+link';\n      } else {\n        candidates.set(path, { score: 1 / (RRF_K + i), via: 'link' });\n      }\n    });\n  }\n\n  // Vector expansion, invoked only: a third RRF list at the swept flat-region constants\n  // (weight 1, pool = fetch). Each row carries its best chunk's line range.\n  const chunkLines = new Map<string, string>();\n  const chunkSimilarity = new Map<string, number>();\n  if (opts.semantic) {\n    const vec = await semanticCandidates(db, cfg, terms, fetch);\n    vec.forEach(({ path, lines, similarity }, i) => {\n      chunkLines.set(path, lines);\n      chunkSimilarity.set(path, similarity);\n      const existing = candidates.get(path);\n      if (existing) {\n        existing.score += 1 / (RRF_K + i);\n        existing.via = `${existing.via}+vector`;\n      } else {\n        candidates.set(path, { score: 1 / (RRF_K + i), via: 'vector' });\n      }\n    });\n  }\n\n  db.exec('DROP TABLE IF EXISTS _find');\n  db.exec('CREATE TEMP TABLE _find (\"path\" TEXT PRIMARY KEY, score REAL, via TEXT, hit TEXT, lines TEXT, similarity REAL)');\n  const insert = db.prepare('INSERT INTO _find (\"path\", score, via, hit, lines, similarity) VALUES (?, ?, ?, ?, ?, ?)');\n  for (const [path, c] of candidates) insert.run(path, c.score, c.via, hits.get(path) ?? null, chunkLines.get(path) ?? null, chunkSimilarity.get(path) ?? null);\n\n  const where = scope ? `WHERE ${scope}` : '';\n  const linesCol = opts.semantic ? ', _find.lines, _find.similarity' : '';\n  return db\n    .prepare(\n      `SELECT f.\"path\" AS path, content.title, content.summary, _find.hit, _find.via, round(_find.score, 4) AS score${linesCol}\n       FROM _find JOIN frontmatter f ON f.\"path\" = _find.\"path\" JOIN content ON content.path = _find.\"path\"\n       ${where} ORDER BY _find.score DESC LIMIT ?`\n    )\n    .all(k) as Row[];\n}\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  hubs: Row[];\n  recent: Row[];\n}\n\nconst INTERNAL_COLUMNS = new Set(['path', '_mtime', '_size', '_rank']);\n\n// Layer 0: what is this tree. Fixed-size output regardless of tree size.\nexport function mapTree(db: DatabaseSync, cfg: Config): TreeMap {\n  const docs = db.prepare('SELECT COUNT(*) AS count, COALESCE(SUM(\"_size\"), 0) AS bytes FROM frontmatter').get() as { count: number; bytes: number };\n\n  const columns = (db.prepare('PRAGMA table_info(frontmatter)').all() as Array<{ name: string }>).map((r) => r.name).filter((name) => !INTERNAL_COLUMNS.has(name));\n  const allFields = columns\n    .map((name) => {\n      const quoted = `\"${name.split('\"').join('\"\"')}\"`;\n      // Observed storage class, not a declared one: these columns are added dynamically and\n      // SQLite types per value, so a field can be text in most notes and numeric in a few.\n      // Listing every distinct type makes both the type and any drift visible.\n      const { n, types } = db.prepare(`SELECT COUNT(${quoted}) AS n, GROUP_CONCAT(DISTINCT typeof(${quoted})) AS types FROM frontmatter WHERE ${quoted} IS NOT NULL`).get() as { n: number; types: string | null };\n      return { field: name, coverage: n, type: types ?? '' };\n    })\n    .sort((a, b) => (b.coverage as number) - (a.coverage as number)) as Row[];\n  const fields = allFields.slice(0, 20);\n\n  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 ORDER BY f.\"_rank\" DESC LIMIT 8`).all() as Row[]) : [];\n\n  const recent = db.prepare(`SELECT \"path\", datetime(\"_mtime\" / 1000, 'unixepoch') AS modified FROM frontmatter ORDER BY \"_mtime\" DESC LIMIT 5`).all() as Row[];\n\n  return { docs, fields, fieldsTotal: allFields.length, features: featureStates(cfg), hubs, recent };\n}\n\nexport interface Peek {\n  path: string;\n  tokens: number;\n  frontmatter: Row;\n  sections: Row[];\n  outbound: string[];\n  backlinks: string[];\n  unresolved: string[];\n  // Totals before truncation: a hub can have thousands of backlinks, and peek's whole\n  // point is bounded output. Query the links table directly for the full list.\n  outboundTotal: number;\n  backlinksTotal: number;\n  unresolvedTotal: number;\n  off: FeatureName[]; // disabled features whose blocks are omitted (not empty)\n}\n\nconst PEEK_LINK_LIMIT = 20;\n\n// Layer 2: everything about one note except its prose -- frontmatter, outline with line\n// ranges + token estimates (so the follow-up Read is a range, not the file), links both ways.\nexport function peek(db: DatabaseSync, cfg: Config, pathArg: string): Peek {\n  const paths = (db.prepare('SELECT \"path\" FROM frontmatter').all() as Array<{ path: string }>).map((r) => r.path);\n  let path = paths.find((p) => p === pathArg);\n  if (!path) {\n    const base = posix.basename(pathArg).replace(/\\.md$/i, '').toLowerCase();\n    const matches = paths.filter((p) => posix.basename(p).replace(/\\.md$/i, '').toLowerCase() === base);\n    if (matches.length === 1) path = matches[0];\n    else if (matches.length > 1) throw new SenseError('NOTE_AMBIGUOUS', `\"${pathArg}\" is ambiguous: ${matches.join(', ')}`);\n    else throw new SenseError('NOTE_NOT_FOUND', `no note matches \"${pathArg}\"`);\n  }\n\n  const row = db.prepare('SELECT * FROM frontmatter WHERE \"path\" = ?').get(path) as Row;\n  const frontmatter: Row = {};\n  for (const [key, value] of Object.entries(row)) {\n    if (!INTERNAL_COLUMNS.has(key) && value !== null) frontmatter[key] = value;\n  }\n\n  const sections = featureEnabled(cfg, 'sections') ? (db.prepare('SELECT level, heading, start_line, end_line, tokens FROM sections WHERE \"path\" = ? ORDER BY idx').all(path) as Row[]) : [];\n\n  let outbound: string[] = [];\n  let backlinks: string[] = [];\n  let unresolved: string[] = [];\n  let backlinksTotal = 0;\n  if (featureEnabled(cfg, 'links')) {\n    const out = db.prepare('SELECT target, dst FROM links WHERE src = ? ORDER BY target').all(path) as Array<{ target: string; dst: string | null }>;\n    outbound = [...new Set(out.filter((l) => l.dst !== null).map((l) => l.dst as string))];\n    unresolved = out.filter((l) => l.dst === null).map((l) => l.target);\n    backlinksTotal = (db.prepare('SELECT COUNT(DISTINCT src) AS n FROM links WHERE dst = ?').get(path) as { n: number }).n;\n    backlinks = (db.prepare('SELECT DISTINCT src FROM links WHERE dst = ? ORDER BY src LIMIT ?').all(path, PEEK_LINK_LIMIT) as Array<{ src: string }>).map((r) => r.src);\n  }\n\n  return {\n    path,\n    tokens: Math.ceil(((row._size as number) ?? 0) / 4),\n    frontmatter,\n    sections,\n    outbound: outbound.slice(0, PEEK_LINK_LIMIT),\n    backlinks,\n    unresolved: unresolved.slice(0, PEEK_LINK_LIMIT),\n    outboundTotal: outbound.length,\n    backlinksTotal,\n    unresolvedTotal: unresolved.length,\n    off: (['sections', 'links'] as FeatureName[]).filter((name) => !featureEnabled(cfg, name)),\n  };\n}\n"],"names":["posix","featureEnabled","featureStates","SenseError","semanticCandidates","linkEdges","personalizedRank","searchError","WEIGHTED_BM25","RRF_K","find","db","cfg","terms","opts","hits","chunkLines","chunkSimilarity","k","fetch","Math","max","scope","where","defaults","whereJoin","whereCond","matchSql","matchRows","prepare","all","err","Map","map","r","path","hit","candidates","forEach","i","set","score","via","edges","length","linked","Set","flat","nodes","seeds","ranked","filter","sort","a","b","slice","existing","get","has","semantic","vec","lines","similarity","exec","insert","c","run","linesCol","INTERNAL_COLUMNS","mapTree","docs","columns","name","allFields","quoted","split","join","n","types","field","coverage","type","fields","hubs","recent","fieldsTotal","features","PEEK_LINK_LIMIT","peek","pathArg","row","paths","p","base","basename","replace","toLowerCase","matches","frontmatter","key","value","Object","entries","sections","outbound","backlinks","unresolved","backlinksTotal","out","l","dst","target","src","tokens","ceil","_size","outboundTotal","unresolvedTotal","off"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sensemaking",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Query a knowledge base you build with an agent: filter notes by frontmatter, then search inside them",
   "keywords": [
     "markdown",

package/schema.json

@@ -82,6 +82,11 @@
         }
       }
     },
+    "checks": {
+      "type": "object",
+      "description": "Assertions over saved queries, for trees whose queries encode invariants: `\"checks\": { \"dead-links\": \"empty\" }` makes `sense check` fail (exit 1) when that query returns rows. Without an entry, `check` reports zero-row queries as `ok, but returns 0 rows` -- informational, since an ordinary query returning nothing is sometimes a bug and sometimes just an empty result. Keys must name saved queries.",
+      "additionalProperties": { "type": "string", "enum": ["empty"] }
+    },
     "queries": {
       "type": "object",
       "description": "Named SQL queries runnable as `sense <name> [params...]`. Tables: `frontmatter` (one row per file, one column per discovered frontmatter key, plus `path`/`_mtime`/`_size`/`_rank`), `content` (FTS5: `title`, `summary`, `text`, `path`), `links` (`src`, `target`, `dst`), and `sections` (`path`, `idx`, `level`, `heading`, `start_line`, `end_line`, `tokens`). `?` placeholders bind to CLI positional args in order. `has(field, value)`: array membership on a JSON-array field, substring match on a string (so has(f.status, 'active') also matches 'inactive'), false on NULL. Exact matches: `=` for scalars, `EXISTS (SELECT 1 FROM json_each(f.tags) WHERE value = ?)` for array members. Canonical query: `SELECT f.path, content.title, content.summary, snippet(content, -1, '«', '»', '…', 10) AS hit FROM frontmatter f JOIN content ON content.path = f.path WHERE content MATCH ? ORDER BY bm25(content, 10.0, 5.0, 1.0) LIMIT 10`. Reserved frontmatter keys: `path`, `_mtime`, `_size`, `_rank`, `content`, `links`, `sections`. Reserved query names (unreachable as subcommands): `init`, `query`, `find`, `map`, `peek`, `watch`, `status`, `rebuild`, `check`.",

package/skills/sense/SKILL.md

@@ -71,16 +71,23 @@ sense --list | status | rebuild | check
 - `score` is a rank-fusion value: it ranks rows within one result set and is not comparable
   across queries, not a relevance magnitude — a perfect lexical hit and a weak vector-only
   hit can both read ~0.017, because the number encodes how many signals fired and at what
-  rank. With `--semantic`, rows carry `similarity` (cosine, -1 to 1) which does measure
-  match quality: on a query whose words are absent from the tree, similarities sit near zero
-  (and can be negative), while a genuine paraphrase match runs high.
+  rank. With `--semantic`, rows carry `similarity`: the cosine (-1 to 1) of the query
+  against that file's best-matching chunk — the same chunk the `lines` range points at.
+  It orders vector evidence within a result set; its absolute range depends on the corpus.
+  Measured: on thousands of notes, unrelated queries ~0.2 and genuine matches ~0.6; on a
+  few dozen notes the ranges compress and can overlap, because even a nonsense query has a
+  moderately near neighbour somewhere. Compare similarities within a result set rather than
+  against a fixed cutoff carried between trees.
 - Lexical `find` returns 0 rows when nothing matches, so it answers "is this in the tree at
   all". `--semantic` always returns up to `k` rows — nearest-neighbour search has a nearest
-  neighbour for any input — so absence is a lexical question; with `--semantic` the
-  `similarity` column is what separates a real hit from the best of a bad lot.
+  neighbour for any input — so absence is a lexical question; `similarity` and the snippet
+  are the evidence for judging whether a vector row is a real hit.
 - `sense check` prepares every saved query (catching syntax and unknown-column errors), runs
   the ones taking no parameters, and prints row counts: a saved query returning 0 rows looks
-  the same as a true empty result until something distinguishes them.
+  the same as a true empty result until something distinguishes them. For queries that
+  encode invariants (a dead-link list, an unsupported-claims list — rows are violations),
+  `checks: { "<name>": "empty" }` in the config inverts the meaning: `check` fails when the
+  query returns rows, making it usable as a test suite rather than a linter.
 
 ## SQL