Lissin Monetization — Master Report

2026-07-20 · the single source: status, self-review, everything done, what's left, and links to the deep-dive reports. Base branch = dev everywhere.

Status at a glance

Review — what I checked & fixed

I did a correctness pass over the whole branch. Findings:

Known limitations (by design, documented): enforcement uses a read-only peek (small concurrency window vs a strict atomic reserve — the reserve/consume path exists & is tested, ready to wire); enforce() + observeUsage each read the access snapshot, so a generation does two snapshot reads in observe mode (fine on dev; optimizable). Scheduler recurring metering was deferred (see "What's left").

What's done — the billing foundation (59 commits across six PRs)

Backend PR #514 (17 commits)

ba17c42  fix: optimistic-lock reserve + rollover-aware limit (review)
d203b21  recurring=shows/week, one-time=episodes/week (revised numbers)
a47b39c  fail-safe hardening (enforce peek fails open; account race re-read)
4e1e491  document BILLING_ENFORCE[_DOMAIN] flags in .env.example
333c46b  pre-flight enforcement on generation + document upload
9fe7dc2  enforcement engine behind per-domain flags (402 denials)
4804bf4  observe-only metering for Explore playback + SSE creates
2de1f2e  wire generation + document upload into observe-only metering
fda8643  observe-only metering via QuotaService.observe
17fed30  project the trial phase from the RevenueCat webhook
c9caf70  expand GET /billing/access with phase, balances, trial
17b250a  access phase + trial fields on billing_access
f546ffc  quota service — balances, reserve/finalize/release
8a6e08b  UTC-anchored usage-window math for quota meters
f4adc3f  usage account + immutable usage ledger schema
8edc016  plan_versions table seeded from the plan contract
2c8591e  versioned credit-based plan contract (source of truth)

Backend PR #515 (4 commits)

9164b10  fix: require filters (400 not 500) + reject past expiry (review)
87c7548  grandfather a hand-picked user-id selection + campaign audit
79bb1c8  fix: key-only idempotency, normalized filter hash, @-anchored domain filter (review)
537f62b  cohort grandfathering — preview + idempotent bulk apply

iOS PR #309 (9 commits)

9b7b8fc5  fix: per-meter balance decode, tier-aware trial fallback, cover fileUploads (review)
75af88fe  fix: per-placement paywall sheet detents
b8253838  test: paywall placement screenshot QA harness
bf61e690  chore: bump build to 126 for the paywall-placement Beta TestFlight
18a8530e  sync fallback one-time limits to weekly contract (2/4/10/50)
a5a174e3  react to the backend's structured 402 billing-denial
7dd7e34b  tests: expanded /billing/access contract decoding
d8d93c06  align local fallback plan to credit-based Phase-0 contract
772daf4e  decode expanded /billing/access contract; extend PlanLimits

iOS PR #311 — offer-stage rescue ladder (6 commits · stacks on #309)

065a4584  fix: don't signal a loaded offering while busy (review)
c39b4fb1  fix: commit ladder stage only after offering load + guard re-entrant dismiss (review)
c32b2a4e  test: offer-ladder progression + stage screenshots
2d8b0648  escalate paywall dismissal into the discount downsell
bfbb5112  load a specific RevenueCat offering per ladder stage
ac02f36f  offer-stage rescue ladder model + coordinator

iOS PR #312 — Phase 4 (12 commits · stacks on #311)

c32084c4  fix: live trial clock + nudge animation + reserved-aware balance (review)
c204dbd4  test: trial/nudge/balances logic
d920a41e  drive Plan & Billing meters from live balances
1efaea0f  usage nudges near meter limits
a184aec9  trial countdown banner on home
44b3060d  test: entitlement-gate decision logic
d752e333  enforce per-file size + upload-count limits on attach
6d734ef2  enforce explore listening-time via the metered balance
19102972  gate premium soundscapes behind entitlement
e52414b2  enforce playback-speed ceiling on the default-speed slider
ed6d9b13  gate transcript + enforce playback-speed ceiling in the player
67da7bcd  entitlement-gate helper + meter-aware explore capability

Admin PR #163 (11 commits)

f9a90fa  grandfathering campaigns audit page + nav link
5f92d3f  user multi-select + bulk grandfather on the users list
c7273b0  server actions for hand-picked grandfathering + audit
f32591f  grandfathering admin page with cohort builder + two-click apply
65b2638  grandfather cohort preview + apply server actions
5bbae77  surface expanded access contract in billing panel (phase/trial/balances)
ad83886  seed grant-form defaults on mount, not during render
75a57e3  correct grant status for not-yet-started grants
6485987  attribute grants to the signed-in operator
82ccee4  billing.manage permission for grant mutations; versioned refreshes
7ae2cd4  admin surface for complimentary grants and access snapshots

New Pro creator-feature stack (nine PRs · stacked on the foundation)

Built this round on top of the billing foundation — all observe-only / capability-gated / dark. Commit-by-commit detail lives on each PR; at a glance:

Not built: the source-monitoring polling / auto-generation pipeline (only the foundation shipped) and sound-effects cataloging — proposed only, since no sound-effects feature exists in the app to tier (soundscapes are background-music beds).

The full pipeline now exists: plan contract → plan_versions (dashboard-editable) → usage ledger → window math → quota service → expanded /billing/access → trial projection → observe-only metering everywhere users act → flag-gated 402 enforcement → iOS decode + placement mapping. Data model added: plan_versions, usage_accounts, usage_ledger, extended billing_access (3 migrations).

Live vs observe-only vs dark

What's left

Non-code (mostly — the real blockers) Product / Store / Ops · You

1. Product sign-offs — prices, 50/65 discount duration, a few rollover caps, cohort/permanent-access policy, nudge caps.
2. App Store Connect + RevenueCat catalog — trial intro offer, exact save50 + save65 rescue offerings, placements, paywalls, prod webhook, promo/win-back. Missing discount offerings are skipped; standard prices are never presented as a discount.
3. QA / store test matrix → sandbox → TestFlight → cohort → % ramp.
4. Analytics instrumentation + dashboards.

Code (future phases — nice-to-have, not blocking) Backend / iOS / Admin

• iOS — auto-present-a-paywall on a live 402 (typed error + mapping already exposed); a DEBUG -billingScenario trial/lowBalance to screenshot the trial banner / nudges / live balances (mock can't synthesize server-only fields today). (The source-monitoring Sources screen + pro_sources paywall wiring shipped in #315.)
• Backend — offer-state + nudge-decision API (iOS is currently client-authoritative for both), pending plan-change projection, atomic reserve/consume wiring, Explore-URL denial.
• Scheduler recurring metering — deliberately deferred: GenerationService has 41 constructor params + 3 direct-construct specs, too high a blast radius to inject billing safely now. Hook identified (triggerProgramEpisode, schedule.userId in scope) for a careful standalone change.
• Grandfathering hardening — backend (#515: cohort + hand-picked users + audit) + admin UI (#163) are shipped; remaining: two-person approval, an expiry dashboard, a dedicated billing.grant.bulk permission.
• Source-monitoring pipeline — only the foundation (#520) + the iOS Sources surface (#315) shipped; the polling / change-detection / auto-generation loop is deferred.
• Sound-effects cataloging — proposed only: there is no sound-effects feature in the app to tier yet (soundscapes are background-music beds), so it needs an SFX feature to exist first.

Your action items

The detailed reports (all in lo/)

PRD source: lo/lissin-monetization-plan/ (docs 01–08). Code — billing foundation: PRs #514 + #515 (backend→dev), #309 + #311 + #312 (iOS→develop, stacked), #163 (admin→dev). Creator-feature stack: #518 + #519 + #520 + #521 (backend), #313 + #314 + #315 (iOS), #166 + #167 (admin). This master report is the single entry point; the reports above go deeper on each dimension.