@mulmoclaude/core 0.28.0 → 0.30.0

package/dist/collection/server/index.cjs

@@ -1,8 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_ids = require("../../ids-DWmHjm17.cjs");
-const require_discovery = require("../../discovery-BKovdRpZ.cjs");
+const require_discovery = require("../../discovery-Bklck7Ck.cjs");
 const require_templatePath = require("../../templatePath-27vUZowm.cjs");
-const require_server = require("../../server-rRQkNBvO.cjs");
+const require_server = require("../../server-BOiz_HDi.cjs");
+exports.BackendUnavailableError = require_discovery.BackendUnavailableError;
 exports.COMPUTED_TYPES = require_ids.COMPUTED_TYPES;
 exports.CollectionQueryZ = require_discovery.CollectionQueryZ;
 exports.CollectionSchemaZ = require_discovery.CollectionSchemaZ;
@@ -40,6 +41,7 @@ exports.firstMutateParamProblem = require_server.firstMutateParamProblem;
 exports.formatCivil = require_server.formatCivil;
 exports.generateItemId = require_discovery.generateItemId;
 exports.getWorkspaceRoot = require_discovery.getWorkspaceRoot;
+exports.isBackendUnavailable = require_discovery.isBackendUnavailable;
 exports.isContainedInRoot = require_discovery.isContainedInRoot;
 exports.isContainedInWorkspace = require_discovery.isContainedInWorkspace;
 exports.isRegularFile = require_discovery.isRegularFile;

package/dist/collection/server/index.d.ts

@@ -4,6 +4,7 @@ export * from './paths';
 export * from './templatePath';
 export * from './io';
 export * from './store';
+export { BackendUnavailableError, isBackendUnavailable } from './backendAvailability';
 export { MAX_CSV_ROWS, encodeCsvRecordId, decodeCsvRecordId, normalizeCsvValue, csvRowToItem, dedupeByRecordId } from './csvStore';
 export { compileCsvQuery, compileJsonlQuery } from './csvQuery';
 export { runQueryOverRows } from './jsonlQuery';

package/dist/collection/server/index.js

@@ -1,5 +1,5 @@
 import { o as COMPUTED_TYPES } from "../../ids-D1M1T6KJ.js";
-import { A as generateItemId, C as compileJsonlQuery, D as buildActionSeedPrompt, E as MAX_QUERY_ROWS, F as readCustomViewI18n, G as resolveDataDir, H as isContainedInRoot, I as readItem, J as safeSlugName, K as resolveTemplatePath, L as readSkillTemplate, M as listItems, N as promptPathsFor, O as buildCollectionActionSeedPrompt, P as readCustomViewHtml, Q as getWorkspaceRoot, R as resolveCreateItemId, S as compileCsvQuery, T as DEFAULT_QUERY_ROWS, U as isContainedInWorkspace, V as SCHEMA_FILE, W as itemFilePath, Z as configureCollectionHost, _ as decodeCsvRecordId, a as toSummary, b as normalizeCsvValue, c as collectionWritable, et as log, f as pageFromFullRead, g as csvRowToItem, i as toDetail, j as isRegularFile, k as deleteItem, l as readOnlyRefusal, m as MAX_CSV_ROWS, n as discoverCollections, nt as setCollectionChangePublisher, o as CollectionSchemaZ, p as projectItemFields, q as safeRecordId, r as loadCollection, t as acceptParsedSchema, tt as publishCollectionChange, u as storeFor, v as dedupeByRecordId, w as CollectionQueryZ, y as encodeCsvRecordId, z as writeItem } from "../../discovery-BVdCgBFN.js";
+import { $ as configureCollectionHost, A as buildCollectionActionSeedPrompt, B as resolveCreateItemId, C as compileJsonlQuery, D as BackendUnavailableError, E as MAX_QUERY_ROWS, F as promptPathsFor, G as isContainedInWorkspace, I as readCustomViewHtml, J as resolveTemplatePath, K as itemFilePath, L as readCustomViewI18n, M as generateItemId, N as isRegularFile, O as isBackendUnavailable, P as listItems, R as readItem, S as compileCsvQuery, T as DEFAULT_QUERY_ROWS, U as SCHEMA_FILE, V as writeItem, W as isContainedInRoot, X as safeSlugName, Y as safeRecordId, _ as decodeCsvRecordId, a as toSummary, b as normalizeCsvValue, c as collectionWritable, et as getWorkspaceRoot, f as pageFromFullRead, g as csvRowToItem, i as toDetail, it as setCollectionChangePublisher, j as deleteItem, k as buildActionSeedPrompt, l as readOnlyRefusal, m as MAX_CSV_ROWS, n as discoverCollections, nt as log, o as CollectionSchemaZ, p as projectItemFields, q as resolveDataDir, r as loadCollection, rt as publishCollectionChange, t as acceptParsedSchema, u as storeFor, v as dedupeByRecordId, w as CollectionQueryZ, y as encodeCsvRecordId, z as readSkillTemplate } from "../../discovery-BbsJwVEq.js";
 import { i as isSafeTemplatePath, n as isSafeCustomViewI18nPath, r as isSafeCustomViewPath, t as isSafeActionTemplatePath } from "../../templatePath-k_WNbL_Q.js";
-import { C as validateRecordObject, D as enrichItems, E as runCollectionQuery, O as runQueryOverRows, S as validateCollectionRecords, T as recordFieldProblem, _ as computeCollectionIcon, a as deleteCollection, b as applyMutateAction, c as computeSuccessor, d as isTriggerDue, f as maybeSpawnSuccessor, h as successorId, i as deleteCustomView, l as daysInMonth, m as resolveEvery, n as MAX_UNSELECTIVE_ITEMS, o as deleteCollectionRefusalMessage, p as parseCivil, r as makeManageCollectionTool, s as advanceTriggerDate, t as MAX_SCHEMA_ISSUES, u as formatCivil, v as buildWorkspaceOntology, w as compileRecordZ, x as firstMutateParamProblem, y as schemaRelations } from "../../server-B8mvfZSF.js";
-export { COMPUTED_TYPES, CollectionQueryZ, CollectionSchemaZ, DEFAULT_QUERY_ROWS, MAX_CSV_ROWS, MAX_QUERY_ROWS, MAX_SCHEMA_ISSUES, MAX_UNSELECTIVE_ITEMS, SCHEMA_FILE, acceptParsedSchema, advanceTriggerDate, applyMutateAction, buildActionSeedPrompt, buildCollectionActionSeedPrompt, buildWorkspaceOntology, collectionWritable, compileCsvQuery, compileJsonlQuery, compileRecordZ, computeCollectionIcon, computeSuccessor, configureCollectionHost, csvRowToItem, daysInMonth, decodeCsvRecordId, dedupeByRecordId, deleteCollection, deleteCollectionRefusalMessage, deleteCustomView, deleteItem, discoverCollections, encodeCsvRecordId, enrichItems, firstMutateParamProblem, formatCivil, generateItemId, getWorkspaceRoot, isContainedInRoot, isContainedInWorkspace, isRegularFile, isSafeActionTemplatePath, isSafeCustomViewI18nPath, isSafeCustomViewPath, isSafeTemplatePath, isTriggerDue, itemFilePath, listItems, loadCollection, log, makeManageCollectionTool, maybeSpawnSuccessor, normalizeCsvValue, pageFromFullRead, parseCivil, projectItemFields, promptPathsFor, publishCollectionChange, readCustomViewHtml, readCustomViewI18n, readItem, readOnlyRefusal, readSkillTemplate, recordFieldProblem, resolveCreateItemId, resolveDataDir, resolveEvery, resolveTemplatePath, runCollectionQuery, runQueryOverRows, safeRecordId, safeSlugName, schemaRelations, setCollectionChangePublisher, storeFor, successorId, toDetail, toSummary, validateCollectionRecords, validateRecordObject, writeItem };
+import { C as validateRecordObject, D as enrichItems, E as runCollectionQuery, O as runQueryOverRows, S as validateCollectionRecords, T as recordFieldProblem, _ as computeCollectionIcon, a as deleteCollection, b as applyMutateAction, c as computeSuccessor, d as isTriggerDue, f as maybeSpawnSuccessor, h as successorId, i as deleteCustomView, l as daysInMonth, m as resolveEvery, n as MAX_UNSELECTIVE_ITEMS, o as deleteCollectionRefusalMessage, p as parseCivil, r as makeManageCollectionTool, s as advanceTriggerDate, t as MAX_SCHEMA_ISSUES, u as formatCivil, v as buildWorkspaceOntology, w as compileRecordZ, x as firstMutateParamProblem, y as schemaRelations } from "../../server-8EZggEg7.js";
+export { BackendUnavailableError, COMPUTED_TYPES, CollectionQueryZ, CollectionSchemaZ, DEFAULT_QUERY_ROWS, MAX_CSV_ROWS, MAX_QUERY_ROWS, MAX_SCHEMA_ISSUES, MAX_UNSELECTIVE_ITEMS, SCHEMA_FILE, acceptParsedSchema, advanceTriggerDate, applyMutateAction, buildActionSeedPrompt, buildCollectionActionSeedPrompt, buildWorkspaceOntology, collectionWritable, compileCsvQuery, compileJsonlQuery, compileRecordZ, computeCollectionIcon, computeSuccessor, configureCollectionHost, csvRowToItem, daysInMonth, decodeCsvRecordId, dedupeByRecordId, deleteCollection, deleteCollectionRefusalMessage, deleteCustomView, deleteItem, discoverCollections, encodeCsvRecordId, enrichItems, firstMutateParamProblem, formatCivil, generateItemId, getWorkspaceRoot, isBackendUnavailable, isContainedInRoot, isContainedInWorkspace, isRegularFile, isSafeActionTemplatePath, isSafeCustomViewI18nPath, isSafeCustomViewPath, isSafeTemplatePath, isTriggerDue, itemFilePath, listItems, loadCollection, log, makeManageCollectionTool, maybeSpawnSuccessor, normalizeCsvValue, pageFromFullRead, parseCivil, projectItemFields, promptPathsFor, publishCollectionChange, readCustomViewHtml, readCustomViewI18n, readItem, readOnlyRefusal, readSkillTemplate, recordFieldProblem, resolveCreateItemId, resolveDataDir, resolveEvery, resolveTemplatePath, runCollectionQuery, runQueryOverRows, safeRecordId, safeSlugName, schemaRelations, setCollectionChangePublisher, storeFor, successorId, toDetail, toSummary, validateCollectionRecords, validateRecordObject, writeItem };

package/dist/collection/server/manageTool.d.ts

@@ -72,6 +72,10 @@ export declare function makeManageCollectionTool(deps?: ManageCollectionDeps): {
                     type: string;
                     description: string;
                 };
+                topic: {
+                    type: string;
+                    description: string;
+                };
                 query: {
                     type: string;
                     description: string;

package/dist/collection/server/schemaDocs.d.ts

@@ -0,0 +1,21 @@
+/** A doc at/below this size is returned whole — sectioning something the
+ *  agent can read in one gulp only costs round-trips. This is also what
+ *  keeps short user-authored workspace copies (config/helps) verbatim. */
+export declare const SCHEMA_DOCS_VERBATIM_LIMIT = 20000;
+/** Ceiling for ANY assembled reply — topic or default — safely inside
+ *  the agent's per-result limit (the full doc is what overflowed it).
+ *  A matched section too large to fit degrades to its own prose plus a
+ *  list of its subsections to fetch individually; an oversized leaf is
+ *  clipped outright; the default drops whole core sections into a
+ *  pointer note. Sized so the CURRENT bundled doc's default reply
+ *  (~33KB) fits without degrading. */
+export declare const SCHEMA_DOCS_RESULT_BUDGET = 36000;
+/** Render the authoring reference for one schemaDocs call. Small docs and
+ *  docs without headings pass through verbatim — there is nothing better
+ *  to key a section off. The assembled reply gets one final hard cap: the
+ *  inner budgeting degrades gracefully, but per-piece overheads (clip
+ *  markers on thousands of matches, join separators, pointer notes) add
+ *  up outside any single piece's budget, and the ceiling must hold no
+ *  matter what shape of document arrives. Only the explicit \`"all"\`
+ *  opt-in and the small-doc verbatim path may exceed it. */
+export declare function renderSchemaDocs(doc: string, topic?: string): string;

package/dist/collection/server/store.d.ts

@@ -30,6 +30,22 @@ export interface CollectionStoreCapabilities {
  *     (io.ts is the reference).
  *  4. HONEST AGGREGATION — `query`, when present, is computed over the
  *     WHOLE data set, never from a capped read. */
+/** What a store reports when its records changed underneath it.
+ *
+ *  Two granularities, because backends genuinely differ: a per-record file
+ *  store knows WHICH record changed, while a single-artifact backend (one
+ *  CSV, one db file, one remote snapshot) only knows THAT something did.
+ *  Naming the difference here is what lets the watcher react uniformly
+ *  instead of branching on the backend. */
+export type StoreChange = {
+    readonly kind: "item";
+    readonly itemId: string;
+} | {
+    readonly kind: "collection";
+};
+export type StoreChangeListener = (change: StoreChange) => void;
+/** Detaches a `watch` subscription. */
+export type StoreUnsubscribe = () => void;
 export interface CollectionStore {
     readonly capabilities: CollectionStoreCapabilities;
     /** Every record, in the store's stable order. CSV store: capped at
@@ -50,6 +66,27 @@ export interface CollectionStore {
      *  collection's slug into the publish hook, so no writer can forget it. */
     write?: (itemId: string, item: CollectionItem, opts?: WriteOptions) => Promise<WriteItemResult>;
     delete?: (itemId: string) => Promise<DeleteItemResult>;
+    /** Subscribe to changes made OUTSIDE this process — a file edited by the
+     *  agent, a CSV replaced by the user, a db written by another tool.
+     *
+     *  Resolves to an unsubscribe function, or to `null` when the backend
+     *  could not arm the watch (no inotify watches left, an unreadable
+     *  directory). `null` is NOT the same as absent `watch`: absent means the
+     *  backend never reports changes and the caller should settle for its
+     *  periodic pass, while `null` means this attempt failed and mounting
+     *  should be retried. Swallowing the difference strands a collection on
+     *  stale data until the process restarts.
+     *
+     *  This is the store's job because only it knows where its bytes live and
+     *  what its own change events look like (which paths to watch, which
+     *  filenames are noise, whether an atomic replace surfaces as two events).
+     *  Absorbing that noise — debouncing a replace into one report — belongs
+     *  here too. What to DO about a change (reconcile bells, sweep, publish)
+     *  is the watcher's policy and is deliberately NOT expressed here.
+     *
+     *  Absent ⇒ the backend cannot report external changes; the caller falls
+     *  back to its periodic pass. */
+    watch?: (onChange: StoreChangeListener) => Promise<StoreUnsubscribe | null>;
 }
 /** True when the collection accepts UI/tool writes. A `dataSource`
  *  collection is read-only: updates happen by editing/replacing the

package/dist/collection/server/watchFs.d.ts

@@ -0,0 +1,17 @@
+export interface FsWatchHandle {
+    close: () => void;
+}
+/** Watch `dir`, reporting each accepted filename. `accept` decides what is
+ *  noise; a null filename always passes (the platform didn't tell us which
+ *  file, so the caller must assume the worst). */
+export declare function watchDirectory(dir: string, accept: (filename: string) => boolean, onHit: (filename: string | null) => void): Promise<FsWatchHandle | null>;
+/** Watch the single file `absPath` by watching its PARENT directory, so an
+ *  atomic replace can't strand the watch on a dead inode. `alsoAccept`
+ *  widens the filter beyond the exact basename (sqlite's `-wal`/`-journal`
+ *  sidecars). Reports are debounced: one replace, one call. */
+export declare function watchSingleFile(absPath: string, alsoAccept: (basename: string, filename: string) => boolean, onChange: () => void): Promise<FsWatchHandle | null>;
+/** An `FsWatchHandle` as a bare unsubscribe — `null` straight through, so an
+ *  unarmed watch stays distinguishable from an armed one. Lives here rather
+ *  than beside the store contract so both `store.ts` and the backends it
+ *  registers can reach it without importing each other. */
+export declare function closerFor(handle: FsWatchHandle | null): (() => void) | null;

package/dist/collection-watchers/index.cjs

@@ -1,14 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_rolldown_runtime = require("../rolldown-runtime-D6vf50IK.cjs");
 const require_ids = require("../ids-DWmHjm17.cjs");
-const require_promptSafety = require("../promptSafety-BFt2g_wn.cjs");
+const require_promptSafety = require("../promptSafety-DbE6eZmP.cjs");
 require("../collection/index.cjs");
-const require_discovery = require("../discovery-BKovdRpZ.cjs");
-const require_server = require("../server-rRQkNBvO.cjs");
+const require_discovery = require("../discovery-Bklck7Ck.cjs");
+const require_server = require("../server-BOiz_HDi.cjs");
 const require_notifier = require("../notifier-bS8IEeLA.cjs");
-let node_path = require("node:path");
-node_path = require_rolldown_runtime.__toESM(node_path, 1);
-let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
 //#region src/collection-watchers/config.ts
 var NOOP_LOG = {
@@ -302,6 +298,15 @@ var watchers = /* @__PURE__ */ new Map();
 var rediscoveryTimer = null;
 var triggerTimer = null;
 var started = false;
+/** Guards the clock tick against overlapping itself. Paired with
+*  `watcherEpoch`: a teardown while a pass is in flight bumps the epoch, so
+*  that pass's `finally` knows it belongs to a dead generation and must not
+*  clear a guard the restarted watcher set now owns. `triggerTickInFlight`
+*  is what teardown AWAITS — clearing the flag alone would let a restart run
+*  a second pass alongside the first. */
+var triggerTickRunning = false;
+var watcherEpoch = 0;
+var triggerTickInFlight = null;
 /** Discovery options threaded into every `discoverCollections` /
 *  `loadCollection` / `sweepStaleActiveEntries` call. Production: empty
 *  (live workspace). Tests: `{ workspaceRoot, userSkillsDir }` pointing
@@ -309,15 +314,10 @@ var started = false;
 *  without threading through every signature. */
 var discoveryOpts = {};
 var itemSlots = /* @__PURE__ */ new Map();
-/** Per-slug single-flight for a storage (db-file) collection's full
-*  reconcile pass — a burst of db writes collapses to one pass + one
-*  trailing re-run, mirroring the per-item slots of the file watcher. */
-var storageSlots = /* @__PURE__ */ new Map();
-/** Trailing debounce per dataSource collection: an atomic file replace
-*  (Excel save, editor rename) surfaces as 2-3 fs events — collapse them
-*  into one change publish so live views refetch once. */
-var DATA_SOURCE_DEBOUNCE_MS = 300;
-var dataSourceTimers = /* @__PURE__ */ new Map();
+/** Per-slug single-flight for a COLLECTION-granularity reconcile — a burst
+*  of changes the store couldn't attribute to a record collapses into one
+*  pass plus one trailing re-run, mirroring the per-item slots. */
+var collectionSlots = /* @__PURE__ */ new Map();
 /** Boot entry point: sweep stale active entries, then mount watchers for
 *  every discovered collection and arm the periodic re-discovery poll.
 *  Idempotent — a second call is a no-op. */
@@ -339,8 +339,15 @@ async function startCollectionWatchers(opts = {}) {
 		const triggerMs = opts.triggerTickIntervalMs === void 0 ? TRIGGER_TICK_INTERVAL_MS : opts.triggerTickIntervalMs;
 		if (triggerMs !== null) {
 			triggerTimer = setInterval(() => {
-				tickTimeTriggers().catch((err) => {
+				if (triggerTickRunning) return;
+				triggerTickRunning = true;
+				const epoch = watcherEpoch;
+				triggerTickInFlight = tickTimeTriggers().catch((err) => {
 					log().warn("watcher trigger tick failed", { error: errMsg(err) });
+				}).finally(() => {
+					if (epoch !== watcherEpoch) return;
+					triggerTickRunning = false;
+					triggerTickInFlight = null;
 				});
 			}, triggerMs);
 			triggerTimer.unref();
@@ -363,20 +370,22 @@ async function stopCollectionWatchers() {
 		clearInterval(triggerTimer);
 		triggerTimer = null;
 	}
+	await triggerTickInFlight;
+	triggerTickInFlight = null;
+	watcherEpoch += 1;
+	triggerTickRunning = false;
 	for (const watcher of watchers.values()) try {
-		watcher.watcher.close();
+		watcher.unsubscribe();
 	} catch {}
 	watchers.clear();
 	itemSlots.clear();
-	storageSlots.clear();
-	for (const timer of dataSourceTimers.values()) clearTimeout(timer);
-	dataSourceTimers.clear();
+	collectionSlots.clear();
 	discoveryOpts = {};
 	started = false;
 }
 /** Test-only: manually trigger one rediscovery + reconcile pass. */
 async function _syncWatchersForTesting() {
-	await syncWatchers();
+	return syncWatchers();
 }
 /** Test-only: drive one wall-clock tick synchronously, with an optional
 *  injected clock. */
@@ -400,7 +409,6 @@ async function tickTimeTriggers(now = evalNow()) {
 			});
 			continue;
 		}
-		if (schema.dataSource !== void 0) continue;
 		if (!schema.triggerField && !schema.spawn) continue;
 		await reconcileAllItems(entry.collection, discoveryOpts, now);
 	}
@@ -416,12 +424,14 @@ async function syncWatchers() {
 		collections = await require_discovery.discoverCollections(discoveryOpts);
 	} catch (err) {
 		log().warn("watcher discover failed", { error: errMsg(err) });
-		return;
+		return false;
 	}
 	const vanishedMutated = stopVanishedWatchers(new Set(collections.map((collection) => collection.slug)));
 	const schemaMutated = await reconcileChangedSchemas(collections);
 	const addedMutated = await startNewWatchers(collections);
-	if (vanishedMutated || schemaMutated || addedMutated) await sweepStaleActiveEntries(discoveryOpts);
+	if (!vanishedMutated && !schemaMutated && !addedMutated) return false;
+	await sweepStaleActiveEntries(discoveryOpts);
+	return true;
 }
 function stopVanishedWatchers(liveSlugs) {
 	let mutated = false;
@@ -429,7 +439,7 @@ function stopVanishedWatchers(liveSlugs) {
 		if (liveSlugs.has(slug)) continue;
 		const watcher = watchers.get(slug);
 		if (watcher) try {
-			watcher.watcher.close();
+			watcher.unsubscribe();
 		} catch {}
 		watchers.delete(slug);
 		mutated = true;
@@ -462,7 +472,7 @@ async function reconcileChangedSchemas(collections) {
 		if (storagePathChanged(existing.schemaJson, collection.schema)) {
 			log().info("watcher storage path changed, remounting", { slug: collection.slug });
 			try {
-				existing.watcher.close();
+				existing.unsubscribe();
 			} catch {}
 			watchers.delete(collection.slug);
 			if (collection.schema.dataSource !== void 0) require_discovery.publishCollectionChange({
@@ -474,199 +484,119 @@ async function reconcileChangedSchemas(collections) {
 		}
 		existing.schemaJson = nextJson;
 		existing.collection = collection;
-		if (collection.schema.dataSource !== void 0) {
-			log().info("dataSource watcher schema changed, publishing", { slug: collection.slug });
-			require_discovery.publishCollectionChange({
-				slug: collection.slug,
-				op: "upsert"
-			});
-			mutated = true;
-			continue;
-		}
 		log().info("watcher schema changed, re-reconciling", { slug: collection.slug });
 		await reconcileAllItems(collection, discoveryOpts);
+		if (collection.schema.dataSource !== void 0) require_discovery.publishCollectionChange({
+			slug: collection.slug,
+			op: "upsert"
+		});
 		mutated = true;
 	}
 	return mutated;
 }
+/** Mount a watcher for every collection that doesn't have one yet. Returns
+*  whether the watcher SET actually changed — the starters report whether
+*  they mounted, because ATTEMPTING is not mounting. A start that throws
+*  (logged and swallowed inside the starter) leaves `watchers` untouched, so
+*  the collection is retried next tick; counting that as a mutation made
+*  `syncWatchers` sweep on every tick for as long as the failure persisted. */
 async function startNewWatchers(collections) {
 	let mutated = false;
 	for (const collection of collections) {
 		if (watchers.has(collection.slug)) continue;
-		if (collection.schema.dataSource !== void 0) await startDataSourceWatcher(collection);
-		else if (collection.schema.storage !== void 0) await startStorageWatcher(collection);
-		else await startWatcherFor(collection);
-		mutated = true;
+		if (await startWatcherFor(collection)) mutated = true;
 	}
 	return mutated;
 }
-/** Publish one (debounced) change event for a dataSource collection —
-*  live views refetch the whole collection; no per-row diffing. */
-function scheduleDataSourcePublish(slug) {
-	const existing = dataSourceTimers.get(slug);
-	if (existing) clearTimeout(existing);
-	const timer = setTimeout(() => {
-		dataSourceTimers.delete(slug);
-		require_discovery.publishCollectionChange({
-			slug,
-			op: "upsert"
-		});
-	}, DATA_SOURCE_DEBOUNCE_MS);
-	timer.unref?.();
-	dataSourceTimers.set(slug, timer);
-}
-/** Watch a dataSource collection's external data file. The watch mounts
-*  on the PARENT directory (watching the file itself goes stale after an
-*  atomic replace — the inode changes) and filters events to the file's
-*  basename; a null filename (platform quirk) is treated as a hit. No
-*  reconciler involvement — replacing the CSV just refreshes the views. */
-async function startDataSourceWatcher(collection) {
-	const file = collection.dataSourceFile;
-	if (file === void 0) return;
-	const dir = node_path.default.dirname(file);
-	const base = node_path.default.basename(file);
-	try {
-		await (0, node_fs_promises.mkdir)(dir, { recursive: true });
-		const watcher = (0, node_fs.watch)(dir, { persistent: false }, (_eventType, filename) => {
-			if (filename !== null && filename !== base) return;
-			scheduleDataSourcePublish(collection.slug);
-		});
-		watcher.on("error", (err) => {
-			log().warn("dataSource watcher error", {
-				slug: collection.slug,
-				error: errMsg(err)
-			});
-		});
-		watchers.set(collection.slug, {
-			slug: collection.slug,
-			dataDir: dir,
-			watcher,
-			schemaJson: JSON.stringify(collection.schema),
-			collection
-		});
-		log().info("dataSource watcher started", {
-			slug: collection.slug,
-			file
-		});
-	} catch (err) {
-		log().warn("dataSource watcher start failed", {
-			slug: collection.slug,
-			error: errMsg(err)
-		});
-	}
-}
-/** Watch a `storage` collection's database file. One db file holds every
-*  record, so an event can't name WHICH record changed — each (debounced)
-*  event runs a full `reconcileAllItems` pass (bells / spawn) plus a
-*  change publish so views refetch after EXTERNAL edits too (host writes
-*  already publish their own change events; the extra ping is debounced
-*  and idempotent). Mounts on the parent dir, same as the dataSource
-*  watcher, so an atomic replace can't strand the watch. */
-async function startStorageWatcher(collection) {
-	const file = collection.storageFile;
-	if (file === void 0) return;
-	const dir = node_path.default.dirname(file);
-	const base = node_path.default.basename(file);
+/** Mount one collection's change subscription, whatever its backend.
+*
+*  The store decides how to detect a change and at what granularity; this
+*  decides what to do about one. That split is the point: adding a backend
+*  means implementing `watch` on its store, not another branch here.
+*
+*  A store without `watch` cannot report external changes at all — it is
+*  still registered (so bells reconcile at boot and on the clock tick), just
+*  without live updates. */
+async function startWatcherFor(collection) {
+	const { slug } = collection;
 	try {
-		await (0, node_fs_promises.mkdir)(dir, { recursive: true });
 		await reconcileAllItems(collection, discoveryOpts);
-		const watcher = (0, node_fs.watch)(dir, { persistent: false }, (_eventType, rawFilename) => {
-			const filename = rawFilename === null ? null : String(rawFilename);
-			if (filename !== null && !filename.startsWith(base)) return;
-			scheduleStorageReconcile(collection.slug).catch((err) => {
-				log().warn("storage watcher reconcile failed", {
-					slug: collection.slug,
+		const store = require_discovery.storeFor(collection, discoveryOpts);
+		const unsubscribe = store.watch ? await store.watch((change) => {
+			handleStoreChange(slug, change).catch((err) => {
+				log().warn("store change handling failed", {
+					slug,
 					error: errMsg(err)
 				});
 			});
-		});
-		watcher.on("error", (err) => {
-			log().warn("storage watcher error", {
-				slug: collection.slug,
-				error: errMsg(err)
-			});
-		});
-		watchers.set(collection.slug, {
-			slug: collection.slug,
-			dataDir: dir,
-			watcher,
+		}) : () => {};
+		if (unsubscribe === null) {
+			log().warn("collection watcher could not arm, retrying next sync", { slug });
+			return false;
+		}
+		watchers.set(slug, {
+			slug,
+			dataDir: collection.dataDir,
+			unsubscribe,
 			schemaJson: JSON.stringify(collection.schema),
 			collection
 		});
-		log().info("storage watcher started", {
-			slug: collection.slug,
-			file
+		log().info("collection watcher started", {
+			slug,
+			live: store.watch !== void 0
 		});
+		return true;
 	} catch (err) {
-		log().warn("storage watcher start failed", {
-			slug: collection.slug,
+		log().warn("collection watcher start failed", {
+			slug,
 			error: errMsg(err)
 		});
+		return false;
 	}
 }
-function scheduleStorageReconcile(slug) {
-	return runSingleFlight(storageSlots, slug, async () => {
+/** React to one reported change. Backend-agnostic by construction — it sees
+*  only the granularity the store reported.
+*
+*  `item`: reconcile just that record, then publish it. `collection`: the
+*  store couldn't say which record, so re-derive everything and pair it with
+*  a sweep — a record deleted remotely leaves a bell that a walk over the
+*  SURVIVING records can never clear. */
+async function handleStoreChange(slug, change) {
+	if (change.kind === "collection") {
+		await scheduleCollectionReconcile(slug);
+		return;
+	}
+	const current = watchers.get(slug)?.collection;
+	if (!current) return;
+	await scheduleItemReconcile(current, change.itemId);
+}
+/** Full re-derivation for a collection-granularity change, single-flighted
+*  per slug so a burst of writes collapses into one pass plus one trailing
+*  re-run. */
+function scheduleCollectionReconcile(slug) {
+	return runSingleFlight(collectionSlots, slug, async () => {
 		const collection = await require_discovery.loadCollection(slug, discoveryOpts);
 		if (!collection) return;
 		await reconcileAllItems(collection, discoveryOpts);
 		await sweepStaleActiveEntries(discoveryOpts);
-		require_discovery.publishCollectionChange({
+	}, () => {
+		safePublish({
 			slug,
 			op: "upsert"
 		});
+		return Promise.resolve();
 	});
 }
-/** Test-only: drive one storage-collection reconcile pass directly. */
-function _scheduleStorageReconcileForTesting(slug) {
-	return scheduleStorageReconcile(slug);
+/** Test-only: feed one store-reported change through the same path a live
+*  subscription uses, so a test can pin how a change is reacted to without
+*  depending on fs.watch timing. */
+function _handleStoreChangeForTesting(slug, change) {
+	return handleStoreChange(slug, change);
 }
-async function startWatcherFor(collection) {
-	const { slug, schema, dataDir } = collection;
-	try {
-		await (0, node_fs_promises.mkdir)(dataDir, { recursive: true });
-		await reconcileAllItems(collection, discoveryOpts);
-		const watcher = (0, node_fs.watch)(dataDir, { persistent: false }, (_eventType, filename) => {
-			onEvent(slug, filename).catch((err) => {
-				log().warn("watcher event failed", {
-					slug,
-					filename,
-					error: errMsg(err)
-				});
-			});
-		});
-		watcher.on("error", (err) => {
-			log().warn("watcher error", {
-				slug,
-				error: errMsg(err)
-			});
-		});
-		watchers.set(slug, {
-			slug,
-			dataDir,
-			watcher,
-			schemaJson: JSON.stringify(schema),
-			collection
-		});
-		log().info("watcher started", {
-			slug,
-			dataDir
-		});
-	} catch (err) {
-		log().warn("watcher start failed", {
-			slug,
-			error: errMsg(err)
-		});
-	}
+/** Test-only: drive one collection-granularity reconcile directly. */
+function _scheduleCollectionReconcileForTesting(slug) {
+	return scheduleCollectionReconcile(slug);
 }
-/** Test-only: the per-key single-flight scheduler. Exported so test code
-*  can drive rapid-fire calls directly and observe the trailing coalesce
-*  — `fs.watch` event timing is too flaky to assert against.
-*
-*  Single-flight semantics: while a reconcile is in flight for a given
-*  (slug, itemId), additional events on the same key set `pending = true`
-*  and return — the running reconcile re-runs once after it completes.
-*  This collapses fs.watch's rapid-fire bursts (atomic rename surfaces as
-*  2-3 events) into a single reconcile + one trailing re-run. */
 function _scheduleItemReconcileForTesting(collection, itemId) {
 	return scheduleItemReconcile(collection, itemId);
 }
@@ -740,30 +670,11 @@ function safePublish(payload) {
 		});
 	}
 }
-/** Handle a single fs.watch event. Re-loads the collection (schema may
-*  have changed since startup), filters out non-record files, and
-*  forwards to the single-flighted reconciler. `filename === null` (rare,
-*  platform-specific) triggers a full directory rescan to be safe. */
-async function onEvent(slug, filename) {
-	const collection = await require_discovery.loadCollection(slug, discoveryOpts);
-	if (!collection) return;
-	if (filename === null) {
-		try {
-			await reconcileAllItems(collection, discoveryOpts);
-			await sweepStaleActiveEntries(discoveryOpts);
-		} finally {
-			safePublish({ slug });
-		}
-		return;
-	}
-	const name = typeof filename === "string" ? filename : filename.toString("utf-8");
-	if (!name.endsWith(".json") || name.startsWith(".")) return;
-	await scheduleItemReconcile(collection, name.slice(0, -5));
-}
 //#endregion
+exports._handleStoreChangeForTesting = _handleStoreChangeForTesting;
 exports._resetReconcilerLocksForTesting = _resetReconcilerLocksForTesting;
+exports._scheduleCollectionReconcileForTesting = _scheduleCollectionReconcileForTesting;
 exports._scheduleItemReconcileForTesting = _scheduleItemReconcileForTesting;
-exports._scheduleStorageReconcileForTesting = _scheduleStorageReconcileForTesting;
 exports._syncWatchersForTesting = _syncWatchersForTesting;
 exports._tickTimeTriggersForTesting = _tickTimeTriggersForTesting;
 exports.clearItemNotification = clearItemNotification;