Referral & affiliate programs (ledger-backed rewards)

Why / Context

PRD §7.2E / §8.6: referral (learner→learner) and affiliate (creator→creator) programs are core growth levers for V1. Marketplace network effects (teardown §5.3 BUILD-EXTRA: "every new creator brings learners who discover other creators") get a direct accelerant when both sides are incentivized to recruit.

Schema already in place — NO migration required

• ReferralCode (owner user OR tenant OR platform, kind LEARNER/CREATOR/AFFILIATE, rewardConfig Json, expiry)
• Referral (referredUser unique, status PENDING→QUALIFIED→REWARDED, rewardLedgerEntryId, firstOrderId)
• LedgerAccount(ownerType: USER) + LedgerEntry(entryType: REFERRAL_REWARD) — user-owned reward balances
• Coupon.campaign for coupon-based reward variants

Implementation plan

1. Reward config contract (Zod): { referrerReward: {type: 'CREDIT'|'COUPON', amountMinor|couponSpec}, refereeReward: {...}, qualifyingEvent: 'FIRST_PAID_ORDER'|'SIGNUP', minOrderMinor }.
2. Code issuance: auto-generate a LEARNER code per user on first login (vanity edit allowed); creator/affiliate codes issued from studio/admin.
3. Attribution: ?ref=CODE → cookie (90d) → Referral(PENDING) on signup; last-touch wins; self-referral blocked.
4. Qualification worker: on first PAID order above minOrderMinor, mark QUALIFIED → apply rewards: referrer LedgerEntry(REFERRAL_REWARD) on their USER ledger account (or coupon), referee coupon at checkout.
5. Redemption of user credit at checkout: apply USER ledger balance as a payment-side discount line (cap per order via PlatformConfig).
6. Affiliate variant: tenant-owned codes reward the tenant ledger account; affiliate dashboard (clicks → signups → qualified → earnings) in studio.
7. Fraud guards: same-device/email-domain heuristics, reward clawback path (ADJUSTMENT entries) on refund of qualifying order.
8. Surfaces: /account/referrals (share links, status), post-purchase share prompt, creator "invite a creator" page.

Acceptance criteria

• Referred signup + first qualifying purchase → both-side rewards exactly once (idempotent under webhook replay)
• Refunding the qualifying order claws back the reward via ledger reversal
• User credit balance spendable at checkout with cap enforced
• Affiliate tenant earnings appear in the payout pipeline like sale earnings
• Self-referral and duplicate-device attempts rejected

Dependencies / sequencing

• MVP M7 (checkout/ledger) required; payout automation (issue #14) pays affiliate balances out

Start with MVP M7 checkout/ledger and the existing ReferralCode, Referral, LedgerAccount, LedgerEntry, and Coupon schema described here. Trace the qualification worker, first paid-order and refund paths, checkout credit redemption, /account/referrals, studio/admin issuance, and the payout pipeline. Done means rewards are idempotent, refunds reverse them, caps and fraud guards work, and affiliate earnings reach payouts.