@vessel-dsp/runtime 0.3.1 → 0.4.1

package/dist/reference-runtime.js

@@ -19,8 +19,9 @@
 // else, and `src/compiler/` never imports this. Either can be deleted without the other
 // noticing. Nothing from the old spine (`src/web`, `src/admission`, `src/container`,
 // `src/dsp`) may be imported here.
+import { computeNumericRepivot } from "@vessel-dsp/compiler";
 import { admissionVerdict } from "./admission.js";
-import { computeNumericRepivot } from "./numeric-pivot.js";
+import { HalfBandStage2x, cascadeLatencyHostSamples, designHalfBand2x, resampleStageSpec, } from "./resample.js";
 import { taperFraction } from "./taper.js";
 export class RuntimeError extends Error {
     constructor(message) {
@@ -1162,6 +1163,20 @@ export class ReferenceRuntime {
      * correct at the sub-sample rate. `hostSampleRate()` is the rate a caller passed in.
      */
     oversample = 1;
+    /**
+     * Band-limited resampling around the solver, one 2x half-band stage per
+     * entry, cascaded for 4x and 8x. Empty unless `oversample` is a power of
+     * two greater than 1; any other factor keeps the legacy hold-and-last
+     * path below. Built fresh (zero state) in `prepare()`, so the filter
+     * state never leaks across renders and block splits stay bit-identical.
+     */
+    resampleUp = [];
+    resampleDown = [];
+    /** Scratch for the sub-sample streams, sized to `oversample` in `prepare()`. */
+    resampleBufA = new Float64Array(0);
+    resampleBufB = new Float64Array(0);
+    /** Total resampler group delay in host samples (0 on the legacy path). */
+    resampleLatencyHost = 0;
     positions = new Map();
     lastShiftedSample = new Map();
     /**
@@ -1402,6 +1417,50 @@ export class ReferenceRuntime {
      * samples 4800 of 4800 -> 22.
      */
     unproductiveUntilSample = new Map();
+    /**
+     * Per block, the last three converged sub-sample solutions and the extrapolation order
+     * that would have predicted the newest of them best, for the Newton start predictor.
+     *
+     * **The start of a Newton solve is a guess, and the previous solution is only the
+     * cheapest guess, not the best one.** At 4x oversampling the circuit moves a quarter as
+     * far per solve, and a quadratic extrapolation of the last three solutions lands inside
+     * the convergence tolerance on most sub-samples, so the first Newton step is already the
+     * answer and the check that follows it is the whole solve: one iteration where the
+     * previous-solution start needs two (one step, one check). Measured 2026-10-09 on the six
+     * profile packets at os4 (`docs/spikes/2026-10-09-newton-iteration-budget.md`): iterations
+     * per host sample fall 38-47 % on the pedals with every converged solution within 0.02
+     * tolerance units of the full-Newton solution from the same state.
+     *
+     * **The order is chosen by the block's own history, not by a constant.** After every
+     * converged solve the three candidate starts the history could have produced (order 0 =
+     * the previous solution, 1 = linear, 2 = quadratic) are scored against the solution just
+     * reached, in tolerance units, and the best one is used for the next solve -- but only
+     * when that solve took at most two iterations (the floor: one step and one check). A
+     * solve that needed more was hunting across a knee, and there a closer start is not a
+     * cheaper one (`recordNewtonSolution` has the measurement). On a hard edge the
+     * extrapolations overshoot the clipping knee and score worse than the previous solution,
+     * so the next solve starts exactly where it always did; on a signal it cannot predict it
+     * costs nothing. A non-converged solve breaks the chain (no history to extrapolate from).
+     *
+     * Only the start moves. The convergence test, the limiter histories, the relaxation rule
+     * and the fold reseed (which reads the caller's `start`, the previous solution) are
+     * untouched, so what converges is still the circuit's equations at the shipped
+     * tolerances -- a different first iterate, the same fixed point.
+     *
+     * **It runs only when `prepare()` was given `oversample > 1`; at factor 1 (the default)
+     * it neither seeds nor records, so the ring stays empty and the solve is the one runtime
+     * 0.3.1 ran.** It shipped in 0.4.0 at every factor and was gated here in 0.4.1 because at
+     * factor 1 it buys little and moves the output more than that saving is worth: iterations
+     * fall 2.9 % across the pedal corpus and 10.1 % across the amps (1 kHz 0.1 V, cap 64),
+     * against `boss-dm-2` moving 6.2 % of its cold-start peak (0.5-0.8 % of the settled peak)
+     * and `boss-mt-2` stalling the WASM console permanently from 2.752 s of two-tone drive
+     * (it does not stall with the predictor off). Above 1 it stays on for every factor, the
+     * held path included (iterations on the profile packets: 2x -6..-15 %, 3x 0..-1 %, 4x
+     * -39..-47 %, 5x/6x -8..-24 %, 8x -44..-50 %; output movement at most 6e-6 relative RMS).
+     * The factor is fixed by `prepare()` (which also clears the ring), so there is no mid-run
+     * switch to reason about.
+     */
+    newtonStartHistory = new Map();
     blockNewtonCensus = new Map();
     totalIterations = 0;
     nonFiniteSamples = 0;
@@ -1682,6 +1741,30 @@ export class ReferenceRuntime {
         // The solver runs at the sub-sample rate. Delay lines and pole coefficients are held in
         // *seconds* and converted here, so they stay correct without knowing about oversampling.
         this.sampleRate = sampleRate * oversample;
+        // The band-limited resampler is designed here, from the stage alone: one
+        // windowed-sinc half-band prototype per 2x stage (`RESAMPLE_STAGE_SPECS`),
+        // fresh zero-state instances per direction, so `prepare()` clears the
+        // filter state and a re-prepared run starts clean. Powers of two only;
+        // any other factor keeps the legacy hold-and-last path in `process()`.
+        const resampleStages = Math.log2(oversample);
+        if (Number.isInteger(resampleStages) && resampleStages >= 1) {
+            const prototypes = Array.from({ length: resampleStages }, (_, stage) => {
+                const [taps, beta] = resampleStageSpec(stage);
+                return designHalfBand2x(taps, beta);
+            });
+            this.resampleUp = prototypes.map((prototype) => new HalfBandStage2x(prototype));
+            this.resampleDown = prototypes.map((prototype) => new HalfBandStage2x(prototype));
+            this.resampleBufA = new Float64Array(oversample);
+            this.resampleBufB = new Float64Array(oversample);
+            this.resampleLatencyHost = cascadeLatencyHostSamples(resampleStages);
+        }
+        else {
+            this.resampleUp = [];
+            this.resampleDown = [];
+            this.resampleBufA = new Float64Array(0);
+            this.resampleBufB = new Float64Array(0);
+            this.resampleLatencyHost = 0;
+        }
         this.maxNewtonIterations = maxNewtonIterations;
         // Negative would be a source that supplies energy under load; refuse the nonsense
         // rather than solve it.
@@ -1703,6 +1786,7 @@ export class ReferenceRuntime {
         this.solvedButFlaggedSamples = 0;
         this.blockNewtonCensus.clear();
         this.unproductiveUntilSample.clear();
+        this.newtonStartHistory.clear();
         this.totalIterations = 0;
         this.nonFiniteSamples = 0;
         this.peakIterations = 0;
@@ -2478,6 +2562,7 @@ export class ReferenceRuntime {
             rhs: new Float64Array(size),
             factors: new Float64Array(schedule.factorCount),
             consecutiveFallbacks: 0,
+            repivotAttempted: false,
         });
     }
     /**
@@ -2581,6 +2666,16 @@ export class ReferenceRuntime {
  * 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.
+ *
+ * A validating shipped order is still replaced when the value-aware candidate
+ * reaches the audio-agreement bar (1e-9) an order of magnitude more cleanly
+ * without meaningful fill cost -- the refinement in `SCHEDULE_REFINEMENT_BAR`.
+ * Bar-clean ties keep shipped even when the audios differ: the
+ * operating-point replay cannot adjudicate audio-time divergence (`boss-os-2`
+ * replays 3.4e-10 shipped vs 2.5e-13 candidate while the audios differ 1000x),
+ * so the rule only moves past the bar it can measure, never on a tie.
+ * Measured adopters: `boss-sd-1` (1.8e-9 to 4.2e-13, audio 6.9e-8 to
+ * 6.5e-12).
  */
     settlePivotOrders() {
         if (this.pivotOrdersSettled) {
@@ -2682,15 +2777,13 @@ export class ReferenceRuntime {
                     ? disagreement
                     : null;
             }
-            if (disagreement <= SCHEDULE_VALIDATION_TOL) {
-                continue;
-            }
-            // The shipped order failed on the real matrix. Before giving the
-            // schedule up, try a value-aware order: threshold Markowitz over the
-            // schedule's own filled pattern, replayed and compared to the same
-            // dense solve. Adoption needs the same tolerance the shipped order
-            // failed; a refused or still-disagreeing candidate drops as before.
+            // The value-aware order, computed always now rather than only when
+            // the shipped order fails: threshold Markowitz over the schedule's
+            // own filled pattern, replayed and compared to the same dense
+            // solve. A refused candidate (null) or a replay that trips its own
+            // guard (Infinity) behaves exactly like a disagreeing one below.
             const candidate = computeNumericRepivot(schedule, size, matrix);
+            let candidateDisagreement = Infinity;
             if (candidate !== null) {
                 const candidateValues = new Float64Array(candidate.slots);
                 const candidateRhs = new Float64Array(size);
@@ -2704,31 +2797,44 @@ export class ReferenceRuntime {
                     candidateDiffSquares += difference * difference;
                     candidateDenseSquares += denseOut[index] ** 2;
                 }
-                const candidateDisagreement = candidateReplayed
+                candidateDisagreement = candidateReplayed
                     ? Math.sqrt(candidateDiffSquares) /
                         Math.max(Math.sqrt(candidateDenseSquares), 1e-9)
                     : Infinity;
-                if (candidateDisagreement <= SCHEDULE_VALIDATION_TOL) {
-                    this.sparseSchedules.set(blockId, {
-                        schedule: candidate,
-                        values: new Float64Array(candidate.slots),
-                        rhs: new Float64Array(size),
-                        factors: new Float64Array(candidate.factorCount),
-                        consecutiveFallbacks: 0,
-                    });
-                    this.repivotedSchedules.add(blockId);
-                    this.droppedSchedules.delete(blockId);
-                    if (planRow !== undefined) {
-                        planRow.path = "sparse";
-                        planRow.reason = `numeric re-pivot ${candidateDisagreement.toExponential(1)} vs dense`;
-                        planRow.pivotDisagreement = candidateDisagreement;
-                        planRow.repivoted = true;
-                        planRow.patternEntries = candidate.slots;
-                        planRow.sparseOps = candidate.sparseOps;
-                        planRow.unprovenPivots = candidate.unprovenPivots;
-                    }
+            }
+            if (disagreement <= SCHEDULE_VALIDATION_TOL) {
+                // The shipped order validates. Replace it only on a refinement:
+                // the candidate reaches the audio-agreement bar while the
+                // shipped order does not, by an order of magnitude, without
+                // meaningful fill cost (see `shouldRefinePivotOrder`). Ties
+                // keep shipped, so adoption never churns a schedule for noise
+                // -- measured, `boss-hm-2`, `boss-ch-1` and `boss-od-3` tie
+                // and keep shipped while `boss-sd-1` crosses (1.8e-9 to
+                // 4.2e-13, audio 6.9e-8 to 6.5e-12).
+                if (candidate !== null &&
+                    shouldRefinePivotOrder({
+                        shippedDisagreement: disagreement,
+                        candidateDisagreement,
+                        shippedOps: schedule.sparseOps,
+                        shippedSlots: schedule.slots,
+                        candidateOps: candidate.sparseOps,
+                        candidateSlots: candidate.slots,
+                    })) {
+                    this.adoptRepivotedSchedule(blockId, candidate, size, planRow, `numeric re-pivot ${candidateDisagreement.toExponential(1)} vs dense ` +
+                        `(shipped ${Number.isFinite(disagreement) ? disagreement.toExponential(1) : "replay refused"}); ` +
+                        `+${(((candidate.sparseOps / Math.max(schedule.sparseOps, 1)) - 1) * 100).toFixed(1)}% ops`, candidateDisagreement);
                     continue;
                 }
+                continue;
+            }
+            // The shipped order failed on the real matrix. Before giving the
+            // schedule up, try the value-aware order computed above: adoption
+            // needs the same tolerance the shipped order failed; a refused or
+            // still-disagreeing candidate drops as before.
+            if (candidate !== null &&
+                candidateDisagreement <= SCHEDULE_VALIDATION_TOL) {
+                this.adoptRepivotedSchedule(blockId, candidate, size, planRow, `numeric re-pivot ${candidateDisagreement.toExponential(1)} vs dense`, candidateDisagreement);
+                continue;
             }
             this.sparseSchedules.delete(blockId);
             this.droppedSchedules.add(blockId);
@@ -2745,6 +2851,102 @@ export class ReferenceRuntime {
             }
         }
     }
+    /**
+     * Adopt a value-aware replacement order for a block, from settle or from
+     * the mid-run re-pivot, with one shared bookkeeping shape.
+     *
+     * The replacement's slots are a superset of the shipped filled pattern
+     * whose extra cells no stamp writes (see `computeNumericRepivot`), so the
+     * pattern-sized matrix refresh keeps reading correct zeros and neither
+     * `clearPairs` nor the selective-copy machinery needs a rebuild -- the
+     * same reason a dropped block, which does change the refresh, sets
+     * `clearPairs` to null where this does not.
+     */
+    adoptRepivotedSchedule(blockId, candidate, size, planRow, reason, pivotDisagreement) {
+        this.sparseSchedules.set(blockId, {
+            schedule: candidate,
+            values: new Float64Array(candidate.slots),
+            rhs: new Float64Array(size),
+            factors: new Float64Array(candidate.factorCount),
+            consecutiveFallbacks: 0,
+            repivotAttempted: false,
+        });
+        this.repivotedSchedules.add(blockId);
+        this.droppedSchedules.delete(blockId);
+        if (planRow !== undefined) {
+            planRow.path = "sparse";
+            planRow.reason = reason;
+            planRow.pivotDisagreement = pivotDisagreement;
+            planRow.repivoted = true;
+            planRow.patternEntries = candidate.slots;
+            planRow.sparseOps = candidate.sparseOps;
+            planRow.unprovenPivots = candidate.unprovenPivots;
+        }
+    }
+    /**
+     * The mid-run half of the pivot-guard contract: at the consecutive-trip
+     * limit, re-pivot once from the current matrix instead of abandoning.
+     *
+     * Takes the stamped matrix and rhs snapshotted before the dense fallback
+     * destroyed them, plus the fallback's answer, and returns whether a
+     * value-aware order was adopted. Adoption needs the rescue standard --
+     * replay within `SCHEDULE_VALIDATION_TOL` of the dense answer on this
+     * matrix -- the same bar a collapse rescue clears at settle, because this
+     * is a rescue: the shipped order demonstrably does not suit this
+     * operating region. A refusal (null candidate, tripped replay, or a
+     * disagreeing replay) returns false and the caller abandons exactly as
+     * before, with the reason naming the refusal. Either outcome lands in
+     * the plan row, so a mid-run adoption is as visible as a settle one.
+     *
+     * Structured for direct unit testing (pure inputs, boolean verdict): the
+     * corpus never trips the guard, so no corpus run exercises this path.
+     */
+    adoptMidRunRepivot(blockId, entry, matrix, rhs, denseAnswer) {
+        const planRow = this.solverPlanRows.find((candidate) => candidate.blockId === blockId);
+        const block = this.blocksById.get(blockId);
+        const size = block !== undefined && block.kind === "mna"
+            ? block.nodeCount + block.auxCount
+            : 0;
+        const refuse = (reason) => {
+            if (planRow !== undefined) {
+                planRow.reason += ` mid-run re-pivot ${reason}; abandoned`;
+            }
+            return false;
+        };
+        if (block === undefined || block.kind !== "mna" || size <= 0) {
+            return refuse("refused (unknown block)");
+        }
+        const candidate = computeNumericRepivot(entry.schedule, size, matrix);
+        if (candidate === null) {
+            return refuse("refused (no candidate meets the threshold)");
+        }
+        const values = new Float64Array(candidate.slots);
+        const scratchRhs = new Float64Array(size);
+        const factors = new Float64Array(candidate.factorCount);
+        const out = new Array(size).fill(0);
+        const replayed = runSparseSchedule(candidate, matrix, rhs, values, scratchRhs, factors, out);
+        let diffSquares = 0;
+        let denseSquares = 0;
+        for (let index = 0; index < size; index += 1) {
+            const difference = out[index] - denseAnswer[index];
+            diffSquares += difference * difference;
+            denseSquares += denseAnswer[index] ** 2;
+        }
+        const disagreement = replayed
+            ? Math.sqrt(diffSquares) / Math.max(Math.sqrt(denseSquares), 1e-9)
+            : Infinity;
+        if (!(disagreement <= SCHEDULE_VALIDATION_TOL)) {
+            return refuse(`refused (replay ${Number.isFinite(disagreement) ? disagreement.toExponential(1) : "tripped"} vs dense)`);
+        }
+        this.adoptRepivotedSchedule(blockId, candidate, size, planRow, `mid-run numeric re-pivot ${disagreement.toExponential(1)} vs dense after ${SCHEDULE_CONSECUTIVE_FALLBACK_LIMIT} guard trips`, disagreement);
+        // The one attempt is spent: a second limit-hit on the adopted order
+        // abandons rather than re-pivoting again.
+        const adopted = this.sparseSchedules.get(blockId);
+        if (adopted !== undefined) {
+            adopted.repivotAttempted = true;
+        }
+        return true;
+    }
     /**
      * 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.
@@ -2776,73 +2978,148 @@ export class ReferenceRuntime {
         // `samples` and the non-converged counters stay in **host** samples however many
         // sub-samples each one costs, because their only job is to report the share of rendered
         // audio that is untrustworthy, and a listener hears host samples.
-        for (let index = 0; index < input.length; index += 1) {
-            // Every block is solved, but the result comes from the block that owns the
-            // output jack -- not from whichever ran last. Regions are independent
-            // subcircuits; only their shared nodes couple them.
-            const sample = input[index] ?? 0;
-            let hostResult = 0;
-            let hostNonConverged = false;
-            let hostNonFinite = false;
-            // The input is **held** across the sub-samples rather than interpolated. A host
-            // sample is one measurement and inventing intermediate values is inventing signal;
-            // holding is the zero-order reading of what was actually delivered.
-            for (let sub = 0; sub < this.oversample; sub += 1) {
-                // Sample `n` is the circuit at `t = n / sampleRate`, counted from `prepare`. Set here
-                // so every block in this sample sees one time, and advanced below so buffer
-                // boundaries are invisible.
-                this.timeSeconds = this.elapsedSamples / this.sampleRate;
-                let result = 0;
-                // A sample is counted once however many of its blocks failed. Counting each
-                // failing block instead let `nonConvergedSamples` exceed `samples` in a
-                // multi-region program, so the number could not be read as the share of audio
-                // that is untrustworthy -- which is the only thing it is for.
-                this.sampleNonConverged = false;
-                this.sampleNonFinite = false;
-                for (const id of this.program.order) {
-                    const block = this.blocksById.get(id);
-                    if (block === undefined) {
-                        continue;
-                    }
-                    const blockOutput = this.processBlock(block, sample);
-                    if (block.kind === "mna" && block.outputNode !== null) {
-                        result = blockOutput;
-                    }
-                }
-                if (this.sampleNonConverged) {
-                    hostNonConverged = true;
-                }
-                if (this.sampleNonFinite) {
-                    hostNonFinite = true;
-                }
-                // The rendered supply peak, read from the solved branch unknowns. Every sample, because
-                // a rectifier's current is a pulse a few samples wide and a coarser sampling of it
-                // would report a smaller number for no physical reason.
-                for (const branch of this.supplyBranchSlots) {
-                    const amps = this.nodeVoltages.get(branch.blockId)?.[branch.slot] ?? 0;
-                    const magnitude = Math.abs(amps);
-                    if (magnitude > this.renderedSupplyPeakAmps) {
-                        this.renderedSupplyPeakAmps = magnitude;
-                    }
-                }
-                this.elapsedSamples += 1;
-                hostResult = result;
-            }
-            // Zero-order decimation: the last sub-sample is the host sample. This is what the
-            // 47-to-50 parity measurement was taken with, and on `boss-ce-5` it is bit-identical
-            // to a boxcar average because the limit cycle oversampling removes is *gone* rather
-            // than moved above Nyquist. A band-limiting decimator is a real improvement for
-            // broadband content and deliberately not guessed at here.
-            if (hostNonConverged) {
-                this.nonConvergedSamples += 1;
+        if (this.resampleUp.length === 0) {
+            for (let index = 0; index < input.length; index += 1) {
+                output[index] = this.processHeldSample(input[index] ?? 0);
             }
-            if (hostNonFinite) {
-                this.nonFiniteSamples += 1;
+        }
+        else {
+            for (let index = 0; index < input.length; index += 1) {
+                output[index] = this.processResampledSample(input[index] ?? 0);
             }
-            output[index] = hostResult;
         }
         return output;
     }
+    /**
+     * One host sample through the legacy path: the input held flat across the
+     * sub-samples, the last sub-sample kept. Bit-identical to the behaviour
+     * before the band-limited resampler existed, which is what makes factor 1
+     * (and non-power-of-two factors) cost nothing and change nothing.
+     */
+    processHeldSample(sample) {
+        // Every block is solved, but the result comes from the block that owns the
+        // output jack -- not from whichever ran last. Regions are independent
+        // subcircuits; only their shared nodes couple them.
+        let hostResult = 0;
+        let hostNonConverged = false;
+        let hostNonFinite = false;
+        // The input is **held** across the sub-samples rather than interpolated. A host
+        // sample is one measurement and inventing intermediate values is inventing signal;
+        // holding is the zero-order reading of what was actually delivered.
+        for (let sub = 0; sub < this.oversample; sub += 1) {
+            hostResult = this.solveSubSample(sample);
+            if (this.sampleNonConverged) {
+                hostNonConverged = true;
+            }
+            if (this.sampleNonFinite) {
+                hostNonFinite = true;
+            }
+        }
+        // Zero-order decimation: the last sub-sample is the host sample. This is what the
+        // 47-to-50 parity measurement was taken with, and on `boss-ce-5` it is bit-identical
+        // to a boxcar average because the limit cycle oversampling removes is *gone* rather
+        // than moved above Nyquist.
+        if (hostNonConverged) {
+            this.nonConvergedSamples += 1;
+        }
+        if (hostNonFinite) {
+            this.nonFiniteSamples += 1;
+        }
+        return hostResult;
+    }
+    /**
+     * One host sample through the band-limited path: half-band interpolate up
+     * by 2 per stage, solve each sub-sample, FIR-decimate back to one host
+     * sample. The resampler state lives on the stages across `process()`
+     * calls, so any block split renders bit-identically to one long call;
+     * the group delay this adds is reported by `oversampleLatency()`.
+     */
+    processResampledSample(sample) {
+        const stages = this.resampleUp.length;
+        // Up cascade: alternate the two scratch buffers, doubling each stage.
+        let cur = this.resampleBufA;
+        let next = this.resampleBufB;
+        this.resampleUp[0].interpolate(sample, cur, 0);
+        let width = 2;
+        for (let stage = 1; stage < stages; stage += 1) {
+            for (let i = 0; i < width; i += 1) {
+                this.resampleUp[stage].interpolate(cur[i], next, 2 * i);
+            }
+            const swap = cur;
+            cur = next;
+            next = swap;
+            width *= 2;
+        }
+        // Solve every sub-sample; outputs land in the idle buffer.
+        let hostNonConverged = false;
+        let hostNonFinite = false;
+        for (let sub = 0; sub < width; sub += 1) {
+            next[sub] = this.solveSubSample(cur[sub]);
+            if (this.sampleNonConverged) {
+                hostNonConverged = true;
+            }
+            if (this.sampleNonFinite) {
+                hostNonFinite = true;
+            }
+        }
+        // Down cascade, highest rate first, halving in place of `next`.
+        const hi = next;
+        for (let stage = stages - 1; stage >= 0; stage -= 1) {
+            const half = width / 2;
+            for (let i = 0; i < half; i += 1) {
+                hi[i] = this.resampleDown[stage].decimate(hi[2 * i], hi[2 * i + 1]);
+            }
+            width = half;
+        }
+        if (hostNonConverged) {
+            this.nonConvergedSamples += 1;
+        }
+        if (hostNonFinite) {
+            this.nonFiniteSamples += 1;
+        }
+        return hi[0];
+    }
+    /**
+     * One sub-sample solve at the solver rate: every block stepped once at
+     * `t = elapsedSamples / sampleRate`, returning the output jack's value.
+     * Shared by the held and the resampled paths, so factor 1 executes the
+     * same operations in the same order as before the resampler existed.
+     */
+    solveSubSample(subInput) {
+        // Sample `n` is the circuit at `t = n / sampleRate`, counted from `prepare`. Set here
+        // so every block in this sample sees one time, and advanced below so buffer
+        // boundaries are invisible.
+        this.timeSeconds = this.elapsedSamples / this.sampleRate;
+        let result = 0;
+        // A sample is counted once however many of its blocks failed. Counting each
+        // failing block instead let `nonConvergedSamples` exceed `samples` in a
+        // multi-region program, so the number could not be read as the share of audio
+        // that is untrustworthy -- which is the only thing it is for.
+        this.sampleNonConverged = false;
+        this.sampleNonFinite = false;
+        for (const id of this.program.order) {
+            const block = this.blocksById.get(id);
+            if (block === undefined) {
+                continue;
+            }
+            const blockOutput = this.processBlock(block, subInput);
+            if (block.kind === "mna" && block.outputNode !== null) {
+                result = blockOutput;
+            }
+        }
+        // The rendered supply peak, read from the solved branch unknowns. Every sample, because
+        // a rectifier's current is a pulse a few samples wide and a coarser sampling of it
+        // would report a smaller number for no physical reason.
+        for (const branch of this.supplyBranchSlots) {
+            const amps = this.nodeVoltages.get(branch.blockId)?.[branch.slot] ?? 0;
+            const magnitude = Math.abs(amps);
+            if (magnitude > this.renderedSupplyPeakAmps) {
+                this.renderedSupplyPeakAmps = magnitude;
+            }
+        }
+        this.elapsedSamples += 1;
+        return result;
+    }
     /**
      * The rate the caller passed to `prepare`, as opposed to the solver's sub-sample rate.
      *
@@ -2852,6 +3129,17 @@ export class ReferenceRuntime {
     hostSampleRate() {
         return this.sampleRate === null ? null : this.sampleRate / this.oversample;
     }
+    /**
+     * The resampler's total group delay in **host** samples, or `null` before
+     * `prepare()`. Zero when the resampler is bypassed (factor 1, or a factor
+     * that is not a power of two and keeps the legacy path): the held path
+     * adds no latency by construction. At 2x/4x/8x this is 19.5/26.25/28.625
+     * host samples for the stage-specific half-band cascade -- a real, reported
+     * latency the caller must absorb or declare, not a hidden one.
+     */
+    oversampleLatency() {
+        return this.sampleRate === null ? null : this.resampleLatencyHost;
+    }
     processBlock(block, input) {
         if (block.kind === "composed") {
             this.processComposedBlock(block);
@@ -3530,8 +3818,19 @@ export class ReferenceRuntime {
         // itself is read-only here and is never handed back to the caller aliased to either
         // buffer, so a caller that still holds it (`[...guess]` in the continuation methods,
         // `previous.slice()` in `processBlock`) sees it unchanged.
+        //
+        // On a standard audio pass of a nonlinear block, and only when the runtime was prepared
+        // with `oversample > 1`, the seed is the predicted start (see `newtonStartHistory`),
+        // falling back to `start`. At factor 1 nothing seeds and nothing records. `start`
+        // itself stays the previous solution for the fold reseed below.
+        const predictorPass = this.oversample > 1 &&
+            !dc &&
+            sourceScale === 1 &&
+            gmin === GMIN_SIEMENS &&
+            !block.linear;
+        const seed = (predictorPass ? this.predictedNewtonStart(block.id, size) : null) ?? start;
         for (let index = 0; index < size; index += 1) {
-            solutionA[index] = start[index] ?? 0;
+            solutionA[index] = seed[index] ?? 0;
         }
         let current = solutionA;
         let next = solutionB;
@@ -3672,11 +3971,37 @@ export class ReferenceRuntime {
                     this.scheduleFallbacks += 1;
                     sparse.consecutiveFallbacks += 1;
                     if (sparse.consecutiveFallbacks >= SCHEDULE_CONSECUTIVE_FALLBACK_LIMIT) {
-                        this.sparseSchedules.delete(block.id);
-                        this.abandonedSchedules.add(block.id);
+                        // The old shape abandoned here, silently dense for the rest
+                        // of the run after paying for both solvers on every one of
+                        // the 64 trips. Re-pivot once from the current matrix
+                        // instead: a control position the operating-point matrix
+                        // never showed can still suit a value-aware order, and
+                        // only a refused or still-disagreeing re-pivot abandons.
+                        // `solve` destroys `matrix` and `rhs`, so the re-pivot's
+                        // inputs are snapshotted first -- once per order, on this
+                        // trip only.
+                        if (!sparse.repivotAttempted) {
+                            sparse.repivotAttempted = true;
+                            const matrixCopy = matrix.map((row) => [...row]);
+                            const rhsCopy = [...rhs];
+                            scratch.denseDirty = true;
+                            solve(matrix, rhs, next);
+                            if (!this.adoptMidRunRepivot(block.id, sparse, matrixCopy, rhsCopy, next)) {
+                                this.sparseSchedules.delete(block.id);
+                                this.abandonedSchedules.add(block.id);
+                            }
+                        }
+                        else {
+                            this.sparseSchedules.delete(block.id);
+                            this.abandonedSchedules.add(block.id);
+                            scratch.denseDirty = true;
+                            solve(matrix, rhs, next);
+                        }
+                    }
+                    else {
+                        scratch.denseDirty = true;
+                        solve(matrix, rhs, next);
                     }
-                    scratch.denseDirty = true;
-                    solve(matrix, rhs, next);
                 }
             }
             if (relaxing) {
@@ -3832,6 +4157,9 @@ export class ReferenceRuntime {
                     census.peakIterations = used;
             }
         }
+        if (predictorPass) {
+            this.recordNewtonSolution(block.id, current, converged, used);
+        }
         return { solution: current, converged, used, worstNode, worstDelta };
     }
     /**
@@ -4024,8 +4352,17 @@ export class ReferenceRuntime {
                 full[portRows[p]] = y[p];
             }
         };
+        // The predicted start (see `newtonStartHistory`), falling back to `start`: the same
+        // rule and the same `oversample > 1` gate as `iterate`, applied through the port
+        // unknowns the reduced solve iterates on.
+        const predictorPass = this.oversample > 1 &&
+            !dc &&
+            sourceScale === 1 &&
+            gmin === GMIN_SIEMENS &&
+            !block.linear;
+        const seed = (predictorPass ? this.predictedNewtonStart(block.id, size) : null) ?? start;
         for (let p = 0; p < portCount; p += 1) {
-            scratch.yCurrent[p] = start[portRows[p]] ?? 0;
+            scratch.yCurrent[p] = seed[portRows[p]] ?? 0;
         }
         reconstructFull(scratch.yCurrent, scratch.fullCurrent);
         const iterations = this.maxNewtonIterations;
@@ -4164,6 +4501,9 @@ export class ReferenceRuntime {
                     census.peakIterations = used;
             }
         }
+        if (predictorPass) {
+            this.recordNewtonSolution(block.id, current, converged, used);
+        }
         return { solution: current, converged, used, worstNode, worstDelta };
     }
     /**
@@ -4461,6 +4801,110 @@ export class ReferenceRuntime {
         this.opampHistory.clear();
         this.triodeHistory.clear();
     }
+    /**
+     * The Newton start `newtonStartHistory` selects for this block, or `null` to start from
+     * the caller's previous solution (order 0, or a chain too short for the chosen order).
+     * The returned array is the block's reused scratch: read it before the next solve.
+     */
+    predictedNewtonStart(blockId, size) {
+        const history = this.newtonStartHistory.get(blockId);
+        if (history === undefined || history.order === 0) {
+            return null;
+        }
+        if (history.candidate.length !== size) {
+            history.candidate = new Array(size).fill(0);
+        }
+        return extrapolateNewtonStart(history, history.order, size, history.candidate)
+            ? history.candidate
+            : null;
+    }
+    /**
+     * Record a finished standard-pass solve: on convergence, score the three candidate
+     * starts the history could have produced against the solution just reached (one fused
+     * pass, no allocation) and keep the best order for the next solve, then rotate the
+     * solution into the history ring; on failure, break the chain.
+     */
+    recordNewtonSolution(blockId, solution, converged, used) {
+        let history = this.newtonStartHistory.get(blockId);
+        if (history === undefined) {
+            history = { x1: null, x2: null, x3: null, chain: 0, order: 0, candidate: [] };
+            this.newtonStartHistory.set(blockId, history);
+        }
+        if (!converged) {
+            history.chain = 0;
+            history.order = 0;
+            return;
+        }
+        const size = solution.length;
+        const { x1, x2, x3 } = history;
+        const has1 = history.chain >= 1 && x1 !== null && x1.length === size;
+        const has2 = has1 && history.chain >= 2 && x2 !== null && x2.length === size;
+        const has3 = has2 && history.chain >= 3 && x3 !== null && x3.length === size;
+        let error0 = has1 ? 0 : Number.POSITIVE_INFINITY;
+        let error1 = has2 ? 0 : Number.POSITIVE_INFINITY;
+        let error2 = has3 ? 0 : Number.POSITIVE_INFINITY;
+        if (has1) {
+            for (let index = 0; index < size; index += 1) {
+                const s = solution[index];
+                const magnitude = Math.abs(s);
+                const v1 = x1[index];
+                const ratio0 = Math.abs(v1 - s) /
+                    (NEWTON_RELATIVE_TOLERANCE * Math.max(Math.abs(v1), magnitude) +
+                        NEWTON_VOLTAGE_TOLERANCE);
+                if (ratio0 > error0)
+                    error0 = ratio0;
+                if (!has2)
+                    continue;
+                const v2 = x2[index];
+                const guess1 = 2 * v1 - v2;
+                const ratio1 = Math.abs(guess1 - s) /
+                    (NEWTON_RELATIVE_TOLERANCE * Math.max(Math.abs(guess1), magnitude) +
+                        NEWTON_VOLTAGE_TOLERANCE);
+                if (ratio1 > error1)
+                    error1 = ratio1;
+                if (!has3)
+                    continue;
+                const guess2 = 3 * v1 - 3 * v2 + x3[index];
+                const ratio2 = Math.abs(guess2 - s) /
+                    (NEWTON_RELATIVE_TOLERANCE * Math.max(Math.abs(guess2), magnitude) +
+                        NEWTON_VOLTAGE_TOLERANCE);
+                if (ratio2 > error2)
+                    error2 = ratio2;
+            }
+        }
+        // Strictly better only: a tie keeps the lower order, so a flat signal (where every
+        // order predicts the same point) stays on the previous-solution start.
+        let best = 0;
+        let bestError = error0;
+        if (error1 < bestError) {
+            best = 1;
+            bestError = error1;
+        }
+        if (error2 < bestError) {
+            best = 2;
+        }
+        // Smooth-regime gate: extrapolate only after a solve that took at most two
+        // iterations (one step and one check -- the floor). A solve that needed more was
+        // hunting across a knee, and there a start that is closer in tolerance units is not
+        // a cheaper start: measured without this gate, `analog-man-prince-of-tone` cost
+        // +50 % iterations at x1 and `boss-hm-2` +39 % (peak 33 -> 63) with every
+        // extrapolation scoring better than the previous solution; with it, -4 % and 0 %,
+        // and every os4 gain is kept (2026-10-09 report, §3/§12).
+        if (used > 2) {
+            best = 0;
+        }
+        history.order = best;
+        // Rotate the ring without allocating: the oldest buffer receives the new solution.
+        const oldest = history.x3;
+        history.x3 = history.x2;
+        history.x2 = history.x1;
+        history.x1 =
+            oldest !== null && oldest.length === size ? oldest : new Array(size).fill(0);
+        for (let index = 0; index < size; index += 1) {
+            history.x1[index] = solution[index];
+        }
+        history.chain += 1;
+    }
     snapshotLimiterHistories() {
         return {
             diode: new Map(this.diodeHistory),
@@ -6404,11 +6848,30 @@ function solve(matrix, rhs, out) {
 /** The opcode stream's per-instruction width, in `Int32Array` slots. */
 const SCHEDULE_OP_WIDTH = 4;
 /**
- * A pivot this small is what the dense `solve` refuses to divide by (its own `continue`), and
- * it is what a *static* order can walk into that a value-aware one cannot: an entry that is
- * structurally present but numerically zero at this control position or this Newton iterate.
+ * Pivot guard floor: a pivot below this absolute value sends the solve back
+ * to the dense path.
+ *
+ * This is deliberately ABSOLUTE, not relative, and that is a measured
+ * position rather than a default. A relative guard (`|pivot| < tau *
+ * max|gathered|`) was implemented and reverted 2026-10-08: at tau 1e-12 it
+ * dropped healthy `boss-ce-5` to dense outright; at 1e-14 it gratuitously
+ * re-pivoted `boss-ch-1`; at 1e-16 it abandoned `boss-dd-3b` and
+ * `mxr-blue-box`, dropped `boss-tw-1` (losing its 0.8x budget fix) and
+ * `mxr-dyna-comp`'s rescue, regressed `boss-nf-1` audio 1000x (7.0e-11 to
+ * 7.7e-05), and put 528k fallback solves onto `moogerfooger-mf-102` for no
+ * audio change. The census behind it: healthy `ce-5`/`ch-1`/carbon-copy
+ * bottom out at 1.0-2.5e-15 while fatal `aw-2` sits at 7.7e-15 -- magnitude
+ * alone cannot separate a healthy late-order gmin pivot from a fatal one,
+ * only a replay against dense can, which is the settle gate's job, not this
+ * one's. So this floor catches exactly what it can judge -- collapse -- and
+ * the re-pivot-once below handles the shape that collapse takes mid-run.
+ * See `docs/spikes/2026-10-08-numeric-pivoting.md`.
+ *
+ * Exported for the unit tests alongside the replay: the trip formula is
+ * load-bearing and the corpus never trips it, so only a synthetic matrix
+ * pins it.
  */
-const SCHEDULE_PIVOT_FLOOR = 1e-18;
+export const SCHEDULE_PIVOT_FLOOR = 1e-18;
 /**
  * How far the sparse replay's answer for the assembled operating-point matrix
  * may disagree with the dense solve's before the shipped order is dropped.
@@ -6424,6 +6887,37 @@ const SCHEDULE_PIVOT_FLOOR = 1e-18;
  * must validate clean.
  */
 const SCHEDULE_VALIDATION_TOL = 1e-3;
+/**
+ * Audio-agreement bar for adopting a value-aware order over a shipped order
+ * that already validates.
+ *
+ * The shipped order replays the operating-point matrix within
+ * `SCHEDULE_VALIDATION_TOL`; the refinement below replaces it only when the
+ * numeric candidate reaches the corpus acceptance bar (sparse vs dense at
+ * most 1e-9 relative) an order of magnitude more cleanly, without meaningful
+ * fill cost. Measured 2026-10-08: `boss-sd-1` crosses (operating-point replay
+ * 1.8e-9 to 4.2e-13, audio 6.9e-8 to 6.5e-12); `boss-hm-2`, `boss-ch-1`,
+ * `boss-od-3` tie and keep shipped; `marshall-jcm800` and `boss-tw-1` cannot
+ * cross at any tau and keep shipped. See
+ * `docs/spikes/2026-10-08-numeric-pivoting.md`.
+ */
+const SCHEDULE_REFINEMENT_BAR = 1e-9;
+/**
+ * How much cleaner the candidate's operating-point replay must be than the
+ * shipped order's before the refinement above fires. Ties (the common case --
+ * both orders replay a healthy matrix to the same rounding) keep shipped, so
+ * adoption never churns a schedule for noise. 10x sits in the measured
+ * canyon: ties are within ~1x, real wins are 1000x or more.
+ */
+const SCHEDULE_REFINEMENT_RATIO = 10;
+/**
+ * Fill-growth ceiling for a refinement adoption, in slots and in ops. A
+ * better replay that costs a third more elimination (`boss-mt-2`: +34% ops
+ * for no audio gain; `mxr-phase-90`: +30% ops for an audio *regression*)
+ * fails the cost criterion it was meant to serve, so the rule refuses it and
+ * keeps shipped. Measured adopters sit far below: `boss-sd-1` +6.5% ops.
+ */
+const SCHEDULE_REFINEMENT_MAX_COST_GROWTH = 1.1;
 // A **residual check on the schedule's answer was implemented, measured and removed.** The
 // reasoning that motivated it was that a static order might produce a bad answer where a
 // pivoting one does not, and that the answer should therefore be verified rather than trusted.
@@ -6453,16 +6947,53 @@ const SCHEDULE_MINIMUM_SAVING = 4;
  * about what to do before it fills. 64 in a row is not an unlucky operating point.
  */
 const SCHEDULE_CONSECUTIVE_FALLBACK_LIMIT = 64;
+/**
+ * Whether a validating shipped order should be replaced by the numeric
+ * candidate: the refinement half of `settlePivotOrders`, extracted pure so
+ * both consoles and the unit tests share the exact predicate.
+ *
+ * Adopt only when the shipped order is above the audio-agreement bar while
+ * the candidate reaches it, by an order of magnitude, without meaningful
+ * fill cost. The shipped-side floor matters as much as the candidate-side
+ * bar: without it, bar-clean ties with a 1000x replay gap (`trainwreck`,
+ * `fender-5e3`, `vox-ac15`) churn schedules -- and lose their generated
+ * kernels on the C++ console -- for zero audio gain, and `hiwatt-dr103`
+ * adopts on one console but not the other from libm-level matrix noise.
+ * Every input is an operating-point-replay disagreement or a slot/op count
+ * -- no audio renders, no per-packet gates.
+ */
+export function shouldRefinePivotOrder(input) {
+    // Total on purpose: settle only calls this when the shipped order
+    // validates (finite, within tolerance), but a refused replay reads as
+    // Infinity and must never refine -- that case belongs to the rescue
+    // branch, with its looser bar, or to the drop.
+    if (!Number.isFinite(input.shippedDisagreement) ||
+        !Number.isFinite(input.candidateDisagreement)) {
+        return false;
+    }
+    return (input.shippedDisagreement > SCHEDULE_REFINEMENT_BAR &&
+        input.candidateDisagreement <= SCHEDULE_REFINEMENT_BAR &&
+        input.candidateDisagreement <
+            input.shippedDisagreement / SCHEDULE_REFINEMENT_RATIO &&
+        input.candidateOps <=
+            SCHEDULE_REFINEMENT_MAX_COST_GROWTH * input.shippedOps &&
+        input.candidateSlots <=
+            SCHEDULE_REFINEMENT_MAX_COST_GROWTH * input.shippedSlots);
+}
 /**
  * Replay a schedule against one stamped matrix.
  *
- * Returns `false` without finishing when a pivot has collapsed below `SCHEDULE_PIVOT_FLOOR`,
- * which is the caller's signal to run the dense solve for this iteration instead. Nothing the
- * caller still needs is destroyed on the way: `matrix` is only read (the gather copies out of
- * it), `rhs` is copied into the schedule's own buffer, and `out` is a scratch buffer the dense
- * fallback overwrites in full.
+ * Returns `false` without finishing when a pivot has collapsed below
+ * `SCHEDULE_PIVOT_FLOOR`, which is the caller's signal to run the dense solve
+ * for this iteration instead. Nothing the caller still needs is destroyed on
+ * the way: `matrix` is only read (the gather copies out of it), `rhs` is
+ * copied into the schedule's own buffer, and `out` is a scratch buffer the
+ * dense fallback overwrites in full.
+ *
+ * Exported for the unit tests: the trip formula is load-bearing and the
+ * corpus never trips it, so only a synthetic matrix pins the boundary.
  */
-function runSparseSchedule(schedule, matrix, rhs, values, scratchRhs, factors, out) {
+export function runSparseSchedule(schedule, matrix, rhs, values, scratchRhs, factors, out) {
     const { ops, gatherRow, gatherColumn, slots, size } = schedule;
     for (let index = 0; index < slots; index += 1) {
         values[index] = matrix[gatherRow[index]][gatherColumn[index]];
@@ -6686,6 +7217,37 @@ function relativeResidual(matrix, rhs, x, pairs, size) {
     }
     return Number.isFinite(worst) ? worst : Number.POSITIVE_INFINITY;
 }
+/**
+ * Order-`order` extrapolation of a block's converged-solution history (see
+ * `newtonStartHistory`) written into `out`: the previous solution, the linear
+ * `2*x1 - x2`, or the quadratic `3*x1 - 3*x2 + x3`. Returns `false`, writing nothing, when
+ * the chain is shorter than the order needs.
+ */
+function extrapolateNewtonStart(history, order, size, out) {
+    const { x1, x2, x3, chain } = history;
+    if (order === 0) {
+        if (chain < 1 || x1 === null)
+            return false;
+        for (let index = 0; index < size; index += 1)
+            out[index] = x1[index];
+        return true;
+    }
+    if (order === 1) {
+        if (chain < 2 || x1 === null || x2 === null)
+            return false;
+        for (let index = 0; index < size; index += 1) {
+            out[index] = 2 * x1[index] - x2[index];
+        }
+        return true;
+    }
+    if (chain < 3 || x1 === null || x2 === null || x3 === null)
+        return false;
+    for (let index = 0; index < size; index += 1) {
+        out[index] =
+            3 * x1[index] - 3 * x2[index] + x3[index];
+    }
+    return true;
+}
 function withinTolerance(next, previous) {
     for (let index = 0; index < next.length; index += 1) {
         const a = next[index] ?? 0;