feat: campaign-name canon — agency/bid/goal parsing + funnel↔delivery join

[mtmtian]

Stacked on #6 (→ #5 → #4) — merge in order. This PR is the last commit.

Summary

Implements the team's campaign-naming convention as the attribution canon and uses it to close the funnel↔delivery gap left pending in #6.

Canon (docs/growth/06 §7)

• Pipeline: activation = Adjust · signup/retention/payment = backend · agency/bid-strategy/conversion-goal = parsed from campaign name · OS/channel = Adjust's own fields (name-derived values are fallback only). Front/back linking stays on the registered-user id forwarded to Adjust (existing app_user_id partner-param mechanism).
• Naming convention (positional, --delimited): agency-date-bid-os-regions-channel-idx-product-goal-audience-custom..., e.g. inhouse-20260512-mai-Android-US/T1/JP-Google-01-Luddi-install-female-Davis-xx.

Changes

• parseCampaignName — pure positional parser: tolerant of short/long names, regions split on /, os/date enum-validated with raw segments preserved (osRaw/dateRaw), free-text fields lowercased not whitelisted (word lists are customer-defined), never throws. 22 tests.
• ConversionEvent += agency/bidStrategy/conversionGoal; CohortSnapshot += agency (into the unique key). Additive migration.
• Cohort group key: date|channel|os|agency (agency attribution follows the same install-first precedence as channel/os).
• Report campaign-level rows stamp agency from the row's campaign name; PlatformAccount.agency demoted to fallback (account-level rows and legacy MMP report pulls keep using it).
• Funnel↔delivery join: /api/reports/breakdown joins CohortSnapshot on (date, os, channelToPlatform(channel), agency) and fills signups / cost-per-signup / D1 / D7 / D0–D7 ROI for joined rows. Joined-to-zero and never-joined are distinguishable (null vs real 0); funnelJoin: full|partial|none is response-level and the UI "pending" hint shows only when not full. Window/metric math shared with /api/growth/summary via kpi-canon helpers — one formula, two consumers.

Known limits (documented in §7)

• Campaigns not following the naming convention parse to agency: null and won't join — their funnel columns stay — by design (no guessing).
• Adapter-written Report rows don't populate os yet (pre-existing), which lowers join hit-rate on those platforms until that's wired.

Test plan

• npx vitest run — 384/384 across 30 files (33 new: parser edge cases, channelToPlatform, shared window helpers, breakdown aggregation with joined/unjoined rows)
• npx tsc --noEmit clean · npm run lint 0 errors (35 pre-existing warnings) · npm run build passes · prisma validate passes (additive-only migration)

🤖 Generated with Claude Code

[oratis]

🤖 Code review — Claude Code

Verdict: Request changes — two real silent-failure correctness bugs in the PR's core deliverable (the funnel↔delivery join), not edge-case nits.

Scope note: Top of the stacked series #4→#5→#6→#7 (all target main), so this PR's diff-vs-main contains #4/#5/#6. This review covers only the incremental delta #7 adds over #6. Merge the stack in order (or retarget bases) — merging #7 now would pull in #4/#5/#6 implicitly, including the open issues flagged on those PRs.

Summary

Adds a positional "campaign-name canon" parser and threads parsed agency/bidStrategy/conversionGoal through the Adjust ingest path, Report writes, and a new CohortSnapshot.agency column. Then implements the funnel↔delivery join in /api/reports/breakdown (Report ⋈ CohortSnapshot on date/os/platform/agency via a channelToPlatform bridge), replacing the hardcoded funnelJoin: 'pending' stub.

Findings

• [High] src/lib/dashboard-bi.ts:316,332-333 — costPerSignup divides all-dates spend by joined-only signups. aggregateBreakdownRows sums spend over every row, but only sums signups/sets hasSignups when r.signups !== null. So costPerSignup = spend(all rows) / signups(joined rows only) whenever a group mixes joined and unjoined days — exactly the funnelJoin: 'partial' state this PR introduces — yielding a silently inflated (wrong, not null) KPI. The same function correctly nulls d1Rate/d7Rate/d0Roi/d7Roi in aggregate mode for this precise "not re-derivable across mixed join state" reason; costPerSignup was missed. → Accumulate a separate joinedSpend (only add r.spend when r.signups !== null) and divide by that, mirroring the rate-column discipline.

• [High] src/lib/sync/report-writer.ts:56-60,145 vs src/lib/growth/campaign-name.ts:99 — agency join-key normalization mismatch → permanent silent miss. parseCampaignName().agency is always .toLowerCase()'d (and that's what lands in ConversionEvent.agency/CohortSnapshot.agency), but resolveReportAgency() — the fallback used by writeCampaignReports for any campaign name that doesn't parse under the canon (i.e. most non-Cuddler campaigns) — returns PlatformAccount.agency verbatim. The join (reports/breakdown/route.ts:73,110,128) is an exact string match with no normalization at the join site. Any org with a mixed-case agency on file (e.g. "GroupM") gets its non-canon Report rows permanently un-joinable to CohortSnapshot data — not a transient "pending", a permanent silent miss. → Lowercase in resolveReportAgency (or canonicalize both sides at the join boundary).

• [Medium] src/lib/growth/ingest-parse.ts:68 — agency: str(r.agency) accepts a backend-supplied agency verbatim, no .trim().toLowerCase(), unlike every other producer of this dimension. Currently unused by any live caller, but it's the same normalization gap waiting for the next caller. → Normalize now while it's one line.

• [Low] src/lib/growth/cohorts.ts (keyOf) and reports/breakdown/route.ts:73,110,128 — group/join keys are naive |-delimited template strings over fields that can contain arbitrary chars (a campaign segment could legally contain a literal |), risking key collision. Pre-existing pattern extended to agency here; low real-world likelihood, noting for awareness.

• [Low] Test-coverage gap on the riskiest code. The join logic itself (cohortsByKey construction, per-group lookup, funnelJoin full/partial/none derivation) has zero coverage — only pure helpers (aggregateCohortWindow, computeFunnelMetrics, channelToPlatform) are unit-tested. Telling: the new aggregateBreakdownRows tests cover "all joined" and "zero joined" but not the mixed case — precisely the gap that let the first finding through. No e2e added.

No Blocker / multi-tenant issues: both new queries filter by org.id from requireAuthWithOrg(); no raw SQL. Migration 20260707130000_campaign_name_canon matches the schema diff (adds the three ConversionEvent cols + CohortSnapshot.agency, widens the unique index) and is staged. parseCampaignName is pure/never-throws with thorough edge-case tests (empty/whitespace/non-string/no-dash/consecutive-dash all covered); single anchored regex, no backtracking risk. CohortSnapshot rows are summed (not fanned out) across the dropped appId dim — deliberate and correct. _client.tsx validates Array.isArray(d.rows) and coerces funnelJoin to a known enum before use.

Test coverage

Not adequate for the highest-risk code — the join/grouping in /api/reports/breakdown has no direct unit or e2e test; the closest aggregation suite stops short of the mixed joined/unjoined case (the actual bug).

Strengths

• Extensive doc comments (docs/growth/06-mmp-ingest.md §7, in-code priority chains) make intent easy to verify against implementation.
• Consistent "never guess, null when unknown" discipline throughout the parsing/fallback chains.
• Sound "recompute ratios from sums, never average pre-derived per-day ratios" instinct — the costPerSignup bug is a narrow miss of a principle applied correctly everywhere else in the same function.

_{Independent automated review. Findings are advisory — use judgment.}

[mtmtian]

✅ Changes applied (fixup pushed)

Both High findings and the Medium normalization gap addressed:

• [High] costPerSignup divides all-dates spend by joined-only signups — aggregateBreakdownRows now accumulates a separate joinedSpend (only adding r.spend when r.signups !== null) and divides by that, mirroring the rate-column discipline already applied to d1Rate/d7Rate/d0Roi/d7Roi. In the funnelJoin: 'partial' state, cost-per-signup is now joinedSpend/joinedSignups instead of a silently inflated all-spend/joined-signups. Added the mixed joined/unjoined regression test — the exact case the prior 'all joined'/'zero joined' tests skipped.
• [High] agency case-normalization mismatch — resolveReportAgency now .trim().toLowerCase()s the PlatformAccount.agency value, matching parseCampaignName's normalization. Mixed-case agencies ('GroupM') on non-canon Report rows can no longer permanently miss the exact-match funnel join.
• [Medium] backend ingest agency unnormalized — ingest-parse.ts now normalizes agency the same way (.trim().toLowerCase()), closing the gap before the next caller hits it.

Re the [Low] |-delimited key collision and the join-logic e2e gap — noted; the key pattern is pre-existing and low-likelihood, and the shared window helpers are unit-covered. The mixed-case aggregation test now covers the specific bug the review flagged; broader route-level e2e is a follow-up.

Commit 7e2b79c (plus 091ed37 chore: gitignore local design PDFs — unrelated repo hygiene). Re-verified: 389/389 vitest, tsc clean, lint clean, build passes.