A constant-time hypothesis.

• target: the IO action under test.
• prepare: a per-pair prologue, run before either sampler and outside the timed region; pure () unless the classes share per-pair state (see fixVsRandomCtx).
• sampleA, sampleB: samplers for the two input classes, typically "fixed" and "random".

Only target is timed, so any asymmetry in how the samplers prepare inputs shows up as a class difference. Return inputs in normal form, build the fixed class by the same code path as the random one (not as a top-level constant), and keep the samplers symmetric in allocation and in where the secret is read from. fixVsRandom does this for the usual case.

A dudect-style fix-vs-random Hypothesis, from a target, a secret sampler, a re-materialisation function, and a completion building a full input around a secret.

The fixed secret is drawn once from the sampler, so it is an ordinary heap value like the random class's. Each sample, class A draws and discards a fresh secret and class B keeps its draw, so the samplers allocate alike. Both classes then re-materialise the pinned secret: class A completes around the copy, class B discards it. With a real copy (for a ByteString, \s -> evaluate (BS.copy s)), neither class is alone in reading one long-lived, cache-hot value, a locality asymmetry that the A/A and B/B controls cannot see. Pass pure only for types with no cheap copy.

The completion runs identically in both classes, so per-pair public inputs stay fresh on both sides. The sampler, re-materialiser, and completion must return values in normal form.

hyp <- fixVsRandom
  (\x -> () <$ evaluate (inv x))   -- target
  (randomMont g)                   -- secret sampler
  pure                             -- no re-materialiser
  pure                             -- input is just the secret

A fix-vs-random Hypothesis whose two classes share one freshly drawn public context per pair.

fixVsRandom completes each class independently, so per-pair public inputs (message, nonce, modulus) either differ across the pair, adding nuisance variance to d, or are pinned for the whole run, testing a single public input. Here prepare draws one context per pair and both classes are built around it, so the test is of secret dependence given identical fresh public input. The null is unaffected: given the context, the two readings are still exchangeable under H_0.

The re-materialisation function plays the same role as in fixVsRandom.

hyp <- fixVsRandomCtx
  (\(k, m) -> () <$ evaluate (mac k m))  -- target
  (randomBytes g 32)                     -- secret sampler
  (\k -> evaluate (BS.copy k))           -- re-materialise
  (randomBytes g 256)                    -- public context
  (\msg key -> pure (key, msg))          -- build the input

Driver configuration.

Defaults: alpha = 1e-6, budget 100000 pairs, batch 1 (no inner repetition), warmup 200 pairs, order-bit seed drawn from OS entropy per run, no margin (sharp null).

Test outcome: Reject (a leak was detected) or Pass (none within budget), each carrying the same run report.

Evidence is on the log e-value scale: a run starts at 0 and rejects when the mixture's running supremum (resPeakLogW) crosses log(1 / alpha). The per-component peaks say which channel found the evidence. They are diagnostic only: each is a supremum at its own time, and the verdict latches on the mixture.

The largest peak log e-value across the CDF-indicator components — 0 when warmup resolved no cut points. A maximum over resCdf, which keeps the per-cut-point detail.

An actionable observation about a Result, produced by diagnose.

The share of pairs clipped at each of the hedge's three magnitude bounds, carried by HighClipRate. Nested by construction: clipWidest <= clipWide <= clipTight, since |d| > 16c implies |d| > 4c implies |d| > c.

The qualitative shape of a leak, inferred from the per-component peaks of the hedge. Reported by RejectionDriver and available standalone via leakShape.

Interpret a Result: heavy clipping, a low-power Pass (the effect interval is wider than the tight bound), and, on Reject, which channel of the hedge drove the detection. Always in that order, so tooling can match by position.

Identify which channel of the hedge has the largest peak log e-value in a Result, binning the two wider magnitude components together as RareOutlier and the CDF-indicator components together as CdfShift. Returns MixedShape when no single peak exceeds the next-largest by a factor of 1.5.

Only meaningful on a Reject — on a Pass every peak sits near the calibrated floor of 0 and the returned shape is not informative.

Under a margin-mode run (resMargin present) only the gating magnitude components are ranked: the sign and CDF peaks did not drive the verdict there, and a sub-margin systematic routinely inflates them.

Errors thrown by runCT when calibration or configuration fails.

Run a constant-time test. See runCTWith for the phase-by-phase description; this is that driver with the per-pair observer discarded.

Run a constant-time test, handing a Frame to the observer after every main-phase pair. The observer runs outside the timed region and gets the frame lazily, so the no-op observer of runCT costs nothing; a recording one reconstructs the trajectory (see record in Censor.Runner).

1. Warmup: cfgWarmup pairs fix the clip bound c and the CDF cut points (order statistics of the pooled readings, so they carry no class information).
2. Main: each pair runs in random order, and every component's functional of (ta, tb) feeds its e-process. The run halts when the mixture crosses 1 / alpha or the budget runs out. d clipped to [-16c, 16c] also feeds the confidence sequence behind resEffect.

With cfgMargin set, warmup also resolves the absolute margin, and only the magnitude components gate the verdict.

Betting on d rather than on the raw readings lets the bet size scale with the noise, p99(|d|), rather than with the target's runtime: a large gain for slow targets with little jitter.

A per-pair snapshot of the driver's state, delivered to the observer passed to runCTWith after every main-phase pair. All quantities are on the same scale as the corresponding Result fields; recording the stream of frames reconstructs the wealth trajectory without reimplementing the driver.

Run a constant-time test and, if it rejects, qualify the rejection with the A/A and B/B negative controls (attribute). A Pass returns Nothing (no controls needed); a Reject returns Just att reporting whether either control convicted the harness. The controls re-run the test twice, so this costs up to three runs on a rejection.

One value per channel of a split run (runSplitWith): a Result each, or the controls' Attribution each.

runSplitWith with the per-pair observer discarded.

Run a constant-time test under a SplitMeter, handing the cycles channel's Frame to the observer after every main-phase pair.

Every pair is read once, as cycles and wall time, and tested on three channels: cycles, the clock period (wall time per cycle), and wall time. Each channel is a full test as runCTWith describes, with its own clip bound and cut points fixed by the same warmup pairs, and each holds its own type-I error at cfgAlpha. The cycles channel decides when the run stops: on its rejection, or at the budget. That stop is a stopping time for the readings of all three, and the order bit is independent of all three, so the other two channels' guarantees hold where it falls.

The cycles channel answers the constant-time question. The period channel answers whether the clock moved with the class, as it does when the core's frequency follows data-dependent power; wall time answers whether elapsed time moved, by either route. A wall rejection beside a cycles pass, with the period rejecting too, is a frequency effect rather than a code path.

The period reads cleanly only beside a cycles pass: the counted region carries a fixed overhead (the clock reads), so wall time per cycle falls as cycles grow, and a cycles difference registers on the period as well.

The A/A and B/B controls under a SplitMeter: each control is one split run, and each channel's verdict comes from that channel's readings of the two. Only meaningful for a channel that rejected, as for attribute.

Pick a cfgBatch that lifts the per-batch reading well above the meter's resolution: probe a class-A sample at geometrically growing batches until the reading reaches a target magnitude, then scale to it. Only meaningful for targets that recompute on every repetition (see cfgBatch).

b <- calibrateBatch meter hyp
r <- runCT meter cfg { cfgBatch = b } hyp

Consumes one prepare and one class-A draw; build a fresh hypothesis for the run if its sampler stream must start undisturbed. Returns 1 if the meter never resolves the target (the run then throws WarmupZeroDuration). The result is meter-specific; pin cfgBatch to compare meters.

The probe history behind calibrateBatchReport, for when the chosen batch surprises.

calibrateBatch with its CalibReport.

Dispersion of meter readings, in per-batch meter units (the scale of resBound and resEffect). Deterministic meters read an IQR of 0.

Baseline cost of the target: median and IQR of single measurements on fresh class-A draws (each after a prepare), at cfgBatch, in the units of resEffect. Unlike crNoise, which remeasures one applied action (no-ops after the first, for a pure target), every measurement here is genuine work. Give it its own hypothesis instance if the run's sampler stream must start undisturbed.

The A/A control: sampleB replaced by sampleA. The hypothesis is then H_0 by construction, so a Reject indicts the harness (unbalanced samplers, RTS state, order effects) rather than the target. Pair with toBB.

runCT meter cfg (toAA hyp).

The B/B control: sampleA replaced by sampleB, catching asymmetries specific to sampleB that toAA cannot see.

runCT meter cfg (toBB hyp).

The control verdict with both control runs in full, so the evidence can be inspected rather than taken on trust.

The outcome of the A/A and B/B controls. They can convict the harness but not acquit it: each compares a sampler against itself, so an asymmetry only between the samplers (say, one returns a thunk that the target forces while timed) is invisible to both.

Run the A/A and B/B controls. Only meaningful after a Reject: on a symmetric harness both pass whether or not the target leaks.

A measurement device. measure m k act runs act k times back to back and returns one reading for the batch: nanoseconds for wallClock, counted events for a withCounter meter. Each meter owns its inner loop, reading the clock or arming the counter once per batch.

Wall-clock meter: elapsed nanoseconds over the batch.

On Darwin, backed by clock_gettime_nsec_np(CLOCK_UPTIME_RAW), which resolves the hardware tick (~42 ns on Apple Silicon, so sub-microsecond targets need batching; see cfgBatch). Not GHC.Clock.getMonotonicTimeNSec, which macOS quantises to microseconds, putting CDF cut points on quantisation boundaries (see issues/handled/ISSUE2.md). Elsewhere, backed by GHC.Clock.getMonotonicTimeNSec.

A hardware (or, for TaskClock, software) event to count.

With wallClock the counters form a ladder in which each adjacent gap isolates one cause of a class difference: instructions (code path) -> cycles (microarchitectural latency) -> ref-cycles (frequency) -> task-clock (kernel and interrupt time) -> wall (scheduling gaps).

Why a withCounter meter could not be opened.

Acquire a performance-counter Meter for the duration of the callback, then release it. Throws MeterError if the counter cannot be opened.

Counters count user space only, which unprivileged processes may open at kernel.perf_event_paranoid 2 or lower; TaskClock deliberately includes kernel time and needs 1 or lower, failing with OpenFailed 13 otherwise rather than silently degrading to a user-only clock. A counter is bound to the thread that opened it, so the callback runs on one OS thread.

A meter reading two quantities over one execution of the batch: measureSplit m k act returns (cycles, nanoseconds). Wall time is cycles times the clock period, and a secret can move it through either factor: through cycles when the code's execution depends on it, through the period when the core's frequency does (data-dependent power under frequency scaling). Reading both on the same execution tells the two apart.

Acquire a SplitMeter for the duration of the callback, then release it. Throws MeterError if the cycle counter cannot be opened.

The wall clock is read inside the counted region, so both readings cover the batch and the clock reads; the overhead is the same in both classes. As with withCounter, the callback runs on one OS thread.

splitmix64 state threaded through an IORef.

Create a generator from a seed. Equal seeds yield equal streams.

Draw the next Word64 from the generator.

Reset a generator to a seed in place: after reseed g s the generator draws exactly the stream of a fresh mkRng s.

Lets one long-lived generator replay a pinned stream, or adopt a fresh one, without allocating per use — so the two classes of a fix-vs-random sampler can share a single generator object and differ only in the seed value written into it.

Draw n pseudorandom bytes as a strict ByteString.

The result is a fresh, fully-materialised heap value -- no thunks for the meter to pay inside the timed region -- so a sampler can return it directly.