Make the model the source of truth for bounds+priors; steer TOML to experiment-only overrides (docs + guardrails)

[vsbuffalo]

Summary

Bounds and priors for an estimated parameter can be declared in two places:

• the model parameters {} block — p : rate in [lo, hi] ~ dist(...), and
• the fit TOML [estimate].<p> — bounds = [...], prior = { ... }.

In practice this two-layer setup is a footgun, and the docs/examples steer users
(and coding agents) toward the TOML layer, which is the wrong default. Proposal:
make the model file the canonical source of truth for bounds + priors, document
it explicitly, and reserve the TOML [estimate] block for experiment-specific
overrides (a narrowed bound for a sensitivity run, a swapped prior for one
experiment) — not for defining priors/bounds on every basic fit. Plus a couple of
guardrails so the divergence can't stay silent.

Where this bit us (Garki DMT methods test, real session)

Concrete costs, all from priors/bounds living in the TOML instead of the model:

1. init = "from_prior" was silently unusable. It reads priors from the model
   ~ declarations only (per docs/inference.md), not from [estimate].prior.
   Because our priors were in the TOML, the boundary-safe init couldn't see them,
   so we were pushed onto uniform_unconstrained — which repeatedly started chains
   in this model's large 2-observation-stream extinction -inf region, where
   they got stuck for the entire warmup (2/4 chains at ll = -inf, 0% acceptance,

   1000 steps). Moving the priors into the model made from_prior usable. Nothing
   warned that the TOML priors were being ignored by the init.

2. Silent bounds divergence. The model declared g : rate in [0.001, 1.0]
   while the TOML overrode bounds = [0.01, 0.5]. Two disagreeing sources, no
   diagnostic; easy to lose track of which is authoritative (and which the init /
   transform actually uses).

3. Prior/bounds coupling surfaces late. A beta prior requires the param's
   bounds to be exactly [0, 1]; a probability param narrowed to [0.02, 0.99]

   • beta fails only at fit-run time:
     error: parameter 'qgam': beta prior requires bounds [0, 1], got [0.02, 0.99].
     Correct as a rule, but it's a late, interface-level trap that a model-first
     convention (declare the beta-prior param once, on [0,1]) would make obvious.

The through-line: a coding agent (me) copied the [estimate].prior pattern from
the fit-toml examples, and inherited all three problems. The model-first path
would have avoided them.

Requests

Docs (primary). State the convention explicitly in docs/fit-toml.md and
docs/inference.md:

A parameter's bounds and prior belong in the model (p : kind in [lo,hi] ~ dist(...)) — that is the definition used by every fit. The fit TOML
[estimate] block should only name which params are estimated, and is for
experiment-specific overrides (a tighter bound for a sensitivity sweep, a
different prior for one experiment) — not for (re)defining priors/bounds on
ordinary fits.

Right now the fit-toml examples feature [estimate].<p>.prior prominently, which
teaches the TOML-first pattern by example. Add the model-first steer, and ideally
recast the canonical example so [estimate] is just g = {} / a name list with
the bounds+prior in the model.

Guardrails (secondary, optional but high-value):

• Warn when a TOML [estimate] entry redefines a bound/prior already declared in
  the model — surface the divergence and which one wins.
• Warn loudly when init = "from_prior" is active and any estimated param's prior
  exists only in the TOML (currently silent — the init just falls back to
  bounds-uniform for that param). At minimum, name the params it couldn't find a
  model prior for.
• (Maybe) let from_prior fall back to the TOML prior, or document firmly that it
  never will.

Assessment (requested)

Agree — this would materially help the workflow. It matches the "the model is
the program" design (the model should be the self-contained source of truth), and
it removes an entire class of two-layer confusion we hit repeatedly in one session
(the from_prior foot-gun above cost the most). Model-first also makes the models
reproducible and portable on their own, and keeps the TOML to what it's actually
good at: naming an experiment and overriding one thing for it.

Filed from the camdl-garki methods test.

[vsbuffalo]

Refinement: the guardrail is narrow-only, and it should be a hard error

The "warn when the TOML redefines a model bound" guardrail above is too broad in
one direction and too soft in the other. Sharpening it:

Narrowing is the intended use, not a divergence. A [estimate.p] bounds
override that is a subset of the model's declared range is exactly what the
TOML layer is for (restrict a scout, pin a sensitivity sweep). That case should
stay silent — warning on it would train users to ignore the warning.

Widening is the footgun, and it should be a hard error, not a warning. When
the TOML bounds fall outside the model's declared range, the two sources
disagree about the science and the TOML silently wins. Per our error-quality bar
("hard errors with hint text over warnings — warnings are noise an agent will
suppress and a non-specialist will skim"), this is an error:

error[E4xx]: fit.toml widens the declared bounds of parameter 'g'
  model declares   g : rate in [0.001, 1.0]
  [estimate.g]     bounds = [0.01, 2.0]   ← 2.0 > 1.0
  a fit.toml bounds may only NARROW the model's range, never widen it.
  fix: to search a wider range, widen the declared bounds in the model
       (`g : rate in [0.001, 2.0]`) — that change is visible in the model,
       travels with it, and re-keys the run identity.

The rule: toml.lo >= model.lo && toml.hi <= model.hi. Anything else errors.

Where. At the point the resolved [estimate].bounds meets the compiled
model's Estimated.bounds — the same seam that already carries the model's
declared range into the fit config. This is a bounds-vs-bounds check; the
existing params_resolver.rs check is value-vs-bounds (a start outside the
range), a different guard.

Docs (done). The rule is now stated in two agent-facing places:

• docs/fit-toml.md (bounds row): "a fit.toml bounds may only narrow it, never loosen."
• docs/agents.md idioms: "A fit.toml bounds may only narrow the model, never
  widen it" — with the fix (edit the declared bounds in the model).

The docs are currently aspirational — nothing enforces narrow-only yet. This
issue's enforcement is what makes them true.

[vsbuffalo]

Correction: the widen guardrail already exists (my previous comment was wrong)

My comment above said "nothing enforces narrow-only yet." That's incorrect — I
described from an incomplete grep instead of reading the resolution seam. The
hard error is already there.

build_if2_params_from_specs in rust/crates/cli/src/fit/runner.rs rejects a
fit.toml [estimate].bounds that falls outside the model's declared bounds:

let (lo, hi) = match (spec.bounds, ir_param.bounds()) {
    (Some((flo, fhi)), Some((mlo, mhi))) => {
        if flo < mlo || fhi > mhi {
            return Err(format!(
                "estimate.{}: fit.toml bounds [{}, {}] lie outside \
                 model bounds [{}, {}]. A fit can tighten bounds but \
                 not loosen them — model bounds may reflect physical \
                 constraints. Either widen the model bounds or \
                 tighten the fit bounds.",
                spec.name, flo, fhi, mlo, mhi));
        }
        (flo, fhi)
    }
    ...
};

It's universal across the inference matrix: fit run builds the estimated
params once (runner.rs:271, build_if2_params → build_if2_params_from_specs)
and hands the same if2_params to IF2 / PGAS / PMMH; survey and profile call
the checked builder directly. No method has a bypass. Tests:

• fit_bounds_outside_model_bounds_rejected — widen [-0.5, 2.0] past model
  [0.0, 1.0] → error contains "outside model bounds".
• fit_bounds_tighten_estimated_param_lower_upper — narrow [0.1, 0.5] inside
  [0.0, 1.0] → accepted (narrowing is the intended use).
• fit_bounds_none_falls_back_to_model_bounds — no override → model bounds.

So the widen direction of this issue's "silent bounds divergence" is already
resolved. Two things remain open under gh#369, both distinct from the widen
error:

1. Narrowing is silent by design. A fit.toml that tightens a bound emits no
   diagnostic. That's the intended workflow (a narrowed scout / sensitivity
   sweep), and warning on it would train users to ignore the warning — so this is
   working as intended, not a gap. (This is the case in the issue's g example:
   [0.01, 0.5] ⊂ [0.001, 1.0] is an allowed narrowing.)
2. The prior-side asks are untouched — init = "from_prior" reading model
   ~ declarations only, and the beta-prior/bounds coupling surfacing late.
   Those are the real remaining work here.

Docs updated to match reality (PR #427): the docs/agents.md idiom now names the
actual rejection error and the fix (widen the model, not the config), rather than
implying the divergence is silent.