toga-ai 1.0.519 → 1.0.520

package/knowledge/2.0/apps/toga2-view/features/get-support-cancel-subscription.md

@@ -6,8 +6,8 @@ project: TOGa View Frontend
 client: shared
 type: feature
 status: active
-updated: 2026-07-28
-owners: ["tcox"]
+updated: 2026-08-04
+owners: ["tcox", "mhammontree"]
 files:
   - toga2-view/src/pages/GetSupport/viewModels/getSupportPageViewModel.ts
   - toga2-view/src/pages/GetSupport/view/GetSupportPage.tsx
@@ -17,6 +17,7 @@ files:
 related:
   - ../architecture.md
   - ../../../../clients/rate/features/service-card-entitlements.md
+  - ../../../../clients/rate/features/subscription-cancellation.md
   - ../../../../clients/rate/profile.md
 ---
 
@@ -30,8 +31,12 @@ services and unclassified services get the subscription details card **without**
 Two things about this flow are easy to get wrong and are the reason it is documented:
 
 - The cancel affordance exists **only on this page** — `ServiceCard` has none.
-- **There is no backend cancellation endpoint yet.** The viewModel's `cancelSubscription()` is a
-  stub that always rejects, so confirming surfaces an error instead of faking success.
+- **The backend now exists** (2026-08-04): `cancelSubscription()` calls
+  **`POST /v2/subscriptions/cancel`** with `{ entitlementUuid }` in the **body**. It is no longer a
+  stub. The route shape, the two-phase PayPal-backed write, and the reason the *entitlement* uuid
+  (not the subscription uuid) is the argument are documented in
+  [Rate tech-support subscription cancellation](../../../../clients/rate/features/subscription-cancellation.md).
+  This is also why the viewModel already exposed `entitlementUuid` on its `subscription` object.
 
 ## Key files / entry points
 

package/knowledge/INDEX.md

@@ -18,8 +18,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 43 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 38 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 44 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **worker2** (Worker) — 39 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 21 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 5 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 5 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/knowledge/clients/rate/INDEX.md

@@ -5,8 +5,10 @@
 | [Rate AIG Warranty Contract Creation (silent-failure interceptor)](features/aig-contract-creation.md) | 2.0 | When a Rate entitlement is created, `_Model_Rate_Entitlement::postPost` (`_underscore/Model/Rate/Entitlement.php`) creates an **AIG warranty contract** as a non | _underscore/Model/Rate/Entitlement.php, _underscore/ApiRequest.php, worker2/Worker/Monitors/RateEntitlement.php |
 | [Rate Monthly Reconciliation Report](features/monthly-reconciliation-report.md) | 1.0 | A monthly cron that emails an Excel reconciliation report covering all Rate subscription sales orders and their linked PayPal payments for the prior calendar mo | worker/crons/notifications/reports/rate/send_monthly_rate_purchases_report.php, worker/schedules/cron.worker.notification.json |
 | [Rate SalesOrder → NetSuite CashSale Export (postPost)](features/netsuite-cashsale-export.md) | 2.0 | Rate sells home-warranty / home-tech-support products. | _underscore/Model/Rate/SalesOrder.php, _underscore/Model/Rate/Item.php |
+| [Rate PayPal Subscription Purchase & Webhook Pipeline](features/paypal-subscription-purchase-webhook.md) | 2.0 | > # ⚠ STATUS (2026-08-04, TRUE-80575) — TWO INDEPENDENT LIVE DEFECTS > > **A. | worker2/Worker/Rate.php, worker2/Config/production.ini, api2/Config/production.ini, _underscore/Component/Api/Paypal.php, toga2-view/src/hooks/usePayPalSubscription.ts, toga2-view/src/services/paypalService.ts, toga2-view/src/pages/CheckOut/viewModel/useCheckoutPageViewModel.ts, toga2-view/src/pages/CheckOut/api/checkoutApi.ts, toga2-view/src/pages/Activation/view/Activation.tsx |
 | [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
 | [Service Card Entitlement Display](features/service-card-entitlements.md) | 2.0 | Rate's home and services pages display one service card per purchased entitlement. | src/components/ServiceCard/ServiceCard.tsx, src/components/ServiceCard/index.ts, src/hooks/useBundleServices.ts, src/hooks/useActiveServices.ts, src/pages/Home/api/homeApi.ts, src/pages/Home/view/HomePage.tsx, src/pages/Home/viewModels/useHomePageViewModel.ts, src/pages/Services/view/ServicesPage.tsx, src/pages/Services/viewModels/useServicePageViewModel.ts, src/api/serviceAddressApi.ts, src/api/apiErrors.ts, dbchanges2/Client_Rate/2026-07-24a - AddressIdFieldPermission.sql |
 | [Rate Service-Purchase Confirmation Emails (Tech / Warranty)](features/service-purchase-emails.md) | 2.0 | When a Rate customer purchases a service, a confirmation email is sent. | _underscore/Model/Rate/Entitlement.php, worker2/Worker/Notification/EmailTemplate.php, dbchanges2/Client_Rate/2026-06-30a - Rate purchase email templates.sql |
+| [Rate Tech-Support Subscription Cancellation (portal self-service)](features/subscription-cancellation.md) | 2.0 | Rate portal customers can cancel their **tech-support** subscription themselves. | _underscore/Model/Rate/Subscription.php, _underscore/Component/Api/Paypal/Paypal.php, worker2/Worker/Rate.php, dbchanges2/Client_Rate/2026-08-04a, dbchanges2/Client_Rate/2026-08-04b, dbchanges2/Core/2026-08-04a, toga2-view/src/pages/GetSupport, toga2-view/src/components/ServiceCard/ServiceCard.tsx, toga2-view/src/pages/Home/api/homeApi.ts, toga2-view/src/hooks/useBundleServices.ts, toga2-view/src/api/apiErrors.ts, api2/Config/beta.ini |
 | [Rate Whole Home Warranty Per-Address Purchase Guard](features/whole-home-warranty-purchase-guard.md) | 2.0 | > # ⚠ STATUS (2026-07-31, TRUE-80487) — THE GUARD HAD NEVER EXECUTED, IN ANY ENVIRONMENT > > Everything below the next section described a guard that **never ra | _underscore/Model/Rate/Entitlement.php, _underscore/Model/Client/Entitlement.php, _underscore/Model/Client/Address.php, _underscore/Component/Library/Carriers/Usps/Usps.php, toga2-view/src/pages/CheckOut/api/checkoutApi.ts, toga2-view/src/pages/CheckOut/viewModel/useCheckoutPageViewModel.ts, toga2-view/src/pages/ZipValidation/api/zipValidation.ts, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Core/2026-07-22a - EntitlementServiceAddressIdField.sql, dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql, dbchanges2/Client_Rate/2026-07-31a - WarrantyAvailabilityCustomRecordScript.sql, test/@Mark/Rate/verify_wholehome_per_address_guard.php, test/@Mark/Rate/verify_wh_gate_and_unit_dedup.php |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/paypal-subscription-purchase-webhook.md

@@ -0,0 +1,149 @@
+---
+title: "Rate PayPal Subscription Purchase & Webhook Pipeline"
+framework: "2.0"
+repo: worker2
+project: Worker
+client: rate
+type: client-feature
+status: active
+updated: 2026-08-04
+owners: ["mhammontree"]
+files:
+  - worker2/Worker/Rate.php
+  - worker2/Config/production.ini
+  - api2/Config/production.ini
+  - _underscore/Component/Api/Paypal.php
+  - toga2-view/src/hooks/usePayPalSubscription.ts
+  - toga2-view/src/services/paypalService.ts
+  - toga2-view/src/pages/CheckOut/viewModel/useCheckoutPageViewModel.ts
+  - toga2-view/src/pages/CheckOut/api/checkoutApi.ts
+  - toga2-view/src/pages/Activation/view/Activation.tsx
+related:
+  - profile.md
+  - service-card-entitlements.md
+  - whole-home-warranty-purchase-guard.md
+  - service-purchase-emails.md
+  - aig-contract-creation.md
+  - subscription-cancellation.md
+---
+
+> # ⚠ STATUS (2026-08-04, TRUE-80575) — TWO INDEPENDENT LIVE DEFECTS
+>
+> **A. Every `Rate/Webhook` worker job fails.** 5/5 jobs on record in prod `Core.WorkerJobs`
+> (ids 560657, 563520, 563544, 563545, 574010; 2026-08-01 → 2026-08-03) died with
+> `watchdog: exceeded maxExecutionTime without completing` at ~322s against a 300s watchdog.
+> Cancellations and renewals are therefore silently not being processed.
+>
+> **B. New purchases have no server-side creation path at all.** Only the customer's browser
+> can create an entitlement. If the browser never completes the call, PayPal keeps the money
+> and TOGa records nothing — no trace, no reconciliation.
+>
+> **A and B are separate.** Fixing the watchdog timeout restores cancellations/renewals but
+> does **not** close the money-taken-nothing-recorded hole. Fix B is awaiting a decision
+> (see *Open decisions*). No code has been written for either.
+
+## Summary
+
+Rate customers buy home-tech-support and home-warranty subscriptions through PayPal on
+`toga2-view`. The purchase is created **entirely client-side**; `_Worker_Rate::Webhook`
+(worker2) handles only post-purchase lifecycle events (renewal sales orders and
+deactivations) against an entitlement that **already exists**.
+
+## How it works
+
+**New purchase (browser-only):**
+1. `usePayPalSubscription.ts` resolves a plan id from `PAYPAL_PLAN_IDS`
+   (`paypalService.ts`) and opens the PayPal subscription flow.
+2. On PayPal approval, the SDK's `onApprove` callback
+   (`usePayPalSubscription.ts:151-177`) fires **in the customer's browser**.
+3. `handleActivateService` (`useCheckoutPageViewModel.ts:402-489`) builds a single nested
+   `POST /entitlements` payload — Entitlement + Subscription + SalesOrder + SalesOrderItem
+   + Payment — and posts it via `checkoutApi.ts:20`.
+4. That browser call is the **only** thing that creates the records.
+
+**Lifecycle (worker2):** PayPal → Lambda → SQS → `_Worker_Rate::Webhook`, which handles
+`PAYMENT.SALE.COMPLETED` (renewal sales order on an existing entitlement) and six
+deactivation events. There is **no** `BILLING.SUBSCRIPTION.ACTIVATED` handler. For a new
+purchase the worker dead-ends early: `Rate.php:112` throws *"Subscription not found for
+token"*, `Rate.php:394` throws *"Entitlement not found"*.
+
+## Gotchas
+
+- **The watchdog timeout is NOT the PayPal-egress problem — do not re-chase egress.**
+  `worker2/Worker/Rate.php:59-77` and `_underscore/Component/Api/Paypal.php:13-18` both
+  assert that webhook stalls come from the EB worker tier being unable to reach
+  `api-m.paypal.com`. That egress problem is real but is **not** what kills these jobs:
+  `verify_signature = false` in `worker2/Config/production.ini`, so the signature/OAuth
+  calls never execute on the inbound path. **Those code comments are wrong about the cause.**
+- **The real cause is an unindexed leading-wildcard LIKE.** `isEventProcessed()`
+  (`Rate.php:268-290`) runs
+  `SELECT COUNT(*) FROM Logs_Rate.Api WHERE source='PAYPAL' AND requestPayload LIKE '%<eventId>%'`.
+  `SHOW INDEX FROM Logs_Rate.Api` has indexes only on `id`, `uuid`, `transactionId`,
+  `apiId(+dtStamp,isAuthRequest)`, `dtStamp`, `method` — **no index on `source`**, and the
+  LIKE is a leading wildcard over a `mediumtext` column across 8.7M rows. Reproduced
+  independently: a bare `WHERE source='PAYPAL'` timed out at 300s twice, while
+  `dtStamp`-bounded queries on the same table returned instantly.
+- **`isSuccess = 0` on a `Rate/Webhook` job does NOT mean "no side effects."** A
+  watchdog-killed job's PHP process can keep running and complete its API writes after the
+  row is marked failed. Job 560657 started 07:53:03, was killed 07:58:18, yet its
+  `POST /v2/sales-orders` landed 08:00:10 and `POST /v2/entitlement-sales-orders` at
+  08:00:41 (worker IP 34.232.23.158). **Re-running or manually remediating a failed job
+  risks duplicates** — always check `Logs_Rate.Api` first. This race also explains why some
+  purchases appear to have worked.
+- **Yearly Home Warranty cannot be purchased at all (separate live bug, needs its own
+  ticket).** `PAYPAL_PLAN_IDS` (`paypalService.ts:31-41`) defines `monthly_tech`,
+  `yearly_tech`, `monthly_warranty` — but **no `yearly_warranty`**. `getPlanId()` builds
+  `` `${plan}_${serviceType}` `` → `yearly_warranty` → `undefined` → `onError("Invalid plan
+  configuration")`.
+- **Security: the webhook endpoint is unauthenticated and forgeable.** With
+  `[paypal] verify_signature` disabled (documented in-code as a temporary tradeoff for the
+  blocked egress), anyone who knows the endpoint URL can create a paid SalesOrder.
+  Separately, the live PayPal `client_secret` is committed in plaintext in the `[paypal]`
+  block of **both** `worker2/Config/production.ini` and `api2/Config/production.ini` — it
+  should be rotated and moved out of the repo. (Location only; the value is not recorded
+  anywhere in this KB.)
+- **Defect A now also blocks portal cancellations, not just renewals.** As of 2026-08-04 the
+  portal's self-service cancel flow relies on this worker consuming
+  `BILLING.SUBSCRIPTION.CANCELLED` to stamp `Subscriptions.dateCancelled` (its reconciliation
+  channel) — with every `Rate/Webhook` job dying, that path is dead. See
+  [Rate tech-support subscription cancellation](subscription-cancellation.md).
+- **Hypothesis, NOT confirmed — the `return_url` lands on a page that creates nothing.**
+  `usePayPalSubscription.ts:126` sets `return_url` to `${origin}/activation?success=true`.
+  If the SDK falls back to a full-page redirect (popup blocked, mobile in-app browser),
+  PayPal redirects there and `onApprove` never runs; `Activation.tsx` is a static
+  "success, redirecting in 10s" page that reads no subscription id and calls no API. The DB
+  can only prove the *absence* of the call, not why the browser didn't make it. Treat as a
+  plausible mechanism, not a cause.
+
+## Investigating this
+
+- **Defect A cannot be reproduced locally via a sandbox webhook.** Non-production worker2 is
+  not SQS-driven (it is manually HTTP-invoked), so a PayPal sandbox webhook never traverses
+  the Lambda→SQS→worker path and the watchdog never fires. Reproduce by timing the
+  `isEventProcessed()` query directly against a large `Logs_Rate.Api`.
+- **Defect B** must be exercised via a real sandbox browser checkout.
+- **Always bound `Logs_Rate.Api` queries by `dtStamp` plus a `method`/route filter.**
+  Unfiltered windows return hundreds of unrelated bulk contact-sync `PUT` rows and truncate.
+
+## Evidence (TRUE-80575)
+
+Zero `POST /v2/entitlements` rows in `Logs_Rate.Api` for all of 2026-08-01, while
+`Client_Rate` User 755 / Contact 773 / Customer 752 (Kwadwo "Drew" Moore) were created at
+16:25:16 pre-payment and PayPal charged $89.97 at 16:32:47 (txn `0DY909616V1516622`,
+subscription `I-411CRRVH81U8`).
+
+## Open decisions
+
+Closing defect B requires giving the server a creation path — either a
+`BILLING.SUBSCRIPTION.ACTIVATED` handler, or a reconciliation job that sweeps PayPal
+subscriptions with no matching `Subscriptions.token`. **Rejected:** framing TRUE-80575 as a
+single "webhook broken" bug. Awaiting Mark's decision; nothing implemented.
+
+## Change history
+
+- 2026-08-04 — Documented from TRUE-80575 investigation (read-only): watchdog failures traced
+  to the unindexed `isEventProcessed()` LIKE (not PayPal egress — corrects the in-code
+  comments), no server-side entitlement-creation path for new purchases, post-kill write race,
+  missing `yearly_warranty` plan id, and the disabled-signature/committed-secret exposure.
+  Session notes: `knowledge/sessions/2026-08-04-TRUE-80575-rate-paypal-webhook-mhammontree.md`
+  (mhammontree)

package/knowledge/clients/rate/features/subscription-cancellation.md

@@ -0,0 +1,208 @@
+---
+title: "Rate Tech-Support Subscription Cancellation (portal self-service)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: rate
+type: client-feature
+status: active
+updated: 2026-08-04
+owners: [mhammontree, tcox]
+files:
+  - _underscore/Model/Rate/Subscription.php
+  - _underscore/Component/Api/Paypal/Paypal.php
+  - worker2/Worker/Rate.php
+  - dbchanges2/Client_Rate/2026-08-04a
+  - dbchanges2/Client_Rate/2026-08-04b
+  - dbchanges2/Core/2026-08-04a
+  - toga2-view/src/pages/GetSupport
+  - toga2-view/src/components/ServiceCard/ServiceCard.tsx
+  - toga2-view/src/pages/Home/api/homeApi.ts
+  - toga2-view/src/hooks/useBundleServices.ts
+  - toga2-view/src/api/apiErrors.ts
+  - api2/Config/beta.ini
+related:
+  - clients/rate/profile.md
+  - service-card-entitlements.md
+  - whole-home-warranty-purchase-guard.md
+  - aig-contract-creation.md
+  - paypal-subscription-purchase-webhook.md
+  - ../../../2.0/apps/toga2-view/features/get-support-cancel-subscription.md
+  - ../../../2.0/apps/api2/features/record-scripts.md
+  - ../../../2.0/apps/_underscore/features/model-save-vs-query-atomic-update.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+---
+
+## Summary
+
+Rate portal customers can cancel their **tech-support** subscription themselves. The Get Support
+page's Cancel button previously had **no backend** (it called a stub that always rejected — see
+[Get Support cancel gating](../../../2.0/apps/toga2-view/features/get-support-cancel-subscription.md));
+this feature is that backend.
+
+**The single most important fact about this flow: TOGA does not bill Rate subscriptions — PayPal
+does.** The recurring charge runs *inside PayPal* against a billing agreement created browser-side
+at checkout and stored as `Subscriptions.token`. There is **no TOGA cron that selects subscriptions
+to charge.** Therefore **writing cancellation columns stops zero money** — a cancel **must** call
+PayPal. Conversely PayPal has no "cancel at period end" (it cancels *immediately*), so the
+"coverage continues until the end of your current period" promise the portal makes is **entirely
+ours to implement**.
+
+Endpoint: **`POST /v2/subscriptions/cancel`** with `{"entitlementUuid": "…"}` in the **body**,
+dispatching to `_Model_Rate_Subscription::cancelApi`.
+
+## Key files / entry points
+
+- `_underscore/Model/Rate/Subscription.php` — `cancelApi` (the record script) and
+  `applyCancellationFields` (the two-phase writer)
+- `_underscore/Component/Api/Paypal/Paypal.php` — the server-side PayPal client (**note the
+  directory**, see gotchas)
+- `worker2/Worker/Rate.php` — the `BILLING.SUBSCRIPTION.CANCELLED` webhook handler and
+  `extendSubscriptionDate`; also the `Rate/ExpireCancelledSubscriptions` cron
+- `dbchanges2/Client_Rate/2026-08-04a` — `AclFieldPermissions` grants (must sort **before** `b`)
+- `dbchanges2/Client_Rate/2026-08-04b` — the record-script registration + dispatch grant
+- `dbchanges2/Core/2026-08-04a` — Core record/field + `CronJobs` row
+- `toga2-view` — `GetSupport` (real call replaces the stub), `ServiceCard`, `homeApi`,
+  `useBundleServices`, `apiErrors`
+
+## Route shape — why the id is in the BODY, and why it is the ENTITLEMENT uuid
+
+Two constraints that look like sloppy API design and are not:
+
+1. **`/subscriptions/{id}/cancel` is impossible.** The V2 dispatcher consumes the **trailing path
+   segment as the script name**, so any id placed before `cancel` breaks route matching. The id
+   therefore travels in the JSON body (supported — see
+   [POST + JSON-body args for scripted APIs](../../../2.0/apps/api2/features/scripted-api-post-body-args.md)).
+2. **The caller passes the `entitlementUuid`, not the subscription uuid.** Surfacing
+   `subscription.uuid` to the portal would require a **new joined-field ACL grant**, and an
+   ungranted joined field **fails the entire entitlements request** (`EZ-2`) — one missing grant
+   would blank the whole services page. The entitlement uuid is already granted and already in
+   hand, so the server resolves the subscription from it.
+
+## How it works — the two-phase write (order is load-bearing)
+
+`applyCancellationFields` writes the cancellation in **two separate commits**, and the ordering
+exists to survive a race with PayPal's own webhook:
+
+1. **`dtRequestToCancel` is committed BEFORE the PayPal call.** Cancelling at PayPal fires
+   `BILLING.SUBSCRIPTION.CANCELLED` back at worker2 **within seconds**. Before this feature that
+   handler set `isActive = 0` **and** `dateEnd = today` — a same-day hard cut that directly
+   contradicts the portal's "coverage continues" copy. With `dtRequestToCancel` already committed,
+   the handler recognises a **wind-down** and leaves `dateEnd` alone.
+2. **Call PayPal** to cancel the billing agreement.
+3. **`dateCancelled` is written only AFTER PayPal confirms.** It is the confirmation marker; an
+   unconfirmed cancellation must never look confirmed.
+4. **`isActive` stays `1`.** The portal gates access on `isActive` alone, so flipping it here would
+   revoke paid-for access immediately. A daily cron — **`Rate/ExpireCancelledSubscriptions`,
+   `Core.CronJobs`, 03:00 Central** — flips it once `dateEnd` has passed.
+
+**The effective end date is always server-computed from `dateEnd`.** Client-supplied dates are
+ignored — honoring them would hand out free coverage.
+
+**Warranties are refused server-side**, using the *same authority as the purchase guard*: WH title
+keyword **or** `Items.id = 3` (see
+[WH purchase guard](whole-home-warranty-purchase-guard.md)). The frontend's `serviceType === 'tech'`
+gate is a UX affordance, not the enforcement point.
+
+## Reconciliation — the webhook IS the confirmation channel
+
+There is deliberately **no api2-side reconciliation endpoint**. When worker2 sees
+`BILLING.SUBSCRIPTION.CANCELLED` on a row that is still unconfirmed, **it stamps `dateCancelled`
+itself**. That closes the loop for cancellations initiated outside the portal too.
+
+**The guard split that matters** (getting this backwards either bills a cancelled customer or robs
+a paying one):
+
+| Row state | Meaning | `extendSubscriptionDate` | Expiry cron |
+|---|---|---|---|
+| `dtRequestToCancel` + **future** `dateEnd`, no `dateCancelled` | **PENDING** — may still be billing | **still extends** | does **not** deactivate |
+| `dtRequestToCancel` + `dateCancelled` | **CONFIRMED** | **stops** | deactivates once `dateEnd` passes |
+
+An unconfirmed cancellation may still be billing, and **that payment genuinely owes the customer
+another period** — so only a *confirmed* cancellation stops the extension. The expiry cron likewise
+requires `dateCancelled` so it can never deactivate someone PayPal is still charging.
+
+Historical note: before this ticket **`dtRequestToCancel` was written by nothing and read by
+nothing** — a dead column. It is now the pending/confirmed discriminator.
+
+## PayPal app pairing (where credentials live — never values)
+
+**A PayPal subscription can only be cancelled with credentials for the app that OWNS it.** The
+server-side `client_id` must therefore match the client-id the **frontend** used to create the
+agreement.
+
+- Verified: `api2/Config/production.ini` `[paypal] client_id` matches
+  `toga2-view/.env.production`.
+- **beta / development use a DIFFERENT PayPal app**, so non-prod testing cannot touch live
+  agreements. Beta credentials live in `api2/Config/beta.ini` `[paypal]`, pointed at
+  `api-m.sandbox.paypal.com`.
+- Sandbox credentials already existed in the 1.0 `webhook/config.rohan-mac.ini` because the 1.0
+  webhook was previously the only server-side PayPal caller.
+
+**Never place the live pair in a non-prod ini — cancellation is irreversible at PayPal.**
+
+## Migration ordering is a dependency contract
+
+`dbchanges2` runs files **alphabetically within a folder**, so the same-day letter suffix is the
+contract between these two files: the **field-permission grants (`2026-08-04a`) must land BEFORE the
+record-script registration (`2026-08-04b`)**. Reversed, the endpoint goes live while the worker
+still cannot see the columns it needs — which is precisely the window in which a cancel truncates a
+customer's paid coverage.
+
+## Frontend
+
+`GetSupport` now calls the real endpoint instead of the rejecting stub. `ServiceCard` /
+`useBundleServices` / `homeApi` render **"Service ends by \<date\>"** in place of "Renews" once a
+cancellation is pending, and the Cancel affordance is hidden. Non-essential new fields are requested
+as **optional** and dropped on `EZ-2`/`EV-8` (`apiErrors`), so a missing grant degrades this one
+feature rather than failing the page.
+
+**No cancellation email is sent — PM decision**, not an oversight.
+
+## Gotchas / known issues
+
+- **`_Component_Api_Paypal` must live at `Component/Api/Paypal/Paypal.php`** — a flat
+  `Component/Api/Paypal.php` fatals on first use. See
+  [component/model namespace + autoload registration](../../../2.0/apps/_underscore/features/component-model-namespace-registration.md).
+- **Never roll a cancellation back with "set the field to null and `save()` again" on the same model
+  instance** — `_Model::save()` silently omits the column and the rollback does nothing. This bug
+  was written and nearly shipped here: it would have left customers marked cancelled while PayPal
+  kept billing them. `applyCancellationFields` loads a **fresh instance per write**. See
+  [_Model::save() vs raw _Query](../../../2.0/apps/_underscore/features/model-save-vs-query-atomic-update.md).
+- **Do not add an `AclRecordPermissions` CREATE grant to "make the scripted POST work."** A scripted
+  POST skips the record-permission check entirely; a CREATE grant on `Subscriptions` would let any
+  portal customer insert arbitrary subscription rows through normal CRUD. An `EZ-1` on a scripted
+  POST means the **script** grant is missing.
+- **Writing cancellation columns without calling PayPal does not stop billing.** There is no TOGA
+  charging cron to stop.
+- **`isActive` is not the cancellation flag.** It stays `1` through the wind-down; read
+  `dtRequestToCancel` / `dateCancelled` to know the cancellation state.
+- **The AIG carrier cancel is chained off the same `BILLING.SUBSCRIPTION.CANCELLED` event** — see
+  [AIG contract creation](aig-contract-creation.md). AIG is the *carrier*, not the `Client_Aig`
+  tenant.
+- **`api2/Config/production.ini` carries a plaintext live PayPal secret in the repo.** Flagged for
+  remediation; do not propagate the pattern.
+- **⚠ The confirmation channel this design depends on is currently BROKEN in production.** Every
+  `Rate/Webhook` worker job is dying on the watchdog (unindexed `isEventProcessed()` LIKE — see
+  [PayPal subscription purchase & webhook pipeline](paypal-subscription-purchase-webhook.md),
+  Defect A). Until that is fixed, `BILLING.SUBSCRIPTION.CANCELLED` is **not processed**, so
+  `dateCancelled` is only ever stamped by `cancelApi`'s own post-PayPal write and the
+  webhook-side reconciliation path is dead. Treat the webhook fix as a prerequisite for relying
+  on reconciliation.
+
+## Change history
+
+- 2026-08-04 — TRUE-80282: built portal self-service cancellation for Rate tech-support
+  subscriptions. `POST /v2/subscriptions/cancel` (`{entitlementUuid}` in the **body** — the V2
+  dispatcher consumes the trailing segment as the script name; the entitlement uuid avoids a joined
+  field grant whose absence would fail the whole entitlements request). Two-phase write:
+  `dtRequestToCancel` committed **before** the PayPal call so the returning
+  `BILLING.SUBSCRIPTION.CANCELLED` webhook treats it as a wind-down instead of truncating `dateEnd`
+  to today; `dateCancelled` only **after** PayPal confirms; `isActive` left at 1 until the daily
+  `Rate/ExpireCancelledSubscriptions` cron (03:00 Central). Recorded that **PayPal, not TOGA, bills
+  these subscriptions** (billing agreement in `Subscriptions.token`; no TOGA charging cron;
+  `dtRequestToCancel` was previously a dead column), that PayPal cancels immediately so the
+  period-end grace is ours, and the pending-vs-confirmed guard split governing
+  `extendSubscriptionDate` and the expiry cron. WH refused server-side by the purchase guard's
+  authority (title keyword or `Items.id 3`); end date always server-computed from `dateEnd`; no
+  cancellation email (PM decision). (mhammontree)

package/knowledge/clients/rate/profile.md

@@ -14,7 +14,7 @@ project: SAML SSO Gateway
 client: rate
 type: profile
 status: active
-updated: 2026-07-31
+updated: 2026-08-04
 owners: ["rgirish", "bala", "mhammontree", "tcox"]
 files: []
 related:
@@ -24,6 +24,8 @@ related:
   - clients/rate/features/service-card-entitlements.md
   - clients/rate/features/aig-contract-creation.md
   - clients/rate/features/service-purchase-emails.md
+  - clients/rate/features/paypal-subscription-purchase-webhook.md
+  - clients/rate/features/subscription-cancellation.md
 ---
 
 ## Summary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.519",
+  "version": "1.0.520",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",