Lissin Monetization — Execution Plan & Build Status

2026-07-18, brought current 2026-07-20 · from the PRD set in lo/lissin-monetization-plan/ · base branch = dev everywhere · focused commits, build + tests green

Where we are

The execution plan

The PRD is a full program (Free/Plus/Pro + 3-day trial, credit quotas, rescue-offer ladder, server enforcement, grandfathering, expanded iOS, store config). The PRD's hard sequencing rule — never enable client gates before backend enforcement + grandfathering exist — sets the order. We're executing it phase by phase with dev as the base branch in every repo:

What shipped this session

Two PRs, ten focused commits, both built against one agreed interface — the backend and iOS work ran in parallel and meet at the expanded /billing/access contract.

Backend — PR #514 → dev

Verification: nest build clean after every commit; 46/46 billing unit tests pass. Migrations authored per repo convention (manual SQL + migrate deploy, never migrate dev).

iOS — PR #309 → develop

Verification: Xcode 26.5 build succeeds (app + test targets); 3/3 decode tests pass. Robustness: phase and MeterBalance.window decode as raw strings so an unknown future value can't fail the snapshot; new composite fields fail open. No paywall placement, capability, or gate trigger changed. It added a new fileMaxBytes field rather than tightening the legacy documentMaxBytes, so no current Pro user is newly blocked.

The shared contract — expanded GET /billing/access

Both PRs were built to this interface, so they line up when merged. Every new field is optional / backward-compatible — old clients and old server responses keep working.

{
  ...existing AccessSnapshot fields (tier, capabilities, limits, usage, ...),
  "phase":        "free|trial|paid|grace|billingRetry|promotional|complimentary|expired",
  "planVersion":  "plan_contract_v1",
  "serverTime":   "2026-07-18T..Z",           // authoritative clock
  "trial":        { "startsAt": "..", "endsAt": ".." } | null,
  "balances": {
    "recurringGeneration": MeterBalance,
    "oneTimeGeneration":   MeterBalance,
    "explorePlayback":     MeterBalance,       // unit: SECONDS
    "fileUploads":         MeterBalance
  }
}
MeterBalance = { limit|null, remaining|null, used, reserved,
                 rolloverBalance, resetAt|null, window }

Branch strategy — dev as base

Why this is safe to merge now

• Observe-only. The quota service exists but is not wired into generation, upload, or playback — nothing reserves or denies yet.
• Additive. Every new field on the access response is optional; the expanded balances are computed read-only (a non-fatal add-on that never breaks the response).
• No client behavior change. iOS only decodes new fields and updates fallback copy; no gate, placement, or capability was touched.
• Dashboard-ready by design. Plan numbers live in the plan_versions table (seeded from code), so they can be edited from admin later without a deploy — the answer to "make each value configurable from the dashboard."

What's next

All the engineering phases above are shipped (webhook trial projection, meter wiring, dark enforcement, iOS Phase 4, and grandfathering are all in the six PRs). What remains is mostly yours:

1. Review & merge the six PRs — backend #514 + #515 → dev (one at a time); admin #163 → dev; iOS in stack order #309 → #311 → #312 → develop.
2. RevenueCat / App Store catalog — create the default, save50, and save65 offerings (the ladder loads save50/save65 for its downsells; the client falls back gracefully until they exist), trial intro offer, placements, prod webhook.
3. Sign off pending product numbers (prices, 50/65 discount duration, rollover caps) — versioned config, a data edit, no deploy.
4. Flip enforcement per capability when ready (BILLING_ENFORCE_CAPABILITIES=true first, then FILES + GENERATION), then QA → cohort → % ramp.

Nice-to-have engineering follow-ups (non-blocking): auto-present a paywall on a live 402; a DEBUG -billingScenario trial/lowBalance to screenshot the trial banner/nudges/live balances; wire pro_sources once a Pro-sources feature exists; grandfathering hardening (two-person approval, expiry dashboard).

Open items & decisions

All six PRs are pushed and open; commits are small and focused; nothing is merged yet — they await your review. Every code-review comment is fixed and re-reviews are green. The only remaining step is the App Store / RevenueCat catalog (yours). See the Master report for the full commit-by-commit detail and action items.