feat: Cohort & retention analysis API

[joelpeace48-cell]

Background & current state

There's no cohort/retention computation. Operators can't answer "of users who registered in week N, how many claimed by week N+k?"

Goal

Add a cohort & retention analysis API computed from indexed data, with deterministic, testable outputs.

Technical design

• Endpoints computing cohorts (by registration period) and retention curves (subsequent activity by offset) from indexed events/rollups (NEW-024/026). Parameterized by campaign, cohort granularity, and metric (claimed/active).
• Precompute where feasible; cache results.

Edge cases

• Timezone/period boundaries (UTC).
• Small cohorts → suppress or flag low-n.
• Re-computation after reconciliation.

Task breakdown

• Cohort/retention computation over indexed data.
• Endpoints + caching.
• Deterministic fixture tests.

Acceptance criteria

• A known fixture yields the expected cohort/retention curves.

Testing & verification

• Deterministic fixture test with hand-computed expected values.

Out of scope

• The dashboard UI (NEW-099) — consumes this.

Dependencies / related

• Requires NEW-024/026; feeds NEW-099.

Difficulty: medium · Effort: M · indexer

[Williams-1604]

Hey Maintainer! This looks like a good match and I'm keen to take it. My approach is to understand the surrounding code first, make a minimal and correct change, cover it with tests, and verify CI is fully passing before review. I'll communicate clearly at each step and won't disappear mid-task. Can you assign it to me, will do a better job than before?

[joelpeace48-cell]

Assigned to you @Williams-1604, would have said ensure all CI pipeline passess, but with the quality of the first code, i am center you know your code well

[grantfox-oss]

🦊 GrantFox — @Williams-1604 has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #623)
2. Your PR will be reviewed by the FinesseStudioLab maintainers

Good luck! Track your progress on GrantFox.