# Reference patch — 01-trial-period

The answer key for how the reference absorbs this change, and the thing that makes `budget.json`
reproducible. **Never shipped to the candidate.**

1. **Overlay** `../contract-delta/CostExplorerApi.java` onto `contract/` — replaces the file of the
   same name, adding `subscribeWithTrial(Plan)`. Contract files are given, so nothing here is
   charged.
2. **Add** `TrialAccount.java` (in this directory) to `reference/src/`. New file, so
   `measureChange` charges nothing for it.
3. **Add one method** to `reference/src/CostExplorer.java`, next to `subscribe`:

   ```java
   @Override
   public String subscribeWithTrial(Plan plan) {
       LocalDate startDate = today();
       String id = "SUB-" + nextId.getAndIncrement();
       subscriptions.save(id, new TrialAccount(new Subscription(plan, startDate, pricing), YearMonth.from(startDate)));
       return id;
   }
   ```

`edits.json` beside this file is the same edit in machine-readable form.

Measured: `reference_diff = 7` (all in `CostExplorer.java`, all additions), so
`diff_budget = max(3, 7 + ceil(7/2)) = 11`.

Both the curveball suite (5 tests) and the base suite (13 tests) are green after the patch. **No
base assertion is invalidated** — `subscribe(Plan)` is untouched, so every account the base suite
builds still has no trial.

## Where the requirement landed, and why `BillingAccount` is the reason

`Subscription.java` was **not opened**. That is the measurement this curveball exists to take.

The tempting shape is to add a `boolean freeFirstMonth` to `Subscription`'s constructor and an
early-return in its `costForMonth`. It works, and it was the first version of this patch — it
measured 14 lines across two files, because the existing `subscribe()` call site and `Subscription`'s
timeline logic both had to learn about a concept, trials, that has nothing to do with a timeline of
plan changes. Every later fact about trials (a trial that requires a card on file, a trial limited
to one per customer) would have gone into the same class that also decides what "overdue" or
"cancelled" means.

**The shape the reference took: a decorator.** `TrialAccount` wraps a `BillingAccount` and answers
exactly one question — "is this the free month?" — before asking the real subscription anything.
It exists only because `BillingAccount` was already the boundary `CostExplorer` and
`SubscriptionRepository` talk through rather than the concrete `Subscription` class; the interface
that looked like foresight for its own sake in the base problem is what a second, unrelated way of
billing an account plugs into for free. This is the same move the shopping-cart problem's
`MemberShipping` makes over `ShippingPolicy`: decorate the existing policy instead of teaching it a
new fact about a different customer.

**What this costs without `BillingAccount` behind the repository.** If `SubscriptionRepository`
stored `Subscription` directly, a decorator would have nothing to implement — there would be no
common type for `TrialAccount` and a plain subscription to share, and the trial flag would have to
go inside `Subscription` after all. The interface earns its keep here in a way the base problem's
tests cannot show on their own.

## Why the free month is "this calendar month", not counted in days

`TrialAccount` stores a `YearMonth`, not a date range — `subscribeWithTrial` mid-month and
`subscribeWithTrial` on the 1st both get the entire month for nothing, exactly as the requirement
states. Doing this by day (30 days from the start date) would have needed the segment-overlap
machinery `Subscription` already has for proration, and that machinery answers a different
question — "how much of this month is covered" — not "was this month waived entirely". Reusing it
for a flat waiver would have made a decorator that is really two policies pretending to be one.
