sensemaking 0.24.6 → 0.25.0

package/dist/cjs/store/turso/store.d.cts

@@ -1,4 +1,6 @@
 import type { Database } from '@tursodatabase/database';
 import type { Capability, Connection, Store } from '../types.js';
 export declare const CAPABILITIES: ReadonlySet<Capability>;
-export declare function createStore(db: Database, conn: Connection): Store;
+export declare function createStore(db: Database, conn: Connection, options?: {
+    observational?: boolean;
+}): Store;

package/dist/cjs/store/turso/store.d.ts

@@ -1,4 +1,6 @@
 import type { Database } from '@tursodatabase/database';
 import type { Capability, Connection, Store } from '../types.js';
 export declare const CAPABILITIES: ReadonlySet<Capability>;
-export declare function createStore(db: Database, conn: Connection): Store;
+export declare function createStore(db: Database, conn: Connection, options?: {
+    observational?: boolean;
+}): Store;

package/dist/cjs/store/turso/store.js

@@ -370,6 +370,7 @@ var CAPABILITIES = new Set([
 // overhead a user should accept (PLAN 3.52), in postgres autovacuum scale-factor shape.
 var BLOAT_FACTOR = 1.5;
 function createStore(db, conn) {
+    var options = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : {};
     return {
         name: 'turso',
         capabilities: CAPABILITIES,
@@ -561,116 +562,130 @@ function createStore(db, conn) {
                 return _ts_generator(this, function(_state) {
                     switch(_state.label){
                         case 0:
+                            if (!options.observational) return [
+                                3,
+                                2
+                            ];
+                            return [
+                                4,
+                                db.close()
+                            ];
+                        case 1:
+                            _state.sent();
+                            return [
+                                2
+                            ];
+                        case 2:
                             // Checkpoint before measuring: the last reconcile's pages sit in the WAL, not the file yet.
                             return [
                                 4,
                                 (0, _connectionts.checkpointWal)(db)
                             ];
-                        case 1:
+                        case 3:
                             _state.sent();
                             reclaimPath = null;
-                            _state.label = 2;
-                        case 2:
+                            _state.label = 4;
+                        case 4:
                             _state.trys.push([
-                                2,
-                                12,
+                                4,
+                                14,
                                 ,
-                                13
+                                15
                             ]);
                             return [
                                 4,
                                 (0, _connectionts.cacheFilePath)(conn)
                             ];
-                        case 3:
+                        case 5:
                             path = _state.sent();
                             return [
                                 4,
                                 (0, _sharedts.getMeta)(conn, 'compact_size')
                             ];
-                        case 4:
+                        case 6:
                             base = Number.apply(void 0, [
                                 (_ref = _state.sent()) !== null && _ref !== void 0 ? _ref : '0'
                             ]);
                             if (!(path === null)) return [
                                 3,
-                                5
+                                7
                             ];
                             _tmp = null;
                             return [
                                 3,
-                                7
+                                9
                             ];
-                        case 5:
+                        case 7:
                             return [
                                 4,
                                 (0, _connectionts.fileSize)(path)
                             ];
-                        case 6:
+                        case 8:
                             _tmp = _state.sent();
-                            _state.label = 7;
-                        case 7:
+                            _state.label = 9;
+                        case 9:
                             size = _tmp;
                             if (!(size !== null)) return [
                                 3,
-                                11
+                                13
                             ];
                             if (!(base === 0)) return [
                                 3,
-                                10
+                                12
                             ];
                             return [
                                 4,
                                 (0, _sharedts.setMeta)(conn, 'compact_size', String(size))
                             ];
-                        case 8:
+                        case 10:
                             _state.sent();
                             // The meta write landed past the checkpoint; leave no WAL for the next opener.
                             return [
                                 4,
                                 (0, _connectionts.checkpointWal)(db)
                             ];
-                        case 9:
+                        case 11:
                             _state.sent();
                             return [
                                 3,
-                                11
+                                13
                             ];
-                        case 10:
+                        case 12:
                             if (size > BLOAT_FACTOR * base) {
                                 reclaimPath = path;
                             }
-                            _state.label = 11;
-                        case 11:
+                            _state.label = 13;
+                        case 13:
                             return [
                                 3,
-                                13
+                                15
                             ];
-                        case 12:
+                        case 14:
                             err = _state.sent();
                             console.error("sense: turso cache bloat check failed, the cache will keep its space until one succeeds: ".concat(err.message));
                             return [
                                 3,
-                                13
+                                15
                             ];
-                        case 13:
+                        case 15:
                             return [
                                 4,
                                 db.close()
                             ];
-                        case 14:
+                        case 16:
                             _state.sent();
                             if (!(reclaimPath !== null)) return [
                                 3,
-                                16
+                                18
                             ];
                             return [
                                 4,
                                 (0, _connectionts.reclaimSpace)(reclaimPath)
                             ];
-                        case 15:
+                        case 17:
                             _state.sent();
-                            _state.label = 16;
-                        case 16:
+                            _state.label = 18;
+                        case 18:
                             return [
                                 2
                             ];

package/dist/cjs/store/turso/store.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/store/turso/store.ts"],"sourcesContent":["import type { Database } from '@tursodatabase/database';\nimport { STORE_DIMS } from '../../embed/types.ts';\nimport { getColumns, getMeta, setMeta } from '../shared.ts';\nimport { withTransaction } from '../transaction.ts';\nimport type { Capability, Connection, Statement, Store } from '../types.ts';\nimport { hasVectorRow, pendingRows } from '../vectors.ts';\nimport { cacheFilePath, checkpointWal, fileSize, reclaimSpace } from './connection.ts';\nimport { fieldStats } from './fieldStats.ts';\nimport { queryLexical } from './lexical.ts';\nimport { rewriteFunctions } from './sql-functions.ts';\nimport { scanCandidates, scanSimilar, writeVectorBatch } from './vectors.ts';\n\n// No 'segment': has()/basename() resolve via SQL rewrite below (sql-functions.ts), but segment() has no SQL form and the client cannot register it as a UDF.\nexport const CAPABILITIES: ReadonlySet<Capability> = new Set(['vectors']);\n\n// close() reclaims once the cache file outgrows its compact size by this factor: the disk\n// overhead a user should accept (PLAN 3.52), in postgres autovacuum scale-factor shape.\nconst BLOAT_FACTOR = 1.5;\n\n// Shares one Connection instance (conn) with the builder's own reconcile call so transaction depth\n// (see transaction.ts) is tracked against the same object everywhere.\nexport function createStore(db: Database, conn: Connection): Store {\n  return {\n    name: 'turso',\n    capabilities: CAPABILITIES,\n    async exec(sql: string): Promise<void> {\n      await conn.exec(sql);\n    },\n    async prepare(sql: string): Promise<Statement> {\n      return conn.prepare(sql);\n    },\n    async runBatch(sql: string, paramRows: unknown[][]): Promise<void> {\n      await conn.runBatch(sql, paramRows);\n    },\n    async transaction<T>(fn: () => Promise<T>): Promise<T> {\n      return withTransaction(conn, fn);\n    },\n    docs: {\n      async columns() {\n        return [...(await getColumns(conn))];\n      },\n      fieldStats: (columns, scopeWhere) => fieldStats(conn, columns, scopeWhere),\n    },\n    lexical: {\n      query: (terms, opts) => queryLexical(conn, terms, opts),\n    },\n    // The column's fixed DDL width (STORE_DIMS) is what every scan binds against, not the\n    // interface's per-call storeDims -- see vectors.ts's padded() for why a shorter vector is still correct against a wider column.\n    vectors: {\n      pending: () => pendingRows(conn),\n      writeVectors: (rows) => writeVectorBatch(conn, STORE_DIMS, rows),\n      candidates: (qv, _storeDims, fetch, allowed) => scanCandidates(conn, qv, STORE_DIMS, fetch, allowed),\n      similar: (path, opts) => scanSimilar(conn, STORE_DIMS, path, opts),\n      hasVector: (path) => hasVectorRow(conn, path),\n    },\n    async engineStatus() {\n      // Read back rather than recomputed: this is what open() actually set (3x the largest\n      // recorded reconcile, floored at 30s, capped at 10min). Turso's PRAGMA busy_timeout names its column \"busy_timeout\" (spike-verified), not \"timeout\" like real SQLite.\n      const row = (await (await db.prepare('PRAGMA busy_timeout')).get()) as { busy_timeout: number };\n      return { busy_timeout: `${row.busy_timeout}ms (derived: 3x the largest reconcile this cache has recorded, floored at 30000ms)` };\n    },\n    raw: {\n      async prepare(sql: string) {\n        const stmt = await db.prepare(rewriteFunctions(sql));\n        stmt.safeIntegers(true); // int64 past 2^53 arrives as BigInt instead of losing precision\n        return {\n          columns: () => stmt.columns(),\n          // sense sql streams through the client's own async generator.\n          iterate: async function* (...params: unknown[]) {\n            yield* stmt.iterate(...params);\n          },\n        };\n      },\n    },\n    async close() {\n      // Checkpoint before measuring: the last reconcile's pages sit in the WAL, not the file yet.\n      await checkpointWal(db);\n      let reclaimPath: string | null = null;\n      try {\n        const path = await cacheFilePath(conn);\n        const base = Number((await getMeta(conn, 'compact_size')) ?? '0');\n        const size = path === null ? null : await fileSize(path);\n        if (size !== null) {\n          // No baseline yet (cold build or an upgraded cache): record it, never reclaim here, so a\n          // cold build pays no VACUUM (PLAN 3.49 Track A) and an upgraded cache heals on a crossing.\n          if (base === 0) {\n            await setMeta(conn, 'compact_size', String(size));\n            // The meta write landed past the checkpoint; leave no WAL for the next opener.\n            await checkpointWal(db);\n          } else if (size > BLOAT_FACTOR * base) {\n            reclaimPath = path;\n          }\n        }\n      } catch (err) {\n        console.error(`sense: turso cache bloat check failed, the cache will keep its space until one succeeds: ${(err as Error).message}`);\n      }\n      await db.close();\n      // After this store's connection is closed, never before: turso hands the file to one\n      // connection at a time, and reclaimSpace opens its own to carry the `vacuum` flag (PLAN 3.54).\n      if (reclaimPath !== null) await reclaimSpace(reclaimPath);\n    },\n  };\n}\n"],"names":["CAPABILITIES","createStore","Set","BLOAT_FACTOR","db","conn","name","capabilities","exec","sql","prepare","runBatch","paramRows","transaction","fn","withTransaction","docs","columns","getColumns","fieldStats","scopeWhere","lexical","query","terms","opts","queryLexical","vectors","pending","pendingRows","writeVectors","rows","writeVectorBatch","STORE_DIMS","candidates","qv","_storeDims","fetch","allowed","scanCandidates","similar","path","scanSimilar","hasVector","hasVectorRow","engineStatus","row","get","busy_timeout","raw","stmt","rewriteFunctions","safeIntegers","iterate","params","close","reclaimPath","base","size","err","checkpointWal","cacheFilePath","getMeta","Number","fileSize","setMeta","String","console","error","message","reclaimSpace"],"mappings":"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"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/store/turso/store.ts"],"sourcesContent":["import type { Database } from '@tursodatabase/database';\nimport { STORE_DIMS } from '../../embed/types.ts';\nimport { getColumns, getMeta, setMeta } from '../shared.ts';\nimport { withTransaction } from '../transaction.ts';\nimport type { Capability, Connection, Statement, Store } from '../types.ts';\nimport { hasVectorRow, pendingRows } from '../vectors.ts';\nimport { cacheFilePath, checkpointWal, fileSize, reclaimSpace } from './connection.ts';\nimport { fieldStats } from './fieldStats.ts';\nimport { queryLexical } from './lexical.ts';\nimport { rewriteFunctions } from './sql-functions.ts';\nimport { scanCandidates, scanSimilar, writeVectorBatch } from './vectors.ts';\n\n// No 'segment': has()/basename() resolve via SQL rewrite below (sql-functions.ts), but segment() has no SQL form and the client cannot register it as a UDF.\nexport const CAPABILITIES: ReadonlySet<Capability> = new Set(['vectors']);\n\n// close() reclaims once the cache file outgrows its compact size by this factor: the disk\n// overhead a user should accept (PLAN 3.52), in postgres autovacuum scale-factor shape.\nconst BLOAT_FACTOR = 1.5;\n\n// Shares one Connection instance (conn) with the builder's own reconcile call so transaction depth\n// (see transaction.ts) is tracked against the same object everywhere.\nexport function createStore(db: Database, conn: Connection, options: { observational?: boolean } = {}): Store {\n  return {\n    name: 'turso',\n    capabilities: CAPABILITIES,\n    async exec(sql: string): Promise<void> {\n      await conn.exec(sql);\n    },\n    async prepare(sql: string): Promise<Statement> {\n      return conn.prepare(sql);\n    },\n    async runBatch(sql: string, paramRows: unknown[][]): Promise<void> {\n      await conn.runBatch(sql, paramRows);\n    },\n    async transaction<T>(fn: () => Promise<T>): Promise<T> {\n      return withTransaction(conn, fn);\n    },\n    docs: {\n      async columns() {\n        return [...(await getColumns(conn))];\n      },\n      fieldStats: (columns, scopeWhere) => fieldStats(conn, columns, scopeWhere),\n    },\n    lexical: {\n      query: (terms, opts) => queryLexical(conn, terms, opts),\n    },\n    // The column's fixed DDL width (STORE_DIMS) is what every scan binds against, not the\n    // interface's per-call storeDims -- see vectors.ts's padded() for why a shorter vector is still correct against a wider column.\n    vectors: {\n      pending: () => pendingRows(conn),\n      writeVectors: (rows) => writeVectorBatch(conn, STORE_DIMS, rows),\n      candidates: (qv, _storeDims, fetch, allowed) => scanCandidates(conn, qv, STORE_DIMS, fetch, allowed),\n      similar: (path, opts) => scanSimilar(conn, STORE_DIMS, path, opts),\n      hasVector: (path) => hasVectorRow(conn, path),\n    },\n    async engineStatus() {\n      // Read back rather than recomputed: this is what open() actually set (3x the largest\n      // recorded reconcile, floored at 30s, capped at 10min). Turso's PRAGMA busy_timeout names its column \"busy_timeout\" (spike-verified), not \"timeout\" like real SQLite.\n      const row = (await (await db.prepare('PRAGMA busy_timeout')).get()) as { busy_timeout: number };\n      return { busy_timeout: `${row.busy_timeout}ms (derived: 3x the largest reconcile this cache has recorded, floored at 30000ms)` };\n    },\n    raw: {\n      async prepare(sql: string) {\n        const stmt = await db.prepare(rewriteFunctions(sql));\n        stmt.safeIntegers(true); // int64 past 2^53 arrives as BigInt instead of losing precision\n        return {\n          columns: () => stmt.columns(),\n          // sense sql streams through the client's own async generator.\n          iterate: async function* (...params: unknown[]) {\n            yield* stmt.iterate(...params);\n          },\n        };\n      },\n    },\n    async close() {\n      if (options.observational) {\n        await db.close();\n        return;\n      }\n      // Checkpoint before measuring: the last reconcile's pages sit in the WAL, not the file yet.\n      await checkpointWal(db);\n      let reclaimPath: string | null = null;\n      try {\n        const path = await cacheFilePath(conn);\n        const base = Number((await getMeta(conn, 'compact_size')) ?? '0');\n        const size = path === null ? null : await fileSize(path);\n        if (size !== null) {\n          // No baseline yet (cold build or an upgraded cache): record it, never reclaim here, so a\n          // cold build pays no VACUUM (PLAN 3.49 Track A) and an upgraded cache heals on a crossing.\n          if (base === 0) {\n            await setMeta(conn, 'compact_size', String(size));\n            // The meta write landed past the checkpoint; leave no WAL for the next opener.\n            await checkpointWal(db);\n          } else if (size > BLOAT_FACTOR * base) {\n            reclaimPath = path;\n          }\n        }\n      } catch (err) {\n        console.error(`sense: turso cache bloat check failed, the cache will keep its space until one succeeds: ${(err as Error).message}`);\n      }\n      await db.close();\n      // After this store's connection is closed, never before: turso hands the file to one\n      // connection at a time, and reclaimSpace opens its own to carry the `vacuum` flag (PLAN 3.54).\n      if (reclaimPath !== null) await reclaimSpace(reclaimPath);\n    },\n  };\n}\n"],"names":["CAPABILITIES","createStore","Set","BLOAT_FACTOR","db","conn","options","name","capabilities","exec","sql","prepare","runBatch","paramRows","transaction","fn","withTransaction","docs","columns","getColumns","fieldStats","scopeWhere","lexical","query","terms","opts","queryLexical","vectors","pending","pendingRows","writeVectors","rows","writeVectorBatch","STORE_DIMS","candidates","qv","_storeDims","fetch","allowed","scanCandidates","similar","path","scanSimilar","hasVector","hasVectorRow","engineStatus","row","get","busy_timeout","raw","stmt","rewriteFunctions","safeIntegers","iterate","params","close","reclaimPath","base","size","err","observational","checkpointWal","cacheFilePath","getMeta","Number","fileSize","setMeta","String","console","error","message","reclaimSpace"],"mappings":"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"}

package/dist/cjs/store/types.d.cts

@@ -34,15 +34,24 @@ export interface OpenDialect<Handle> {
     filename: string;
     schemaVersion: string;
     reconcileDialect: ReconcileDialect;
-    connect(dbPath: string, cfg: ResolvedConfig): Promise<{
+    connect(dbPath: string, cfg: ResolvedConfig, options: {
+        existingOnly: boolean;
+        observational: boolean;
+    }): Promise<{
         handle: Handle;
         conn: Connection;
     }>;
-    close(handle: Handle): Promise<void>;
+    close(handle: Handle, options?: {
+        observational?: boolean;
+    }): Promise<void>;
     isLocked?(err: Error): boolean;
     ensureSchema(handle: Handle, conn: Connection, cfg: Config): Promise<void>;
     setDerivedBusyTimeout?(handle: Handle, conn: Connection, ms: number): Promise<void>;
-    createStore(handle: Handle, conn: Connection, cfg: ResolvedConfig): Store;
+    prepareLexical?(conn: Connection): Promise<void>;
+    assertLexicalReady?(conn: Connection): Promise<void>;
+    createStore(handle: Handle, conn: Connection, cfg: ResolvedConfig, options: {
+        observational: boolean;
+    }): Store;
 }
 export interface FieldStat {
     field: string;

package/dist/cjs/store/types.d.ts

@@ -34,15 +34,24 @@ export interface OpenDialect<Handle> {
     filename: string;
     schemaVersion: string;
     reconcileDialect: ReconcileDialect;
-    connect(dbPath: string, cfg: ResolvedConfig): Promise<{
+    connect(dbPath: string, cfg: ResolvedConfig, options: {
+        existingOnly: boolean;
+        observational: boolean;
+    }): Promise<{
         handle: Handle;
         conn: Connection;
     }>;
-    close(handle: Handle): Promise<void>;
+    close(handle: Handle, options?: {
+        observational?: boolean;
+    }): Promise<void>;
     isLocked?(err: Error): boolean;
     ensureSchema(handle: Handle, conn: Connection, cfg: Config): Promise<void>;
     setDerivedBusyTimeout?(handle: Handle, conn: Connection, ms: number): Promise<void>;
-    createStore(handle: Handle, conn: Connection, cfg: ResolvedConfig): Store;
+    prepareLexical?(conn: Connection): Promise<void>;
+    assertLexicalReady?(conn: Connection): Promise<void>;
+    createStore(handle: Handle, conn: Connection, cfg: ResolvedConfig, options: {
+        observational: boolean;
+    }): Store;
 }
 export interface FieldStat {
     field: string;

package/dist/cjs/store/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/store/types.ts"],"sourcesContent":["// The backing-store interface: a minimal portable statement surface (exec/prepare), plus\n// dedicated interfaces exactly where engines diverge (lexical index, vector scan, raw sql).\n\nimport type { Config, ResolvedConfig, StoreName } from '../config/index.ts';\nimport type { ReconcileDelta } from '../features/types.ts';\nimport type { ParsedDoc } from '../scan/index.ts';\n\n// 'vectors': the store's VectorStore is functionally implemented, not present-but-inert; checked\n// at open (index.ts) before a config with an \"embed\" block is allowed onto a store lacking it.\n// 'segment': the engine can run segment() (Intl.Segmenter grapheme clustering) as a SQL function;\n// turso's client cannot register it and has no rewrite for it, unlike has()/basename(), which now\n// work everywhere. An array, not a bare union, so a runtime check reads the same list the type does.\nexport const CAPABILITY_NAMES = ['vectors', 'segment'] as const;\nexport type Capability = (typeof CAPABILITY_NAMES)[number];\n\nexport interface RunResult {\n  changes: number | bigint;\n  lastInsertRowid: number | bigint;\n}\n\n// A prepared statement's async surface: every supported engine crosses a real async boundary\n// for a query (DuckDB has no synchronous client), so run/get/all return Promises.\nexport interface Statement {\n  run(...params: unknown[]): Promise<RunResult>;\n  get(...params: unknown[]): Promise<unknown>;\n  all(...params: unknown[]): Promise<unknown[]>;\n  iterate(...params: unknown[]): AsyncIterable<unknown>;\n  columns(): Array<{ name: string }>;\n  setReadBigInts(enabled: boolean): void;\n}\n\n// Connection surface feature-owned SQL runs against inside a store's hot loops (schema,\n// reconcile), portable so a feature never imports an engine-specific client type.\nexport interface Connection {\n  exec(sql: string): Promise<void>;\n  prepare(sql: string): Promise<Statement>;\n  runBatch(sql: string, paramRows: unknown[][]): Promise<void>;\n  // Bulk-inserts rows that cannot conflict, through a path that binds no per-value parameters.\n  // Optional: a store that has nothing faster than its own INSERT omits it and callers fall back\n  // (appendRows in shared.ts). `columns` names the values each row carries; a table column the\n  // caller does not write takes its default.\n  appendRows?(table: string, columns: string[], rows: unknown[][]): Promise<void>;\n}\n\n// One reconcile algorithm (src/store/reconcile.ts), parameterised per engine. reconcileContent is\n// the load-bearing member: it lands every content-table change and owns its own multi-step\n// strategy (sqlite FTS5 incremental, duckdb combined delete/insert, turso incremental-or-rebuild).\nexport interface ReconcileDialect {\n  // BEGIN mode for the whole reconcile: sqlite/turso 'BEGIN IMMEDIATE', duckdb 'BEGIN'.\n  beginMode(): string;\n  // Throws SenseError('COLUMN_LIMIT', ...) past this store's own column ceiling and reasoning.\n  checkColumnLimit(count: number): void;\n  // Adds `names` to frontmatter, already filtered to columns this connection doesn't have yet.\n  // sqlite/turso loop (their ADD COLUMN is metadata-only); duckdb issues one statement per call.\n  addColumns(conn: Connection, names: string[]): Promise<void>;\n  // Deletes content rows for `touched`, inserts rows for `docs`; `delta` carries the tree state a\n  // strategy may need. Must not open its own transaction, and must not return before its own\n  // multi-step strategy (e.g. turso's DROP/rebuild) completes.\n  reconcileContent(conn: Connection, touched: string[], docs: ParsedDoc[], delta: ReconcileDelta, cfg: Config): Promise<void>;\n  // Records this reconcile's write-transaction duration. sqlite/turso use it for open()'s derived\n  // busy_timeout; duckdb has no such PRAGMA and omits it.\n  recordDuration?(conn: Connection, ms: number): Promise<void>;\n}\n\n// One open algorithm (src/store/open.ts), parameterised per engine. `Handle` is whatever this\n// store needs to close the connection and construct its Store (sqlite: {db}; duckdb:\n// {instance, duckdb}; turso: db) -- opaque to the shared orchestration, threaded through unchanged.\nexport interface OpenDialect<Handle> {\n  // Cache filename under STATE_DIR, e.g. 'cache.db'.\n  filename: string;\n  // Cache shape version, independent of the config's own `version`; bumping it rebuilds an existing tree.\n  schemaVersion: string;\n  reconcileDialect: ReconcileDialect;\n  // Opens the physical connection and applies pragmas due before any SQL runs (sqlite: busy_timeout\n  // + WAL; turso: connect-time timeout; duckdb: none).\n  connect(dbPath: string, cfg: ResolvedConfig): Promise<{ handle: Handle; conn: Connection }>;\n  // Releases the handle, for both the rebuild-and-reopen branch and error cleanup on this attempt.\n  close(handle: Handle): Promise<void>;\n  // True when connect() failed because another process holds the cache file, which the orchestration\n  // retries. Each engine words it differently, so the match is the dialect's own (`native-not-emulated`).\n  // Absent for sqlite, whose file lock is shared and whose concurrent-open failure is a different defect.\n  // Matching on message text is forced, not chosen: measured 2026-09-02, duckdb throws a plain Error\n  // whose only own properties are stack and message, and turso sets code to the constant\n  // 'GenericFailure' on every failure alike with rawCode undefined. Neither exposes anything a\n  // predicate could switch on, so each dialect pins its engine's wordings and unit-tests them.\n  isLocked?(err: Error): boolean;\n  // Schema DDL beyond frontmatter/preset_files/meta (content table, feature hooks); sole owner of\n  // whether it wraps itself in a write transaction (sqlite: yes, guards a cold-open ALTER race; duckdb/turso: no).\n  ensureSchema(handle: Handle, conn: Connection, cfg: Config): Promise<void>;\n  // Installs the derived busy_timeout PRAGMA right before reconcile (sqlite/turso); absent for\n  // duckdb, which has no such PRAGMA.\n  setDerivedBusyTimeout?(handle: Handle, conn: Connection, ms: number): Promise<void>;\n  createStore(handle: Handle, conn: Connection, cfg: ResolvedConfig): Store;\n}\n\nexport interface FieldStat {\n  field: string;\n  coverage: number;\n  type: string;\n}\n\nexport interface DocumentStore {\n  // Frontmatter column names (including internal ones; callers filter).\n  columns(): Promise<string[]>;\n  // Per-column coverage (non-null count) and observed type set, aggregated in one SQL query,\n  // never one row per note. `scopeWhere` is a caller-built WHERE fragment, per LexicalQueryOptions.\n  fieldStats(columns: string[], scopeWhere: string): Promise<FieldStat[]>;\n}\n\n// A ranked match, nothing more. Snippets are cut from the document above the store\n// (commands/search.ts), identically for every engine, so no store carries them.\nexport interface LexicalHit {\n  path: string;\n}\n\nexport interface LexicalQueryOptions {\n  whereJoin: string;\n  whereCond: string;\n  scopeCond: string;\n  limit: number;\n}\n\nexport interface LexicalIndex {\n  // Ranked word-match query with snippet, scoped by the caller-built SQL fragments (the same\n  // fragments narrowByWhere/materializeScope produce elsewhere).\n  query(terms: string, opts: LexicalQueryOptions): Promise<LexicalHit[]>;\n}\n\nexport interface VectorCandidate {\n  path: string;\n  lines: string;\n  similarity: number;\n}\n\nexport interface VectorSimilar {\n  path: string;\n  similarity: number;\n}\n\nexport interface VectorWriteRow {\n  path: string;\n  chunk: number;\n  scale: number;\n  vector: Buffer;\n}\n\nexport interface VectorStore {\n  // Rows whose vector is NULL: never embedded, or added since.\n  pending(): Promise<Array<{ path: string; chunk: number }>>;\n  // One batch write per call (never per row) so a provider's embedding batch stays inside a\n  // single store method.\n  writeVectors(rows: VectorWriteRow[]): Promise<void>;\n  candidates(queryVector: Float32Array, storeDims: number, fetch: number, allowed?: Set<string>): Promise<VectorCandidate[]>;\n  similar(path: string, opts: { exclude: Set<string>; allowed?: Set<string>; k: number }): Promise<VectorSimilar[]>;\n  hasVector(path: string): Promise<boolean>;\n}\n\n// The `sense sql` passthrough: string in, streamed rows out. Each store registers the same\n// sense-supplied functions and applies its own read-bigints/error-translation behavior.\nexport interface RawStatement {\n  columns(): Array<{ name: string }>;\n  iterate(...params: unknown[]): AsyncIterable<unknown>;\n}\n\nexport interface SqlSession {\n  prepare(sql: string): Promise<RawStatement>;\n}\n\nexport interface Store {\n  readonly name: StoreName;\n  readonly capabilities: ReadonlySet<Capability>;\n  exec(sql: string): Promise<void>;\n  prepare(sql: string): Promise<Statement>;\n  // One crossing, N rows: every external write loop (search's candidate insert, graph ring's\n  // temp-table writes) goes through this instead of looping over `run()`. Same contract as Connection.runBatch.\n  runBatch(sql: string, paramRows: unknown[][]): Promise<void>;\n  // Pins one snapshot across multi-statement reads; `map` and `peek` use it. A network-bound\n  // write (search's embedding top-up) must stay outside it. Nesting joins the enclosing transaction.\n  transaction<T>(fn: () => Promise<T>): Promise<T>;\n  docs: DocumentStore;\n  lexical: LexicalIndex;\n  vectors: VectorStore;\n  raw: SqlSession;\n  // Engine-level facts for `sense status` (e.g. a derived busy_timeout PRAGMA reading); each\n  // store owns what it reports and how it is worded. Empty when there is nothing to report.\n  engineStatus(): Promise<Record<string, string>>;\n  close(): Promise<void>;\n}\n"],"names":["CAPABILITY_NAMES"],"mappings":"AAAA,yFAAyF;AACzF,4FAA4F;;;;;+BAW/EA;;;eAAAA;;;AAAN,IAAMA,mBAAmB;IAAC;IAAW;CAAU"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/store/types.ts"],"sourcesContent":["// The backing-store interface: a minimal portable statement surface (exec/prepare), plus\n// dedicated interfaces exactly where engines diverge (lexical index, vector scan, raw sql).\n\nimport type { Config, ResolvedConfig, StoreName } from '../config/index.ts';\nimport type { ReconcileDelta } from '../features/types.ts';\nimport type { ParsedDoc } from '../scan/index.ts';\n\n// 'vectors': the store's VectorStore is functionally implemented, not present-but-inert; checked\n// at open (index.ts) before a config with an \"embed\" block is allowed onto a store lacking it.\n// 'segment': the engine can run segment() (Intl.Segmenter grapheme clustering) as a SQL function;\n// turso's client cannot register it and has no rewrite for it, unlike has()/basename(), which now\n// work everywhere. An array, not a bare union, so a runtime check reads the same list the type does.\nexport const CAPABILITY_NAMES = ['vectors', 'segment'] as const;\nexport type Capability = (typeof CAPABILITY_NAMES)[number];\n\nexport interface RunResult {\n  changes: number | bigint;\n  lastInsertRowid: number | bigint;\n}\n\n// A prepared statement's async surface: every supported engine crosses a real async boundary\n// for a query (DuckDB has no synchronous client), so run/get/all return Promises.\nexport interface Statement {\n  run(...params: unknown[]): Promise<RunResult>;\n  get(...params: unknown[]): Promise<unknown>;\n  all(...params: unknown[]): Promise<unknown[]>;\n  iterate(...params: unknown[]): AsyncIterable<unknown>;\n  columns(): Array<{ name: string }>;\n  setReadBigInts(enabled: boolean): void;\n}\n\n// Connection surface feature-owned SQL runs against inside a store's hot loops (schema,\n// reconcile), portable so a feature never imports an engine-specific client type.\nexport interface Connection {\n  exec(sql: string): Promise<void>;\n  prepare(sql: string): Promise<Statement>;\n  runBatch(sql: string, paramRows: unknown[][]): Promise<void>;\n  // Bulk-inserts rows that cannot conflict, through a path that binds no per-value parameters.\n  // Optional: a store that has nothing faster than its own INSERT omits it and callers fall back\n  // (appendRows in shared.ts). `columns` names the values each row carries; a table column the\n  // caller does not write takes its default.\n  appendRows?(table: string, columns: string[], rows: unknown[][]): Promise<void>;\n}\n\n// One reconcile algorithm (src/store/reconcile.ts), parameterised per engine. reconcileContent is\n// the load-bearing member: it lands every content-table change and owns its own multi-step\n// strategy (sqlite FTS5 incremental, duckdb combined delete/insert, turso incremental-or-rebuild).\nexport interface ReconcileDialect {\n  // BEGIN mode for the whole reconcile: sqlite/turso 'BEGIN IMMEDIATE', duckdb 'BEGIN'.\n  beginMode(): string;\n  // Throws SenseError('COLUMN_LIMIT', ...) past this store's own column ceiling and reasoning.\n  checkColumnLimit(count: number): void;\n  // Adds `names` to frontmatter, already filtered to columns this connection doesn't have yet.\n  // sqlite/turso loop (their ADD COLUMN is metadata-only); duckdb issues one statement per call.\n  addColumns(conn: Connection, names: string[]): Promise<void>;\n  // Deletes content rows for `touched`, inserts rows for `docs`; `delta` carries the tree state a\n  // strategy may need. Must not open its own transaction, and must not return before its own\n  // multi-step strategy (e.g. turso's DROP/rebuild) completes.\n  reconcileContent(conn: Connection, touched: string[], docs: ParsedDoc[], delta: ReconcileDelta, cfg: Config): Promise<void>;\n  // Records this reconcile's write-transaction duration. sqlite/turso use it for open()'s derived\n  // busy_timeout; duckdb has no such PRAGMA and omits it.\n  recordDuration?(conn: Connection, ms: number): Promise<void>;\n}\n\n// One open algorithm (src/store/open.ts), parameterised per engine. `Handle` is whatever this\n// store needs to close the connection and construct its Store (sqlite: {db}; duckdb:\n// {instance, duckdb}; turso: db) -- opaque to the shared orchestration, threaded through unchanged.\nexport interface OpenDialect<Handle> {\n  // Cache filename under STATE_DIR, e.g. 'cache.db'.\n  filename: string;\n  // Cache shape version, independent of the config's own `version`; bumping it rebuilds an existing tree.\n  schemaVersion: string;\n  reconcileDialect: ReconcileDialect;\n  // Opens the physical connection and applies pragmas due before any SQL runs (sqlite: busy_timeout\n  // + WAL; turso: connect-time timeout; duckdb: none).\n  connect(dbPath: string, cfg: ResolvedConfig, options: { existingOnly: boolean; observational: boolean }): Promise<{ handle: Handle; conn: Connection }>;\n  // Releases the handle, for both the rebuild-and-reopen branch and error cleanup on this attempt.\n  close(handle: Handle, options?: { observational?: boolean }): Promise<void>;\n  // True when connect() failed because another process holds the cache file, which the orchestration\n  // retries. Each engine words it differently, so the match is the dialect's own (`native-not-emulated`).\n  // Absent for sqlite, whose file lock is shared and whose concurrent-open failure is a different defect.\n  // Matching on message text is forced, not chosen: measured 2026-09-02, duckdb throws a plain Error\n  // whose only own properties are stack and message, and turso sets code to the constant\n  // 'GenericFailure' on every failure alike with rawCode undefined. Neither exposes anything a\n  // predicate could switch on, so each dialect pins its engine's wordings and unit-tests them.\n  isLocked?(err: Error): boolean;\n  // Schema DDL beyond frontmatter/preset_files/meta (content table, feature hooks); sole owner of\n  // whether it wraps itself in a write transaction (sqlite: yes, guards a cold-open ALTER race; duckdb/turso: no).\n  ensureSchema(handle: Handle, conn: Connection, cfg: Config): Promise<void>;\n  // Installs the derived busy_timeout PRAGMA right before reconcile (sqlite/turso); absent for\n  // duckdb, which has no such PRAGMA.\n  setDerivedBusyTimeout?(handle: Handle, conn: Connection, ms: number): Promise<void>;\n  // Persistent lexical preparation belongs to build, while no-build calls only the readiness\n  // check. SQLite and Turso maintain lexical state during reconcile and omit both hooks.\n  prepareLexical?(conn: Connection): Promise<void>;\n  assertLexicalReady?(conn: Connection): Promise<void>;\n  createStore(handle: Handle, conn: Connection, cfg: ResolvedConfig, options: { observational: boolean }): Store;\n}\n\nexport interface FieldStat {\n  field: string;\n  coverage: number;\n  type: string;\n}\n\nexport interface DocumentStore {\n  // Frontmatter column names (including internal ones; callers filter).\n  columns(): Promise<string[]>;\n  // Per-column coverage (non-null count) and observed type set, aggregated in one SQL query,\n  // never one row per note. `scopeWhere` is a caller-built WHERE fragment, per LexicalQueryOptions.\n  fieldStats(columns: string[], scopeWhere: string): Promise<FieldStat[]>;\n}\n\n// A ranked match, nothing more. Snippets are cut from the document above the store\n// (commands/search.ts), identically for every engine, so no store carries them.\nexport interface LexicalHit {\n  path: string;\n}\n\nexport interface LexicalQueryOptions {\n  whereJoin: string;\n  whereCond: string;\n  scopeCond: string;\n  limit: number;\n}\n\nexport interface LexicalIndex {\n  // Ranked word-match query with snippet, scoped by the caller-built SQL fragments (the same\n  // fragments narrowByWhere/materializeScope produce elsewhere).\n  query(terms: string, opts: LexicalQueryOptions): Promise<LexicalHit[]>;\n}\n\nexport interface VectorCandidate {\n  path: string;\n  lines: string;\n  similarity: number;\n}\n\nexport interface VectorSimilar {\n  path: string;\n  similarity: number;\n}\n\nexport interface VectorWriteRow {\n  path: string;\n  chunk: number;\n  scale: number;\n  vector: Buffer;\n}\n\nexport interface VectorStore {\n  // Rows whose vector is NULL: never embedded, or added since.\n  pending(): Promise<Array<{ path: string; chunk: number }>>;\n  // One batch write per call (never per row) so a provider's embedding batch stays inside a\n  // single store method.\n  writeVectors(rows: VectorWriteRow[]): Promise<void>;\n  candidates(queryVector: Float32Array, storeDims: number, fetch: number, allowed?: Set<string>): Promise<VectorCandidate[]>;\n  similar(path: string, opts: { exclude: Set<string>; allowed?: Set<string>; k: number }): Promise<VectorSimilar[]>;\n  hasVector(path: string): Promise<boolean>;\n}\n\n// The `sense sql` passthrough: string in, streamed rows out. Each store registers the same\n// sense-supplied functions and applies its own read-bigints/error-translation behavior.\nexport interface RawStatement {\n  columns(): Array<{ name: string }>;\n  iterate(...params: unknown[]): AsyncIterable<unknown>;\n}\n\nexport interface SqlSession {\n  prepare(sql: string): Promise<RawStatement>;\n}\n\nexport interface Store {\n  readonly name: StoreName;\n  readonly capabilities: ReadonlySet<Capability>;\n  exec(sql: string): Promise<void>;\n  prepare(sql: string): Promise<Statement>;\n  // One crossing, N rows: every external write loop (search's candidate insert, graph ring's\n  // temp-table writes) goes through this instead of looping over `run()`. Same contract as Connection.runBatch.\n  runBatch(sql: string, paramRows: unknown[][]): Promise<void>;\n  // Pins one snapshot across multi-statement reads; `map` and `peek` use it. A network-bound\n  // write (search's embedding top-up) must stay outside it. Nesting joins the enclosing transaction.\n  transaction<T>(fn: () => Promise<T>): Promise<T>;\n  docs: DocumentStore;\n  lexical: LexicalIndex;\n  vectors: VectorStore;\n  raw: SqlSession;\n  // Engine-level facts for `sense status` (e.g. a derived busy_timeout PRAGMA reading); each\n  // store owns what it reports and how it is worded. Empty when there is nothing to report.\n  engineStatus(): Promise<Record<string, string>>;\n  close(): Promise<void>;\n}\n"],"names":["CAPABILITY_NAMES"],"mappings":"AAAA,yFAAyF;AACzF,4FAA4F;;;;;+BAW/EA;;;eAAAA;;;AAAN,IAAMA,mBAAmB;IAAC;IAAW;CAAU"}

package/dist/cjs/watch.js

@@ -40,12 +40,38 @@ function _async_to_generator(fn) {
         });
     };
 }
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else obj[key] = value;
+    return obj;
+}
 function _instanceof(left, right) {
     "@swc/helpers - instanceof";
     if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
         return !!right[Symbol.hasInstance](left);
     } else return left instanceof right;
 }
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property(target, key, source[key]);
+        });
+    }
+    return target;
+}
 function _ts_generator(thisArg, body) {
     var f, y, t, _ = {
         label: 0,
@@ -145,11 +171,12 @@ function _ts_generator(thisArg, body) {
         };
     }
 }
-// Watch is a cache pre-warmer, not a correctness mechanism: open() always reconciles anyway, so any fs event just triggers a debounced full reconcile.
+// Watch prepares the index for snapshot queries; filesystem events request debounced builds
+// and periodic reconciliation recovers missed notifications.
 var DEBOUNCE_MS = 200;
 function runWatch(_0) {
     return _async_to_generator(function(cfg) {
-        var opts, _opts_onEvent, _opts_debounceMs, _opts_heartbeatIntervalMs, _cfg_rootDir, _cfg_configDir, _opts_force, onEvent, debounceMs, reconcileIntervalMs, claimIntervalMs, rootDir, configDir, claimFailure, requestShutdown, claim, claimCloseStarted, closeClaim, _ref, initialStore, dbPath, initialWarnings, initialParsed, initialTotal, _tmp, stopping, running, queuedAlways, tick, startCycle, requestCycle, debounceTimer, scheduleReconcile, watcher, reconcileTimer, err, closeError;
+        var opts, _opts_onEvent, _opts_debounceMs, _opts_heartbeatIntervalMs, _cfg_rootDir, _cfg_configDir, _opts_force, onEvent, debounceMs, reconcileIntervalMs, claimIntervalMs, rootDir, configDir, claimFailure, requestShutdown, claim, claimCloseStarted, closeClaim, watcher, startup, startupNotification, scheduleReconcile, stopping, _opts_signal, startupEvents, _ref, initialStore, dbPath, initialWarnings, initialParsed, initialTotal, _tmp, _ref1, store, parsed, warnings, _, _tmp1, running, queuedAlways, tick, startCycle, requestCycle, debounceTimer, reconcileTimer, err, closeError;
         var _arguments = arguments;
         return _ts_generator(this, function(_state) {
             switch(_state.label){
@@ -178,14 +205,31 @@ function runWatch(_0) {
                         claimCloseStarted = true;
                         return claim.close();
                     };
+                    startup = true;
+                    startupNotification = false;
+                    stopping = false;
                     _state.label = 2;
                 case 2:
                     _state.trys.push([
                         2,
-                        12,
-                        17,
-                        18
+                        22,
+                        27,
+                        28
                     ]);
+                    // 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 = (0, _nodefs.watch)(rootDir, {
+                        recursive: true
+                    }, function(_event, filename) {
+                        if (!(0, _watchnotificationts.shouldReconcileWatchNotification)(filename)) return;
+                        if (startup) startupNotification = true;
+                        else scheduleReconcile === null || scheduleReconcile === void 0 ? void 0 : scheduleReconcile();
+                    });
+                    watcher.on('error', function(err) {
+                        claimFailure !== null && claimFailure !== void 0 ? claimFailure : claimFailure = err;
+                        requestShutdown === null || requestShutdown === void 0 ? void 0 : requestShutdown(err);
+                    });
+                    startupEvents = [];
                     return [
                         4,
                         (0, _indexts.openStore)(cfg)
@@ -237,7 +281,71 @@ function runWatch(_0) {
                     ];
                 case 10:
                     if (claimFailure) throw claimFailure;
-                    stopping = false;
+                    startupEvents.push({
+                        parsed: initialParsed,
+                        total: initialTotal,
+                        warnings: initialWarnings
+                    });
+                    _state.label = 11;
+                case 11:
+                    startupNotification = false;
+                    return [
+                        4,
+                        (0, _indexts.openStore)(cfg)
+                    ];
+                case 12:
+                    _ref1 = _state.sent(), store = _ref1.store, parsed = _ref1.parsed, warnings = _ref1.warnings;
+                    _state.label = 13;
+                case 13:
+                    _state.trys.push([
+                        13,
+                        ,
+                        16,
+                        18
+                    ]);
+                    if (!(parsed > 0 || warnings.length > 0)) return [
+                        3,
+                        15
+                    ];
+                    _ = startupEvents.push;
+                    _tmp1 = {
+                        parsed: parsed
+                    };
+                    return [
+                        4,
+                        (0, _indexts.docCount)(store)
+                    ];
+                case 14:
+                    _.apply(startupEvents, [
+                        (_tmp1.total = _state.sent(), _tmp1.warnings = warnings, _tmp1)
+                    ]);
+                    _state.label = 15;
+                case 15:
+                    return [
+                        3,
+                        18
+                    ];
+                case 16:
+                    return [
+                        4,
+                        store.close()
+                    ];
+                case 17:
+                    _state.sent();
+                    return [
+                        7
+                    ];
+                case 18:
+                    if (claimFailure) throw claimFailure;
+                    _state.label = 19;
+                case 19:
+                    if (startupNotification && !((_opts_signal = opts.signal) === null || _opts_signal === void 0 ? void 0 : _opts_signal.aborted)) return [
+                        3,
+                        11
+                    ];
+                    _state.label = 20;
+                case 20:
+                    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.
                     running = null;
@@ -342,6 +450,8 @@ function runWatch(_0) {
                         startCycle(alwaysEmit);
                     };
                     debounceTimer = null;
+                    // Ignore our own state files, or cache and claim writes would retrigger reconciliation forever.
+                    // An unresolvable filename reconciles because parsing nothing costs less than missing a real edit.
                     scheduleReconcile = function scheduleReconcile() {
                         if (debounceTimer) clearTimeout(debounceTimer);
                         debounceTimer = setTimeout(function() {
@@ -349,14 +459,6 @@ function runWatch(_0) {
                             requestCycle(true);
                         }, debounceMs);
                     };
-                    // Ignore our own state files, or cache and claim writes would retrigger reconciliation forever.
-                    // An unresolvable filename reconciles because parsing nothing costs less than missing a real edit.
-                    watcher = (0, _nodefs.watch)(rootDir, {
-                        recursive: true
-                    }, function(_event, filename) {
-                        if (!(0, _watchnotificationts.shouldReconcileWatchNotification)(filename)) return;
-                        scheduleReconcile();
-                    });
                     reconcileTimer = setInterval((0, _guardedtickts.guardedTick)(function() {
                         return _async_to_generator(function() {
                             return _ts_generator(this, function(_state) {
@@ -389,7 +491,7 @@ function runWatch(_0) {
                                                     (_opts_signal = opts.signal) === null || _opts_signal === void 0 ? void 0 : _opts_signal.removeEventListener('abort', stopNormally);
                                                     clearInterval(reconcileTimer);
                                                     if (debounceTimer) clearTimeout(debounceTimer);
-                                                    watcher.close();
+                                                    watcher === null || watcher === void 0 ? void 0 : watcher.close();
                                                     return [
                                                         4,
                                                         running
@@ -488,13 +590,30 @@ function runWatch(_0) {
                                         rootDir: rootDir,
                                         dbPath: dbPath
                                     });
-                                    if (!stopping && (initialWarnings.length > 0 || initialParsed > 0)) {
-                                        onEvent({
-                                            type: 'reconciled',
-                                            parsed: initialParsed,
-                                            total: initialTotal,
-                                            warnings: initialWarnings
-                                        });
+                                    if (!stopping) {
+                                        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                                        try {
+                                            for(var _iterator = startupEvents[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                                                var event = _step.value;
+                                                if (stopping) break;
+                                                if (event.warnings.length > 0 || event.parsed > 0) onEvent(_object_spread({
+                                                    type: 'reconciled'
+                                                }, event));
+                                            }
+                                        } catch (err) {
+                                            _didIteratorError = true;
+                                            _iteratorError = err;
+                                        } finally{
+                                            try {
+                                                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                                    _iterator.return();
+                                                }
+                                            } finally{
+                                                if (_didIteratorError) {
+                                                    throw _iteratorError;
+                                                }
+                                            }
+                                        }
                                     }
                                 } catch (err) {
                                     shutdown(_instanceof(err, Error) ? err : new Error(String(err)));
@@ -502,46 +621,47 @@ function runWatch(_0) {
                             }
                         })
                     ];
-                case 11:
+                case 21:
                     return [
                         2,
                         _state.sent()
                     ];
-                case 12:
+                case 22:
                     err = _state.sent();
+                    watcher === null || watcher === void 0 ? void 0 : watcher.close();
                     if (claimCloseStarted) throw err;
-                    _state.label = 13;
-                case 13:
+                    _state.label = 23;
+                case 23:
                     _state.trys.push([
-                        13,
-                        15,
+                        23,
+                        25,
                         ,
-                        16
+                        26
                     ]);
                     return [
                         4,
                         closeClaim()
                     ];
-                case 14:
+                case 24:
                     _state.sent();
                     return [
                         3,
-                        16
+                        26
                     ];
-                case 15:
+                case 25:
                     closeError = _state.sent();
                     throw new AggregateError([
                         err,
                         closeError
                     ], 'watch setup and claim cleanup both failed');
-                case 16:
+                case 26:
                     throw err;
-                case 17:
+                case 27:
                     requestShutdown = undefined;
                     return [
                         7
                     ];
-                case 18:
+                case 28:
                     return [
                         2
                     ];