@fnndsc/cumin 3.8.1 → 3.9.0

package/README.md

@@ -54,7 +54,7 @@ In the "Sandwich Model" architecture, `cumin` is the bottom layer (just above th
 -   **`ChrisIO`**: High-level IO operations, including recursive directory uploading (`uploadLocalPath`).
 -   **`ChRISResource.resources_getAll()`**: Generic pagination handler.
 -   **`ListCache`** (`listCache_get()`): Session-scoped directory listing cache for the VFS.
--   **`ProcCache`** (`procCache_get()`): Session-scoped job monitoring cache. Stores all visible plugin instances as a DAG (two flat maps: `instances` keyed by ID, `children`/`feedRoots` for tree traversal). Structure is permanent once built; only non-terminal instance statuses are refreshed on read. Powers the `/proc/jobs/` VFS provider in salsa.
+-   **`ProcCache`** (`procCache_get()`): Session-scoped job monitoring DAG with versioned, identity-scoped daemon checkpoints. Restored topology remains usable while CUBE reconciliation runs; terminal status persists and active status refreshes on read. Powers the `/proc/jobs/` VFS provider in salsa.
 
 ## Developer Setup
 
@@ -75,4 +75,4 @@ To build the `cumin` library from source:
 MIT — part of the [ChRIS Project](https://chrisproject.org).
 
 ---
-_-30-_
+_-30-_

package/dist/cache/index.d.ts

@@ -6,4 +6,8 @@
 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 } from './procCache.js';
+export type { ProcInstance, ProcFeed, ProcFeedScopeCounts, ProcWarmupProgress, ProcCacheState, ProcCacheLifecycle, ProcCacheSnapshot, } from './procCache.js';
+export { procPromptState_get, PROC_PROMPT_STATES } from './procPrompt.js';
+export type { ProcPromptState, ProcPromptProgress } from './procPrompt.js';
+export { procCheckpointPath_get, procCheckpoint_restore, procCheckpoint_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.PROC_TERMINAL_STATUSES = exports.status_isTerminal = exports.procCache_get = exports.ProcCache = exports.listCache_get = exports.ListCache = void 0;
+exports.procCheckpoint_watch = exports.procCheckpoint_save = exports.procCheckpoint_restore = exports.procCheckpointPath_get = exports.PROC_PROMPT_STATES = exports.procPromptState_get = exports.PROC_TERMINAL_STATUSES = exports.status_isTerminal = exports.procCache_get = exports.ProcCache = exports.listCache_get = exports.ListCache = void 0;
 /**
  * @file Cache module exports.
  *
@@ -14,4 +14,12 @@ Object.defineProperty(exports, "ProcCache", { enumerable: true, get: function ()
 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, "PROC_TERMINAL_STATUSES", { enumerable: true, get: function () { return procCache_js_1.PROC_TERMINAL_STATUSES; } });
+var procPrompt_js_1 = require("./procPrompt.js");
+Object.defineProperty(exports, "procPromptState_get", { enumerable: true, get: function () { return procPrompt_js_1.procPromptState_get; } });
+Object.defineProperty(exports, "PROC_PROMPT_STATES", { enumerable: true, get: function () { return procPrompt_js_1.PROC_PROMPT_STATES; } });
+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, "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, "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"}
+{"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;AAU5E,iDAA0E;AAAjE,oHAAA,mBAAmB,OAAA;AAAE,mHAAA,kBAAkB,OAAA;AAEhD,yDAK6B;AAJ3B,2HAAA,sBAAsB,OAAA;AACtB,2HAAA,sBAAsB,OAAA;AACtB,wHAAA,mBAAmB,OAAA;AACnB,yHAAA,oBAAoB,OAAA"}

package/dist/cache/listCache.d.ts

@@ -144,6 +144,17 @@ export declare class ListCache {
      * @param path - Optional specific path to invalidate. If omitted, clears entire cache.
      */
     cache_invalidate(path?: string): void;
+    /**
+     * Invalidates a path and every cached listing beneath it.
+     * Called by operations that remove or replace an entire directory tree
+     * (rm -r, a directory re-upload): nested listings cached before the
+     * mutation would otherwise serve the old tree's contents until their TTL
+     * expires, with no refresh hint.
+     *
+     * @param path - Root of the subtree to invalidate. The entry for the path
+     *     itself is removed along with all entries under `path + '/'`.
+     */
+    cache_invalidateTree(path: string): void;
     /**
      * @deprecated Use cache without cwd tracking. Cache persists across navigation.
      * This method is kept for backward compatibility but does nothing.

package/dist/cache/listCache.js

@@ -178,6 +178,25 @@ class ListCache {
             this.cache.clear();
         }
     }
+    /**
+     * Invalidates a path and every cached listing beneath it.
+     * Called by operations that remove or replace an entire directory tree
+     * (rm -r, a directory re-upload): nested listings cached before the
+     * mutation would otherwise serve the old tree's contents until their TTL
+     * expires, with no refresh hint.
+     *
+     * @param path - Root of the subtree to invalidate. The entry for the path
+     *     itself is removed along with all entries under `path + '/'`.
+     */
+    cache_invalidateTree(path) {
+        this.cache.delete(path);
+        const prefix = path.endsWith("/") ? path : `${path}/`;
+        for (const key of this.cache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.cache.delete(key);
+            }
+        }
+    }
     /**
      * @deprecated Use cache without cwd tracking. Cache persists across navigation.
      * This method is kept for backward compatibility but does nothing.

package/dist/cache/listCache.js.map

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

package/dist/cache/procCache.d.ts

@@ -2,11 +2,11 @@
  * @file Process Cache
  *
  * Session-scoped cache of ChRIS feed topology. Separates permanent data
- * (instance DAG structure) from volatile data (status — never stored).
+ * (instance DAG structure and terminal status) from volatile active status.
  *
  * Design decisions:
  * - Topology (id, feedID, parentID, pluginName) is permanent once written.
- * - Status is always fetched live from the API — never stored here.
+ * - Terminal status is immutable and checkpointed; active status refreshes live.
  * - Feed job counters (finishedJobs etc.) give aggregate feed status
  *   without per-instance API calls.
  * - topologyLoaded distinguishes "loaded but 0 instances" from "not yet loaded".
@@ -67,6 +67,12 @@ export interface ProcInstance {
     pluginType?: string;
     /** null until first cat — immutable once populated. */
     params: Record<string, unknown> | null;
+    /**
+     * Authoritative CUBE output directory, resolved lazily for the `/proc` data
+     * link. `undefined` means not looked up; `null` means CUBE reported none.
+     * This navigation convenience is deliberately excluded from checkpoints.
+     */
+    outputPath?: string | null;
     /**
      * Last known job status. Terminal statuses (see {@link PROC_TERMINAL_STATUSES})
      * are immutable and kept permanently; active statuses are refreshed live.
@@ -98,16 +104,39 @@ export declare function status_isTerminal(status: string | null | undefined): bo
  * total is zero until the server reports the visible plugin-instance count.
  * active becomes true when observable page progress begins, and false when the
  * sweep completes or aborts. Use the topology lifecycle to detect an earlier
- * running phase before the first page arrives.
+ * running state before the first page arrives.
  */
 export interface ProcWarmupProgress {
     loaded: number;
     total: number;
     active: boolean;
 }
+/** Availability and freshness states for the persistent process cache. */
+export type ProcCacheState = 'empty' | 'restored' | 'reconciling' | 'current' | 'failed';
 /**
- * Session-scoped cache of feed and instance topology.
- * Status is never stored — always fetched live from the API.
+ * Persistent process-cache freshness metadata.
+ *
+ * @property state - Current availability and reconciliation state.
+ * @property checkpointAt - ISO timestamp of the latest durable checkpoint.
+ */
+export interface ProcCacheLifecycle {
+    state: ProcCacheState;
+    checkpointAt?: string;
+}
+/**
+ * Serializable topology retained across daemon restarts.
+ *
+ * @property feeds - Visible feed metadata.
+ * @property instances - Normalized plugin-instance topology.
+ * @property topologyLoaded - Feed IDs whose instance topology is complete.
+ */
+export interface ProcCacheSnapshot {
+    feeds: ProcFeed[];
+    instances: ProcInstance[];
+    topologyLoaded: number[];
+}
+/**
+ * Session-scoped cache of feed and instance topology with restorable terminal state.
  */
 export declare class ProcCache {
     private static _instance;
@@ -124,10 +153,33 @@ export declare class ProcCache {
     private _warmupProgress;
     /** Whether initial feed index has been built. */
     private _built;
+    private lifecycle;
+    private listeners;
     private constructor();
     static instance_get(): ProcCache;
     get built(): boolean;
     get warmupComplete(): boolean;
+    /**
+     * Returns a copy of the current cache lifecycle metadata.
+     *
+     * @returns Current cache state and checkpoint timestamp.
+     */
+    lifecycle_get(): ProcCacheLifecycle;
+    /**
+     * Changes the cache freshness state.
+     *
+     * @param state - New lifecycle state.
+     * @returns Nothing.
+     */
+    lifecycle_set(state: ProcCacheState): void;
+    /**
+     * Registers a callback for checkpoint-worthy cache mutations.
+     *
+     * @param listener - Callback invoked after a cache mutation.
+     * @returns Function that unregisters the callback.
+     */
+    changeListener_add(listener: () => void): () => void;
+    private change_emit;
     /**
      * Adds or updates a feed entry.
      */
@@ -149,6 +201,14 @@ export declare class ProcCache {
      * Removes a feed and all its instances from the cache.
      */
     feed_remove(feedID: number): void;
+    /**
+     * Replaces the visible feed set while preserving topology for retained feeds.
+     *
+     * @param feeds - Authoritative feeds visible to the current identity.
+     * @returns IDs requiring topology reconciliation because they are new, their
+     *   aggregate job counts changed, or they still have active work.
+     */
+    feeds_reconcile(feeds: ProcFeed[]): number[];
     /**
      * Adds a plugin instance to the topology cache.
      */
@@ -169,10 +229,36 @@ export declare class ProcCache {
      * Removes an instance from the topology cache.
      */
     instance_remove(id: number): void;
+    /**
+     * Removes instances absent from an authoritative topology sweep.
+     *
+     * @param instanceIDs - Instance IDs returned by the completed CUBE sweep.
+     * @returns Nothing.
+     */
+    topology_reconcile(instanceIDs: Set<number>): void;
     /**
      * Updates cached params for an instance (on first cat).
      */
     params_update(id: number, params: Record<string, unknown>): void;
+    /**
+     * Stores the lazily resolved CUBE output path for one instance.
+     *
+     * @param id - Plugin-instance ID whose output location was resolved.
+     * @param outputPath - Absolute CFS output directory, or null when absent.
+     * @returns Nothing.
+     */
+    outputPath_update(id: number, outputPath: string | null): void;
+    /**
+     * Finds the closest cached job output containing a CFS path.
+     *
+     * An output path is a directory boundary: `/home/alice/run` contains
+     * `/home/alice/run/result.txt`, but not `/home/alice/run-old`.
+     *
+     * @param cfsPath - Absolute CFS path to resolve against live-session outputs.
+     * @returns The closest producing instance, or undefined when no output path
+     *   known in this session contains the path.
+     */
+    outputPath_match(cfsPath: string): ProcInstance | undefined;
     /**
      * Updates the cached status for an instance. Terminal (settled) statuses are
      * never overwritten — once finished, a job's status is immutable.
@@ -211,6 +297,12 @@ export declare class ProcCache {
     warmup_abort(): void;
     warmup_progress(loaded: number, total: number): void;
     warmupProgress_get(): ProcWarmupProgress;
+    /**
+     * Resets reconciliation progress while retaining restored topology.
+     *
+     * @returns Nothing.
+     */
+    warmup_reset(): void;
     /**
      * Reconstructs the full /proc/jobs path for a given instance ID.
      *
@@ -233,6 +325,27 @@ export declare class ProcCache {
      */
     instances_find(term: string): ProcInstance[];
     built_set(): void;
+    /**
+     * Creates a persistence-safe snapshot without parameters or active statuses.
+     *
+     * @returns Serializable feed and terminal-topology state.
+     */
+    snapshot_create(): ProcCacheSnapshot;
+    /**
+     * Replaces in-memory topology with a validated persistent snapshot.
+     *
+     * @param snapshot - Previously validated snapshot data.
+     * @param checkpointAt - ISO timestamp when the checkpoint was written.
+     * @returns Nothing.
+     */
+    snapshot_restore(snapshot: ProcCacheSnapshot, checkpointAt: string): void;
+    /**
+     * Records the timestamp of a successful durable save.
+     *
+     * @param checkpointAt - ISO timestamp written into the checkpoint.
+     * @returns Nothing.
+     */
+    checkpoint_mark(checkpointAt: string): void;
     /**
      * Clears all cache data. Called before a full rebuild.
      */

package/dist/cache/procCache.js

@@ -3,11 +3,11 @@
  * @file Process Cache
  *
  * Session-scoped cache of ChRIS feed topology. Separates permanent data
- * (instance DAG structure) from volatile data (status — never stored).
+ * (instance DAG structure and terminal status) from volatile active status.
  *
  * Design decisions:
  * - Topology (id, feedID, parentID, pluginName) is permanent once written.
- * - Status is always fetched live from the API — never stored here.
+ * - Terminal status is immutable and checkpointed; active status refreshes live.
  * - Feed job counters (finishedJobs etc.) give aggregate feed status
  *   without per-instance API calls.
  * - topologyLoaded distinguishes "loaded but 0 instances" from "not yet loaded".
@@ -21,6 +21,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProcCache = exports.PROC_TERMINAL_STATUSES = void 0;
 exports.status_isTerminal = status_isTerminal;
 exports.procCache_get = procCache_get;
+/** Feed counters whose changes can alter a feed's plugin-instance topology. */
+const FEED_TOPOLOGY_COUNTERS = [
+    'finishedJobs',
+    'erroredJobs',
+    'startedJobs',
+    'scheduledJobs',
+    'cancelledJobs',
+    'createdJobs',
+];
+/** Reports whether a feed has work which can still change after checkpointing. */
+function feed_isActive(feed) {
+    return feed.startedJobs > 0 || feed.scheduledJobs > 0 || feed.createdJobs > 0;
+}
+/** Reports whether two feed summaries indicate different instance topology. */
+function feedTopology_changed(previous, current) {
+    return FEED_TOPOLOGY_COUNTERS.some((counter) => previous[counter] !== current[counter]);
+}
 /**
  * Job statuses that never change once reached. An instance in one of these states
  * is settled — its status can be cached permanently rather than re-fetched.
@@ -40,8 +57,7 @@ function status_isTerminal(status) {
     return status != null && exports.PROC_TERMINAL_STATUSES.has(status);
 }
 /**
- * Session-scoped cache of feed and instance topology.
- * Status is never stored — always fetched live from the API.
+ * Session-scoped cache of feed and instance topology with restorable terminal state.
  */
 class ProcCache {
     constructor() {
@@ -58,6 +74,8 @@ class ProcCache {
         this._warmupProgress = { loaded: 0, total: 0, active: false };
         /** Whether initial feed index has been built. */
         this._built = false;
+        this.lifecycle = { state: 'empty' };
+        this.listeners = new Set();
     }
     static instance_get() {
         if (!ProcCache._instance) {
@@ -67,6 +85,36 @@ class ProcCache {
     }
     get built() { return this._built; }
     get warmupComplete() { return this._warmupComplete; }
+    /**
+     * Returns a copy of the current cache lifecycle metadata.
+     *
+     * @returns Current cache state and checkpoint timestamp.
+     */
+    lifecycle_get() { return { ...this.lifecycle }; }
+    /**
+     * Changes the cache freshness state.
+     *
+     * @param state - New lifecycle state.
+     * @returns Nothing.
+     */
+    lifecycle_set(state) {
+        this.lifecycle = { ...this.lifecycle, state };
+        this.change_emit();
+    }
+    /**
+     * Registers a callback for checkpoint-worthy cache mutations.
+     *
+     * @param listener - Callback invoked after a cache 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();
+    }
     // ── Feed ──────────────────────────────────────────────────────────────────
     /**
      * Adds or updates a feed entry.
@@ -76,6 +124,7 @@ class ProcCache {
         if (!this.feedRoots.has(feed.id)) {
             this.feedRoots.set(feed.id, []);
         }
+        this.change_emit();
     }
     feed_get(feedID) {
         return this.feeds.get(feedID);
@@ -119,6 +168,30 @@ class ProcCache {
             this.instance_remove(inst.id);
         }
         this.feedRoots.delete(feedID);
+        this.change_emit();
+    }
+    /**
+     * Replaces the visible feed set while preserving topology for retained feeds.
+     *
+     * @param feeds - Authoritative feeds visible to the current identity.
+     * @returns IDs requiring topology reconciliation because they are new, their
+     *   aggregate job counts changed, or they still have active work.
+     */
+    feeds_reconcile(feeds) {
+        const reconciliationTargets = [];
+        const visible = new Set(feeds.map((feed) => feed.id));
+        for (const feedID of this.feedIDs_get()) {
+            if (!visible.has(feedID))
+                this.feed_remove(feedID);
+        }
+        for (const feed of feeds) {
+            const previous = this.feed_get(feed.id);
+            if (!previous || feedTopology_changed(previous, feed) || feed_isActive(feed)) {
+                reconciliationTargets.push(feed.id);
+            }
+            this.feed_add(feed);
+        }
+        return reconciliationTargets;
     }
     // ── Instance ──────────────────────────────────────────────────────────────
     /**
@@ -140,6 +213,7 @@ class ProcCache {
                 this.children.set(inst.parentID, kids);
             }
         }
+        this.change_emit();
     }
     instance_get(id) {
         return this.instances.get(id);
@@ -191,6 +265,22 @@ class ProcCache {
             const kids = this.children.get(inst.parentID) ?? [];
             this.children.set(inst.parentID, kids.filter((k) => k !== id));
         }
+        this.change_emit();
+    }
+    /**
+     * Removes instances absent from an authoritative topology sweep.
+     *
+     * @param instanceIDs - Instance IDs returned by the completed CUBE sweep.
+     * @returns Nothing.
+     */
+    topology_reconcile(instanceIDs) {
+        for (const id of Array.from(this.instances.keys())) {
+            if (!instanceIDs.has(id))
+                this.instance_remove(id);
+        }
+        for (const feedID of this.feedIDs_get())
+            this.topologyLoaded.add(feedID);
+        this.change_emit();
     }
     /**
      * Updates cached params for an instance (on first cat).
@@ -200,6 +290,46 @@ class ProcCache {
         if (inst)
             inst.params = params;
     }
+    /**
+     * Stores the lazily resolved CUBE output path for one instance.
+     *
+     * @param id - Plugin-instance ID whose output location was resolved.
+     * @param outputPath - Absolute CFS output directory, or null when absent.
+     * @returns Nothing.
+     */
+    outputPath_update(id, outputPath) {
+        const inst = this.instances.get(id);
+        if (inst)
+            inst.outputPath = outputPath;
+    }
+    /**
+     * Finds the closest cached job output containing a CFS path.
+     *
+     * An output path is a directory boundary: `/home/alice/run` contains
+     * `/home/alice/run/result.txt`, but not `/home/alice/run-old`.
+     *
+     * @param cfsPath - Absolute CFS path to resolve against live-session outputs.
+     * @returns The closest producing instance, or undefined when no output path
+     *   known in this session contains the path.
+     */
+    outputPath_match(cfsPath) {
+        const cleanPath = cfsPath.length > 1 && cfsPath.endsWith('/')
+            ? cfsPath.slice(0, -1)
+            : cfsPath;
+        let closest;
+        for (const inst of this.instances.values()) {
+            const outputPath = inst.outputPath;
+            if (!outputPath)
+                continue;
+            const isAncestor = outputPath === '/'
+                ? cleanPath.startsWith('/')
+                : cleanPath === outputPath || cleanPath.startsWith(`${outputPath}/`);
+            if (isAncestor && (!closest || outputPath.length > (closest.outputPath?.length ?? 0))) {
+                closest = inst;
+            }
+        }
+        return closest;
+    }
     /**
      * Updates the cached status for an instance. Terminal (settled) statuses are
      * never overwritten — once finished, a job's status is immutable.
@@ -213,7 +343,10 @@ class ProcCache {
             return;
         if (status_isTerminal(inst.status))
             return;
-        inst.status = status;
+        if (inst.status !== status) {
+            inst.status = status;
+            this.change_emit();
+        }
     }
     /**
      * Records the resolved topological-join parent IDs for a `ts` instance. Immutable
@@ -224,8 +357,10 @@ class ProcCache {
      */
     joinParents_update(id, ids) {
         const inst = this.instances.get(id);
-        if (inst)
+        if (inst) {
             inst.joinParentIDs = ids;
+            this.change_emit();
+        }
     }
     /**
      * Returns the resolved join parent IDs for an instance, or an empty array when the
@@ -240,6 +375,7 @@ class ProcCache {
     // ── Topology loaded tracking ───────────────────────────────────────────────
     topologyLoaded_mark(feedID) {
         this.topologyLoaded.add(feedID);
+        this.change_emit();
     }
     topologyLoaded_has(feedID) {
         return this.topologyLoaded.has(feedID);
@@ -258,6 +394,8 @@ class ProcCache {
     warmup_complete() {
         this._warmupComplete = true;
         this._warmupProgress = { ...this._warmupProgress, active: false };
+        this.lifecycle = { ...this.lifecycle, state: 'current' };
+        this.change_emit();
     }
     /**
      * Stops an unsuccessful warm-up without marking its topology complete.
@@ -267,6 +405,8 @@ class ProcCache {
     warmup_abort() {
         this._warmupComplete = false;
         this._warmupProgress = { ...this._warmupProgress, active: false };
+        this.lifecycle = { ...this.lifecycle, state: 'failed' };
+        this.change_emit();
     }
     warmup_progress(loaded, total) {
         this._warmupProgress = { loaded, total, active: true };
@@ -274,6 +414,19 @@ class ProcCache {
     warmupProgress_get() {
         return { ...this._warmupProgress };
     }
+    /**
+     * Resets reconciliation progress while retaining restored topology.
+     *
+     * @returns Nothing.
+     */
+    warmup_reset() {
+        this._warmupComplete = false;
+        this._warmupProgress = { loaded: this.instances.size, total: this.instances.size, active: false };
+        this.lifecycle = this.lifecycle.checkpointAt
+            ? { ...this.lifecycle, state: 'restored' }
+            : { state: 'empty' };
+        this.change_emit();
+    }
     // ── Path reconstruction ───────────────────────────────────────────────────
     /**
      * Reconstructs the full /proc/jobs path for a given instance ID.
@@ -327,6 +480,58 @@ class ProcCache {
     built_set() {
         this._built = true;
     }
+    /**
+     * Creates a persistence-safe snapshot without parameters or active statuses.
+     *
+     * @returns Serializable feed and terminal-topology state.
+     */
+    snapshot_create() {
+        const instances = Array.from(this.instances.values()).map((inst) => {
+            const { outputPath: _outputPath, ...persistent } = inst;
+            return {
+                ...persistent,
+                params: null,
+                status: status_isTerminal(inst.status) ? inst.status : null,
+                joinParentIDs: inst.joinParentIDs ? [...inst.joinParentIDs] : undefined,
+            };
+        });
+        return {
+            feeds: Array.from(this.feeds.values()).map((feed) => ({ ...feed })),
+            instances,
+            topologyLoaded: Array.from(this.topologyLoaded),
+        };
+    }
+    /**
+     * Replaces in-memory topology with a validated persistent snapshot.
+     *
+     * @param snapshot - Previously validated snapshot data.
+     * @param checkpointAt - ISO timestamp when the checkpoint was written.
+     * @returns Nothing.
+     */
+    snapshot_restore(snapshot, checkpointAt) {
+        this.cache_clear();
+        for (const feed of snapshot.feeds) {
+            this.feeds.set(feed.id, { ...feed });
+            this.feedRoots.set(feed.id, []);
+        }
+        for (const inst of snapshot.instances) {
+            const { outputPath: _outputPath, ...restored } = inst;
+            this.instance_add({ ...restored, params: null, status: status_isTerminal(inst.status) ? inst.status : null });
+        }
+        this.topologyLoaded = new Set(snapshot.topologyLoaded.filter((id) => this.feeds.has(id)));
+        this._warmupProgress = { loaded: this.instances.size, total: this.instances.size, active: false };
+        this.lifecycle = { state: 'restored', checkpointAt };
+        this.change_emit();
+    }
+    /**
+     * Records the timestamp of a successful durable save.
+     *
+     * @param checkpointAt - ISO timestamp written into the checkpoint.
+     * @returns Nothing.
+     */
+    checkpoint_mark(checkpointAt) {
+        this.lifecycle = { ...this.lifecycle, checkpointAt };
+    }
     /**
      * Clears all cache data. Called before a full rebuild.
      */
@@ -340,6 +545,8 @@ class ProcCache {
         this._warmupComplete = false;
         this._warmupProgress = { loaded: 0, total: 0, active: false };
         this._built = false;
+        this.lifecycle = { state: 'empty' };
+        this.change_emit();
     }
 }
 exports.ProcCache = ProcCache;