FastLSQ 0.4.2__tar.gz → 0.6.1__tar.gz

{fastlsq-0.4.2 → fastlsq-0.6.1}/CHANGELOG.md

@@ -2,6 +2,411 @@
 
 All notable changes to FastLSQ will be documented in this file.
 
+## Release tags
+
+Every released version is tagged `vMAJOR.MINOR.PATCH`.  The tags for 0.1.0 through
+0.6.0 were **reconstructed in September 2026**: the project was published to PyPI for
+its first year with only one tag (`v0.2.2`) ever created by hand.
+
+Each tag was placed by comparing the `fastlsq/*.py` sources at every commit in the
+repository against the sdist actually published to PyPI, not by guessing from dates.
+Fourteen of the seventeen published releases matched a commit byte for byte.  The one
+pre-existing tag, `v0.2.2`, was left untouched and independently resolved to the same
+commit the reconstruction chose, which is the main evidence that the method is sound.
+
+Three tags are **approximate**, and their tag messages say so:
+
+| Version | What is wrong | Authoritative artefact |
+|---|---|---|
+| 0.1.2 | The published sdist contains `fastlsq/problems/apebench.py`, which exists in no commit in this repository | `fastlsq-0.1.2.tar.gz` on PyPI |
+| 0.1.3 | Same file, same problem | `fastlsq-0.1.3.tar.gz` on PyPI |
+| 0.1.5 | The published `fastlsq/problems/linear.py` is ahead of every committed version of that file | `fastlsq-0.1.5.tar.gz` on PyPI |
+
+All three were released from a working tree holding source that was never committed.
+For those versions the sdist on PyPI is the record, not the tag.
+
+### Versions documented here that were never released
+
+- **0.2.0** (dated 2026-03-01 below) was never on PyPI and `pyproject.toml` never
+  declared it. The published sequence runs 0.1.4 → 0.1.5 → 0.2.1. There is no `v0.2.0`
+  tag. The entry is kept for the history of the work, not as a release.
+- **0.4.3** and **0.5.0** are real code milestones on `main` -- `pyproject.toml`
+  declares each -- but neither was uploaded. The published sequence runs 0.4.2
+  (2026-07-20) straight to 0.6.0 (2026-07-21). Both are tagged, and both tags say
+  `NEVER PUBLISHED TO PyPI`.
+
+### Releases missing from this file
+
+**0.1.1, 0.1.2, 0.1.3 and 0.1.4 were published to PyPI but have no entry below.**
+They are tagged, and their scope can be read from the tags and the commit history, but
+this file jumps 0.1.0 → 0.2.0 → 0.1.5 and does not describe them. Reconstructing four
+changelog entries a year after the fact would be invention rather than record, so the
+gap is documented here instead of filled in.
+
+## [0.6.1] - 2026-09-18
+
+A correctness and packaging pass. No published number changes, and no API is
+removed -- but three of the fixes below were silent wrong answers, not errors.
+
+### Fixed -- silent wrong answers
+
+- **kernels** -- `SeparableKernelOperator.inner_products` keyed its cache on
+  `(id(basis), n_features)`. A freed basis' address is reused by the next one, and
+  `LearnableFastLSQ.basis` builds a new basis object on every access, so a learnable fit
+  of a Fredholm problem could train on another basis' operators (measured error of the
+  assembled block 0.083 on entries of about 0.05, with no warning). The key is now the
+  storage pointer and version counter of `W` and `b`, plus a weak reference to the basis.
+- **linalg** -- `method="qr"` on a rank-deficient matrix returned garbage with no
+  exception and no warning (`||x|| = 7e18`, residual `6e4`, where `svd` gives `59` and
+  `1e-8`). The diagonal of `R` is now tested against `rcond` and warned about.
+- **learnable** -- `driver="gelsd"` was hard-coded, and torch accepts the rank-revealing
+  LAPACK drivers on CPU only, so the learnable path could not run off CPU. Now CPU-only.
+
+### Fixed -- missing operators
+
+- **augment** -- `AugmentedBasis` gained `hessian_diag`, `biharmonic`, `advection` and
+  `multi_integral`, with the closed forms for the polynomial columns.
+  `MultiIntegralOperator.apply(aug, x)` used to raise `AttributeError`, so the `Wave1D`,
+  `Wave2D_MS` and `Maxwell2D_TM` problems could not take an augmented basis at all.
+- **basis** -- a 0-d (scalar) symbol is a constant multiplier, not an error.
+- **solvers** -- `add_block(scale=...)` accepts a tuple or tensor of per-axis scales, not
+  just a list or ndarray.
+- **newton** -- when no backtracked step satisfied Armijo, the loop restored `beta` and
+  then recomputed the identical step until `max_iter`, while `history` recorded the last
+  alpha tried as if the step had been taken. It now stops, records the rejection as
+  `step_size 0.0`, and tags every exit with a stop reason.
+- **kernels** -- `from_inner_products` objects now raise a clear error from
+  `check_quadrature` and `degenerate_eigenvalues` instead of failing inside `leggauss(0)`.
+
+### Changed -- diagnostics and documentation
+
+- **linalg** -- `return_info` now carries `method_used`, because `"auto"` picks its
+  back-end at run time; on CPU with `mu = 0` it never runs QR (Cholesky probe, then
+  `gelsd`), which the module docstring claimed otherwise. The docstring now describes what
+  the code does.
+- **linalg/api** -- `rank_used` is documented as what it is: a post-hoc count of singular
+  values above `rcond * sigma_max`, not the rank the back-end worked with.
+- **newton** -- the convergence test is relative to the first residual, as the code always
+  did; the docstring said absolute.
+- **kernels** -- `degenerate_eigenvalues` no longer runs a full quadrature for inner
+  products it discards, and its docstring no longer claims the values depend on the basis.
+- **basis** -- the `1/sqrt(N)` normalisation convention is documented, including the
+  differing defaults of `solve_linear` and `solve_nonlinear`.
+
+### Tests
+
+- `test_symbol` used `np.trapz`, removed in NumPy 2, so the fractional-Laplacian check
+  against the singular-integral definition silently never ran on a current install. With
+  `np.trapezoid` the suite goes from 202 passed / 3 failed to 205 passed.
+- New `tests/test_closed_forms_property.py`: 46 property tests checking every closed form
+  against an independent reference (autograd, Gauss-Legendre quadrature, the analytic
+  characteristic value) at random dimensions, feature counts, bandwidths and orders,
+  including the cache-invalidation regression above.
+- `test_version` compared `fastlsq.__version__` against a hard-coded literal, so it had
+  to be edited on every release and never caught anything. It now compares
+  `__version__` against the version in `pyproject.toml`, which is the drift that can
+  actually happen.
+- Full suite: 251 passed.
+
+### Packaging and repository
+
+- **`scipy` is declared as a test dependency.** Eight scripts under `examples/` use it for
+  their reference solvers, and `tests/test_grad_shafranov.py` and `tests/test_grid_swing.py`
+  import those scripts -- but `scipy` appeared only in the `battery` extra, never in `dev`
+  or `requirements.txt`. `pip install -e ".[dev]"` into a clean environment produced six
+  errors; the suite passed locally only where scipy happened to be installed for other
+  reasons. Found by the new CI on its first run.
+- `fastlsq/py.typed` is now actually shipped. `[tool.setuptools.package-data]` had
+  declared it since 0.4.0, but the file did not exist, so the package advertised PEP 561
+  inline typing that type checkers never saw.
+- The build requirement is `setuptools>=77.0`. `license = "MIT"` is the PEP 639 SPDX
+  expression form, which setuptools only understands from 77.0 on; the pin said `>=68.0`.
+- Continuous integration runs the suite on Python 3.9 through 3.12 (`.github/workflows/tests.yml`).
+- The JOSS submission draft (`paper.md`, `paper.bib`) is tracked in the repository.
+- Two 0.5.x changelog entries advertised example scripts under `examples/inverse/` that
+  were never shipped; both entries now say so.
+
+### Fixed -- documentation
+
+- **The citation in `README.md` had the wrong paper title.** It read *"FastLSQ: A
+  Framework for One-Shot PDE Solving"*; the actual title of arXiv:2602.10541 is
+  *"FastLSQ: Solving PDEs in One Shot via Fourier Features with Exact Analytical
+  Derivatives"*. Anyone who copied that BibTeX block produced a wrong bibliography
+  entry. The block now matches the arXiv record and carries the DOI.
+- `paper.bib` cited the same preprint without the `FastLSQ:` title prefix. Corrected to
+  the arXiv title, so the JOSS paper and the README agree.
+
+### Added -- release tags and README
+
+- Release tags for every version, and the *Release tags* section above documenting how
+  they were reconstructed, which three are approximate, and which documented versions
+  were never released.
+- `README.md`: status badges (CI, PyPI, Python versions, licence, arXiv); the
+  dependency and optional-extras list; a **Development** section covering the test
+  suite and CI; a **Releases and versioning** section; and a pointer to the JOSS paper
+  draft.
+
+### Changed -- README
+
+- `README.md`: the BerkeleyLab ATAP talk link moved from above the project title, where
+  it preceded the description, into the **Paper** section with the other references.
+
+## [0.6.0] - 2026-07-21
+
+Completes the operator taxonomy: multi-axis integrals, separable kernels, and
+Fredholm equations, with the integral-equation problems promoted into the same
+`solve_linear` harness as the PDEs so they report in one table.
+
+### New features
+
+| Feature | API | What it buys |
+|---|---|---|
+| Multi-axis integrals | `MultiIntegralOperator`, `SinusoidalBasis.multi_integral` | Integrate over any subset of axes at once, each independently definite or Volterra — area/volume functionals and mixed "definite in space, running in time" memory terms that a single-axis operator cannot express |
+| Separable (degenerate) kernels | `SeparableKernelOperator` | `K(x,y) = Σ g_m(x) h_m(y)` assembles as a rank-`R` product `G @ C`; the inner products `C` are computed once, independent of the collocation points |
+| Fredholm, second kind | `fredholm_second_kind` | `u − λ∫K u = f` as `I − λK`, solved in the same single least squares as everything else |
+| Kernel diagnostics | `degenerate_eigenvalues`, `check_quadrature` | The `λ` at which the equation is singular, and whether the inner-product quadrature actually resolves the basis — both failure modes that otherwise show up only as a bad fit |
+| Integral Problem classes | `fastlsq.problems.integral` | Four integral / integro-differential problems with **closed-form** solutions, running through `solve_linear` |
+
+### Added
+
+- **`MultiIntegralOperator` / `SinusoidalBasis.multi_integral`.** The plane wave
+  factorises over axes, `e^{iW·x} = ∏_k e^{iW_k x_k}`, so a multi-axis integral
+  is a *product* of the same numerically stable one-axis factors already used by
+  `definite_integral`, and the phase collapses to the value at the per-axis
+  midpoint:
+
+      ∫∫ φ_j ∏_{k∈S} dx_k = [∏_{k∈S} Δ_k · sinc(W_k Δ_k / 2π)] · sin(Z_mid)
+
+  Exact, quadrature-free, and finite for near-DC features on every axis. With
+  `|S| = 1` it reproduces `IntegralOperator.definite` bit-for-bit (verified to
+  1e-14); against tensor-product quadrature in 2-D and 3-D it agrees to the
+  quadrature's own error. Order is 1 per axis — a repeated integral along one
+  axis remains `IntegralOperator`, whose Cauchy/Taylor branches handle the
+  small-`W` cancellation a naive repeated product would suffer.
+
+- **`SeparableKernelOperator` (`fastlsq/kernels.py`).** A degenerate kernel
+  collapses the integral operator to `Σ_m g_m(x) ∫ h_m u`, so acting on the
+  basis needs only the `R × N` matrix `C_{mj} = ∫ h_m φ_j`. Assembly is
+  `G(x) @ C` — a rank-`R` factorisation instead of an `M × M` kernel evaluation,
+  and the assembled block's rank is exactly `R` (verified).
+
+  Quadrature enters in exactly one place, computing `C`, and it is a
+  precomputation rather than a per-row cost: tensor-product Gauss-Legendre,
+  spectrally convergent for smooth integrands. Because it must still resolve the
+  feature oscillation, `check_quadrature` reports the achieved convergence
+  (2e-14 for a typical basis; the test suite also pins that it *flags* an
+  under-resolved one), and `from_inner_products` accepts analytic `C` to skip
+  quadrature entirely.
+
+- **`fredholm_second_kind` and `degenerate_eigenvalues`.** Fredholm equations of
+  the second kind assemble as `I − λK`. For a rank-`R` degenerate kernel there
+  are at most `R` characteristic values, at which the equation is singular;
+  `degenerate_eigenvalues` computes them so a near-singular `λ` is detectable
+  instead of silently producing a garbage fit. For `K(x,y)=xy` on `[0,1]` it
+  recovers the analytic `λ = 3` as `3.0000000000000093`.
+
+  Validated against degenerate-kernel theory rather than a reference quadrature:
+  the exact solution of `u − λ∫₀¹xy·u = f` is `u = f + λcx` with
+  `c = ∫yf/(1−λ/3)`, matched to ~1e-8 for `λ` swept from 0.25 to 2.9 (i.e. right
+  up to the singular value). `λ` may be an `nn.Parameter`.
+
+- **`fastlsq/problems/integral.py`.** `FredholmProductKernel`,
+  `FredholmRank2Kernel`, `VolterraSecondKind` and `IntegroDifferentialODE`, each
+  with a closed-form solution, running through `solve_linear` exactly as the PDE
+  problems do — so integral equations now produce a results table alongside the
+  PDEs rather than living only in example scripts. The module docstring writes
+  down the (duck-typed, no base class) Problem contract, which was previously
+  implicit and inconsistent.
+
+  Note the second-kind problems return an **empty** `bcs` list: the identity term
+  makes them well posed with no boundary rows at all. Only the
+  integro-differential ODE, which has a genuine constant of integration, needs
+  one.
+
+- **Accuracy regressions (`tests/test_problems_integral.py`).** Each problem is
+  solved through the real harness and checked against its analytic solution, and
+  separately each closed form is verified to satisfy its own equation by
+  independent quadrature — so a closed form and an operator cannot be wrong in
+  the same direction without being caught.
+
+### Measured
+
+All five integral-equation problems, through `solve_linear` (300 features, 2000
+collocation points), against their closed-form solutions:
+
+| Problem | rel L2 | grad rel L2 | boundary rows |
+|---|---|---|---|
+| Fredholm `K=xy`, λ=0.5 | 5.5e-14 | 5.7e-12 | 0 |
+| Fredholm `K=xy`, λ=2.0 | 3.8e-13 | 3.9e-11 | 0 |
+| Fredholm rank-2, λ=0.4 | 9.1e-14 | 9.5e-12 | 0 |
+| Volterra 2nd kind, λ=1.5 | 8.8e-13 | 1.0e-10 | 0 |
+| Integro-differential ODE, λ=4.0 | 6.2e-16 | 1.7e-14 | 1 |
+
+Approaching the kernel's singular value `λ = 3` costs only ~2 orders of
+magnitude: 5.5e-14 at `λ = 0.5`, 6.8e-13 at `λ = 2.9`, 3.9e-12 at `λ = 2.99`.
+
+### Documentation
+
+- The README now tables the SDF primitives (`sdf_ball`, `sdf_disk`, `sdf_box`,
+  `sdf_annulus`, `sdf_lshape`, `sdf_flower`, `sdf_polygon`, `sdf_tokamak`) and
+  the CSG combinators (`sdf_union`, `sdf_intersection`, `sdf_difference`,
+  `sdf_complement`) by name. They were exported in `__all__` from 0.5.0 but only
+  described in prose, so the composable `ψ`-level API was effectively
+  undiscoverable — you could find `SDFDomain.disk()` but not `sdf_disk`, and the
+  CSG functions not at all.
+- `PolynomialColumns` is likewise named explicitly alongside `AugmentedBasis`.
+
+### Changed
+
+- **Operator composition is now duck-typed.** `IntegroDifferentialOperator._as_terms`
+  and `DiffOperator.__add__` dispatch on the presence of `.apply(basis, x, cache)`
+  rather than a fixed `isinstance` tuple, so operators defined in other modules
+  (`SeparableKernelOperator`, and any user-defined operator) compose with the
+  built-ins without `basis.py` importing them. No change to existing behaviour.
+
+## [0.5.0] - 2026-07-21
+
+Closes three gaps between what the paper describes and what the package shipped:
+SDF geometry (§2.7), Fourier-symbol operators (§3.4), and explicit polynomial
+augmentation columns (§2.3).
+
+### Added
+
+- **SDF / membership-oracle geometry (`fastlsq.geometry`).** A domain can now be
+  given as any callable `ψ(x)` that is negative inside — no mesh, no analytic
+  sampler. `sample_sdf` rejection-samples the interior (unbiased, so the radial
+  CDF of a disk is exactly `r²`), `project_to_boundary` lands points on `ψ = 0`,
+  and `outward_normal` returns `∇ψ/‖∇ψ‖` via autograd, which is what a Neumann or
+  Robin condition needs. `SDFDomain` bundles these with a bounding box and CSG
+  composition (`|`, `&`, `-`), plus `neumann_rows` / `robin_rows` that contract
+  the analytic basis gradient against the normal into an `(M, N)` block.
+
+  Shipped domains: `disk`, `ball`, `box`, `annulus` (multiply-connected),
+  `lshape` (reentrant corner), `flower` (smooth non-convex), `polygon`, and
+  `tokamak` — the D-shaped Miller poloidal cross-section, at the same MAST-U
+  scale (`R ∈ [0.6, 1.4]`) as `examples/grad_shafranov.py`, which until now used
+  a plain rectangle.
+
+  Projection is **damped** Newton, `x ← x − ψ∇ψ/‖∇ψ‖²`, with per-point
+  backtracking and monotone acceptance. The `1/‖∇ψ‖²` normalisation matters:
+  the textbook `x − ψ∇ψ` is valid only for a true distance function, and
+  `sdf_flower` has `‖∇ψ‖` spanning 1 to ~10. Undamped, it left 
+  `|ψ| ≈ 1.5e-1` on the boundary; damped and monotone, 99.9% of interior seeds
+  converge to `1e-10`. The residual failures are seeds within `r < 0.2` of the
+  centre, where a non-distance `ψ` has no unique nearest boundary point;
+  `sample_boundary_sdf` filters them rather than hiding them.
+
+- **`SymbolOperator` — Fourier-multiplier (nonlocal) operators.** Every feature
+  is a plane wave, so a multiplier `L e^{iξ·x} = m(ξ) e^{iξ·x}` acts *diagonally*
+  on the basis: assembling `L` is a per-column rescale, exact to machine
+  precision, with no quadrature and no discretisation of the kernel. Operators
+  that are hard for mesh methods — the fractional Laplacian is nonlocal with a
+  singular kernel, giving a dense ill-conditioned FEM/FD matrix — cost exactly
+  what the Laplacian costs here.
+
+  Factories: `fractional_laplacian(s)`, `riesz_potential(s)`,
+  `riesz_transform(k)`, `convolution(k̂)`. The order `s` may be an
+  `nn.Parameter`: the symbol is `exp(s·log‖ξ‖²)`, so gradient descent recovers a
+  planted order (test recovers `s = 0.65` to `<1e-3`). Composes with `Op` and
+  `IntegralOperator` through the usual arithmetic.
+
+  Verified against independent references, not just self-consistency: `s=1`
+  reproduces `−Δ` and `s=2` reproduces `Δ²` bit-exactly; the symbol is checked
+  against the **singular-integral definition** including its normalising constant
+  `C(1,s)`; and Gaussian convolution matches direct quadrature to `<1e-8`.
+
+  `ConvolutionOperator` is `SymbolOperator.convolution(k̂)` — this is what
+  `examples/memory_diffusion.py:80` was doing by hand with a `(1, N)` broadcast
+  coefficient. That hand-rolled version uses `basis.W[0:1, :]`, correct only
+  because `d=2` has exactly one spatial axis; a symbol sees all of `W` and
+  generalises to any dimension.
+
+- **Polynomial / DC augmentation columns (`fastlsq.augment`).** `AugmentedBasis`
+  widens a basis with explicit `1, x, x², …` columns carrying **exact** operator
+  images — analytic monomial derivatives, antiderivatives (a negative multi-index
+  integrates: `x^p → x^{p+1}/(p+1)`), and Cauchy iterated integrals — not a
+  zero-derivative stub. It implements the same duck-typed protocol as
+  `SinusoidalBasis`, so `Op`, `IntegralOperator` and `SymbolOperator` all work
+  unchanged and return `(M, N + n_cols)`.
+
+  This is what §2.3 means by an integration constant "pinned by an explicit
+  polynomial column"; previously the only such column in the repo was hand-rolled
+  in `examples/extras/scenarios/s01_beamloss_ode.py`, which had to maintain its
+  derivative block by hand.
+
+  Scope, honestly: a sinusoidal bank with random phases can already approximate a
+  constant from near-DC features, so this is an improvement, not a rescue — on
+  `u'' = f` with a DC offset it is neutral at `C = 0` and ~12× better at
+  `C = 1000`. A non-constant monomial has no function-valued Fourier-multiplier
+  image, so `SymbolOperator` on `degree > 0` columns raises rather than inventing
+  a value.
+
+### Fixed
+
+- **`ProjectionOperator`'s docstring claimed the Fourier-symbol operators were
+  "already in the package".** They were not, until this release. It now points at
+  `SymbolOperator` and states the actual distinction (a symbol acts diagonally;
+  a projection row mixes features).
+
+### Notes
+
+- **Which fractional Laplacian.** The symbol calculus applies the multiplier to
+  the global plane-wave extension of the trial function, so
+  `fractional_laplacian` is the **whole-space (restricted)** `(−Δ)^s` on `R^d`,
+  *not* the spectral or regional variant defined by an eigenbasis of a bounded
+  domain. These coincide on `R^d` and differ on a bounded domain. Results should
+  not be read as the spectral fractional Laplacian.
+
+- Boundary points from `sample_boundary_sdf` are **not** uniform with respect to
+  surface measure — they are the pushforward of the uniform box measure under the
+  projection, which over-weights convex bulges. Fine for collocation; do not use
+  them as quadrature nodes for a surface integral without reweighting.
+
+## [0.4.3] - 2026-07-20
+
+### Fixed
+
+- **The Σ-learner trained uphill: `train_bandwidth` now uses the exact envelope
+  gradient.** The outer loss was backpropagated *through* `torch.linalg.lstsq`,
+  whose backward carries a `(AᵀA)⁻¹` and therefore squares `cond(A)`. For a
+  routine collocation system (`cond(A) ≈ 2.2e11` on the `AnisoPoisson` benchmark)
+  that needs ~5e22 of dynamic range, far past float64. Measured against central
+  finite differences at the isotropic init, the resulting "gradient" was **4.3e6×
+  too large with `cos(angle) = −0.707`** — an *ascent* direction, which `AdamW`
+  duly followed (`clip_grad` rescaled the magnitude but preserved the direction).
+  `fit()` consequently returned a solution ~3.6× *worse* than the isotropic
+  `solve_linear` baseline it is meant to beat.
+
+  The inner solve is now performed under `no_grad` and only the assembled `A(L)`
+  is differentiated. This is **exact, not an approximation**: for
+  `J(L) = ‖A(L)β* − b‖²` the chain-rule contribution through `β*` is
+  `2 (Aᵀr)ᵀ dβ*/dL`, and `Aᵀr = 0` at the least-squares optimum (the residual is
+  orthogonal to `range(A)`), so the term vanishes identically and
+  `dJ/dL = 2 rᵀ (dA/dL) β*` — the envelope (Danskin) theorem. The detached
+  gradient matches finite differences to **1.2e-3 relative, `cos(angle) = 1.0000`**,
+  and skips the ill-conditioned backward entirely.
+
+  On the `AnisoPoisson` benchmark the training loss now descends monotonically
+  (`1.9e-3` → `9.8e-11`) instead of climbing (`1.9e-3` → `1.2e+05`), an
+  independent held-out collocation draw tracks it the whole way (no overfitting),
+  and the learned Σ reaches `4.4e-8` against the isotropic `solve_linear`
+  baseline's `1.9e-4` — **~4350× better**, where it was previously ~3.6× *worse*.
+  Not backpropagating through the solve also makes each step ~6× cheaper
+  (`tests/test_learnable.py`: 389s → 57s).
+
+  Note this is the *third* attempt at this bug (see 0.2.1 and 0.2.2): both earlier
+  fixes swapped the inner solve's driver (`svd` → rank-revealing `gelsd`) to stop
+  the gradient being `NaN`. That made it **finite but never correct** — the loop
+  still differentiated through the solve. Differentiating through an
+  ill-conditioned least-squares solve is not stabilisable by choice of driver;
+  the envelope identity removes the need to do it at all.
+- **`train_bandwidth` restored the wrong "best" iterate.** `best_params` was
+  snapshotted *after* `optimizer.step()`, so it stored `θ_{t+1}` while recording
+  `loss(θ_t)` — the best-iterate restore returned the successor of the best
+  iterate. The snapshot (and the `history` entry's `sigma` / `cov_diag`, which had
+  the same off-by-one) now happens before the step, so all three describe the same
+  point.
+
 ## [0.4.2] - 2026-07-20
 
 ### Fixed
@@ -105,8 +510,10 @@ All notable changes to FastLSQ will be documented in this file.
   Gauss--Hermite quadrature of the slice integral to machine precision in d = 2, 3, 4
   (≤4e-13 observed), that autodiff of the rows wrt `c` matches finite differences, and
   that a windowed field is recovered from its projections at several directions in one
-  LSQ. `examples/inverse/tomography_projection.py` demonstrates the full reconstruction
-  plus the differentiable-optics gradient.
+  LSQ. *(Correction, 0.6.1: this entry also announced an
+  `examples/inverse/tomography_projection.py` demonstrating the full reconstruction plus
+  the differentiable-optics gradient. That example was never shipped; the reconstruction
+  and the gradient check live in `tests/test_projection.py` instead.)*
 
 ### Scope (honest)
 
@@ -145,9 +552,11 @@ All notable changes to FastLSQ will be documented in this file.
   linear-least-squares design matrix; coefficients stay differentiable so learnable
   integral-term coefficients train through the solve. All three exported from `fastlsq`.
 - **Examples** `examples/integro_differential_demo.py` (one-shot forward solve of
-  `u'(x) + ∫_0^x u ds = f`, rel-L2 ~3e-11) and
-  `examples/inverse/inverse_memory_kernel.py` (recover an unknown memory strength λ from
-  noisy data via AdamW through the differentiable solve). New `tests/test_integral.py`
+  `u'(x) + ∫_0^x u ds = f`, rel-L2 ~3e-11). *(Correction, 0.6.1: this entry also
+  announced an `examples/inverse/inverse_memory_kernel.py` recovering an unknown memory
+  strength λ from noisy data via AdamW through the differentiable solve. That example was
+  never shipped; gradient flow through the solve is covered by `tests/test_integral.py`.)*
+  New `tests/test_integral.py`
   asserts ∫-then-∂ round-trips to identity, Volterra/definite match quadrature, the DC
   guard stays finite, and gradients flow to learnable coefficients.