@fnndsc/cumin 3.17.1 → 3.19.0

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;

package/dist/cache/queryIndexCheckpoint.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUERY_INDEX_CHECKPOINT_FLOOR_MS = void 0;
+exports.queryIndexCheckpointPath_get = queryIndexCheckpointPath_get;
+exports.queryIndexCheckpoint_restore = queryIndexCheckpoint_restore;
+exports.queryIndexCheckpoint_save = queryIndexCheckpoint_save;
+exports.queryIndexCheckpoint_watch = queryIndexCheckpoint_watch;
+/**
+ * @file Persistent checkpoint for the PACS query index.
+ *
+ * The index is expensive to build and cheap to keep: the back-fill walks a
+ * collection whose every row drags a compressed result, so the sweep is a
+ * cost worth paying once rather than at every boot. Written to disk and
+ * restored at start, it comes back with its floor, and the sweep resumes
+ * from there instead of starting over.
+ *
+ * Same shape as the listing checkpoint next door: one identity-keyed,
+ * mode-0600 file under a mode-0700 folder, written by same-directory atomic
+ * rename, throttled so a burst of queries 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 queryIndex_1 = require("./queryIndex");
+const QUERY_INDEX_SCHEMA = 1;
+/** Minimum spacing between two writes of the query-index checkpoint. */
+exports.QUERY_INDEX_CHECKPOINT_FLOOR_MS = 10 * 1000;
+/** Returns the default directory for persistent index files. */
+function queryIndexRoot_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 queryIndexCheckpointPath_get(identity, root = queryIndexRoot_get()) {
+    const key = (0, crypto_1.createHash)('sha256').update(identity).digest('hex').slice(0, 16);
+    return (0, path_1.join)(root, `pacs-queries-${key}-v${QUERY_INDEX_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.key === 'string' && entry.key.length > 0 &&
+        typeof entry.queryId === 'number' && Number.isFinite(entry.queryId) &&
+        typeof entry.server === 'string' &&
+        typeof entry.owner === 'string' &&
+        typeof entry.answeredAt === 'string' && !Number.isNaN(Date.parse(entry.answeredAt)) &&
+        typeof entry.hasResult === 'boolean' &&
+        entry.criteria !== undefined && entry.criteria !== null && typeof entry.criteria === 'object';
+}
+/** 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 === QUERY_INDEX_SCHEMA &&
+        file.identity === identity &&
+        typeof file.writtenAt === 'string' &&
+        !Number.isNaN(Date.parse(file.writtenAt)) &&
+        (file.floor === null || (typeof file.floor === 'string' && !Number.isNaN(Date.parse(file.floor)))) &&
+        Array.isArray(file.entries) &&
+        file.entries.every(entry_check);
+}
+/**
+ * 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.
+ */
+async function queryIndexCheckpoint_restore(identity, root = queryIndexRoot_get()) {
+    try {
+        const raw = await fs_1.promises.readFile(queryIndexCheckpointPath_get(identity, root), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!file_check(parsed, identity)) {
+            return { restored: false, count: 0, reason: 'incompatible query index' };
+        }
+        const snapshot = { entries: parsed.entries, floor: parsed.floor };
+        (0, queryIndex_1.queryIndex_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 query index' : (error instanceof Error ? error.message : String(error)),
+        };
+    }
+}
+/**
+ * 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.
+ */
+async function queryIndexCheckpoint_save(identity, root = queryIndexRoot_get()) {
+    const path = queryIndexCheckpointPath_get(identity, root);
+    const temporaryPath = `${path}.${process.pid}-${(0, crypto_1.randomUUID)()}.tmp`;
+    const snapshot = (0, queryIndex_1.queryIndex_get)().snapshot_create();
+    const file = {
+        schemaVersion: QUERY_INDEX_SCHEMA,
+        identity,
+        writtenAt: new Date().toISOString(),
+        floor: snapshot.floor,
+        entries: snapshot.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 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.
+ */
+function queryIndexCheckpoint_watch(identity, root = queryIndexRoot_get(), delayMs = 2000, floorMs = exports.QUERY_INDEX_CHECKPOINT_FLOOR_MS) {
+    let timer = null;
+    let lastWrite = 0;
+    const listener_remove = (0, queryIndex_1.queryIndex_get)().changeListener_add(() => {
+        if (timer)
+            return;
+        const wait = Math.max(delayMs, lastWrite + floorMs - Date.now());
+        timer = setTimeout(() => {
+            timer = null;
+            lastWrite = Date.now();
+            void queryIndexCheckpoint_save(identity, root).catch(() => { });
+        }, wait);
+        timer.unref();
+    });
+    return () => {
+        listener_remove();
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+    };
+}
+//# sourceMappingURL=queryIndexCheckpoint.js.map

package/dist/cache/queryIndexCheckpoint.js.map

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

package/dist/chrisapi/contract.d.ts

@@ -95,6 +95,35 @@ export interface PageWalkStep<T> {
  * ```
  */
 export declare function listPages_walk<T>(page_fetch: (offset: number, limit: number) => Promise<ListPage<T>>, options?: PageWalkOptions): AsyncGenerator<PageWalkStep<T>, void, void>;
+/**
+ * Options for a windowed walk. See {@link listPages_walkWindowed}.
+ *
+ * @property pageSize - Rows requested per page. Defaults to 100.
+ * @property inFlight - Pages fetched concurrently once the total is known.
+ *   Defaults to 4.
+ */
+export interface WindowedPageWalkOptions {
+    pageSize?: number;
+    inFlight?: number;
+}
+/**
+ * Walks every page of a paginated CUBE list with several pages in flight.
+ *
+ * The one pagination loop, windowed: the first page is fetched alone to
+ * learn the server's total, and every further offset is then known, so up
+ * to `inFlight` pages are fetched at once and yielded as each lands — in
+ * completion order, which is why this walk suits a consumer that keys rows
+ * by id and commits the whole set when it is done, and not one that reads
+ * rows in server order or resumes from an offset. A server that reports no
+ * total is walked one page at a time, exactly as {@link listPages_walk}
+ * does. A fetch error ends the walk once the pages already in flight have
+ * settled, and propagates.
+ *
+ * @param page_fetch - Fetches one page at the given offset and limit.
+ * @param options - Page size and window width. See WindowedPageWalkOptions.
+ * @returns Async generator yielding a PageWalkStep per fetched page.
+ */
+export declare function listPages_walkWindowed<T>(page_fetch: (offset: number, limit: number) => Promise<ListPage<T>>, options?: WindowedPageWalkOptions): AsyncGenerator<PageWalkStep<T>, void, void>;
 /**
  * Drains every page of a paginated CUBE list into one array.
  *
@@ -333,6 +362,33 @@ export interface ComputeResourceData {
     name?: string;
     [key: string]: unknown;
 }
+/**
+ * Wire shape of one registered plugin row, as served by `getPlugins`.
+ *
+ * @property id - Plugin id.
+ * @property name - The plugin's registered name (`pl-dcm2niix`).
+ * @property version - Its registered version.
+ * @property type - `ds`, `fs` or `ts`: what the node consumes and produces.
+ * @property title - The human title, when the plugin declared one.
+ * @property authors - Declared authorship.
+ * @property description - What the plugin does.
+ * @property documentation - Where its source or docs live.
+ * @property category - The plugin's declared category.
+ * @property creation_date - ISO registration timestamp.
+ */
+export interface PluginData {
+    id?: number;
+    name?: string;
+    version?: string;
+    type?: string;
+    title?: string;
+    authors?: string;
+    description?: string;
+    documentation?: string;
+    category?: string;
+    creation_date?: string;
+    [key: string]: unknown;
+}
 /**
  * Typed handle over one plugin detail resource (metadata surfaces only).
  */
@@ -412,6 +468,41 @@ export declare function collectionPage_wrap<T>(collection: {
     totalCount: number;
     hasNextPage: boolean;
 }, rows: T[]): ListPage<T>;
+/**
+ * One registered plugin resolved from CUBE: its row, and a handle onto the
+ * sub-collections that hang off it.
+ *
+ * @property data - The plugin's wire payload.
+ * @property handle - Typed access to its parameters and compute resources.
+ */
+export interface PluginFound {
+    data: PluginData;
+    handle: PluginHandle;
+}
+/**
+ * Fetches one registered plugin by exact name and version.
+ *
+ * @param client - Connected chrisapi client.
+ * @param name - Exact plugin name.
+ * @param version - Exact plugin version.
+ * @returns The plugin and a handle onto it, or null when CUBE has no such
+ *   plugin at that version.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+export declare function plugin_find(client: Client, name: string, version: string): Promise<PluginFound | null>;
+/**
+ * Reads every parameter a plugin declares, to exhaustion.
+ *
+ * A plugin's parameter list is the one collection a surface cannot ask
+ * twice about: a form built from a truncated list silently omits flags the
+ * plugin requires. The single-page `{ limit: 100 }` idiom this replaces lost
+ * the tail of any plugin with more, and said nothing.
+ *
+ * @param handle - A plugin handle.
+ * @returns Every declared parameter, in server order.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+export declare function pluginParameters_drain(handle: PluginHandle): Promise<PluginParameterData[]>;
 /**
  * Fetches one registered pipeline's detail resource as a typed handle.
  *
@@ -430,6 +521,19 @@ export declare function pipeline_get(client: Client, pipelineID: number): Promis
  * @throws {Error} Propagates chrisapi/network errors.
  */
 export declare function pipelineSourceFilesPage_get(client: Client, params: Record<string, unknown>): Promise<ListPage<PipelineSourceFileData>>;
+/**
+ * Drains every pipeline source file matching a filter.
+ *
+ * The registered pipelines' source files are a collection, not a page: a
+ * caller asking which file a pipeline came from wants the answer, and
+ * `{ limit: 1000 }` was a guess at how many that could be (#401).
+ *
+ * @param client - Connected chrisapi client.
+ * @param filter - Server-side filter (a `pipeline_id`, an `fname`), or none.
+ * @returns Every matching source file, in server order.
+ * @throws {Error} Propagates chrisapi/network errors.
+ */
+export declare function pipelineSourceFiles_drain(client: Client, filter?: Record<string, unknown>): Promise<PipelineSourceFileData[]>;
 /**
  * Creates a CUBE download token for authenticated file access and LONK.
  *