@fnndsc/brasa 0.16.1 → 0.18.0

package/dist/builtins/net/query.js

@@ -9,9 +9,12 @@
  * @module
  */
 import chalk from 'chalk';
-import { errorStack, chrisContext, Context, pacsQuery_get, pacsQuery_resultDecode, pacsQueries_create, pacsServers_list, envelope_ok, envelope_error, listCache_get, } from '@fnndsc/cumin';
+import { errorStack, chrisContext, Context, pacsQuery_get, pacsQuery_resultDecode, pacsQueries_create, pacsServers_list, envelope_ok, envelope_error, listCache_get, queryIndex_get, } from '@fnndsc/cumin';
 import { queryFolderName_build } from '@fnndsc/salsa';
-import { PACS_QUERY_MODEL_KIND } from '@fnndsc/menu';
+import { PACS_QUERY_MODEL_KIND, } from '@fnndsc/menu';
+import { PATIENT_KEY, QUERY_COHORT_MAX, QUERY_INLINE_FANOUT_MAX, fanout_permit, patients_read, queryTerms_expand, queryTerms_parse, } from './query.fanout.js';
+import { sink_get } from '../../core/sink.js';
+import { csvFile_write, pacsAnswer_toCsv } from './query.csv.js';
 import { series_cubePathGet } from './pacsUtils.js';
 import { screen } from '@fnndsc/chili/screen/screen.js';
 import { spinner } from '../../lib/spinner.js';
@@ -91,7 +94,12 @@ export async function pacsQuery_createAndWait(queryExpr, title, pacsserver, onSt
     // so an immediate `ls` shows the query instead of a stale directory.
     listCache_get().cache_invalidate('/net/pacs/queries');
     const queryId = createResult.value.id;
-    const ownerUsername = typeof createResult.value.owner_username === 'string' ? createResult.value.owner_username : undefined;
+    // CUBE does not always name the owner on the create response, and the
+    // index is keyed by it — a query filed under nobody is a query the next
+    // identical ask cannot find. The session's own identity is the fallback,
+    // since it is who just asked.
+    const ownerUsername = (typeof createResult.value.owner_username === 'string' ? createResult.value.owner_username : undefined)
+        ?? (await askingIdentity_get()) ?? undefined;
     const vfsPath = queryVfsPath_build(queryId, queryObj, ownerUsername);
     const deadline = Date.now() + QUERY_TIMEOUT_MS;
     const sleep = (ms) => new Promise(r => setTimeout(r, ms));
@@ -102,6 +110,7 @@ export async function pacsQuery_createAndWait(queryExpr, title, pacsserver, onSt
         onStatus?.(`Query ${queryId} — ${status}`);
         const decodeResult = await pacsQuery_resultDecode(queryId);
         if (decodeResult.ok && decodeResult.value.json !== undefined) {
+            queryIndex_file(queryId, queryObj, await pacsIdentifier_resolve(pacsserver), ownerUsername, true);
             return { queryId, vfsPath, decoded: decodeResult.value };
         }
         if (!decodeResult.ok) {
@@ -113,6 +122,9 @@ export async function pacsQuery_createAndWait(queryExpr, title, pacsserver, onSt
         // A succeeded query with no stored payload means the PACS matched
         // nothing; a couple of grace polls cover result-write lag.
         if (status === 'succeeded' && ++succeededWithoutPayload >= 2) {
+            // Filed as a no-hit. A replay must know this question was asked and
+            // found nothing, so it can decline to serve the emptiness back.
+            queryIndex_file(queryId, queryObj, await pacsIdentifier_resolve(pacsserver), ownerUsername, false);
             return { queryId, vfsPath, decoded: { raw: '' } };
         }
         await sleep(QUERY_POLL_INTERVAL_MS);
@@ -120,6 +132,30 @@ export async function pacsQuery_createAndWait(queryExpr, title, pacsserver, onSt
     errorStack.stack_push('error', `query: Timed out waiting for query ${queryId} result.`);
     return null;
 }
+/**
+ * Files a finished query in the replay index.
+ *
+ * Every query mise runs indexes itself, so the next identical question is
+ * answered without waiting for the background sweep to have walked this far
+ * back. The server is recorded because the same criteria asked of a
+ * different PACS is a different question.
+ *
+ * @param queryId - The stored query's id.
+ * @param criteria - The criteria as asked.
+ * @param server - The PACS identifier it was asked of.
+ * @param owner - Who asked, when CUBE said.
+ * @param hasResult - Whether it found anything.
+ */
+function queryIndex_file(queryId, criteria, server, owner, hasResult) {
+    queryIndex_get().entry_note({
+        queryId,
+        server,
+        criteria,
+        owner: owner ?? '',
+        answeredAt: new Date().toISOString(),
+        hasResult,
+    });
+}
 /**
  * Renders decoded PACS query JSON into a human-readable study/series summary.
  *
@@ -323,6 +359,494 @@ async function modelPulledState_fill(model) {
         }));
     }
 }
+/**
+ * Who is asking, as the index keys it.
+ *
+ * `current_get(ChRISuser)` reads a per-session context snapshot, and a
+ * surface attached to a running calypso does not necessarily have one —
+ * which silently keyed every lookup under an empty owner and made the
+ * whole stored back-catalogue unreachable from argus while chell found it
+ * perfectly. `ChRISuser_get` reads the authenticated login instead, which
+ * is the same thing the sweep files records under.
+ *
+ * @returns The CUBE username, or an empty string when nobody is logged in.
+ */
+async function askingIdentity_get() {
+    return (await chrisContext.ChRISuser_get()) ?? '';
+}
+/**
+ * What each way of naming a server resolves to. Server identifiers do not
+ * change under a session, and this is on the path of every query.
+ */
+const pacsIdentifiers = new Map();
+/**
+ * Resolves whatever names a PACS server into its canonical identifier.
+ *
+ * The context may hold a numeric id, a `--pacsserver` may be either, and
+ * CUBE files a query under the identifier. The index is keyed on what CUBE
+ * stores, so both the write and the lookup have to speak that.
+ *
+ * @param pacsserver - An id or an identifier.
+ * @returns The identifier, or the input unchanged when it cannot be resolved.
+ */
+export async function pacsIdentifier_resolve(pacsserver) {
+    const remembered = pacsIdentifiers.get(pacsserver);
+    if (remembered !== undefined)
+        return remembered;
+    const servers = await pacsServers_list();
+    // Best effort by design: this only decides what a lookup is filed under,
+    // so an unreachable or unhelpful CUBE must never fail the query itself.
+    if (!servers?.ok)
+        return pacsserver;
+    let resolved = pacsserver;
+    for (const server of servers.value) {
+        if (server.identifier === pacsserver) {
+            resolved = pacsserver;
+            break;
+        }
+        if (String(server.id) === pacsserver && server.identifier) {
+            resolved = server.identifier;
+            break;
+        }
+    }
+    pacsIdentifiers.set(pacsserver, resolved);
+    return resolved;
+}
+/**
+ * Says how long ago something was answered, in the coarsest true unit.
+ *
+ * A replay states its age because mise refuses to decide staleness on the
+ * operator's behalf: an accession names a study that will not change, an
+ * MRN can gain one tomorrow, and no heuristic tells those apart reliably.
+ *
+ * @param at - An ISO timestamp.
+ * @returns A phrase like `3 months ago`, or null when the stamp is unusable.
+ */
+export function age_describe(at) {
+    const then = Date.parse(at);
+    if (Number.isNaN(then))
+        return null;
+    const seconds = Math.max(0, Math.round((Date.now() - then) / 1000));
+    const units = [
+        { limit: 60, size: 1, name: 'second' },
+        { limit: 3600, size: 60, name: 'minute' },
+        { limit: 86400, size: 3600, name: 'hour' },
+        { limit: 2592000, size: 86400, name: 'day' },
+        { limit: 31536000, size: 2592000, name: 'month' },
+        { limit: Infinity, size: 31536000, name: 'year' },
+    ];
+    for (const unit of units) {
+        if (seconds >= unit.limit)
+            continue;
+        const count = Math.max(1, Math.floor(seconds / unit.size));
+        return `${count} ${unit.name}${count === 1 ? '' : 's'} ago`;
+    }
+    return null;
+}
+/**
+ * Serves a stored answer when this exact question already has one.
+ *
+ * The rules were settled in #379 and each earns its place:
+ *
+ * - the criteria, the server AND the asking identity must match, because
+ *   another identity's answer is not an answer to this question;
+ * - a query that found NOTHING is never replayed. A hit is evidence that
+ *   persists — the study existed and still does — while an absence decays,
+ *   and "no imaging found" is the answer a clinician acts on;
+ * - the index is advisory, so a hit is confirmed by actually decoding the
+ *   stored result. Anything that fails — the query deleted, the payload
+ *   unreadable — drops the entry and falls through to a fresh query.
+ *
+ * @param criteria - The criteria as asked.
+ * @param identifier - The PACS being asked.
+ * @param owner - The identity asking.
+ * @returns The stored answer and its age, or null to ask the PACS.
+ */
+async function replay_attempt(criteria, identifier, owner) {
+    const entry = queryIndex_get().entry_find(criteria, identifier, owner);
+    if (entry === null || !entry.hasResult)
+        return null;
+    const decoded = await pacsQuery_resultDecode(entry.queryId);
+    if (!decoded.ok || decoded.value.json === undefined) {
+        // The index promised something CUBE no longer has. Forget it and ask.
+        errorStack.stack_pop();
+        queryIndex_get().entry_drop(criteria, identifier, owner);
+        return null;
+    }
+    return {
+        result: {
+            queryId: entry.queryId,
+            vfsPath: queryVfsPath_build(entry.queryId, entry.criteria, entry.owner || undefined),
+            decoded: decoded.value,
+        },
+        answeredAt: entry.answeredAt,
+    };
+}
+/**
+ * Reads a JSON expression as single-valued terms.
+ *
+ * The JSON form predates multi-value and stays what it was: one question,
+ * spelled as an object.
+ *
+ * @param expr - The expression, starting with `{`.
+ * @returns Terms with one value each, or null when the JSON is not an object.
+ */
+function termsFromJson_read(expr) {
+    const parsed = queryExpr_parse(expr);
+    if (parsed === null)
+        return null;
+    return Object.fromEntries(Object.entries(parsed).map(([key, value]) => [key, [value]]));
+}
+/** How many patient queries are in flight at once. */
+const QUERY_FANOUT_CONCURRENCY = 4;
+/**
+ * Renders criteria back into the expression syntax they were parsed from,
+ * so a single question inside a fan-out is asked exactly as one typed by
+ * hand — the create path takes an expression, not a record.
+ *
+ * @param criteria - One question's criteria.
+ * @returns The `Key:Value,Key:Value` form.
+ */
+function criteria_toExpression(criteria) {
+    return Object.entries(criteria)
+        .map(([key, value]) => `${key}:${value}`)
+        .join(',');
+}
+/**
+ * Asks one question, replaying it when the same question has been asked
+ * before.
+ *
+ * @param ask - The question.
+ * @param title - Title for the PACSQuery record this may create.
+ * @param pacsserver - The server to ask.
+ * @param identifier - That server as the replay index keys it.
+ * @param owner - The identity asking.
+ * @param fresh - True to skip the stored answer and trouble the PACS.
+ * @returns What came back, including the reason when nothing did.
+ */
+async function ask_run(ask, title, owner, fresh) {
+    if (!fresh) {
+        const replayed = await replay_attempt(ask.criteria, ask.identifier, owner);
+        if (replayed !== null) {
+            return { ask, result: replayed.result, answeredAt: replayed.answeredAt };
+        }
+    }
+    const checkpoint = errorStack.checkpoint_mark();
+    const expression = criteria_toExpression(ask.criteria);
+    // Each question gets its own title. CUBE refuses a second PACSQuery with
+    // a title it already holds for that server — measured live, where a
+    // fan-out under one title had every question after the first come back
+    // "You have already registered a PACS query with title=..." — so a
+    // cohort sharing one title would report a room full of unasked patients.
+    const result = await pacsQuery_createAndWait(expression, `${title} · ${expression}`, ask.server);
+    if (result !== null)
+        return { ask, result, answeredAt: null };
+    // A question that could not be asked has told us nothing. Its reason is
+    // carried onto the row rather than left on the stack, where a later
+    // question's success would bury it.
+    const reasons = errorStack.checkpoint_drain(checkpoint);
+    const reason = reasons[reasons.length - 1]?.message;
+    // Stripped where the reason becomes data: this message is read in a
+    // table and on a graphical surface, and `[pacsServer_resolve ] |` is a
+    // debugging artefact in both. Imported here rather than at the top so
+    // this module keeps its narrow graph.
+    const { error_stripDebugPrefix } = await import('../utils.js');
+    return {
+        ask,
+        result: null,
+        answeredAt: null,
+        error: reason === undefined ? 'the query could not be completed' : error_stripDebugPrefix(reason),
+    };
+}
+/**
+ * Runs a fan-out, at most four questions in flight.
+ *
+ * Not operator-settable: nobody inside mise knows the right number for a
+ * given hospital, and a flag that can hurt a shared clinical system will
+ * eventually be set to fifty.
+ *
+ * @param asks - Every question to ask, each naming its own server.
+ * @param title - Title for the PACSQuery records created.
+ * @param owner - The identity asking.
+ * @param fresh - True to skip stored answers.
+ * @returns The answers, in the order the questions were given.
+ */
+async function fanout_run(asks, title, owner, fresh) {
+    const answers = new Array(asks.length);
+    let done = 0;
+    // What is being counted: patients when every question names one, plain
+    // questions otherwise — a fan-out over servers or dates is not MRNs.
+    const label = asks.every((ask) => ask.patientId !== undefined)
+        ? 'MRNS QUERIED'
+        : 'QUERIES';
+    const progress_say = (phase) => {
+        sink_get().progress_write({
+            operation: 'task',
+            kind: 'inspection',
+            phase,
+            label,
+            current: done,
+            total: asks.length,
+            percent: asks.length > 0 ? Math.min(100, (done / asks.length) * 100) : undefined,
+            status: phase === 'complete' ? 'done' : 'running',
+        });
+    };
+    progress_say('working');
+    let next = 0;
+    const worker = async () => {
+        while (next < asks.length) {
+            const index = next++;
+            answers[index] = await ask_run(asks[index], title, owner, fresh);
+            done++;
+            progress_say('working');
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(QUERY_FANOUT_CONCURRENCY, asks.length) }, worker));
+    progress_say('complete');
+    return answers;
+}
+/**
+ * Unions a fan-out's answers into one model.
+ *
+ * The studies keep their own identities and paths, each already built
+ * against the query that found it. The patient level records what was
+ * ASKED — including the questions that found nothing and the ones that
+ * could not be asked at all, which is the half of a cohort answer that
+ * cannot be derived from studies nobody has.
+ *
+ * @param answers - What every question came back with.
+ * @param facts - The command's identity facts.
+ * @returns The union model.
+ */
+function fanoutModel_build(answers, facts) {
+    // A row says which PACS answered only when more than one could have. On
+    // a single-server query the column would repeat one value down the page
+    // and tell an operator nothing.
+    const manyServers = new Set(answers.map((answer) => answer.ask.identifier)).size > 1;
+    const studies = [];
+    const patients = [];
+    let anchor = null;
+    let oldest = null;
+    let allReplayed = true;
+    for (const answer of answers) {
+        const found = answer.result === null ? [] : pacsQueryModel_build(answer.result.decoded, {
+            queryId: answer.result.queryId,
+            vfsPath: answer.result.vfsPath,
+            pacsName: answer.ask.server,
+            expression: criteria_toExpression(answer.ask.criteria),
+        }).studies.map((study) => (manyServers ? { ...study, server: answer.ask.identifier } : study));
+        studies.push(...found);
+        if (answer.result !== null && (anchor === null || found.length > 0)) {
+            if (anchor === null || anchor.decoded.json === undefined)
+                anchor = answer.result;
+        }
+        const answeredAt = answer.answeredAt ?? new Date().toISOString();
+        if (answer.answeredAt === null)
+            allReplayed = false;
+        if (answer.result !== null && (oldest === null || answeredAt < oldest))
+            oldest = answeredAt;
+        if (answer.ask.patientId === undefined)
+            continue;
+        const seriesCount = found.reduce((total, study) => total + study.series.length, 0);
+        patients.push({
+            patientId: answer.ask.patientId,
+            ...(manyServers ? { server: answer.ask.identifier } : {}),
+            ...(found[0]?.patientName ? { patientName: found[0].patientName } : {}),
+            status: answer.result === null ? 'unasked' : (found.length > 0 ? 'found' : 'none'),
+            studyCount: found.length,
+            seriesCount,
+            ...(answer.result === null ? {} : { queryId: answer.result.queryId }),
+            ...(answer.result === null ? {} : {
+                provenance: { replayed: answer.answeredAt !== null, answeredAt },
+            }),
+            ...(answer.error === undefined ? {} : { error: answer.error }),
+        });
+    }
+    return {
+        queryId: anchor?.queryId ?? 0,
+        vfsPath: anchor?.vfsPath ?? '',
+        pacsName: facts.pacsName,
+        expression: facts.expression,
+        studies,
+        // The set's provenance is its OLDEST row: the worst row is what decides
+        // whether an audit table can be trusted, and a set is only "replayed"
+        // when nothing in it troubled the PACS.
+        ...(oldest === null ? {} : { provenance: { replayed: allReplayed, answeredAt: oldest } }),
+        ...(patients.length > 0 ? { patients } : {}),
+    };
+}
+/**
+ * Renders a cohort as the audit table it is: one row per patient asked.
+ *
+ * A miss reads as a zero and a failure reads as a dash in an error hue,
+ * because a server that timed out has told us nothing while a PACS that
+ * answered with nothing has told us something, and a clinician acts on the
+ * difference.
+ *
+ * @param patients - Every patient asked.
+ * @returns The rendered table.
+ */
+function cohort_render(patients) {
+    const server_of = (patient) => patient.server ?? '';
+    const manyServers = new Set(patients.map(server_of)).size > 1;
+    const serverWidth = 14;
+    const lines = [''];
+    const serverCap = manyServers ? chalk.bold.white('SERVER'.padEnd(serverWidth)) : '';
+    lines.push(`  ${chalk.bold.white('MRN'.padEnd(18))}${serverCap}${chalk.bold.white('STUDIES'.padEnd(10))}${chalk.bold.white('SERIES'.padEnd(9))}${chalk.bold.white('ANSWERED')}`);
+    lines.push(`  ${chalk.gray('─'.repeat(manyServers ? 74 : 60))}`);
+    for (const patient of patients) {
+        const answered = patient.provenance === undefined
+            ? null
+            : age_describe(patient.provenance.answeredAt);
+        const counts = patient.status === 'unasked'
+            ? ['—', '—']
+            : [String(patient.studyCount), String(patient.seriesCount)];
+        const hue = patient.status === 'unasked'
+            ? chalk.red
+            : (patient.status === 'none' ? chalk.gray : chalk.white);
+        const note = patient.status === 'unasked'
+            ? chalk.red(patient.error ?? 'unasked')
+            : chalk.gray(answered ?? 'just now');
+        const server = manyServers ? server_of(patient).padEnd(serverWidth) : '';
+        lines.push(`  ${hue(patient.patientId.padEnd(18))}${server}${counts[0].padEnd(10)}${counts[1].padEnd(9)}${note}`);
+    }
+    const tally = (state) => patients.filter((patient) => patient.status === state).length;
+    lines.push('');
+    lines.push(`  ${chalk.green(`FOUND ${tally('found')}`)} ${chalk.gray('·')} ${chalk.gray(`NONE ${tally('none')}`)} ${chalk.gray('·')} ${chalk.red(`UNASKED ${tally('unasked')}`)}`);
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Renders an answer as CSV, and writes it into ChRIS storage when asked.
+ *
+ * Two flags rather than one with an optional value: `--csv PatientID:1234`
+ * could not tell a destination from a query expression, and guessing wrong
+ * writes a file named after a patient.
+ *
+ * A local terminal needs no destination — `--csv > audit.csv` writes the
+ * operator's own disk, because engine and operator share a filesystem. A
+ * detached surface does not: the engine runs on the daemon's host, so a
+ * redirect lands on somebody else's machine. `--csv-to` puts the table in
+ * CFS instead, where a cohort's MRNs and study descriptions stay inside
+ * ChRIS rather than on whatever laptop the operator is sitting at.
+ *
+ * @param model - The answer.
+ * @param destination - A CFS path to write to, or null to render only.
+ * @returns The CSV text and where it went, or a failure already explained.
+ */
+async function csv_deliver(model, destination, ask = false, force = false) {
+    const csv = pacsAnswer_toCsv(model);
+    let target = destination;
+    if (target === null && ask) {
+        // Asked only once there is something to write: a question raised before
+        // the PACS answered would be a question about a file that may never
+        // exist.
+        const chosen = await csvDestination_ask();
+        if (chosen === '')
+            return { ok: false, message: 'query: no destination given; nothing written.' };
+        target = chosen;
+    }
+    if (target === null)
+        return { ok: true, rendered: csv };
+    const written = await csvFile_write(csv, target, force);
+    if (!written.ok)
+        return { ok: false, message: `query: ${written.message}` };
+    // A folder that had to be made is said, not discovered later.
+    const made = written.created === undefined
+        ? ''
+        : `${chalk.gray(`  made ${written.created}`)}\n`;
+    // A file that was there and is not any more is said, for the same reason
+    // the folder is: an act nobody reported is an act nobody can check.
+    const gone = written.replaced === true
+        ? `${chalk.gray(`  replaced the table that was there`)}\n`
+        : '';
+    return { ok: true, rendered: `${made}${gone}${chalk.green(`✓ wrote ${written.path}`)}\n` };
+}
+/**
+ * Asks where the table should go.
+ *
+ * The anchor is the session's own cwd — a fact, not a guess. Inventing a
+ * directory here would mean creating one behind the operator's back, which
+ * is what the surface used to do.
+ *
+ * @returns The location given, or '' when the operator abandoned the ask.
+ */
+async function csvDestination_ask() {
+    const { session } = await import('../../session/index.js');
+    const { repl_questionPath } = await import('../../core/question.js');
+    const stamp = new Date().toISOString().slice(0, 19).replace(/[:T]/g, '-');
+    // Where the operator is, unless they are somewhere nothing can be
+    // written: a session sitting in `/bin` or `/proc` is browsing a provider,
+    // not a place a file lands, and an errand that opens there offers a
+    // destination that is refused the moment it is committed.
+    const cwd = await session.getCWD();
+    const virtual = ['/bin', '/usr', '/etc', '/proc', '/net']
+        .some((prefix) => cwd === prefix || cwd.startsWith(`${prefix}/`));
+    try {
+        const answer = await repl_questionPath('Where should the table go? ', {
+            anchor: virtual ? '~' : cwd,
+            wantsDirectory: false,
+            suggest: `pacs-${stamp}.csv`,
+        }, 'EXPORT HERE');
+        return answer.trim();
+    }
+    catch {
+        // A refused or abandoned ask is not a failure of the query: the answer
+        // stands, and only the writing of it does not happen.
+        return '';
+    }
+}
+/**
+ * Answers a cohort: many questions, one model, one table.
+ *
+ * @param asks - The questions.
+ * @param facts - Title, server, identity and how the answer should read.
+ * @returns One envelope carrying every answer.
+ */
+async function cohort_answer(asks, facts) {
+    spinner.start(`Querying PACS for ${asks.length} questions...`, true);
+    const answers = await fanout_run(asks, facts.title, facts.owner, facts.fresh);
+    spinner.stop();
+    const model = fanoutModel_build(answers, {
+        pacsName: facts.pacsserver,
+        expression: facts.expression,
+    });
+    await modelPulledState_fill(model);
+    const patients = model.patients ?? [];
+    const unasked = patients.filter((patient) => patient.status === 'unasked').length;
+    if (facts.csv || facts.csvTo !== null || facts.csvToAsk) {
+        const delivered = await csv_deliver(model, facts.csvTo, facts.csvToAsk, facts.force);
+        if (!delivered.ok) {
+            process.exitCode = 1;
+            // The ANSWER stands: only the writing of it did not happen. An
+            // abandoned question, or a refused destination, is no reason to
+            // throw away a PACS answer the operator waited for — the model
+            // crosses either way, and a surface still shows what was found.
+            return {
+                ...envelope_error('', undefined, `${chalk.red(delivered.message)}\n`),
+                model: { kind: PACS_QUERY_MODEL_KIND, data: model },
+            };
+        }
+        return envelope_ok(delivered.rendered, { kind: PACS_QUERY_MODEL_KIND, data: model });
+    }
+    // A fan-out over something other than patients has no audit table to
+    // show; its studies are the answer, and they are already in the model.
+    const rendered = patients.length > 0
+        ? cohort_render(patients)
+        : `${chalk.green(`✓ ${asks.length} queries complete — ${model.studies.length} studies`)}\n`;
+    // Every question failing is a failure of the command; some failing is an
+    // answer with holes in it, which the table states and the operator reads.
+    if (unasked > 0 && unasked === patients.length) {
+        process.exitCode = 1;
+        // The model still crosses. A surface showing which MRNs went unasked,
+        // and why, is more use than an empty pane beside a red line.
+        return {
+            ...envelope_error(rendered, undefined, `${chalk.red(`query: none of the ${unasked} questions could be asked.`)}\n`),
+            model: { kind: PACS_QUERY_MODEL_KIND, data: model },
+        };
+    }
+    return envelope_ok(rendered, { kind: PACS_QUERY_MODEL_KIND, data: model });
+}
 /**
  * Creates a PACS query, waits for results, displays findings, and prints the VFS path.
  *
@@ -339,6 +863,14 @@ export async function builtin_query(args) {
     let title = `Query ${Date.now()}`;
     let pacsserverOverride = null;
     let tableMode = false;
+    let fresh = false;
+    let patientsArg = null;
+    let csv = false;
+    let csvTo = null;
+    /** True when `--csv-to` was given no value: the destination is asked for. */
+    let csvToAsk = false;
+    /** True when the operator said to overwrite a table that already exists. */
+    let force = false;
     const positional = [];
     for (let i = 0; i < args.length; i++) {
         if (args[i] === '--title' && i + 1 < args.length) {
@@ -350,35 +882,164 @@ export async function builtin_query(args) {
         else if (args[i] === '--table') {
             tableMode = true;
         }
+        else if (args[i] === '--patients' && i + 1 < args.length) {
+            patientsArg = args[++i];
+        }
+        else if (args[i] === '--csv') {
+            csv = true;
+        }
+        else if (args[i] === '--csv-to') {
+            // A value-taking flag given no value is an ASK. `--csv-to` with
+            // nothing after it means "ask me where", which is how a graphical
+            // surface opens its errand and how a terminal gets a prompt. Given
+            // nothing and treated as nothing — which is what happened before —
+            // the operator asked for a CSV and silently got none.
+            const value = args[i + 1];
+            if (value !== undefined && !value.startsWith('--')) {
+                csvTo = args[++i];
+            }
+            else {
+                csvToAsk = true;
+            }
+        }
+        else if (args[i] === '--force') {
+            force = true;
+        }
+        else if (args[i] === '--fresh') {
+            fresh = true;
+        }
         else if (!args[i].startsWith('--')) {
             positional.push(args[i]);
         }
     }
-    if (positional.length === 0) {
+    if (positional.length === 0 && patientsArg === null) {
         process.exitCode = 1;
-        return envelope_error('', undefined, `${chalk.red('query: Missing query expression. Usage: query <Key:Value[,...]> [--title <title>]')}\n`);
+        return envelope_error('', undefined, `${chalk.red('query: Missing query expression. Usage: query <Key:Value[,...]> [--patients <list|@file>] [--title <title>]')}\n`);
     }
     const queryExpr = positional.join(' ');
-    // Validate expression early
-    if (!queryExpr_parse(queryExpr)) {
+    // Validate expression early. A cohort may narrow with terms or with none
+    // at all — `--patients @mrns.txt` is a complete question.
+    const terms = queryExpr === '' ? {} : (queryExpr.trimStart().startsWith('{')
+        ? termsFromJson_read(queryExpr)
+        : queryTerms_parse(queryExpr));
+    if (terms === null) {
         process.exitCode = 1;
         return envelope_error('', undefined, `${chalk.red(`query: Invalid expression: "${queryExpr}". Use Key:Value pairs (e.g. PatientID:1234) or JSON.`)}\n`);
     }
-    // Resolve PACS server
-    let pacsserver = pacsserverOverride ?? await chrisContext.current_get(Context.PACSserver);
-    if (!pacsserver) {
-        const serversResult = await pacsServers_list();
-        if (serversResult.ok && serversResult.value.length > 0) {
-            pacsserver = String(serversResult.value[0].id);
+    // Resolve the PACS servers. Several is a QUERY across them; one is the
+    // ordinary case. There is no sweep-everything: a fan-out is always
+    // something the operator named, because thirteen registrations of
+    // unknown liveness is thousands of C-FINDs mostly into the void.
+    const named = (pacsserverOverride ?? '')
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry !== '');
+    let servers = named;
+    if (servers.length === 0) {
+        const inContext = await chrisContext.current_get(Context.PACSserver);
+        if (inContext) {
+            servers = [inContext];
         }
         else {
+            const serversResult = await pacsServers_list();
+            if (serversResult.ok && serversResult.value.length > 0) {
+                servers = [String(serversResult.value[0].id)];
+            }
+            else {
+                process.exitCode = 1;
+                return envelope_error('', undefined, `${chalk.red('query: No PACS server available. Set one with: pacs connect <id>')}\n`);
+            }
+        }
+    }
+    const pacsserver = servers[0];
+    // The index is keyed on what CUBE stores, which is the identifier.
+    const identifiers = await Promise.all(servers.map((server) => pacsIdentifier_resolve(server)));
+    const identifier = identifiers[0];
+    const owner = await askingIdentity_get();
+    // What the operator asked for, as the questions it stands for. A PACS
+    // will not match a list, so several patients is several C-FINDs.
+    const asks = [];
+    if (patientsArg !== null) {
+        const cohort = await patients_read(patientsArg);
+        if (!cohort.ok) {
+            const problem = errorStack.stack_pop();
+            process.exitCode = 1;
+            return envelope_error('', undefined, `${chalk.red(problem?.message ?? 'query: --patients could not be read.')}\n`);
+        }
+        if (!fanout_permit(cohort.value.length, QUERY_COHORT_MAX)) {
+            const problem = errorStack.stack_pop();
+            process.exitCode = 1;
+            return envelope_error('', undefined, `${chalk.red(problem?.message ?? 'query: too many patients.')}\n`);
+        }
+        const base = Object.fromEntries(Object.entries(terms).map(([key, values]) => [key, values[0]]));
+        if (!fanout_permit(cohort.value.length * servers.length, QUERY_COHORT_MAX)) {
+            const problem = errorStack.stack_pop();
             process.exitCode = 1;
-            return envelope_error('', undefined, `${chalk.red('query: No PACS server available. Set one with: pacs connect <id>')}\n`);
+            return envelope_error('', undefined, `${chalk.red(problem?.message ?? 'query: too many questions.')}\n`);
+        }
+        for (const mrn of cohort.value) {
+            for (let index = 0; index < servers.length; index++) {
+                asks.push({
+                    criteria: { ...base, [PATIENT_KEY]: mrn },
+                    patientId: mrn,
+                    server: servers[index],
+                    identifier: identifiers[index],
+                });
+            }
         }
     }
-    spinner.start(`Querying PACS for ${queryExpr}...`, true);
-    const result = await pacsQuery_createAndWait(queryExpr, title, pacsserver, (msg) => spinner.updateMessage(msg));
-    spinner.stop();
+    else {
+        const expanded = queryTerms_expand(terms);
+        if (!fanout_permit(expanded.length * servers.length, QUERY_INLINE_FANOUT_MAX)) {
+            const problem = errorStack.stack_pop();
+            process.exitCode = 1;
+            return envelope_error('', undefined, `${chalk.red(problem?.message ?? 'query: too many queries.')}\n`);
+        }
+        const asksPerServer = expanded.length * servers.length;
+        for (const one of expanded) {
+            for (let index = 0; index < servers.length; index++) {
+                asks.push({
+                    criteria: one,
+                    // A single question put to a single server is not a cohort: it
+                    // needs no patient level, and inventing one would put an audit
+                    // table where a study list belongs.
+                    ...(one[PATIENT_KEY] === undefined || asksPerServer === 1
+                        ? {}
+                        : { patientId: one[PATIENT_KEY] }),
+                    server: servers[index],
+                    identifier: identifiers[index],
+                });
+            }
+        }
+    }
+    if (asks.length > 1) {
+        return await cohort_answer(asks, {
+            // The model names the server the way CUBE does. `--pacsserver 1` and
+            // `--pacsserver PACSDCM` are the same server, and a table that says
+            // "1" tells an operator nothing about which PACS answered.
+            title, pacsserver: identifier, owner, fresh, csv, csvTo, csvToAsk, force,
+            expression: patientsArg === null ? queryExpr : `${queryExpr} --patients ${patientsArg}`.trim(),
+        });
+    }
+    const criteria = asks[0]?.criteria ?? {};
+    // One question, spelled as the create path wants it — which is not
+    // necessarily what was typed: `--patients 1234` names a patient without
+    // an expression to carry it.
+    const askExpr = criteria_toExpression(criteria);
+    let result = null;
+    let answeredAt = null;
+    if (!fresh) {
+        const replayed = await replay_attempt(criteria, identifier, owner);
+        if (replayed !== null) {
+            result = replayed.result;
+            answeredAt = replayed.answeredAt;
+        }
+    }
+    if (result === null) {
+        spinner.start(`Querying PACS for ${askExpr}...`, true);
+        result = await pacsQuery_createAndWait(askExpr, title, pacsserver, (msg) => spinner.updateMessage(msg));
+        spinner.stop();
+    }
     if (!result) {
         let errOut = '';
         const errs = errorStack.stack_getAll?.() ?? [];
@@ -401,23 +1062,51 @@ export async function builtin_query(args) {
     const model = pacsQueryModel_build(result.decoded, {
         queryId: result.queryId,
         vfsPath: result.vfsPath,
-        pacsName: pacsserver,
-        expression: queryExpr,
+        pacsName: identifier,
+        expression: askExpr,
+        provenance: {
+            replayed: answeredAt !== null,
+            answeredAt: answeredAt ?? new Date().toISOString(),
+        },
     });
     // Mark what CUBE already holds: a surface then offers gather instead of
     // pull for series that are already home. One bounded sweep, no retries.
     await modelPulledState_fill(model);
+    if (csv || csvTo !== null || csvToAsk) {
+        const delivered = await csv_deliver(model, csvTo, csvToAsk, force);
+        if (!delivered.ok) {
+            process.exitCode = 1;
+            // The answer stands; only the writing of it did not happen.
+            return {
+                ...envelope_error('', undefined, `${chalk.red(delivered.message)}\n`),
+                model: { kind: PACS_QUERY_MODEL_KIND, data: model },
+            };
+        }
+        return envelope_ok(delivered.rendered, { kind: PACS_QUERY_MODEL_KIND, data: model });
+    }
     if (!renderedResult) {
         // Nothing matched: browsing or pulling the empty query would be
         // meaningless, so no hints. The empty model still crosses, so a
         // graphical surface can say "no studies" in its own voice.
         return envelope_ok(`${chalk.yellow(`⚠ Query ${result.queryId} complete — no studies found.`)}\n`, { kind: PACS_QUERY_MODEL_KIND, data: model });
     }
-    let rendered = `${chalk.green(`✓ Query ${result.queryId} complete`)}\n`;
+    // Rendered FROM the model's provenance, not from a second copy of the
+    // same fact: one timestamp, one claim, however many surfaces say it.
+    const replayed = model.provenance?.replayed === true ? model.provenance : undefined;
+    const age = replayed === undefined ? null : age_describe(replayed.answeredAt);
+    let rendered = replayed === undefined
+        ? `${chalk.green(`✓ Query ${result.queryId} complete`)}\n`
+        : `${chalk.green(`✓ Query ${result.queryId} — answered ${age ?? 'earlier'}`)}\n`;
     rendered += `${renderedResult}\n`;
     rendered += `${chalk.bold(`  VFS path: ${chalk.cyan(result.vfsPath)}`)}\n`;
     rendered += `${chalk.gray(`  cd ${result.vfsPath}`)}\n`;
     rendered += `${chalk.gray(`  pull ${result.vfsPath}`)}\n`;
+    if (replayed !== undefined) {
+        // Said, never decided: mise states the age and leaves the judgement
+        // with the operator, who knows whether this question can gain an
+        // answer between then and now.
+        rendered += `${chalk.gray(`  query ${askExpr} --fresh   # ask the PACS again`)}\n`;
+    }
     return envelope_ok(rendered, { kind: PACS_QUERY_MODEL_KIND, data: model });
 }
 //# sourceMappingURL=query.js.map