Rejected experiment: centered TruncatedNormal bounded group priors

docs/changelog.md

@@ -16,7 +16,9 @@
 
 7. **Invalid model-level prior and link presets now fail fast** (#1233). `prior_settings` accepts only `"safe"` or `None`, and `link_settings` accepts only `"log_logit"` or `None`; wrong-case strings, booleans, mappings, and other unsupported values now raise a clear `ValueError` instead of silently changing prior, link, initial-value, or display behavior. The API documentation now clarifies that both presets act on regression parameters: `prior_settings=None` delegates missing regression-term priors to Bambi but leaves HSSM's simple-parameter defaults unchanged. The Poisson-race tutorial has also been migrated to marimo and no longer presents `prior_settings` as a prior dictionary.
 
-8. **Safe priors now preserve a unique unmatched group-only population location and reject ambiguous or unrepresentable specifications** ([#1225](https://github.com/lnccbrown/HSSM/issues/1225)). When HSSM generates a prior for a group term with no exact common Formulae counterpart, the group distribution owns the population location. HSSM therefore preserves its location-bearing hierarchy and centers that generated term even when the model or component requested non-centering, because Bambi's current non-centered construction omits `mu`. For previously generated unmatched Normal terms under default non-centering, this intentionally changes the likelihood by reconnecting the location that Bambi had discarded. Exact common/group matches remain zero-mean deviations and honor the requested parameterization ([#1224](https://github.com/lnccbrown/HSSM/issues/1224)). Repeated unmatched expressions now fail when safe generation has no unique owner. Explicit priors are never rewritten, but HSSM raises before Bambi when a group prior cannot be represented faithfully and warns about buildable centered specifications with multiple free owners of one location. Identity-linked group-only intercepts retain their response-scale hierarchy for every identity spelling ([#1232](https://github.com/lnccbrown/HSSM/issues/1232)); transformed links use a hierarchy on the linear-predictor scale. Follow-ups cover upstream location-aware non-centering ([#1268](https://github.com/lnccbrown/HSSM/issues/1268), [Bambi #1003](https://github.com/bambinos/bambi/issues/1003)), bounded identity group priors ([#1269](https://github.com/lnccbrown/HSSM/issues/1269)), and broader numeric regression-term semantics ([#1271](https://github.com/lnccbrown/HSSM/issues/1271)).
+8. **Safe priors now preserve a unique unmatched group-only population location and reject ambiguous or unrepresentable specifications** ([#1225](https://github.com/lnccbrown/HSSM/issues/1225)). When HSSM generates a prior for a group term with no exact common Formulae counterpart, the group distribution owns the population location. HSSM therefore preserves its location-bearing hierarchy and centers that generated term even when the model or component requested non-centering, because Bambi's current non-centered construction omits `mu`. For previously generated unmatched Normal terms under default non-centering, this intentionally changes the likelihood by reconnecting the location that Bambi had discarded. Exact common/group matches remain zero-mean deviations and honor the requested parameterization ([#1224](https://github.com/lnccbrown/HSSM/issues/1224)). Repeated unmatched expressions now fail when safe generation has no unique owner. Explicit priors are never rewritten, but HSSM raises before Bambi when a group prior cannot be represented faithfully and warns about buildable centered specifications with multiple free owners of one location. Identity-linked group-only intercepts retain their response-scale hierarchy for every identity spelling ([#1232](https://github.com/lnccbrown/HSSM/issues/1232)); transformed links use a hierarchy on the linear-predictor scale. Follow-ups cover upstream location-aware non-centering ([#1268](https://github.com/lnccbrown/HSSM/issues/1268), [Bambi #1003](https://github.com/bambinos/bambi/issues/1003)) and broader numeric regression-term semantics ([#1271](https://github.com/lnccbrown/HSSM/issues/1271)).
+
+9. **Generated identity-linked group locations now honor configured response bounds** ([#1269](https://github.com/lnccbrown/HSSM/issues/1269)). A unique unmatched group-only intercept on a generic parameter receives a centered native hierarchical `TruncatedNormal` whenever at least one response bound is finite. The generated population-location hyperprior and group coefficients retain visible Bambi hierarchy and stay within the configured support; analytical and black-box DDM parameters keep their calibrated HDDM prior families, transformed-link coefficients remain unbounded on the predictor scale, and explicit priors are unchanged. HSSM warns when other additive terms mean that one bounded coefficient cannot constrain the full identity predictor. Vector initial-value jitter is now support-aware for native bounded group terms, including narrow and one-sided intervals, while invalid or boundary starts remain available for PyMC's normal validation.
 
 ### 0.4.0
 

docs/explanations/coming_from_hddm.md

@@ -136,17 +136,21 @@ several free centered owners produce a likelihood ridge.
   [Link functions and safe priors](../tutorials/link_functions.ipynb) explains
   these scale and ownership changes from first principles. Explicit priors are
   never rewritten, but incompatible group specifications are rejected before
-  Bambi can drop or misinterpret them. Finite coefficient bounds are not yet
-  propagated to generic identity-linked group-only intercept priors; likelihood
-  bounds still apply, and bounding one coefficient would not constrain a complete
-  identity-linked predictor after other effects are added. Prefer a
-  support-respecting transformed link when appropriate; [Specify hierarchical
-  group priors](../how_to/specify_group_priors.md) explains the remaining
-  identity-link choices and compatibility rules. The broader rule is the
-  likelihood: these defaults apply unless you use the neural
-  (`approx_differentiable`) likelihood, which has its own priors derived from
-  the network's training bounds. Specifying your own is a different interface
-  through the same prior controls.
+  Bambi can drop or misinterpret them. For a generic identity-linked parameter,
+  a unique generated group-only intercept with a finite configured bound now
+  receives a centered native `TruncatedNormal` hierarchy. A pure group-intercept
+  predictor is therefore supported by construction. The bound still applies to
+  that coefficient, not to a complete additive predictor after slopes or other
+  effects are added; HSSM warns about that distinction. A transformed link can
+  instead constrain the assembled predictor when its inverse image matches the
+  parameter support. Values outside configured likelihood bounds receive HSSM's
+  finite per-trial log-likelihood floor (`-66.1`), not a hard-support rejection.
+  [Specify hierarchical group priors](../how_to/specify_group_priors.md) gives
+  the exact generated and explicit-prior rules. Analytical and black-box DDM
+  variants keep their calibrated HDDM Gamma, Beta, or Normal hierarchies, while
+  neural (`approx_differentiable`) variants use generic safe priors derived from
+  the network's finite training bounds. Specifying your own is a different
+  interface through the same prior controls.
 - **Outliers.** HDDM's `p_outlier` exists in HSSM under the same name, and the
   lapse distribution is configurable rather than fixed. See [Model outliers
   with lapse probabilities](../tutorials/lapse_prob_and_dist.ipynb).

docs/how_to/specify_group_priors.md

@@ -68,6 +68,21 @@ The per-prior `noncentered=False` override takes precedence over a component or
 model-level `noncentered=True` setting. Generated safe priors apply this centered
 fallback automatically for a unique group-only location.
 
+When that generated owner is an **intercept on an identity link**, HSSM also
+uses the parameter's configured bounds when it can do so without changing an
+HDDM-calibrated prior family. A generic parameter with at least one finite bound
+receives a native hierarchical `TruncatedNormal`: both its generated population
+location and its group coefficients stay inside the configured interval, and
+the group term is centered so Bambi retains that hierarchy. A pure formula such
+as `b ~ 0 + (1 | participant_id)` therefore keeps the complete predictor inside
+the bounds.
+
+This generated-safe behavior is deliberately narrower than general constraint
+propagation. It does not apply to slopes, matching zero-mean deviations,
+transformed links, or explicit priors. Analytical and black-box DDM families
+keep their calibrated response-scale Gamma, Beta, or Normal hierarchies when
+those families already match the built-in parameter support.
+
 If the same unmatched expression occurs under several grouping factors, do not
 give every group distribution a free location. Add the exact common expression
 and use zero-mean group deviations, or deliberately choose exactly one group term
@@ -86,7 +101,7 @@ The relevant rules are:
 | Effectively non-centered plain `Normal` | Supported only with hierarchical `sigma`, absent or all-zero `mu`, no truncation or custom distribution, and no extra arguments |
 | Free or nonzero group `mu` | Use `noncentered=False` so the requested location is retained |
 | Hierarchical non-Normal or custom outer family | Use `noncentered=False` |
-| `hssm.Prior(..., bounds=...)` on a group term | Rejected under either parameterization; HSSM's truncated wrapper cannot satisfy Bambi's group-hyperprior contract |
+| Explicit `hssm.Prior(..., bounds=...)` on a group term | Rejected under either parameterization; HSSM's custom truncated wrapper cannot satisfy Bambi's group-hyperprior contract. This is distinct from the native named `TruncatedNormal` hierarchy HSSM generates for the bounded safe case above. |
 
 These checks do not rewrite explicit priors. HSSM raises when continuing would
 either fail in Bambi or silently construct a different prior tree. The same
@@ -98,7 +113,8 @@ prior-valued arguments.
 All common and group coefficients first combine on the linear-predictor scale,
 and the inverse link is applied afterward. Bounding one identity-linked group
 intercept therefore does **not** guarantee that the full predictor remains inside
-the parameter's support once slopes and other effects are added.
+the parameter's support once slopes and other effects are added. HSSM warns when
+it generates a bounded group-location coefficient in such a mixed predictor.
 
 Use a support-respecting transformed link when it matches the model:
 
@@ -109,8 +125,11 @@ Use a support-respecting transformed link when it matches the model:
 
 If an identity link is scientifically required, choose a centered hierarchical
 family with appropriate natural support when possible, and remember that this
-constrains that coefficient rather than the entire predictor. HSSM's likelihood
-bounds still apply to the assembled parameter value.
+constrains that coefficient rather than the entire predictor. For values outside
+configured likelihood bounds, HSSM substitutes a finite per-trial log-likelihood
+floor (`-66.1`); this is a penalty with a flat region, not a hard-support prior.
+A transformed link is the mechanism that constrains the *complete* additive
+predictor when its inverse image matches the parameter support.
 
 For the underlying scale and location logic, continue with [Link functions and
 safe priors](../tutorials/link_functions.ipynb). For the general prior interface,