@fnndsc/cumin 3.15.1 → 3.16.1

package/dist/cache/index.d.ts

@@ -4,9 +4,11 @@
  * @module
  */
 export { ListCache, listCache_get } from './listCache.js';
-export type { CacheStats, CacheResult, CacheOptions } from './listCache.js';
-export { ProcCache, procCache_get, status_isTerminal, PROC_TERMINAL_STATUSES } from './procCache.js';
-export type { ProcInstance, ProcFeed, ProcFeedScopeCounts, ProcWarmupProgress, ProcCacheState, ProcCacheLifecycle, ProcCacheSnapshot, } from './procCache.js';
+export type { CacheStats, CacheResult, CacheOptions, ListCacheSnapshot, ListCacheEntrySnapshot } from './listCache.js';
+export { listCheckpointPath_get, listCheckpoint_restore, listCheckpoint_save, listCheckpoint_watch, } from './listCheckpoint.js';
+export type { ListCheckpointRestoreResult } from './listCheckpoint.js';
+export { ProcCache, procCache_get, status_isTerminal, feed_isActive, feedTopology_changed, PROC_TERMINAL_STATUSES } from './procCache.js';
+export type { ProcInstance, ProcFeed, ProcFeedScopeCounts, ProcWarmupProgress, ProcCacheState, ProcCacheLifecycle, ProcCacheSnapshot, ProcFeedSnapshot, ProcCacheChange, ProcCacheListener, } from './procCache.js';
 export type { ProcPromptState, ProcPromptProgress } from '@fnndsc/menu';
-export { procCheckpointPath_get, procCheckpoint_restore, procCheckpoint_save, procCheckpoint_watch, } from './procCheckpoint.js';
+export { procCheckpointPath_get, procCheckpointDir_get, procCheckpoint_restore, procCheckpoint_save, procCheckpointFeed_save, procCheckpointRoster_save, procCheckpoint_watch, } from './procCheckpoint.js';
 export type { ProcCheckpointRestoreResult } from './procCheckpoint.js';

package/dist/cache/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.procCheckpoint_watch = exports.procCheckpoint_save = exports.procCheckpoint_restore = exports.procCheckpointPath_get = exports.PROC_TERMINAL_STATUSES = exports.status_isTerminal = exports.procCache_get = exports.ProcCache = exports.listCache_get = exports.ListCache = void 0;
+exports.procCheckpoint_watch = exports.procCheckpointRoster_save = exports.procCheckpointFeed_save = exports.procCheckpoint_save = exports.procCheckpoint_restore = exports.procCheckpointDir_get = exports.procCheckpointPath_get = exports.PROC_TERMINAL_STATUSES = exports.feedTopology_changed = exports.feed_isActive = exports.status_isTerminal = exports.procCache_get = exports.ProcCache = exports.listCheckpoint_watch = exports.listCheckpoint_save = exports.listCheckpoint_restore = exports.listCheckpointPath_get = exports.listCache_get = exports.ListCache = void 0;
 /**
  * @file Cache module exports.
  *
@@ -9,14 +9,24 @@ exports.procCheckpoint_watch = exports.procCheckpoint_save = exports.procCheckpo
 var listCache_js_1 = require("./listCache.js");
 Object.defineProperty(exports, "ListCache", { enumerable: true, get: function () { return listCache_js_1.ListCache; } });
 Object.defineProperty(exports, "listCache_get", { enumerable: true, get: function () { return listCache_js_1.listCache_get; } });
+var listCheckpoint_js_1 = require("./listCheckpoint.js");
+Object.defineProperty(exports, "listCheckpointPath_get", { enumerable: true, get: function () { return listCheckpoint_js_1.listCheckpointPath_get; } });
+Object.defineProperty(exports, "listCheckpoint_restore", { enumerable: true, get: function () { return listCheckpoint_js_1.listCheckpoint_restore; } });
+Object.defineProperty(exports, "listCheckpoint_save", { enumerable: true, get: function () { return listCheckpoint_js_1.listCheckpoint_save; } });
+Object.defineProperty(exports, "listCheckpoint_watch", { enumerable: true, get: function () { return listCheckpoint_js_1.listCheckpoint_watch; } });
 var procCache_js_1 = require("./procCache.js");
 Object.defineProperty(exports, "ProcCache", { enumerable: true, get: function () { return procCache_js_1.ProcCache; } });
 Object.defineProperty(exports, "procCache_get", { enumerable: true, get: function () { return procCache_js_1.procCache_get; } });
 Object.defineProperty(exports, "status_isTerminal", { enumerable: true, get: function () { return procCache_js_1.status_isTerminal; } });
+Object.defineProperty(exports, "feed_isActive", { enumerable: true, get: function () { return procCache_js_1.feed_isActive; } });
+Object.defineProperty(exports, "feedTopology_changed", { enumerable: true, get: function () { return procCache_js_1.feedTopology_changed; } });
 Object.defineProperty(exports, "PROC_TERMINAL_STATUSES", { enumerable: true, get: function () { return procCache_js_1.PROC_TERMINAL_STATUSES; } });
 var procCheckpoint_js_1 = require("./procCheckpoint.js");
 Object.defineProperty(exports, "procCheckpointPath_get", { enumerable: true, get: function () { return procCheckpoint_js_1.procCheckpointPath_get; } });
+Object.defineProperty(exports, "procCheckpointDir_get", { enumerable: true, get: function () { return procCheckpoint_js_1.procCheckpointDir_get; } });
 Object.defineProperty(exports, "procCheckpoint_restore", { enumerable: true, get: function () { return procCheckpoint_js_1.procCheckpoint_restore; } });
 Object.defineProperty(exports, "procCheckpoint_save", { enumerable: true, get: function () { return procCheckpoint_js_1.procCheckpoint_save; } });
+Object.defineProperty(exports, "procCheckpointFeed_save", { enumerable: true, get: function () { return procCheckpoint_js_1.procCheckpointFeed_save; } });
+Object.defineProperty(exports, "procCheckpointRoster_save", { enumerable: true, get: function () { return procCheckpoint_js_1.procCheckpointRoster_save; } });
 Object.defineProperty(exports, "procCheckpoint_watch", { enumerable: true, get: function () { return procCheckpoint_js_1.procCheckpoint_watch; } });
 //# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,+CAA0D;AAAjD,yGAAA,SAAS,OAAA;AAAE,6GAAA,aAAa,OAAA;AAEjC,+CAAqG;AAA5F,yGAAA,SAAS,OAAA;AAAE,6GAAA,aAAa,OAAA;AAAE,iHAAA,iBAAiB,OAAA;AAAE,sHAAA,sBAAsB,OAAA;AAqB5E,yDAK6B;AAJ3B,2HAAA,sBAAsB,OAAA;AACtB,2HAAA,sBAAsB,OAAA;AACtB,wHAAA,mBAAmB,OAAA;AACnB,yHAAA,oBAAoB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,+CAA0D;AAAjD,yGAAA,SAAS,OAAA;AAAE,6GAAA,aAAa,OAAA;AAEjC,yDAK6B;AAJ3B,2HAAA,sBAAsB,OAAA;AACtB,2HAAA,sBAAsB,OAAA;AACtB,wHAAA,mBAAmB,OAAA;AACnB,yHAAA,oBAAoB,OAAA;AAGtB,+CAA0I;AAAjI,yGAAA,SAAS,OAAA;AAAE,6GAAA,aAAa,OAAA;AAAE,iHAAA,iBAAiB,OAAA;AAAE,6GAAA,aAAa,OAAA;AAAE,oHAAA,oBAAoB,OAAA;AAAE,sHAAA,sBAAsB,OAAA;AAwBjH,yDAQ6B;AAP3B,2HAAA,sBAAsB,OAAA;AACtB,0HAAA,qBAAqB,OAAA;AACrB,2HAAA,sBAAsB,OAAA;AACtB,wHAAA,mBAAmB,OAAA;AACnB,4HAAA,uBAAuB,OAAA;AACvB,8HAAA,yBAAyB,OAAA;AACzB,yHAAA,oBAAoB,OAAA"}

package/dist/cache/listCache.d.ts

@@ -32,6 +32,27 @@ export interface CacheOptions {
     /** Mark as dirty immediately */
     dirty?: boolean;
 }
+/**
+ * A persistence-safe copy of one cache entry.
+ *
+ * @property path - The listed path.
+ * @property data - The cached listing.
+ * @property timestamp - When it was cached (ms since epoch); age is judged
+ *   against this on restore, so a restored entry is as stale as it really is.
+ * @property dirty - Whether a local mutation invalidated it.
+ * @property ttl - Its time-to-live in milliseconds.
+ */
+export interface ListCacheEntrySnapshot {
+    path: string;
+    data: unknown;
+    timestamp: number;
+    dirty: boolean;
+    ttl: number;
+}
+/** The whole cache, oldest entry first (the LRU order). */
+export interface ListCacheSnapshot {
+    entries: ListCacheEntrySnapshot[];
+}
 /**
  * Statistics about cache usage.
  */
@@ -97,6 +118,33 @@ export declare class ListCache {
     private ttlConfig;
     /** Cache statistics. */
     private stats;
+    /** Listeners told after any mutation a persister would want to see. */
+    private listeners;
+    /**
+     * Registers a callback for checkpoint-worthy mutations (set, update,
+     * dirty, invalidate).
+     *
+     * @param listener - Callback invoked after a mutation.
+     * @returns Function that unregisters the callback.
+     */
+    changeListener_add(listener: () => void): () => void;
+    private change_emit;
+    /**
+     * Creates a persistence-safe copy of every entry, oldest first.
+     *
+     * @returns The snapshot.
+     */
+    snapshot_create(): ListCacheSnapshot;
+    /**
+     * Merges a snapshot's entries into the cache, keeping their original
+     * timestamps: what was stale stays stale and is revalidated on its next
+     * visit. A path already cached in this process is newer than anything on
+     * disk and is kept as is. Entries beyond the LRU bound are dropped
+     * oldest-first.
+     *
+     * @param snapshot - A validated snapshot.
+     */
+    snapshot_restore(snapshot: ListCacheSnapshot): void;
     /**
      * Private constructor to enforce singleton pattern.
      */

package/dist/cache/listCache.js

@@ -53,6 +53,55 @@ exports.listCache_get = listCache_get;
  * ```
  */
 class ListCache {
+    /**
+     * Registers a callback for checkpoint-worthy mutations (set, update,
+     * dirty, invalidate).
+     *
+     * @param listener - Callback invoked after a mutation.
+     * @returns Function that unregisters the callback.
+     */
+    changeListener_add(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    change_emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+    /**
+     * Creates a persistence-safe copy of every entry, oldest first.
+     *
+     * @returns The snapshot.
+     */
+    snapshot_create() {
+        const entries = [];
+        for (const [path, entry] of this.cache) {
+            entries.push({ path, data: entry.data, timestamp: entry.timestamp, dirty: entry.dirty, ttl: entry.ttl });
+        }
+        return { entries };
+    }
+    /**
+     * Merges a snapshot's entries into the cache, keeping their original
+     * timestamps: what was stale stays stale and is revalidated on its next
+     * visit. A path already cached in this process is newer than anything on
+     * disk and is kept as is. Entries beyond the LRU bound are dropped
+     * oldest-first.
+     *
+     * @param snapshot - A validated snapshot.
+     */
+    snapshot_restore(snapshot) {
+        const live = new Map(this.cache);
+        this.cache.clear();
+        for (const entry of snapshot.entries) {
+            if (live.has(entry.path))
+                continue;
+            this.cache.set(entry.path, { data: entry.data, timestamp: entry.timestamp, dirty: entry.dirty, ttl: entry.ttl });
+        }
+        for (const [path, entry] of live)
+            this.cache.set(path, entry);
+        this.evict_lru();
+        this.change_emit();
+    }
     /**
      * Private constructor to enforce singleton pattern.
      */
@@ -77,6 +126,8 @@ class ListCache {
             staleHits: 0,
             evictions: 0,
         };
+        /** Listeners told after any mutation a persister would want to see. */
+        this.listeners = new Set();
     }
     /**
      * Gets the singleton instance of ListCache.
@@ -136,6 +187,7 @@ class ListCache {
         });
         // LRU eviction if over limit
         this.evict_lru();
+        this.change_emit();
     }
     /**
      * Marks a cached path as dirty (needs refresh).
@@ -147,6 +199,7 @@ class ListCache {
         const entry = this.cache.get(path);
         if (entry) {
             entry.dirty = true;
+            this.change_emit();
         }
     }
     /**
@@ -162,6 +215,7 @@ class ListCache {
             entry.data = updater(entry.data);
             entry.timestamp = Date.now(); // Reset timestamp
             entry.dirty = false; // Clean after update
+            this.change_emit();
         }
     }
     /**
@@ -177,6 +231,7 @@ class ListCache {
         else {
             this.cache.clear();
         }
+        this.change_emit();
     }
     /**
      * Invalidates a path and every cached listing beneath it.
@@ -196,6 +251,7 @@ class ListCache {
                 this.cache.delete(key);
             }
         }
+        this.change_emit();
     }
     /**
      * @deprecated Use cache without cwd tracking. Cache persists across navigation.

package/dist/cache/listCache.js.map

@@ -1 +1 @@
-{"version":3,"file":"listCache.js","sourceRoot":"","sources":["../../src/cache/listCache.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAoWH,sCAEC;AAnSD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAa,SAAS;IA4BpB;;OAEG;IACH;QA5BA,mCAAmC;QAC3B,UAAK,GAAqC,IAAI,GAAG,EAAE,CAAC;QAE5D,4CAA4C;QACpC,eAAU,GAAW,GAAG,CAAC;QAEjC,sDAAsD;QAC9C,eAAU,GAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QAE3C,uCAAuC;QAC/B,cAAS,GAAwB,IAAI,GAAG,CAAC;YAC/C,CAAC,SAAS,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,EAAM,oCAAoC;YACrE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,EAAU,gCAAgC;YAClE,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,EAAU,iCAAiC;YACnE,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,EAAO,uBAAuB;SAC1D,CAAC,CAAC;QAEH,wBAAwB;QAChB,UAAK,GAAG;YACd,IAAI,EAAE,CAAC;YACP,MAAM,EAAE,CAAC;YACT,SAAS,EAAE,CAAC;YACZ,SAAS,EAAE,CAAC;SACb,CAAC;IAKqB,CAAC;IAExB;;;;OAIG;IACH,MAAM,CAAC,YAAY;QACjB,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;YACxB,SAAS,CAAC,QAAQ,GAAG,IAAI,SAAS,EAAE,CAAC;QACvC,CAAC;QACD,OAAO,SAAS,CAAC,QAAQ,CAAC;IAC5B,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAc,IAAY;QACjC,MAAM,KAAK,GAAoC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEpE,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACpB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,2CAA2C;QAC3C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAE5B,sBAAsB;QACtB,MAAM,GAAG,GAAW,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC;QACjD,MAAM,KAAK,GAAY,CAAC,KAAK,CAAC,KAAK,IAAI,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;QAEvD,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QACzB,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAS,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAC/C,CAAC;IAED;;;;;;OAMG;IACH,SAAS,CAAc,IAAY,EAAE,IAAO,EAAE,OAAsB;QAClE,mDAAmD;QACnD,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAED,MAAM,GAAG,GAAW,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAEvD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE;YACnB,IAAI;YACJ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK;YAC9B,GAAG;SACJ,CAAC,CAAC;QAEH,6BAA6B;QAC7B,IAAI,CAAC,SAAS,EAAE,CAAC;IACnB,CAAC;IAED;;;;;OAKG;IACH,eAAe,CAAC,IAAY;QAC1B,MAAM,KAAK,GAAoC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpE,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;QACrB,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,YAAY,CAAc,IAAY,EAAE,OAAuB;QAC7D,MAAM,KAAK,GAAoC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpE,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAS,CAAC,CAAC;YACtC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAE,kBAAkB;YACjD,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAY,qBAAqB;QACvD,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,gBAAgB,CAAC,IAAa;QAC5B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,oBAAoB,CAAC,IAAY;QAC/B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,MAAM,GAAW,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC;QAC9D,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YACpC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,OAAe;QACxB,qDAAqD;QACrD,oDAAoD;IACtD,CAAC;IAED;;;;;OAKG;IACK,OAAO,CAAC,IAAY;QAC1B,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;QACnC,CAAC;QAED,KAAK,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC5C,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,KAAK,GAAW,IAAI,MAAM,CAAC,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;gBAC3E,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;oBACrB,OAAO,GAAG,CAAC;gBACb,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;OAEG;IACK,SAAS;QACf,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACzC,MAAM,SAAS,GAAuB,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YACrE,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBAC7B,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAE,wCAAwC;YAClD,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,SAAS;QACP,IAAI,SAAS,GAAW,CAAC,CAAC;QAC1B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACxC,qCAAqC;YACrC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;QACjD,CAAC;QAED,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACrB,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;YACzB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS;YAC/B,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS;YAC/B,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACxB,SAAS;SACV,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,WAAW;QACT,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;QACpB,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;IAC3B,CAAC;CACF;AAtPD,8BAsPC;AAED;;;;GAIG;AACH,SAAgB,aAAa;IAC3B,OAAO,SAAS,CAAC,YAAY,EAAE,CAAC;AAClC,CAAC"}
+{"version":3,"file":"listCache.js","sourceRoot":"","sources":["../../src/cache/listCache.ts"],"names":[],"mappings":"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"}

package/dist/cache/listCheckpoint.d.ts

@@ -0,0 +1,52 @@
+/** Minimum spacing between two writes of the listing checkpoint. */
+export declare const LIST_CHECKPOINT_FLOOR_MS: number;
+/**
+ * Outcome of attempting to restore a listing checkpoint.
+ *
+ * @property restored - Whether validated entries replaced the cache.
+ * @property count - Number of restored listings.
+ * @property writtenAt - Checkpoint creation time when restoration succeeded.
+ * @property reason - Human-readable reason when restoration was skipped.
+ */
+export interface ListCheckpointRestoreResult {
+    restored: boolean;
+    count: number;
+    writtenAt?: string;
+    reason?: string;
+}
+/**
+ * Builds the identity-keyed checkpoint path without exposing the identity.
+ *
+ * @param identity - Canonical ChRIS identity string.
+ * @param root - Checkpoint directory override.
+ * @returns Versioned checkpoint path.
+ */
+export declare function listCheckpointPath_get(identity: string, root?: string): string;
+/**
+ * Restores a matching, validated listing checkpoint into the cache.
+ *
+ * @param identity - Canonical ChRIS identity string.
+ * @param root - Checkpoint directory override.
+ * @returns Restoration outcome without throwing for absent or invalid files.
+ */
+export declare function listCheckpoint_restore(identity: string, root?: string): Promise<ListCheckpointRestoreResult>;
+/**
+ * Atomically saves the listing cache.
+ *
+ * @param identity - Canonical ChRIS identity string.
+ * @param root - Checkpoint directory override.
+ * @returns Promise resolved after the mode-0600 file is durable in place.
+ */
+export declare function listCheckpoint_save(identity: string, root?: string): Promise<void>;
+/**
+ * Starts a throttled checkpoint writer for listing-cache mutations: a write
+ * at least `delayMs` after the first pending mutation, and no more often
+ * than once per `floorMs`, the last change never dropped.
+ *
+ * @param identity - Canonical ChRIS identity string.
+ * @param root - Checkpoint directory override.
+ * @param delayMs - Debounce interval in milliseconds.
+ * @param floorMs - Minimum spacing between two writes.
+ * @returns Function that stops watching and cancels a pending save.
+ */
+export declare function listCheckpoint_watch(identity: string, root?: string, delayMs?: number, floorMs?: number): () => void;

package/dist/cache/listCheckpoint.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_CHECKPOINT_FLOOR_MS = void 0;
+exports.listCheckpointPath_get = listCheckpointPath_get;
+exports.listCheckpoint_restore = listCheckpoint_restore;
+exports.listCheckpoint_save = listCheckpoint_save;
+exports.listCheckpoint_watch = listCheckpoint_watch;
+/**
+ * @file Persistent checkpoint for the directory-listing cache.
+ *
+ * The listing cache is a set of per-path snapshots with a TTL each. Written
+ * to disk, restored at boot with their original timestamps, they come back
+ * exactly as stale as they are: the first visit to a restored path renders
+ * at once and revalidates behind itself, instead of starting cold. One
+ * identity-keyed, mode-0600 file under a mode-0700 folder, written by
+ * same-directory atomic rename, throttled so a burst of listings coalesces
+ * into one write.
+ *
+ * @module
+ */
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const listCache_1 = require("./listCache");
+const LIST_CHECKPOINT_SCHEMA = 1;
+/** Minimum spacing between two writes of the listing checkpoint. */
+exports.LIST_CHECKPOINT_FLOOR_MS = 10 * 1000;
+/** Returns the default directory for persistent listing files. */
+function listCheckpointRoot_get() {
+    const cacheHome = process.env.XDG_CACHE_HOME ?? (0, path_1.join)((0, os_1.homedir)(), '.cache');
+    return (0, path_1.join)(cacheHome, 'chell', 'vfs');
+}
+/**
+ * Builds the identity-keyed checkpoint path without exposing the identity.
+ *
+ * @param identity - Canonical ChRIS identity string.
+ * @param root - Checkpoint directory override.
+ * @returns Versioned checkpoint path.
+ */
+function listCheckpointPath_get(identity, root = listCheckpointRoot_get()) {
+    const key = (0, crypto_1.createHash)('sha256').update(identity).digest('hex').slice(0, 16);
+    return (0, path_1.join)(root, `listings-${key}-v${LIST_CHECKPOINT_SCHEMA}.json`);
+}
+/** Reports whether a value is a structurally valid persisted entry. */
+function entry_check(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const entry = value;
+    return typeof entry.path === 'string' && entry.path.startsWith('/') &&
+        entry.data !== undefined && entry.data !== null &&
+        typeof entry.timestamp === 'number' && Number.isFinite(entry.timestamp) &&
+        typeof entry.dirty === 'boolean' &&
+        typeof entry.ttl === 'number' && Number.isFinite(entry.ttl) && entry.ttl > 0;
+}
+/** Reports whether parsed JSON is a compatible checkpoint for an identity. */
+function file_check(value, identity) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const file = value;
+    return file.schemaVersion === LIST_CHECKPOINT_SCHEMA &&
+        file.identity === identity &&
+        typeof file.writtenAt === 'string' &&
+        !Number.isNaN(Date.parse(file.writtenAt)) &&
+        Array.isArray(file.entries) &&
+        file.entries.every(entry_check) &&
+        new Set(file.entries.map((entry) => entry.path)).size === file.entries.length;
+}
+/**
+ * Restores a matching, validated listing checkpoint into the cache.
+ *
+ * @param identity - Canonical ChRIS identity string.
+ * @param root - Checkpoint directory override.
+ * @returns Restoration outcome without throwing for absent or invalid files.
+ */
+async function listCheckpoint_restore(identity, root = listCheckpointRoot_get()) {
+    try {
+        const raw = await fs_1.promises.readFile(listCheckpointPath_get(identity, root), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!file_check(parsed, identity)) {
+            return { restored: false, count: 0, reason: 'incompatible listing checkpoint' };
+        }
+        const snapshot = { entries: parsed.entries };
+        (0, listCache_1.listCache_get)().snapshot_restore(snapshot);
+        return { restored: true, count: parsed.entries.length, writtenAt: parsed.writtenAt };
+    }
+    catch (error) {
+        const code = error.code;
+        return {
+            restored: false,
+            count: 0,
+            reason: code === 'ENOENT' ? 'no listing checkpoint' : (error instanceof Error ? error.message : String(error)),
+        };
+    }
+}
+/**
+ * Atomically saves the listing cache.
+ *
+ * @param identity - Canonical ChRIS identity string.
+ * @param root - Checkpoint directory override.
+ * @returns Promise resolved after the mode-0600 file is durable in place.
+ */
+async function listCheckpoint_save(identity, root = listCheckpointRoot_get()) {
+    const path = listCheckpointPath_get(identity, root);
+    const temporaryPath = `${path}.${process.pid}-${(0, crypto_1.randomUUID)()}.tmp`;
+    const file = {
+        schemaVersion: LIST_CHECKPOINT_SCHEMA,
+        identity,
+        writtenAt: new Date().toISOString(),
+        entries: (0, listCache_1.listCache_get)().snapshot_create().entries,
+    };
+    await fs_1.promises.mkdir((0, path_1.dirname)(path), { recursive: true, mode: 0o700 });
+    await fs_1.promises.chmod((0, path_1.dirname)(path), 0o700);
+    await fs_1.promises.writeFile(temporaryPath, `${JSON.stringify(file)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await fs_1.promises.rename(temporaryPath, path);
+    await fs_1.promises.chmod(path, 0o600);
+}
+/**
+ * Starts a throttled checkpoint writer for listing-cache mutations: a write
+ * at least `delayMs` after the first pending mutation, and no more often
+ * than once per `floorMs`, the last change never dropped.
+ *
+ * @param identity - Canonical ChRIS identity string.
+ * @param root - Checkpoint directory override.
+ * @param delayMs - Debounce interval in milliseconds.
+ * @param floorMs - Minimum spacing between two writes.
+ * @returns Function that stops watching and cancels a pending save.
+ */
+function listCheckpoint_watch(identity, root = listCheckpointRoot_get(), delayMs = 2000, floorMs = exports.LIST_CHECKPOINT_FLOOR_MS) {
+    let timer = null;
+    let lastWrite = 0;
+    const listener_remove = (0, listCache_1.listCache_get)().changeListener_add(() => {
+        if (timer)
+            return;
+        const wait = Math.max(delayMs, lastWrite + floorMs - Date.now());
+        timer = setTimeout(() => {
+            timer = null;
+            lastWrite = Date.now();
+            void listCheckpoint_save(identity, root).catch(() => { });
+        }, wait);
+        timer.unref();
+    });
+    return () => {
+        listener_remove();
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+    };
+}
+//# sourceMappingURL=listCheckpoint.js.map

package/dist/cache/listCheckpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listCheckpoint.js","sourceRoot":"","sources":["../../src/cache/listCheckpoint.ts"],"names":[],"mappings":"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"}

package/dist/cache/procCache.d.ts

@@ -49,6 +49,21 @@ export interface ProcFeedScopeCounts {
     shared: number;
     total: number;
 }
+/**
+ * Reports whether a feed has work which can still change after checkpointing.
+ *
+ * @param feed - Feed summary with CUBE job counters.
+ * @returns True when any job is created, scheduled, or started.
+ */
+export declare function feed_isActive(feed: ProcFeed): boolean;
+/**
+ * Reports whether two feed summaries indicate different instance topology.
+ *
+ * @param previous - The cached feed summary.
+ * @param current - A freshly fetched feed summary.
+ * @returns True when any job counter differs.
+ */
+export declare function feedTopology_changed(previous: ProcFeed, current: ProcFeed): boolean;
 /**
  * Instance entry. Topology (id/feedID/parentID/pluginName) is permanent.
  * Status is cached only once terminal (settled); active status is refreshed live.
@@ -141,6 +156,38 @@ export interface ProcCacheSnapshot {
     instances: ProcInstance[];
     topologyLoaded: number[];
 }
+/**
+ * One feed's persistence-safe topology: what a per-feed checkpoint shard holds.
+ *
+ * @property feedID - The feed these instances belong to.
+ * @property loaded - Whether the feed's topology is known to be complete.
+ * @property instances - Normalized instances with terminal status only.
+ */
+export interface ProcFeedSnapshot {
+    feedID: number;
+    loaded: boolean;
+    instances: ProcInstance[];
+}
+/**
+ * What a cache mutation touched, so a persister can write only that part.
+ *
+ * - `roster`: the feed index (a feed row added, updated, or removed);
+ * - `feed`: one feed's topology, status, metrics, joins, or loaded mark;
+ * - `all`: every feed at once (a completed global sweep);
+ * - `lifecycle`: freshness state only — nothing durable changed.
+ */
+export type ProcCacheChange = {
+    scope: 'roster';
+} | {
+    scope: 'feed';
+    feedID: number;
+} | {
+    scope: 'all';
+} | {
+    scope: 'lifecycle';
+};
+/** A cache mutation listener, told what the mutation touched. */
+export type ProcCacheListener = (change: ProcCacheChange) => void;
 /**
  * Session-scoped cache of feed and instance topology with restorable terminal state.
  */
@@ -181,10 +228,10 @@ export declare class ProcCache {
     /**
      * Registers a callback for checkpoint-worthy cache mutations.
      *
-     * @param listener - Callback invoked after a cache mutation.
+     * @param listener - Callback invoked after a cache mutation with what it touched.
      * @returns Function that unregisters the callback.
      */
-    changeListener_add(listener: () => void): () => void;
+    changeListener_add(listener: ProcCacheListener): () => void;
     private change_emit;
     /**
      * Adds or updates a feed entry.
@@ -346,6 +393,22 @@ export declare class ProcCache {
      * @returns Serializable feed and terminal-topology state.
      */
     snapshot_create(): ProcCacheSnapshot;
+    /**
+     * Creates one feed's persistence-safe snapshot: its instances (terminal
+     * status only, no params or output paths) and whether its topology is
+     * complete. A per-feed checkpoint shard is exactly this.
+     *
+     * @param feedID - The feed to snapshot.
+     * @returns The feed's shard content; empty when the feed holds no instances.
+     */
+    feedSnapshot_create(feedID: number): ProcFeedSnapshot;
+    /**
+     * Feed IDs that hold any instances or a loaded mark — the feeds a full
+     * checkpoint must shard.
+     *
+     * @returns Feed IDs with persistent topology state.
+     */
+    shardedFeedIDs_get(): number[];
     /**
      * Replaces in-memory topology with a validated persistent snapshot.
      *