feat(design): coupled FactorConstraint for build_grid (#103)

[jc-macdonald]

Closes #103.

Summary

Adds FactorConstraint for design-time coupled-factor constraints (e.g. "if method == 'elbo_only' then patience <= 2") and plumbs a constraints= kwarg through build_grid for full, lhs, sobol, and halton.

This is distinct from the existing protocols.Constraint, which filters trials after simulation based on observables. FactorConstraint filters candidate configs before evaluation so QMC budget isn't wasted on points that would be discarded post-hoc.

Behavior

• Full factorial: filters the Cartesian product directly.
• LHS / Sobol / Halton: rejection sampling with doubling oversample (cap 64×).
  • Emits a UserWarning when realized feasibility ratio < 10% (QMC space-filling is degraded by rejection).
  • Raises ValueError if the budget is exhausted before n_samples feasible configs are collected.
• Backward compatible — constraints defaults to None and existing call sites are unchanged.

Example

from trade_study import Factor, FactorType, FactorConstraint, build_grid

factors = [
    Factor("method", FactorType.CATEGORICAL, levels=["elbo_only", "mixed", "full"]),
    Factor("patience", FactorType.DISCRETE, levels=[1, 2, 3, 5, 10]),
]
constraints = [
    FactorConstraint(
        lambda c: c["method"] != "elbo_only" or c["patience"] <= 2,
        name="elbo_short_patience",
    ),
]
grid = build_grid(factors, method="sobol", n_samples=64, seed=0, constraints=constraints)

Tests

8 new tests in tests/test_design.py covering:

• predicate evaluation
• full-factorial filtering and the all-rejected edge case
• deterministic seeding under constraints (parametrized over sobol/halton/lhs)
• low-feasibility warning
• budget-exhausted ValueError

CI

just ci clean: lint, mypy strict, 275 tests pass, design.py at 100% line coverage.

Follow-ups

• Multi-fidelity early-stopping within a batch (Hyperband / successive-halving) #104 — multi-fidelity early-stopping within a batch (Hyperband / successive-halving)
• Regime-conditional surrogate: interpolate factor recommendations across regime features #105 — regime-conditional surrogate