@vessel-dsp/runtime 0.2.0

package/dist/reference-runtime.d.ts

@@ -0,0 +1,1080 @@
+import type { ClockLawParams, ControlId, DelayLengthSpec, Program } from "@vessel-dsp/compiler";
+import { type RealtimeBudget } from "./admission";
+import type { SupplyAddress, SupplyInfo } from "./supply";
+/**
+ * What the solver did, so that failing to solve is never silent.
+ *
+ * A Newton loop that exhausts its iteration cap and then uses whatever iterate it
+ * happens to hold produces plausible audio for a circuit it did not actually solve --
+ * the same shape as a device law with no stamp, and just as invisible. Counting the
+ * failures is the minimum; a real-time runtime cannot throw mid-buffer, but it must
+ * never pretend.
+ */
+export type RuntimeTelemetry = {
+    readonly samples: number;
+    /** Samples where Newton hit the iteration cap without meeting tolerance. */
+    readonly nonConvergedSamples: number;
+    /** Samples that stopped moving without satisfying the equations. See `stalledSamples`. */
+    readonly stalledSamples: number;
+    /** Samples that stopped moving WITH the equations satisfied, rejected only by a limiter flag. */
+    readonly solvedButFlaggedSamples: number;
+    /**
+     * Per-block Newton census, most-exhausted first. The only counter here that can say which
+     * packets a change to the iteration budget would touch — the two host-level ones cannot.
+     */
+    readonly blockNewtonCensus: readonly {
+        readonly blockId: string;
+        readonly samples: number;
+        readonly exhausted: number;
+        readonly peakIterations: number;
+    }[];
+    /** Samples where the solve produced a non-finite value and was discarded. */
+    readonly nonFiniteSamples: number;
+    /** Largest iteration count any sample needed. */
+    readonly peakIterations: number;
+    /**
+     * Blocks whose DC operating point did not solve, so they started from zero state and
+     * are charging through a transient the run will otherwise measure as the circuit.
+     */
+    readonly operatingPointFailures: number;
+    /**
+     * The largest supply current the DC solve drew, in amps, across every `dc-source` branch.
+     *
+     * A pedal draws single-digit milliamps. This exists because an **ideal source hides a
+     * catastrophic load**: measured, `ibanez-ts808` draws **193 A** through the short that
+     * `diode-forward-across-supply` warns about, and renders a plausible gain of 0.506 anyway,
+     * because a source with no impedance supplies whatever is asked of it. Nothing in the audio
+     * says so and no telemetry counter moved.
+     *
+     * Reported rather than judged: the runtime does not know what a plausible draw is for a
+     * circuit it was handed, and a threshold here would be a guess. A consumer comparing this
+     * against a pedal's datasheet current does know.
+     *
+     * **It is blind to an AC supply, by construction, and zero here is not "no short".** The
+     * operating point evaluates an `ac-source` at its `t = 0` value, which is zero volts, so a
+     * mains inlet with a dead short across it draws nothing at DC and this figure stays at 0.
+     * `renderedSupplyPeakAmps` is the figure that can see it.
+     */
+    readonly operatingPointSupplyAmps: number;
+    /**
+     * The largest supply current seen **while rendering**, in amps, across every `dc-source` and
+     * `ac-source` branch — or `null` when no sample has been processed.
+     *
+     * `null` rather than 0 for the unmeasured case, deliberately. The failure this field exists
+     * to prevent is a reader taking `operatingPointSupplyAmps: 0` for "no short", and a second
+     * zero would reproduce it exactly: a reader cannot tell "measured, and nothing flowed" from
+     * "nobody rendered anything". A skipped input is a skip, not a pass.
+     *
+     * It answers a question the DC figure cannot even ask. An AC supply is zero at the operating
+     * point, so its whole current lives in the render; and a DC short that only appears under
+     * drive — a diode that turns on when the signal arrives — is invisible at DC as well. On a
+     * static DC circuit the two figures agree, which is what makes this one checkable against the
+     * older one rather than a second opinion.
+     *
+     * A **peak** rather than a mean, for the same reason the Newton deadline reports peak
+     * iterations: a mean over a mains cycle hides the conduction pulse, which is where a
+     * rectifier's current is. Read from the solved branch unknowns, so a held sample contributes
+     * the last state that actually solved.
+     */
+    readonly renderedSupplyPeakAmps: number | null;
+    /**
+     * Iterations summed over every sample and every nonlinear block.
+     *
+     * Peak alone cannot tell a deadline apart from a spike: a circuit averaging 4
+     * iterations with one 1500-iteration sample and a circuit needing 1500 every sample
+     * report the same peak and have completely different real-time answers. The first
+     * needs a bounded solver, the second is not a real-time circuit at all.
+     */
+    readonly totalIterations: number;
+    /**
+     * Why the last non-converged sample failed, which the counts alone cannot say.
+     *
+     * Two failures look identical in `nonConvergedSamples` and need opposite fixes: a node
+     * still genuinely moving (`delta` large) is a solver or model problem, while a tiny
+     * `delta` with `limited` set means the answer had arrived and a limiter was still
+     * firing, so the convergence *test* is what refused. Guessing between them cost two
+     * wrong hypotheses on `boss-od-3`.
+     */
+    readonly lastFailure: {
+        readonly node: number;
+        readonly delta: number;
+        readonly limited: boolean;
+        /** Which element limited, as kind plus nodes, when one did. */
+        readonly limitedBy: string | null;
+    } | null;
+};
+/**
+ * A solved branch current, one per auxiliary unknown.
+ *
+ * **Sign convention: positive is current flowing into the element's first terminal from the
+ * circuit**, which is the MNA stamp's own orientation — a `dc-source` row asserts
+ * `v(positive) - v(negative) = volts` and contributes `+i` to the positive node's equation, so
+ * a supply *delivering* power to the circuit reads **negative**. Corroborated on the corpus:
+ * every compiled pedal's supply reads negative, `boss-bd-2-blues-driver` at `-9.92 mA`.
+ *
+ * This exists because the current through a supply is not derivable from node voltages: the
+ * source is ideal, so no impedance relates its voltage to its current, and the aux unknown is
+ * the only place the value lives. `nodeVoltageSnapshot` slices the aux tail off, which left rail
+ * current unreachable through the public API — the first thing the power-domain rail/sag
+ * contract in `thoughts/shared/experiments/power-domain-rail-sag-contract/` asks for.
+ */
+export type RuntimeBranchCurrent = {
+    readonly blockId: string;
+    /** The stamp kind owning the unknown: the five that add an auxiliary row. */
+    readonly kind: "dc-source" | "ac-source" | "input-source" | "ideal-opamp" | "transformer";
+    readonly sourceIndex: number;
+    readonly amps: number;
+};
+export type RuntimeNodeVoltageSnapshot = {
+    readonly blockId: string;
+    readonly nodeCount: number;
+    /** `outputNode` and every index into `voltages` is a row, not a source node id. */
+    readonly outputNode: number | null;
+    readonly voltages: readonly number[];
+    /**
+     * The block's `nodeIds`, carried through so a caller can name a row.
+     *
+     * Without it a consumer holding source-keyed data -- the terminal labels
+     * `render-v2-audio.ts --held` prints beside each voltage, say -- has no way back from a
+     * row to the net the document authored, and indexing that data by the row instead
+     * attaches the wrong label to a real voltage. That reads as a circuit fault rather than
+     * a reporting one.
+     */
+    readonly nodeIds: readonly number[];
+};
+export declare class RuntimeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Fundamental of a window by normalized autocorrelation (board-p3 row 6).
+ * Pure over its inputs so the estimator is unit-testable without a program:
+ * the lag with peak energy-normalized correlation, parabolically refined,
+ * converted to Hz. 0 when the window holds no energy. Harmonic complexes
+ * peak at the fundamental period (all partials agree there); octave errors
+ * are the documented mistuning mode, graded by the acceptance, not defined
+ * away here.
+ */
+export declare function trackPitchFundamental(window: Float64Array, sampleRate: number): number;
+/**
+ * How long a nonlinear block's Newton loop may keep trying before the iterate it has is the
+ * answer it returns.
+ *
+ * **A correctness bound, and nothing else.** It stopped being the admission gate's cost input
+ * on 2026-09-09 (`RealtimeBudget.budgetedIterationsPerSample`); while it was both, no value
+ * could satisfy both, which is why it sat at 64 below the requirement of several legitimate
+ * circuits.
+ *
+ * **64 was too low, and truncating does not merely return a worse answer.** It leaves a
+ * residual that re-seeds the next sample, so the packet never recovers:
+ * `moogerfooger-mf-102` needs **183** iterations once and then 2.1 per sample forever after,
+ * but capped at 64 it burned all 64 on every sample of a ten-second render — and
+ * `boss-tw-1` shipped audio **11,900x too loud** for the same reason.
+ *
+ * **The bound is 801** — `fender-twin-reverb`'s one-off transient, with `mxr-blue-box` at 356
+ * — so this sits above the observed maximum with headroom, because a bound equal to the
+ * population maximum is a coincidence rather than a bound.
+ */
+export declare const DEFAULT_NEWTON_MAX_ITERATIONS = 1024;
+/**
+ * A delay-tap read length, pure over its inputs (board-p3 row 4). Factored
+ * out of the interpreter so every mode is unit-testable without a program:
+ * the smoothing arithmetic, the modulation estimator, the parameter scale,
+ * and the capacity default mirror the delay kernels branch for branch, in
+ * the same priority. `min`/`headroom`/`round` carry the kernels' shaping --
+ * DDL rounds to whole samples above 1, BBD reads fractionally above 0 with
+ * two slots of headroom -- so one function serves both without blurring them.
+ */
+export declare function composedDelayLength(input: {
+    readonly mode: DelayLengthSpec["mode"];
+    readonly capacity: number;
+    readonly current: number;
+    readonly target: number;
+    readonly sampleRate: number;
+    readonly paramScale: number | null;
+    /**
+     * A tapped length in samples (a `tapped` line's interval times its ratio), or null. In
+     * `parameter` mode it wins over `paramScale` and is clamped to `floor..capacity`.
+     */
+    readonly tapped: number | null;
+    readonly modVolts: number | null;
+    readonly modEstimate: number;
+    readonly modSeeded: boolean;
+    /**
+     * The open-OX2 law constants plus stage count, or null. Read only by the
+     * `clock-law` branch; every other mode ignores it, exactly as they ignore
+     * `modVolts` outside `modulation`. Optional so existing callers keep
+     * compiling; absent reads as no law, and the branch falls to capacity.
+     */
+    readonly clockLaw?: (ClockLawParams & {
+        readonly stages: number;
+    }) | null;
+    readonly min: number;
+    /**
+     * The shortest length, in samples, a `parameter` read may produce: the source's cited
+     * floor. The control sweeps `floor..capacity` rather than `0..capacity`. 0 reproduces the
+     * old `capacity x scale` reading exactly, and is what every registry decomposition passes.
+     */
+    readonly floor: number;
+    readonly headroom: number;
+    readonly round: boolean;
+}): {
+    length: number;
+    current: number;
+    modEstimate: number;
+    modSeeded: boolean;
+};
+export declare class ReferenceRuntime {
+    private readonly program;
+    private sampleRate;
+    /**
+     * Solver sub-samples per host sample; 1 is the plain path and costs nothing.
+     *
+     * `sampleRate` above is the **solver's** rate, already multiplied by this, because every
+     * `dt`, delay length and pole coefficient in this file is derived from it and each is
+     * correct at the sub-sample rate. `hostSampleRate()` is the rate a caller passed in.
+     */
+    private oversample;
+    private readonly positions;
+    private readonly lastShiftedSample;
+    /**
+     * Build-order step 6: bumped by every `setControl` call. `eliminationScratch`'s cached
+     * factorisation, `Z` and `K_reduced` are valid only while this has not moved since they
+     * were built (see `setControl`'s own comment) -- starts at 0 and the cache's own
+     * `cachedGeneration` starts at -1, so the first sample always builds fresh regardless of
+     * whether a control was ever explicitly set.
+     */
+    private controlGeneration;
+    /**
+     * Block base-matrix rebuilds performed by `setSupply`, one per affected block
+     * per call. A call whose values already match, an empty address list, or a call
+     * before `prepare()` rebuilds nothing and leaves this unchanged.
+     */
+    private supplyRebuildCount;
+    private readonly capacitorState;
+    private readonly nodeVoltages;
+    /**
+     * Previous-iterate junction voltages, which junction limiting needs.
+     *
+     * Keyed by a packed integer (`packHistoryKey2`/`3`) rather than a `${block.id}:${node}...`
+     * string built fresh on every lookup -- same intent as the id-lookup maps built in the
+     * constructor, applied to the per-iteration, per-stamp case. **Keying by the stamp object
+     * itself was tried first and reverted**: it changes behaviour, not just performance.
+     * `boss-hm-2` has two distinct `diode` stamps sharing one node pair (anode 0, cathode 19)
+     * -- a real, if unusual, circuit shape -- and the string key's collision on them is not a
+     * latent bug to fix here, it is part of the exact trajectory this runtime is the reference
+     * for: the two diodes sharing one limiter history slot changes which of them a later
+     * iteration damps against, and that changed `boss-hm-2`'s digest. A packed integer of
+     * (block index, node indices) reproduces that exact collision -- two same-kind stamps at
+     * the same nodes still hash identically -- while costing an arithmetic combine instead of a
+     * string allocation. See `applyStamp`'s `bjt` case and `packHistoryKey2`/`3`'s own comment.
+     */
+    private readonly bjtHistory;
+    /**
+     * Previous-iterate grid and plate voltages, for the triode's step limiter.
+     *
+     * Shared with the `pentode` case below, and keyed the same way as `bjtHistory` -- which
+     * also means a triode and a pentode sharing grid/cathode/plate node numbers in the same
+     * block still collide, exactly as the old string key made them (see `bjtHistory`'s comment
+     * for why that is the correct thing to reproduce here, not a bug to fix).
+     */
+    private readonly triodeHistory;
+    /**
+     * Previous-iterate op-amp differentials, which the gain step needs damping against,
+     * plus the step that produced each -- a step's *sign* is what tells a march toward
+     * the solution apart from an oscillation straddling it. See the `ideal-opamp` case.
+     * Keyed the same way as `bjtHistory`.
+     */
+    private readonly opampHistory;
+    /**
+     * The op-amp dominant pole's raw open-loop state, in volts -- the backward-Euler memory the
+     * `ideal-opamp` case steps against, seeded from the operating point in `solveOperatingPoint`
+     * and advanced once per sample in `processBlock` rather than per Newton iterate, because it
+     * is a property of the circuit's clock, not of the iteration. Keyed like `opampHistory`.
+     */
+    private readonly opampRawState;
+    /**
+     * Previous-iterate diode junction voltages, which `limitJunction` damps against.
+     * Keyed the same way as `bjtHistory`.
+     */
+    private readonly diodeHistory;
+    /**
+     * Previous-iterate FET channel voltages, which both FET limiters need.
+     * Keyed the same way as `bjtHistory`.
+     */
+    private readonly fetHistory;
+    /**
+     * One composed block's delay lines, by line id (board-p3 row 4). Same ring
+     * discipline the retired macro state kept, but allocated from the composition's
+     * own `lines` table rather than a model's parameters, and with the
+     * clock-smoothing pair every delay line carries whether a macro or a
+     * composition owns it.
+     */
+    /**
+     * Per-block, per-position state keys, built once at prepare.
+     *
+     * `composedStateKey` concatenates, and `processComposedBlock` runs once per sample, so
+     * calling it there allocated a string 48,000 times a second per composed block. Measured
+     * as test timeouts on the brigade and reverb decks before this table existed.
+     */
+    private readonly composedStateKeys;
+    /**
+     * Per momentary control: the sample of its last press, and the interval between its last two.
+     * A press is a rising edge through `setControl`; the time is the sample clock at that call,
+     * which is a host block boundary, so a tap is timed to within one block (2.7 ms at 128 / 48k).
+     */
+    private readonly tapState;
+    /** The position each composed block ran last sample, to know when a mode was just selected. */
+    private readonly lastComposedPosition;
+    private readonly composedLineState;
+    /**
+     * Per-composed-block DC seed, carrying the `dcEstimate` /
+     * `dcOperatingPoint` pair (board-p3 row 4). The `macro-audio-source`
+     * stamp adds the operating point back to a block's published AC, so a
+     * composition must carry the same seed seeded from the same tap, or the
+     * shell solves a different source -- measured as a ULP divergence at the
+     * first echo on `ibanez-dl5`, whose shell carries real DC bias.
+     */
+    private readonly composedDcState;
+    /**
+     * One composed block's Schroeder sections, allocated at prepare from the
+     * composition's own comb/allpass ops (board-p3 row 4). Same buffers,
+     * indices, and gains the reverb kernel owns -- the interpreter factors
+     * the kernel's state per op rather than re-deriving it.
+     */
+    private readonly composedFilterState;
+    /**
+     * One pitch-shift op's resampling state, keyed by block then op position
+     * (board-p3 row 5). Absolute positions, never wrapped counters: the read
+     * pointer advances `ratio` per sample through a fixed history window and
+     * wraps by whole windows when it outruns or falls behind, which is the
+     * documented discontinuity -- no crossfade, fundamental preserved.
+     */
+    private readonly composedPitchState;
+    /**
+     * One pitch-tracker op's estimator state, keyed by block then op
+     * position (board-p3 row 6): the ring the autocorrelation window is
+     * copied from, samples since the last estimate, and the held output.
+     */
+    private readonly composedTrackerState;
+    /**
+     * Each macro's current write-back value, read by a `macro-audio-source` stamp in whatever
+     * block shares its audio-out node. Updated once per sample, when the macro block's own turn
+     * in `program.order` comes up -- and `couple.ts`'s corrected schedule (spec clause 3) places
+     * that turn strictly before the block reading this map, so the value read is this sample's,
+     * not last sample's. Written by whichever composition publishes into it -- today
+     * only the delay-line compositions.
+     */
+    private readonly macroOutputVolts;
+    /**
+     * Each spring reverb tank's mechanical state, keyed by {@link springKey}.
+     *
+     * A tank is not a macro block: it stays inside the MNA block its terminals belong to,
+     * because unlike a BBD it has no audio-in/audio-out *port* to couple -- it has two ordinary
+     * terminal pairs the surrounding driver and recovery stages are wired to. So its state
+     * lives here and advances with the block's other memory, once per solved sample.
+     */
+    private readonly springState;
+    /** Each tank's current pickup voltage, read by its own `spring-reverb` stamp. */
+    private readonly springOutputVolts;
+    private lastFailure;
+    /**
+     * Whether a limiter damped a step during the current Newton iteration.
+     *
+     * An iterate the limiter moved is a step towards the solution, not the solution, so
+     * it cannot be allowed to satisfy the convergence test. See `limitedIterate`.
+     */
+    private limitedIterate;
+    /**
+     * Which element limited, as kind plus its nodes.
+     *
+     * `lastFailure` said *that* a limiter was active and never *which*, and on `boss-ge-7`
+     * that was the whole distance between "the convergence test refused" and a fix: 7
+     * op-amps, 2 FETs and a BJT share one boolean, and a stationary iterate barred by any
+     * one of them looks identical. Nodes rather than a device id because a stamp does not
+     * carry one.
+     */
+    private limitedBy;
+    /**
+     * The op-amp whose limiter fired on the current iteration, with what a fold reseed needs.
+     * `folded` means its cap sat within an eighth of a linear width. See `OPAMP_FOLD_STREAK`.
+     */
+    private limitedOpamp;
+    private maxNewtonIterations;
+    /**
+     * Cap-hit diagnostics, **off unless `VESSEL_LIMITER_TRACE=1`**. Both are written once
+     * per Newton iteration, so leaving the per-iteration array on costs ~1.7M pushes on a
+     * 3 s 48 kHz render of a stiff amp -- it grows without bound and it inflates the cost
+     * of the very solver anyone is benchmarking. Nothing in the repository reads them; they
+     * exist for an external probe reaching in past `private`, which is why the gate is an
+     * env var rather than a `prepare()` option.
+     */
+    private readonly limiterTrace;
+    private limitedIterationCount;
+    private limitedIterationPerSample;
+    /** Series ohms of whatever drives the input jack -- see `prepare()`'s option. */
+    private inputSourceOhms;
+    /**
+     * Seconds since `prepare`, for the sample being processed. The program's only clock.
+     *
+     * A sine EMF needs absolute time, and nothing else in a program does: every other stamp is a
+     * function of node voltages and reactive state. It is advanced **once per sample** inside the
+     * sample loop rather than per buffer, so a callback boundary cannot shift the waveform --
+     * the invariance the power-domain rectifier experiment measures as `rmsDelta = 0` across
+     * callback sizes. It is not a program field: `t = n / sampleRate` is computed from the rate
+     * `prepare` was given, so one program still runs at any rate.
+     */
+    private timeSeconds;
+    private elapsedSamples;
+    private samples;
+    private nonConvergedSamples;
+    /**
+     * Newton iterations that stopped moving while the equations stayed **unsatisfied** — stuck
+     * against a non-smooth boundary rather than converged. `nonConvergedSamples` counts these
+     * together with iterations still moving when the budget ran out, and the two need opposite
+     * fixes: a stall wants damping or a formulation change, a still-moving one wants a larger
+     * budget. Diagnostic only — nothing branches on it.
+     */
+    private stalledSamples;
+    /**
+     * Newton iterations that stopped moving with the equations **satisfied**, which the current
+     * test rejects because a limiter fired. Diagnostic only, and deliberately so: see the
+     * comment at the convergence test for the 37-packet gate failure that keeps it that way.
+     */
+    private solvedButFlaggedSamples;
+    /**
+     * Per-block Newton census: how many samples each block solved, how many **exhausted its
+     * iteration budget**, and the most iterations it ever used.
+     *
+     * **Per block, because the level a counter aggregates at is part of its meaning.**
+     * `nonConvergedSamples` sums at the host and `peakIterations` at the host, so a *secondary*
+     * block running out of budget is invisible in both — which is how a cap raise moved ten
+     * packets that those two counters said it could not touch, `electro-harmonix-q-tron` among
+     * them at +0.9 dB with a clean bill of health from every failure counter.
+     *
+     * **And the identity is load-bearing, not decoration.** "Some block here exhausted" detects
+     * the affected class but cannot predict a packet's delta, and predicting each affected
+     * packet's delta in advance is the whole point of the two-sided gate. Which block, how many
+     * of its samples, and how badly is what supports a prediction.
+     */
+    /**
+     * Blocks on probation, and the sample index each one's probation ends at.
+     *
+     * A block lands here when one of its samples stalled, or was already solved, at the moment
+     * the budget ran out. Both verdicts say more iterations cannot help *that sample*, so the
+     * ones after it are bought at `NEWTON_UNPRODUCTIVE_ITERATIONS` instead of the full budget.
+     *
+     * **It is a probation and not a sentence, and the difference is a packet that plays.** This
+     * was a `Set` with no expiry until 2026-09-19: one qualifying sample revoked a block's budget
+     * for the rest of the render, so a block that needs a one-off large budget never got one
+     * again. `moogerfooger-mf-102` is the case -- it needs 183 iterations once and 2.1 per sample
+     * after that (see `DEFAULT_NEWTON_MAX_ITERATIONS`), and under the permanent form it was
+     * capped at 64 from its first flagged sample onward and rendered **digital silence** for the
+     * whole render, while the C++ console, which has no revocation at all, played it. Measured
+     * 2026-09-19 at 1 kHz/0.1 V over 4800 samples: RMS `0.00e+0` -> `3.10e-2`, non-converged
+     * samples 4800 of 4800 -> 22.
+     */
+    private readonly unproductiveUntilSample;
+    private readonly blockNewtonCensus;
+    private totalIterations;
+    private nonFiniteSamples;
+    private peakIterations;
+    /** Whether any block failed on the sample being processed, counted once per sample. */
+    private sampleNonConverged;
+    private sampleNonFinite;
+    /**
+     * Blocks whose operating point did not solve. Those keep zero state -- the old
+     * behaviour -- and this counts them so a silent fallback cannot look like a settled
+     * circuit.
+     */
+    private operatingPointFailures;
+    private operatingPointSupplyAmps;
+    private renderedSupplyPeakAmps;
+    /**
+     * Where each supply branch's current sits in each block's solution, resolved once.
+     *
+     * The per-sample cost of the rendered peak has to be a handful of array reads, not a walk of
+     * every stamp in the program: `branchCurrentSnapshot` does that walk and is a diagnostic
+     * called once, while this runs inside the sample loop.
+     */
+    private supplyBranchSlots;
+    /**
+     * The operating point is solved once, on the first `process` after `prepare`, and
+     * deliberately not on `setControl`.
+     *
+     * Deferring it that far is what lets a caller set its knobs first, so the circuit
+     * settles at the positions it will be played at. Not re-solving afterwards is the
+     * physical answer: powering on establishes an operating point, and turning a knob
+     * after that is a transient the solver follows. Re-solving would discard the reactive
+     * memory mid-stream, which is both a click and a circuit that does not exist.
+     */
+    private operatingPointPending;
+    /**
+     * Block lookup by id, built once here rather than searched per use.
+     *
+     * `process`'s sample loop walks `program.order` and previously resolved each id with
+     * `program.blocks.find(...)` -- a linear scan repeated for every scheduled block on every
+     * sample. `program.blocks` does not change after construction, so the scan's answer
+     * cannot change either; this trades an O(blocks) search, paid every sample, for one map
+     * build paid once.
+     */
+    private readonly blocksById;
+    /**
+     * Control lookup by id, built once for the same reason as `blocksById`.
+     *
+     * `applyStamp`'s `controlled-conductance`/`controlled-resistance` cases resolved the
+     * owning control with `program.controls.find(...)` to read its taper -- a scan repeated
+     * for every such stamp, every Newton iteration, every sample. Hotter than the block scan
+     * by a wide margin (stamps x iterations x samples versus blocks x samples), and the same
+     * fix applies: `program.controls` is fixed after construction.
+     */
+    private readonly controlsById;
+    /**
+     * A small integer per block, in place of `block.id` (a string), for the packed history
+     * keys `packHistoryKey2`/`3` build. Built once here from `program.blocks`'s fixed order,
+     * same as `blocksById`. See `bjtHistory`'s comment for why the key needs a block
+     * component at all: two blocks (a real shape -- `boss-hm-2` has two) can each stamp a
+     * device at the same local node numbers, and those must not collide with each other the
+     * way two co-located devices *within* one block are meant to.
+     */
+    private readonly blockIndexById;
+    /**
+     * Reusable Newton-iteration scratch, one entry per MNA block, sized once in `prepare`.
+     *
+     * Every Newton iteration used to allocate a fresh N x N matrix and an N-vector rhs
+     * (`zeros(size)`, `new Array(size).fill(0)`), and `solve` then made its own defensive
+     * copies of both before eliminating -- four allocations, up to N^2 numbers each, for
+     * every iteration of every block of every sample. Reused here: the same arrays are
+     * zeroed in place at the top of each iteration instead of replaced, and `solve` now
+     * eliminates directly on the caller's buffers (see its own comment for why that is safe).
+     *
+     * `solutionA`/`solutionB` close the gap that reuse left open: `solve` used to return a
+     * fresh N-length array every iteration (`iterate`'s closing comment used to say this was
+     * deliberate, because the alternative -- writing into one of two buffers `iterate` keeps
+     * across iterations -- hadn't been done yet). Measured on `pro-co-rat`, whose 33x33 block
+     * needs ~3.2 Newton iterations a sample on average: that line alone was 5.5% of total
+     * runtime self-time under `--cpu-prof-md`, on top of `solve`'s own 56%. `iterate` now pings
+     * between these two instead, so `solve` writes into whichever one is not currently `current`
+     * -- see `iterate`'s and `solve`'s own comments for why swapping is safe.
+     */
+    private readonly iterationScratch;
+    /**
+     * Per-block static elimination schedules, built once in `prepare()` and replayed by
+     * `iterate` in place of the dense `solve` -- see `buildSparseSchedule`.
+     *
+     * A block appears here only when the schedule is worth replaying (`solverPlan()` reports
+     * the split and its reason). Absent means the dense path, which is also where a block
+     * lands mid-solve if its pivot guard trips.
+     */
+    private readonly sparseSchedules;
+    /**
+     * Precomputed base matrices from constant stamps for each MNA block.
+     *
+     * Fold constant, control-free, dynamic-free stamp values into a precomputed base
+     * matrix and RHS vector per block, initialized with standard GMIN and ground row.
+     * During audio processing, iterate only copies the base matrix and applies the
+     * non-constant stamps.
+     */
+    private readonly baseMatrices;
+    /** Blocks that gave up their schedule at runtime, for `solverPlan()` to report. */
+    private readonly abandonedSchedules;
+    /**
+     * Blocks whose shipped elimination order divides by a pivot the assembled
+     * operating-point matrix cannot support, dropped to the dense solve at the
+     * first `process()` call. See `settlePivotOrders`.
+     */
+    private readonly droppedSchedules;
+    /**
+     * Blocks whose shipped order failed numeric validation and whose replacement
+     * order (threshold Markowitz on the assembled operating-point matrix) was
+     * adopted instead of dropping to dense. See `computeNumericRepivot`.
+     */
+    private readonly repivotedSchedules;
+    /** Set once the shipped orders have been validated against the real matrix. */
+    private pivotOrdersSettled;
+    /** Why each block took the path it did, for `solverPlan()`. */
+    private readonly solverPlanRows;
+    /**
+     * How many solves hit a pivot below `SCHEDULE_PIVOT_FLOOR` and ran again densely, against
+     * how many the schedule ran at all. A fallback is correct but not free: it pays for the
+     * schedule and then the dense solve. A rate that is not small means that block is not
+     * suited to a static order, not that the net is doing its job.
+     */
+    private scheduleFallbacks;
+    private scheduleSolves;
+    /**
+     * Build-order step 6, vertical slice: which blocks run through symbolic elimination
+     * instead of `iterate`'s full-system Newton solve.
+     *
+     * **Deliberately opt-in, per block id, and empty by default.** Every packet other than
+     * one named for this experiment takes the untouched `iterate` path; nothing here changes
+     * unless a caller explicitly asks for it. The plan's own rule ("the stamp interpreter is
+     * never deleted out from under that role until behavioural parity replaces it by
+     * decision") is honoured by construction: `iterate` is not touched, is still what
+     * `solveOperatingPoint`'s continuation methods use unconditionally, and is exactly what
+     * this path is diffed against -- see `scripts/report-elimination-parity.ts`.
+     */
+    private readonly eliminateBlocks;
+    /**
+     * Per-block port analysis, computed once in `prepare()` from the block's own stamps
+     * (`computeNewtonPortRows`) -- never re-derived per sample, since the set of rows a
+     * stamp's law can write to is a static fact about the program, not the operating point.
+     */
+    private readonly eliminationPorts;
+    /**
+     * Reused per-sample/per-iteration scratch for the eliminated path, sized once per block
+     * in `prepare()` -- the same discipline `iterationScratch` already follows, for the same
+     * reason: an allocation inside the hot loop is exactly the cost this path exists to
+     * remove.
+     *
+     * **`ll`/`permutation`/`z`/`kReduced` are control-generation-cached, not per-sample.**
+     * `M_lin[L][L]`'s factorisation, the port-response matrix `Z`, and `K_reduced` all depend
+     * only on control positions -- never on the time-varying input or on capacitor history --
+     * exactly the `linear && controlFree` distinction build-order step 3/4 already established
+     * for baking a whole block's realisation. `iterateEliminated` rebuilds these three only
+     * when `cachedGeneration` disagrees with `this.controlGeneration`; every sample still
+     * rebuilds `linear`/`linearRhs` (cheap, and needed for the RHS regardless) and always
+     * recomputes `z0`/`uReduced` fresh, since those depend on capacitor state and the sample's
+     * own input.
+     */
+    private readonly eliminationScratch;
+    constructor(program: Program, options?: {
+        readonly eliminateBlocks?: ReadonlySet<string>;
+    });
+    /**
+     * The only entry point that accepts a sample rate. No default exists.
+     *
+     * The Newton iteration cap is a real CPU-versus-accuracy knob, the same role
+     * SPICE's ITL settings play, so a host may lower it. Lowering it does not make
+     * the runtime lie: samples that then fail to converge are held and counted.
+     *
+     * `realtimeBudget` is the real-time admission gate (see `./admission.ts`): supplying
+     * one asks "can this program be shown to fit", refusing by name and by number when it
+     * cannot. Omitting it opts out of the gate entirely -- this runtime has no honest
+     * per-machine default to fall back on.
+     */
+    prepare(sampleRate: number, options?: {
+        readonly maxNewtonIterations?: number;
+        readonly realtimeBudget?: RealtimeBudget;
+        /**
+         * Series impedance of whatever drives the input jack, in ohms. **A console
+         * setting, not a program one** -- the same compiled pedal is driven by a guitar
+         * (~5-15 kOhm plus pickup inductance), a buffered board (~100 Ohm), or a stiff
+         * test source (0), and none of that belongs in the ROM.
+         *
+         * Defaults to 0, the historical stiff-drive behavior. It exists because a fuzz
+         * face's defining dynamics ARE the loading interaction between its low, nonlinear
+         * input impedance and the pickup's source impedance; driven from an ideal source
+         * it renders at constant maximum harshness -- found by ear on the 2026-08-18
+         * listening pass, twice, either side of the cabinet IR landing.
+         */
+        readonly inputSourceOhms?: number;
+        /**
+         * Solver sub-samples per host sample. **A console setting, not a program one**, for
+         * the same reason `inputSourceOhms` is: the rate a host runs at is not a property of
+         * the circuit, and decision 3 already puts sample rate on this side of the
+         * boundary.
+         *
+         * **Why it earns its place, measured 2026-09-07.** At 4x,
+         * `report:compiler-spice-parity` goes from 47 to 50 `agrees` over 118 packets, five
+         * packets move and every one improves, and none loses agreement. It also removes
+         * `boss-ce-5`'s full-scale limit cycle -- 4.000 V of AC from silence at 48 kHz,
+         * 1.01e-3 at 96 kHz -- and that cycle is *gone* rather than folded down, so raw,
+         * zero-order- and boxcar-decimated output are identical at every rate.
+         *
+         * **Why it is not on by default.** Cost is about 3.2x the solver work at the corpus
+         * median (2.6 iterations per output sample against 8.3), because everything floors
+         * at 2.0-2.4 iterations per sub-sample whatever the rate and only packets above that
+         * floor save anything. Those are the stiff ones: `boss-ce-5` costs 1.23x and has the
+         * limit cycle, `mxr-phase-45` costs 3.84x and already agrees at 0.9710. A global
+         * multiplier spends the most where it buys least, so the factor belongs with whoever
+         * knows the packet -- `report-newton-deadline` computes the stiffness signal.
+         *
+         * **What it does not do.** Decimation here is zero-order: the last sub-sample of each
+         * host sample is the output. That is what the 47-to-50 measurement was taken with. A
+         * band-limiting decimator is a real improvement for broadband content and is *not*
+         * implemented, because a single 1 kHz tone cannot justify a filter choice.
+         */
+        readonly oversample?: number;
+    }): void;
+    /** Read after processing. Non-zero failure counts mean the audio is not trustworthy. */
+    telemetry(): RuntimeTelemetry;
+    /** Read-only solved MNA node voltages for diagnostics after prepare/process. */
+    nodeVoltageSnapshot(): readonly RuntimeNodeVoltageSnapshot[];
+    /**
+     * Read-only solved branch currents after prepare/process. See `RuntimeBranchCurrent` for
+     * the sign convention.
+     *
+     * Ordered by block, then by the stamp order within it, so a caller pairing these against
+     * `program.blocks[].stamps` sees the same sequence.
+     */
+    branchCurrentSnapshot(): readonly RuntimeBranchCurrent[];
+    /**
+     * Get the physical, causal brightness of any LED or indicator in the circuit.
+     *
+     * Brightness is a normalized value between 0.0 (completely dark) and 1.0 (fully glowing),
+     * calculated in real-time from the physical forward current flowing through the LED diode junction.
+     */
+    getLedBrightness(deviceId: string): number;
+    setControl(id: ControlId, position: number): void;
+    /**
+     * Block base-matrix rebuilds performed by `setSupply` so far. Read-only:
+     * re-applying the values a stamp already has rebuilds nothing and leaves this
+     * unchanged.
+     */
+    get supplyRebuilds(): number;
+    /**
+     * Every addressable `dc-source` stamp in `program.blocks` order, then stamp
+     * order within each block. `blockIndex` is the index into `program.blocks`;
+     * pass `infos.map((info) => info.address)` straight to `setSupply`.
+     */
+    getSupplies(): readonly SupplyInfo[];
+    /**
+     * Retarget one or more supply stamps between `process()` calls: every named
+     * `dc-source` stamp solves `V(positive) - V(negative) - sourceOhms * i =
+     * volts` with the new values from the next sample on.
+     *
+     * Call between `process()` calls, never concurrently with one -- the same
+     * contract as `setControl`. Effect starts at the next sample: the affected
+     * blocks' cached base matrices are rebuilt exactly the way `prepare()`
+     * builds them, and `controlGeneration` is bumped so the eliminated-path
+     * factorisation, Z, and K_reduced rebuild on next use. The sparse schedule is
+     * untouched: its pattern is value-independent.
+     *
+     * Reactive state (capacitor and op-amp pole memory) carries over, which is
+     * the physically honest response to hot-swapping a battery, and the DC
+     * operating point is deliberately NOT re-solved -- same transient-following
+     * rule as `setControl`'s `operatingPointPending` comment.
+     *
+     * Validation mirrors `setControl` and is atomic: `volts` must be finite,
+     * `sourceOhms` must be finite and non-negative (a negative resistance is
+     * gain, not sag), and every address must name an existing `dc-source` stamp
+     * (unknown block index, non-MNA block, or a `sourceIndex` with no
+     * `dc-source` all throw `RuntimeError`). All addresses are validated before
+     * any state is touched, so a bad address leaves even the valid ones in the
+     * same call unchanged. An empty address list changes nothing, and a call
+     * whose values already match the stamps rebuilds nothing (`supplyRebuilds`
+     * unchanged).
+     *
+     * Never mutates the caller's `Program`: the touched stamp objects are
+     * replaced on this runtime's own copies (copy on write), so two runtimes
+     * built from one program, or a frozen program, never interact.
+     *
+     * NOTE (cross-repo, gated by the extraction plan): the C++ console needs the
+     * same setter -- update its loaded program's supply fields and re-derive
+     * whatever it caches from them, with parity rows in the workbench harness.
+     * This method changes no `Program` or `Stamp` shape, so it triggers no
+     * format bump.
+     */
+    setSupply(addresses: readonly SupplyAddress[], volts: number, sourceOhms: number): void;
+    /**
+     * Fold one block's constant stamps into its cached base matrix and RHS, with
+     * the standard GMIN and ground-row pinning. This is the `prepare()` build,
+     * factored so `setSupply` rebuilds exactly what `prepare()` built.
+     */
+    private rebuildBaseMatrix;
+    /**
+     * Decide, once per block, whether its static elimination schedule is worth replaying.
+     *
+     * The rule is a **cost ratio computed from the block's own pattern**, not a size cutoff.
+     * Two reasons, both measured. Dense cost is not a function of `size` alone -- `solve`
+     * skips a zero multiplier, so two 28-unknown blocks in this corpus differ by 4x in dense
+     * wall clock -- and node counts are about to shrink when the compiler stops sizing a block
+     * by its largest authored node *label*, which would silently move any absolute threshold.
+     * A ratio re-derives itself correctly on both counts.
+     *
+     * The floor is set where the measured wall-clock win stops being worth the branch: at a
+     * predicted saving of 4x the smallest corpus block that clears it measured 2.9x real, and
+     * the one that does not clear it measured 2.0x on a 4-unknown block that costs nothing
+     * either way.
+     */
+    private planSparseSchedule;
+    /**
+     * Assemble one block's audio-structure Jacobian at the solved operating
+     * point, for validating the shipped elimination order before the first
+     * audio sample replays it.
+     *
+     * This mirrors `iterate`'s standard audio pass exactly -- base-matrix copy,
+     * non-constant stamps at the operating-point voltages with zero input,
+     * ground-row overwrite -- so the matrix is what the first Newton iteration
+     * would stamp. `applyStamp` also advances limiter histories, divider state
+     * and clock/bucket state, which belong to the audio run, not to this probe:
+     * every mutable stamp state it touches is snapshotted and restored, and
+     * the state vector itself is passed as a copy, never live. A unit test
+     * pins that the audio is bit-identical with and without this call.
+     */
+    private assembleAudioMatrix;
+    /**
+     * Validate every admitted block's shipped elimination order against the
+     * assembled operating-point matrix, once, before the first audio sample.
+     *
+     * The order was chosen from the stamp pattern alone, where every node
+     * diagonal reads as a pivot candidate because the runtime adds `gmin` to
+     * it. A pivot of `1e-12` against entries of order `1e2` is a growth factor
+     * of `1e14` that dense partial pivoting would never choose, and replaying
+     * it is what makes the sparse and dense solves disagree on the row-6
+     * packets (`boss-aw-2` never converges sparsely and converges in four
+     * iterations densely).
+     *
+ * The gate is a comparison, not a pivot theory: both solves run on the
+ * same assembled matrix and their answers are compared. Per-pivot ratios
+ * do not separate healthy blocks from broken ones -- healthy `boss-ce-5`
+ * carries 18 pivots below any absolute-scaled threshold and still matches
+ * dense to `1e-10`, because a tiny pivot is harmless late in the order
+ * and fatal early -- so the ratios stay on as diagnostics while the
+ * disagreement drops the block. A dropped block renders exactly what the
+ * forced-dense control renders; correctness first, and the cost of the
+ * dense path belongs to phase 2.
+ *
+ * The tolerance sits in a measured canyon: the largest disagreement among
+ * kept corpus blocks is `boss-tw-1` at `7.1e-5` (whose sparse audio agrees
+ * with dense to `1e-9` and converges 100% -- dropping it would regress its
+ * 0.83x budget fix to ~850x, so the gate must NOT fire there), while the
+ * smallest dropped disagreement is `boss-aw-2` at `9.8e+3`. Dense is not
+ * assumed right -- `tw-1` diverges on 61 samples densely while converging
+ * sparsely -- the gate only fires where the replay demonstrably collapses.
+ */
+    private settlePivotOrders;
+    /**
+     * Which blocks took the static schedule and which kept the dense solve, and how often the
+     * pivot guard sent a solve back to the dense path.
+     *
+     * Exists so "the sparse solver landed" is never read as "every block got faster". Valid
+     * only after `prepare()`.
+     */
+    solverPlan(): {
+        readonly blocks: readonly {
+            readonly blockId: string;
+            readonly size: number;
+            readonly patternEntries: number;
+            readonly sparseOps: number;
+            readonly denseOps: number;
+            readonly unprovenPivots: number;
+            readonly path: "sparse" | "dense";
+            readonly reason: string;
+            readonly pivotViolations: number;
+            readonly worstPivotRatio: number | null;
+            readonly pivotDisagreement: number | null;
+            readonly repivoted: boolean;
+        }[];
+        /** Blocks that gave the schedule up mid-run after a run of pivot-guard trips. */
+        readonly abandoned: readonly string[];
+        /** Blocks whose shipped order failed numeric validation at the operating point. */
+        readonly dropped: readonly string[];
+        /** Blocks running a numeric re-pivot order instead of their shipped order. */
+        readonly repivoted: readonly string[];
+        readonly scheduleSolves: number;
+        readonly scheduleFallbacks: number;
+    };
+    process(input: Float64Array): Float64Array;
+    /**
+     * The rate the caller passed to `prepare`, as opposed to the solver's sub-sample rate.
+     *
+     * `this.sampleRate` is the rate the circuit is actually solved at; a console that needs to
+     * know what it asked for -- to size a buffer, or to report -- wants this one.
+     */
+    hostSampleRate(): number | null;
+    private processBlock;
+    /**
+     * The composition interpreter (board-p3 row 4): a data-driven graph of
+     * closed-vocabulary primitive ops, evaluated top to bottom each sample.
+     * No pedal id, no part number, no registry lookup -- the program the
+     * packet supplies is the whole instruction, which is what makes this a
+     * machine that runs a program rather than a library of classes the
+     * compiler dispatches to.
+     *
+     * Evaluation order is load-bearing for the bit-identical gate: float
+     * addition is not associative, so ops run strictly in listed order and a
+     * source may only name the block input, a constant, or an earlier op's
+     * output. Feedback flows through delay-line state, never through
+     * temporaries.
+     */
+    /**
+     * What a `parameter`-mode tap reads for one line: a 0..1 fraction of its range, or a tapped
+     * length in samples, or neither (the tap then reads capacity, the cited maximum).
+     *
+     * Three sources, never two. A line's own `sweep` wins: `scanned` reads its control by
+     * position through the control's taper, `tapped` reads the interval between the control's
+     * last two presses times `ratio`. With no sweep, the block's solved `parameter` node, which is
+     * a registry model's reading.
+     */
+    private composedLineReading;
+    /**
+     * A delay core's DC transfer, derived from its own ops for the
+     * operating-point solve: at steady state every delay line holds what is
+     * pushed into it, so taps read line values and pushes update them, iterated
+     * to a fixed point. Ops that are DC-blocking by construction
+     * (`filter-dcblock`) push 0, so a core behind a DC block correctly reports
+     * no transfer; `mix` applies its gains, including swept ones. Anything
+     * else (combs, allpasses, pitch, hold, trackers) makes the transfer
+     * ill-defined and returns null -- the macro then reads 0 during the
+     * solve, exactly as before, rather than a guess.
+     *
+     * `null` also for programs owning no delay lines (reverb owns combs, not
+     * lines): those keep their established no-DC behavior, which this
+     * derivation must reproduce rather than revisit. No per-chip flag, no
+     * name reading; the ops are the whole input. The loop is contractive
+     * exactly when the program's own feedback is (gain < 1); capped well
+     * past any such settling, with null on non-convergence.
+     */
+    private composedDcTransfer;
+    private processComposedBlock;
+    /**
+     * One Newton solve of a block, shared by a sample and by the operating point.
+     *
+     * Extracted rather than copied: the operating point differs from a sample only in
+     * which elements conduct, and a second copy of the limiter rule, the gmin row, the
+     * ground pin and the convergence test would drift from this one and then describe a
+     * circuit the sample loop does not solve.
+     */
+    private iterate;
+    /**
+     * Build-order step 6, vertical slice: the part of a block's matrix that is the same for
+     * every Newton iteration of this sample -- every stamp `newtonPortRowsOf` calls linear,
+     * plus `gmin` and the ground pin, in exactly `iterate`'s own order. Rebuilt once per
+     * sample (not once per iteration, and not once per program) because a control-bearing
+     * stamp's conductance can move between samples even though it never moves within one.
+     *
+     * Nonlinear stamps are skipped entirely here -- their current lives only in
+     * `reduceNonlinearContribution`, re-evaluated at the current iterate every time, exactly
+     * as `iterate` re-evaluates them every time. `solution` is passed as an all-zero
+     * placeholder because every linear stamp kind ignores it (verified by inspection of
+     * `applyStamp`'s own linear cases); a nonlinear stamp reaching here would read garbage,
+     * which is exactly why it must never be one of the stamps this loop calls.
+     */
+    private buildLinearBackground;
+    /**
+     * Build-order step 6, vertical slice: `iterate`'s exact per-sample contract, produced by
+     * symbolic elimination around the block's nonlinear devices instead of a full-system
+     * Newton solve every iteration.
+     *
+     * **The method, in one paragraph.** Partition every row into `P` (the union of rows a
+     * nonlinear law writes, `computeNewtonPortRows`) and `L` (everything else). `M_lin[L][L]`
+     * is eliminated once per sample, carrying the `P`-count port-response columns and the
+     * constant column `b_L` together (`solveMulti`) -- this is the factorisation `iterate`
+     * pays for fresh on every Newton iteration, paid here exactly once. `K_reduced` and
+     * `u_reduced` fold `M_lin[P][P]` and `b_lin[P]` against that response, giving the small
+     * `|P| x |P|` system every Newton iteration on the *port* voltages actually solves;
+     * `reduceNonlinearContribution` adds each iteration's own nonlinear current and Jacobian,
+     * chain-ruled through the same response so an L-node a law reads (an op-amp's inputs, a
+     * FET's gate) is exactly as correct as one it does not. `x_L` is reconstructed from the
+     * current port voltages every iteration via one cheap matrix-vector product, never solved
+     * for directly, so every node's value is always available to the laws and to the
+     * convergence test without re-deriving anything.
+     *
+     * **What must stay identical to `iterate` for the exactness gate to mean anything**: the
+     * convergence test (`withinTolerance` plus `!limitedIterate`, same functions), the
+     * limiter/history side effects (the same `applyStamp`, the same history maps, so a
+     * limited iterate here is limited for the identical reason it would be in `iterate`), and
+     * the return contract (`solution` is the latest iterate whether or not it converged,
+     * matching `iterate`'s own "advance the clock even on failure" rule one level up in
+     * `processBlock`).
+     */
+    private iterateEliminated;
+    /**
+     * Solve every block at DC and start the reactive elements from that answer.
+     *
+     * **Why this exists.** A run that starts from zero state starts with every capacitor
+     * at 0 V, which is a *short*, and a short across a bias network accidentally supplies
+     * a bias path the circuit does not have. So a stage that cannot hold an operating
+     * point still has real gain for the first fraction of a second, and then cuts off as
+     * the capacitors charge. Measured on named pedals: `ibanez-ts808` renders a gain of
+     * 0.748 cold, 0.206 after half a second, and 0.004 after two -- three different
+     * answers about one pedal, only the last of which is the pedal.
+     *
+     * At DC a capacitor is an open circuit and an inductor is a short, which is the only
+     * difference between this solve and a sample. The result is written back as the state
+     * a settled circuit would have reached: a capacitor holding its DC voltage and
+     * carrying no current, an inductor with no voltage across it and carrying the DC
+     * current the solve found.
+     *
+     * **What this does not do:** make a badly biased circuit sound right. If a packet has
+     * no DC path to a base, the operating point says so immediately instead of after two
+     * seconds of charging. That is the point -- it turns a wait into an answer -- but a
+     * recovered pedal is not among the things it promises.
+     *
+     * A block that fails to converge here keeps zero state, which is exactly the old
+     * behaviour, and is counted so the failure is never silent.
+     */
+    private solveOperatingPoint;
+    /**
+     * One block's operating point, with **gmin stepping** as a fallback.
+     *
+     * SPICE's first continuation method, and the reason ngspice solves decks this runtime
+     * refuses. A circuit that will not converge at `gmin = 1e-12` is often easy at
+     * `1e-2`, because a hundred-ohm conductance from every node to ground swamps the
+     * nonlinearities and leaves something close to a resistor network. Solve that, use its
+     * answer to seed a solve at a tenth the conductance, and walk down: each problem is a
+     * small deformation of the one already solved, so Newton starts inside the basin.
+     *
+     * `null` when even the final pass at the true `gmin` fails. **A raised gmin is not an
+     * answer** -- it is a different circuit, with leakage the packet does not contain -- so
+     * the walk is only ever a source of initial guesses, and the value returned is always
+     * from a pass at `GMIN_SIEMENS`.
+     *
+     * The direct attempt comes first and short-circuits, so nothing that already converges pays
+     * for either continuation. Before the corpus's declared transistor types were read, all 52
+     * compiled packets solved on that direct pass and neither method was ever reached;
+     * `boss-bd-2-blues-driver` is the first packet measured to need one, and it needs the
+     * *second* -- gmin stepping fails on it and source stepping solves it, which is why both
+     * exist rather than only the first.
+     */
+    private solveOperatingPointForBlock;
+    /**
+     * Continuation on the *devices*: walk down from a conductance that makes the circuit nearly
+     * linear, each step seeding the next.
+     *
+     * That sequencing is the whole mechanism -- the chain of problems is continuous even though
+     * any single jump would not converge on its own.
+     */
+    private solveByGminStepping;
+    /**
+     * Continuation on the *excitation*: power the circuit up from zero in linear steps.
+     *
+     * SPICE's second method, tried when gmin stepping has already failed, because the two fail on
+     * different circuits. Gmin stepping swamps a nonlinearity with leakage, which works when the
+     * difficulty is a device's curvature; it does nothing about a circuit whose difficulty is
+     * *which* of several states the supplies put it in. With every supply at zero every junction
+     * is unambiguously off -- a state Newton reaches trivially -- and each step up is a small
+     * perturbation of an answer already in hand.
+     *
+     * An unconverged intermediate step still seeds the next, as in the gmin walk. The value
+     * returned is always from a final pass at full supply and the true `gmin`, so a partially
+     * powered circuit is only ever a source of initial guesses and never an answer.
+     *
+     * One inconsistency worth naming: an `ideal-opamp` carries its rails on the stamp, resolved
+     * from the supply set at compile time, so its clipping levels do not ramp with the supplies.
+     * That makes the intermediate steps physically incoherent for an op-amp circuit and does not
+     * affect the result, which is taken at full supply.
+     */
+    private solveBySourceStepping;
+    private clearLimiterHistories;
+    private snapshotLimiterHistories;
+    private restoreLimiterHistories;
+    /** Advance reactive memory. Trapezoidal, so it carries both across and through. */
+    /**
+     * Allocate one tank's springs. Called on first use rather than in `prepare()` so the buffer
+     * sizes come from the host's actual rate, which is the same reason the macro ring buffer is
+     * sized there: a delay is a time, and only the host knows how many samples that is.
+     */
+    private springTankState;
+    /**
+     * One sample of tank motion: drive in, springs run, pickup out.
+     *
+     * Each spring is a delay line with its dispersion chain **inside** the feedback loop, which
+     * is what makes successive reflections progressively more smeared instead of identically
+     * filtered echoes. Stability is structural rather than tuned: an allpass has unity magnitude
+     * at every frequency, so the loop gain is exactly `feedback`, which is below 1 for any
+     * positive decay time.
+     */
+    private advanceSpringReverb;
+    private advanceReactiveState;
+    /**
+     * One per-sample step of the op-amp dominant pole's raw state, advanced from the solved
+     * differential exactly as `advanceReactiveState` advances the capacitor state -- once, after
+     * the solve, on every sample whether it converged or not, because the pole's clock runs
+     * either way. Unrailed op-amps are virtual shorts with no pole state, so they are skipped.
+     */
+    private advanceOpAmpRawState;
+    private applyStamp;
+}
+//# sourceMappingURL=reference-runtime.d.ts.map