react-cheminfo 0.76.0 → 0.77.0

package/src/osiris/core/barGeometry.ts

@@ -0,0 +1,74 @@
+/**
+ * Where a property's bar starts, how far it runs, and where its labelled mark
+ * goes.
+ *
+ * Three numbers come out of the domain and are merely arranged here. The
+ * **position** is how far along the scale the value sits and gives the bar its
+ * length; the **fitness** is DataWarrior's own `getValuation`, a continuous
+ * 0-to-1 score that the stylesheet reads as the green-to-red ramp; the
+ * **threshold** is the published rule of thumb — cLogP ≤ 5, logS > −4,
+ * molweight < 450, drug-likeness > 0 — drawn as a mark on the track.
+ *
+ * Nothing here invents a cut-off. A bar whose colour disagreed with the panel's
+ * own scale record would be a second opinion nobody could trace.
+ */
+
+import { propertyFitness, propertyPosition } from './fitness.ts';
+import type { PropertyKey } from './propertyKeys.ts';
+import { propertyScale } from './scales.ts';
+
+/** Where a bar's fill and its mark go, all as fractions of the track. */
+export interface BarGeometry {
+  /** Where the fill starts, 0 at the left end of the track and 1 at the right. */
+  start: number;
+  /** How much of the track the fill covers, 0 to 1. */
+  length: number;
+  /** How good the value is: 0 as bad as the ramp goes, 1 inside the preferred band. */
+  fitness: number;
+  /**
+   * Where the fill grows from: the left end of the track, or its middle for a
+   * quantity that runs either side of zero. Drawn as a tick, because a fill
+   * that starts at a quarter of the way along says nothing without it.
+   */
+  origin: number;
+  /** Where the published threshold is marked, or `null` where the property has none. */
+  mark: number | null;
+  /** How that threshold reads, e.g. `≤ 5`, or `null`. */
+  markLabel: string | null;
+}
+
+/**
+ * Where a diverging bar grows from: the middle of its own range, which is
+ * drug-likeness 0 and drug score 0.
+ */
+const DIVERGING_ORIGIN = 0.5;
+
+/**
+ * Lay out one property's bar.
+ * @param key - Which of the ten properties.
+ * @param value - The predicted number, or `null` when the predictor could not answer.
+ * @returns The geometry, or `null` when there is no bar to draw.
+ */
+export function barGeometry(
+  key: PropertyKey,
+  value: number | null,
+): BarGeometry | null {
+  const position = propertyPosition(key, value);
+  if (position === null) return null;
+
+  const scale = propertyScale(key);
+  const origin = scale.diverging ? DIVERGING_ORIGIN : 0;
+  const mark =
+    scale.threshold === null
+      ? null
+      : propertyPosition(key, scale.threshold.value);
+
+  return {
+    start: Math.min(origin, position),
+    length: Math.abs(position - origin),
+    fitness: propertyFitness(key, value) ?? 0,
+    origin,
+    mark,
+    markLabel: scale.threshold?.label ?? null,
+  };
+}

package/src/osiris/core/computeProperties.ts

@@ -0,0 +1,175 @@
+/**
+ * Everything the tool predicts about one molecule, in one pass.
+ *
+ * The order of the reads is not arbitrary. `MoleculeProperties`' constructor
+ * normalises ambiguous bonds on the molecule it is handed, so the work is done
+ * on a copy and the caller's molecule — the one the editor is still drawing —
+ * is never touched. Its fields are prototype getters that rerun the whole
+ * predictor on every read, at 13 µs each, and the object cannot be spread or
+ * serialised at all, so each field is read exactly once into a plain object,
+ * and that plain object is what crosses the worker boundary.
+ *
+ * Nothing here trusts OpenChemLib to fail loudly. An empty molecule answers a
+ * full set of innocent numbers and a drug score of 0.63; a failed predictor
+ * answers -999, -1 or 0, never `NaN`; and `DrugScoreCalculator` consumes every
+ * one of those and returns something plausible. So the empty molecule is
+ * refused first, every sentinel becomes `null`, and a drug score is computed
+ * only when all of its inputs are real.
+ */
+
+import type * as OCL from 'openchemlib';
+
+import {
+  NO_FRAGMENT_MATCHED,
+  RISK_TYPE_CODES,
+  UNKNOWN_NUMBER,
+  UNKNOWN_SURFACE_AREA,
+  riskCodeOf,
+  riskLevelOf,
+} from './constants.ts';
+import type { OsirisPredictors } from './predictors.ts';
+import type { OsirisProperties, RiskLevel, RiskType } from './types.ts';
+import { RISK_TYPES } from './types.ts';
+
+/** What a caller knows about the molecule that the molecule does not. */
+export interface ComputePropertiesOptions {
+  /**
+   * The name the source carried. The canonical SMILES is used when there is
+   * none, so a row always has something to be called.
+   * @default the canonical SMILES
+   */
+  label?: string;
+}
+
+/** A structure with no atoms, which has nothing to predict. */
+export const EMPTY_MOLECULE_MESSAGE =
+  'This structure has no atoms, so there is nothing to predict.';
+
+/**
+ * Predict everything the tool shows for one molecule.
+ * @param molecule - The molecule. It is copied before anything touches it, so the caller keeps it exactly as it was.
+ * @param predictors - OpenChemLib with its resources registered and checked.
+ * @param options - See {@link ComputePropertiesOptions}.
+ * @returns The ten numbers, the four risks, and what to call the molecule.
+ * @throws {Error} When the molecule has no atoms.
+ */
+export function computeProperties(
+  molecule: OCL.Molecule,
+  predictors: OsirisPredictors,
+  options: ComputePropertiesOptions = {},
+): OsirisProperties {
+  if (molecule.getAllAtoms() === 0) throw new Error(EMPTY_MOLECULE_MESSAGE);
+
+  const working = molecule.getCompactCopy();
+  const idCode = working.getIDCode();
+  const smiles = working.toIsomericSmiles();
+  const { formula, relativeWeight } = working.getMolecularFormula();
+
+  const properties = new predictors.MoleculeProperties(working);
+  const logP = real(properties.logP, UNKNOWN_NUMBER);
+  const logS = real(properties.logS, UNKNOWN_NUMBER);
+  const polarSurfaceArea = real(
+    properties.polarSurfaceArea,
+    UNKNOWN_SURFACE_AREA,
+  );
+  const acceptorCount = properties.acceptorCount;
+  const donorCount = properties.donorCount;
+  const stereoCenterCount = properties.stereoCenterCount;
+  const rotatableBondCount = properties.rotatableBondCount;
+
+  const assessed = predictors.druglikeness.assessDruglikeness(working);
+  const druglikeness =
+    assessed === UNKNOWN_NUMBER || assessed === NO_FRAGMENT_MATCHED
+      ? null
+      : assessed;
+
+  const risks = assessRisks(working, predictors);
+
+  return {
+    idCode,
+    smiles,
+    label: options.label ?? smiles,
+    molecularFormula: formula,
+    molecularWeight: relativeWeight,
+    logP,
+    logS,
+    polarSurfaceArea,
+    druglikeness,
+    drugScore: drugScore(predictors, {
+      logP,
+      logS,
+      relativeWeight,
+      druglikeness,
+      risks,
+    }),
+    acceptorCount,
+    donorCount,
+    stereoCenterCount,
+    rotatableBondCount,
+    risks,
+  };
+}
+
+function assessRisks(
+  molecule: OCL.Molecule,
+  predictors: OsirisPredictors,
+): Record<RiskType, RiskLevel> {
+  const risks = {} as Record<RiskType, RiskLevel>;
+  for (const risk of RISK_TYPES) {
+    risks[risk] = riskLevelOf(
+      predictors.toxicity.assessRisk(molecule, RISK_TYPE_CODES[risk]),
+    );
+  }
+  return risks;
+}
+
+interface DrugScoreInputs {
+  logP: number | null;
+  logS: number | null;
+  relativeWeight: number;
+  druglikeness: number | null;
+  risks: Record<RiskType, RiskLevel>;
+}
+
+/**
+ * The drug score, or `null` when any of its five inputs was unknown.
+ *
+ * `calculate` never refuses: a drug-likeness of -999 simply makes that factor
+ * exactly 0.5 and the score comes back looking ordinary, and an unassessed risk
+ * applies no penalty where a high one would have applied 0.6. Both read as good
+ * news, which is why they are refused here instead.
+ *
+ * The second argument is the **solubility**. The legacy explorer passed the
+ * polar surface area, which is a different number in a different unit; see the
+ * test that pins both.
+ * @param predictors - OpenChemLib with its resources registered and checked.
+ * @param inputs - The four predicted numbers and the four risks.
+ * @returns The score, or `null` when it cannot be trusted.
+ */
+function drugScore(
+  predictors: OsirisPredictors,
+  inputs: DrugScoreInputs,
+): number | null {
+  const { logP, logS, relativeWeight, druglikeness, risks } = inputs;
+  if (logP === null || logS === null || druglikeness === null) return null;
+
+  const codes: number[] = [];
+  for (const risk of RISK_TYPES) {
+    const level = risks[risk];
+    if (level === 'unknown') return null;
+    codes.push(riskCodeOf(level));
+  }
+
+  return predictors.DrugScoreCalculator.calculate(
+    logP,
+    logS,
+    relativeWeight,
+    druglikeness,
+    codes,
+  );
+}
+
+function real(value: number, sentinel: number): number | null {
+  if (value === sentinel || !Number.isFinite(value)) return null;
+  return value;
+}

package/src/osiris/core/constants.ts

@@ -0,0 +1,110 @@
+/**
+ * The numbers OpenChemLib speaks, and the words this site says instead.
+ *
+ * Two translations live here and nowhere else. The first is the library's risk
+ * numbering, which is easy to get backwards: `ToxicityPredictor.RISK_NAMES` is
+ * indexed by risk *type*, not by risk *level*, and the library exports no level
+ * names at all — so reading a level out of `RISK_NAMES` gives a confident,
+ * wrong answer. The second is the set of sentinels every predictor returns
+ * instead of failing: none of them is `NaN`, and `DrugScoreCalculator` consumes
+ * every one of them and hands back a plausible number.
+ */
+
+import type { RiskLevel, RiskType } from './types.ts';
+
+/**
+ * Where each risk sits in the library's numbering — `TYPE_MUTAGENIC` 0 through
+ * `TYPE_REPRODUCTIVE_EFFECTIVE` 3. It is also the order `DrugScoreCalculator`
+ * expects its `toxRisks` array in.
+ */
+export const RISK_TYPE_CODES: Record<RiskType, number> = {
+  mutagenic: 0,
+  tumorigenic: 1,
+  irritant: 2,
+  reproductive: 3,
+};
+
+/**
+ * What `assessRisk` returns, read as a word: `RISK_UNKNOWN` 0, `RISK_NO` 1,
+ * `RISK_LOW` 2, `RISK_HIGH` 3.
+ */
+export const RISK_LEVELS: readonly RiskLevel[] = [
+  'unknown',
+  'none',
+  'low',
+  'high',
+];
+
+/**
+ * What the library calls each risk, matching `ToxicityPredictor.RISK_NAMES`.
+ * Written out here so reading a label costs no import of a megabyte of
+ * OpenChemLib on a page that only draws a table.
+ */
+export const RISK_LABELS: Record<RiskType, string> = {
+  mutagenic: 'Mutagenicity',
+  tumorigenic: 'Tumorigenicity',
+  irritant: 'Irritating effects',
+  reproductive: 'Reproductive effects',
+};
+
+/**
+ * How each level reads on screen. OSIRIS's own three words, plus one for the
+ * state where the tables did not load — which is not "no risk" and must never
+ * be shown as one.
+ */
+export const RISK_LEVEL_LABELS: Record<RiskLevel, string> = {
+  unknown: 'Not assessed',
+  none: 'No risk',
+  low: 'Medium risk',
+  high: 'High risk',
+};
+
+/**
+ * What each level multiplies the drug score by, decoded from
+ * `DrugScoreCalculator.calculate`. `unknown` applies no factor at all, which is
+ * why a score is refused rather than shown when a risk came back unassessed.
+ */
+export const DRUG_SCORE_RISK_FACTORS: Record<RiskLevel, number> = {
+  unknown: 1,
+  none: 1,
+  low: 0.8,
+  high: 0.6,
+};
+
+/**
+ * What cLogP, solubility and drug-likeness answer when the predictor failed
+ * outright. `CLogPPredictor` returns it on an internal exception, and both
+ * `SolubilityPredictor.cSolubilityUnknown` and
+ * `DruglikenessPredictor.DRUGLIKENESS_UNKNOWN` are this value.
+ */
+export const UNKNOWN_NUMBER = -999;
+
+/** What the polar surface area answers when it is unknown — not `-999`. */
+export const UNKNOWN_SURFACE_AREA = -1;
+
+/**
+ * What `assessDruglikeness` answers when the molecule matched none of the 5294
+ * fragments. It is a real return value, not a failure, and it is
+ * indistinguishable from a drug-likeness that happens to be exactly -1.
+ */
+export const NO_FRAGMENT_MATCHED = -1;
+
+/**
+ * The word for a risk the library answered with a number.
+ * @param code - What `assessRisk` returned, 0 to 3.
+ * @returns The level, `unknown` for anything outside the four the library defines.
+ */
+export function riskLevelOf(code: number): RiskLevel {
+  return RISK_LEVELS[code] ?? 'unknown';
+}
+
+/**
+ * The number the library uses for a level, for the `toxRisks` argument of
+ * `DrugScoreCalculator.calculate`.
+ * @param level - The level.
+ * @returns 0 to 3.
+ */
+export function riskCodeOf(level: RiskLevel): number {
+  const code = RISK_LEVELS.indexOf(level);
+  return code === -1 ? 0 : code;
+}

package/src/osiris/core/fitness.ts

@@ -0,0 +1,59 @@
+/**
+ * How good one predicted number is, from 0 to 1, and where it sits on its bar.
+ *
+ * The fitness is what the green-to-red ramp reads; the position is what the
+ * bar's length reads. They are deliberately two numbers: a molecular weight of
+ * 780 is nearly the full width of its bar and nearly the worst fitness, while
+ * a drug-likeness of 0 is halfway along its bar and exactly half fit.
+ */
+
+import { clamp } from '../../format/core/clamp.ts';
+
+import type { PropertyKey } from './propertyKeys.ts';
+import { propertyScale } from './scales.ts';
+import { getValuation } from './valuation.ts';
+
+/**
+ * How well a value sits in its property's preferred band, from 0 (as bad as
+ * the ramp goes) to 1 (inside the band).
+ *
+ * The drug score is already that fitness — it is the product of the four
+ * valuations `DrugScoreCalculator` computes — so it is returned as it stands
+ * rather than valued a second time.
+ * @param key - Which of the ten properties.
+ * @param value - The predicted number, or `null` when the predictor could not answer.
+ * @returns The fitness, or `null` for an unknown value.
+ */
+export function propertyFitness(
+  key: PropertyKey,
+  value: number | null,
+): number | null {
+  if (value === null || !Number.isFinite(value)) return null;
+  const scale = propertyScale(key);
+  if (scale.halfWidth === null) return clamp(value, 0, 1);
+  return getValuation(
+    value,
+    scale.preferredMin,
+    scale.preferredMax,
+    scale.halfWidth,
+  );
+}
+
+/**
+ * Where a value sits along its bar, from 0 at the left end to 1 at the right.
+ *
+ * Clamped, because a range is a typical spread rather than a bound: cholesterol
+ * runs past the solubility axis and still has to draw.
+ * @param key - Which of the ten properties.
+ * @param value - The predicted number, or `null`.
+ * @returns The position, or `null` for an unknown value.
+ */
+export function propertyPosition(
+  key: PropertyKey,
+  value: number | null,
+): number | null {
+  if (value === null || !Number.isFinite(value)) return null;
+  const { rangeMin, rangeMax } = propertyScale(key);
+  if (rangeMax === rangeMin) return 0;
+  return clamp((value - rangeMin) / (rangeMax - rangeMin), 0, 1);
+}

package/src/osiris/core/index.ts

@@ -0,0 +1,78 @@
+export type { BarGeometry } from './barGeometry.ts';
+export { barGeometry } from './barGeometry.ts';
+export type { ComputePropertiesOptions } from './computeProperties.ts';
+export {
+  EMPTY_MOLECULE_MESSAGE,
+  computeProperties,
+} from './computeProperties.ts';
+export {
+  DRUG_SCORE_RISK_FACTORS,
+  NO_FRAGMENT_MATCHED,
+  RISK_LABELS,
+  RISK_LEVELS,
+  RISK_LEVEL_LABELS,
+  RISK_TYPE_CODES,
+  UNKNOWN_NUMBER,
+  UNKNOWN_SURFACE_AREA,
+  riskCodeOf,
+  riskLevelOf,
+} from './constants.ts';
+export { propertyFitness, propertyPosition } from './fitness.ts';
+export { MAX_POOL_SIZE, predictionPoolSize } from './poolSize.ts';
+export type {
+  PredictionInput,
+  PredictionOutcome,
+  PredictionPool,
+  PredictionPoolOptions,
+  PredictionProgress,
+} from './poolTypes.ts';
+export {
+  UNREADABLE_ID_CODE_MESSAGE,
+  predictIdCode,
+  riskDetailOfIdCode,
+} from './predictIdCode.ts';
+export type {
+  PredictRequest,
+  PredictResponse,
+  PropertiesRequest,
+  RiskDetailRequest,
+} from './predictProtocol.ts';
+export { isPredictRequest } from './predictProtocol.ts';
+export { createPredictionPool } from './predictionPool.ts';
+export type { PredictionQueue } from './predictionQueue.ts';
+export { createPredictionQueue } from './predictionQueue.ts';
+export type { OsirisPredictors, ResourceSource } from './predictors.ts';
+export {
+  PredictorsUnavailableError,
+  loadPredictors,
+  resetPredictors,
+} from './predictors.ts';
+export type { PropertyKey } from './propertyKeys.ts';
+export { PROPERTY_KEYS, isPropertyKey, propertyValue } from './propertyKeys.ts';
+export type { RiskAppearance, RiskTone } from './riskAppearance.ts';
+export {
+  KNOWN_MOLECULE_NOTE,
+  PENDING_RISK_LABEL,
+  RISK_CAVEAT,
+  riskAppearance,
+} from './riskAppearance.ts';
+export { riskDetail } from './riskDetail.ts';
+export { parseRiskFindings } from './riskFindings.ts';
+export { runPredictionJob } from './runPredictionJob.ts';
+export type {
+  PropertyScale,
+  PropertyThreshold,
+  ScaleSource,
+} from './scales.ts';
+export { PROPERTY_SCALES, propertyScale } from './scales.ts';
+export type {
+  DetailEntry,
+  OsirisProperties,
+  RiskDetail,
+  RiskFinding,
+  RiskFindingKind,
+  RiskLevel,
+  RiskType,
+} from './types.ts';
+export { RISK_TYPES } from './types.ts';
+export { getValuation } from './valuation.ts';

package/src/osiris/core/poolSize.ts

@@ -0,0 +1,24 @@
+/**
+ * How many workers to run.
+ *
+ * One fewer than the machine's cores, so the thread that draws the table keeps
+ * one to itself, and never more than eight: measured scaling is 2.45x on two
+ * workers and 4.57x on four, and each worker costs its own copy of OpenChemLib
+ * and of the 398 kB resource tables.
+ */
+
+import { clamp } from '../../format/core/clamp.ts';
+
+/** The most workers the pool will ever run. */
+export const MAX_POOL_SIZE = 8;
+
+/**
+ * How many workers a pool should run here.
+ * @param requested - What the caller asked for, or `undefined` to read the machine.
+ * @returns A count between 1 and {@link MAX_POOL_SIZE}.
+ */
+export function predictionPoolSize(requested?: number): number {
+  const cores = globalThis.navigator?.hardwareConcurrency;
+  const wanted = requested ?? (typeof cores === 'number' ? cores - 1 : 1);
+  return Math.trunc(clamp(wanted, 1, MAX_POOL_SIZE, 1));
+}

package/src/osiris/core/poolTypes.ts

@@ -0,0 +1,140 @@
+/**
+ * What a page asks the prediction pool, and what it hears back.
+ *
+ * A prediction costs 210 to 380 ms of one thread, so a set of any size is
+ * answered a molecule at a time rather than all at once: a row appears as soon
+ * as it is read and fills in when its worker returns. Everything here is shaped
+ * around that — a per-result callback rather than a promise over the set, a
+ * progress figure, a cancel that works, and a way to say which rows the reader
+ * can actually see so those are computed first.
+ */
+
+import type { WorkerLike } from '../../worker/core/messages.ts';
+
+import type { PredictRequest, PredictResponse } from './predictProtocol.ts';
+import type { ResourceSource } from './predictors.ts';
+import type { OsirisProperties, RiskDetail, RiskType } from './types.ts';
+
+/** One molecule to predict. */
+export interface PredictionInput {
+  /**
+   * The caller's key for the row, echoed on the answer. It is the row's read
+   * position, never its idCode: a real list holds the same structure twice
+   * under two names, and both rows have to fill in.
+   */
+  key: string;
+  /** The idCode, with the editor's atom coordinates after a space or without. */
+  idCode: string;
+  /**
+   * The name the source carried.
+   * @default the canonical SMILES
+   */
+  label?: string;
+}
+
+/** What came back for one molecule. */
+export type PredictionOutcome =
+  | { key: string; ok: true; properties: OsirisProperties }
+  | { key: string; ok: false; message: string };
+
+/** How far the pool has got. */
+export interface PredictionProgress {
+  /** Molecules answered, whether predicted or refused. */
+  done: number;
+  /** Molecules accepted since the run started. */
+  total: number;
+  /** Molecules still queued or still being worked on. */
+  pending: number;
+  /** Whether anything is still to come. */
+  running: boolean;
+}
+
+/** How a pool is built, and who it reports to. */
+export interface PredictionPoolOptions {
+  /**
+   * Where the workers register OpenChemLib's resources from — the absolute URL
+   * of the site's own `openchemlib-resources.json`, resolved on the main
+   * thread. See {@link ResourceSource}.
+   */
+  resources: ResourceSource;
+  /**
+   * How many workers to run. Clamped to 1 to 8.
+   * @default one fewer than the machine's cores, which measured 2.45x on two workers and 4.57x on four
+   */
+  size?: number;
+  /**
+   * Makes one worker, which serves `runPredictionJob` for the requests
+   * `isPredictRequest` accepts. Only called where the page has a `Worker` at
+   * all. The site writes it because a bundler resolves a worker's address
+   * against the module naming it: written in this package, the URL would point
+   * inside `node_modules` rather than at a chunk the site's build emitted.
+   */
+  createWorker: () => WorkerLike;
+  /**
+   * The same job on this thread, used where there is no `Worker` — Node, a
+   * unit test.
+   * @default `runPredictionJob`, the same function the worker serves
+   */
+  runInProcess?: (request: PredictRequest) => Promise<PredictResponse>;
+  /**
+   * Called once per molecule, as each one comes back.
+   * @default undefined
+   */
+  onResult?: (outcome: PredictionOutcome) => void;
+  /**
+   * Called whenever the count of answered molecules changes.
+   * @default undefined
+   */
+  onProgress?: (progress: PredictionProgress) => void;
+  /**
+   * Called once when the resource tables did not load. Every answer from every
+   * worker would be `unknown`, so the run stops and nothing more is dispatched.
+   * @default undefined
+   */
+  onUnavailable?: (message: string) => void;
+  /**
+   * Milliseconds one molecule may take before it is given up on.
+   * @default 60000
+   */
+  timeoutMs?: number;
+}
+
+/** A pool of workers answering one molecule at a time, each. */
+export interface PredictionPool {
+  /** How many workers it runs. */
+  readonly size: number;
+  /** How far it has got. */
+  readonly progress: PredictionProgress;
+  /**
+   * Add molecules to predict. One already queued or in flight is ignored, so a
+   * page may resubmit its whole set whenever the set changes.
+   * @param molecules - The molecules.
+   */
+  submit: (molecules: readonly PredictionInput[]) => void;
+  /**
+   * Say which rows to answer first — the ones the reader can see. Molecules
+   * already being worked on are left alone; only what is still queued moves.
+   * @param keys - The keys, most wanted first.
+   */
+  prioritize: (keys: readonly string[]) => void;
+  /**
+   * Why one risk came back as it did. Jumps the queue, because it is a click.
+   * A {@link PredictionPool.cancel} is about the set, not about the click, so
+   * an explanation it drops is asked for again.
+   * @param idCode - The molecule, coordinates included or not.
+   * @param risk - Which of the four risks to explain.
+   * @returns The findings, with the matched atoms and bonds of every fragment.
+   * @throws {Error} When even the second ask was dropped, with a sentence to show the reader.
+   */
+  riskDetail: (idCode: string, risk: RiskType) => Promise<RiskDetail>;
+  /**
+   * Drop everything queued and stop reporting. The molecule each worker is
+   * already on cannot be interrupted — the library call is synchronous — so it
+   * finishes and its answer is thrown away, within about 400 ms. A
+   * {@link PredictionPool.submit} made in the same turn is still dispatched, on
+   * the slots those abandoned answers free.
+   */
+  cancel: () => void;
+  /** Cancel, and end every worker. */
+  terminate: () => void;
+}