Coupon journeys

The Store's side of a QR coupon journey (MeshWeaver.Plugins#2063). Design of record: QR Coupon Journeys. The link itself is an Essentials action link (MeshWeaver.Plugins#2060); this page is what a coupon link's Continue opens.

What the review page does

It trusts nothing it was handed. As the viewer it checks that a person is signed in and may read the link's page a/{linkId}. As the platform it reads the link's presentation and private definition, the coupon, and any claim the viewer already holds, and decides (CouponClaimRules.Decide), in this order: signed in; the link serves (revoked, expired, unknown and unreadable all render the same line); the link is bound to this site; the journey reads; the coupon can still be claimed (window, plan tier, bounded term, budget); an existing claim.

It shows the exact quote — the plan tier, the real benefit start and end dates (and that the term is reduced when the coupon's validity cuts it short), Due today: 0 — the method-storage consent when the journey requires a payment setup, and an optional renewal as not available on this site yet. Visiting, refreshing or previewing it writes nothing.

Save my claim re-decides everything as the platform, then reserves a redemption slot and creates the claim. The save itself grants no plan, installs no course, saves no payment method and charges nothing. After the save, the claim's own control plane activates the bounded plan (see Activating the plan below) when the journey needs no payment setup. When the page is opened again, it says where the claim stands: being activated, active until the accepted end, already covered by the recipient's plan, needing the site's attention, or ended. Every line says nothing was charged.

The claim and its consents

CouponClaims/{claimKey} (node type Store/CouponClaim), a platform-owned partition nobody is granted anything on. The key is CouponJourneyRules.ClaimKey — site, recipient and coupon offer, never the link — and the create of the node is the atomic arbiter of one claim per site, person and offer: a second tab, a double click or a second QR link returns the claim the first one created.

The claim keeps the accepted quote and its hash, the phase (Prepared), the slot, and two separate consent records, each { kind, textHash, textVersion, acceptedAt, acceptedBy, quoteHash }:

• methodStorageConsent — present exactly when the journey requires a payment setup, over the journey's own consent text.
• recurringConsent — only for a selected renewal whose terms were quoted. This build quotes no renewal terms, so a selected renewal or a recurring consent is refused; the two are never merged into one record.

The redemption budget

There is no cluster-atomic counter (core: Expressing a Write → Status: a cross-hub fold can lose a count), so the budget is reserved by creating slot nodes: CouponClaims/Slots/{CODE}/{n} for n in 1…maxRedemptions. A listing of the existing slots only picks where to start (CouponClaimRules.ProbeOrder); the first successful create is the reservation; all taken is "no redemptions left". At most maxRedemptions slots can exist, and no two claims hold one. A coupon with no limit takes no slot.

Known limits, stated rather than hidden:

• A slot is taken before the claim is created. A run that loses the claim create gives its slot back; a process that dies between the two leaves a slot held by no claim. Both failures can only issue FEWER redemptions, never more.
• A stopped claim (expired, revoked or cancelled) gives its slot back (see below). A claim that became active used its unit, and that unit is never given back.

Activating the plan

CouponClaimControlPlane is a watcher on the claim node's own hub. It has the same shape as SubscriptionControlPlane. It re-reads the claim, takes one step, and moves the phase only along CouponClaimPhase.CanAdvance. Steps run one at a time, and nothing else writes a saved claim. A step runs on EVERY emission that finds the claim in its phase. So an operator's repair on a running hub is acted on straight away, and a queued emission of a phase the claim has since left does nothing. The save starts the claim's hub by reading the new claim once.

1. Prepared, when the journey needs no payment setup. A claim that needs a setup waits in Prepared for the provider (MeshWeaver.Plugins#2064). The control plane follows policy authorize-as-caller-execute-as-system:

   • The recipient's authority is checked again (CouponClaimStore.Recheck, the review page's own decision). The recipient must still be signed in and still allowed to read the invitation; the link must still serve on this site, through an enabled handler rule. If the link no longer serves, the claim is Revoked. If the check cannot be made, the step faults; that is never a verdict.
   • The coupon is checked again (CouponClaimGrantRules.OfferRefusal). If the coupon was withdrawn, is out of its window, no longer grants the accepted plan, or the accepted period is over, the claim is Expired, and the benefit is never granted.
   • The selected course is checked against the coupon (CouponClaimGrantRules.CourseRefusal). The coupon's package list must name it, and a declared scope must cover it. These are the restrictions the free redemption and a coupon's key enforce, so a journey never installs a course its coupon was not issued for. A course outside them needs attention before anything is granted.
   • Then the claim moves to GrantPending, with coupon-claim:{claimKey} as its request id.

2. GrantPending: the claim's ONE bounded plan is requested on the recipient's subscription record (CouponGrants.Request). The request writes only requestedCouponGrant: the tier, the EXACT accepted end, and the request id. The record's own control plane decides and applies it in ONE write, on the record's own turn (SubscriptionContent.SettleCouponGrant). So the plan it protects is the plan the record holds at that instant, never a reading that another writer has changed since. The decision (CouponGrants.Decide) protects what the recipient already holds:

   • It applies the offer when there is no live plan (none, lapsed or cancelled), a granted plan of the same rank that ends sooner, or a lower granted plan that ends no later than the offer. The record becomes Active on the offer's tier: manual cadence, not permanent, no processor subscription behind it, ending exactly at the accepted end. A cancelled plan's retained term is replaced by that end, never kept.
   • The offer is covered when there is a plan that is higher, sold (a billing cadence), permanent, or of the same rank and unbounded or reaching as far, or when this site's own plan covers it. The record does not change, and the claim goes to Active with grant: Covered.
   • It is refused when a lower plan is sold, permanent, unbounded, or reaches beyond the offer. The offer would re-tier, cut short or extend that plan, so the claim needs attention.

   Pending requests and their settlements are kept by request id (requestedCouponGrants, couponGrantOutcomes). Two claims of one person therefore never overwrite each other. They are decided oldest first in the same write: the first may apply, and the second then finds the plan covering it. Each claim reads its own receipt. An applied grant is final for its claim only once the record has reconciled it, meaning it has revoked the unlocks the new tier no longer covers, as an activation does. That reconciliation is the record's own resumable step: a restart runs it again, and a sweep that fails is recorded on the receipt, so the claim needs attention. Its repair asks again, which clears the failure and retries the sweep. An ACTIVE permanent plan is never replaced, whatever date is left on it.

   A claim acts only on a receipt that is final AND whose id is no longer pending (CouponGrants.SettledReceipt), read off the record's own live stream. A repair that asks again therefore never reads the previous round's receipt as its answer. Receipts are trimmed as history only: one that still owes its reconciliation, or that failed and waits for repair, is always kept.

   The request id is applied at most once. A claim asking again (after a crash, a recycle or a repair) gets the settlement it already had, and a second claim for the same offer finds the plan covers it. This is never RedeemFree, and never an eternal entitlement.

3. A stopped claim with a slot gives the slot back, which returns the unit to the coupon's budget, but only while the slot is still this claim's. The slot is read first. A slot that is gone, or that names another claim or holder (it was given back before and taken again), is left alone. This claim's own slot is deleted with the version that read saw as a precondition, which the owning hub checks. The claim then records slotReleased. This is the coupon budget's one give-back (CouponBudget.Release, ownership by CouponBudget.Holds), the same one a lost save and a free redemption's ticket use; a journey slot reserved before slots recorded their holder is owned by its claim key alone.

4. Active → Installing → Complete: the course. The claim records the course the journey selected (course). The watcher reads the course's tier, then waits until a reading SHOWS the recipient's plan covering it. That is the same read Subscriptions.Unlock decides with, re-read because it trails the grant. A record that states it is permanent reads as live whatever date is left on it (Subscriptions.Parse). A read that fails reads as nothing, never as "no plan".

   • If this site's plan covers the course, the audience verdict (PlanAccess.Grants) must admit the recipient.
   • Otherwise the course is unlocked through the plan (Subscriptions.Unlock): an unlock record under the subscription plus the plan's own grant, and never an eternal entitlement marker, so the course goes when the plan lapses. An unlock that completes empty is a refusal, not a success.
   • Only then is the course installed (DependencyInstall.InstallAfterAcquisition), as System for the recipient, the same shape order fulfilment uses.
   • A course confirmed not covered is never unlocked: one with no tier, or one a live plan of a lower rank cannot reach. The claim completes, and its note says why.
   • An inconclusive reading, a refusal, or a failed install leaves the plan granted and the claim in NeedsAttention with failedIn: Installing. Its repair runs the install again.
   • A journey that selected no course completes straight away.

A step that faults moves the claim to NeedsAttention, with the phase it failed in (failedIn) and why (problem). The repair is an operator moving the claim back to failedIn, and the running hub runs the step again.

The link facts it reads

Store never compiles Essentials. The review page reads the link's presentation (linkId, definition) and private definition (linkId, site, invocation, validFrom, expiresAt, revokedAt, revision) as data (CouponJourneyLinkFacts) — a field-name contract with Essentials' ActionLinkDefinition, read tolerantly: a missing field reads as "does not serve".

One budget

A coupon has ONE redemption budget, maxRedemptions, and both ways of redeeming it reserve from the same ledger: the free redemption (CouponRedemption.RedeemFree, the coupon field on a package page) and a coupon journey's claim. Two ledgers over one budget could each see a unit left and each take it, so there is one (Store/Coupon/Source/CouponBudget.cs).

Pinned by CouponClaimTests in the Store/CouponClaim Tests area (the pure capacity and ticket rules; a live race in which the free redemption's reservation and a journey claim's reservation are subscribed together for the last unit and exactly one wins; one person's concurrent submissions holding one unit) and by CouponBudgetEntrypointTests in the Store/Plugin Tests area, on a hub that does not register the slot type: RedeemFree and a free coupon order refused before any grant when a journey holds the last unit, and a successful RedeemFree writing redeemedBy and slottedBy together and leaving the other unit.