sensemaking 0.25.0 → 0.26.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.0",
+  "version": "0.26.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/SKILL.md

@@ -5,7 +5,7 @@ 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`.
 
@@ -73,7 +73,9 @@ Read [search evidence and troubleshooting](references/search.md) when a search w
 
 ## 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.
 
 `--where` filters search and graph commands against frontmatter alias `f`:
 

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-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.26.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.26.0` passed on 2026-10-01, 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,158 ms | 256 ms | 351 ms | 569 ms | 0.3306 |
+| duckdb | 3,100 ms | 315 ms | 501 ms | 691 ms | 0.3282 |
+| turso | 3,268 ms | 276 ms | 409 ms | 1,066 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.