feat(stripe): add early fraud warning persistence foundation

Author: RSO

.specs/impact-affiliate-tracking.md

@@ -20,6 +20,7 @@ Updated 2026-05-12 -- note price-versioned billing preserves affiliate semantics
 Updated 2026-05-20 -- broaden tracking to Kilo Pass SALE conversions and rename the affiliate spec.
 Updated 2026-05-20 -- tighten attribution boundaries, SALE uniqueness, Kilo Pass eligibility, reversal scope, and
 provider-contract ownership after audit.
+Updated 2026-05-28 -- allow full SALE reversal for enforced Stripe EFW refunds.
 
 ## Conventions
 
@@ -57,9 +58,9 @@ BCP 14 [RFC 2119] [RFC 8174] keywords apply only when they appear in all capital
 - **Kilo Pass cadence**: Eligible billing cadence `monthly` or `yearly`.
 - **Promo code**: Provider- or checkout-applied purchase code that is available as a discrete reportable value for an
   eligible SALE.
-- **Disputed eligible sale**: Eligible payment-provider-backed SALE whose underlying payment later receives a provider
-  dispute notification.
-- **Commission reversal**: Provider-facing rejection of an affiliate SALE commission for a disputed eligible sale.
+- **Adverse eligible sale**: Eligible payment-provider-backed SALE whose underlying payment later receives a provider
+  dispute notification or is refunded under enforced Stripe Early Fraud Warning handling.
+- **Commission reversal**: Provider-facing rejection of an affiliate SALE commission for an adverse eligible sale.
 - **Reversal identity**: Provider-retained reference needed to reverse a prior SALE without guessing which reported
   action to reject.
 - **Primary operation**: User creation, authentication, subscription settlement, billing progression, or another
@@ -193,26 +194,28 @@ after the winning attribution is established.
 27. Admin-only subscription interventions, such as admin trial resets, admin cancellations, or manual trial-date edits,
     MUST NOT emit affiliate conversion events.
 
-### Dispute Reversals
+### Adverse Payment Reversals
 
-28. When the payment provider reports creation of a dispute for a disputed eligible sale, the system MUST submit a full
-    commission reversal. This covers payment-provider-backed personal KiloClaw SALE events and eligible Kilo Pass SALE
-    events.
+28. When the payment provider reports creation of a dispute for an adverse eligible sale, or Kilo refunds that sale under
+    enforced Stripe Early Fraud Warning handling, the system MUST submit a full commission reversal. This covers
+    payment-provider-backed personal KiloClaw SALE events and eligible Kilo Pass SALE events.
 
-29. Partial payment disputes MUST still reverse the full associated affiliate commission.
+29. Partial payment disputes and an enforced EFW refund of only the remaining refundable amount MUST still reverse the
+    full associated affiliate commission.
 
-30. The system MUST NOT automatically restore reversed commission if the dispute is later resolved in the brand's favor.
+30. The system MUST NOT automatically restore reversed commission if the dispute is later resolved in the brand's favor
+    or an EFW-enforced account later receives legitimate-user remediation.
 
-31. Reversal handling MUST preserve intent when a dispute arrives before the corresponding SALE is reversal-ready. Once
-    the relevant SALE and reversal identity become resolvable, the pending dispute MUST be eligible for reversal
-    submission.
+31. Reversal handling MUST preserve intent when a dispute or enforced EFW refund arrives before the corresponding SALE is
+    reversal-ready. Once the relevant SALE and reversal identity become resolvable, the pending adverse payment MUST be
+    eligible for reversal submission.
 
 32. Automatic reversal is REQUIRED only when a reversal identity exists or can be recovered without guessing. If an
     earlier eligible sale lacks recoverable reversal identity, the system MUST make that gap operationally observable for
     non-automated follow-up.
 
-33. Reversal processing MUST be idempotent. Duplicate dispute notifications for the same disputed eligible sale MUST NOT
-    produce multiple commission reversals.
+33. Reversal processing MUST be idempotent. Duplicate dispute notifications, duplicate EFW processing, or a later
+    dispute for an already EFW-reversed eligible sale MUST NOT produce multiple commission reversals.
 
 ### Client-Side Identity Bridging
 
@@ -249,6 +252,10 @@ after the winning attribution is established.
 
 ## Changelog
 
+### 2026-05-28 -- Enforced EFW refund reversals
+
+Expanded adverse SALE reversal to enforced Stripe Early Fraud Warning refunds so proactive refunds can reverse a full eligible affiliate commission without waiting for a dispute, while preserving reversal identity and deduplication requirements.
+
 ### 2026-05-20 -- Audit clarifications after Kilo Pass expansion
 
 Removed VISIT reporting from this spec, clarified that Kilo Pass affiliate SALE requires a positive paid invoice amount,

.specs/impact-referrals.md

@@ -17,6 +17,7 @@ Draft -- created 2026-04-21 as `.specs/kiloclaw-referrals.md` for KiloClaw refer
 Updated 2026-05-06 -- require Impact Advocate reward redemption after local KiloClaw reward application.
 Updated 2026-05-12 -- note price-versioned KiloClaw billing preserves referral semantics.
 Updated 2026-05-22 -- renamed to `.specs/impact-referrals.md` and expanded to Kilo Pass referrals.
+Updated 2026-05-28 -- classify enforced Stripe EFW refunds as adverse payments.
 
 ## Conventions
 
@@ -73,6 +74,9 @@ BCP 14 [RFC 2119] [RFC 8174] keywords apply only when they appear in all capital
 - **Chargeback**: Stripe dispute event for the qualifying Stripe payment.
 - **Fraud-marked payment**: Qualifying payment marked fraudulent by Stripe, an internal fraud process, or an authorized
   operator.
+- **Enforced EFW refund**: Refund of a qualifying personal Stripe payment performed under
+  `.specs/stripe-early-fraud-warnings.md` after a new Stripe Early Fraud Warning; it is an adverse payment even when no
+  later chargeback is created.
 - **Support review**: Durable `review_required` reward state with triggering reason, affected billing period, and source
   payment or dispute recorded. Kilo team review is required before an already-applied reward can be canceled, clawed
   back, or otherwise adjusted.
@@ -625,18 +629,22 @@ conversion, local referral rewards are authoritative and affiliate SALE reportin
 
 ### Refunds, Reversals, and Fraud
 
-159. Rewards from a qualifying Stripe payment MUST be canceled if Stripe reports a chargeback for that payment.
+159. Rewards from a qualifying Stripe payment MUST be treated as adverse when Stripe reports a chargeback or when
+     Kilo enforces an EFW refund for that payment.
 
 160. Pending or earned-but-unapplied rewards MUST be canceled when the qualifying Stripe payment is charged back,
-     refunded, or fraud-marked.
+     refunded, fraud-marked, or refunded as part of enforced EFW handling. This rule applies to both KiloClaw and Kilo
+     Pass qualifying payments.
 
-161. Already-applied rewards from a charged-back, refunded, or fraud-marked payment MUST be marked for support review
-     and MUST NOT be automatically canceled or clawed back.
+161. Already-applied rewards from a charged-back, refunded, fraud-marked, or EFW-refunded payment MUST be marked for
+     support review and MUST NOT be automatically canceled or clawed back.
 
-162. If a qualifying Impact action must be reversed, the system SHOULD use Impact's reverse-action mechanism instead of
-     creating an unrelated negative conversion.
+162. If a qualifying Impact action must be reversed, including after an enforced EFW refund that prevents a later
+     chargeback event, the system SHOULD use Impact's reverse-action mechanism instead of creating an unrelated negative
+     conversion.
 
-163. Reversal and reward-cancellation handling MUST be idempotent.
+163. Reversal and reward-cancellation handling MUST be idempotent across EFW refund, ordinary refund, fraud marking, and
+     later chargeback delivery for the same qualifying payment.
 
 ### GDPR and PII
 
@@ -715,6 +723,10 @@ conversion, local referral rewards are authoritative and affiliate SALE reportin
 
 ## Changelog
 
+### 2026-05-28 -- Enforced EFW refunds are adverse payments
+
+Classified an enforced Stripe Early Fraud Warning refund as an adverse qualifying payment for both covered products. Pending or earned-but-unapplied rewards cancel, already-applied rewards require support review, and later refund or chargeback delivery must remain idempotent.
+
 ### 2026-05-22 -- Rename and expand to Kilo Pass
 
 Renamed `.specs/kiloclaw-referrals.md` to `.specs/impact-referrals.md`. Generalized shared Impact Advocate referral

.specs/kiloclaw-billing.md

@@ -30,6 +30,7 @@ Updated 2026-04-16 -- successor subscription rows on personal reprovision.
 Updated 2026-05-10 -- price-versioned legacy and current pricing.
 Updated 2026-05-12 -- retired current Standard first-month discount.
 Updated 2026-05-18 -- organization hard-expiry suspension and recovery contract.
+Updated 2026-05-28 -- exceptional personal Stripe EFW cancellation and suspension contract.
 
 ## Conventions
 
@@ -91,6 +92,10 @@ capitals, as shown here.
   the pre-increase KiloClaw prices.
 - **Current pricing**: The default price version for fresh subscription
   rows created after the price-increase rollout.
+- **Fraud-enforcement cancellation**: Exceptional immediate personal
+  subscription cancellation and suspension required when a personal
+  Stripe payment is enforced under `.specs/stripe-early-fraud-warnings.md`.
+  It is not a user cancellation or ordinary payment-dunning transition.
 
 ## Overview
 
@@ -831,6 +836,15 @@ rows renew.
     price version. Re-enrollment after final cancellation MUST follow
     Pricing Versions and Legacy Lineages rule 9.
 
+### Fraud-Enforcement Cancellation Exception
+
+1. The ordinary period-end continuation rule in Cancellation and Reactivation rule 4 MUST NOT apply when a canonical personal Stripe payment is enforced under `.specs/stripe-early-fraud-warnings.md`.
+2. Fraud enforcement MUST immediately cancel renewal for every current personal KiloClaw subscription belonging to the contained user, including Stripe-funded, hybrid, and pure-credit renewal state. Any Stripe-backed cancellation MUST leave local billing state reconciled with the provider outcome.
+3. Fraud enforcement MUST stop or suspend affected personal compute promptly, transition the affected subscription into non-access-granting canceled/suspended state, and assign a fresh destruction deadline 7 days after suspension.
+4. Fraud enforcement MUST preserve the seven-day destruction grace and MUST NOT destroy instance data immediately. Remediation during that interval is an audited admin/support path, not automatic payment recovery.
+5. Every fraud-enforcement mutation MUST be captured in append-only subscription change history with a non-sensitive fraud-enforcement reason and a system actor.
+6. This exception MUST NOT apply to organization-managed KiloClaw subscriptions or instances based solely on an organization-owned EFW; organization warnings remain review-only under the EFW spec.
+
 ### Billing Lifecycle Background Job
 
 1. The background job MUST be protected by an authorization secret;
@@ -1325,6 +1339,11 @@ rows renew.
 
 ### Changelog
 
+#### 2026-05-28 -- Personal Stripe EFW fraud-enforcement exception
+
+- Defined fraud enforcement as an exceptional immediate cancellation/suspension path for personal KiloClaw subscriptions rather than ordinary period-end cancellation.
+- Preserved append-only change history and the fresh seven-day destruction grace while excluding organization-owned EFWs from automatic KiloClaw action.
+
 #### 2026-05-18 -- Organization hard-expiry suspension contract
 
 - Defined hard-expired organization trial state as the organization-managed

.specs/kiloclaw-datamodel.md

@@ -19,8 +19,9 @@ background jobs). All consumers MUST comply with the rules below.
 
 ## Status
 
-Draft — created 2026-04-15.
+Draft -- created 2026-04-15.
 Updated 2026-05-12 -- required KiloClaw price-version lineage invariants.
+Updated 2026-05-28 -- fraud-enforcement subscription mutation invariants.
 
 ## Conventions
 
@@ -57,11 +58,14 @@ capitals, as shown here.
 - **Actor**: The entity responsible for a subscription mutation.
   An actor is either a user (identified by user ID) or the system
   (identified by a service or process name).
-- **Context**: The ownership scope of an instance — either
+- **Context**: The ownership scope of an instance -- either
   _personal_ (not associated with any organization) or
   _organizational_ (associated with a specific organization). A user
   has one personal context and one organizational context per
   organization they belong to.
+- **Fraud-enforcement mutation**: Exceptional personal subscription
+  cancellation or suspension required by an enforced Stripe Early
+  Fraud Warning under `.specs/stripe-early-fraud-warnings.md`.
 - **Active instance**: An instance record that has not been marked
   as destroyed.
 - **Mutation**: Any database write (INSERT or UPDATE) to a
@@ -269,6 +273,13 @@ and serves as the authoritative audit trail for subscription state.
     identifiers (e.g., Stripe subscription ID, invoice ID) MAY be
     included as context.
 
+### Fraud-Enforcement Mutations
+
+- An enforced personal Stripe Early Fraud Warning is an exceptional immediate mutation path. It MUST cancel or suspend affected personal subscription state without relying on ordinary paid-period continuation.
+- A fraud-enforcement cancellation or suspension MUST write subscription change log entries with a system actor, consistent action labels, and a non-sensitive fraud-enforcement reason.
+- A fraud-enforcement suspension MUST retain the associated instance and subscription records and MUST assign the seven-day destruction grace defined by KiloClaw billing rather than destroying data immediately.
+- Organization-managed subscription and instance rows MUST NOT be mutated automatically for an organization-owned Early Fraud Warning in the initial rollout.
+
 ### Record Creation Order
 
 The creation order below reflects the target lifecycle. This order
@@ -342,6 +353,11 @@ not yet enforced in the current codebase:
 
 ## Changelog
 
+### 2026-05-28 -- Fraud-enforcement subscription mutations
+
+- Defined enforced personal Stripe Early Fraud Warnings as exceptional immediate cancellation/suspension mutations that retain instance history, write system-attributed change logs, and preserve the seven-day destruction grace.
+- Excluded organization-owned warnings from automatic organization-managed instance or subscription mutation.
+
 ### 2026-05-12 -- Required KiloClaw price-version lineage invariants
 
 - Added required `kiloclaw_price_version` row semantics.