@insiderfinance/totalfinance/strategy/scanner

value

SCAN_OBJECTIVES

Every ranking objective a scan accepts, as DATA — the single source the type, the runtime guard and the error message are all derived from. RV11 — these were three copies: a hand-written union here, a hand-written array in `optimizer.ts`, and a third hand-written list inside the error string. The string copy drifted and kept teaching `pop|ev` after both were renamed, because plain prose is invisible to a rename of the quoted literals. One tuple, and `.join(', ')` for the message, is what makes that impossible rather than merely fixed. `'return'` became `'returnOnRisk'` in the same pass: it ranked by `returnOnRisk` and the candidate output already called that number `returnOnRisk`, so one quantity carried two public names.

export declare const SCAN_OBJECTIVES: readonly ['probabilityOfProfit', 'expectedValue', 'returnOnRisk', 'expectedValuePerRisk'];

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

Declared field units are shown above. “Unitless by name” means the name alone does not establish a unit, not that a financial quantity has none. Check source descriptions, conventions, and the returned diagnostics. Errors and warnings are part of the result contract.

interface

ScanCandidate

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface ScanCandidate {
    structure: ScanStructure;
    /** The structure's strikes, ascending. */
    strikes: number[];
    /** Net debit (> 0 paid) or credit (< 0 received), PER CONTRACT (multiplier-scaled, 100×) — the
     * same units as `maxProfit`/`maxLoss`/`expectedValue` and `Position.netDebit()`. */
    netDebit: number;
    /** Max profit / max loss / expected value are per contract (100× multiplier, as in `Position`). */
    maxProfit: number | null;
    maxLoss: number | null;
    /** Whether each tail of the expiration payoff is bounded (a `null` bound above is unbounded). */
    bounded: {
        profit: boolean;
        loss: boolean;
    };
    breakevens: number[];
    probabilityOfProfit: number;
    expectedValue: number;
    /**
     * `|maxProfit / maxLoss|` — the same definition as `Position.probability().riskReward` — or
     * `null` when undefined (an unbounded side or a zero max loss). Never `Infinity` (B3).
     */
    returnOnRisk: number | null;
    /** `expectedValue / |maxLoss|` — a risk-normalized EV; 0 when risk is unbounded. */
    expectedValuePerRisk: number;
    /** Liquidity in `[0, 1]` from the legs' relative bid/ask spreads (1 = tight), null if unpriced. */
    liquidity: number | null;
    /** The value of the ranking objective for this candidate; `null` when the objective is undefined for it. */
    score: number | null;
    /**
     * The resolved legs (premiums included, whatever their source), so every candidate is
     * MATERIALIZABLE (WS7.3): `strategy(candidate.legs)` reconstructs the exact position for charting or
     * mark-to-market, and `strategy(candidate.legs).metrics()` reproduces the reported payoff metrics.
     */
    legs: Leg[];
}

Fields, parameters & returned members (16)

Name / type	Meaning & unit	Optional / default
`bounded` `{ profit: boolean; loss: boolean; }`	Whether each tail of the expiration payoff is bounded (a `null` bound above is unbounded). unitless by name	Required / declared member No @default declared; consult the signature and description.
`bounded.loss` `boolean`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`bounded.profit` `boolean`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`breakevens` `number[]`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`expectedValue` `number`	currency amount (the field or record currency)	Required / declared member No @default declared; consult the signature and description.
`expectedValuePerRisk` `number`	`expectedValue / \|maxLoss\|` — a risk-normalized EV; 0 when risk is unbounded. unitless by name	Required / declared member No @default declared; consult the signature and description.
`legs` `Leg[]`	The resolved legs (premiums included, whatever their source), so every candidate is MATERIALIZABLE (WS7.3): `strategy(candidate.legs)` reconstructs the exact position for charting or mark-to-market, and `strategy(candidate.legs).metrics()` reproduces the reported payoff metrics. unitless by name	Required / declared member No @default declared; consult the signature and description.
`liquidity` `number \| null`	Liquidity in `[0, 1]` from the legs' relative bid/ask spreads (1 = tight), null if unpriced. unitless by name	Required / declared member No @default declared; consult the signature and description.
`maxLoss` `number \| null`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`maxProfit` `number \| null`	Max profit / max loss / expected value are per contract (100× multiplier, as in `Position`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`netDebit` `number`	Net debit (> 0 paid) or credit (< 0 received), PER CONTRACT (multiplier-scaled, 100×) — the same units as `maxProfit`/`maxLoss`/`expectedValue` and `Position.netDebit()`. unitless by name	Required / declared member No @default declared; consult the signature and description.
`probabilityOfProfit` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`returnOnRisk` `number \| null`	`\|maxProfit / maxLoss\|` — the same definition as `Position.probability().riskReward` — or `null` when undefined (an unbounded side or a zero max loss). Never `Infinity` (B3). unitless by name	Required / declared member No @default declared; consult the signature and description.
`score` `number \| null`	The value of the ranking objective for this candidate; `null` when the objective is undefined for it. unitless by name	Required / declared member No @default declared; consult the signature and description.
`strikes` `number[]`	The structure's strikes, ascending. unitless by name	Required / declared member No @default declared; consult the signature and description.
`structure` `ScanStructure`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

type

ScanObjective

Ranking objective; `expectedValuePerRisk` (expected value ÷ max loss) is the default.

/** Ranking objective; `expectedValuePerRisk` (expected value ÷ max loss) is the default. */
export type ScanObjective = (typeof SCAN_OBJECTIVES)[number];

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

ScanOptions

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface ScanOptions {
    /** Underlying spot price (WS3.2: renamed from `underlyingPrice` for workspace consistency). */
    spot: number;
    /**
     * Valuation instant. Epoch ms or a zoned ISO datetime, resolved at the boundary by core's
     * `resolveValuationAsOf` — the ONE valuation-instant grammar shared by `Position.probability()`,
     * the what-if cube and every other pricing boundary. A bare date is refused: a 0DTE's value
     * depends on the time of day.
     */
    asOf: EpochMs | string;
    /** Option expiry (`YYYY-MM-DD` → 16:00 ET, or a full datetime). */
    expiry: string;
    riskFreeRate: number;
    dividendYield?: number;
    /** The option chain — one row per strike, ascending or not (sorted internally). */
    chain: ScanQuoteRow[];
    /** Constant annualized volatility used for probabilityOfProfit / expectedValue scoring and to price any missing premiums. */
    volatility?: number;
    /**
     * Per-strike implied-volatility smile. Used to price any missing per-strike premiums (takes
     * precedence over `volatility`). **Scoring uses a SINGLE volatility:** `probabilityOfProfit` and
     * `expectedValue` are computed closed-form at the at-spot volatility `smile(spot)` (or
     * `volatility`), not the full smile — for smile-consistent probabilities, price a specific structure
     * with `Position.monteCarloProbability({ localVolatility })`.
     */
    smile?: (strike: number) => number;
    /** Which structures to enumerate (default: all). */
    structures?: ScanStructure[];
    /** Cap on the width (strike distance) of any single wing/spread, in price units. */
    maxWidth?: number;
    /** Keep only candidates with probability-of-profit ≥ this. */
    minProbabilityOfProfit?: number;
    /** Keep only candidates whose max loss ≤ this (in the position's P&L units — per contract, 100×). */
    maxRisk?: number;
    /** Ranking objective (default `expectedValuePerRisk`). */
    rankBy?: ScanObjective;
    /** Return only the top-N ranked candidates (default 25). */
    top?: number;
}

Fields, parameters & returned members (15)

Name / type	Meaning & unit	Optional / default
`asOf` `string \| number`	Valuation instant. Epoch ms or a zoned ISO datetime, resolved at the boundary by core's `resolveValuationAsOf` — the ONE valuation-instant grammar shared by `Position.probability()`, the what-if cube and every other pricing boundary. A bare date is refused: a 0DTE's value depends on the time of day. an instant: epoch milliseconds or a YYYY-MM-DD / zoned ISO string (the resolveAsOf convention)	Required / declared member No @default declared; consult the signature and description.
`chain` `ScanQuoteRow[]`	The option chain — one row per strike, ascending or not (sorted internally). unitless by name	Required / declared member No @default declared; consult the signature and description.
`dividendYield` `number`	decimal rate (0.05 = 5%)	Optional No @default declared; consult the signature and description.
`expiry` `string`	Option expiry (`YYYY-MM-DD` → 16:00 ET, or a full datetime). unitless by name	Required / declared member No @default declared; consult the signature and description.
`maxRisk` `number`	Keep only candidates whose max loss ≤ this (in the position's P&L units — per contract, 100×). unitless by name	Optional No @default declared; consult the signature and description.
`maxWidth` `number`	Cap on the width (strike distance) of any single wing/spread, in price units. unitless by name	Optional No @default declared; consult the signature and description.
`minProbabilityOfProfit` `number`	Keep only candidates with probability-of-profit ≥ this. unitless by name	Optional No @default declared; consult the signature and description.
`rankBy` `'probabilityOfProfit' \| 'expectedValue' \| 'returnOnRisk' \| 'expectedValuePerRisk'`	Ranking objective (default `expectedValuePerRisk`). unitless by name	Optional No @default declared; consult the signature and description.
`riskFreeRate` `number`	decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`smile` `(strike: number) => number`	Per-strike implied-volatility smile. Used to price any missing per-strike premiums (takes precedence over `volatility`). Scoring uses a SINGLE volatility: `probabilityOfProfit` and `expectedValue` are computed closed-form at the at-spot volatility `smile(spot)` (or `volatility`), not the full smile — for smile-consistent probabilities, price a specific structure with `Position.monteCarloProbability({ localVolatility })`. unitless by name	Optional No @default declared; consult the signature and description.
`smile(strike)` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`spot` `number`	Underlying spot price (WS3.2: renamed from `underlyingPrice` for workspace consistency). unitless by name	Required / declared member No @default declared; consult the signature and description.
`structures` `ScanStructure[]`	Which structures to enumerate (default: all). unitless by name	Optional No @default declared; consult the signature and description.
`top` `number`	Return only the top-N ranked candidates (default 25). unitless by name	Optional No @default declared; consult the signature and description.
`volatility` `number`	Constant annualized volatility used for probabilityOfProfit / expectedValue scoring and to price any missing premiums. unitless by name	Optional No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

ScanQuoteRow

One strike's market data. `call`/`put` are mid premiums; bid/ask feed the liquidity score.

/** One strike's market data. `call`/`put` are mid premiums; bid/ask feed the liquidity score. */
export interface ScanQuoteRow {
    strike: number;
    /** Call mid premium. If omitted, priced from `volatility`/`smile` via Black–Scholes. */
    call?: number;
    /** Put mid premium. If omitted, priced from `volatility`/`smile` via Black–Scholes. */
    put?: number;
    callBid?: number;
    callAsk?: number;
    putBid?: number;
    putAsk?: number;
}

Fields, parameters & returned members (7)

Name / type	Meaning & unit	Optional / default
`call` `number`	Call mid premium. If omitted, priced from `volatility`/`smile` via Black–Scholes. unitless by name	Optional No @default declared; consult the signature and description.
`callAsk` `number`	unitless by name	Optional No @default declared; consult the signature and description.
`callBid` `number`	unitless by name	Optional No @default declared; consult the signature and description.
`put` `number`	Put mid premium. If omitted, priced from `volatility`/`smile` via Black–Scholes. unitless by name	Optional No @default declared; consult the signature and description.
`putAsk` `number`	unitless by name	Optional No @default declared; consult the signature and description.
`putBid` `number`	unitless by name	Optional No @default declared; consult the signature and description.
`strike` `number`	unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

ScanResult

The scan report (Law 2 report grammar): the ranked candidates plus the applied conventions (`assumptions`) and a warnings channel (`diagnostics`).

/**
 * The scan report (Law 2 report grammar): the ranked candidates plus the applied conventions
 * (`assumptions`) and a warnings channel (`diagnostics`).
 */
export interface ScanResult {
    /** The top-N candidates by the ranking objective, descending, each fully metric'd. */
    candidates: ScanCandidate[];
    /** Applied conventions, echoed (Law 2 report grammar). */
    assumptions: {
        conventionsVersion: string;
        dayCount: 'ACT/365F';
        /** The ranking objective that produced the order (and each candidate's `score`). */
        rankBy: ScanObjective;
        /** The structures that were enumerated. */
        structures: ScanStructure[];
        /** Year fraction to the scanned expiry. */
        timeToExpiryYears: number;
        /** The single at-spot volatility that `probabilityOfProfit`/`expectedValue` are scored at (see the `smile` doc). */
        scoringVolatility: number;
    };
    /** Structured warnings; always present (possibly empty). */
    diagnostics: Diagnostics;
}

Fields, parameters & returned members (26)

Name / type	Meaning & unit	Optional / default
`assumptions` `{ conventionsVersion: string; dayCount: 'ACT/365F'; rankBy: ScanObjective; scoringVolatility: number; structures: ScanStructure[]; timeToExpiryYears: number; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.dayCount` `'ACT/365F'`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`assumptions.rankBy` `'probabilityOfProfit' \| 'expectedValue' \| 'returnOnRisk' \| 'expectedValuePerRisk'`	The ranking objective that produced the order (and each candidate's `score`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.scoringVolatility` `number`	The single at-spot volatility that `probabilityOfProfit`/`expectedValue` are scored at (see the `smile` doc). unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.structures` `ScanStructure[]`	The structures that were enumerated. unitless by name	Required / declared member No @default declared; consult the signature and description.
`assumptions.timeToExpiryYears` `number`	Year fraction to the scanned expiry. years (decimal)	Required / declared member No @default declared; consult the signature and description.
`candidates` `ScanCandidate[]`	The top-N candidates by the ranking objective, descending, each fully metric'd. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics` `Diagnostics`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.autoReason` `string`	When a meta-engine (e.g. `engines.auto()`) selected a delegate, this is a one-sentence, human-readable explanation of WHY that delegate was chosen (`engine` then names the delegate). Absent when no auto-selection took place. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.converged` `boolean`	Whether an iterative procedure converged. `false` means the value is not trustworthy. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.decomposition` `Record<string, number>`	Named intermediate quantities the value decomposes into — a par spread's protection leg and risky annuity, a forward variance's near/far legs. The H-series explain paths disclose their arithmetic here so a caller can audit the ratio, not just receive it (3B.3). unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.engine` `string`	Pricing/solver engine name, e.g. `black-scholes-merton`. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.finiteDifferenceBumps` `Record<string, number>`	Finite-difference engines: the ACTUAL bump sizes used for FD Greeks (spec P2.3) — adaptive near the vol/time boundaries, so the caller can see exactly what was differenced. Keys: `spotStep`, `volatilityStep`, `timeStepYears`, `rateStep`, and — extended Greeks only — `dividendYieldStep`. Each is the actual step differenced, in the unit of the coordinate it bumps. (This doc named the retired `hS`/`hSig`/`hT`/`hR`/`hQ` keys for one release after the emit sites had moved to the semantic names, so a caller following it read `undefined`.) unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.iterations` `number`	Iteration count for iterative methods. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.method` `string`	Numerical method, e.g. `closed-form`, `brent`, `finite-difference`. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection` `import('@insiderfinance/totalfinance/core/pricing').SelectionReport`	The structured engine-selection report (Gate C, `@insiderfinance/totalfinance/core/pricing`): who was selected, why, and — for automatic selection — every candidate considered with its verdict. This is the machine-readable superset of `engine` + `autoReason` (which remain for compatibility); `selected.name` always agrees with `engine` when both are present. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection.candidates` `readonly import('@insiderfinance/totalfinance/core/pricing').SelectionCandidate[]`	Candidates an automatic selection considered; absent for explicit mode. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.selection.mode` `'explicit' \| 'automatic'`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.reason` `string`	Why the selected engine answers this request. unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected` `{ name: string; version?: string; }`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected.name` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`diagnostics.selection.selected.version` `string`	unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.timingMs` `number`	Wall-clock timing in milliseconds, when measured. milliseconds	Optional No @default declared; consult the signature and description.
`diagnostics.warmup` `number`	Series facades: number of leading output slots that are warmup sentinels (null/NaN) while the computation seeds. Equals the input length when the indicator never emitted. unitless by name	Optional No @default declared; consult the signature and description.
`diagnostics.warnings` `import('@insiderfinance/totalfinance/core').QuantWarning[]`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

type

ScanStructure

The structures the scanner can enumerate (all single-expiry, defined-risk or long-premium).

/** The structures the scanner can enumerate (all single-expiry, defined-risk or long-premium). */
export type ScanStructure = 'bullCallSpread' | 'bearCallSpread' | 'bullPutSpread' | 'bearPutSpread' | 'ironCondor' | 'ironButterfly' | 'longCallButterfly' | 'longPutButterfly' | 'straddle' | 'strangle';

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

scanStrategies

Enumerate, score, and rank option structures over a strike grid. `candidates` carries the top-N by the chosen objective, each with the full payoff/probability metrics.

export declare function scanStrategies(options: ScanOptions): ScanResult;

Fields, parameters & returned members (24)

Name / type	Meaning & unit	Optional / default
`(options)` `ScanOptions`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`(options).asOf` `string \| number`	Valuation instant. Epoch ms or a zoned ISO datetime, resolved at the boundary by core's `resolveValuationAsOf` — the ONE valuation-instant grammar shared by `Position.probability()`, the what-if cube and every other pricing boundary. A bare date is refused: a 0DTE's value depends on the time of day. an instant: epoch milliseconds or a YYYY-MM-DD / zoned ISO string (the resolveAsOf convention)	Required / declared member No @default declared; consult the signature and description.
`(options).chain` `ScanQuoteRow[]`	The option chain — one row per strike, ascending or not (sorted internally). unitless by name	Required / declared member No @default declared; consult the signature and description.
`(options).dividendYield` `number`	decimal rate (0.05 = 5%)	Optional No @default declared; consult the signature and description.
`(options).expiry` `string`	Option expiry (`YYYY-MM-DD` → 16:00 ET, or a full datetime). unitless by name	Required / declared member No @default declared; consult the signature and description.
`(options).maxRisk` `number`	Keep only candidates whose max loss ≤ this (in the position's P&L units — per contract, 100×). unitless by name	Optional No @default declared; consult the signature and description.
`(options).maxWidth` `number`	Cap on the width (strike distance) of any single wing/spread, in price units. unitless by name	Optional No @default declared; consult the signature and description.
`(options).minProbabilityOfProfit` `number`	Keep only candidates with probability-of-profit ≥ this. unitless by name	Optional No @default declared; consult the signature and description.
`(options).rankBy` `'probabilityOfProfit' \| 'expectedValue' \| 'returnOnRisk' \| 'expectedValuePerRisk'`	Ranking objective (default `expectedValuePerRisk`). unitless by name	Optional No @default declared; consult the signature and description.
`(options).riskFreeRate` `number`	decimal rate (0.05 = 5%)	Required / declared member No @default declared; consult the signature and description.
`(options).smile` `(strike: number) => number`	Per-strike implied-volatility smile. Used to price any missing per-strike premiums (takes precedence over `volatility`). Scoring uses a SINGLE volatility: `probabilityOfProfit` and `expectedValue` are computed closed-form at the at-spot volatility `smile(spot)` (or `volatility`), not the full smile — for smile-consistent probabilities, price a specific structure with `Position.monteCarloProbability({ localVolatility })`. unitless by name	Optional No @default declared; consult the signature and description.
`(options).spot` `number`	Underlying spot price (WS3.2: renamed from `underlyingPrice` for workspace consistency). unitless by name	Required / declared member No @default declared; consult the signature and description.
`(options).structures` `ScanStructure[]`	Which structures to enumerate (default: all). unitless by name	Optional No @default declared; consult the signature and description.
`(options).top` `number`	Return only the top-N ranked candidates (default 25). unitless by name	Optional No @default declared; consult the signature and description.
`(options).volatility` `number`	Constant annualized volatility used for probabilityOfProfit / expectedValue scoring and to price any missing premiums. unitless by name	Optional No @default declared; consult the signature and description.
`return.assumptions` `{ conventionsVersion: string; dayCount: 'ACT/365F'; rankBy: ScanObjective; scoringVolatility: number; structures: ScanStructure[]; timeToExpiryYears: number; }`	Applied conventions, echoed (Law 2 report grammar). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.conventionsVersion` `string`	unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.dayCount` `'ACT/365F'`	count (integer)	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.rankBy` `'probabilityOfProfit' \| 'expectedValue' \| 'returnOnRisk' \| 'expectedValuePerRisk'`	The ranking objective that produced the order (and each candidate's `score`). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.scoringVolatility` `number`	The single at-spot volatility that `probabilityOfProfit`/`expectedValue` are scored at (see the `smile` doc). unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.structures` `ScanStructure[]`	The structures that were enumerated. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.assumptions.timeToExpiryYears` `number`	Year fraction to the scanned expiry. years (decimal)	Required / declared member No @default declared; consult the signature and description.
`return.candidates` `ScanCandidate[]`	The top-N candidates by the ranking objective, descending, each fully metric'd. unitless by name	Required / declared member No @default declared; consult the signature and description.
`return.diagnostics` `Diagnostics`	Structured warnings; always present (possibly empty). unitless by name	Required / declared member No @default declared; consult the signature and description.

Stability, warnings & conventions

stable-by-law (pre-1.0; not a 1.0 stability guarantee)