NEREIDS · VENUS neutron-resonance imaging

Analysis whitebox — a living design map

NEREIDS measures isotope areal density and effective temperature, pixel by pixel, from the resonance dips in a transmitted time-of-flight spectrum — 5–200 eV, on VENUS at the SNS.

Built physics-first: one shared forward model, four experiment pipelines derived from it, an API contract specified last i

claim badges: verified hypothesis unverified corrected·r1 — links to the review record detail

Scope. Resolved-resonance region only; transmission imaging in 1D ROI and 2D per-pixel form. The map starts at the recorded events: chopper phase, moderator condition and frame definition enter as run state — as the configuration hash a calibration transfer is keyed on, and as qualification checks (frame overlap, timing epoch) — not as quantities this document re-derives. 3-D tomography is a different inverse problem and is deliberately deferred — the reasons are on the Physics tab.

On this tab

Dotted terms open a definition — hover, tap or tab to one.

How the map was built, left to right — settled means reviewed and folded; draft means awaiting sign-off. (The badges in the header describe individual claims, not phases.)

→ → →

If the physics is what you needread

Pipelines → Physics. Watch the model run first — one pulse, one dip, one map — then read why it is built that way. Neither tab assumes you know the software.

If you are reviewing the contractread

Data → API. What every stage consumes and produces, then the eight operations the code is allowed to expose and the invariants each type must guarantee.

If a word is unfamiliartools

Every dotted-underlined term opens its definition — hover, tap or tab to it. glossary lists all of them; show everything opens every fold so the page reads linearly and Ctrl-F finds it.

How to read this: there is one forward model (Physics). Each pipeline runs it as an instance — calibration solves the instrument; the experiments solve density and temperature. Data is what the model consumes; the API is the contract the code must implement i

Every claim on these tabs carries a status badge, and the whole document has passed one round of cross-family adversarial review (two independent reviews, 40 findings, all adjudicated against re-derived numerics). What each correction changed is in the review record.

New to resonance analysis? Start on Pipelines — the same model running, one pulse to one map — then come back here for why it is built this way.

One deterministic chain — the shared engine every fit runs i

Verified by derivation, in-session numerics and literature (dossier in .research/pipeline-map/); reviewed by a second LLM family; corrections folded and recorded in the review record.

σ(E) total cross-section per isotope

n·d areal density (atoms/barn)

τ₀ peak optical depth of a line

T_eff effective (lattice) temperature

Δ_D Doppler width

Γ natural (total) resonance width

W equivalent width of a dip

L, t₀ flight path, time offset

θ_res, K(t|E) resolution shape, kernel

Φε incident flux × detector efficiency

Q, B exposure normalization, background

S, O sample and open-beam counts

Transformation chain

Six stages turn nuclear parameters into counts. Every fit runs all six, in this order — select one to see it applied.

1Microscopic cross-section

σ_{0} (E)

Total σ per isotope, built coherently from the collision matrix — not a sum of independent terms (that is single-level SLBW) — the sums below run over spin groups J and channels c; resonances interfere inside U_cc:

σ_{tot} = \frac{2 π}{k^{2}} \sum_{J} g_{J} \sum_{c} (1 - Re U_{cc})

Coherence is within each isotope's channels; isotope contributions sum in the exponent. The reconstruction uses each evaluation's declared resolved-resonance formalism (ENDF File 2: RM / MLBW / SLBW as given; an unsupported formalism such as RML (LRF=7) is rejected fail-closed, never substituted erratum·p5) plus File-3 background where present, honouring region-boundary rules. corrected·r1 Interference asymmetry scales with Γn/Γtot; scattering resonances can rise above the baseline. Removal is by total σ, but forward scatter into the detector makes the effective removal < σ_tot — prefer capture-dominated resonances for quantitative n·d.

parameters: E_r, Γn, Γγ, J, π, ℓ · channel spin · g_J · radii (AP, a_c, NAPS) · reduced-width signs · boundary B · distant-level R^ext · abundances · bare mass A

VENUS band ≤ 200 eV ⇒ resolved region only: no URR, no inelastic threshold (Ta-181's is 6.24 keV).

Parameters, by what they belong to

Four families, four treatments. The instrument family is calibrated once and then carried as a correlated prior — never hard-pinned.

Family	Parameters	Treatment	Why
Nuclear	E_r, Γn, Γγ, J, π, ℓ, channel spin, g_J · radii (NAPS) · reduced-width signs · boundary B · distant-level R^ext · abundances · bare mass A · Debye θ_D	fixed reference + covariance	its covariance must propagate into fitted n·d, T — never treated as certain
Instrument	flight path L (+ per-pixel t₀ if warranted) · time offset t₀ · resolution shape θ_res	calibrated once, then a correlated prior / joint fit — never hard-pinned	hard-pinning understates every downstream uncertainty (see the covariance note below)
Sample	areal density (n·d)ᵢ per isotope · effective temperature T_eff · (3D: local density via inversion)	the science — solved jointly	n·d and T are jointly encoded by the curve of growth; fit together, not read off depth or width
Nuisance	normalization Q_s, Q_o · backgrounds B_s ≠ B_o · incident flux Φ(E)	solved per measurement, constrained	they trade off directly against density

The line, live — Doppler · saturation · resolution

One resonance you can heat, thicken and blur. The degeneracies the rest of this tab describes happen here on screen.

T300 K n·d0.50 θ_res1.05 %

the same 4.28 eV Ta-181 line the scene fits — θ_res is the blur width as ΔE/E · drag, or press a preset

Saturation & the curve of growth — width grows with n·d at fixed T; width is not a thermometer

As (n·d)·σ grows the dip deepens toward T≈0 (never exactly zero) and — at fixed temperature — widens. So the width does not encode temperature alone.

Both dips at the same temperature. Raising areal density widens then saturates the dip — so FWHM ⇏ temperature; n·d and T fit jointly. "FWHM gives T without density" holds only optically thin (τ₀ ≲ 0.3) with Γ and resolution known. That threshold applies to width-only inversion; under full forward-model fitting opacity is deterministic and modelable, so τ₀ ~ 1 is usable (see calibration). A saturated core is not pure background — it carries resolution leakage, in-scatter, gammas and frame overlap: a model-assisted constraint, not a free zero.

Degeneracies — why fits are coupled

Coupled pair	Mechanism	Broken by
n·d ⊗ T	jointly encoded by the curve of growth	joint fitting; pinning only under the marginalization criterion below · see it live ↑
θ_res ⊗ T	both broaden the line	calibration determines resolution; carried as a correlated prior · see it live ↑
(L, t₀) ⊗ E_r	energy scale vs resonance position	anchored by the known calibrant
n·d ⊗ Q ⊗ B	depth vs scale vs baseline	background templates + monitor observations + restricted nuisance freedom
n ⊗ d	transmission sees only the areal product	volumetric density needs geometry (3D)

Fitting instances — one model, coupled unknowns

One model, four instances. Only the pattern of what is solved and what is held by a prior changes.

Instance	Nuclear	Instrument	Sample	Nuisance
Calibration	fixed (known calibrant)	SOLVE L, t₀, θ_res	fixed (known ρ, T)	solve
Density	fixed	tight prior ← calibration	SOLVE n·d (+T joint or prior)	solve
Temperature	fixed	tight prior ← calibration	SOLVE T (+n·d joint)	solve
In-situ	fixed	tight prior ← calibration	SOLVE n·d + T (joint)	solve

Instrument carried as a correlated calibration prior or fit jointly — not hard-pinned. Hard-pinning reports C_cond; the honest covariance is

C_{marg} = C_{cond} + J Σ_{cal} J^{T} ⪰ C_{cond}

In a toy MC, hard-pinning shrank the reported 1σ bar until it covered only 20.4% of truth draws instead of the nominal 68.3% (≈4× too small; ~27× near the T–resolution degeneracy) — pinning is the failure. Joint fitting is honest and tighter — sharp resonances re-measure resolution and energy scale.

Calibration instance — how the instrument is determined

Which data feature identifies which parameter — and the degeneracies that fix the order of operations.

Reviewed by a second LLM family and independently re-derived numerically; every number reproduced by both to the quoted digits. Three initially-proposed claims were corrected in that review — details in the review record.

Calibration is the instance where nuclear data and sample state are known and the instrument is solved. Its value comes from which data feature identifies which parameter — and from the degeneracies that fix the order of operations.

Identifiability map

Parameter	Identified from	Requirement / limit
L, t₀	Resonance positions. $t_{r} = t_{0} + L \sqrt{m_{n} / 2 E_{r}}$ — linear in E^−1/2, so intercept = t₀, slope ∝ L.	≥2 well-separated resonances is the algebraic minimum; in practice an overdetermined set. Wide span reduces but never removes the L–t₀ anticorrelation: ρ = −0.81 (2 endpoints, 5–200 eV) → −0.88 (20 lines); narrow 10–40 eV → −0.97; 8–12 eV → −0.998.
θ_res	Excess broadening and asymmetry beyond the known natural Γ ⊗ known Doppler.	Sensitivity is resonance-specific, strongest where the instrumental width ≳ Doppler+natural — at VENUS that is the high-energy end; low-energy Ta lines are weak resolution probes. Known parameters give an intrinsic-shape prior, not an exact shape — nuclear/sample uncertainty must be modelled, never absorbed into θ_res.
nuisances	Open-beam, resonance-free continuum, blocked-beam, charge scaling — plus distinct spectral templates.	Known n·d does not by itself make normalization+background identifiable — it supplies depth information only. Unexplained depth residuals must stay visible as model inadequacy, not be absorbed into background.

Timing degeneracy (exact) — a constant lag is exactly t₀; an E^−1/2 lag is exactly L

Writing the arrival time as $t (E) = t_{0} + L / v (E) + lag (E)$ , the fit spans only ${1, E^{- 1 / 2}}$ . Therefore:

Lag form	Degenerate with	Residual after projection
constant	t₀ — exactly; a wide energy span does not cure it	3×10⁻¹⁶ µs
∝ E^−1/2	L — exactly; an emission delay of this form is a longer flight path	4×10⁻¹⁷ µs
other (e.g. ∝ E⁻¹)	nothing — separable in principle	only what survives projection: 1 µs @10 eV leaves 0.14 µs, which must exceed centroid precision

A fixed-time lag is not a fixed extra path — the implied path varies ~6.3× across 5–200 eV, so the two cannot be conflated.

Consequences. L, t₀ and the kernel location must be fitted jointly under an explicitly stated anchoring convention — not in sequence. The fitted L is an effective flight path that absorbs the emission depth: it is not the surveyed distance, so a discrepancy against the survey is expected and physical, not a validation failure. Because a constant delay is exactly absorbed by t₀, there is no internal check on t₀ — which trigger defines it must be stated externally.

Calibrant & resonance selection — span the band · τ₀ up to ~1 · fit shapes, never centroids

Span the band (lever arm for L vs t₀, and the kernel's energy dependence) · use a range of optical depths, favouring weak-to-moderate τ₀ up to ~1 for the resolution core · keep saturated lines for wing/background diagnostics · isolated lines only (no blends) · fit modelled dip shapes, never raw centroids (an asymmetric kernel plus opacity bias the centroid, which biases both L and t₀). corrected·r1

Why τ₀ ≲ 0.3 was too strict: at τ₀ = 0.3 the dip is only 26% deep — too weak to build a resolution determination on — while opacity broadening at τ₀ = 1 is only +28% and is deterministic under the forward model, i.e. modelable rather than corrupting. Apparent/natural HWHM ratio: 1.08 / 1.28 / 1.91 / 3.66 at τ₀ = 0.3 / 1 / 3 / 10. Do not impose a capture-dominance cut — it discards the most resolution-sensitive lines; model the interference instead.

Reality check. A real Ta foil is already saturated at its strong low-energy lines: at the 4.28 eV resonance, 25 µm → τ₀ ≈ 2.2 (dip 89% deep) and 100 µm → τ₀ ≈ 8.7. "Use only optically-thin resonances" is not satisfiable there — opacity must be modelled, not avoided.

Per-pixel calibration? — geometry no (ΔE/E ≈ 6×10⁻⁷); timing maybe (up to ~10⁻³)

Geometric per-pixel flight path is unnecessary at VENUS. ΔL/L ≈ r²/2L₀²: at L₀ = 25 m, r = 2 cm gives ΔE/E ≈ 6×10⁻⁷; even a 20 cm-square detector's corner gives 3×10⁻⁵ — orders below any stated bias budget. This removes a parameter from the model.

The corollary is not that the field collapses to one calibration: a per-pixel/per-chip t₀ (time-walk, clock distribution, cluster-timing estimator) reaches ΔE/E ≈ 1.4×10⁻³ at 10 eV and 6.3×10⁻³ at 200 eV for a 400 ns offset — at or above resolution. A genuine 1D-ROI-vs-2D calibration disagreement would indicate timing, statistics, or sub-pixel heterogeneity — not geometry.

What calibration must emit — the joint posterior with full covariance, never point values

Not point values. The output object is the joint posterior: parameter vector + full covariance (or samples / a validated parametric form where non-Gaussian), plus the resolution model form and its anchoring convention, the validity energy range, the calibrant assumptions it is conditional on, and any correlations with nuclear data.

Why the full covariance is mandatory: discarding the off-diagonal is wrong in both directions. At ρ = −0.861, the variance of one linear combination is overstated 7.2× while the orthogonal one is understated ~1.9×; at ρ = −0.98 the overstatement reaches 50×. Which error you make depends on which combination the downstream observable is sensitive to — marginal error bars cannot be salvaged.

The calibration process (physics-derived order) — select · predict · jointly fit · emit the posterior · check

Select resonances — span the band, a range of optical depths, isolated lines. This sets the L–t₀ lever arm and decides where θ_res is constrained.
Predict the known cross-section — σ(E; T_eff) from evaluated parameters at the calibrant's known temperature and areal density. No free parameters, but conditional on nuclear data and the calibrant assay, whose uncertainty must be carried.
Jointly fit instrument + nuisances — {L, t₀, θ_res} and the nuisances against modelled dip shapes, under an explicit kernel anchoring convention. Positions and widths are not separable steps (see the degeneracy structure): one joint fit.
Emit the joint posterior — mean + full covariance + model form + anchor + validity range + conditionality; consumed downstream as a correlated prior or in a joint fit, never hard-pinned.
Check self-consistency — residual structure across resonances, and 1D-ROI vs per-pixel agreement. Per-resonance residuals are model-inadequacy evidence and must remain visible, not be absorbed.

Confirmed gaps & residual couplings (physics still to settle — not code)

Bound-atom lattice dynamics vs free-gas T_eff — trades directly against instrumental width, worst below ~20–40 eV where Doppler dominates.
Multiple scattering / accepted in-scatter — fills dips and creates apparent resolution wings; not a scalar background.
Detector dead time, MCP gain depletion, pileup, gamma-flash recovery — distorts exactly the short-TOF high-energy lines that carry the resolution information.
Frame overlap / wraparound — 5–200 eV arrives at 0.13–0.81 ms; slower neutrons from the previous 16.7 ms frame can alias in.
Background needs distinct spectral templates (constant-in-TOF, ~1/E, prompt tail), not a single (B_s, B_o) pair.
t₀'s definition — accelerator trigger vs proton-on-target vs moderator reference vs detector trigger vs chopper phase; these drift independently and a constant offset is exactly degenerate with t₀.
ENDF resonance-parameter covariance — treating nuclear data as exact converts nuclear-data error into a spurious instrument correction.
Dip-location bias under an asymmetric, non-stationary kernel — minimum ≠ centroid ≠ fitted energy once opacity and asymmetry act.
Convolution order — Doppler inside σ before exponentiation; instrument kernel after, on Φ·ε·T, with the open beam propagated separately.
Calibrant assay — Ta-182 activation, Ta-180m, oxide layers, impurities, thickness map: "known n·d" is itself uncertain.
Temperature gradients along the beam — the measured spectrum is a path mixture of exponentials at different T, not a single cross-section at the mean temperature.
Monitor / normalization covariance — Q_s, Q_o are noisy observations sharing monitors; run-to-run drift correlates the arms.
Flux-weighted ROI averaging — the pixel/ROI average is illumination- and energy-weighted and entangled with the detector PSF, not a plain area mean.
Thermal strain, creep, foil bowing (in-situ) — geometry changes that are not isotropic expansion and break the deterministic n·d(T) link.
The design metric itself — identifiability and experimental design rest on the joint Fisher information over {n·d, T, L, t₀, θ_res, backgrounds, nuclear nuisances}; the width-ratio arguments here are the physical intuition behind that computation, not its substitute.

Open calls for the instrument team

The actual VENUS resolution width vs energy — it decides where in the band θ_res is actually constrained.
The calibration foil thickness — it decides the τ₀ regime and whether any line is usable optically thin.
Is the calibrant temperature measured or assumed room temperature?
Per-pixel / per-chip timing calibration — does it exist, and what is its magnitude?
Which trigger defines t₀, and how stable is it run-to-run?

The experiment instances — density · temperature · in-situ

Optical depth governs both separations. Each instance must state what it may treat as known, and prove it.

Optical depth τ₀ governs both separations — thin decouples area↔n·d and width↔T; saturation destroys both, continuously

The unifying result: optical depth τ₀ governs both separations

In the optically thin limit the two observables decouple cleanly: the area of a dip carries n·d free of temperature, because Doppler conserves the cross-section area (d ln W / d ln T = 0.008 at τ₀ ≈ 0.1) — while the width carries T free of n·d, because the Doppler width ∝ √T sets the shape and n·d only scales the depth (the FWHM result above, valid at τ₀ ≲ 0.3).

Saturation destroys both separations — continuously. Corrections begin at O(τ₀); there is no sharp threshold. For a representative fixed-Γ line (Voigt, Γ = 60 meV, Ta-181-like at 10 eV), temperature leaks into the area as d ln W/d ln T = 0.023 → 0.063 → 0.110 at τ₀ ≈ 0.3 → 1 → 3, while opacity broadening inflates the width by +18.6% from τ₀ 0.3 → 1 (Lorentzian shape; a Gaussian gives +12.1%). These numbers are line-specific, not functions of τ₀ alone: a pure conserved-area Gaussian scale family reaches 0.021 → 0.061 → 0.168 → 0.327 over the same range, and the fixed-Γ Voigt is non-monotonic — falling back to 0.092 by τ₀ ≈ 10 as deep saturation moves the equivalent width onto the T-independent Lorentzian wings. τ₀ remains the master design variable; thresholds quoted on it are illustrations for a stated line shape, never universal constants. corrected·r1

method noteMy first numerical test normalised the line profile to unit peak, which silently holds τ₀ fixed instead of n·d and manufactured a spurious T-dependence in the thin limit. The correct test holds n·d fixed with an area-normalised cross-section. Recorded because it is exactly the kind of mistake a plot would have "confirmed".

Density — n·d from the equivalent width · optimal τ₀ ≈ 2.2 · T held only by the marginalization criterion

Density instance — known isotope + T → n·d

Identified from: the equivalent width / integrated dip strength — not the depth alone, since depth trades directly against normalization and background.

Optimal sample thickness. With Poisson counting, Var(τ) = (e^τ+1)/N, so minimising the relative error on τ gives e^τ(τ−2) = 2 ⟹ τ₀ ≈ 2.22. Penalty for being off: 3.6× worse at τ₀ = 0.3, 4.7× at τ₀ = 8. This is an asymptotic, equal-exposure, known-normalization result — backgrounds, monitors and unequal allocation shift it, and at τ₀ = 8 ten expected sample counts already need N ≈ 3×10⁴ open counts/bin. corrected·r1

⚑ A real design tension: the density optimum (τ₀ ≈ 2.2) and the resolution-calibration optimum (τ₀ ≲ 1) differ — the sample and the calibrant genuinely want different thicknesses. Neither optimum is universal (flux, background, binning, kernel), but the tension between them is generic.

May T be pinned? Not by a τ₀ branch alone. Pinning is permitted only when marginalizing over T's external uncertainty shifts the n·d posterior by less than a stated fraction of the total error budget; a T prior is always preferred over a hard pin. The thin regime is why the test passes at small τ₀ (area conservation makes the sensitivity vanish) — the test, not the regime label, is the gate. corrected·r1

degeneracies: n·d ⊗ normalization ⊗ background · n·d ⊗ T (curve of growth) · per-isotope n·d ⊗ each other wherever lines overlap

Temperature — T from the full line shape · the information lives at low E · opacity masquerades as heat

Temperature instance — known n·d → T_eff

Identified from: the full line shape (never the raw FWHM), specifically the Doppler contribution in excess of the pinned instrument kernel.

Where the temperature information lives. The relative Doppler width Δ_D/E ∝ E^−1/2 falls with energy, while a moderator-dominated instrument gives roughly constant relative resolution (see the resolution section) — so the Doppler-to-instrument width ratio improves toward low energy. The width ratio is a proxy, not the decision metric: the canonical selection ranks candidate resonance sets by expected information on T_eff after marginalizing density, kernel, background and nuclear-data uncertainty; under moderator-dominated resolution that ranking lands on the lowest usable lines, which is why the rule of thumb survives. corrected·r1

With realistic moderator-dominated resolution (ΔE/E ≈ 1.05×10⁻² — an assumed moderator-scaling figure; the measured VENUS kernel is an open call) the instrument width equals or exceeds the Doppler width across essentially the whole band, crossing only near the very bottom (≈ 5.2 eV): the ratio is 1.02 at 5 eV, 0.72 at 10 eV, 0.23 at 100 eV. corrected·r1

Consequence — a serious one. Temperature is extracted from a broadening contribution that is sub-dominant over nearly the whole band and at best comparable at its very bottom. That is exactly why the resolution must be pinned from a calibrant and propagated with its covariance: a small θ_res error becomes a large T error. It also independently explains the earlier finding that VENUS suppresses Doppler sensitivity by roughly 4×.

May n·d be pinned? Same rule as pinning T — only under the marginalization criterion; prefer a prior over a pin. The danger it guards: since T ∝ Δ_D², a fractional width error ε maps to (1+ε)²−1 in temperature. An unmodelled τ₀ drift from 0.3 → 1 inflates apparent temperature by +41% ≈ +122 K at 300 K; 1 → 3 gives +124% ≈ +371 K. If the fitted width contains instrument or natural components removed in quadrature, the bias amplifies further. Opacity masquerades as heat. corrected·r1

corrected modelAn earlier draft compared Doppler against a fixed timing uncertainty, producing a "crossover at 22 eV / 7 eV". Unphysical: the dominant moderator term scales as 1/√E, giving constant ΔE/E — the crossover figures are withdrawn; the directional conclusion (favour low-E lines) survives. corrected·r1

degeneracies: T ⊗ θ_res (the reason calibration runs first) · T ⊗ n·d (curve of growth) · T ⊗ energy scale (a stretched axis mimics broadening)

In-situ — shared n·d₀ under the expansion constraint + per-frame T · the sharing declaration is part of the experiment definition

In-situ instance — neither known → n·d + T, tracked

What makes separation possible at all is not the shape of a single line but two independent levers. First, the energy dependence across resonances: temperature acts coherently on every line via Δ_D ∝ √E, while optical depth acts through each line's own σ_peak — typically separable with ≥2 resonances of differing strength spanning energy, though that count is a rule of thumb, neither necessary nor sufficient; the identifiability screen, not the line count, is the gate. corrected·r1 Second, the global fit across the thermal series: the reference n·d₀ is shared across frames (absent composition change) while T varies per frame — a shared-parameter fit with a large identifiability gain over frame-by-frame fitting.

⚑ Thermal expansion is a first-class term, not a correction. Per-frame areal density follows n·dⱼ = n·d₀·exp(−2∫α(T)dT); with constant α over 1000 K that is −1.25% (Ta), −0.89% (W), −2.78% (Au). Left out of the model it masquerades as mass loss or composition change — precisely the quantity an in-situ experiment claims to measure. The free-isotropic law breaks under fixtures (anisotropic strain), phase changes, or near melting (Au: 1337 K) — then an integrated strain model with uncertainty replaces it. corrected·r1

Composition evolution constrains what may be shared: if composition genuinely changes (phase change, diffusion), per-isotope n·d cannot be shared across the series. The model must declare which parameters are global and which are per-frame — that declaration is part of the experiment definition, not an implementation choice.

Statistics & inference — which likelihood, and what it costs

Counts is the canonical domain. Transmission is a diagnostic that has to earn its place, test by test.

Domain	Objective	Admissible when
Transmission	Gaussian χ² on T(E), σ_T propagated from counting statistics. Flux and background divided out during reduction.	Ratio bias ≈ 1/λ_o: 1.02% at 100 open counts/bin, <1% only from ≥103 — a rule of thumb, not a guarantee i corrected·r1
Counts	Poisson / KL deviance with Φ(E) and background inside the model; sample and open beam predicted separately.	Always. Exact at any count level; the only option in the low-count regime VENUS actually produces. Goodness of fit does not read directly at low counts: D/(n−k) → 1 only asymptotically (per-bin E[D] ≈ 1.15 at λ=1, 1.02 at λ=10) — calibrate the deviance reference by parametric bootstrap / posterior predictive. corrected·r1

Two silent traps — Neyman χ² biases low; per-pixel UQ understates ~3–4× (a VENUS observation, cause unattributed)

Two statistical traps that silently bias results

Neyman χ² bias. Taking the per-bin variance from the data (σ² = N_observed) generally biases fitted amplitudes low — deep bins get over-weighted. The sign is not universal once backgrounds and nonlinear shape parameters enter: the Poisson likelihood is the defensible default; Pearson χ² (variance from the model) is the minimum.

Per-pixel UQ underestimates. The ~3–4× understatement of per-superpixel scatter is an empirical VENUS observation, not a general statistical fact — under regular high-count conditions the inverse-Hessian covariance is asymptotically correct, so a shortfall this size points at model mismatch, ignored calibration covariance, or spatial correlation cause unattributed. Reserve MCMC for ROIs / a global co-fit; report a χ²-scaled covariance elsewhere with the scaling disclosed. corrected·r1

The joint-fit contract. The instrument enters as a correlated prior (or is fitted jointly), never hard-pinned; the reported covariance is C_marg = C_cond + JΣ_calJ^T. Nuclear-data covariance propagates the same way — otherwise evaluation error is silently reclassified as a physical result.

The spatial dimension — 1D ROI · 2D per-pixel · 3D

1D and 2D disagree by a predictable, signed amount — which turns a vague consistency hope into a quantitative test.

1D-ROI underestimates n·d by ≈ −Var(τ)/2 — predictable and signed; the 1D↔2D offset is a QC number, not a hope

⚑ 1D-ROI and 2D-per-pixel disagree by a predictable, signed amount

Because exp is convex, Jensen's inequality gives ⟨exp(−τ)⟩ ≥ exp(−⟨τ⟩). Fitting an aggregated ROI with a uniform model therefore returns τ_fit ≈ ⟨τ⟩ − Var(τ)/2 — so 1D-ROI systematically underestimates areal density whenever the ROI is heterogeneous. Verified numerically (prediction vs Monte-Carlo agree): at ⟨τ⟩ = 2, a thickness spread of 10% → −1.0%, 20% → −4.1%, 30% → −9.0% in n·d. −Var(τ)/2 is the leading cumulant only, and the exact offset is distribution-dependent: at 30% spread it ranges −8.5% (two-point) to −8.7% (uniform) to −9.0% (Gaussian). corrected·r1

Consequence for the never-tested 1D↔2D check: the offset has a predicted value — exactly −ln⟨e^(−τ)⟩ − ⟨τ⟩ computed from the fitted 2D field (all cumulants, with illumination weighting), −Var(τ)/2 to leading order. erratum·p5 That converts a vague consistency hope into a quantitative test. Counts may legitimately be summed over an ROI (Poisson sums are Poisson), but the ROI forward model must then be ⟨exp(−τ)⟩, not exp(−⟨τ⟩).

Regularization must be physically justified — edge-preserving where real boundaries exist; never cosmetic smoothing

The estimator axis, and when regularization is physically justified

independent per-pixel → adaptive binning → spatial regularization → joint spatial-spectral inversion. Regularization is justified when: (a) the underlying field really is smooth or piecewise-smooth on the pixel/PSF scale — use edge-preserving (TV-like) priors where the sample has genuine boundaries, not Gaussian smoothing; and (b) the detector PSF already correlates neighbouring pixels, so independent per-pixel fitting is statistically inefficient, not merely unsmoothed. It is not justified as cosmetic noise suppression: regularization trades variance for bias, so the reported uncertainty must account for the effective degrees of freedom it consumes.

3D factorises only at uniform T — otherwise reconstruction and spectral fitting are one joint inverse problem

⚑ Why 3D is a different problem — and when it factorises

Each measurement is a line integral: τ(E, ray) = Σᵢ ∫ nᵢ(x) σᵢ(E; T(x)) dl.

With uniform temperature it factorises: σ leaves the integral, τ(E, ray) is linear in the line integral of n, and the correct order is to reconstruct the linear quantity τ tomographically, then fit per voxel. With spatially varying temperature it does not: σ depends on position, reconstruction and spectral fitting must be solved jointly — in-situ 3D (thermal gradients) is fundamentally harder than density-only 3D.

Reconstruction operates on line integrals — under two conditions. (i) The linearity of τ = −ln T holds for the model-domain transmission: once expected counts are convolved in TOF, −ln(counts ratio) per energy bin is not a linear Radon sinogram — deconvolve, or fit a count-domain forward model. (ii) Back-projecting per-ray fitted values is legitimate iff the fitted quantity is a line integral of a common scalar density (uniform or known T); it is invalid when the ray fit mixes temperature, composition, resolution or opacity into something non-additive along the ray. corrected·r1

Results, QC & uncertainty — where every instance converges

Every instance ends in the same product family. A correlated systematic does not average down, however many pixels you bin.

Every experiment terminates in the same product family, so this is shared scaffolding, not per-experiment reporting: value map · 1σ uncertainty map · goodness-of-fit map · convergence/trust mask · residual cube.

A correlated systematic does not average down — the calibration term sets a floor binning cannot remove

⚑ A correlated systematic does not average down

The calibration-covariance contribution is spatially correlated — every pixel shares the one calibration draw — so the variance of an N-pixel mean plateaus instead of falling as 1/N: σ²_stat/N + a floor ḡᵀΣ_cal ḡ, where ḡ is the illumination-weighted mean of the per-pixel calibration sensitivities J_i. Binning cannot beat the second term. In the fully common-mode limit — all pixels sharing one sensitivity direction — the floor equals the per-pixel systematic: with 5% per-pixel statistics and a 1% correlated floor, N = 100 → 1.12%, N = 10⁴ → 1.001%, N = 10⁵ → 1.000%. Reporting a spatial average with a 1/√N error bar is wrong by construction. Sharing the parameter vector does not, however, force pairwise ρ = 1: ρ_ij = J_iΣ_cal J_jᵀ / √((J_iΣ_cal J_iᵀ)(J_jΣ_cal J_jᵀ)), which reaches one only when the sensitivity directions are proportional — pixels dominated by different resonances sit well below (ρ ≈ 0.58 for 1 eV- vs 100 eV-dominated pixels under a {L, t₀} posterior) — so ROI and map aggregates must use the full J_iΣ_cal J_jᵀ block, never a ρ = 1 shortcut. Systematics with finite spatial correlation soften to σ²_sys(1+(N−1)ρ)/N and partially average down. corrected·r1 erratum·p5

Consistency tests — each with a predicted value, not a hope

Test	Predicted value	A departure means
1D ↔ 2D	offset = −ln⟨e^(−τ)⟩ − ⟨τ⟩ from the fitted 2D field (−Var(τ)/2 to leading order) — not zero	agreement at zero itself indicates a homogeneous ROI or a masked bug
transmission ↔ counts	agreement within ratio-bias (≈1/λ_o) + resolution-order bias	a larger disagreement localises to flux or background modelling
deviance	its calibrated (bootstrap / posterior-predictive) reference	systematic departure = model inadequacy, not noise
per-resonance residuals	flat, line by line	a model wrong in one resonance but averaged away globally is the failure mode this catches

ruleModel adequacy must stay visible. Nuisance flexibility has to be restricted enough that unexplained structure cannot be absorbed into normalization or background.

If the background can reproduce any residual, the fit can never report that the physics is wrong — the single most dangerous property an analysis can have.

The resolution function — what it physically is

Moderator-dominated, so relative resolution is roughly constant across the band — and the emission delay is extra flight path.

This section was missing from the first pass — resolution appeared only as a chain step and a calibration target, a black box inside a whitebox. Closing that gap produced the corrected temperature model above.

The moderator emission delay is exactly extra flight path — why fitted L ≠ surveyed L (≈13 cm at 3 µs)

⚑ The moderator emission delay is an extra flight path

A neutron detected at energy E was born fast and had to slow down inside the moderator before leaking out. The slowing-down time to reach E scales as τ_mod = C/√E. Converting to an equivalent path: ΔL = v·τ_mod = √(2E/m)·C/√E = C√(2/m) — energy-independent.

A 1/√E emission delay is therefore exactly a constant flight-path offset. This is the physical origin of the exact L-degeneracy in the calibration section, and it is large: a 3 µs delay at 10 eV corresponds to 13.1 cm of apparent extra path — 0.53% of a 25 m flight path (1 µs → 4.4 cm; 10 µs → 43.7 cm). Since a 0.3% L error is already catastrophic for the fit, the moderator delay is the dominant reason the fitted L must differ from the surveyed distance — and why it is meaningless to "check" one against the other.

Components, and how each scales

Independent timing contributions convolve (widths add in quadrature only where each is Gaussian — the moderator term is not). With ΔE/E = 2Δt/t and t ∝ E^−1/2:

Component	Δt scaling	ΔE/E scaling	Note
Moderator emission	∝ 1/√E	constant	Dominant across 5–200 eV. Asymmetric (slowing-down rise + storage decay) — what Ikeda–Carpenter models.
Fixed timing (binning, electronics)	constant	∝ √E	Grows with energy; overtakes the moderator only well above the band for plausible values.
Geometric ΔL (moderator depth, divergence)	— (path, not time)	constant	A flat floor, 2ΔL/L. Off-axis pixel geometry is negligible (≈6×10⁻⁷).
Detector conversion depth / time-walk	constant, small	∝ √E, small	Per-pixel; the cluster-timing estimator matters more than the depth.
Sample thickness	none	none	For unscattered neutrons the total source-to-detector path is unchanged — a thick sample does not broaden TOF; it enters only via scattering.

Net shape of the resolution curve: moderator-dominated ⟹ ΔE/E approximately constant across 5–200 eV (≈1.05×10⁻² for a 3 µs @10 eV moderator), with a slow √E rise only at higher energy. This is the fact that corrected the temperature model: relative resolution does not grow across the band.

Admissible kernels are non-negative, normalised, causal, anchored — a Gaussian fails causality; Ikeda–Carpenter is causal by construction

Constraints any admissible kernel must satisfy — and why a Gaussian fails

An admissible kernel is non-negative (a probability density over arrival times), normalised (∫K dt = 1 — it redistributes neutrons in time, never creates or destroys them), causal (K = 0 before emission: nothing arrives before it left), and position-anchored (one convention, mode or mean at zero, must be fixed, or the kernel's location fights t₀ and L).

A Gaussian violates causality: it has support at negative times. The leaked fraction is Φ(−μ/σ) — 15.9% at μ = σ, 2.3% at 2σ, 0.14% at 3σ. A Gaussian is only defensible where the mean delay exceeds ~3–4σ. The moderator term is both wide and skewed — precisely the regime where a symmetric Gaussian is least valid. Ikeda–Carpenter is causal by construction (its t²e^(−αt) slowing-down term vanishes at t = 0) — the physics reason to prefer it over a Gaussian, not merely a better fit.

Ikeda–Carpenter parameters, physically: α = slowing-down decay rate (energy-dependent, faster neutrons escape sooner); β = storage/thermal decay rate; R = the fraction emitted through the storage channel. A tabulated (UDR) kernel is the alternative — it captures real geometry, filters and collimation no analytic form knows, but it is only as good as its sampling and does not extrapolate. Physics fixes the family (positive, normalised, causal, moderator-skewed); the choice within it is a modelling decision.

Fit shapes, never centroids — only centroid drift outside span{1, E^−1/2} tilts the fit

Why asymmetry biases the energy scale — "fit shapes, not centroids" is physics

The moderator tail runs to late times, displacing every observed dip centroid; left uncorrected, a mean-vs-mode offset d shifts apparent energy by −2d/t: for d = 2 µs that is −0.50% at 5 eV, −3.13% at 200 eV. Inside the calibration fit, however, these shifts do not tilt anything by themselves: a constant offset is absorbed exactly into t₀ (verified: refit residual 10⁻¹³ µs, L untouched) and an E^−1/2 component exactly into L — only the part of the kernel's centroid drift outside span{1, E^−1/2} survives projection and genuinely distorts the fit. corrected·r1

Why "fit modelled dip shapes, never raw centroids" still stands: (i) the Ikeda–Carpenter asymmetry drifts with energy in exactly such a non-absorbable way; (ii) opacity displaces each line's centroid by a depth-dependent amount — not a timing function at all, so it corrupts a centroid fit line-by-line; (iii) silently absorbed offsets redefine L and t₀ away from the declared kernel anchor, breaking the calibration transfer to sample fits with different line sets. Shape fitting models all three by construction. A centroid scheme is self-consistent only if the kernel mean is the declared anchor, used identically everywhere — fragile, and still opacity-biased.

One fitting engine, four modes. Every parameter is fitted jointly — a mode is a prior pattern i. Pick a mode; the scene below runs it live, on the same Ta-181 physics the Physics tab specifies.

The interactive model follows the document's forward-model structure (resonances → Doppler → Beer-Lambert → E(t; L, t₀) inside the likelihood → constant-relative-width blur as the demo reduction of K(t|E)) with demo-reduced line shapes — seven fixed Ta-181 lines as independent, area-conserving Gaussian profiles; the real σ(E) is built coherently from the collision matrix with interference and Lorentzian wings (stage 1), which no on-page demo number represents — fitted by 5-parameter Gauss-Newton with the mode's prior pattern; the engineering contract for each stage is in the developer layer below. Design and content history: review record.

you bring →the fit solves →you receive tight priors

tight priors ← calibration posterior

The same five stops, in plain words

The full walkthrough — the five numbered stops, in plain words

1 Every pulse releases one burst of neutrons. Over the 25 m flight, time sorts them by energy — fast ones land early, slow ones late — so arrival time doubles as an energy axis. On the way through the sample, its nuclei absorb neutrons at their resonance energies. Each surviving neutron is one count at (pixel, time). Before any run is used it is checked; incomplete or faulty runs stop here.

2 Adding up thousands of pulses gives each pixel a spectrum: a smooth curve with dark notches at the resonance energies. The notches are the signal — how much beam they remove says how much material is in the way (areal density n·d), and their shape says how hot it is (thermal motion broadens them). The pale curve is the reference beam measured with no sample.

3 The analysis never works backward from the data. It predicts the full spectrum from physics — resonances, thermal broadening at temperature T, attenuation by n·d, the flight-time relation E(t; L, t₀), the instrument’s timing blur — and compares prediction with measurement, count by count. The strip under the spectrum shows what is left over; flat noise means the physics accounts for everything.

4 Fitting adjusts all five parameters together — nothing is pinned, and the mode decides only the prior pattern. In the experiment modes the science parameters run free while the instrument three (flight path L, time offset t₀, timing-blur shape θ_res) carry tight priors taken from the calibration posterior — their uncertainty is counted in the result without adding freedom the data cannot support. In calibration mode the pattern flips: the reference foil’s n·d and T are the tightly-known ones, and the fit solves the instrument — try it; the fitted L lands ≈8 cm above the surveyed 25 m, which is the moderator emission depth, expected and physical. The answer is always the joint posterior — the ellipse — whose tilt states honestly how much the two headline parameters mimic each other.

5 The same fit runs in every pixel, and that field of fits is the deliverable: value map, uncertainty map, per-pixel residuals. Click any pixel to load its spectrum — the whole pipeline is that one loop, repeated. Spatially a mode runs per pixel (as here) or on a summed region of interest; 3-D tomography is a different inverse problem and is deferred — see the Physics tab. Calibration instead ends in one product: the instrument posterior every other mode consumes.

The four modes, side by side — the reference table

Run as	You bring	The fit solves	Tight prior (uncertainty counted)	You receive
Calibration	a reference foil whose n·d and T are tightly known	L, t₀, θ_res	the foil’s n·d, T · nuclear data (+ covariance)	the instrument posterior every other run consumes
Density	known isotope + temperature	n·d per pixel	L, t₀, θ_res (calibration posterior) · T	n·d map + uncertainty + residuals
Temperature	known areal density	T_eff per pixel	L, t₀, θ_res · n·d	temperature map + uncertainty + residuals
In-situ	a time series, neither known	shared n·d₀ + per-frame T	L, t₀, θ_res · the expansion constraint n·d(T)	n·d and T trajectories with joint uncertainty

Every other mode consumes the calibration posterior as its tight prior. How tight a prior may be — and when a parameter may be treated as effectively fixed — is governed per case by the marginalization criterion on the Physics tab.

The engineering contract, stage by stage

The demonstration above is the pipeline's meaning; the contract below is its law — every normative rule the round-1 review settled, with corrected·r1 links into the record. Collapsed because it is reference, not reading.

1 · Qualification — fail-closed, before any reduction corrected·r1

A corrupt or truncated run fails before it can meet a valid open beam: pulse IDs, live time, proton charge and beam monitors, chopper state, moderator condition, detector HV/thresholds, geometry, trigger and timing epochs, run completeness, sample motion, frame overlap, metadata consistency are all checked here. Dead time, pile-up, gain depletion and nonlinearity are corrected using the detector-health characterization, with propagated uncertainty, and bounded by a hard rate-validity limit — sample and open rates differ, so these effects never cancel in a ratio, and uncorrected losses invalidate the Poisson likelihood itself. corrected·r1 Dedicated background measurements (blocked-beam runs, black-resonance notch filters) are first-class inputs constraining the additive components per spectral template (constant-in-TOF, ~1/E, prompt tail). corrected·r1 The detector-health mask comes from independent diagnostics — hot, noisy, timing-shifted, cross-talk and saturated pixels — never from the science counts being fitted, and never a low-count screen. corrected·r1

2 · Reduction — one convention, native TOF preserved corrected·r1

Reduction hard-excludes only the sample ∪ open-beam unhealthy-pixel union (masking by counts would bias the Poisson statistics it feeds). Native-TOF bin edges are recorded per run and never re-binned downstream; per-bin width Δt is carried; live time and monitor counts attach as observations with uncertainties — Q_s, Q_o are never exact divisors. corrected·r1 Reduction never rebins to energy: E(t; L, t₀) is evaluated inside every likelihood evaluation at the current calibration parameters — that is what lets L and t₀ float with their covariance; a baked axis would silently pin them and re-interpolate counts. A derived energy axis is a display product of stage 5 only. No per-pixel geometric L (≈6×10⁻⁷ centre, 3×10⁻⁵ corner — orders below any stated budget); per-pixel t₀ only from independent timing calibration. The domain decision lives here: counts is the canonical arm; transmission T=(S/Q_s)/(O/Q_o) is a community-convention diagnostic formed only if every validity test passes (open-count bias, black cores, shared-open-beam covariance, background and monitor uncertainty, and the forward-simulated resolution-order bound) — never the canonical fit domain. corrected·r1 The output carries the provenance block — the Data tab’s five groups as known at reduction, later-registered conditioning identities extending the block per the Data-tab rule — including bin edges, masks, live-time and monitor observations, calibration-posterior identity, nuclear library/version, component versions, configuration hashes and seeds; background and calibrant runs reduce through this same path. corrected·r1

3 · Forward model + likelihood — one invocation corrected·r1

σ(E; T_eff) is assembled per isotope with the evaluation's declared resolved-resonance formalism (ENDF File 2: RM / MLBW / SLBW as given — never an assumed Reich-Moore; an evaluation declaring a formalism outside the supported set, e.g. RML (LRF=7), is rejected fail-closed, never silently substituted erratum·p5), the full parameter set, File-3 background where present, boundary rules honoured; isotope contributions sum in the exponent; Doppler broadening at T_eff with the lattice-model family declared. Nuclear covariance is carried under an explicit failure policy: availability checked, non-PSD repaired and disclosed, missing covariance → declared default or rejection, one shared uncertainty across all fits, model discrepancy its own term. corrected·r1 The kernel K(t|E) acts on expected counts (Φ·ε·T), position-anchored; the measured background templates enter as additive likelihood components (distinct from the ENDF File-3 smooth cross-section term); every non-Beer-Lambert contribution (container attenuation, scatter-in, multiple scattering, PSF mixing, self-shielding) is modelled, bounded with a stated magnitude, or measured. corrected·r1 Objectives: Poisson/KL deviance with a calibrated GOF reference (D/(n−k)→1 only asymptotically; per-bin E[D] ≈ 1.15 at λ=1) corrected·r1; the transmission diagnostic uses Pearson-weighted Gaussian χ², never Neyman. The identifiability screen is layered — design time, per configuration, per pixel class on the actual data, post-fit — fails loudly, and never converts non-identifiability into a hard pin: pinning is permitted only under the marginalization criterion. corrected·r1 corrected·r1

4 · Fit instances — four prior patterns, one engine corrected·r1

Calibration selects isolated resonances spanning the band at a range of optical depths, reduces through the shared axis-free path and starts the fit at the surveyed L and nominal t₀, predicts the known σ(E; T_eff) with ENDF covariance carried, and jointly fits {L, t₀, θ_res} + nuisances against modelled dip shapes under an explicit kernel anchor — never centroids, never a sequential position/width split. It emits (θ̂, Σ_cal) with off-diagonals — or samples where non-Gaussian — plus kernel form, anchor, validity range and its full conditioning set. corrected·r1 Transfer is enforced by a compatibility gate (configuration hashes: moderator condition, thresholds/HV, rate regime, chopper, geometry, epoch; drift bounded by bracketing references and control charts; on mismatch reject or attach an explicit drift model), and validated by holdout — held-out resonances, thicknesses or repeat runs are predicted, not fitted. corrected·r1 Density frees (n·d)ᵢ + nuisances with T under a prior (pinned only by the marginalization criterion; τ₀ ≈ 2.2 is the idealized thickness optimum). Temperature frees T_eff with n·d under a prior; resonance sets are ranked by expected information after marginalization corrected·r1; the lattice-model family is declared and its uncertainty propagated corrected·r1. In-situ declares its sharing structure as part of the experiment definition — global reference n·d₀ under the integrated expansion constraint n·dⱼ = n·d₀·exp(−2∫α(T)dT) corrected·r1, per-frame T, and the time-dependent instrument and beam terms (a global fit does not protect against drift it does not model) corrected·r1 — then fits the series jointly. Every experiment instance also declares its spatial estimator (independent per-pixel → binning → regularization → joint inversion) and ROI geometry as part of its definition.

5 · Results / QC — every instance terminates here corrected·r1

The product family: value map, uncertainty map (total marginal covariance authoritative; the statistical/systematic split is a documented decomposition convention; credible intervals where posteriors are bounded or skewed corrected·r1), calibrated GOF/deviance map, trust mask, and residual cube in signed-deviance / randomized-quantile form. Derived display products — the energy axis at the calibration posterior and the transmission spectrum — are produced here for display and cross-checks only, never the fit domain. Consistency tests each carry a predicted value: 1D↔2D offset = ⟨e^(−τ)⟩ from the 2D field (not zero); transmission↔counts within ratio-bias + resolution-order bias; deviance against its calibrated reference; per-resonance residuals per line. Nuisance flexibility is restricted so unexplained structure cannot be absorbed. Every failure class has a predefined outcome — fail-closed or a declared degraded mode: missing open beam / background / monitor data, partial frames, dead-time violation, calibration incompatibility, missing or non-PSD covariance, kernel extrapolation, a counts fit requested without the separate-arm detector response, unsupported detector background, acquisition-window kernel loss, non-identifiability, non-convergence. amended·p5

What exists between the instrument and a result — eleven data classes: who makes each, who consumes it i

Taxonomy finalized against the round-1-reviewed pipeline contract; completeness swept twice — a mechanical noun map, then a round-2 adversarial cross-read (15 findings: homeless items + two contract contradictions, all folded — review record). Calibrant evaluation below was Phase-1 work, adversarially reviewed.

externalacquisition · DAQ · diagnostics · library · assay · the scientist

1 Qualificationfail-closed

2 Reductionone convention

3 Model + likelihoodbuilds σ(E) and the likelihood

— consumes only

4a Calibrationits own run, before any experiment

4 Fits · 5 Results/QCwhere every instance ends

Each class is produced by exactly one stage and consumed downstream. Select one.

Provenance — what every result must carry

Five groups. A result must be reproducible bit-for-bit from this block alone, and a calibration transfer rejectable without human judgement.

Group	Fields	What it protects
Identity	nuclear library + version + file hashes · software component versions · kernel form + anchor identifier	that two results used the same physics
Configuration	one hash over moderator condition · chopper · HV/thresholds · rate regime · geometry · trigger epoch	the calibration transfer — mismatch is mechanically rejectable (the compatibility gate)
Acquisition	run IDs · pulse-quality records · live time · monitor streams · timestamps (thermal lag, in-situ)	that the counts mean what the likelihood assumes
Conditioning	calibration-posterior identity + its own conditioning chain (a cold-start flag for the calibration run’s own reduction, which precedes any posterior) · calibrant-assay identity · background-run identities · covariance-repair disclosures · experiment-definition identity · compatibility-gate verdict identity · marginalization-criterion evaluation identities	that priors and templates trace to real measurements
Statistical	random seeds · bootstrap / posterior-predictive settings of the GOF reference	bit-for-bit reproducibility of every stochastic step

The rule: a result must be reproducible bit-for-bit from its provenance block alone, and a calibration transfer must be rejectable on configuration mismatch without human judgement. The block is one shared object: reduction attaches it to every reduced spectrum; results inherit and extend it.

Calibrant foil selection — Ta / W / Au / Ag

Ranked against the calibrant's two jobs — A: the energy scale (L, t₀) · B: the resolution function θ_res(E) i

A calibrant serves two distinct jobs, and they favour different foils — which is why "cleanest resonance" and "most preferred" need not be the same material.

Job A — the energy scale (L, t₀) — wants many accurately-known, well-separated resonance positions spanning the widest E^−1/2 range; multi-isotope is harmless, since a position is a position. Job B — the resolution function θ_res(E) — wants the instrumental width not swamped by intrinsic Doppler + natural width, sampled across the band, at unsaturated optical depth, on isolated lines; that favours heavy nuclei (Δ_D ∝ 1/√A).

Wrank 1

Best kernel coverage — several sparse ladders, and its activation decays in a day.

the full assessment

best for Resolution function. Best kernel coverage — largest E^−1/2 sampling gap only 0.132. Strong low-band lines at 4.1 & 7.7 eV verified.

weakest for Multi-isotope (W-182/183/184/186) → more nuclear-data bookkeeping; harmless for Job A.

practical Refractory, robust, cheap, often already in-beam. Activation W-187 ≈ 24 h — decays away in days t½ unverified.

Tarank 2

The verified flight-path standard; one dense ladder that blends above ~50–100 eV.

the full assessment

best for Verified flight-path standard verified. Effectively mononuclidic (Ta-181 = 99.988%); dense ladder gives many lines across the band.

weakest for I = 7/2 → many spin groups → ladder crowds/blends above ~50–100 eV.

practical Refractory. Activation Ta-182 ≈ 114 d — a real handling nuisance vs W t½ unverified.

Aurank 3

The cleanest energy-scale anchor, with the worst kernel-coverage gap.

the full assessment

best for Energy-scale anchor. Best lever arm (ρ = −0.79). Mononuclidic (100%), inert, international standard → best-known parameters. 4.906 eV line strongly capture-dominated (Γ = 137.5 meV, Γn = 15.0 meV ⇒ Γ_γ ≈ 122 meV) — hence its exceptional cleanliness verified.

weakest for Kernel coverage — worst sampling gap 0.305 (~2× the others), driven by a large 4.9 → ~46.7 eV hole gap unverified. Soft, expensive.

practical Chemically inert (never oxidises); Au-198 ≈ 2.7 d, decays fast.

Agrank 4

A thermometry reference rather than a calibrant — lightest, so Doppler swamps the instrument width.

the full assessment

best for A known-temperature thermometry reference (Ag-109 5.19 eV) — a different job entirely.

weakest for The only quantitative physics penalty: lightest ⇒ Doppler width ~35% larger, so the instrumental share of the observed width falls to 27% vs ~40% for the heavies. Two comparable isotopes (51.8 / 48.2%) interleave ladders.

practical Tarnishes. Long-lived activation (Ag-110m ≈ 250 d, Ag-108m ≈ 438 y) t½ unverified.

Recommendation — two foils, each in two thicknesses

W (or Ta) primary for θ_res(E) coverage · Au as the independent energy-scale anchor i · thin + thick of each verified i · fit modelled dip shapes, never raw centroids verified i

Why W is preferred — physics-grounded rationale (adopted)

The rationale rests on solid nuclear physics: the even-even isotopes W-182/184/186 have spin I = 0, so each contributes only a single s-wave spin group (J = ½) and therefore a sparse, widely-spaced ladder. Several sparse ladders superimposed give band coverage with isolated, non-blended lines — whereas one dense ladder (Ta, I = 7/2) crowds and blends. Combined with refractory robustness and short-lived activation, this explains the preference. verified as physics · unverified as attribution — no published source was found stating this as the reason practitioners choose W.

Adopted as the working justification by project decision. What this is and is not: the underlying nuclear physics is certain (even-even nuclei always have I = 0 ground state, hence a single s-wave spin group), but no published source was found that states this as the reason practitioners choose W. It is a derived explanation, not a cited one.

Corroborating but not decisive: a dedicated study exists on Neutron Doppler broadening studies of tantalum and tungsten metal — Ta and W are the canonical pair for this class of work.

Open items on the foil choice

Does Au-197 really have a 4.9 → ~46.7 eV gap? The Au ranking depends on it more than on anything else. The GELINA study of ¹⁹⁷Au+n below 200 eV is the authoritative source.
Activation half-lives — quoted from general knowledge, not verified in session; they carry real operational weight (Ta-182 114 d vs W-187 24 h).
~~The actual reason for W's preference~~ — closed by project decision: the physics-grounded rationale above is adopted; no literature attribution is being sought.

Sources — NRTA feasibility study (flight-path calibration by linear fit; Ta as standard) · Compact D-T NRTA (W 4.1/7.7 eV lines) · Au-197 4.90 eV parameters · Resonance parameters for ¹⁹⁷Au+n below 200 eV (GELINA) · Doppler broadening studies of Ta and W metal · Black-and-white filter method for background · Two-thickness resolution method

How the pipeline is driven — the design, its reasoning, and the exact contract text. Pick a mode: the numbered sequence is the API i

The public surface — eight operations, two gates

The whole public surface: five operations on the main line, two gates that must return a verdict before the next step may run, and calibration feeding its posterior in by identity. Everything below elaborates this picture.

How you run it — the call sequence per mode

The design decisions — what was weighed, what was chosen, why

Each decision states the requirements that pulled on it, the alternatives that were rejected, and what the choice costs.

D1 · The unit of composition is a Campaign — the append-only registry recording one measurement campaign, with the eight operations on it

Pulling requirements: priors by registered identity need a resolver; gate verdicts bind triples and the binding must be recorded; provenance chains append across stages; in-situ fits a declared series; stages are fail-closed; and the scientists must see the gates fire. Rejected: free functions (identity resolution, verdict pairing and provenance land on the caller — exactly the misuse surface the adversarial review exploited; nothing enforces order) and a black-box executor (hides the gates this whitebox exists to expose). Consequence: operations return typed handles, consumes are by-handle, and a handle exists only once its object is registered — so the legal call order is the handle dependency graph, enforced by types, not by documentation. The calibration cold start becomes a second, provenance-flagged Reduce constructor instead of a footnote.

D2 · One fit engine; a mode is data (a PriorPattern value inside the definition)

The physics forced one model with four prior patterns; the API makes that literal: fit(campaign, screened definition), the mode inside the definition. Adding a mode is adding data, not surface. Rejected: four mode functions — surface growth, duplicated logic, per-mode drift; the “death by features” failure this document exists to prevent.

D3 · Identity is registry-resolved — handles, never passed values, never a global singleton

Content-addressed ids assigned by their producers; a handle is (id, typed view) resolved by its campaign. Rejected: raw value passing (re-opens the pin-by-proxy and definition-swap attacks; provenance by hand) and a global registry (breaks multi-campaign concurrency and test isolation — campaigns are values).

D4 · Gates are type-level where possible, runtime where the check needs data

Gate outputs are the only constructors of GatedPosterior and ScreenedDefinition — skipping a gate is unrepresentable at compile time. Configuration/band matching is data-dependent and stays a runtime identity check at Fit. Rejected: runtime-only (bypassable — the attack surface) and purely type-level (band matching needs runtime data).

D5 · Failures are values in the field; stages fail closed; registry appends are atomic

A 3-pixel non-convergence must not kill a 262 144-pixel run: per-pixel failure is data (trust mask + failure verdicts). Stage-level failure is a typed fail-closed return, and a failed operation registers nothing. Rejected: exceptions across the boundary (hostile to the thin Python wrapper; partial-state hazards) and silent NaN maps (adequacy must stay visible — the document’s most defended rule).

D6 · Computational structure: a pure ForwardModel evaluator · declared accelerators · streamed results · parallel-safe by construction

Scale: 512×512 = 262 144 pixels, native TOF grid O(10³–10⁴) bins, Gauss-Newton over 5+ parameters, ~8 iterations/pixel; the expensive kernel is σ(E; T, nuclear) assembly. σ depends on the pixel only through T (and composition where it varies), so: the ForwardModel is a pure evaluator object built once per definition, the engine owns batching; any accelerator (e.g. a σ(E,T) surface with interpolation) is a declared approximation that must pass the same acceptance rows — the no-ad-hoc-approximation rule extended to performance engineering. All shared fit inputs are immutable contracted values, so the per-pixel fan-out is parallel-safe by construction — this is the derivation of the immutability invariants, not a decoration. The residual cube is the large output (≈3–5 GB at f32): Results emits in streamed blocks; whole-cube materialisation may never be assumed. E(t; L, t₀ + δt_px) is a cheap per-pixel axis map inside the likelihood — never baked.

D7 · The thin Python wrapper is a consequence, not a rule to police

Every handle and report type is plain data (ids + arrays + enums), so the binding layer mirrors without behaviour — this falls out of D1/D3, and is why the scope decision (bindings outside the contract) is safe.

D8 · The Campaign is durable, and identities resolve across campaigns by verified import

A VENUS campaign spans days — calibration Monday, experiment Wednesday — so the registry is a durable, append-only store: reopenable by id, integrity-checked on load (content hashes re-verified), bulk arrays as content-addressed blobs referenced by id. A new campaign resolves a foreign identity through ingest-by-reference (an Ingest variant importing a contracted object from another campaign’s store, re-verifying its hash) — Wednesday’s fit still takes Monday’s posterior only by registered identity. Storage format is implementation freedom; reopen / append-only / verify / import-by-reference are contract. Found by the builder attack: the traces had glossed "same or new campaign".

The object model — what can only be built from what

Arrows read “can only be constructed from”. The legal call order is this graph — skipping a gate is not expressible.

The contract, clause by clause — the enforcement layer

Everything below is the hardened contract text the adversarial review produced (36 findings folded) — reference, not reading. Eight entry points and nothing else; click one to see what crosses it i

Phase 4 contract — derived doc-only (no code read), self-gated and adversarially reviewed (completeness / representability / derivation attackers; all findings folded — record entries R3·A/B/C), signed off 2026-08-03; the closing rule below governs, with CI enforcement landing in the Phase-5 acceptance wave. The scope, granularity and acceptance-regime rows are Phase-4 project decisions (d1–d3, user-adopted); the type invariants are Phase-4 normative additions — everything else derives from the other three tabs.

stages: 0 ingestion boundary · 1 qualification · 2 reduction · 3 model/likelihood (its gate: G3, the identifiability screen) · 4 fits, 4a calibration (their gate: G4, the compatibility gate) · 5 results/QC

ruleA proposed public function that is not one of the eight entry points, and not a pure accessor on a contracted type, requires updating this contract first — that is how the public surface stays closed.

What counts as a pure accessor, and how failures are typed

Closed means closed: a proposed public function that is not one of these eight, and not a pure accessor on a contracted type, requires updating this contract first — that is how the public surface stays closed. A pure accessor is deterministic from the object alone, takes no parameters beyond the object, and cannot produce a fit-domain input — in particular, no accessor takes (L, t₀) or returns an energy axis; derived energy/transmission views exist only on Results, flagged display-only. Accessors remain public surface for the CI enforcement rule — the exemption is only from the entry-point closure. One named exception: NominalInstrument is a pure accessor on RunState whose output type is consumable solely by the Reduce cold-start constructor (its resolution-order bound uses the definition’s declared kernel family) — the nominal values exist, and can go nowhere else. Failure outcomes are typed: every entry point returns its declared fail-closed or degraded-mode variants from the stage-5 failure taxonomy; a failure class without a declared variant cannot be handled without a contract change.

The fit contract

A parameter is either free or carries a prior with its covariance block. The type has no “fixed” constructor.

A parameter is free or carries a prior(mean, Σ-block) — the type has no "fixed" constructor

Hard-pinning is unrepresentable by construction: "effectively fixed" exists only as a criterion-approved degenerate prior, and the marginalization-criterion evaluation that approved it is recorded in provenance. This is the C_marg = C_cond + JΣ_calJ^T rule (Physics tab) enforced by the type system rather than by discipline — the failure the 20.4%-coverage toy MC demonstrates cannot be expressed in the type system at all.

Mode	Free	Prior (tight, correlated)	Emits
Calibration	L, t₀, θ_res	foil n·d, T (assay) · nuclear data	the instrument posterior
Density	(n·d)ᵢ per pixel	instrument (calibration posterior) · T (external measurement)	n·d posteriors
Temperature	T_eff per pixel	instrument · n·d (external measurement)	T posteriors
In-situ	shared n·d₀ + per-frame T	instrument · the expansion constraint n·d(T)	joint trajectories

Covariance in: the instrument posterior with its off-diagonals, nuclear covariance under the failure policy. Covariance out: C_marg always — C_cond alone is not constructible from the public surface. Likelihood: counts canonical (Poisson/KL, flux inside the model); the Results posterior is always the counts-likelihood product.

Further fit rules — spatial estimators · ROI model · lattice family · nuisances

Spatial estimators honour the declared spatial-estimator ladder — a regularized or jointly inverted fit emits one coupled field posterior whose uncertainty accounts for the effective degrees of freedom the estimator consumed. ROI fits: summed counts are Poisson, and the ROI forward model is ⟨exp(−τ)⟩, never exp(−⟨τ⟩). The lattice-model family is declared per experiment and its model-form (family-choice) uncertainty enters C_marg as a declared term. Transmission-diagnostic fits appear only inside consistency-test outcomes; the transmission ratio exists only behind its validity verdicts. Nuisances are solved per measurement with restricted freedom so model inadequacy stays visible.

Boundary types — the invariants the code must make unbreakable

one type per Data-tab class + the verdict types + the shared provenance block — the Data tab holds the field inventories; this reference table holds the invariants

RawRun — raw run

role is an explicit closed enum (sample · open-beam · blocked-beam · notch-filter · calibrant); per-pulse records immutable.

RunState — run & beam state

the configuration hash is derived, never hand-set; every hashed field is present or the hash does not exist.

DetectorHealth — detector health

constructible only from independent diagnostics — no constructor takes science counts, and the diagnostics carry their own run identities, checked disjoint from every science-run identity in the reduction they mask.

QualifiedRun — qualified run

fail-closed: no path from a failed qualification to a reducible object; corrections carry propagated uncertainty.

ReducedSpectrum — reduced spectrum

immutable; native-TOF bin edges only — the type has no energy axis, E(t; L, t₀ + δt_px) is computed inside the likelihood with the carried per-pixel timing reference; monitors are observations with σ, never divisors; provenance block attached at construction.

BackgroundConstraints — background constraints

per-template amplitudes with uncertainty — identifiability reported, uncertainty withheld for dependent templates amended·p5; templates are the declared closed set.

NuclearData — nuclear data

formalism is the evaluation’s declared one — no default; covariance access runs through the failure policy (available | repaired-and-disclosed | declared-default | reject).

ExternalMeasurement — externally-measured sample state (assay · thermometry)

the general class of externally-measured state (the calibrant assay is its calibration-mode instance; sample thermometry and known areal density are its experiment-mode instances); source named, σ carried, measured-or-assumed flagged in the type; science priors are taken only by reference to these records — hand-typed tightness is not constructible.

InstrumentPosterior — instrument posterior

produced only by Calibrate (producer-restricted, like QualifiedRun); inseparable from kernel form + anchor convention + validity range + conditioning set; off-diagonals never dropped — there is no marginal-only accessor. The fit engine takes priors by registered-posterior identity, never as caller-supplied numbers — a hand-built Σ (however tight) is not a prior.

ExperimentDefinition — experiment definition

only the identifiability screen constructs a screened definition, and its approval is layer-tagged — Reduce requires the design/configuration layers, Fit requires every data-independent layer plus the per-pixel-class layer on the data being fitted; for a series the per-configuration tag is a set of per-hash verdicts and the pixel-class layer runs once over the series; the fit engine accepts nothing else, checks each frame’s configuration and posterior identities against a member verdict, and the definition declares the marginalization-criterion threshold (the stated fraction of the error budget).

ScreenVerdicts — the identifiability screen’s products

layer-tagged verdicts + marginalization-criterion evaluations; each evaluation binds (parameter, prior, the declared threshold, the computed shift, verdict) to the definition and configuration identities it judged — the threshold is declared in the ExperimentDefinition, never chosen at fit time.

GateVerdict — the compatibility gate’s product

exists only as accept | conditional(drift model) | reject, bound to the (posterior identity, configuration hash, fitted energy band) triple it judged — a band outside the posterior’s validity range is a reject (kernel extrapolation is detected here); the fit engine’s posterior argument is the pair (posterior, non-reject verdict) — a posterior without its verdict is not accepted.

Results — results

stores the total marginal covariance; decompositions and display products (energy axis, transmission) are derived views flagged display-only — not inputs to anything. The statistical/systematic display split returns scalar summaries only — the C_cond-equivalent block is never exposed as a covariance object. Distinct from that split, the spatially common-mode covariance component (calibration + shared nuclear terms) is a labelled part of the total covariance’s declared structure — required for any correct N-pixel aggregate (the correlated floor does not average down). Residual cube in signed-deviance / randomized-quantile form, emitted in staged, streamed blocks — the Results identity is registered only at the atomic commit, so uncommitted blocks are explicitly uncommitted (reconciling streaming with register-nothing-on-failure); reduced spectra grant the same block access on the input side, bounding a series fit’s working set by batching, never whole-series residency.

ProvenanceBlock — provenance (five groups)

one shared type; attached to every reduced spectrum, inherited and extended by every result; sufficient alone for bit-for-bit reproduction.

The six conventions — scope · granularity · identity · optionality · uncertainty · units

Convention	Rule
Scope	The contract governs the core analysis crates. The Python bindings are a declared thin wrapper — no independent surface, no behaviour of their own; the GUI is a consumer outside the contract.
Granularity	Entry points + boundary types + invariants. Never function signatures — signatures are implementation, and contracting them invites matching the code instead of the physics.
Identity	Every contracted object carries a content-addressed identity assigned by its producer; references between objects are by identity, never by copy. The configuration hash is the compatibility-gate key.
Optionality	A field is required unless marked conditional(test), where the test is a contracted validity check (e.g. the diagnostic transmission ratio exists iff every validity test passed). Variants are closed sums declared here — e.g. posterior representation: gaussian(mean, full Σ) \| samples \| validated parametric form.
Uncertainty	One encoding: a posterior object (mean + full covariance, or a declared variant). A scalar ±σ is only ever a 1-D posterior; credible intervals are derived views, never the stored object.
Units	Every physical field declares its unit in the type: eV, µs, m, K, atoms/barn; counts are dimensionless with live time attached; resolution parameters carry the kernel-form identity they parameterize.

Acceptance — how we know the code matches the physics

Seven criteria, each with an oracle and a stated budget — and a ratchet: a tolerance once achieved is never loosened. No single row proves the code matches the physics; the composition does — module oracles (1), constructive laws (4) and real-data holdout prediction (7) carry model adequacy, while recovery (2) carries inference calibration only.

Resolved σ(E)

oracle / targetSAMMY as the resolved-resonance oracle, per declared formalism (RM / MLBW / SLBW; RML (LRF=7) is declared-unsupported and rejects fail-closed — never silently substituted erratum·p5) — an oracle for resolved σ(E) only, never a match-target for the pipeline

budget & ruleper-module relative-error budget, stated in the test; ratchet clause: a tightness once achieved is never loosened

Known-sample recovery

oracle / targetsynthetic data from the contracted forward model at known truth, all four modes — by construction this tests inference calibration only (generator = fitter is required for a coverage criterion and cannot see a shared forward-model error; adequacy is carried by rows 1, 4 and 7)

budget & ruleposterior coverage: nominal 68.3% within stated tolerance, per mode — the criterion that catches the hard-pinning failure (20.4% actual coverage in the toy study)

Doc-number regressions

oracle / targetthe document’s own verified numbers as fixed targets (from its analytic derivations and Phase-1 numerics — never the on-page demo): ρ(L,t₀) structure, the Jensen −Var(τ)/2 offset, the deviance reference E[D] at low counts, the marginalization-criterion behaviour

budget & rulereproduced within quoted digits; a change to any target is a contract change

Forward-model laws

oracle / targetconstructive property tests independent of any oracle: Doppler kernel conserves the reaction rate (1/v exact) · convolution order (Doppler inside σ; the kernel on expected counts) · kernel validity conditions (non-negative, normalised, causal, anchored), checked at kernel registration

budget & rulea violated law fails the suite regardless of any oracle agreement

Non-vacuity guards

oracle / targetevery kernel / Jacobian test paired with a nonzero with-vs-without difference pre-check (a test that cannot see the feature is vacuous); ENDF fixtures pinned to the raw evaluation-file bytes, never parser output (a fixture built to match the parser is circular)

budget & rulea test that passes with the feature disabled fails the suite

End-to-end independence

oracle / targetreal-data holdout prediction (the calibration contract’s held-out resonances, thicknesses or repeat runs are predicted, not fitted — promoted here from the calibration contract) + at least one end-to-end acceptance fixture NOT produced by the contracted implementation (SAMMY-computed transmission for a declared sample carried through the chain, or an analytically constructed case)

budget & ruleholdout prediction within its stated tolerance; the independent fixture reproduced within its stated budget — a suite whose every end-to-end row is generated by the code under test does not satisfy this criterion

Enforcement

oracle / targetthe acceptance suite runs in CI

budget & rulea contract change without a corresponding test change fails; a public-surface addition without a contract change fails; a test change that widens any budget or tolerance without a contract change fails — every acceptance budget and tolerance is contract material (the ratchet clause generalizes to all rows)

Once agreed, this tab is the gate: no new public function without updating this contract first — with an extremely high bar for additions.

Every claim in this document was challenged in a round of cross-family adversarial review — two independent reviews (physics; pipeline architecture), 40 findings, each adjudicated against independently re-derived numerics before anything was folded in.

This tab is the correction history: what each accepted finding changed, from → to. The reading tabs state only the corrected physics; a corrected·r1 chip at a claim links to its entry here. Full adjudication (including the findings that were refuted, with the deciding numerics) lives in .research/pipeline-map/adjudication-round1.md.

Process corrections (own-error record, pre-review)

R0·1 Calibrant selection — the τ₀ ≲ 0.3 rule was too strict

~~Use only optically-thin resonances (τ₀ ≲ 0.3) for calibration.~~ → Favour τ₀ up to ~1 for the resolution core; keep saturated lines for wing/background diagnostics. At τ₀ = 0.3 the dip is only 26% deep — too weak to determine resolution — while opacity broadening at τ₀ = 1 (+28%) is deterministic under the forward model. A real Ta foil is already saturated at its strong lines (25 µm → τ₀ ≈ 2.2), so thin-only is not satisfiable anyway.

Physics · calibrant & resonance selection

R0·2 Temperature information — fixed-timing crossover withdrawn

~~Doppler/instrument crossover at 22 eV (1 µs) / 7 eV (3 µs), from a fixed timing uncertainty.~~ → The dominant moderator term scales as 1/√E, giving constant ΔE/E; the instrument equals or exceeds Doppler across essentially the whole band, crossing only near 5.2 eV. The directional conclusion (favour low-E lines) survives; the numbers did not.

Physics · temperature instance

Round 1 · physics review (sections A–I of the adjudication)

R1·1 The ∂lnW/∂lnT ladder is line-specific, and its τ₀ labels were wrong

~~d lnW/d lnT = 0.023 → 0.063 → 0.110 at τ₀ ≈ 0.37 → 1.2 → 3.7, presented as a function of τ₀.~~ → Those values hold at τ₀(300 K) = 0.3 → 1 → 3 (the old labels were 150 K peak depths), for one specific line model (fixed-Γ = 60 meV Voigt at 10 eV). A pure conserved-area Gaussian family gives 0.021 → 0.061 → 0.168 → 0.327; the Voigt ladder is non-monotonic (0.092 by τ₀ ≈ 10). Both ladders were reproduced exactly in adjudication — the correction is that no such ladder is universal, and corrections begin at O(τ₀) with no sharp threshold.

Physics · unifying τ₀ result

R1·2 The +18.6% opacity widening is shape-specific

~~Opacity broadening inflates the width +18.6% from τ₀ 0.3 → 1.~~ → That figure is the Lorentzian HWHM ratio (1.276/1.076); a Gaussian profile gives +12.1%. Both reproduced in adjudication — the number now carries its line shape wherever quoted.

Physics · unifying τ₀ result

R1·3 τ_opt = 2.22 carries unstated conditions

~~Optimal sample thickness is a solved problem: τ₀ ≈ 2.22.~~ → An asymptotic, equal-exposure, known-normalization result; backgrounds, monitors and unequal allocation shift it, and the log-ratio estimator degrades at extreme depth (τ₀ = 8: ten expected sample counts need N ≈ 3×10⁴ open counts/bin).

Physics · density instance

R1·4 "Sub-dominant everywhere" overstated; the 1.05% kernel is an assumption

~~Temperature is a sub-dominant broadening contribution everywhere in the band.~~ → Sub-dominant over nearly the whole band, at best comparable at its bottom (ratio 1.02 at 5 eV); and the ΔE/E ≈ 1.05×10⁻² figure is a moderator-scaling estimate, not a measured VENUS kernel.

Physics · temperature instance

R1·5 Opacity→temperature bias: the linear rule understates it

~~τ₀ drift 0.3→1: apparent T +37% ≈ +112 K; 1→3: +99% ≈ +297 K (first-order 2ε rule).~~ → Exact (1+ε)² values: +41% ≈ +122 K and +124% ≈ +371 K — the linear rule understates badly at large ε, and quadrature-subtracted width components amplify the bias further.

Physics · temperature instance

R1·6 "≥2 resonances" is neither necessary nor sufficient

~~Separable with ≥2 resonances of differing strength.~~ → A rule of thumb: one well-resolved line can suffice in favourable conditions; many lines stay degenerate if kernel, t₀, backgrounds or T_eff are unconstrained. The identifiability screen is the gate. Also: the shared in-situ quantity is the reference n·d₀ under the expansion link, not a literally constant n·d.

Physics · in-situ instance

R1·7 The "~100 counts" rule is a rule of thumb, and not the only condition

~~>~100 open counts/bin ⇒ <1% ratio bias ⇒ transmission admissible.~~ → Exact conditional bias is 1.02% at λ=100 (<1% only from ≥103); and admissibility additionally fails on black resonance cores (S ≈ 0 where the information lives), the shared open beam correlating all pixels, and background/monitor uncertainty. Neyman-χ²'s low bias is the general tendency, not a universal sign.

Physics · statistics table

R1·8 The 3–4× per-pixel UQ shortfall is an observation, not a law

~~Linearised covariance is known to understate per-superpixel scatter by ~3–4×.~~ → An empirical VENUS observation with unattributed cause (model mismatch, ignored calibration covariance, or spatial correlation); under regularity the inverse-Hessian is asymptotically correct.

Physics · statistical traps

R1·9 −Var(τ)/2 is the leading cumulant, not the exact offset

~~The 1D↔2D offset has a predicted value: −Var(τ)/2.~~ → Leading order only; the exact offset is distribution-dependent (−8.5% two-point / −8.7% uniform / −9.0% Gaussian at 30% spread) — the QC target is ⟨e^(−τ)⟩ computed from the fitted 2D field.

Physics · spatial dimension & QC tests

R1·10 3D: convolution order, and back-projection is conditional

~~Never reconstruct fitted densities; τ = −ln T is the linear observable.~~ → The linearity holds in the model domain: TOF-convolved counts do not form a linear Radon sinogram per energy bin. Back-projecting per-ray fits is legitimate iff the fitted quantity is a line integral of a common scalar density (uniform/known T) — invalid when it mixes T, composition, resolution or opacity.

Physics · 3D box

R1·11 The correlated floor is exact only for common-mode systematics

~~A correlated systematic does not average down: variance floor σ²_sys.~~ → Exact for the calibration term (one shared parameter vector, ρ = 1 by construction); finite-correlation systematics soften to σ²_sys(1+(N−1)ρ)/N and partially average down.

Physics · results/QC

R1·12 The centroid-shift "tilt" claim was wrong — and contradicted our own degeneracy structure

~~The mean-vs-mode offset varies with energy, so it does not cancel in the L–t₀ straight-line fit; it tilts it, biasing both parameters.~~ → A constant offset is absorbed exactly into t₀ (verified: refit residual 10⁻¹³ µs, L untouched) and an E^(−1/2) component exactly into L; only centroid drift outside span{1, E^(−1/2)} distorts the fit. "Fit shapes, not centroids" survives on three real mechanisms: energy-dependent kernel asymmetry, per-line opacity centroid displacement, and anchor-convention integrity. This was the review's sharpest catch: the original sentence contradicted the timing-degeneracy table two sections above it.

Physics · resolution function

Round 1 · pipeline review (28 findings, all folded)

R2·1 Native TOF preserved through the fit

~~Reduction built an energy axis from the calibration posterior.~~ → Reduction never rebins to energy; E(t; L, t₀) is evaluated inside every likelihood evaluation, and the energy axis is a stage-5 display product. The old design contradicted the floating calibration: an axis baked at reduction would pin L, t₀ and re-interpolate counts.

Pipelines · stage 2/5

R2·2 A qualification stage was missing

~~The spine began at reduction; run vetting was implicit.~~ → Stage 1: fail-closed run/beam/detector qualification before any reduction.

Pipelines · stage 1

R2·3 Backgrounds are measured, not guessed

~~Backgrounds appeared only as nuisance parameters B_s, B_o.~~ → Dedicated background measurements (blocked-beam, black-resonance filters) are first-class data constraining per-template components.

Pipelines · stage 1

R2·4 Dead time / pile-up enter the design

~~Dead time was a listed gap, absent from the pipeline.~~ → Characterized and corrected with propagated uncertainty and a hard rate-validity limit; rates differ between arms, so nothing cancels in a ratio, and uncorrected losses invalidate the Poisson likelihood.

Pipelines · stage 1

R2·5 Monitors are observations

~~Q_s, Q_o treated as exact divisors.~~ → Noisy monitor observations with their own likelihood terms and shared-monitor covariance.

Physics · observation model; Pipelines · stage 2

R2·6 Counts is canonical; transmission is a diagnostic

~~Two co-equal arms, transmission admissible past two tests.~~ → Counts is the canonical fit domain; transmission is retained as the community-convention diagnostic under a tightened admissibility set (open-count bias, black cores, shared-OB covariance, backgrounds, forward-simulated resolution-order bound). Scope note: the reviewer argued for counts-only; the transmission arm is retained by the project's fixed scope envelope, repositioned as never-canonical.

Pipelines · stage 2 arm split

R2·8 Attenuation completeness is a policy, not a hope

~~Non-Beer-Lambert effects listed as gaps; "model inadequacy stays visible".~~ → Each effect (container, scatter-in, multiple scattering, PSF mixing, self-shielding) is modelled, bounded with a stated magnitude, or measured.

Pipelines · stage 3

R2·9 Use the evaluation's declared formalism

~~"Coherent Reich-Moore σ per isotope from ENDF."~~ → The evaluation's declared File-2 formalism (RM / RML / MLBW as given), File-3 background where present, boundary rules honoured. The reviewer's companion claim that the doc combined isotopes coherently was a misread — isotope contributions always summed in the exponent — recorded in the adjudication.

Physics · chain step 1; Pipelines · stage 3

R2·10 Nuclear covariance has a failure policy

~~"ENDF covariance carried."~~ → Availability checked; non-PSD repaired and disclosed; missing → declared default or rejection; one shared uncertainty across all fits; model discrepancy its own term.

Pipelines · stage 3

R2·11 The calibration posterior need not be Gaussian

~~(θ̂, Σ_cal) as the output object.~~ → Samples or a validated parametric form where the posterior is non-Gaussian; the conditioning set extends to detector state, beam configuration and kernel family.

Pipelines · stage 4a

R2·12 Calibration validity is enforced

~~Validity range carried as metadata.~~ → A compatibility gate: configuration match via hashes, drift bounded by bracketing references and control charts; on mismatch reject or attach an expanded drift model.

Pipelines · stage 4a

R2·13 Calibration gets holdout validation

~~Self-consistency = in-sample residuals across fitted resonances.~~ → Plus held-out resonances / thicknesses / repeat runs predicted, not fitted — in-sample residuals cannot distinguish a predictive kernel from one compensating ENDF or assay errors.

Pipelines · stage 4a

R2·14 The identifiability screen is layered

~~"Gate: runs once per configuration, not per pixel."~~ → Four layers: design time, per configuration, per pixel class on the actual usable data, post-fit posterior diagnostics — a global screen would accept pixels with no local information.

Pipelines · stage 3

R2·15 Pins are replaced by the marginalization criterion

~~"T pinned if the screen confirms the thin regime"; "n·d joint unless τ₀ known small" — binary τ₀ branches.~~ → Pinning is admissible only when marginalizing the parameter's external uncertainty shifts the target posterior by less than a stated fraction of the error budget; a prior is always preferred over a pin. τ₀ remains the physical reason the criterion passes in the thin limit. (Merges findings 15–17.)

Physics · density & temperature instances; Pipelines · stages 3/4b/4c

R2·16 Resonance choice by expected information, not an axiom

~~"Prefer the lowest usable resonances" as the rule.~~ → Rank candidate sets by expected information on T_eff after marginalizing density, kernel, background and nuclear data; under moderator-dominated resolution the ranking lands on the low lines — the rule of thumb is the expected outcome, not the criterion.

Physics & Pipelines · temperature

R2·17 Thermometry carries lattice-model-family uncertainty

~~"Report T_eff with the Debye/lattice relation stated."~~ → The family (free-gas / Debye / phonon DOS) is declared and its model uncertainty propagated into thermodynamic T — different families give different line shapes.

Pipelines · stage 4c

R2·19 Masking from independent diagnostics

~~"Union of sample ∪ OB broken-pixel masks", brokenness unspecified.~~ → Detector-health states from independent diagnostics (hot/noisy, timing-shifted, cross-talk, saturation) — never inferred from the science counts being fitted.

Pipelines · stages 1/2

R2·21 The expansion law is integrated and conditional

~~n·d scales as (1+αΔT)⁻² with constant α.~~ → n·dⱼ = n·d₀·exp(−2∫α(T)dT), valid for free isotropic expansion; fixtures, anisotropy, phase changes or near-melting (Au: 1337 K) replace it with an integrated strain model with uncertainty.

Physics & Pipelines · in-situ

R2·22 The sharing declaration covers drift

~~Sharing structure = which physics parameters are global vs per-frame.~~ → Also the time-dependent instrument and beam structure: per-frame intensity/monitors, background, detector state, timing drift — a global fit does not protect against drift it does not model.

Pipelines · stage 4d

R2·23 The deviance reference is calibrated

~~Goodness of fit reads directly: D/(n−k) → 1.~~ → Only asymptotically — per-bin E[D] ≈ 1.15 at λ=1, 1.02 at λ=10 (verified by exact summation); the reference is calibrated by parametric bootstrap / posterior predictive, and residual cubes use signed-deviance / randomized-quantile residuals.

Physics · statistics; Pipelines · stages 3/5

R2·24 Total covariance is authoritative

~~Statistical and systematic parts "separated".~~ → The total marginal covariance is authoritative; the split is a documented decomposition convention, with credible intervals for bounded or skewed posteriors.

Pipelines · stage 5

R2·25 Failure states are predefined

~~A trust mask at the end.~~ → A failure taxonomy decided in advance: each class fail-closed or a declared degraded mode — missing OB/background/monitors, partial frames, dead-time violation, calibration incompatibility, missing/non-PSD covariance, kernel extrapolation, non-identifiability, non-convergence.

Pipelines · stage 5

R2·26 Provenance includes versions, hashes, seeds

~~Provenance = bin edges, masks, Q values, axis parameters, library/version.~~ → Plus component versions, configuration hashes and random seeds — enough to reproduce a result bit-for-bit or reject a mismatched transfer.

Pipelines · stage 2

note Findings adjudicated but not folded as corrections

Remaining findings (7 of 28) either confirmed existing design statements or sharpened wording without changing a rule — e.g. the resolution-order screen already moved to a forward-simulated bound (R1·7), the path-length dismissal restated as a budget comparison. Two findings were partially rejected with evidence: counts-only (scope envelope keeps the transmission diagnostic) and the isotope-coherence misread (see R2·6, R2·9). The full disposition table, including refuted findings and the deciding numerics, is in the adjudication file.

Round 2 · Data-tab taxonomy (adversarial cross-read, in-session)

R2·D Homeless data items and two contract contradictions, folded

Taxonomy v1: transmission "display-only, never the fit domain"; characterization "at qualification"; calibration "reduces with nominal axis parameters"; no home for per-pixel t₀, drift records, known sample-state values, screen verdicts, live time, rate regime. → The conditional diagnostic transmission arm (+ its admissibility verdicts) lives on the reduced spectrum, so "display-only" qualifies only the stage-5 product; per-pixel t₀ timing calibration and nonlinearity live in detector health; the drift record and selected resonance set in the instrument posterior; known sample-state values, α(T) data, screen verdicts, attenuation policy and model-discrepancy term in the experiment definition; live time, rate regime and surveyed geometry in run & beam state; stage 2 consumes the experiment definition (it executes the domain decision); calibration seeds at surveyed L / nominal t₀ through the axis-free path; stage 1 checks the configuration the gate hashes; measured background templates are named in the model stage, distinct from ENDF File-3.

Data · taxonomy + provenance; Pipelines · stage contracts 1–4

Round 3 · API-contract review (adversarial, doc-only, in-session)

R3·A Representability holes closed — the contract now blocks what it previously only discouraged

Gate verdict produced but consumed by nothing; "pure accessor" undefined (the baked-axis escape hatch); any caller could mint an InstrumentPosterior (pin-by-proxy via a hand-built near-zero Σ); C_cond exposable through decomposition views; ratchet scoped to one row and no rule against widening tolerances; the marginalization-criterion approval self-evaluated; definition admittance unbound from configuration; diagnostics independence unverifiable. → Fit accepts the posterior only paired with its accept verdict (GateVerdict is a contracted type); pure accessor is defined (deterministic, parameter-free, cannot produce a fit-domain input) and stays inside the CI rule; posteriors are minted only by Calibrate and priors enter by minted identity, never caller-supplied numbers; decomposition views never return covariance-form components; every budget and tolerance is contract material (generalized ratchet, symmetric CI rule); criterion evaluations are screen products with linked identities; admittance binds to the admitting configuration/posterior identities; diagnostics carry run identities checked disjoint from science runs.

API · entry points, types, fit contract, acceptance

R3·B Derivation audit — one stage contradiction, one type hole, cell mismatches, and the tripwire

Background constraints produced at Qualify (before reduction exists); the Fit→Assemble object had no contracted type; Reduce required a definition for calibrant/background runs; screen consumers missing from the Data columns; "surveyed-geometry seed" an invented name; acceptance rows ungrounded in the doc; credible intervals stored vs derived contradiction. → Templates are produced at Reduce from reduced background runs; the Fit output is the posterior layer of the Results class (produced 4–5, matching the Data column); the definition input is conditional to sample-role reductions and admitted at the design/configuration layers; the Data consumed-by columns gained the screen and the 4a seed; the seed is named as its class (run & beam state); acceptance decisions carry their grounding inline (oracle-not-match-target, circularity and vacuity rationales) and are labelled Phase-4 project decisions; intervals are derived views everywhere, the Results row aligned.

API + Data · flows, taxonomy columns, acceptance

R3·C Completeness attack — nineteen uncoverable requirements, all given contracted homes

The gate pairing severed the expanded-drift arm; calibration could not terminate in stage 5; stage 5 lacked nuclear data and the diagnostic-arm fit had no producer; reduction could not fill its provenance fields or run the resolution-order bound; per-pixel t₀ had no path into the likelihood; the calibration definition, drift-record history, screen-verdict type, criterion threshold, expected-information ranking, forward-model law tests, typed failure outcomes, external ingestion, spatial-estimator upper rungs, ⟨exp(−τ)⟩ ROI rule, lattice-family term, layer-tagged admission, common-mode covariance share and residual-cube form were all unrepresentable. → Fit accepts accept-or-expanded-drift verdicts with the drift model in the parameter set; Calibrate emits a posterior layer into Assemble like every instance; Assemble consumes nuclear data; Fit produces the Pearson-weighted diagnostic-arm fit; Reduce reads posterior + nuclear identities (never an axis); the reduced spectrum carries the per-pixel t₀ reference into E(t; L, t₀ + δt_px); calibration runs under its own admitted calibration-mode definition with history for the drift record; ScreenVerdicts is a contracted type binding each criterion evaluation to its declared threshold (a definition field); the screen emits the expected-information ranking; forward-model laws are constructive acceptance tests; failure outcomes are typed; Ingest is the eighth entry point (the closed set grew by exactly one, by contract change); coupled field posteriors count effective degrees of freedom; the ROI model is ⟨exp(−τ)⟩; the lattice-family term enters C_marg; admission is layer-tagged; the common-mode covariance share is a labelled part of the total structure; the residual cube is signed-deviance / randomized-quantile.

API · all four sections; Data · three rows

R3·D Round-8 design attacks — the traces were executed and broke; the design grew four decisions

The API tab stated a contract without its design; when the reasoning layer (Campaign registry, handles, traces) was added and adversarially executed: cross-campaign identity resolution was impossible; known-state priors were caller-supplied numbers inside the definition (the hand-pinning carve-out); T2 and T4 ran gates and reductions before the handles they consume could exist; the gate judged an energy band it never received; the diagnostic-arm admissibility verdicts and the NominalSeed had no producers; calibration history and prior Results had no first-ever case; streamed emission contradicted atomic minting. → D8: the Campaign is durable with verified ingest-by-reference. D9: the KnownStateRecord — every prior, instrument or science, enters by identity of a minted object. Trace orders corrected (screen-design → gate → reduce → screen-pixel → fit; the series variant with per-hash verdict sets). The gate consumes the definition’s declared band; Reduce mints the admissibility verdicts; background constraints are configuration-bound; conditional first-ever cases declared; spool-then-commit reconciles streaming with mint-nothing-on-failure; NominalSeed is a named accessor exception consumable only by the bootstrap.

API · design layer, traces, types; .research/pipeline-map/api-design-analysis.md

Round 10 · terminology audit (user challenge: are these terms real?)

R10·1 Coined metaphor names replaced by standard vocabulary — no rule, type or invariant changed

The user challenged the API vocabulary as possibly invented to sound professional. The audit confirmed it in part: the underlying concepts are standard, but several names were this document’s own metaphors (coin-minting, courtroom, clinical-trial “arm”, print-spool), presented without saying so. Renamed, concept for concept: ~~AdmittedDef~~ → ScreenedDefinition · ~~PairedPosterior~~ → GatedPosterior · ~~KnownStateRecord~~ → ExternalMeasurement · ~~NominalSeed~~ → NominalInstrument · ~~minted~~ → registered / produced by its one producer · ~~expanded-drift(model)~~ → conditional(drift model) · ~~diagnostic transmission arm~~ → diagnostic transmission ratio · ~~admissibility tests~~ → validity tests (the mathematical sense in “kernel admissibility” stays) · ~~spool~~ → staged blocks · ~~the letter of the contract~~ → the contract, clause by clause. Entries above this one keep the old names — they are the historical record, and the glossary resolves both. Kept because they are standard terms of their fields: identifiability, nuisance, marginal covariance, holdout, coverage (statistics); campaign, calibrant, assay, thermometry, live time (instrument practice); registry, content-addressed identity, append-only, atomic commit, fail-closed, verdict, test oracle, vacuous test, closed enum, handle (software engineering). Kept as declared coinages, now marked as such in the glossary: the contracted type names (RawRun … ProvenanceBlock) and PriorPattern. A second, independent fresh-eyes pass over the renamed page then flagged twenty-one further register defects — an overclaiming glossary preamble (“every other entry is standard” was false), anti-rot gate, the death-by-features–vector phrasing, the anti-20.4% label, temporal protocol, hostile-developer surface, thin mirror, bootstrap constructor (collides with the statistical bootstrap used on the same page), expansion link (collides with the GLM link function), covariance share, discrete-model uncertainty, the surviving “kernel admissibility”, and three terms used without definition (posterior layer, contracted, resolution-order bound) — all folded: renamed, or defined and declared. Full classification: .research/pipeline-map/LEXICON.md.

API + Data + Physics · vocabulary only

Phase 5 · reconciliation errata (adjudicated at plan approval)

R5·1 RML (LRF=7) reclassified: declared-unsupported, fail-closed — not a supported formalism

The Phase-4 text listed the supported resolved formalisms as “RM / RML / MLBW”. At Phase-5 reconciliation the project removed the R-Matrix-Limited (LRF=7) computation path (with the unresolved-region path) as dead-and-incomplete code; the scope envelope’s calibrant and sample isotopes (Ta / W / Au / Ag, 5–200 eV) all declare LRF 1/2/3. The law that survives unchanged is the one that mattered: the evaluation’s declared formalism is honoured as given, never silently substituted — an evaluation declaring LRF=7 is now rejected fail-closed with a loud diagnostic instead of being computed. The formalism list in the stage-3 law and the acceptance card was corrected to “RM / MLBW / SLBW” (SLBW, LRF=1, was always supported and belonged on the list). Adjudicated with the user at the Phase-5 plan approval.

API acceptance card + Pipelines stage-3 law · formalism support list

R5·2 “ρ = 1 by construction” corrected — a shared calibration vector does not force unit pixel correlation

The results section (and the R1·11 fold) asserted the calibration systematic is common-mode with pairwise ρ = 1 “by construction” because pixels share one parameter vector, making σ²_stat/N + σ²_sys an exact floor. For a multi-dimensional θ that inference is invalid: shared δθ ~ N(0, Σ_cal) gives ρ_ij = J_iΣ_cal J_jᵀ normalized, which equals one only under proportional sensitivities (Cauchy–Schwarz); a numeric check with a {L, t₀} posterior gives ρ ≈ 0.58 between 1 eV- and 100 eV-dominated pixels. What survives: the systematic never averages down — the mean’s variance plateaus at ḡᵀΣ_cal ḡ. What changed: “exact” and “ρ = 1” are gone; aggregates use the full J_iΣ_cal J_jᵀ block. Found in the Phase-5 branch review (cross-family verified); the R1·11 entry above is left as history.

Physics · results & uncertainty (aggregation floor)

R5·3 1D↔2D predicted offset restated in commensurate units

Two sites (the consequence paragraph and the QC table) wrote the predicted 1D↔2D offset as “⟨e^(−τ)⟩ … (−Var(τ)/2 to leading order)” — equating a transmission in (0,1) with an optical-depth offset. The fitted 1D-ROI optical depth is −ln⟨e^(−τ)⟩, so the predicted offset is −ln⟨e^(−τ)⟩ − ⟨τ⟩ ≈ −Var(τ)/2; the adjacent Jensen derivation and its worked numbers were already in the correct convention and are unchanged. Found in the Phase-5 branch review (cross-family verified); the R1·9 entry above is left as history.

Physics · spatial dimension + results QC table

R5·4 Interactive demos made area-conserving — the on-screen physics now obeys the stage-2 law

Both live demos broadened with fixed-unit-peak Gaussians: the line lab’s profile kept peak 1 while its width grew with T (σ-area +36% from 300 → 900 K), and the pipeline scene divided σ by its T-dependent peak — so the “n·d” control actually pinned peak optical depth, keeping dip depth T-invariant where the document’s own stage-2 law conserves the σ-area and trades depth for width. This is the same unit-peak normalization mistake the temperature-instance method note records for an earlier prose draft, reproduced in the demo JavaScript; the in-page fits could not expose it because data generation and fitting share the model. Fixed by anchoring both demos at the 295 K calibrant reference: profiles scale as w_ref/w(T) (area conserved; verified numerically to machine precision), n·d reads τ₀ at 295 K, the heat preset now shows the depth-for-width trade (+32% width, −20% depth), and the look-alike ghost was retuned (300 K, n·d 0.88, θ 2.48% matches the 900 K line to |ΔT| < 0.004). The calibration demo and its published CALPOST numbers are unchanged: the foil is at 295 K, where old and new normalizations coincide. Found in the Phase-5 branch review (cross-family verified, both verifiers reproducing the +36% area defect to nine digits).

Physics line lab + Pipelines interactive scene · demo JavaScript only

R5·5 Demo reductions disclosed in full; demo weights made model-variance (Pearson)

The pipeline-scene status line called the demo “the document’s own forward model”, flagging only the blur as a reduction — while the demo’s σ(E) is seven fixed Ta-181 lines summed as independent Gaussian profiles, the very shape the stage-1 law warns against (no collision-matrix interference, no Lorentzian wings), and its noise model was multiplicative Gaussian with weights derived from the noisy observation — the Neyman trap the statistics section names. Neither reduction appeared in the disclosed list, and the in-page fits could not expose them (data generation and fitting share the model). Corrected three ways: the status line and the demo-reductions tooltip now disclose the line-shape and noise/weight reductions explicitly; the fit weights derive from the model value (Pearson), not the noisy draw; and the doc-number acceptance row states its targets come from the document’s analytic derivations and Phase-1 numerics, never the on-page demo. Found in the Phase-5 branch review (cross-family verified).

Pipelines scene status + tooltip + demo JavaScript · API acceptance row

R5·6 Acceptance suite gains an end-to-end independence row; page navigation repaired

The acceptance header claimed the six criteria show “the code matches the physics”, but no row supplied an independent end-to-end oracle: the SAMMY row is scoped to resolved σ(E), the doc-number and law rows are piece-wise, and the known-sample recovery row is a same-model generate/fit loop — blind by construction to a shared error such as a mis-scaled TOF constant, the same circularity standard the suite itself applies to parser fixtures. Fixed by scoping the recovery row to inference calibration explicitly and adding a seventh criterion: real-data holdout prediction (promoted from the calibration contract) plus at least one end-to-end fixture not produced by the contracted implementation. Separately, two navigation defects: “show everything” never unhid the top-level tabs (Ctrl-F reached about one-sixth of the document; the print stylesheet already had the missing rule), and initial-load / hashchange deep links could not switch tabs (the reveal engine could not reach the tab activator, so shared anchors landed on Overview with the target hidden — record links additionally need the developer view, now set automatically). Found in the Phase-5 branch review (cross-family verified; deep-link failure reproduced at runtime).

API acceptance section · page chrome (expand + deep links)

Phase 5 · Wave-1 contract amendments (adjudicated at the Wave-1 plan approval)

R5·7 Wave-1 engine concepts admitted: detector-bin response · two-arm counts · background templates as a Reduce product · two-tier Doppler declared

The Wave-1 harvest (archive/pr712-venus-gate2) lands engine mechanisms whose public surface is not yet one of the eight entry points, and the closing rule requires the contract to move first. Per the Granularity convention the admission is at boundary-type altitude, four clauses. (1) The instrument-kernel stage gains its contracted operator form: the detector-bin response (bin probabilities from an admissible kernel over the actual detector-time edges, physical clock preserved, acquisition-window loss reported rather than renormalized away) and the two-arm count response O_i = Σ_j F_j R_ij, S_i = Σ_j F_j T_j R_ij, with F_j the incident fluence weight at true energy E_j (flux × efficiency × the energy-integration weight) — the arms broaden separately, and a post-hoc broadened ratio R[T] is named as not this response, closing the silent route the code actually had. (2) Background-template amplitude estimation is declared the mechanism behind Reduce’s existing background-constraints product — a non-negative two-arm amplitude fit over declared spectral templates with identifiability reported and uncertainties withheld for dependent templates — resolving the tension that a free fitting function would otherwise read as a ninth entry point. (3) Doppler evaluation is declared two-tier, with the tier boundary including the thermal window: resolved SLBW/MLBW sources with √E > 8u (u = √(k_B·T_eff/A), the kernel width in √E) whose full thermal support window [(√E−8u)², (√E+8u)²] lies inside the resolved range, and with no File-3 background term, integrate the free-gas kernel over the resonance equation itself at error-controlled quadrature; every other case — another formalism, √E ≤ 8u (where the written window bound would fold through zero), a window crossing the range boundary, or a File-3 term — takes the sampled-table route, the base kernel-on-grid broadener: a declared approximation boundary disclosed per isotope, never a silent substitution; the route is per-isotope, all-or-nothing over the requested grid — never mixed within one isotope result. (4) Three failure classes join the stage-5 taxonomy: a counts fit requested without the separate-arm detector response, unsupported detector background, and acquisition-window kernel loss. Four of these properties are normative obligations on the engine PRs rather than descriptions of the archived code — the quantified window-loss report; the per-isotope route disclosure (the archive preserves the loss and names the fallback internally, but exposes neither); the F_j efficiency semantics: the archived operator’s F_j = w_j·Φ(E_j) omits detector efficiency, which this contract folds into F_j as the discrete Φ·ε, so porting the archived rustdoc verbatim would land a definitional conflict; and the File-3 tier gate, vacuously satisfied by the archive (File-3 is unrepresented in the codebase today) and binding on whichever PR introduces File-3 support; the engine PRs land all four citing this entry. Adjudicated with the user at the Wave-1 plan approval; the review round additionally aligned the BackgroundConstraints data-class and type-invariant texts with the withheld-uncertainty rule.

Physics stages 2 + 5 · Reduce entry point · stage-5 failure taxonomy · Data background-constraints class + BackgroundConstraints type invariant

Terms used on this page

Every dotted-underlined word in the document opens its definition. Written for a physicist who does not work in resonance analysis. Names set in code face — RawRun, GateVerdict, … — are this document’s own proposed names for the objects its contract defines. Entries whose definition ends “(A term this document defines.)” — and every entry carrying a rename note — are likewise this document’s vocabulary, not field terminology; everything else is standard usage in its field. Several early coinages were renamed during review; the Review record keeps the old names, and both resolve here.

forward model: The calculation that goes from physical parameters (density, temperature, instrument) to a predicted measurement; fitting runs it thousands of times and never inverts the data directly.
inverse problem: Recovering parameters from a measurement — the hard direction, because many different parameter sets can produce nearly the same data.
joint fit: One fit in which every unknown varies together, so parameter trade-offs land in the reported uncertainty instead of disappearing.
degeneracy: Two parameters change the predicted data in nearly the same way, so the data alone cannot say which one moved.
identifiability: Whether the data in hand can determine a parameter at all — a property of the experiment, not of whether the fitter happened to converge.
identifiability screen (G3): The pre-fit check that a proposed measurement can actually determine its target parameters; it refuses the run rather than returning a confident unsupported number.
prior: A probability statement about a parameter brought in from outside this measurement — a previous calibration, an assay, a thermometer — carrying its own uncertainty.
tight prior: A prior that is narrow but still has width: the parameter is still fitted and its uncertainty still flows into the answer; it simply cannot wander far.
hard pin (fixing a parameter): Holding a parameter at one number with zero uncertainty; it makes every downstream error bar too small, which is why this document forbids it.
posterior: The result of a fit stated as a probability distribution — best values plus the full covariance — rather than as a list of numbers.
covariance matrix: The table of variances and correlations for a set of fitted parameters; the diagonal holds the individual error bars, the off-diagonal the trade-offs between them.
off-diagonal terms: The correlation part of a covariance; dropping it makes some parameter combinations look far too certain and others far too uncertain, so the error is in both directions.
marginalization: Averaging over a parameter you do not care about, so its uncertainty is carried into the one you do care about instead of being ignored.
C_marg vs C_cond: C_cond is the error bar you get by pretending the calibration is exact; C_marg = C_cond + JΣ_calJᵀ adds what the calibration's own uncertainty contributes, and is the honest one.
marginalization criterion: The explicit test that decides whether a parameter may be treated as effectively fixed: only if marginalizing over its external uncertainty moves the answer by less than a stated fraction of the error budget. (A term this document defines.)
nuisance parameter: An unknown you must fit but do not want — normalization, background, flux — real physics that would otherwise contaminate the parameter you do want.
likelihood: The probability of the data you actually recorded, given a trial set of parameters; fitting means finding the parameters that make the recorded data most probable.
Poisson (counts-domain) likelihood: The fitting statistic for counting individual neutrons; correct at any count level, including bins holding a handful of events, where a Gaussian χ² is not.
deviance: The goodness-of-fit measure that plays the role of χ² for Poisson data: twice the log-likelihood gap between the fitted model and a model that matches every bin exactly.
Neyman vs Pearson χ²: Neyman takes each bin's variance from the observed counts, Pearson from the model prediction; Neyman over-weights bins that happened to fluctuate low and so biases fitted amplitudes.
goodness of fit: The number saying whether the model can explain the data at all — a different question from how precisely it determined the parameters.
residual: Measured minus predicted, bin by bin; structure in the residuals is the model being wrong, which is why this document insists it must stay visible.
residual cube: Residuals kept for every pixel and every time bin — a three-dimensional array — rather than collapsed to one number per pixel.
signed-deviance / randomized-quantile residual: Two ways to make count residuals comparable to a standard normal: signed deviance takes ±√(per-bin deviance); randomized-quantile adds a uniform jitter inside each discrete probability step so the result is exactly normal when the model is true.
parametric bootstrap / posterior-predictive check: Simulating many fake datasets from the fitted model and re-fitting them, to learn what a normal goodness-of-fit value looks like before judging the real one.
coverage: How often a stated 1σ bar actually contains the truth; a correct 1σ covers 68.3% of cases, and the toy study on this page found a hard-pinned fit covering only 20.4%.
Gauss–Newton: The standard iterative least-squares algorithm: linearize the model at the current parameters, solve for a step, repeat until it stops moving.
inverse-Hessian (linearised) covariance: The cheap error bar taken from the curvature of the fit at its minimum; asymptotically correct, but optimistic when the model is wrong, the counts are low or the posterior is not ellipsoidal.
Fisher / expected information: How much a proposed measurement can tell you about a parameter, computable before you take it; used here to rank candidate resonance sets instead of choosing them by rule of thumb.
MCMC: Sampling the posterior directly instead of approximating it by a curvature matrix; exact for awkward shapes, and far too slow to run in every one of 262 144 pixels.
credible interval: The Bayesian error bar — a range containing the parameter with stated probability — used where a posterior is skewed or bounded and a ±σ would mislead.
regularization: Adding a penalty that pulls neighbouring pixels toward each other; it buys lower noise with added bias, so it must be justified by real physics rather than by a nicer-looking map.
edge-preserving (TV-like) prior: Regularization that smooths within regions but permits sharp jumps at boundaries — appropriate when the sample genuinely has edges, unlike Gaussian smoothing which erases them.
effective degrees of freedom: How many independent parameters a regularized fit really used — fewer than the number of pixels — and the number the error bars must be charged for.
holdout validation: Fitting with some resonances, thicknesses or runs deliberately withheld and then predicting them; it catches a model that is compensating errors rather than describing physics.
model inadequacy / model discrepancy: The part of the mismatch caused by the model being wrong rather than by noise; given its own term so it cannot be quietly absorbed into the background.
Jensen's inequality: Because exp is convex, the average of exp(−τ) always exceeds exp of the average τ — which is why fitting a heterogeneous region as if it were uniform underestimates density.
cumulant: A term in a systematic expansion of a distribution; the −Var(τ)/2 offset on this page is the leading cumulant only, so the exact offset still depends on the distribution's shape.
correlated (common-mode) systematic: An error shared identically by every pixel; averaging more pixels does not reduce it, so a 1/√N error bar on a spatial mean is wrong by construction.
adaptive binning / superpixel: Grouping neighbouring pixels to raise the counts entering one fit, trading spatial resolution for statistical precision.
trust mask: The per-pixel record of where the fit is believable, so failures arrive as data instead of as numbers that merely look plausible. (A term this document defines.)
optical depth τ₀: The exponent of the attenuation at a resonance peak, τ = n·d·σ: τ₀ = 1 removes 63% of the beam at that energy, τ₀ = 3 removes 95%.
areal density n·d: Atoms per unit area along the beam, in atoms/barn; transmission measures this product only, never thickness and volumetric density separately.
barn: The nuclear cross-section unit, 10⁻²⁴ cm²; quoting areal density in atoms/barn makes the product n·d·σ dimensionless.
Beer–Lambert law: Transmission = exp(−Σ n·d·σ), exact for the un-scattered beam at any thickness — so it is not a thin-sample approximation that breaks when the sample gets thick.
self-shielding: The front of a thick sample removes the resonance-energy neutrons, so the back sees a beam already depleted; in transmission the exponential already describes this exactly, and it only becomes a correction if you linearize.
saturation / black resonance: A line strong enough that essentially no neutrons at that energy get through: the dip stops deepening and only its width still responds to more material.
curve of growth: How a dip's strength grows with areal density — linear while thin, then flattening and widening once it saturates; borrowed from stellar spectroscopy, and the reason depth and width cannot be read as separate measurements.
equivalent width: The area removed by a dip, ∫(1−T)dE, expressed as the width a perfectly black rectangular line would need to remove the same number of neutrons; more robust against normalization error than the depth.
Doppler broadening: Thermal motion of the target nuclei smears the resonance in energy, widening and shallowing it; the free-gas kernel conserves the reaction rate exactly and the cross-section area only to order (Δ_D/E)².
Doppler width Δ_D: The characteristic energy spread from that motion, ≈ √(4k_BT_eff·E/A): larger when hot, larger at high energy, smaller for heavy nuclei.
free-gas model: The standard Doppler treatment, which pretends the nuclei move like an ideal gas at temperature T; exact for the reaction rate, and applied to a solid only through an effective temperature.
effective temperature T_eff: The temperature a free gas would need to reproduce the mean-square nuclear motion of a real lattice; always above the thermodynamic temperature because of zero-point motion, converging to it when hot.
Debye temperature θ_D / phonon DOS: The lattice-vibration model that converts thermodynamic temperature into T_eff; different model families give slightly different line shapes, so the family must be declared and its uncertainty carried.
resonance: A neutron energy at which a compound-nucleus state is available, raising the cross-section by orders of magnitude and cutting a sharp notch into the transmitted spectrum.
Γ, Γn, Γγ (resonance widths): Γ is the intrinsic energy width of a resonance, set by the lifetime of the compound state; Γn is the part that decays by re-emitting the neutron and Γγ the part that decays by gamma emission, with Γ their sum over open channels.
capture-dominated resonance: One with Γγ ≫ Γn, so nearly every neutron it removes is genuinely absorbed rather than scattered forward into the detector — the clean kind for quantitative density.
interference asymmetry: Resonance scattering adds coherently with potential scattering, tilting the line shape and letting the cross-section fall below or rise above the smooth baseline; the effect scales with Γn/Γ.
spin group (J, π, ℓ, channel spin): The quantum labels that sort resonances into independent families — total angular momentum, parity, orbital angular momentum and channel spin; only resonances in the same family interfere with each other.
statistical spin factor g_J: The weight (2J+1)/(2(2I+1)) giving each spin group its share of the cross-section, with I the target's ground-state spin.
resolved resonance region (RRR): The energy band where individual resonances are separated and tabulated one by one; the VENUS band of ≤ 200 eV lies entirely inside it.
unresolved resonance region (URR): The higher band where resonances overlap and only their statistical distributions are known, so cross-sections there are averages, not lines; not used by this pipeline.
ENDF File 2 / File 3: In an evaluated nuclear-data library, File 2 holds the resonance parameters and File 3 the smooth background cross-section that must be added to whatever the resonance formula reconstructs.
resonance formalism (SLBW · MLBW · Reich-Moore · RML): Successive approximations for turning resonance parameters into a cross-section: SLBW adds each line independently, MLBW restores level-level interference in the elastic channel, Reich-Moore eliminates the gamma channels but keeps the full R-matrix in the particle channels, and RML is the general multichannel form — an evaluation's parameters mean only the formalism it declares.
collision matrix U_cc: The R-matrix quantity giving the amplitude for a neutron to enter and leave in the same channel; because the total cross-section is built from 1 − Re U_cc, resonances interfere rather than simply add.
scattering / channel radius (AP, a_c, NAPS): AP sets the potential-scattering amplitude, a_c the radius at which the R-matrix is matched to free-particle waves, and NAPS is the ENDF flag stating whether the evaluation uses one number for both.
boundary condition B · distant-level R^ext: Bookkeeping parameters describing the R-matrix boundary and the levels outside the tabulated range; they shift the smooth part of the cross-section and must be carried as the evaluation gives them, never defaulted.
reduced-width sign: The sign of a resonance's width amplitude, which decides whether neighbouring lines interfere constructively or destructively; discarding it changes the line shape even though the widths are unchanged.
mononuclidic · even-even nucleus: An element with effectively one stable isotope; an even-even nucleus (even proton and neutron number) always has ground-state spin 0, so s-wave neutrons see a single spin group and produce a sparse, cleanly separated resonance ladder.
resonance ladder: A nuclide's sequence of resonances up the energy axis; dense ladders (high target spin, many spin groups) blend into each other, sparse ones stay isolated and usable.
resolution function K(t|E): The instrument's own smearing in arrival time — the probability of observing time t for a neutron of true energy E — which broadens every dip on top of the physics.
Ikeda–Carpenter: The standard analytic moderator-emission shape: a t²e^−αt slowing-down rise convolved with a slower storage decay, with R the fraction emitted through the storage channel; causal by construction, unlike a Gaussian.
non-stationary kernel: A blur whose shape changes along the energy axis, so it cannot be applied as a single convolution — convolution assumes the same shape everywhere.
moderator emission delay: The time a neutron spends slowing down inside the moderator before leaking out; because it scales as 1/√E it is mathematically identical to a constant extra flight path, which is why the fitted L must differ from the surveyed one.
anchoring convention: The declared rule for where zero sits inside the resolution kernel — its mode or its mean; without one fixed convention the kernel's position competes with t₀ and L for the same degree of freedom. (A term this document defines.)
t₀ (time offset): The constant tying the recorded clock to the moment the neutrons left; any constant timing error is absorbed exactly into it, so nothing inside the fit can check it and the defining trigger must be stated externally.
black-resonance notch filter: A foil placed in the beam whose saturated resonances let nothing through at known energies, so whatever is counted there is background by construction.
non-PSD covariance: A published covariance matrix that is not positive semi-definite — it implies a negative variance for some combination — and so must be repaired before use, with the repair disclosed.
NRTA: Neutron resonance transmission analysis: reading composition, areal density and temperature from the resonance dips in a transmitted time-of-flight spectrum — the method family this pipeline belongs to.
entry point / public surface: One of the eight named operations that are the only way to drive the pipeline; everything else is either a read-only accessor or does not exist.
contract: The written specification the code must satisfy, treated as authoritative over the code — here the code is validated against the document, never the reverse.
invariant: A property guaranteed to hold of an object at all times — for instance that a reduced spectrum has no energy axis — enforced by how it is built rather than by review discipline.
type-level enforcement: Making a rule violation fail to compile rather than fail at run time; it is what turns "do not skip the gate" from a policy into something that cannot be written.
handle: A reference to an object already recorded in the campaign, passed instead of the values themselves — you cannot invent one, so a step cannot be fed a hand-made input.
registered (content-addressed) identity: An identifier computed from an object's own content by the one component permitted to produce that object, so its origin is verifiable and two identical objects have the same name. (The review records say “minted” — the same thing.)
campaign: To the facility, a campaign is the measurement activity — days of beamtime. In this contract it is also the name of the object that records one: an append-only registry of the campaign’s objects and identities, which is what lets Wednesday’s fit consume Monday’s calibration by reference rather than by copy.
registry: The store inside a campaign that resolves an identity back to the object it names.
producer-restricted constructor: Only one operation may create a given kind of object — only Calibrate produces an instrument posterior — which is what stops a hand-typed covariance from posing as a calibration result. (A term this document defines.)
fail-closed: On a failed check the stage produces nothing at all, rather than continuing with data it has flagged as suspect.
gate: A check that must return a positive verdict before the next stage may run: G3 is the identifiability screen (can this measurement answer the question?), G4 the compatibility gate (does this calibration apply to this run?).
pure accessor: A read-only function computing solely from the object handed to it, taking no other parameters and unable to produce anything the fit consumes; the one category exempt from the closed list of entry points.
pure evaluator: Code with no hidden state, so identical inputs always give identical outputs and thousands of copies can run at once without interfering.
immutable: Once constructed, an object never changes; that property is what makes fanning the same fit out over 262 144 pixels safe without locks or copies.
provenance block: The metadata travelling with every result — library versions, file hashes, object identities, random seeds — carrying enough to reproduce the number bit for bit.
configuration hash: A single fingerprint of the instrument configuration; two runs either match or they do not, so a calibration transfer can be rejected mechanically instead of by judgement.
closed enum / closed variant set: A list of allowed cases fixed in the contract, so no unlisted case can be introduced without changing the contract first.
streamed blocks · stage-then-commit: Writing a multi-gigabyte residual cube out piece by piece while registering the result only once at the end, so an interrupted run leaves nothing half-recorded. (A term this document defines.)
ingest-by-reference: Importing an object from another campaign's store with its content hash re-verified, so identities resolve across campaigns without values ever being copied by hand. (A term this document defines.)
test oracle: An independent source of truth a test compares against — here SAMMY for resolved cross-sections; it is a check on the code, never a target the pipeline is tuned to match.
property test: A test asserting a law the model must obey for all inputs — normalization, causality, conservation — rather than reproducing one stored number.
non-vacuity guard: A pre-check that the test would actually fail if the feature were switched off; without it a passing test may be testing nothing at all. (A term this document defines.)
ratchet clause: Once a tolerance has been achieved it may never be loosened; widening it is a contract change, not a test edit. (A term this document defines.)
CI: The automatic build-and-test run on every proposed change — the place the contract rules are actually enforced rather than merely stated.
thin wrapper (Python bindings): The Python layer exposes the same objects with no logic of its own, so there is only one implementation of the physics to keep correct.
native TOF: Time-of-flight kept in the bins the detector actually recorded — never re-binned and never converted to an energy axis, so the energy scale stays a fitted quantity instead of a baked-in assumption.
dead time · pile-up: After each event a detector is briefly blind (dead time), and two events arriving together can be recorded as one (pile-up); both lose counts as the rate rises, and because sample and open-beam rates differ the losses do not cancel in a ratio.
frame overlap / wraparound: Slow neutrons from one pulse arriving after the next pulse has started, so they are timed as though they were fast neutrons belonging to the following frame.
MCP gain depletion: A microchannel-plate detector loses local gain where it has been heavily illuminated, so its efficiency drifts during a run and across the field.
detector PSF: The point-spread function: one neutron's position is reconstructed with some blur, so neighbouring pixels share information and are not statistically independent.
ROI (region of interest): A group of pixels summed and fitted as a single spectrum, trading spatial detail for counting statistics; its forward model must be the average of exp(−τ), not exp of the average.
whitebox: A design document stating what the software must do and why, so the code can be checked against it — the opposite of a black box whose behaviour is only discoverable by running it.
fitting instance: One concrete run of the shared forward model under a particular pattern of what is solved and what is held by a prior; calibration, density, temperature and in-situ are the four. (A term this document defines.)
PriorPattern: The value inside an experiment definition that says which parameters run free and which carry priors — what makes a “mode” data rather than a separate code path.
ScreenedDefinition: An experiment definition the identifiability screen has approved. It is the only kind the fit engine accepts, and only the screen can produce one. (Named AdmittedDef in earlier review records.)
GatedPosterior: A calibration posterior bound to a non-reject verdict from the compatibility gate. The fit takes this pair, never a bare posterior — so a calibration cannot be used on a run it was never checked against. (Named PairedPosterior in earlier review records.)
ExternalMeasurement: An externally-measured statement of sample state — a thermometry reading, an assayed areal density — ingested with its source and its σ. Science priors reference one of these by identity, so a “known” value can never be a number someone typed in. (Named KnownStateRecord in earlier review records.)
conditional gate verdict: The gate's middle answer: the calibration nearly applies, so it may be used only with an explicit drift model added to the fitted parameters. (Named expanded-drift in earlier review records.)
diagnostic transmission ratio: The transmission ratio (S/Q_s)/(O/Q_o), formed for cross-checking only, and only if every validity test passed — never the domain the reported answer comes from. (Called the diagnostic transmission arm in earlier review records.)
canonical domain: The one domain the reported answer is produced in — counts, under a Poisson likelihood. Everything else on the page is a diagnostic. (A term this document defines.)
validity verdict: The recorded pass or fail of each test deciding whether a diagnostic quantity may be formed and used at all. (Called admissibility verdicts in earlier review records.)
NominalInstrument: The surveyed flight path and nominal time offset read off the instrument record — the instrument as known before any calibration; the calibration posterior supersedes it. Nothing accepts it except the first calibration's reduction, which has no posterior to start from. (Named NominalSeed in earlier review records.)
posterior layer: The per-pixel / per-ROI joint posteriors inside a Results object — the part Fit or Calibrate produces and Assemble consumes. Not a hierarchical-model level. (A term this document defines.)
contracted: Covered by this contract: a contracted type is one whose fields and invariants this document fixes; a contracted object is an instance of one. (A term this document defines.)
resolution-order bound: Resolution broadening does not commute with forming the transmission ratio — dividing two broadened spectra is not the same as broadening the divided one. The resulting bias is bounded by forward simulation with the declared kernel, and the transmission diagnostic may be used only inside that bound. (A term this document defines.)