sensemaking 0.25.1 → 0.27.0

package/dist/esm/watch.js

@@ -7,10 +7,19 @@ import { startWatchClaim, WATCH_HEARTBEAT_INTERVAL_MS } from './watch-claim.js';
 // Watch prepares the index for snapshot queries; filesystem events request debounced builds
 // and periodic reconciliation recovers missed notifications.
 const DEBOUNCE_MS = 200;
-// Runs in the foreground until SIGINT/SIGTERM/signal abort. DuckDB and Turso hand the cache file to
-// one process at a time, so every reconcile cycle opens and closes instead of holding an idle lock.
-export async function runWatch(cfg, opts = {}) {
+function isCallerAbort(signal, reason) {
+    return (signal === null || signal === void 0 ? void 0 : signal.aborted) === true && Object.is(reason, signal.reason);
+}
+function errorMessage(reason) {
+    return reason instanceof Error ? reason.message : String(reason);
+}
+/**
+ * Runs in the foreground. Caller abort waits for active native work and cleanup; SIGINT/SIGTERM
+ * also run one final freshness pass. Cleanup failures reject either shutdown path.
+ */ export async function runWatch(cfg, opts = {}) {
     var _opts_onEvent, _opts_debounceMs, _opts_heartbeatIntervalMs, _cfg_rootDir, _cfg_configDir, _opts_force;
+    var _opts_signal;
+    if ((_opts_signal = opts.signal) === null || _opts_signal === void 0 ? void 0 : _opts_signal.aborted) return;
     const onEvent = (_opts_onEvent = opts.onEvent) !== null && _opts_onEvent !== void 0 ? _opts_onEvent : ()=>{};
     const debounceMs = (_opts_debounceMs = opts.debounceMs) !== null && _opts_debounceMs !== void 0 ? _opts_debounceMs : DEBOUNCE_MS;
     const reconcileIntervalMs = (_opts_heartbeatIntervalMs = opts.heartbeatIntervalMs) !== null && _opts_heartbeatIntervalMs !== void 0 ? _opts_heartbeatIntervalMs : WATCH_HEARTBEAT_INTERVAL_MS;
@@ -35,8 +44,10 @@ export async function runWatch(cfg, opts = {}) {
     let startupNotification = false;
     let scheduleReconcile;
     let stopping = false;
+    let callerCanceled = false;
     try {
-        var _opts_signal;
+        var _opts_signal1, _opts_signal2, _opts_signal3;
+        (_opts_signal1 = opts.signal) === null || _opts_signal1 === void 0 ? void 0 : _opts_signal1.throwIfAborted();
         // Subscribe before the first build. Native watchers have no ready barrier, so startup also
         // performs an unconditional catch-up pass after the initial build.
         watcher = fsWatch(rootDir, {
@@ -51,7 +62,9 @@ export async function runWatch(cfg, opts = {}) {
             requestShutdown === null || requestShutdown === void 0 ? void 0 : requestShutdown(err);
         });
         const startupEvents = [];
-        const { store: initialStore, dbPath, warnings: initialWarnings, parsed: initialParsed } = await openStore(cfg);
+        const { store: initialStore, dbPath, warnings: initialWarnings, parsed: initialParsed } = await openStore(cfg, {
+            signal: opts.signal
+        });
         let initialTotal = 0;
         try {
             // total is read before close: an event fires only once nothing is held open again.
@@ -59,6 +72,7 @@ export async function runWatch(cfg, opts = {}) {
         } finally{
             await initialStore.close();
         }
+        (_opts_signal2 = opts.signal) === null || _opts_signal2 === void 0 ? void 0 : _opts_signal2.throwIfAborted();
         if (claimFailure) throw claimFailure;
         startupEvents.push({
             parsed: initialParsed,
@@ -68,8 +82,12 @@ export async function runWatch(cfg, opts = {}) {
         // Always reopen once after subscribing, then drain notifications observed while startup was
         // in progress. Each pass closes before the next one starts, so no stores overlap.
         do {
+            var _opts_signal4, _opts_signal5;
             startupNotification = false;
-            const { store, parsed, warnings } = await openStore(cfg);
+            (_opts_signal4 = opts.signal) === null || _opts_signal4 === void 0 ? void 0 : _opts_signal4.throwIfAborted();
+            const { store, parsed, warnings } = await openStore(cfg, {
+                signal: opts.signal
+            });
             try {
                 if (parsed > 0 || warnings.length > 0) startupEvents.push({
                     parsed,
@@ -79,8 +97,9 @@ export async function runWatch(cfg, opts = {}) {
             } finally{
                 await store.close();
             }
+            (_opts_signal5 = opts.signal) === null || _opts_signal5 === void 0 ? void 0 : _opts_signal5.throwIfAborted();
             if (claimFailure) throw claimFailure;
-        }while (startupNotification && !((_opts_signal = opts.signal) === null || _opts_signal === void 0 ? void 0 : _opts_signal.aborted))
+        }while (startupNotification && !((_opts_signal3 = opts.signal) === null || _opts_signal3 === void 0 ? void 0 : _opts_signal3.aborted))
         startup = false;
         // At most one open+reconcile+close cycle runs at a time; a trigger that arrives mid-cycle is
         // coalesced into a single rerun instead of opening a second, overlapping connection.
@@ -88,7 +107,9 @@ export async function runWatch(cfg, opts = {}) {
         let queuedAlways = null;
         const tick = async (alwaysEmit)=>{
             try {
-                const { store, parsed, warnings } = await openStore(cfg);
+                const { store, parsed, warnings } = await openStore(cfg, {
+                    signal: opts.signal
+                });
                 try {
                     if (alwaysEmit || parsed > 0 || warnings.length > 0) {
                         onEvent({
@@ -102,9 +123,10 @@ export async function runWatch(cfg, opts = {}) {
                     await store.close();
                 }
             } catch (err) {
+                if (isCallerAbort(opts.signal, err)) return;
                 onEvent({
                     type: 'reconcile-error',
-                    message: err.message
+                    message: errorMessage(err)
                 });
             }
         };
@@ -140,15 +162,16 @@ export async function runWatch(cfg, opts = {}) {
         return await new Promise((resolveShutdown, rejectShutdown)=>{
             var _opts_signal;
             let shutdownReason = null;
-            const shutdown = (reason)=>{
+            const shutdown = (reason, canceledByCaller = false)=>{
                 shutdownReason !== null && shutdownReason !== void 0 ? shutdownReason : shutdownReason = reason !== null && reason !== void 0 ? reason : null;
+                callerCanceled || (callerCanceled = canceledByCaller);
                 if (stopping) return;
                 stopping = true;
                 const shutdownTask = (async ()=>{
                     var _opts_signal;
                     process.off('SIGINT', stopNormally);
                     process.off('SIGTERM', stopNormally);
-                    (_opts_signal = opts.signal) === null || _opts_signal === void 0 ? void 0 : _opts_signal.removeEventListener('abort', stopNormally);
+                    (_opts_signal = opts.signal) === null || _opts_signal === void 0 ? void 0 : _opts_signal.removeEventListener('abort', stopForCaller);
                     clearInterval(reconcileTimer);
                     if (debounceTimer) clearTimeout(debounceTimer);
                     watcher === null || watcher === void 0 ? void 0 : watcher.close();
@@ -157,7 +180,7 @@ export async function runWatch(cfg, opts = {}) {
                     try {
                         // A normal stop performs one final freshness pass. Ownership loss drains existing work
                         // but starts nothing new because the replacement watcher now owns that responsibility.
-                        if (!shutdownReason) {
+                        if (!shutdownReason && !callerCanceled) {
                             const { store: finalStore } = await openStore(cfg);
                             await finalStore.close();
                         }
@@ -179,14 +202,15 @@ export async function runWatch(cfg, opts = {}) {
                 shutdownTask.then(resolveShutdown, rejectShutdown);
             };
             const stopNormally = ()=>shutdown();
+            const stopForCaller = ()=>shutdown(undefined, true);
             requestShutdown = shutdown;
             process.once('SIGINT', stopNormally);
             process.once('SIGTERM', stopNormally);
             if (claimFailure) shutdown(claimFailure);
-            else if ((_opts_signal = opts.signal) === null || _opts_signal === void 0 ? void 0 : _opts_signal.aborted) shutdown();
+            else if ((_opts_signal = opts.signal) === null || _opts_signal === void 0 ? void 0 : _opts_signal.aborted) stopForCaller();
             else {
                 var _opts_signal1;
-                (_opts_signal1 = opts.signal) === null || _opts_signal1 === void 0 ? void 0 : _opts_signal1.addEventListener('abort', stopNormally, {
+                (_opts_signal1 = opts.signal) === null || _opts_signal1 === void 0 ? void 0 : _opts_signal1.addEventListener('abort', stopForCaller, {
                     once: true
                 });
                 try {
@@ -210,6 +234,7 @@ export async function runWatch(cfg, opts = {}) {
             }
         });
     } catch (err) {
+        const canceledByCaller = isCallerAbort(opts.signal, err);
         watcher === null || watcher === void 0 ? void 0 : watcher.close();
         if (claimCloseStarted) throw err;
         try {
@@ -220,6 +245,7 @@ export async function runWatch(cfg, opts = {}) {
                 closeError
             ], 'watch setup and claim cleanup both failed');
         }
+        if (canceledByCaller) return;
         throw err;
     } finally{
         requestShutdown = undefined;

package/dist/esm/watch.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/watch.ts"],"sourcesContent":["import { watch as fsWatch } from 'node:fs';\nimport type { ResolvedConfig } from './config/index.ts';\nimport { SenseError } from './errors.ts';\nimport { guardedTick } from './lib/guarded-tick.ts';\nimport { shouldReconcileWatchNotification } from './lib/watch-notification.ts';\nimport { docCount, openStore } from './store/index.ts';\nimport { startWatchClaim, WATCH_HEARTBEAT_INTERVAL_MS } from './watch-claim.ts';\n\n// Watch prepares the index for snapshot queries; filesystem events request debounced builds\n// and periodic reconciliation recovers missed notifications.\nconst DEBOUNCE_MS = 200;\n\nexport type WatchEvent = { type: 'started'; rootDir: string; dbPath: string } | { type: 'reconciled'; parsed: number; total: number; warnings: string[] } | { type: 'reconcile-error'; message: string };\n\nexport interface WatchOptions {\n  force?: boolean;\n  onEvent?: (event: WatchEvent) => void;\n  // Aborting runs the same shutdown path as SIGINT/SIGTERM.\n  signal?: AbortSignal;\n  debounceMs?: number;\n  heartbeatIntervalMs?: number;\n}\n\n// Runs in the foreground until SIGINT/SIGTERM/signal abort. DuckDB and Turso hand the cache file to\n// one process at a time, so every reconcile cycle opens and closes instead of holding an idle lock.\nexport async function runWatch(cfg: ResolvedConfig, opts: WatchOptions = {}): Promise<void> {\n  const onEvent = opts.onEvent ?? (() => {});\n  const debounceMs = opts.debounceMs ?? DEBOUNCE_MS;\n  const reconcileIntervalMs = opts.heartbeatIntervalMs ?? WATCH_HEARTBEAT_INTERVAL_MS;\n  if (!Number.isFinite(reconcileIntervalMs) || reconcileIntervalMs <= 0) throw new SenseError('CONFIG_INVALID', 'watch heartbeatIntervalMs must be a finite positive number');\n  // Reconciliation may be parked for a caller, but live ownership must renew before fixed expiry.\n  const claimIntervalMs = Math.min(reconcileIntervalMs, WATCH_HEARTBEAT_INTERVAL_MS);\n  const rootDir = cfg.rootDir ?? cfg.baseDir;\n  const configDir = cfg.configDir ?? rootDir;\n  let claimFailure: Error | null = null;\n  let requestShutdown: ((reason: Error) => void) | undefined;\n  const claim = await startWatchClaim(configDir, opts.force ?? false, claimIntervalMs, (err) => {\n    claimFailure ??= err;\n    requestShutdown?.(err);\n  });\n  let claimCloseStarted = false;\n  const closeClaim = (): Promise<void> => {\n    claimCloseStarted = true;\n    return claim.close();\n  };\n  let watcher: ReturnType<typeof fsWatch> | undefined;\n  let startup = true;\n  let startupNotification = false;\n  let scheduleReconcile: (() => void) | undefined;\n  let stopping = false;\n  try {\n    // Subscribe before the first build. Native watchers have no ready barrier, so startup also\n    // performs an unconditional catch-up pass after the initial build.\n    watcher = fsWatch(rootDir, { recursive: true }, (_event, filename) => {\n      if (!shouldReconcileWatchNotification(filename)) return;\n      if (startup) startupNotification = true;\n      else scheduleReconcile?.();\n    });\n    watcher.on('error', (err) => {\n      claimFailure ??= err;\n      requestShutdown?.(err);\n    });\n\n    const startupEvents: Array<{ parsed: number; total: number; warnings: string[] }> = [];\n    const { store: initialStore, dbPath, warnings: initialWarnings, parsed: initialParsed } = await openStore(cfg);\n    let initialTotal = 0;\n    try {\n      // total is read before close: an event fires only once nothing is held open again.\n      initialTotal = initialWarnings.length > 0 || initialParsed > 0 ? await docCount(initialStore) : 0;\n    } finally {\n      await initialStore.close();\n    }\n    if (claimFailure) throw claimFailure;\n\n    startupEvents.push({ parsed: initialParsed, total: initialTotal, warnings: initialWarnings });\n    // Always reopen once after subscribing, then drain notifications observed while startup was\n    // in progress. Each pass closes before the next one starts, so no stores overlap.\n    do {\n      startupNotification = false;\n      const { store, parsed, warnings } = await openStore(cfg);\n      try {\n        if (parsed > 0 || warnings.length > 0) startupEvents.push({ parsed, total: await docCount(store), warnings });\n      } finally {\n        await store.close();\n      }\n      if (claimFailure) throw claimFailure;\n    } while (startupNotification && !opts.signal?.aborted);\n    startup = false;\n\n    // At most one open+reconcile+close cycle runs at a time; a trigger that arrives mid-cycle is\n    // coalesced into a single rerun instead of opening a second, overlapping connection.\n    let running: Promise<void> | null = null;\n    let queuedAlways: boolean | null = null;\n\n    const tick = async (alwaysEmit: boolean): Promise<void> => {\n      try {\n        const { store, parsed, warnings } = await openStore(cfg);\n        try {\n          if (alwaysEmit || parsed > 0 || warnings.length > 0) {\n            onEvent({ type: 'reconciled', parsed, total: await docCount(store), warnings });\n          }\n        } finally {\n          await store.close();\n        }\n      } catch (err) {\n        onEvent({ type: 'reconcile-error', message: (err as Error).message });\n      }\n    };\n\n    const startCycle = (alwaysEmit: boolean) => {\n      running = tick(alwaysEmit).then(() => {\n        running = null;\n        if (queuedAlways !== null && !stopping) {\n          const again = queuedAlways;\n          queuedAlways = null;\n          startCycle(again);\n        }\n      });\n    };\n\n    const requestCycle = (alwaysEmit: boolean) => {\n      if (stopping) return;\n      if (running) {\n        queuedAlways = queuedAlways || alwaysEmit;\n        return;\n      }\n      startCycle(alwaysEmit);\n    };\n\n    let debounceTimer: NodeJS.Timeout | null = null;\n    // Ignore our own state files, or cache and claim writes would retrigger reconciliation forever.\n    // An unresolvable filename reconciles because parsing nothing costs less than missing a real edit.\n    scheduleReconcile = () => {\n      if (debounceTimer) clearTimeout(debounceTimer);\n      debounceTimer = setTimeout(() => {\n        debounceTimer = null;\n        requestCycle(true);\n      }, debounceMs);\n    };\n    const reconcileTimer = setInterval(\n      guardedTick(\n        async () => requestCycle(false),\n        () => stopping\n      ),\n      reconcileIntervalMs\n    );\n\n    return await new Promise<void>((resolveShutdown, rejectShutdown) => {\n      let shutdownReason: Error | null = null;\n      const shutdown = (reason?: Error) => {\n        shutdownReason ??= reason ?? null;\n        if (stopping) return;\n        stopping = true;\n        const shutdownTask = (async () => {\n          process.off('SIGINT', stopNormally);\n          process.off('SIGTERM', stopNormally);\n          opts.signal?.removeEventListener('abort', stopNormally);\n          clearInterval(reconcileTimer);\n          if (debounceTimer) clearTimeout(debounceTimer);\n          watcher?.close();\n          await running;\n          let finalError: unknown;\n          try {\n            // A normal stop performs one final freshness pass. Ownership loss drains existing work\n            // but starts nothing new because the replacement watcher now owns that responsibility.\n            if (!shutdownReason) {\n              const { store: finalStore } = await openStore(cfg);\n              await finalStore.close();\n            }\n          } catch (err) {\n            finalError = err;\n          }\n          try {\n            await closeClaim();\n          } catch (err) {\n            if (finalError) throw new AggregateError([finalError, err], 'watch shutdown and claim cleanup both failed');\n            throw err;\n          }\n          if (finalError) throw finalError;\n          if (shutdownReason) throw shutdownReason;\n        })();\n        shutdownTask.then(resolveShutdown, rejectShutdown);\n      };\n      const stopNormally = () => shutdown();\n      requestShutdown = shutdown;\n      process.once('SIGINT', stopNormally);\n      process.once('SIGTERM', stopNormally);\n      if (claimFailure) shutdown(claimFailure);\n      else if (opts.signal?.aborted) shutdown();\n      else {\n        opts.signal?.addEventListener('abort', stopNormally, { once: true });\n        try {\n          onEvent({ type: 'started', rootDir, dbPath });\n          if (!stopping) {\n            for (const event of startupEvents) {\n              if (stopping) break;\n              if (event.warnings.length > 0 || event.parsed > 0) onEvent({ type: 'reconciled', ...event });\n            }\n          }\n        } catch (err) {\n          shutdown(err instanceof Error ? err : new Error(String(err)));\n        }\n      }\n    });\n  } catch (err) {\n    watcher?.close();\n    if (claimCloseStarted) throw err;\n    try {\n      await closeClaim();\n    } catch (closeError) {\n      throw new AggregateError([err, closeError], 'watch setup and claim cleanup both failed');\n    }\n    throw err;\n  } finally {\n    requestShutdown = undefined;\n  }\n}\n"],"names":["watch","fsWatch","SenseError","guardedTick","shouldReconcileWatchNotification","docCount","openStore","startWatchClaim","WATCH_HEARTBEAT_INTERVAL_MS","DEBOUNCE_MS","runWatch","cfg","opts","onEvent","debounceMs","reconcileIntervalMs","heartbeatIntervalMs","Number","isFinite","claimIntervalMs","Math","min","rootDir","baseDir","configDir","claimFailure","requestShutdown","claim","force","err","claimCloseStarted","closeClaim","close","watcher","startup","startupNotification","scheduleReconcile","stopping","recursive","_event","filename","on","startupEvents","store","initialStore","dbPath","warnings","initialWarnings","parsed","initialParsed","initialTotal","length","push","total","signal","aborted","running","queuedAlways","tick","alwaysEmit","type","message","startCycle","then","again","requestCycle","debounceTimer","clearTimeout","setTimeout","reconcileTimer","setInterval","Promise","resolveShutdown","rejectShutdown","shutdownReason","shutdown","reason","shutdownTask","process","off","stopNormally","removeEventListener","clearInterval","finalError","finalStore","AggregateError","once","addEventListener","event","Error","String","closeError","undefined"],"mappings":"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"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/watch.ts"],"sourcesContent":["import { watch as fsWatch } from 'node:fs';\nimport type { ResolvedConfig } from './config/index.ts';\nimport { SenseError } from './errors.ts';\nimport { guardedTick } from './lib/guarded-tick.ts';\nimport { shouldReconcileWatchNotification } from './lib/watch-notification.ts';\nimport { docCount, openStore } from './store/index.ts';\nimport { startWatchClaim, WATCH_HEARTBEAT_INTERVAL_MS } from './watch-claim.ts';\n\n// Watch prepares the index for snapshot queries; filesystem events request debounced builds\n// and periodic reconciliation recovers missed notifications.\nconst DEBOUNCE_MS = 200;\n\nexport type WatchEvent = { type: 'started'; rootDir: string; dbPath: string } | { type: 'reconciled'; parsed: number; total: number; warnings: string[] } | { type: 'reconcile-error'; message: string };\n\n/** Options for the root {@link runWatch} API. */\nexport interface WatchOptions {\n  force?: boolean;\n  onEvent?: (event: WatchEvent) => void;\n  /** Caller abort cancels provider work, skips final preparation, and resolves after cleanup. */\n  signal?: AbortSignal;\n  debounceMs?: number;\n  heartbeatIntervalMs?: number;\n}\n\nfunction isCallerAbort(signal: AbortSignal | undefined, reason: unknown): boolean {\n  return signal?.aborted === true && Object.is(reason, signal.reason);\n}\n\nfunction errorMessage(reason: unknown): string {\n  return reason instanceof Error ? reason.message : String(reason);\n}\n\n/**\n * Runs in the foreground. Caller abort waits for active native work and cleanup; SIGINT/SIGTERM\n * also run one final freshness pass. Cleanup failures reject either shutdown path.\n */\nexport async function runWatch(cfg: ResolvedConfig, opts: WatchOptions = {}): Promise<void> {\n  if (opts.signal?.aborted) return;\n  const onEvent = opts.onEvent ?? (() => {});\n  const debounceMs = opts.debounceMs ?? DEBOUNCE_MS;\n  const reconcileIntervalMs = opts.heartbeatIntervalMs ?? WATCH_HEARTBEAT_INTERVAL_MS;\n  if (!Number.isFinite(reconcileIntervalMs) || reconcileIntervalMs <= 0) throw new SenseError('CONFIG_INVALID', 'watch heartbeatIntervalMs must be a finite positive number');\n  // Reconciliation may be parked for a caller, but live ownership must renew before fixed expiry.\n  const claimIntervalMs = Math.min(reconcileIntervalMs, WATCH_HEARTBEAT_INTERVAL_MS);\n  const rootDir = cfg.rootDir ?? cfg.baseDir;\n  const configDir = cfg.configDir ?? rootDir;\n  let claimFailure: Error | null = null;\n  let requestShutdown: ((reason: Error) => void) | undefined;\n  const claim = await startWatchClaim(configDir, opts.force ?? false, claimIntervalMs, (err) => {\n    claimFailure ??= err;\n    requestShutdown?.(err);\n  });\n  let claimCloseStarted = false;\n  const closeClaim = (): Promise<void> => {\n    claimCloseStarted = true;\n    return claim.close();\n  };\n  let watcher: ReturnType<typeof fsWatch> | undefined;\n  let startup = true;\n  let startupNotification = false;\n  let scheduleReconcile: (() => void) | undefined;\n  let stopping = false;\n  let callerCanceled = false;\n  try {\n    opts.signal?.throwIfAborted();\n    // Subscribe before the first build. Native watchers have no ready barrier, so startup also\n    // performs an unconditional catch-up pass after the initial build.\n    watcher = fsWatch(rootDir, { recursive: true }, (_event, filename) => {\n      if (!shouldReconcileWatchNotification(filename)) return;\n      if (startup) startupNotification = true;\n      else scheduleReconcile?.();\n    });\n    watcher.on('error', (err) => {\n      claimFailure ??= err;\n      requestShutdown?.(err);\n    });\n\n    const startupEvents: Array<{ parsed: number; total: number; warnings: string[] }> = [];\n    const { store: initialStore, dbPath, warnings: initialWarnings, parsed: initialParsed } = await openStore(cfg, { signal: opts.signal });\n    let initialTotal = 0;\n    try {\n      // total is read before close: an event fires only once nothing is held open again.\n      initialTotal = initialWarnings.length > 0 || initialParsed > 0 ? await docCount(initialStore) : 0;\n    } finally {\n      await initialStore.close();\n    }\n    opts.signal?.throwIfAborted();\n    if (claimFailure) throw claimFailure;\n\n    startupEvents.push({ parsed: initialParsed, total: initialTotal, warnings: initialWarnings });\n    // Always reopen once after subscribing, then drain notifications observed while startup was\n    // in progress. Each pass closes before the next one starts, so no stores overlap.\n    do {\n      startupNotification = false;\n      opts.signal?.throwIfAborted();\n      const { store, parsed, warnings } = await openStore(cfg, { signal: opts.signal });\n      try {\n        if (parsed > 0 || warnings.length > 0) startupEvents.push({ parsed, total: await docCount(store), warnings });\n      } finally {\n        await store.close();\n      }\n      opts.signal?.throwIfAborted();\n      if (claimFailure) throw claimFailure;\n    } while (startupNotification && !opts.signal?.aborted);\n    startup = false;\n\n    // At most one open+reconcile+close cycle runs at a time; a trigger that arrives mid-cycle is\n    // coalesced into a single rerun instead of opening a second, overlapping connection.\n    let running: Promise<void> | null = null;\n    let queuedAlways: boolean | null = null;\n\n    const tick = async (alwaysEmit: boolean): Promise<void> => {\n      try {\n        const { store, parsed, warnings } = await openStore(cfg, { signal: opts.signal });\n        try {\n          if (alwaysEmit || parsed > 0 || warnings.length > 0) {\n            onEvent({ type: 'reconciled', parsed, total: await docCount(store), warnings });\n          }\n        } finally {\n          await store.close();\n        }\n      } catch (err) {\n        if (isCallerAbort(opts.signal, err)) return;\n        onEvent({ type: 'reconcile-error', message: errorMessage(err) });\n      }\n    };\n\n    const startCycle = (alwaysEmit: boolean) => {\n      running = tick(alwaysEmit).then(() => {\n        running = null;\n        if (queuedAlways !== null && !stopping) {\n          const again = queuedAlways;\n          queuedAlways = null;\n          startCycle(again);\n        }\n      });\n    };\n\n    const requestCycle = (alwaysEmit: boolean) => {\n      if (stopping) return;\n      if (running) {\n        queuedAlways = queuedAlways || alwaysEmit;\n        return;\n      }\n      startCycle(alwaysEmit);\n    };\n\n    let debounceTimer: NodeJS.Timeout | null = null;\n    // Ignore our own state files, or cache and claim writes would retrigger reconciliation forever.\n    // An unresolvable filename reconciles because parsing nothing costs less than missing a real edit.\n    scheduleReconcile = () => {\n      if (debounceTimer) clearTimeout(debounceTimer);\n      debounceTimer = setTimeout(() => {\n        debounceTimer = null;\n        requestCycle(true);\n      }, debounceMs);\n    };\n    const reconcileTimer = setInterval(\n      guardedTick(\n        async () => requestCycle(false),\n        () => stopping\n      ),\n      reconcileIntervalMs\n    );\n\n    return await new Promise<void>((resolveShutdown, rejectShutdown) => {\n      let shutdownReason: Error | null = null;\n      const shutdown = (reason?: Error, canceledByCaller = false) => {\n        shutdownReason ??= reason ?? null;\n        callerCanceled ||= canceledByCaller;\n        if (stopping) return;\n        stopping = true;\n        const shutdownTask = (async () => {\n          process.off('SIGINT', stopNormally);\n          process.off('SIGTERM', stopNormally);\n          opts.signal?.removeEventListener('abort', stopForCaller);\n          clearInterval(reconcileTimer);\n          if (debounceTimer) clearTimeout(debounceTimer);\n          watcher?.close();\n          await running;\n          let finalError: unknown;\n          try {\n            // A normal stop performs one final freshness pass. Ownership loss drains existing work\n            // but starts nothing new because the replacement watcher now owns that responsibility.\n            if (!shutdownReason && !callerCanceled) {\n              const { store: finalStore } = await openStore(cfg);\n              await finalStore.close();\n            }\n          } catch (err) {\n            finalError = err;\n          }\n          try {\n            await closeClaim();\n          } catch (err) {\n            if (finalError) throw new AggregateError([finalError, err], 'watch shutdown and claim cleanup both failed');\n            throw err;\n          }\n          if (finalError) throw finalError;\n          if (shutdownReason) throw shutdownReason;\n        })();\n        shutdownTask.then(resolveShutdown, rejectShutdown);\n      };\n      const stopNormally = () => shutdown();\n      const stopForCaller = () => shutdown(undefined, true);\n      requestShutdown = shutdown;\n      process.once('SIGINT', stopNormally);\n      process.once('SIGTERM', stopNormally);\n      if (claimFailure) shutdown(claimFailure);\n      else if (opts.signal?.aborted) stopForCaller();\n      else {\n        opts.signal?.addEventListener('abort', stopForCaller, { once: true });\n        try {\n          onEvent({ type: 'started', rootDir, dbPath });\n          if (!stopping) {\n            for (const event of startupEvents) {\n              if (stopping) break;\n              if (event.warnings.length > 0 || event.parsed > 0) onEvent({ type: 'reconciled', ...event });\n            }\n          }\n        } catch (err) {\n          shutdown(err instanceof Error ? err : new Error(String(err)));\n        }\n      }\n    });\n  } catch (err) {\n    const canceledByCaller = isCallerAbort(opts.signal, err);\n    watcher?.close();\n    if (claimCloseStarted) throw err;\n    try {\n      await closeClaim();\n    } catch (closeError) {\n      throw new AggregateError([err, closeError], 'watch setup and claim cleanup both failed');\n    }\n    if (canceledByCaller) return;\n    throw err;\n  } finally {\n    requestShutdown = undefined;\n  }\n}\n"],"names":["watch","fsWatch","SenseError","guardedTick","shouldReconcileWatchNotification","docCount","openStore","startWatchClaim","WATCH_HEARTBEAT_INTERVAL_MS","DEBOUNCE_MS","isCallerAbort","signal","reason","aborted","Object","is","errorMessage","Error","message","String","runWatch","cfg","opts","onEvent","debounceMs","reconcileIntervalMs","heartbeatIntervalMs","Number","isFinite","claimIntervalMs","Math","min","rootDir","baseDir","configDir","claimFailure","requestShutdown","claim","force","err","claimCloseStarted","closeClaim","close","watcher","startup","startupNotification","scheduleReconcile","stopping","callerCanceled","throwIfAborted","recursive","_event","filename","on","startupEvents","store","initialStore","dbPath","warnings","initialWarnings","parsed","initialParsed","initialTotal","length","push","total","running","queuedAlways","tick","alwaysEmit","type","startCycle","then","again","requestCycle","debounceTimer","clearTimeout","setTimeout","reconcileTimer","setInterval","Promise","resolveShutdown","rejectShutdown","shutdownReason","shutdown","canceledByCaller","shutdownTask","process","off","stopNormally","removeEventListener","stopForCaller","clearInterval","finalError","finalStore","AggregateError","undefined","once","addEventListener","event","closeError"],"mappings":"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"}

package/dist/esm/workers/parse.d.ts

@@ -6,8 +6,8 @@ export interface ParseWorkerData {
     cfg: Config;
     featureNames: FeatureName[];
 }
-export type ParseTask = FileStat;
-export type ParseTaskResult = {
+export type ParseTask = FileStat[];
+export type ParseFileResult = {
     ok: true;
     doc: ParsedDoc;
     warnings: string[];
@@ -16,4 +16,5 @@ export type ParseTaskResult = {
     ok: false;
     error: WorkerErrorPayload;
 };
-export default function parseTask(file: ParseTask): ParseTaskResult;
+export type ParseTaskResult = ParseFileResult[];
+export default function parseTask(files: ParseTask): ParseTaskResult;

package/dist/esm/workers/parse.js

@@ -8,21 +8,23 @@ const { cfg, featureNames } = Tinypool.workerData;
 // Filtering the registry (rather than mapping the names) keeps registry order, which is the
 // order `extracted` keys land in on the serial path.
 const selected = FEATURES.filter((feature)=>featureNames.includes(feature.name));
-export default function parseTask(file) {
-    try {
-        const start = process.hrtime.bigint();
-        const { doc, warnings } = parseFile(file, featuresForFile(selected, cfg, file), cfg);
-        const parseMs = Number(process.hrtime.bigint() - start) / 1e6;
-        return {
-            ok: true,
-            doc,
-            warnings,
-            parseMs
-        };
-    } catch (err) {
-        return {
-            ok: false,
-            error: serializeError(err)
-        };
-    }
+export default function parseTask(files) {
+    return files.map((file)=>{
+        try {
+            const start = process.hrtime.bigint();
+            const { doc, warnings } = parseFile(file, featuresForFile(selected, cfg, file), cfg);
+            const parseMs = Number(process.hrtime.bigint() - start) / 1e6;
+            return {
+                ok: true,
+                doc,
+                warnings,
+                parseMs
+            };
+        } catch (err) {
+            return {
+                ok: false,
+                error: serializeError(err)
+            };
+        }
+    });
 }

package/dist/esm/workers/parse.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/workers/parse.ts"],"sourcesContent":["import Tinypool from 'tinypool';\nimport type { Config, FeatureName } from '../config/index.ts';\nimport { FEATURES } from '../features/index.ts';\nimport type { ParsedDoc } from '../scan/index.ts';\nimport { parseFile } from '../scan/index.ts';\nimport type { FileStat } from '../scan/list.ts';\nimport { featuresForFile } from '../scan/reparse.ts';\nimport type { WorkerErrorPayload } from '../scan/worker-error.ts';\nimport { serializeError } from '../scan/worker-error.ts';\n\n// Constant for the whole dispatch, so it crosses once per worker instead of once per task. A\n// Feature carries closures and cannot cross the thread boundary; its name can, and the registry here resolves it back.\nexport interface ParseWorkerData {\n  cfg: Config;\n  featureNames: FeatureName[];\n}\n\n// tinypool's task, in and out. The task itself is one FileStat. Result carries only what\n// parseFile already returns -- extracted text and per-feature values, never the token tree.\nexport type ParseTask = FileStat;\n\n// parseMs is the worker's own hrtime for parseFile, excluding dispatch and the return clone --\n// what separates it from the pool's dispatch-to-drain `parse` stage.\nexport type ParseTaskResult = { ok: true; doc: ParsedDoc; warnings: string[]; parseMs: number } | { ok: false; error: WorkerErrorPayload };\n\n// Read once per worker, not per task.\nconst { cfg, featureNames } = Tinypool.workerData as ParseWorkerData;\n// Filtering the registry (rather than mapping the names) keeps registry order, which is the\n// order `extracted` keys land in on the serial path.\nconst selected = FEATURES.filter((feature) => featureNames.includes(feature.name));\n\nexport default function parseTask(file: ParseTask): ParseTaskResult {\n  try {\n    const start = process.hrtime.bigint();\n    const { doc, warnings } = parseFile(file, featuresForFile(selected, cfg, file), cfg);\n    const parseMs = Number(process.hrtime.bigint() - start) / 1e6;\n    return { ok: true, doc, warnings, parseMs };\n  } catch (err) {\n    return { ok: false, error: serializeError(err) };\n  }\n}\n"],"names":["Tinypool","FEATURES","parseFile","featuresForFile","serializeError","cfg","featureNames","workerData","selected","filter","feature","includes","name","parseTask","file","start","process","hrtime","bigint","doc","warnings","parseMs","Number","ok","err","error"],"mappings":"AAAA,OAAOA,cAAc,WAAW;AAEhC,SAASC,QAAQ,QAAQ,uBAAuB;AAEhD,SAASC,SAAS,QAAQ,mBAAmB;AAE7C,SAASC,eAAe,QAAQ,qBAAqB;AAErD,SAASC,cAAc,QAAQ,0BAA0B;AAiBzD,sCAAsC;AACtC,MAAM,EAAEC,GAAG,EAAEC,YAAY,EAAE,GAAGN,SAASO,UAAU;AACjD,4FAA4F;AAC5F,qDAAqD;AACrD,MAAMC,WAAWP,SAASQ,MAAM,CAAC,CAACC,UAAYJ,aAAaK,QAAQ,CAACD,QAAQE,IAAI;AAEhF,eAAe,SAASC,UAAUC,IAAe;IAC/C,IAAI;QACF,MAAMC,QAAQC,QAAQC,MAAM,CAACC,MAAM;QACnC,MAAM,EAAEC,GAAG,EAAEC,QAAQ,EAAE,GAAGlB,UAAUY,MAAMX,gBAAgBK,UAAUH,KAAKS,OAAOT;QAChF,MAAMgB,UAAUC,OAAON,QAAQC,MAAM,CAACC,MAAM,KAAKH,SAAS;QAC1D,OAAO;YAAEQ,IAAI;YAAMJ;YAAKC;YAAUC;QAAQ;IAC5C,EAAE,OAAOG,KAAK;QACZ,OAAO;YAAED,IAAI;YAAOE,OAAOrB,eAAeoB;QAAK;IACjD;AACF"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/workers/parse.ts"],"sourcesContent":["import Tinypool from 'tinypool';\nimport type { Config, FeatureName } from '../config/index.ts';\nimport { FEATURES } from '../features/index.ts';\nimport type { ParsedDoc } from '../scan/index.ts';\nimport { parseFile } from '../scan/index.ts';\nimport type { FileStat } from '../scan/list.ts';\nimport { featuresForFile } from '../scan/reparse.ts';\nimport type { WorkerErrorPayload } from '../scan/worker-error.ts';\nimport { serializeError } from '../scan/worker-error.ts';\n\n// Constant for the whole dispatch, so it crosses once per worker instead of once per task. A\n// Feature carries closures and cannot cross the thread boundary; its name can, and the registry here resolves it back.\nexport interface ParseWorkerData {\n  cfg: Config;\n  featureNames: FeatureName[];\n}\n\n// Each task is a small file batch. Results stay per-file so one failure does not stop the\n// remaining files in that batch, and no token tree crosses the thread boundary.\nexport type ParseTask = FileStat[];\n\n// parseMs is the worker's own hrtime for parseFile, excluding dispatch and the return clone --\n// what separates it from the pool's dispatch-to-drain `parse` stage.\nexport type ParseFileResult = { ok: true; doc: ParsedDoc; warnings: string[]; parseMs: number } | { ok: false; error: WorkerErrorPayload };\nexport type ParseTaskResult = ParseFileResult[];\n\n// Read once per worker, not per task.\nconst { cfg, featureNames } = Tinypool.workerData as ParseWorkerData;\n// Filtering the registry (rather than mapping the names) keeps registry order, which is the\n// order `extracted` keys land in on the serial path.\nconst selected = FEATURES.filter((feature) => featureNames.includes(feature.name));\n\nexport default function parseTask(files: ParseTask): ParseTaskResult {\n  return files.map((file): ParseFileResult => {\n    try {\n      const start = process.hrtime.bigint();\n      const { doc, warnings } = parseFile(file, featuresForFile(selected, cfg, file), cfg);\n      const parseMs = Number(process.hrtime.bigint() - start) / 1e6;\n      return { ok: true, doc, warnings, parseMs };\n    } catch (err) {\n      return { ok: false, error: serializeError(err) };\n    }\n  });\n}\n"],"names":["Tinypool","FEATURES","parseFile","featuresForFile","serializeError","cfg","featureNames","workerData","selected","filter","feature","includes","name","parseTask","files","map","file","start","process","hrtime","bigint","doc","warnings","parseMs","Number","ok","err","error"],"mappings":"AAAA,OAAOA,cAAc,WAAW;AAEhC,SAASC,QAAQ,QAAQ,uBAAuB;AAEhD,SAASC,SAAS,QAAQ,mBAAmB;AAE7C,SAASC,eAAe,QAAQ,qBAAqB;AAErD,SAASC,cAAc,QAAQ,0BAA0B;AAkBzD,sCAAsC;AACtC,MAAM,EAAEC,GAAG,EAAEC,YAAY,EAAE,GAAGN,SAASO,UAAU;AACjD,4FAA4F;AAC5F,qDAAqD;AACrD,MAAMC,WAAWP,SAASQ,MAAM,CAAC,CAACC,UAAYJ,aAAaK,QAAQ,CAACD,QAAQE,IAAI;AAEhF,eAAe,SAASC,UAAUC,KAAgB;IAChD,OAAOA,MAAMC,GAAG,CAAC,CAACC;QAChB,IAAI;YACF,MAAMC,QAAQC,QAAQC,MAAM,CAACC,MAAM;YACnC,MAAM,EAAEC,GAAG,EAAEC,QAAQ,EAAE,GAAGpB,UAAUc,MAAMb,gBAAgBK,UAAUH,KAAKW,OAAOX;YAChF,MAAMkB,UAAUC,OAAON,QAAQC,MAAM,CAACC,MAAM,KAAKH,SAAS;YAC1D,OAAO;gBAAEQ,IAAI;gBAAMJ;gBAAKC;gBAAUC;YAAQ;QAC5C,EAAE,OAAOG,KAAK;YACZ,OAAO;gBAAED,IAAI;gBAAOE,OAAOvB,eAAesB;YAAK;QACjD;IACF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sensemaking",
-  "version": "0.25.1",
+  "version": "0.27.0",
   "description": "Query and search your markdown notes with context-aware progressive disclosure: SQL over frontmatter, links, and text, plus semantic search and link-graph ranking. No server, no build step.",
   "keywords": [
     "markdown",

package/skills/sense/EXAMPLES.md

@@ -17,7 +17,7 @@ sense search "pricing OR billing OR invoicing" --k 10 --format json
 ]
 ```
 
-Tens of tokens per row; often the `summary` answers the question with no read at all. A row with `via: "link"` never contained the terms. It is linked from notes that did. `lines`, when set, is the section that earned the row, a direct `Read` range.
+Tens of tokens per row; often the `summary` answers the question with no read at all. A row with `via: "link"` has link evidence rather than a word match. `lines`, when set, is a section or embedding chunk's line range, a direct `Read` range. See [Sense terminology](references/terminology.md) for these distinctions.
 
 ## B. Known-field filtering (no search)
 
@@ -56,7 +56,7 @@ The note is ~4,400 tokens; the peek is ~500. If only one section matters, `Read`
 
 ```
 sense sql "SELECT src FROM links WHERE dst = ?" notes/pricing-model.md    # who cites this
-sense sql "SELECT src, target FROM links WHERE dst IS NULL"               # dead links
+sense sql "SELECT src, target FROM links WHERE dst IS NULL"               # unresolved links
 sense sql "SELECT path, round(_rank*100,2) r FROM frontmatter ORDER BY _rank DESC LIMIT 5"  # load-bearing notes
 ```
 
@@ -83,7 +83,7 @@ sense search "children dying from poor nutrition" --k 3 --format json
 ]
 ```
 
-A `via: "vector"` row never contained the terms. It is semantically near them; `similarity` is the cosine against the chunk `lines` names, a direct `Read` range. Vector rows appear whenever the config names an `embed` model and it is downloaded; a result of only vector rows means the words themselves are nowhere in the scope.
+A `via: "vector"` row has vector evidence rather than a word match. `similarity` is the cosine against the chunk identified by `lines`, a direct `Read` range. Vector search requires a configured model, enabled vector signal and prepared embeddings. Vector-only results do not prove the query words are absent; use the word-search guidance when absence matters.
 
 ## Consequences
 

package/skills/sense/SKILL.md

@@ -5,10 +5,12 @@ description: "Query a markdown tree with the sense CLI: filter notes by frontmat
 
 # sense
 
-Use sense to locate evidence in a markdown tree before reading files. With the config default `"build": true`, CLI queries incrementally scan the configured tree for the capabilities they need; vector preparation is limited to the eligible scope. Config `"build": false` or a one-query `--no-build` reads the last completed indexed generation, checks requested readiness and does not scan live files. Explicit build and watch prepare it regardless of that default. Results contain paths, metadata, excerpts, and line ranges. Read the returned files or ranges when the task needs their prose.
+Use sense to locate evidence in a markdown tree before reading files. With the config default `"build": true`, CLI queries incrementally scan the configured tree for the capabilities they need; vector preparation is limited to the eligible scope. Config `"build": false` or a one-query `--no-build` reads the last completed indexed generation, checks requested readiness and does not scan live files. Explicit build and watch prepare it regardless of that default. Results contain paths, metadata, snippets, and line ranges. Read the returned files or ranges when the task needs their prose.
 
 Setup, store selection, presets, and note design belong to the `sense-setup` skill. Translating an Obsidian Bases file belongs to `sense-bases`.
 
+Use the shared [Sense terminology](references/terminology.md) when explaining results or output controls. Read it when distinguishing a snippet, section, section description, outline, chunk or link type; those names are not interchangeable.
+
 ## Start with the tree
 
 Run these when the tree or its configuration is unfamiliar:
@@ -67,13 +69,19 @@ The tables, `?` placeholders, quoted identifiers, `has()`, `basename()`, and pre
 
 Combinations such as `match+link` mean that more than one signal produced the row. `score` ranks rows within that result only. Do not compare it across searches. `similarity` ranks vector evidence within the current result and model. Do not carry a fixed similarity cutoff between trees.
 
-The `lines` value points at the section that earned the row. Read that range when it is present. A null range means the whole note is the reference. A vector-only row has no lexical snippet and is a lead, not proof that the note contains the query terms.
+The `lines` value gives a line range in the indexed note. It can identify a section around a word match or an embedding chunk. Read that range when it is present. A null range means the whole note is the reference. A vector-only row has no lexical snippet and is a lead, not proof that the note contains the query terms.
 
 Read [search evidence and troubleshooting](references/search.md) when a search will support a factual claim, when absence matters, when results look noisy, or when tuning signal weights.
 
+`sense search --explain --format json` adds the actual ranking contributions for returned notes. It does not change ranking or explain every missing result. The search guide describes how contributions differ from the `via` evidence label.
+
 ## Scope and output
 
-Bare commands use the `default` preset. `--preset <name>` chooses another. For `search`, `--include`, `--exclude`, and `--no-exclude` change the query scope for one invocation, but cannot reach files that no preset indexes. `sense status` shows actual coverage.
+Bare commands use the `default` preset. `--preset <name>` chooses another. For `search`, `map`, `peek`, `path`, and `related`, `--include`, `--exclude`, and `--no-exclude` change the query scope for one invocation, but cannot reach files that no preset indexes. `sense status` shows actual coverage. Scope selects results; presets are not a security boundary.
+
+`peek` rejects an exact path outside scope before trying a basename, resolves basenames within scope, and shows only scoped resolved links and backlinks; unresolved targets remain as written. `path` resolves its endpoints across the indexed tree and scopes intermediate notes. `related` resolves its seed across the indexed tree and scopes result candidates.
+
+`peek --section-count-limit n` bounds section descriptions. `--link-count-limit n` independently bounds each group of outbound links, backlinks and unresolved links. Both default to 20 and require positive safe integers. Request more when the outline or links you need are truncated, or fewer for triage. Totals still describe the full selected groups; the limits do not widen scope. Section descriptions identify where to read; they do not return section prose.
 
 `--where` filters search and graph commands against frontmatter alias `f`:
 

package/skills/sense/references/search.md

@@ -2,6 +2,8 @@
 
 Read this guide when search results will support a factual claim, when absence matters, when results look noisy, or when changing signal weights.
 
+[Sense terminology](terminology.md) defines the result objects. In particular, snippets, sections and embedding chunks are different units.
+
 ## What each signal establishes
 
 `words` ranks literal occurrences after stemming. It is the right signal for identifiers, error strings, names, and quoted phrases. A `match` row is lexical evidence because its `snippets` show the occurrence.
@@ -22,12 +24,26 @@ Weights are corpus and model choices. Compare representative queries before chan
 
 - `via` names the evidence that produced the row.
 - `snippets` contains marked lexical passages. It is empty when no word matched.
-- `lines` names the best section to read. Null means the whole note is the reference.
+- `lines` is the selected section or embedding chunk's line range in the indexed note. Null means the whole note is the reference.
 - `score` orders the fused result. Its scale changes with the participating signals and ranks, so compare rows only inside one result.
 - `similarity` is cosine similarity against the best chunk. Compare it inside one result and one model. Small trees can give unrelated text a moderately close nearest neighbor.
 
 Relay the evidence label when reporting a result. "The note contains these words" and "the note is semantically related" support different claims.
 
+## Finite retrieval and paging
+
+`k` is the maximum number of notes returned by one finite retrieval. Changing `k` can change the candidate pools, link seeds and fused ranking, including the earlier rows. It starts a new retrieval rather than continuing a stable result set. When you need pages, retain one returned array or JSON result and page that locally.
+
+## Explain a ranking
+
+Add `--explain` to a direct `sense search` invocation when you need to inspect how the configured signals contributed. With `--format json`, each returned row adds an `explanation` array containing `signal`, `rank`, `weight` and `contribution`. Entries follow words, links, vectors order and include only signals that contributed to that candidate. Without the flag, ordinary output is unchanged.
+
+Ranks are one-based within each signal's candidate list. A contribution is `weight / (60 + rank - 1)`, using the actual unrounded value accumulated during ranking. The sum is the fused score before its public display rounding. These values are not native BM25 scores and do not make lexical rankings comparable across stores.
+
+An isolated word-match seed can receive link-signal restart mass while its `via` label remains `match`. The explanation reports the numeric contribution; `via` remains the evidence label, not an exhaustive score breakdown. An explanation does not establish that a claim is true or describe why an absent note failed to enter the candidate set.
+
+Table and CSV formats encode the explanation cell as JSON text. Table output follows the existing cell clipping rules; use JSON or CSV for the complete values. Explanation reuses the current search and does not make an additional embedding request. It is not a saved-query configuration field.
+
 ## When a search misses
 
 For word search, try concrete terms that the notes may use, widen the selected preset, or raise `--k`. Search grammar depends on the selected store. Read its guide before adding operators.

package/skills/sense/references/sql.md

@@ -94,7 +94,7 @@ SELECT DISTINCT path FROM hop WHERE d > 0;
 
 Use `sense path` for the shortest chain between two known notes. Use raw recursion when the task needs a set of neighbors to filter or join.
 
-## Dead links
+## Unresolved links
 
 `dst IS NULL` includes links to attachments that sense never indexes, such as images, PDFs, and `.base` files. Exclude the attachment extensions used by the tree before treating the remaining rows as broken links. Trees with dotted markdown titles need an explicit extension list instead of a blanket "contains a dot" filter.
 

package/skills/sense/references/stores/duckdb.md

@@ -4,7 +4,7 @@ Read this guide when `store` is `duckdb`.
 
 Sense stores the cache at `.sense/cache.duckdb`. It is a DuckDB database file with frontmatter values in `VARIANT` columns and embeddings in native fixed-width float arrays. Use this store when another DuckDB tool needs to inspect or analyze the cache.
 
-The first open installs `@duckdb/node-api` if needed. Its native download is about 110 MB. DuckDB holds the cache file for the connection's lifetime, so another sense command waits for the current command or watcher cycle to close it.
+The first open installs `@duckdb/node-api` if needed. Its native download is about 110 MB. Under DuckDB's [concurrency model](https://duckdb.org/docs/current/connect/concurrency), Sense opens an existing cache for no-build observation in read-only mode, so several independent reader processes can coexist. A build-enabled command or watcher opens it read-write and excludes every other process until it closes. Contenders wait within Sense's bounded lock budget, then fail with `STORE_BUSY`. This cross-process rule does not promise writer/reader coexistence or unrestricted sharing by independently configured DuckDB instances in one process.
 
 ## `sense search` grammar
 

package/skills/sense/references/terminology.md

@@ -0,0 +1,32 @@
+# Sense terminology
+
+This is the shared vocabulary for Sense's README, command help, API documentation and skills. Use these names when describing results and output controls.
+
+| Term | Meaning |
+|---|---|
+| Note | One Markdown file. A document is the same unit; SQL and some status fields use that name. |
+| Tree | The directory of notes configured as Sense's root. |
+| Frontmatter | The YAML metadata at the beginning of a note, such as its title, tags or status. |
+| Search result | One matching note, returned with its path, ranking information and any snippets. A result is not a section or a chunk. |
+| Snippet | A short passage selected around matching words, marked with `«»`. A note can return multiple snippets. A snippet need not contain a whole section. |
+| Heading | A Markdown heading such as `## Installation`. Its level is its depth, from 1 to 6. |
+| Section | A heading and the content following it until the next heading of any level, or the end of the note. Text before the first heading is not a section in the `sections` table. A parent section does not include subsequent subsections. |
+| Section description | The heading text, level, start and end lines, and estimated token count returned by `peek`. It does not contain the section's prose. |
+| Outline | The section descriptions in document order. It is a view of the note's structure, not another stored type of content. |
+| Chunk | A span of note content prepared for embedding. Chunking follows document structure and a token budget; a chunk is not necessarily one section or one snippet. |
+| Line range | Inclusive, one-based lines in the indexed source note, such as `L12-28`. Search can point to a section or an embedding chunk. A null range provides no narrower location. |
+| Outbound link | A link from the current note to another indexed note. `peek.outbound` returns distinct destination paths. |
+| Backlink | A link from another indexed note to the current note. `peek.backlinks` returns distinct source paths. |
+| Unresolved link | A written link target that did not resolve to an indexed note. This does not establish that the link is broken: attachments and notes outside the index can also be unresolved. `peek.unresolved` returns written targets. |
+| Scope | The indexed notes selected for an operation by its preset and filters. Scope is not an access-control boundary. |
+| Search signal | One source of ranking evidence: word matches, link relationships or vector similarity. A signal's rank is a candidate's position within that signal, not the final combined position. |
+
+## Reading a section description
+
+The illustrative entry `## Installation [L12-28, ~90t]` describes a section headed “Installation”, starting at line 12 and ending at line 28, with an estimated 90 tokens. `peek` returns that description. Reading the indicated lines retrieves the content. With nested headings, the description ends before the next heading, even when that heading is deeper.
+
+## Naming output controls
+
+Name the object and the unit: a snippet count is how many passages are returned; a snippet character limit controls passage length; a section count is how many section descriptions are returned; a link count controls link entries. A count limit is not pagination. An offset, when supported by an operation, skips entries before returning the requested count. Raw SQL supports `LIMIT` and `OFFSET`; search and peek do not currently expose offset options.
+
+Peek count limits request prefixes of the ordered section and link lists. Each search or peek reads one committed index snapshot; separately issued operations can observe later commits. See [finite retrieval and paging](search.md#finite-retrieval-and-paging) for search budgets and paging retained results.

package/skills/sense-setup/SKILL.md

@@ -22,7 +22,7 @@ sense status
 
 By default, the config indexes its own directory. A top-level `root` can point at another markdown tree. Relative roots resolve from the config directory, and `.sense/` remains beside the config. Use this when separate consumers need their own presets, saved queries, or caches over one tree.
 
-Globs and indexed paths are relative to the selected root. Run `sense status` and `sense map` after changing the config to confirm preset coverage and the selected store. A change that affects indexed content rebuilds the relevant cache and reports the reason.
+Globs and indexed paths are relative to the selected root. Run `sense status` and `sense map` after changing the config to confirm preset coverage and the selected store. A change that affects indexed content rebuilds the relevant cache and reports the reason. A build-enabled command replaces an incompatible derived cache format and repairs incomplete feature state; config `"build": false` or `--no-build` reports the required build without rebuilding or repairing the Sense index.
 
 ## Choose the store
 
@@ -86,7 +86,7 @@ Vectors require two choices. The top-level `embed` block names the model and pro
 }
 ```
 
-The config's `"build": true` default lets CLI queries prepare their needed capabilities. Set `"build": false` for manual-build or watch workflows. The first build-enabled vector search downloads a named static model and embeds its eligible scope. `sense build` and `sense watch` prepare all configured capabilities regardless of this setting; `sense download` fetches the model earlier when CI, offline work, or timing makes that useful. A config change that alters the model, vector coverage, or chunking can rebuild vectors. Config `"build": false` or `--no-build` requires the requested vector scope to be ready and does not read newer live files.
+The config's `"build": true` default lets CLI queries prepare their needed capabilities. Set `"build": false` for manual-build or watch workflows. The first build-enabled vector search downloads a named static model and embeds its eligible scope. `sense build` and `sense watch` prepare all configured capabilities regardless of this setting; `sense download` fetches the model earlier when CI, offline work, or timing makes that useful. A config change that alters the provider, model, effective endpoint, vector coverage, or chunking can invalidate or rebuild vectors. Config `"build": false` or `--no-build` requires the requested vector scope to be ready and does not read newer live files.
 
 Read [embedding setup](references/embeddings.md) when choosing a provider or model, supporting a non-English tree, changing chunk size, or tuning signal weights.
 

package/skills/sense-setup/references/embeddings.md

@@ -22,7 +22,7 @@ For a static model, inspect current Model2Vec models and their cards rather than
 
 Naming a remote static model in the config authorizes its download. `sense download` performs that fetch before a query. A default vector query embeds its eligible scope; `sense build` and `sense watch` prepare all configured vector capabilities, while `--no-build` requires the requested scope to be ready.
 
-Changing the model changes the vector space and rebuilds embeddings. Changing preset coverage can also add, remove, or rebuild vector rows. Settle the broad scope before embedding a large tree.
+Changing the provider, model, or effective endpoint invalidates stored vector values while preserving the indexed chunks. Changing `embed.chunkTokens` rebuilds affected embedding rows, and changing preset coverage can add, remove, or rebuild them. A build-enabled command performs this work; config `"build": false` or `--no-build` reports incompatible or unprepared state without rebuilding or repairing the Sense index. Settle the broad scope before embedding a large tree.
 
 ## Chunk size
 

package/skills/sense-setup/references/store-benchmarks.md

@@ -1,15 +1,15 @@
-<!-- sense-store-benchmark release=0.25.0 -->
+<!-- sense-store-benchmark release=0.27.0 -->
 # Current store benchmark summary
 
-The release assessment generated this file for store selection. Release `0.25.0` passed on 2026-09-20, measured on Apple M4 Pro with Node v26.8.2.
+The release assessment generated this file for store selection. Release `0.27.0` passed on 2026-10-03, measured on Apple M1 Pro with Node v26.10.0.
 
 The timing rows ran on the same 6,566-note tree. They include CLI startup and each store's complete selected path. Ranked candidates and downstream work can differ by store, so these are current operating measurements rather than an isolated database-engine contest.
 
 | Store | Cold index | Warm count | Lexical search | Semantic search | Portable semantic nDCG@10 |
 |---|---|---|---|---|---|
-| sqlite | 1,197 ms | 126 ms | 190 ms | 338 ms | 0.3306 |
-| duckdb | 1,801 ms | 164 ms | 297 ms | 415 ms | 0.3284 |
-| turso | 2,056 ms | 135 ms | 232 ms | 640 ms | 0.3307 |
+| sqlite | 2,254 ms | 260 ms | 350 ms | 576 ms | 0.3306 |
+| duckdb | 3,026 ms | 319 ms | 510 ms | 695 ms | 0.3282 |
+| turso | 3,273 ms | 279 ms | 412 ms | 1,081 ms | 0.3299 |
 
 Cold index measures core index creation and a count query, excluding document embeddings. Warm count is a no-change `COUNT(*)` query. Lexical and semantic search are steady-state `sense search` commands. Lower timing is faster. Higher nDCG@10 is better; that quality column uses the same NFCorpus queries, judgments, result count, and model on every store.
 

package/skills/sense-setup/references/stores/duckdb.md

@@ -18,7 +18,7 @@ Sense's [store benchmark summary](../store-benchmarks.md) measures the current a
 
 - DuckDB support is experimental.
 - The first open installs `@duckdb/node-api`, with a native download of about 110 MB.
-- DuckDB holds the cache file for the life of a connection. Concurrent sense commands wait for the current command or watcher cycle to close it.
+- Under DuckDB's [concurrency model](https://duckdb.org/docs/current/connect/concurrency), Sense opens an existing cache for no-build observation in read-only mode, so several independent reader processes can coexist. A build-enabled command or watcher opens it read-write and excludes every other process until it closes. Contenders wait within Sense's bounded lock budget, then fail with `STORE_BUSY`. This cross-process rule does not promise writer/reader coexistence or unrestricted sharing by independently configured DuckDB instances in one process.
 - `sense search` accepts bare words and quoted phrases. It rejects FTS5 boolean, prefix, `NEAR`, initial-token, grouping, and column-filter syntax.
 - SQLite's raw `MATCH`, `snippet()`, and `bm25()` queries do not port.
 - Mixed-type `VARIANT` fields can require explicit casts in predicates.