Label saved catalog estimates with model provenance

Merged
SI
2d ago
+335-2

Saved catalog valuations currently carry numbers and a free-text trace without structured model provenance. This adds an estimate descriptor containing USD currency, lifetime-average period and catalog-age/floor source, immutable assumptions, methodology version/executor and source freshness. Modeled estimates remain explicitly separate from observed revenue (not_collected), including not_measured results with null modeled-period values.

The descriptor reads the existing model constants, including the one-year age floor. Constants, formulas, rounding, date behavior and existing result fields are preserved. The enrichment reuse key becomes catalog-valuation-v2 so unlabeled v1 content is not silently reused. scope and shareable are documented labels; existing owner/catalog access checks remain the permission boundary.

Validation: genuine RED before implementation (three missing-label/key failures), then 26 focused model/descriptor/collector/enrichment tests passing. Exact baseline comparison: 132 model outputs and 24 collector cases with every pre-existing field unchanged under a fixed clock. Nested assumptions are frozen. Scoped TypeScript, ESLint, Prettier and whitespace checks passed; independent source review completed.

Adapted from historical API #1018 head717a3177 onto verified main2a4f116b. No migration, HTTP/MCP action, dispatcher enablement, brief integration, provider call, paid collection, marketing/chat mirror change or commercial-assumption endorsement. Verification is source/local synthetic only, not hosted runtime, provider execution or actual revenue. Draft for root's exact-head review, CI qualification and merge.

Refs recoupable/app#2144.

Summary by cubic

Adds a structured estimate descriptor to saved catalog valuations so the numbers carry provenance—currency, period, assumptions, methodology, and source—instead of a free-text trace.

  • Descriptor reads frozen assumptions from the same constants as the calculation, so labels cannot drift from the model.
  • Modeled estimates stay explicitly separate from observed revenue (not_collected); not_measured results carry null catalog-age and floor values.
  • Enrichment reuse key changes to catalog-valuation-v2 so unlabeled v1 results are not silently reused.
  • Valuation calculation, existing result fields, and access checks are unchanged; scope and shareable are descriptive labels only.