Phase 8: split Environment into spec + FittedEnvironment

[edeno]

Summary

Phase 8 (final phase) of the review-findings stack. Eliminates the Environment footgun the full-repo review flagged: a single 1700-LOC dataclass that fused input parameters with eleven _-suffixed Optional fitted fields plus an _is_fitted flag, so a freshly-constructed Environment could be read as if fitted (returning Nones), and downstream code guarded with scattered if env.X_ is None: raise checks.

Stacked on #37 (test-coverage-gaps). Review/merge #29 → #30 → #33 → #34 → #35 → #36 → #37 first.

What changed

• Environment is now purely the user-facing input specification — its constructor signature and public name are unchanged, so existing user code and notebooks keep working (from non_local_detector import Environment).
• Environment.fit_place_grid(position) returns a new FittedEnvironment instead of mutating self in place. The resolved spatial grid (edges_, place_bin_centers_, is_track_interior_, distance_between_nodes_, ...) and the spatial-query methods (get_bin_ind, get_manifold_distances, get_distances_to_interior_bins, get_direction, plot_grid, save_environment) live on FittedEnvironment.
• The _is_fitted flag and the eleven Optional fitted fields are gone — "fitted" is now a type, not a mutable flag.
• models/base.py:initialize_environments captures the returned FittedEnvironment into self.environments (re-fitting from the original spec so re-fit is correct). Detector usage is unchanged.
• Likelihood/transition boundary guards use getattr(env, "place_bin_centers_", None) so an unfitted spec still yields the helpful "fit first" ValueError rather than a raw AttributeError.
• make_nD_track_graph_from_environment takes explicit arrays instead of a half-built self.
• FittedEnvironment exported at the package top level alongside Environment.

Decisions / scope

• Public name kept as Environment (per maintainer decision) rather than renaming to EnvironmentSpec — avoids breaking every downstream analysis and notebook. Achieves the plan's goal without the breaking rename.
• FittedEnvironment is a regular (non-frozen) dataclass — the existing lazy _bin_distance_matrix_ cache is set after construction, which frozen=True would forbid. Immutable in spirit (no _is_fitted, no Optional-then-mutate).
• Deferred (documented, not regressions): frozen continuous-transition dataclasses (8.8, requires removing self.environment assignments first); notebook updates (plan scoped to a follow-up); full is-None guard sweep in internal-only call sites (distance2D, deep models/base.py) — those are reached only post-fit.

Test plan

• golden regression — 4 pass, bit-identical (refactor is structural, not numerical)
• snapshot — 8 pass, no diffs
• new test_environment_spec.py — 9 contract tests (spec has no fitted attrs; fit returns FittedEnvironment; fit does not mutate spec; spec hashable; read-only forwarded params)
• broad pytest -m "not slow" — 907 passed, 5 skipped, 1 xfailed, 0 failures
• ruff check + ruff format --check clean

🤖 Generated with Claude Code