feat(features): wire phase 2 seeder columns into time-safe featuresets

[w7-mgfcode]

Summary

Phase 2 of the seeder (PRs #92 / #93) added retail-depth generators (lifecycle, replenishment, markdowns, bundles) producing realistic per-(store, product, date) columns. A grep across app/features/featuresets/, forecasting/, and backtesting/ returns zero references to any Phase 2 generator — the data shape exists, but no downstream consumer reads it. Only Phase 1's exogenous columns are wired (via _compute_exogenous_features at service.py:360).

This issue scopes a single vertical-slice extension: take three of the four Phase 2 generators (lifecycle, replenishment, markdowns/promotion) and expose them as time-safe feature columns inside app/features/featuresets/, mirroring the proven exogenous pattern. bundles is intentionally deferred — its cross-product JOIN deserves its own leakage analysis.

Locked design decisions

• Lifecycle: continuous-only. Drop the categorical stage; emit days_since_launch_lag{N} + days_since_discontinue_lag{N} only. LightGBM splits discover stage boundaries naturally; no encoding decision needed; no seeder-threshold coupling.
• Promotion: generalized. PromotionConfig handles all four promotion.kind values (pct_off | bogo | bundle | markdown) via one JOIN. Default kinds_to_track=("markdown",) preserves the original markdown-only scope; bundles/BOGO/pct_off ride along when caller opts in.
• Replenishment: in-method async JOIN. _load_replenishment_events_up_to_cutoff filters event_date <= cutoff_date at the SQL boundary; pandas left-merge inside _compute_replenishment_features.

MVP scope

• ✅ 3 new Pydantic v2 *Config models (LifecycleConfig, ReplenishmentConfig, PromotionConfig)
• ✅ 3 new _compute_*_features methods in app/features/featuresets/service.py
• ✅ 3 new leakage cases in tests/test_leakage.py (one per family) — leakage test ships FIRST
• ✅ 1 end-to-end LightGBM 14-day rolling backtest proving the extended matrix trains cleanly
• ✅ Additive contract: pre-PR /featuresets/compute callers receive byte-identical responses
• ❌ No DB migration — all columns exist from feat(data): seeder Phase 2 — retail depth (channels, lifecycle, bundles/BOGO, markdowns, lead-time) #92 / feat(data,db): seeder phase 2 — retail-depth foundation + lifecycle generator (#92) #93 (verified against app/features/data_platform/models.py)
• ❌ No bundles wiring — separate slice (cross-product JOIN)
• ❌ No UI / frontend changes — backend slice only

Execution plan (5-slice PRP)

Umbrella: PRPs/PRP-3.1-phase2-feature-wiring.md · Slices written individually under PRPs/PRP-3.1A...E.md.

Slice	Scope	Status
PRP-3.1A	Pydantic configs + Phase 2-shaped fixtures (schema-only) — unblocks B/C/D in parallel	PRP ready
PRP-3.1B	Lifecycle compute method + leakage test	Pending
PRP-3.1C	Replenishment compute method (async replenishment_event JOIN) + leakage test	Pending
PRP-3.1D	Promotion compute method (date-range JOIN per kind) + leakage test	Pending
PRP-3.1E	E2E LightGBM backtest + docs (PHASE/3-FEATURE_ENGINEERING.md, _base/DOMAIN_MODEL.md)	Pending

Recommended sequence: A → B → (C ∥ D) → E.

Time-safety contract

Every new feature ships with a leakage test FIRST. app/features/featuresets/tests/test_leakage.py is load-bearing per .claude/rules/product-vision.md Principle 5. Code review specifically eyeballs every .rolling() for a preceding .shift(1).

Verified DB shapes (no migration needed)

• product.launch_date + product.discontinue_date (both Date | None) — models.py:101-102
• promotion.kind ∈ {pct_off, bogo, bundle, markdown} (CHECK constraint) — models.py:305, 334
• promotion.discount_pct: Numeric(5,4) (range 0..1) — models.py:306
• replenishment_event table with index (store_id, product_id, date) — models.py:471-514

Quality gates (every slice)

uv run ruff check app/features/featuresets/
uv run mypy app/features/featuresets/
uv run pyright app/features/featuresets/
uv run pytest app/features/featuresets/ -v

Related

• PR feat(data): seeder Phase 2 — retail depth (channels, lifecycle, bundles/BOGO, markdowns, lead-time) #92 / feat(data,db): seeder phase 2 — retail-depth foundation + lifecycle generator (#92) #93 — Phase 2 seeder
• PR feat(data): seeder Phase 1 — exogenous signals, multi-seasonality, changepoints, returns, substitution #88 — Phase 1 (exogenous, returns, substitution)
• PRP-3 — original feature-engineering slice this extends
• ci: tighten main branch protection — require status checks at the release boundary #108 — main branch protection (paired CI-hardening track, out-of-scope here)

[w7-mgfcode]

Closing — the PRP-3.1 umbrella is fully landed.

PRP	Description	PR
3.1A	Pydantic configs + PRP set	#110
3.1B	Lifecycle compute method	#111
3.1C	Replenishment compute method	#114
3.1D	Promotion compute method	#112
3.1E	E2E integration + cross-config leakage + docs	#115

POST /featuresets/compute now accepts lifecycle_config + replenishment_config + promotion_config. The additive contract is regression-guarded at two layers (schema + HTTP). Cross-config leakage spec is in test_leakage.py::TestPhase2CrossConfigLeakage.

Follow-ups (non-blocking, tracked separately):

• feat(features): extend FeatureDataLoader to join product.launch_date / discontinue_date for lifecycle E2E #116 — extend FeatureDataLoader to plumb product attrs so lifecycle E2E columns surface end-to-end.
• fix(api,features): audit strict=True request models for FastAPI validate_python date/datetime gotcha #117 — repo-wide audit of ConfigDict(strict=True) request models for the FastAPI validate_python + JSON-date gotcha.