# The Subscription Optimization Engine ("Rotate Churn")

> This spec is a living starting point — open for revision once the prototype exists.

## Purpose

Translates the user's desired content into a monthly financial plan. Every month starts as a blank slate (Zero-Based Budgeting) — every platform must earn its spot based on the user's current watchlist priorities and budget cap. Output: a concrete Keep / Subscribe To / Downgrade / Dump plan.

---

## 1. Inputs

### User Data

| Field | Description |
|---|---|
| `budget_cap` | Hard monthly maximum (e.g. $30/mo) |
| `aggregated_watchlist` | All items across all lists + shared group lists |
| `priority_weighting` | Must Watch = 3.0, Nice to Watch = 1.0 |
| `series_progress` | Episode tracking for in-progress shows (higher weight to keep the service until finished) |
| `watch_status` / `hibernation` | Completed or Hibernating items drop platform weight contribution to 0 |
| `active_subscriptions` | Current services, monthly cost, and next billing date |

### Platform Data

| Field | Description |
|---|---|
| `pricing_tiers` | Monthly cost per tier (ad-supported, standard, premium) |
| `bundles` | Pre-defined service groupings at discounted bundle rates |
| `catalogs` | Which titles are on which platforms (titles can exist on multiple platforms simultaneously) |
| `content_lifecycle` | "Leaving Soon" expiration dates and new season premiere dates |

---

## 2. Platform Utility Score

Before deciding what to subscribe to, the algorithm grades every platform based on the user's watchlist:

```
Platform Utility Score = Σ [ (Hybrid Rec Score × Emphasis Weight × Urgency Multiplier) × (1 − Hibernation State) ]
```

| Variable | Description |
|---|---|
| Hybrid Rec Score | Blended thematic + collaborative score from the Recommendation Engine |
| Emphasis Weight | Must Watch = 3.0, Nice to Watch = 1.0 |
| Urgency Multiplier | Default 1.0; spikes to ~5.0 if the title leaves before the next billing cycle |
| Hibernation State | Binary — 1 if Completed/Hibernating, which zeroes out that title's contribution entirely |

---

## 3. The Allocation (Zero-Based Knapsack)

Maximize total platform value without exceeding `budget_cap`. This is a constrained optimization problem (the 0/1 Knapsack Problem):

```
Maximize:   Σ [ Platform Utility Score × Decision ]
Subject to: Σ [ Monthly Cost × Decision ] ≤ budget_cap
```

`Decision` is binary per platform: 1 = Keep/Subscribe, 0 = Cancel/Dump.

---

## 4. Tier & Bundle Constraints

### Tier Exclusivity
A user can only be on one tier per platform at a time:
```
Σ (Active Tiers for a Platform) ≤ 1
```
The algorithm tries the premium tier first. If it exceeds the budget, it tests the ad-supported tier before recommending full cancellation.

### Bundle Optimization
Before locking in individual subscriptions, the algorithm checks if combining needed platforms qualifies for a known bundle at a lower total cost. If so, it outputs the bundle recommendation instead of à la carte options.

### Reseller / Distribution Channel Note
A service like Peacock can be subscribed to directly, via Amazon Channels, or via Apple TV Channels. For algorithm purposes the subscription is the subscription — content access is identical. This only matters for **deep linking** ("Watch Now" links behave differently depending on how the user subscribed). For the prototype, deep link to the primary platform app. Reseller channel distinction is a production-tier concern.

---

## 5. The 5-Step Processing Loop

The algorithm runs in strict sequence, treating no current subscription as guaranteed:

1. **Purge** — zero out platform weight for all titles marked Completed or Hibernating
2. **Rank** — sort remaining titles by priority + urgency (Must Watch + leaving in 3 days = #1 slot)
3. **Reset** — start with the full unallocated `budget_cap`; flag all currently active subscriptions as "Pending Churn"
4. **Allocate** — walk the ranked list top to bottom:
   - Identify the required platform for the top-ranked title
   - Deduct its cost from the budget
   - Mark it Keep (if already active) or Subscribe (if not)
   - *Multi-platform check:* if the title is on multiple inactive platforms, temporarily hold — scan the rest of the list and pick the platform that covers the most other high-priority items
   - *Bundle check:* before marking individual subscriptions, test if a bundle is cheaper
   - *Downgrade check:* if adding the platform exceeds the budget, test the cheaper tier before skipping
   - Continue until budget = $0
5. **Churn** — anything still "Pending Churn" after the budget runs out → Cancel or Downgrade. Calculate the execute date from `next_billing_date` so the user doesn't lose access before their paid period ends.

---

## 6. Savings Tracking

### The Baseline Portfolio
To calculate savings, the system needs to know what the user *would have* kept paying for. This "Baseline Portfolio" is:
- **Seeded at onboarding** — whatever services the user selected during setup
- **Expanded automatically** — if the algorithm recommends a new service and the user keeps it for one month, it enters the baseline

Any month a baseline service is Cancelled or Downgraded triggers the savings calculation for that platform.

### Savings Formula

```
Total Saved = Σ over 12 months [ Σ(Cancelled Platform Costs) + Σ(Downgrade Cost Deltas) ]
```

**Example:** Disney+ ($10/mo) in the Baseline Portfolio, kept cancelled for 4 months:
```
Savings = 4 × $10 = $40
```
UI output: *"You paused Disney+ for 4 months this year, saving $40!"*

---

## 7. Outputs

The algorithm produces an `action_plan` with four instruction types:

| Output | Contents |
|---|---|
| `subscribe` | Platform, expected cost, reason (e.g. "Contains 3 Must Watch movies and 1 new season") |
| `cancel` | Platform, execute date (billing-cycle-aware), monthly savings |
| `downgrade` | Platform, target tier (e.g. ad-supported), cost reduction |
| `keep` | Platform, upcoming renewal date, cost |

---

## 8. Guardrails

- **Billing Cycle Rule ("Ride It Out")** — if a service is flagged for cancellation, tell the user to act before the next billing date but keep the platform's catalog factored into recommendations for the remainder of the paid period
- **Downgrade Before Cancel** — always test a cheaper tier before recommending full cancellation
- **No Mid-Cycle Downgrades** — downgrades take effect at the next billing cycle to avoid prorated math against the strict budget cap
- **Strict Budget Adherence** — the sum of Keep + Subscribe + Downgrade costs must never exceed `budget_cap`; if it does, drop the lowest-value platform
- **Urgency Overrides** — a platform containing a high-priority item with an imminent "Leaving Soon" date gets a temporary massive score boost, overriding normal ranking
- **Completion/Hibernation Mid-Month** — when a user marks a series Watched or Hibernating during the month, that platform's value drops immediately, triggering a re-evaluation of whether it's still worth keeping for the remainder of the cycle