feat(paycraft): consumables end-to-end — grant path, drain, store sync; fix: store-subscription tenant attribution; fix(security): resolve balance subject server-side

.github/workflows/billing-canary.yml

@@ -0,0 +1,75 @@
+name: Billing canary
+
+# Answers "can a customer pay right now?" hourly, which no other workflow does.
+#
+# `cloud-smoke` checks the marketing site returns 200. `dashboard-ci` checks the build. Neither can
+# see a broken purchase path: a rotated key, a deactivated store product or an unreachable webhook
+# leaves every one of their checks green. This runs scripts/billing-canary.sh, whose exit codes are
+# designed for a scheduler — 1 = a purchase path is broken, 2 = the canary could not run, which is
+# deliberately NOT treated as healthy.
+#
+# Scheduled on a public repo, so GitHub Actions minutes are free (PayCraft is public; the rule of
+# thumb for this org is that private repos do not get scheduled workflows).
+
+on:
+  workflow_dispatch:
+  workflow_call:
+  schedule:
+    # Hourly at :41. Offset from cloud-smoke (:23) and the pg_cron canary (:07) so a shared
+    # failure shows up as three distinct timestamps rather than one ambiguous pile.
+    - cron: "41 * * * *"
+
+permissions:
+  contents: read
+
+jobs:
+  canary:
+    name: Can a customer pay?
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install psql client
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq postgresql-client
+
+      - name: Run billing canary
+        id: canary
+        env:
+          # L1 — provider config truth via /api/v1/readiness
+          PAYCRAFT_ACCOUNT_KEY: ${{ secrets.PAYCRAFT_ACCOUNT_KEY }}
+          # L2 — webhook delivery verdicts (migration 165). PG* rather than a URL so no
+          # credential-bearing string lands in a process listing or a log line.
+          PGHOST: ${{ secrets.PAYCRAFT_PGHOST }}
+          PGPORT: ${{ secrets.PAYCRAFT_PGPORT }}
+          PGUSER: ${{ secrets.PAYCRAFT_PGUSER }}
+          PGPASSWORD: ${{ secrets.PAYCRAFT_PGPASSWORD }}
+          PGDATABASE: ${{ secrets.PAYCRAFT_PGDATABASE }}
+          PGSSLMODE: require
+          # L3 — chain truth. Absent until a canary tenant exists; the script reports BLOCKED
+          # (exit 2) rather than skipping silently.
+          PAYCRAFT_CANARY_TENANT_ID: ${{ secrets.PAYCRAFT_CANARY_TENANT_ID }}
+          PAYCRAFT_CANARY_SKU: ${{ secrets.PAYCRAFT_CANARY_SKU }}
+          PAYCRAFT_CANARY_API_KEY: ${{ secrets.PAYCRAFT_CANARY_API_KEY }}
+          STRIPE_TEST_KEY: ${{ secrets.PAYCRAFT_STRIPE_TEST_KEY }}
+        run: |
+          set +e
+          bash scripts/billing-canary.sh
+          CODE=$?
+          echo "code=$CODE" >> "$GITHUB_OUTPUT"
+          exit 0
+
+      - name: Fail on broken purchase path
+        if: steps.canary.outputs.code == '1'
+        run: |
+          echo "::error title=Purchase path broken::A provider cannot transact. See the canary log above."
+          exit 1
+
+      # Exit 2 is surfaced as a WARNING, not a failure. A missing canary credential is an
+      # operational gap to close, not an outage — but it must stay visible, because a canary that
+      # cannot run looks exactly like a canary that found nothing wrong.
+      - name: Warn on blocked canary
+        if: steps.canary.outputs.code == '2'
+        run: |
+          echo "::warning title=Canary blocked::Checks could not run (missing credential or unreachable API). This is NOT a pass."

.github/workflows/cloud-smoke.yml

@@ -3,6 +3,12 @@ name: Production smoke tests
 on:
   workflow_call:
   workflow_dispatch:
+  # Unattended, every 6 hours. Until 2026-10-22 this workflow had NO schedule — it ran only when
+  # the deploy called it or a human clicked it, so between deploys nothing watched production at
+  # all. A smoke test that only runs at deploy time cannot catch what breaks after a deploy, which
+  # is the entire class of outage worth catching.
+  schedule:
+    - cron: "23 */6 * * *"
 
 jobs:
   smoke:

cmp-paycraft/src/commonMain/kotlin/com/mobilebytelabs/paycraft/PayCraft.kt

@@ -274,6 +274,33 @@ object PayCraft {
      */
     val plans: List<BillingPlan> get() = config?.plans ?: emptyList()
 
+    /**
+     * The subscription-ish half of [plans] — everything a PAYWALL may offer.
+     *
+     * [plans] is the whole catalogue (that is what [products] subsets for the store), so once
+     * consumables started reaching it the paywall surfaces had to say which half they meant. They
+     * pick by RANK — `minByOrNull` for the cheapest, `maxByOrNull` for the top tier — and rank is
+     * just catalogue order, so an unfiltered pick could render "300 Ripples" as the upgrade a free
+     * user is offered. A coin pack is not an upgrade path.
+     *
+     * Lifetime and one_time unlocks STAY: they are real entitlements a paywall legitimately sells,
+     * and they were in this list before. Only consumables leave.
+     */
+    public val subscriptionPlans: List<BillingPlan> get() = plans.filterNot { it.isConsumable }
+
+    /**
+     * The non-subscription catalogue — consumable packs and one-time unlocks.
+     *
+     * Deliberately EXCLUDES subscription and trial plans (they belong to the paywall): a store that
+     * lists a plan beside a coin pack invites a user to "buy" a subscription they may already hold,
+     * and the two are bought through different flows.
+     *
+     * Derived from the same [plans] the paywall renders rather than a second fetch, so the two
+     * surfaces can never quote different prices for one sku.
+     */
+    val products: List<BillingPlan>
+        get() = plans.filter { it.isConsumable || it.interval == "lifetime" }
+
     /**
      * The native store's OWN localized price per plan sku (Play `formattedPrice` / StoreKit
      * `displayPrice`), resolved after products load on native billing lanes. When present it is
@@ -1490,10 +1517,29 @@ private fun List<ProductDto>.toBillingPlans(
     popularSku: String?,
     nativePricesBySku: Map<String, NativeDisplayPrice> = emptyMap(),
 ): List<BillingPlan> {
-    val subscriptions = filter { it.type == "subscription" || it.type == "lifetime" }
+    // EVERY sellable type, and a DENYLIST rather than an allowlist — deliberately.
+    //
+    // This was `filter { type == "subscription" || type == "lifetime" }`, which dropped
+    // `consumable` and `one_time` BEFORE the map below ever ran. The cost was not a missing row
+    // in one list: it made `isConsumable = dto.type == "consumable"` (further down) UNREACHABLE,
+    // so the flag was permanently false for every product in the app, and three unrelated things
+    // broke in ways that each looked like their own bug —
+    //
+    //   * PayCraftStoreSection rendered "No products available" against a tenant that had packs;
+    //   * ConsumableDrainer's `plans.filter { it.isConsumable }` matched nothing, so purchased
+    //     units were never drained into the host (the balance just sat on the server);
+    //   * PayCraftBillingManager.isConsumableStoreProduct returned false, so a pack purchase was
+    //     ACKNOWLEDGED instead of CONSUMED — Play then refuses to sell it again, permanently.
+    //
+    // An allowlist is what let that happen: a type the server learned and this list did not
+    // silently vanishes, and the symptom appears far from the cause. A denylist fails the other
+    // way — a new type SHOWS UP, where it is noticed. `trial` is the one genuine exclusion,
+    // because a trial is not independently sellable: it attaches to a parent product and is
+    // folded into it as `trialDays` below.
+    val sellable = filter { it.type != "trial" }
         .sortedBy { it.displayOrder }
     val trials = filter { it.type == "trial" }
-    return subscriptions.mapIndexed { idx, dto ->
+    return sellable.mapIndexed { idx, dto ->
         val attachedTrial = trials.firstOrNull { it.attachesToProductId == dto.id }
         val trialDays = when {
             attachedTrial != null -> attachedTrial.trialDurationDays
@@ -1549,6 +1595,7 @@ private fun List<ProductDto>.toBillingPlans(
             // "lifetime", which makes a consumable indistinguishable from a one-time unlock —
             // and Play finishes those two with different calls.
             isConsumable = dto.type == "consumable",
+            grantQuantity = dto.grantQuantity,
         )
     }
 }

cmp-paycraft/src/commonMain/kotlin/com/mobilebytelabs/paycraft/config/SuiteConfig.kt

@@ -64,7 +64,7 @@ data class SuiteConfig(
 data class ProductDto(
     val id: String,
     val sku: String,
-    val type: String, // "subscription" | "trial" | "lifetime"
+    val type: String, // "subscription" | "trial" | "lifetime" | "consumable"
     @SerialName("display_name") val displayName: String,
     @SerialName("trial_enabled") val trialEnabled: Boolean = true,
     @SerialName("trial_duration_days") val trialDurationDays: Int? = 7,
@@ -73,6 +73,13 @@ data class ProductDto(
     @SerialName("base_price_cents") val basePriceCents: Int = 0,
     @SerialName("base_currency") val baseCurrency: String = "USD",
     @SerialName("display_order") val displayOrder: Int = 0,
+    /**
+     * How many units ONE purchase of a consumable grants (migration 158's `tenant_products
+     * .grant_quantity`). 0 for every other product type, and 0 is also the safe default for an
+     * older server that does not send the field — a pack that grants nothing is visibly broken,
+     * whereas a guessed non-zero default would silently credit currency nobody configured.
+     */
+    @SerialName("grant_quantity") val grantQuantity: Int = 0,
     val active: Boolean = true,
     @SerialName("resolved_price") val resolvedPrice: PriceDto? = null,
     /**

cmp-paycraft/src/commonMain/kotlin/com/mobilebytelabs/paycraft/core/BillingManager.kt

@@ -3,6 +3,7 @@ package com.mobilebytelabs.paycraft.core
 import com.mobilebytelabs.paycraft.model.BillingState
 import com.mobilebytelabs.paycraft.model.OAuthProvider
 import com.mobilebytelabs.paycraft.model.SubscriptionStatus
+import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.SharedFlow
 import kotlinx.coroutines.flow.StateFlow
 
@@ -146,4 +147,65 @@ internal interface BillingManager {
     suspend fun revokeCurrentDevice()
 
     fun logOut()
+
+    // ─── Consumable balances (REQUIREMENTS.md PC-001..006) ───────────────────
+
+    /**
+     * Server-authoritative consumable balances, keyed by sku.
+     *
+     * READ-ONLY and there is deliberately no local increment path (AR-013): a client-writable
+     * balance is forgeable currency. Every value here came from the server — either a
+     * [refreshBalance] read or the new balance a successful [spend] returned. A sku absent from the
+     * map has simply not been read yet; it is NOT the same as a zero balance.
+     *
+     * Default empty so alternate [BillingManager] implementations stay source-compatible.
+     */
+    val balances: StateFlow<Map<String, Int>> get() = MutableStateFlow(emptyMap())
+
+    /**
+     * Re-read [sku]'s balance from the server and publish it to [balances].
+     *
+     * @return the balance, or 0 when it cannot be read. 0 is the safe reading of "unknown" — it
+     *   withholds a spend rather than granting one.
+     */
+    suspend fun refreshBalance(sku: String): Int = 0
+
+    /**
+     * Spend [quantity] of [sku] atomically, server-checked.
+     *
+     * [idempotencyKey] is REQUIRED and has no default (AR-011). A caller retrying after a timeout
+     * must present the SAME key, so the server recognises the replay and returns the original
+     * balance instead of charging twice. Only the caller knows which retry is the same logical
+     * spend, which is why this cannot be defaulted here.
+     *
+     * @return the new balance on success. Insufficient funds is a [Result.failure], NOT an
+     *   exception (AR-012) — a shopper short on currency is an expected outcome of a shop. Never
+     *   grant the purchased thing on a failure.
+     */
+    suspend fun spend(sku: String, quantity: Int, idempotencyKey: String): Result<Int> =
+        Result.failure(UnsupportedOperationException("balances not supported by this BillingManager"))
+
+    /**
+     * Credit an in-app ACTIVITY earn and return the new server balance.
+     *
+     * Throws rather than returning a Result: unlike a spend, there is no "refused" outcome a caller
+     * renders — the server either records it or the call failed, and PayCraftBalances queues the
+     * latter for replay.
+     */
+    suspend fun earn(sku: String, quantity: Int, eventId: String): Int =
+        throw UnsupportedOperationException("balances not supported by this BillingManager")
+
+    // ─── One-time product ownership ──────────────────────────────────────────
+
+    /**
+     * Skus this user owns outright (non-consumable one-time unlocks).
+     *
+     * Server-confirmed only. A sku is absent until [refreshOwnership] gets a `true` back — never
+     * optimistically on purchase return, because Play and StoreKit can both report success for a
+     * transaction that later fails verification.
+     */
+    val ownedSkus: StateFlow<Set<String>> get() = MutableStateFlow(emptySet())
+
+    /** Re-read ownership of [sku] from the server into [ownedSkus]. False when it cannot be read. */
+    suspend fun refreshOwnership(sku: String): Boolean = false
 }

cmp-paycraft/src/commonMain/kotlin/com/mobilebytelabs/paycraft/core/PayCraftAdRewards.kt

@@ -0,0 +1,104 @@
+package com.mobilebytelabs.paycraft.core
+
+import com.mobilebytelabs.paycraft.debug.PayCraftLogger
+
+/**
+ * Watch an ad, earn currency — the third way units enter a balance, beside buying and in-app effort.
+ *
+ * ## Why the SDK does not show the ad
+ *
+ * PayCraft owns the MONEY path, not someone else's ad SDK. AdMob, AppLovin and the rest each take a
+ * firm position on Activity / UIViewController ownership and ship large platform-specific
+ * dependencies; adopting one would force it on every consumer, including those who sell no ads at
+ * all. So the host shows the ad — it already has the network it chose — and binds this seam exactly
+ * the way it binds `identity`. Everything after "the ad completed" is the SDK's.
+ *
+ * ## What makes the reward trustworthy
+ *
+ * **Not this interface.** A client saying "I watched an ad" is a client minting currency with no
+ * attention actually sold — the same shape as the subject-id hole migration 159 closed, and the
+ * email hole 162 closed. So completing an ad here credits NOTHING directly.
+ *
+ * Instead the ad network's own **server-side verification (SSV)** callback reaches PayCraft's
+ * `ad-reward` edge function, which checks the network's signature before crediting
+ * `entitlement_balance_ledger` with `reason = 'ad_reward'` via a service-role RPC that has no
+ * client-callable overload. This class's only job is to carry enough context in the ad request for
+ * that callback to know WHO and WHICH SKU — and then to reconcile, because the credit lands
+ * server-side and out of band.
+ *
+ * ## Not to be confused with `PayCraftAdUnlock`
+ *
+ * [PayCraftAdUnlock] grants a time-boxed FEATURE unlock and is deliberately local-only: a free
+ * feature has no transferable value, so a round-trip to prove it would cost more than it protects.
+ * Currency does have transferable value. The two must not be merged, and this one can never be
+ * local.
+ */
+public fun interface AdRewardProvider {
+
+    /**
+     * Show a rewarded ad and return true only if the user EARNED the reward (watched to the point
+     * the network rewards), false if they dismissed it early or no ad was available.
+     *
+     * [customData] must be passed to the ad network verbatim as its custom-data / server-side
+     * verification payload (AdMob: `ServerSideVerificationOptions.customData`). It is how the SSV
+     * callback attributes the reward to this device and sku — without it the callback arrives with
+     * nothing to credit, and the user watches an ad for nothing.
+     *
+     * Throwing is treated as "no reward".
+     */
+    public suspend fun showRewardedAd(customData: String, userId: String): Boolean
+}
+
+/**
+ * Drives one watch-to-earn round: show the ad, then adopt whatever the server says.
+ *
+ * Deliberately returns the RECONCILED balance rather than "how much you earned". The client never
+ * learns the reward amount from the ad — the network's callback decides it server-side, and a
+ * client-computed delta would be a number the user could disagree with and the server would
+ * overrule a moment later.
+ */
+public class PayCraftAdRewards internal constructor(
+    private val provider: AdRewardProvider?,
+    private val balances: PayCraftBalances,
+    private val deviceToken: () -> String?,
+) {
+
+    /** True when the host bound a provider — hosts hide the watch-to-earn affordance when false. */
+    public val isAvailable: Boolean get() = provider != null
+
+    /**
+     * Show a rewarded ad for [sku] and return the balance after reconciling.
+     *
+     * Returns null when no provider is bound, the device is unregistered, or the user did not earn
+     * the reward — all of which are ordinary outcomes a host renders as "no reward this time",
+     * never as an error.
+     *
+     * The reconcile is not optional and not instant: the SSV callback is an out-of-band server call
+     * that may land after this returns. A host that shows a stale balance here and never reconciles
+     * again will leave the user believing the ad paid nothing.
+     */
+    public suspend fun watchAndEarn(sku: String): Int? {
+        val ads = provider ?: return null
+        val token = deviceToken()
+        if (token.isNullOrBlank()) {
+            // No registered device means the callback has nothing to attribute the reward to, so
+            // showing the ad would spend the user's attention for certain nothing.
+            PayCraftLogger.onError("ad-reward", "no registered device — not showing an ad")
+            return null
+        }
+
+        // sku and device token, in the shape the ad-reward edge function parses. The token (not a
+        // subject id) for the same reason every other client call carries one: a caller must only
+        // ever be able to name ITSELF.
+        val customData = "$token|$sku"
+
+        val earned = runCatching { ads.showRewardedAd(customData, token) }.getOrDefault(false)
+        if (!earned) return null
+
+        // The credit is already in flight server-side; this adopts it. If the callback has not
+        // landed yet the number is simply unchanged, and the next reconcile picks it up — which is
+        // why the balance is a flow the host observes rather than a one-shot answer.
+        balances.reconcile(sku)
+        return balances.balanceOf(sku)
+    }
+}