@fnndsc/cumin 3.17.1 → 3.18.0

package/dist/cache/index.d.ts

@@ -7,6 +7,10 @@ export { ListCache, listCache_get, LIST_CACHE_SIGNAL_BACKED_TTL_MS, LIST_CACHE_S
 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 { QueryIndex, queryIndex_get, queryKey_build, queryCriteria_parse, } from './queryIndex.js';
+export type { QueryIndexEntry, QueryIndexEntrySnapshot, QueryIndexSnapshot, QueryIndexListener, } from './queryIndex.js';
+export { queryIndexCheckpointPath_get, queryIndexCheckpoint_restore, queryIndexCheckpoint_save, queryIndexCheckpoint_watch, QUERY_INDEX_CHECKPOINT_FLOOR_MS, } from './queryIndexCheckpoint.js';
+export type { QueryIndexRestoreResult } from './queryIndexCheckpoint.js';
 export { listingsForFeeds_note, listingsForFeeds_drop, listingsForRoster_note, listingInvalidation_flush, listingInvalidation_reset, LISTING_INVALIDATION_WINDOW_MS, } from './listingInvalidation.js';
 export { ProcCache, procCache_get, status_isTerminal, feed_isActive, feedTopology_changed, PROC_TERMINAL_STATUSES, PROC_ARRIVAL_TTL_MS } from './procCache.js';
 export type { RosterFolders, ProcInstance, ProcFeed, ProcFeedScopeCounts, ProcWarmupProgress, ProcFeedLoadProgress, ProcCacheState, ProcCacheLifecycle, ProcCacheSnapshot, ProcFeedSnapshot, ProcCacheChange, ProcCacheListener, } from './procCache.js';

package/dist/cache/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.procCheckpoint_watch = exports.procCheckpointRoster_save = exports.procCheckpointFeed_save = exports.procCheckpoint_save = exports.procCheckpoint_restore = exports.procCheckpointDir_get = exports.procCheckpointPath_get = exports.PROC_ARRIVAL_TTL_MS = exports.PROC_TERMINAL_STATUSES = exports.feedTopology_changed = exports.feed_isActive = exports.status_isTerminal = exports.procCache_get = exports.ProcCache = exports.LISTING_INVALIDATION_WINDOW_MS = exports.listingInvalidation_reset = exports.listingInvalidation_flush = exports.listingsForRoster_note = exports.listingsForFeeds_drop = exports.listingsForFeeds_note = exports.listCheckpoint_watch = exports.listCheckpoint_save = exports.listCheckpoint_restore = exports.listCheckpointPath_get = exports.LIST_CACHE_MAX_ENTRIES = exports.LIST_CACHE_PLUGIN_INDEX_TTL_MS = exports.LIST_CACHE_SIGNAL_FREE_TTL_MS = exports.LIST_CACHE_SIGNAL_BACKED_TTL_MS = 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_ARRIVAL_TTL_MS = exports.PROC_TERMINAL_STATUSES = exports.feedTopology_changed = exports.feed_isActive = exports.status_isTerminal = exports.procCache_get = exports.ProcCache = exports.LISTING_INVALIDATION_WINDOW_MS = exports.listingInvalidation_reset = exports.listingInvalidation_flush = exports.listingsForRoster_note = exports.listingsForFeeds_drop = exports.listingsForFeeds_note = exports.QUERY_INDEX_CHECKPOINT_FLOOR_MS = exports.queryIndexCheckpoint_watch = exports.queryIndexCheckpoint_save = exports.queryIndexCheckpoint_restore = exports.queryIndexCheckpointPath_get = exports.queryCriteria_parse = exports.queryKey_build = exports.queryIndex_get = exports.QueryIndex = exports.listCheckpoint_watch = exports.listCheckpoint_save = exports.listCheckpoint_restore = exports.listCheckpointPath_get = exports.LIST_CACHE_MAX_ENTRIES = exports.LIST_CACHE_PLUGIN_INDEX_TTL_MS = exports.LIST_CACHE_SIGNAL_FREE_TTL_MS = exports.LIST_CACHE_SIGNAL_BACKED_TTL_MS = exports.listCache_get = exports.ListCache = void 0;
 /**
  * @file Cache module exports.
  *
@@ -18,6 +18,17 @@ Object.defineProperty(exports, "listCheckpointPath_get", { enumerable: true, 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 queryIndex_js_1 = require("./queryIndex.js");
+Object.defineProperty(exports, "QueryIndex", { enumerable: true, get: function () { return queryIndex_js_1.QueryIndex; } });
+Object.defineProperty(exports, "queryIndex_get", { enumerable: true, get: function () { return queryIndex_js_1.queryIndex_get; } });
+Object.defineProperty(exports, "queryKey_build", { enumerable: true, get: function () { return queryIndex_js_1.queryKey_build; } });
+Object.defineProperty(exports, "queryCriteria_parse", { enumerable: true, get: function () { return queryIndex_js_1.queryCriteria_parse; } });
+var queryIndexCheckpoint_js_1 = require("./queryIndexCheckpoint.js");
+Object.defineProperty(exports, "queryIndexCheckpointPath_get", { enumerable: true, get: function () { return queryIndexCheckpoint_js_1.queryIndexCheckpointPath_get; } });
+Object.defineProperty(exports, "queryIndexCheckpoint_restore", { enumerable: true, get: function () { return queryIndexCheckpoint_js_1.queryIndexCheckpoint_restore; } });
+Object.defineProperty(exports, "queryIndexCheckpoint_save", { enumerable: true, get: function () { return queryIndexCheckpoint_js_1.queryIndexCheckpoint_save; } });
+Object.defineProperty(exports, "queryIndexCheckpoint_watch", { enumerable: true, get: function () { return queryIndexCheckpoint_js_1.queryIndexCheckpoint_watch; } });
+Object.defineProperty(exports, "QUERY_INDEX_CHECKPOINT_FLOOR_MS", { enumerable: true, get: function () { return queryIndexCheckpoint_js_1.QUERY_INDEX_CHECKPOINT_FLOOR_MS; } });
 var listingInvalidation_js_1 = require("./listingInvalidation.js");
 Object.defineProperty(exports, "listingsForFeeds_note", { enumerable: true, get: function () { return listingInvalidation_js_1.listingsForFeeds_note; } });
 Object.defineProperty(exports, "listingsForFeeds_drop", { enumerable: true, get: function () { return listingInvalidation_js_1.listingsForFeeds_drop; } });

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,+CAOwB;AANtB,yGAAA,SAAS,OAAA;AACT,6GAAA,aAAa,OAAA;AACb,+HAAA,+BAA+B,OAAA;AAC/B,6HAAA,6BAA6B,OAAA;AAC7B,8HAAA,8BAA8B,OAAA;AAC9B,sHAAA,sBAAsB,OAAA;AAGxB,yDAK6B;AAJ3B,2HAAA,sBAAsB,OAAA;AACtB,2HAAA,sBAAsB,OAAA;AACtB,wHAAA,mBAAmB,OAAA;AACnB,yHAAA,oBAAoB,OAAA;AAGtB,mEAOkC;AANhC,+HAAA,qBAAqB,OAAA;AACrB,+HAAA,qBAAqB,OAAA;AACrB,gIAAA,sBAAsB,OAAA;AACtB,mIAAA,yBAAyB,OAAA;AACzB,mIAAA,yBAAyB,OAAA;AACzB,wIAAA,8BAA8B,OAAA;AAEhC,+CAA+J;AAAtJ,yGAAA,SAAS,OAAA;AAAE,6GAAA,aAAa,OAAA;AAAE,iHAAA,iBAAiB,OAAA;AAAE,6GAAA,aAAa,OAAA;AAAE,oHAAA,oBAAoB,OAAA;AAAE,sHAAA,sBAAsB,OAAA;AAAE,mHAAA,mBAAmB,OAAA;AA0BtI,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,+CAOwB;AANtB,yGAAA,SAAS,OAAA;AACT,6GAAA,aAAa,OAAA;AACb,+HAAA,+BAA+B,OAAA;AAC/B,6HAAA,6BAA6B,OAAA;AAC7B,8HAAA,8BAA8B,OAAA;AAC9B,sHAAA,sBAAsB,OAAA;AAGxB,yDAK6B;AAJ3B,2HAAA,sBAAsB,OAAA;AACtB,2HAAA,sBAAsB,OAAA;AACtB,wHAAA,mBAAmB,OAAA;AACnB,yHAAA,oBAAoB,OAAA;AAGtB,iDAKyB;AAJvB,2GAAA,UAAU,OAAA;AACV,+GAAA,cAAc,OAAA;AACd,+GAAA,cAAc,OAAA;AACd,oHAAA,mBAAmB,OAAA;AAQrB,qEAMmC;AALjC,uIAAA,4BAA4B,OAAA;AAC5B,uIAAA,4BAA4B,OAAA;AAC5B,oIAAA,yBAAyB,OAAA;AACzB,qIAAA,0BAA0B,OAAA;AAC1B,0IAAA,+BAA+B,OAAA;AAGjC,mEAOkC;AANhC,+HAAA,qBAAqB,OAAA;AACrB,+HAAA,qBAAqB,OAAA;AACrB,gIAAA,sBAAsB,OAAA;AACtB,mIAAA,yBAAyB,OAAA;AACzB,mIAAA,yBAAyB,OAAA;AACzB,wIAAA,8BAA8B,OAAA;AAEhC,+CAA+J;AAAtJ,yGAAA,SAAS,OAAA;AAAE,6GAAA,aAAa,OAAA;AAAE,iHAAA,iBAAiB,OAAA;AAAE,6GAAA,aAAa,OAAA;AAAE,oHAAA,oBAAoB,OAAA;AAAE,sHAAA,sBAAsB,OAAA;AAAE,mHAAA,mBAAmB,OAAA;AA0BtI,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/queryIndex.d.ts

@@ -0,0 +1,207 @@
+/**
+ * @file The PACS query index: what has already been asked, and answered.
+ *
+ * CUBE keeps every PACS query it has run, criteria and result both, so a
+ * question asked before need not be asked again. It cannot be *searched*
+ * for, though: the queries collection accepts no parameter over the stored
+ * criteria, and every row of every page drags its compressed result along —
+ * kilobytes each, thousands of rows. Looking a question up by sweeping that
+ * collection would cost megabytes, and would cost them most often on a
+ * MISS, which is the common case for a genuinely new query. A client that
+ * searched naively would make every new query slower than not searching.
+ *
+ * So the collection is walked once, in the background, and what is learned
+ * is kept here: criteria and server in, the stored query's id out. A lookup
+ * is then a map read.
+ *
+ * The index is ADVISORY. A hit is a claim to be confirmed — the caller
+ * decodes the stored result before serving it, and any failure (the query
+ * deleted, the result unreadable) falls through to a fresh query. A stale
+ * entry can therefore cost a wasted lookup and never a wrong answer, which
+ * is what makes it safe to keep across restarts and to fill lazily.
+ *
+ * It is also the log itself. Each entry carries the criteria and owner the
+ * VFS renders into `/net/pacs/queries/<name>`, so that listing can be
+ * served from here — complete, rather than the first page of it.
+ *
+ * @module
+ */
+/** What the index knows about one stored query. */
+export interface QueryIndexEntry {
+    /** The stored CUBE query's id — what a replay decodes. */
+    queryId: number;
+    /** The PACS this was asked of; part of the key, kept for the listing. */
+    server: string;
+    /** The criteria as asked, for rebuilding the log's display name. */
+    criteria: Record<string, string>;
+    /** Who asked. Part of the log's display name. */
+    owner: string;
+    /** When the query record was created — the age a replay states. */
+    answeredAt: string;
+    /**
+     * Whether it found anything.
+     *
+     * A query that found nothing is indexed *as such* rather than omitted,
+     * so a replay can refuse it knowingly. An absence decays where a hit does
+     * not: the patient is scanned next week, and "no imaging found" is the
+     * answer a clinician acts on.
+     */
+    hasResult: boolean;
+}
+/** One entry with the key it is filed under. */
+export interface QueryIndexEntrySnapshot extends QueryIndexEntry {
+    key: string;
+}
+/** The whole index, and how far the back-fill has walked. */
+export interface QueryIndexSnapshot {
+    entries: QueryIndexEntrySnapshot[];
+    /**
+     * The oldest record the back-fill has reached, as an ISO timestamp.
+     *
+     * The sweep walks newest first, so this is where it resumes — everything
+     * newer is already held. Null before the first sweep.
+     */
+    floor: string | null;
+}
+/** Told after any mutation, so a checkpoint writer can debounce on it. */
+export type QueryIndexListener = () => void;
+/**
+ * Builds the key a question is filed under.
+ *
+ * Two questions are the same question when their criteria sets are equal
+ * and they were asked of the same PACS. Key order and surrounding
+ * whitespace are normalized away because they are how the question was
+ * *typed*, not what it asked. Values are otherwise left exactly as given:
+ * they are the PACS's own vocabulary, and mise does not get to reinterpret
+ * them — a case fold here would silently claim that two DICOM values match
+ * when only the PACS can say so.
+ *
+ * The owner is part of the question. The index holds the whole log —
+ * every identity's queries, because that is what `/net/pacs/queries` lists
+ * — while a replay may only ever serve back an answer to the identity that
+ * asked for it. Keying by owner makes those two facts one lookup instead of
+ * a filter somebody can forget.
+ *
+ * @param criteria - The criteria as asked.
+ * @param server - The PACS identifier the query was asked of.
+ * @param owner - The identity that asked.
+ * @returns The key, stable for equal questions.
+ */
+export declare function queryKey_build(criteria: Record<string, string>, server: string, owner: string): string;
+/**
+ * Parses the criteria CUBE stores as a JSON string on a query record.
+ *
+ * @param raw - The record's `query` field.
+ * @returns The criteria, or null when the field is absent or unparseable.
+ */
+export declare function queryCriteria_parse(raw: unknown): Record<string, string> | null;
+/**
+ * What has already been asked of which PACS, and where the answer is kept.
+ */
+export declare class QueryIndex {
+    /**
+     * Every record, by its query id. This is the log: asking the same thing
+     * twice leaves two records, and both remain reachable.
+     */
+    private entries;
+    /**
+     * Question to the newest record answering it. This is the lookup: a
+     * replay wants the most recent answer, not every answer.
+     */
+    private byQuestion;
+    private floor;
+    private listeners;
+    /**
+     * Files a query under its question.
+     *
+     * The newest answer to a question wins: asking the same thing twice
+     * leaves the later record indexed, which is the one whose age a replay
+     * should state.
+     *
+     * @param entry - What was asked, of whom, and what came back.
+     */
+    entry_note(entry: QueryIndexEntry): void;
+    /**
+     * Looks a question up.
+     *
+     * @param criteria - The criteria being asked.
+     * @param server - The PACS being asked.
+     * @param owner - The identity asking; another identity's answer is not
+     *   an answer to this question.
+     * @returns What is known, or null when this question is new to the index.
+     */
+    entry_find(criteria: Record<string, string>, server: string, owner: string): QueryIndexEntry | null;
+    /**
+     * Forgets one query, for when its stored answer turns out to be gone.
+     *
+     * @param criteria - The criteria it was filed under.
+     * @param server - The PACS it was asked of.
+     * @param owner - The identity that asked.
+     */
+    entry_drop(criteria: Record<string, string>, server: string, owner: string): void;
+    /**
+     * Every record, for the callers that render the log rather than search it.
+     *
+     * This is the whole log — every query, not one per question — because
+     * that is what `/net/pacs/queries` lists and what an operator went
+     * looking for when they could not find a query they knew they had run.
+     */
+    entries_all(): QueryIndexEntry[];
+    /** How many records the index holds. */
+    size_get(): number;
+    /** How many distinct questions those records answer. */
+    questions_count(): number;
+    /**
+     * The newest record held, which is where a resumed sweep starts.
+     *
+     * A completed sweep has walked everything down to the floor, so the only
+     * thing a later boot can be missing is what arrived since. Asking CUBE
+     * for records at or after this turns a rebuild into a top-up.
+     *
+     * @returns An ISO timestamp, or null when the index is empty.
+     */
+    newest_get(): string | null;
+    /**
+     * The oldest record the back-fill has walked, where it resumes.
+     *
+     * @returns An ISO timestamp, or null before the first sweep.
+     */
+    floor_get(): string | null;
+    /**
+     * Records how far back the sweep has reached.
+     *
+     * @param at - The oldest record walked, as an ISO timestamp.
+     */
+    floor_set(at: string): void;
+    /**
+     * Creates a persistence-safe copy.
+     *
+     * @returns The snapshot.
+     */
+    snapshot_create(): QueryIndexSnapshot;
+    /**
+     * Merges a snapshot in, keeping anything this process already learned:
+     * a query indexed since the checkpoint was written is newer than the
+     * checkpoint by definition.
+     *
+     * @param snapshot - A validated snapshot.
+     */
+    snapshot_restore(snapshot: QueryIndexSnapshot): void;
+    /**
+     * Registers a listener told after any mutation.
+     *
+     * @param listener - The listener.
+     * @returns A function that removes it.
+     */
+    changeListener_add(listener: QueryIndexListener): () => void;
+    /** Empties the index. For tests, and for a change of identity. */
+    reset(): void;
+    /** Tells every listener. A listener that throws must not stop the rest. */
+    private change_emit;
+}
+/**
+ * The process-wide query index.
+ *
+ * @returns The singleton.
+ */
+export declare function queryIndex_get(): QueryIndex;

package/dist/cache/queryIndex.js

@@ -0,0 +1,314 @@
+"use strict";
+/**
+ * @file The PACS query index: what has already been asked, and answered.
+ *
+ * CUBE keeps every PACS query it has run, criteria and result both, so a
+ * question asked before need not be asked again. It cannot be *searched*
+ * for, though: the queries collection accepts no parameter over the stored
+ * criteria, and every row of every page drags its compressed result along —
+ * kilobytes each, thousands of rows. Looking a question up by sweeping that
+ * collection would cost megabytes, and would cost them most often on a
+ * MISS, which is the common case for a genuinely new query. A client that
+ * searched naively would make every new query slower than not searching.
+ *
+ * So the collection is walked once, in the background, and what is learned
+ * is kept here: criteria and server in, the stored query's id out. A lookup
+ * is then a map read.
+ *
+ * The index is ADVISORY. A hit is a claim to be confirmed — the caller
+ * decodes the stored result before serving it, and any failure (the query
+ * deleted, the result unreadable) falls through to a fresh query. A stale
+ * entry can therefore cost a wasted lookup and never a wrong answer, which
+ * is what makes it safe to keep across restarts and to fill lazily.
+ *
+ * It is also the log itself. Each entry carries the criteria and owner the
+ * VFS renders into `/net/pacs/queries/<name>`, so that listing can be
+ * served from here — complete, rather than the first page of it.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryIndex = void 0;
+exports.queryKey_build = queryKey_build;
+exports.queryCriteria_parse = queryCriteria_parse;
+exports.queryIndex_get = queryIndex_get;
+/**
+ * Separates the server from the criteria in a key, and one criterion from
+ * the next.
+ *
+ * ASCII record and unit separators, written as escapes: a PACS identifier
+ * or a DICOM value may contain anything printable — including the spaces,
+ * colons and commas that would otherwise let two different questions
+ * collide on one key.
+ */
+const KEY_SERVER_SEPARATOR = '\u001e';
+/** Separates one criterion from the next in a key. */
+const KEY_PAIR_SEPARATOR = '\u001f';
+/**
+ * Builds the key a question is filed under.
+ *
+ * Two questions are the same question when their criteria sets are equal
+ * and they were asked of the same PACS. Key order and surrounding
+ * whitespace are normalized away because they are how the question was
+ * *typed*, not what it asked. Values are otherwise left exactly as given:
+ * they are the PACS's own vocabulary, and mise does not get to reinterpret
+ * them — a case fold here would silently claim that two DICOM values match
+ * when only the PACS can say so.
+ *
+ * The owner is part of the question. The index holds the whole log —
+ * every identity's queries, because that is what `/net/pacs/queries` lists
+ * — while a replay may only ever serve back an answer to the identity that
+ * asked for it. Keying by owner makes those two facts one lookup instead of
+ * a filter somebody can forget.
+ *
+ * @param criteria - The criteria as asked.
+ * @param server - The PACS identifier the query was asked of.
+ * @param owner - The identity that asked.
+ * @returns The key, stable for equal questions.
+ */
+function queryKey_build(criteria, server, owner) {
+    const pairs = [];
+    for (const [name, value] of Object.entries(criteria)) {
+        const key = name.trim();
+        const held = String(value ?? '').trim();
+        if (key.length === 0 || held.length === 0)
+            continue;
+        pairs.push(`${key}=${held}`);
+    }
+    pairs.sort();
+    return `${owner.trim()}${KEY_SERVER_SEPARATOR}${server.trim()}${KEY_SERVER_SEPARATOR}${pairs.join(KEY_PAIR_SEPARATOR)}`;
+}
+/**
+ * Parses the criteria CUBE stores as a JSON string on a query record.
+ *
+ * @param raw - The record's `query` field.
+ * @returns The criteria, or null when the field is absent or unparseable.
+ */
+function queryCriteria_parse(raw) {
+    if (typeof raw !== 'string' || raw.trim().length === 0)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        const criteria = {};
+        for (const [name, value] of Object.entries(parsed)) {
+            if (value === undefined || value === null)
+                continue;
+            criteria[name] = String(value);
+        }
+        return criteria;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What has already been asked of which PACS, and where the answer is kept.
+ */
+class QueryIndex {
+    constructor() {
+        /**
+         * Every record, by its query id. This is the log: asking the same thing
+         * twice leaves two records, and both remain reachable.
+         */
+        this.entries = new Map();
+        /**
+         * Question to the newest record answering it. This is the lookup: a
+         * replay wants the most recent answer, not every answer.
+         */
+        this.byQuestion = new Map();
+        this.floor = null;
+        this.listeners = new Set();
+    }
+    /**
+     * Files a query under its question.
+     *
+     * The newest answer to a question wins: asking the same thing twice
+     * leaves the later record indexed, which is the one whose age a replay
+     * should state.
+     *
+     * @param entry - What was asked, of whom, and what came back.
+     */
+    entry_note(entry) {
+        this.entries.set(entry.queryId, entry);
+        const key = queryKey_build(entry.criteria, entry.server, entry.owner);
+        const heldId = this.byQuestion.get(key);
+        const held = heldId === undefined ? undefined : this.entries.get(heldId);
+        // Strictly newer, so a tie leaves the incumbent in place: what this
+        // process learned outranks what a restored checkpoint claims.
+        if (held === undefined || Date.parse(entry.answeredAt) > Date.parse(held.answeredAt)) {
+            this.byQuestion.set(key, entry.queryId);
+        }
+        this.change_emit();
+    }
+    /**
+     * Looks a question up.
+     *
+     * @param criteria - The criteria being asked.
+     * @param server - The PACS being asked.
+     * @param owner - The identity asking; another identity's answer is not
+     *   an answer to this question.
+     * @returns What is known, or null when this question is new to the index.
+     */
+    entry_find(criteria, server, owner) {
+        const queryId = this.byQuestion.get(queryKey_build(criteria, server, owner));
+        if (queryId === undefined)
+            return null;
+        return this.entries.get(queryId) ?? null;
+    }
+    /**
+     * Forgets one query, for when its stored answer turns out to be gone.
+     *
+     * @param criteria - The criteria it was filed under.
+     * @param server - The PACS it was asked of.
+     * @param owner - The identity that asked.
+     */
+    entry_drop(criteria, server, owner) {
+        const key = queryKey_build(criteria, server, owner);
+        const queryId = this.byQuestion.get(key);
+        if (queryId === undefined)
+            return;
+        this.byQuestion.delete(key);
+        this.entries.delete(queryId);
+        // An older record may still answer this question; the newest of what
+        // is left takes the pointer back.
+        let heir = null;
+        for (const entry of this.entries.values()) {
+            if (queryKey_build(entry.criteria, entry.server, entry.owner) !== key)
+                continue;
+            if (heir === null || Date.parse(entry.answeredAt) > Date.parse(heir.answeredAt))
+                heir = entry;
+        }
+        if (heir !== null)
+            this.byQuestion.set(key, heir.queryId);
+        this.change_emit();
+    }
+    /**
+     * Every record, for the callers that render the log rather than search it.
+     *
+     * This is the whole log — every query, not one per question — because
+     * that is what `/net/pacs/queries` lists and what an operator went
+     * looking for when they could not find a query they knew they had run.
+     */
+    entries_all() {
+        return [...this.entries.values()];
+    }
+    /** How many records the index holds. */
+    size_get() {
+        return this.entries.size;
+    }
+    /** How many distinct questions those records answer. */
+    questions_count() {
+        return this.byQuestion.size;
+    }
+    /**
+     * The newest record held, which is where a resumed sweep starts.
+     *
+     * A completed sweep has walked everything down to the floor, so the only
+     * thing a later boot can be missing is what arrived since. Asking CUBE
+     * for records at or after this turns a rebuild into a top-up.
+     *
+     * @returns An ISO timestamp, or null when the index is empty.
+     */
+    newest_get() {
+        let newest = null;
+        for (const entry of this.entries.values()) {
+            if (newest === null || Date.parse(entry.answeredAt) > Date.parse(newest)) {
+                newest = entry.answeredAt;
+            }
+        }
+        return newest;
+    }
+    /**
+     * The oldest record the back-fill has walked, where it resumes.
+     *
+     * @returns An ISO timestamp, or null before the first sweep.
+     */
+    floor_get() {
+        return this.floor;
+    }
+    /**
+     * Records how far back the sweep has reached.
+     *
+     * @param at - The oldest record walked, as an ISO timestamp.
+     */
+    floor_set(at) {
+        if (this.floor !== null && Date.parse(this.floor) <= Date.parse(at))
+            return;
+        this.floor = at;
+        this.change_emit();
+    }
+    /**
+     * Creates a persistence-safe copy.
+     *
+     * @returns The snapshot.
+     */
+    snapshot_create() {
+        const entries = [];
+        for (const entry of this.entries.values()) {
+            entries.push({ key: queryKey_build(entry.criteria, entry.server, entry.owner), ...entry });
+        }
+        return { entries, floor: this.floor };
+    }
+    /**
+     * Merges a snapshot in, keeping anything this process already learned:
+     * a query indexed since the checkpoint was written is newer than the
+     * checkpoint by definition.
+     *
+     * @param snapshot - A validated snapshot.
+     */
+    snapshot_restore(snapshot) {
+        for (const entry of snapshot.entries) {
+            if (this.entries.has(entry.queryId))
+                continue;
+            const { key: _key, ...held } = entry;
+            this.entry_note(held);
+        }
+        if (snapshot.floor !== null && (this.floor === null || Date.parse(snapshot.floor) < Date.parse(this.floor))) {
+            this.floor = snapshot.floor;
+        }
+        this.change_emit();
+    }
+    /**
+     * Registers a listener told after any mutation.
+     *
+     * @param listener - The listener.
+     * @returns A function that removes it.
+     */
+    changeListener_add(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /** Empties the index. For tests, and for a change of identity. */
+    reset() {
+        this.entries.clear();
+        this.byQuestion.clear();
+        this.floor = null;
+        this.change_emit();
+    }
+    /** Tells every listener. A listener that throws must not stop the rest. */
+    change_emit() {
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch {
+                /* a listener's failure is its own */
+            }
+        }
+    }
+}
+exports.QueryIndex = QueryIndex;
+let queryIndex = null;
+/**
+ * The process-wide query index.
+ *
+ * @returns The singleton.
+ */
+function queryIndex_get() {
+    if (queryIndex === null)
+        queryIndex = new QueryIndex();
+    return queryIndex;
+}
+//# sourceMappingURL=queryIndex.js.map

package/dist/cache/queryIndex.js.map

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

package/dist/cache/queryIndexCheckpoint.d.ts

@@ -0,0 +1,55 @@
+/** Minimum spacing between two writes of the query-index checkpoint. */
+export declare const QUERY_INDEX_CHECKPOINT_FLOOR_MS: number;
+/**
+ * Outcome of attempting to restore a query-index checkpoint.
+ *
+ * @property restored - Whether validated entries reached the index.
+ * @property count - Number of restored queries.
+ * @property writtenAt - Checkpoint creation time when restoration succeeded.
+ * @property reason - Human-readable reason when restoration was skipped.
+ */
+export interface QueryIndexRestoreResult {
+    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 queryIndexCheckpointPath_get(identity: string, root?: string): string;
+/**
+ * Restores a matching, validated checkpoint into the index.
+ *
+ * A rejected file is not an error worth raising: the index is advisory, so
+ * an unreadable checkpoint costs a sweep and nothing else.
+ *
+ * @param identity - Canonical ChRIS identity string.
+ * @param root - Checkpoint directory override.
+ * @returns Restoration outcome without throwing for absent or invalid files.
+ */
+export declare function queryIndexCheckpoint_restore(identity: string, root?: string): Promise<QueryIndexRestoreResult>;
+/**
+ * Atomically saves the query index.
+ *
+ * @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 queryIndexCheckpoint_save(identity: string, root?: string): Promise<void>;
+/**
+ * Starts a throttled checkpoint writer for index 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 queryIndexCheckpoint_watch(identity: string, root?: string, delayMs?: number, floorMs?: number): () => void;