glmm 0.1.0__tar.gz

glmm-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,160 @@
+name: CI
+
+# Single-crate mirror of the MCPower engine's `rust` job, plus the three gates a
+# standalone publishable crate needs: an MSRV floor check, a wasm compile (the
+# crate ships a cfg(wasm32) faer split), and a publish dry-run so `main` is always
+# in a releasable state.
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+  # Let release.yml reuse these exact gates before publishing (single source of truth).
+  workflow_call:
+
+# Newer pushes supersede in-flight runs on the same ref.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  # ── fmt + clippy + the regex-free-kernel guard, on stable ─────────────────
+  # Split out from the #[test] suite so the four feature-variant test runs can
+  # go wide in a matrix (below) instead of recompiling serially behind clippy.
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: fmt
+        run: cargo fmt --all -- --check
+      - name: clippy
+        # The crate's workspace lints set clippy::all = deny, so a plain clippy
+        # run is the correctness gate — no extra `-- -D warnings` needed.
+        run: cargo clippy --all-targets
+      - name: guard — the default-off kernel links no regex
+        # `formula` is on by default (semver-covered surface), so the kernel's
+        # regex-free property is no longer structural — this assertion IS the
+        # guarantee. See GLMM.md's dependency-direction decision.
+        run: |
+          if cargo tree -e normal -p glmm --no-default-features | grep -q regex; then
+            echo "::error::default-off kernel pulls in regex — the formula feature is leaking"
+            cargo tree -e normal -p glmm --no-default-features | grep -B5 regex
+            exit 1
+          fi
+          echo "Kernel is regex-free with default features off."
+
+  # ── the full #[test] suite across all four feature configs, in parallel ───
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      # The dhat bounded-allocation gates assert exact alloc counts; faer/rayon
+      # multi-thread jitter perturbs them, so pin the pool to one thread.
+      RAYON_NUM_THREADS: 1
+    strategy:
+      # A failing feature config must not cancel the others — we want every
+      # leg's result on one push, not just the first to break.
+      fail-fast: false
+      matrix:
+        # Each entry is one recompile-and-test on its own runner:
+        #   default        — the semver-covered surface.
+        #   loop_advanced  — unstable scratch-explicit surface, off by default;
+        #                    must still compile+pass so the hot-path consumer
+        #                    never breaks silently.
+        #   parallel       — rayon in-fit parallelism (AGQ cluster loop), off by
+        #                    default; includes the bit-identity test pinning it
+        #                    to the serial path's exact output.
+        #   no-default     — the parse-once/fit-many formula-free kernel; the
+        #                    formula tests are #![cfg(feature = "formula")] and
+        #                    skip themselves.
+        include:
+          - { name: default, flags: "" }
+          - { name: loop_advanced, flags: "--features loop_advanced" }
+          - { name: parallel, flags: "--features parallel" }
+          - { name: no-default, flags: "--no-default-features" }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: test (${{ matrix.name }})
+        run: cargo test ${{ matrix.flags }}
+
+  # ── MSRV floor: the bobyqa dep pins rust-version = 1.85 ───────────────────
+  msrv:
+    name: msrv (1.85)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@1.85
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo check --all-targets
+
+  # ── wasm: keep the cfg(wasm32) faer config honest ─────────────────────────
+  wasm:
+    name: wasm
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo check --target wasm32-unknown-unknown
+      - name: check (parallel feature, must be inert on wasm)
+        # rayon is target-dep-excluded on wasm32, so the feature must compile to
+        # a no-op here, never pull rayon in or break the build.
+        run: cargo check --target wasm32-unknown-unknown --features parallel
+
+  # ── package: gate the publishable state on every push ─────────────────────
+  package:
+    name: publish dry-run
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo publish --dry-run
+
+  # ── python: build the glmm wheel, install it, test + lint (spec §7) ───────
+  python:
+    name: python (glmm wheel)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel (abi3, Linux x86_64)
+        uses: PyO3/maturin-action@v1
+        with:
+          working-directory: python
+          command: build
+          args: --release --out dist
+      - name: Install the built wheel (non-editable, catches packaging mistakes)
+        run: pip install --find-links python/dist glmm
+      - name: Install test + lint deps
+        run: pip install pytest ruff
+      - name: pytest against the installed wheel, run outside the source tree
+        run: |
+          cd "$RUNNER_TEMP"
+          python -m pytest "$GITHUB_WORKSPACE/python/tests" -v
+      - name: ruff check
+        run: ruff check python/
+      - name: ruff format --check
+        run: ruff format --check python/

glmm-0.1.0/.github/workflows/publish-r-universe.yml

@@ -0,0 +1,61 @@
+name: Publish (r-universe)
+
+# Publishes fastglmm to r-universe. r-universe builds straight from a git ref
+# via `R CMD build`, which strips out-of-package path deps (r/ depends on
+# ../glmm-r, which depends on ../ — the glmm kernel), so it cannot build the
+# repo tree directly. Instead this workflow runs cran-tarball.sh --vendor to
+# stage the self-contained, offline-vendored package and force-pushes that
+# staged tree as the *root* of an orphan `r-universe` branch. r-universe's
+# registry (a separate repo the user controls) points at that branch; it
+# notices the ref change and rebuilds. main never holds the vendored tree —
+# the branch is a generated artifact (docs/GLMM/plans/2026-07-16-r-repo-publishing-spec.md).
+on:
+  push:
+    tags: ["r-*"]
+
+jobs:
+  verify:
+    uses: ./.github/workflows/ci.yml
+
+  version-check:
+    name: Verify tag matches r/DESCRIPTION
+    runs-on: ubuntu-latest
+    needs: [verify]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check tag matches DESCRIPTION version
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF#refs/tags/r-}"
+          VERSION=$(grep -m1 '^Version: ' r/DESCRIPTION | cut -d' ' -f2)
+          if [ "$VERSION" != "$TAG" ]; then
+            echo "::error::r/DESCRIPTION has Version: $VERSION, tag is r-$TAG"
+            exit 1
+          fi
+          echo "r/DESCRIPTION matches tag r-$TAG."
+
+  publish-r-universe:
+    name: Stage + push r-universe branch
+    needs: [version-check]
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: write   # force-push the generated r-universe branch with GITHUB_TOKEN
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: r-lib/actions/setup-r@v2
+      - name: Stage self-contained, vendored package
+        run: r/tools/cran-tarball.sh --vendor
+      - name: Force-push staged tree as the r-universe branch root
+        working-directory: target/cran-stage/fastglmm
+        run: |
+          git init -q
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -q -m "r-universe: fastglmm ${GITHUB_REF#refs/tags/r-}"
+          git push --force "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" HEAD:r-universe
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

glmm-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,234 @@
+name: Publish
+
+# One tag, one release: `v*` ships the crate to crates.io AND the Python package
+# to PyPI from the same run. The Python package is a thin wrapper over the crate
+# with no independent version or changelog, so it has no separate cadence.
+#
+# Both indexes use Trusted Publishing (OIDC) — no stored tokens.
+#
+# PREREQUISITES:
+#   - crates.io: crate exists and has a Trusted Publisher pointing at THIS repo +
+#     release.yml + the `release` environment. (No pending-publisher flow there,
+#     so 0.0.1 was published manually; this covers 0.0.2+.)
+#   - PyPI: a pending publisher for project `glmm` bound to this repo +
+#     release.yml + the same `release` environment (shared with crates.io —
+#     protection rules on it gate both uploads).
+on:
+  push:
+    tags: ["v*"]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  # Run the full CI suite (fmt + clippy + test + msrv + wasm + publish dry-run)
+  # against the tagged commit. Everything downstream is gated on this — a tag that
+  # fails any gate never reaches an index.
+  verify:
+    uses: ./.github/workflows/ci.yml
+
+  # The three versions are lockstep-coupled but otherwise enforced only by a
+  # comment in pyproject.toml. This makes drift a release-time failure.
+  version-check:
+    name: Verify tag matches all three versions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check 3-way version lockstep
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          fail=0
+          check() {  # $1 = found version, $2 = file it came from
+            if [ "$1" != "$TAG" ]; then
+              echo "::error::$2 has version '$1', tag is '$TAG'"; fail=1
+            fi
+          }
+          CRATE=$(grep -m1 '^version = ' Cargo.toml | cut -d'"' -f2)
+          PYCRATE=$(grep -m1 '^version = ' glmm-python/Cargo.toml | cut -d'"' -f2)
+          PYPROJ=$(grep -m1 '^version = ' python/pyproject.toml | cut -d'"' -f2)
+          check "$CRATE" Cargo.toml
+          check "$PYCRATE" glmm-python/Cargo.toml
+          check "$PYPROJ" python/pyproject.toml
+          [ "$fail" = 0 ] || exit 1
+          echo "All three at $TAG."
+
+  build_wheels:
+    name: Build & test wheel (${{ matrix.target }} on ${{ matrix.os }})
+    needs: [verify, version-check]
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # One abi3 wheel per platform (abi3-py310 → no per-Python matrix), built
+        # AND tested on its own hardware so no wheel ships untested. macOS is
+        # Apple Silicon only: the Intel macos-13 runner was retired Dec 2025 —
+        # Intel Macs fall back to the sdist.
+        # Linux is also built+tested by ci.yml's python job (via verify) —
+        # deliberate: that job gates every push, this one produces the release
+        # artifact with the manylinux tag. Don't deduplicate.
+        include:
+          - { os: ubuntu-latest,  target: x86_64,  manylinux: '2_28' }
+          - { os: macos-latest,   target: aarch64 }
+          - { os: windows-latest, target: x64 }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      # maturin-action, not cibuildwheel: pyproject's manifest-path reaches out to
+      # ../glmm-python, which depends on ... cibuildwheel mounts
+      # only the package dir, so those paths would not resolve; this mounts the
+      # whole workspace.
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          # manylinux applies to the Linux entry only; 'auto' is a no-op on the
+          # macOS/Windows entries that omit it.
+          manylinux: ${{ matrix.manylinux || 'auto' }}
+          working-directory: python
+          args: --release --out dist
+      - name: Verify native extension + license are in the wheel
+        shell: bash
+        run: |
+          python - <<'PY'
+          import glob, sys, zipfile
+          wheels = glob.glob("python/dist/*.whl")
+          assert wheels, "no wheel built"
+          for whl in wheels:
+              names = zipfile.ZipFile(whl).namelist()
+              if not any("_native" in n for n in names):
+                  sys.exit(f"::error::native extension (_native) missing from {whl}")
+              lic = [n for n in names if n.endswith("dist-info/licenses/LICENSE")]
+              if not lic:
+                  sys.exit(f"::error::LICENSE missing from {whl}")
+              body = zipfile.ZipFile(whl).read(lic[0]).decode()
+              # python/LICENSE must stay a real copy, never a symlink to ../LICENSE:
+              # Git for Windows does not materialize symlinks without core.symlinks,
+              # which actions/checkout does not set, so the runner would embed the
+              # 10-byte string "../LICENSE" as the GPL text. This catches that.
+              if "GNU GENERAL PUBLIC LICENSE" not in body:
+                  sys.exit(f"::error::LICENSE in {whl} is not the GPL text")
+              print(f"  ok: {whl}")
+          PY
+      - name: Install the built wheel and run the suite
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install python/dist/*.whl
+          python -m pip install pytest
+          # Scratch dir + absolute tests path: `import glmm` must resolve to the
+          # installed wheel, never python/glmm/ in the source tree.
+          cd "$RUNNER_TEMP"
+          python -m pytest "$GITHUB_WORKSPACE/python/tests" -v
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}-${{ matrix.target }}
+          path: python/dist/*.whl
+
+  build_sdist:
+    name: Build & test sdist
+    needs: [verify, version-check]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      # Plain maturin, not maturin-action: an sdist needs no manylinux container,
+      # so the action's container machinery buys nothing here. (The build only
+      # archives sources; the Rust toolchain above is for the install step below.)
+      - name: Build sdist
+        working-directory: python
+        run: |
+          python -m pip install "maturin>=1.9,<2.0"
+          maturin sdist --out dist
+      # The sdist is the only install path for Intel Macs and Linux aarch64, so it
+      # gets the same gate as the wheels: install it (a real source build — hence
+      # the Rust toolchain above) and run the suite.
+      - name: Install from the sdist and run the suite
+        shell: bash
+        run: |
+          python -m pip install python/dist/*.tar.gz
+          python -m pip install pytest
+          cd "$RUNNER_TEMP"
+          python -m pytest "$GITHUB_WORKSPACE/python/tests" -v
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: python/dist/*.tar.gz
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    environment: release       # must match the PyPI trusted-publisher config
+    permissions:
+      id-token: write          # mints the OIDC token PyPI verifies
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist/
+      - name: Flatten artifacts
+        run: |
+          mkdir -p dist-flat
+          find dist/ \( -name '*.whl' -o -name '*.tar.gz' \) -exec cp {} dist-flat/ \;
+          ls -la dist-flat/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist-flat/
+          # No skip-existing, unlike the crates.io guard below: on the real index
+          # "file already exists" means the version was not bumped, and that must
+          # fail loudly.
+
+  # Ordered last, after PyPI: both uploads are irreversible, and this way a failing
+  # wheel never leaves a crate release stranded without its Python counterpart. If
+  # this job fails after PyPI succeeded, re-run THIS JOB alone — a full workflow
+  # re-run dies in publish-pypi on the already-uploaded files.
+  publish-crates:
+    name: cargo publish
+    needs: [publish-pypi]
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    # Naming an environment lets you attach required-reviewer / branch protection
+    # to releases. It MUST match the environment set in the crates.io Trusted
+    # Publisher config (or remove it in both places).
+    environment: release
+    permissions:
+      # Required: lets the job request the OIDC identity token crates.io verifies.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # cargo publish has no --skip-existing and hard-fails on an existing version,
+      # so re-running a tag after a transient failure would error instead of
+      # converging. This guard makes it a no-op instead.
+      - name: Skip if this version is already on crates.io
+        id: guard
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          # Sparse-index path for a 4-char crate name: /gl/mm/glmm. One JSON object
+          # per line, one per published version. `curl -f` so a 404 (crate absent)
+          # yields empty rather than an HTML body.
+          PUBLISHED=$(curl -sf https://index.crates.io/gl/mm/glmm | jq -r '.vers' || true)
+          if grep -qx "$TAG" <<<"$PUBLISHED"; then
+            echo "glmm $TAG already on crates.io — skipping publish."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Authenticate to crates.io (Trusted Publishing)
+        if: steps.guard.outputs.skip == 'false'
+        id: auth
+        uses: rust-lang/crates-io-auth-action@v1
+      - name: Publish
+        if: steps.guard.outputs.skip == 'false'
+        run: cargo publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}

glmm-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+/target
+/Cargo.lock
+dhat-heap.json
+python/venv/
+__pycache__/
+*.egg-info/
+python/build/
+python/.pytest_cache/
+python/glmm/_native*.so
+python/glmm/_native*.pyd
+
+# parity: fixed-seed simulated inputs (regenerated by run.sh --prep; the freeze is
+# the committed seed + prep script, not the bytes) and per-engine result JSONs
+# (regenerated every run). Committed inputs: data_empirical/*.csv (lme4/nlme). Durable
+# summaries live in parity/reports/ and parity/weights/ (not under results/).
+# The flat *.csv fixtures under data_simulated/ are small and committed (cargo
+# test's include_str! depends on them, incl. in CI); only the 429MB grid/
+# campaign dataset is gitignored.
+/parity/data_simulated/grid/
+/parity/weights/data_simulated/
+/parity/results/
+/parity/weights/results/

glmm-0.1.0/CHANGELOG.md

@@ -0,0 +1,191 @@
+# Changelog
+
+All notable changes to the `glmm` crate are recorded here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+The Python package (`glmm` on PyPI) is versioned in lockstep with the crate and
+shares these entries; Python-specific notes are called out where they differ.
+
+## [Unreleased]
+
+## [0.1.0] — 2026-07-16
+
+First release of the Python package (`glmm` on PyPI), and the first crate
+release since `0.0.2`. The breaking changes below are real breaks against the
+published `0.0.2` — `ModelSpec` is now structure-only and the `mcpower` feature
+is renamed `loop_advanced`. `0.0.3` was never published, so it is not a
+migration source.
+
+All four estimators are wired into the stable `fit` dispatch: OLS; GLM
+(Gaussian, binomial logit/probit, Poisson, Gamma, negative binomial); LMM
+(closed-form single-intercept + BOBYQA general); GLMM (dense and sparse-Z, all
+families including NB), with AGQ (nAGQ > 1) for single scalar random effects.
+Validated against R/lme4 and Julia/MixedModels.jl across a 23-rung dataset
+parity manifest plus a 15-rung prior-weights harness.
+
+### Fixed
+
+- **A factor's level order is no longer silently discarded.** `glmm::formula`
+  sorted every factor's levels lexicographically, so the treatment-contrast base
+  was whichever label sorted first, regardless of what the caller asked for. A
+  deliberately ordered categorical — `pd.Categorical(x, categories=["low",
+  "med", "high"])` — was refactored to base `"high"`, returning a different
+  coefficient for a different question with nothing in the output to reveal it.
+  `Column::Factor` now takes `{ levels, codes }`, so the caller states the order
+  and level 0 is the base. Python passes a `Categorical`'s
+  `categories`/`codes` through; a plain string column has no declared order and
+  is sorted by `Column::factor_from_labels` — the same lexicographic default as
+  R's `factor()`, now a default rather than an imposition.
+- Python: a categorical of non-strings (`pd.Categorical([1, 2, 3])`) was
+  classified numeric and fit as one continuous slope instead of expanding to
+  dummies. Column classification now checks the dtype before sniffing values.
+- Python: `summary()` printed `group 0` instead of the grouping's name, and its
+  per-term rows carried no labels — `Lowered::re_groups` was never carried
+  across the PyO3 shim. It now is, and `summary()` prints e.g. `Subject:` with
+  `(Intercept)`/`Days` rows.
+
+### Added
+
+- `glmm::formula` — the R-style formula frontend is now part of the crate,
+  behind the `formula` feature (on by default). `lower("y ~ x + (1|g)", &table,
+  family)` builds the kernel's inputs from a formula string and a data table.
+  Previously an unpublished companion crate, so it was unreachable for anyone
+  installing from crates.io.
+- `default-features = false` gives the formula-free kernel, which links no
+  `regex` — the configuration for parse-once/fit-many hot paths.
+- **`Fit::vcov`** — the full `p×p` fixed-effect covariance `Cov(β̂)`, on every
+  path. `Fit::se` is its diagonal and cannot answer anything about two
+  coefficients jointly, so a contrast, a confidence interval, or anything of
+  `vcov()`/`confint`/`glht`/`emmeans`'s shape needed off-diagonals that were
+  being computed and thrown away (GLMM) or never formed (OLS/GLM/LMM). It is
+  finite exactly where `se` is. Also on the Python `Fit`, as a `(p, p)` array.
+- Python `Fit` gained `n_eval` (optimizer evaluation count), `deviance` (the
+  minimized criterion — **not** comparable across models, see the docs), and
+  `re_groups`. All three were already on the Rust `Fit`; none crossed the shim.
+
+### Changed
+
+- **Python: `theta=` is renamed `init_theta=`.** One call had two unrelated
+  parameters named `theta`: the negative-binomial shape seed and, inside
+  `warm_start={"theta": …}`, the random-effect Cholesky vector. The seed takes
+  the name R already uses for it (`MASS::glm.nb(init.theta=)`);
+  `warm_start["theta"]` is unchanged, matching lme4's `start=list(theta=)`.
+- **Python: `targets=` is removed.** It exposed `FitOptions::target_indices`, a
+  performance knob for MCPower's hot path that leaves non-target SEs `NaN`. That
+  hot path drives the Rust surface directly, where the option is unchanged; no
+  Python caller wants `summary()` printing `NA` for standard errors it could
+  have computed.
+- Python: the native call returns a dict keyed by field name rather than a
+  positional tuple. Internal, but it is why `re_groups`/`n_eval`/`deviance`
+  could go missing unnoticed.
+
+### LMM cold start
+
+#### Changed
+
+- **LMM cold starts now use the unit-diagonal blind seed** (diagonal θ at 1,
+  off-diagonal vech entries at 0 — the lme4/MixedModels convention), on both
+  the dense (`fit_lmm`) and sparse (`fit_mle_sparse`) Gaussian paths. The
+  former start set *every* component to 1; on wide-slope designs (q ≥ 4 with
+  correlated slopes) that start funneled BOBYQA into a second-best local
+  optimum on 8 of 9 adjudicated grid cells (deviance gaps +0.23 to +57.4 vs
+  the best-known optima, now frozen as goldens under `parity/goldens/optima/`).
+  With the new seed the fitted optimum matches or beats MixedModels on all 9.
+  Intercept-only and uncorrelated-slope models have no off-diagonal
+  components and are bit-identical. Full-grid effect vs MixedModels on the
+  gaussian slope stratum: worse-than-MM cells drop 8 → 2 — the two
+  remaining are *new* coin-flips where the old start happened to hold the
+  best-known basin (`lmm_q6_g300p5_bal_base` +0.008,
+  `lmm_q8_g3000p5_bal_lowsnr` +2.03; goldens frozen for both). It also fixes
+  the dense-vs-sparse basin disagreement behind the `noz_sparse_grid_agrees`
+  cell-20 failure. Eval counts on affected wide-slope fits move both ways
+  (grid-wide gaussian-slope total −10%). The sparse non-Gaussian GLMM joint
+  seed already used this shape; the Gaussian paths now match it.
+
+### Prior weights
+
+#### Added
+
+- **`FitOptions::weights`** — per-row prior (case) weights, lme4's `weights=`.
+  An aggregated binomial (y = success proportion, weight = trial count) now
+  fits directly — lme4's `cbind(s, m−s)` objective, which shares its argmin
+  (and so β/SE/varcomp) with the expanded-Bernoulli fit — letting the
+  `sim_sparse_binomial` parity rung fit its 240 aggregated rows instead of the
+  3,059-row Bernoulli expansion. Parity holds at unchanged tolerances; the
+  per-solve O(n·width²) cost collapses accordingly.
+
+#### Changed
+
+- `FitOptions.weights` now supported on all paths (was: sparse binomial GLMM
+  only); nAGQ>1 with weights rejected.
+
+### Two-stage GLMM optimizer
+
+#### Changed
+
+- **GLMM fits now use a two-stage optimizer** (lme4's structure, Bates et al. 2015
+  §3): a fast θ-only search profiles the fixed effects β out per PIRLS iteration,
+  then a short joint (θ, β) polish on the exact Laplace objective warm-started from
+  it. The converged (θ̂, β̂) and all standard errors are unchanged up to optimizer
+  tolerance — the parity goldens hold at their existing tolerances — but the outer
+  evaluation count drops materially (roughly 2× fewer BOBYQA evaluations on the
+  grouseticks 3-crossed Poisson fixture). The prior single-stage joint solve remains
+  available as an internal A/B toggle. `Fit::n_eval` now includes stage-1
+  evaluations, so eval counts are not directly comparable to versions before this
+  change.
+
+#### Added
+
+- **PIRLS step-halving.** The inner penalized-IRLS loop now backtracks (halves the
+  step, up to 10 times) when a full Fisher-scoring step raises the penalized
+  deviance, hardening convergence on ill-scaled joint (u, β) steps; an exhausted
+  backtrack surfaces as the existing non-converged/NaN failure state.
+
+### M3.5 — warm-start entry-split
+
+The fit surface now separates model *structure*, optimizer *warm-start state*, and
+method *knobs* into three distinct places (`docs/GLMM/api.md`, Layers A–C). The
+stable `fit`/`fit_grouped` signatures are unchanged; the breakage is in the shapes
+they consume.
+
+#### Changed (breaking)
+
+- **`ModelSpec` is structure-only.** Removed the method knobs `wald_se` and `nagq`
+  and every magnitude payload — a `ModelSpec` can no longer carry a start estimate.
+  - `ReStructure` and `Grouping` lost `tau_squared` and now hold
+    `slopes: Vec<ColumnId>` (the `SlopeTerm` struct, which bundled a column with its
+    variance/correlation magnitudes, is deleted along with the `re_correlation_*`
+    helpers).
+  - `Family::Gamma` lost its `dispersion: Option<f64>` payload;
+    `Family::NegativeBinomial` lost its `theta: Option<f64>` payload.
+- **`FitOptions` gained the relocated knobs:** `wald_se`, `nagq`, and `dispersion`
+  (the Gamma fix-vs-estimate directive). All are defaulted — construct with
+  `..FitOptions::default()` (Wald SE `Hessian`, `nagq` 1 = Laplace, `dispersion`
+  `None` = estimate φ post-fit). `FitOptions` now implements `Default`.
+- **The stable `fit`/`fit_grouped` cold-start the optimizer** — they no longer derive
+  a warm start from spec magnitudes; the kernels use their `THETA0` blind start. The
+  converged MLE is unchanged up to optimizer tolerance (start-independent), so the
+  oracle goldens stay green at their existing tolerances.
+- **Cargo feature `mcpower` renamed to `loop_advanced`.** Capability-named rather
+  than consumer-named; still off by default, still the unstable scratch-explicit
+  loop-tier surface with no semver guarantees. The `cluster_theta_truth` re-export is
+  removed (truth-start magnitudes no longer live in `ModelSpec`).
+
+#### Added
+
+- **`StartValues { beta, theta }`** — the warm-start primitive (api.md Layer B): raw
+  optimizer state (`beta` = fixed-effect start, `theta` = RE Cholesky parameters),
+  not high-level variances. Exported `pub` only behind the `loop_advanced` feature;
+  the stable tier never takes it. Carries no `phi`/`nb_theta`: Gamma φ is profiled and
+  the GLMM neg-binomial θ search is a global bracket, so neither warm-starts anything
+  reachable through the loop surface.
+
+#### Migration — MCPower pin-bump action
+
+MCPower consumes a pinned published `glmm`, so this rename is not a live break. When
+MCPower next bumps its pinned `glmm`:
+
+- switch its feature selection `mcpower` → `loop_advanced`;
+- build any spec-derived start as a raw `StartValues.theta` (column-major vech of the
+  RE Cholesky parameters) instead of relying on the removed `cluster_theta_truth` /
+  `ModelSpec` magnitude fields.