toga-ai 1.0.616 → 1.0.618

package/knowledge/1.0/apps/tools/features/errors-curation-console.md

@@ -6,8 +6,8 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
-owners: ["jcardinal"]
+updated: 2026-08-19
+owners: ["jcardinal", "mhammontree"]
 files:
   - tools/mvc/errors/get.php
   - tools/mvc/errors/post.php
@@ -266,6 +266,14 @@ They were renamed from plural on 2026-08-01, after the pipeline was already in p
 
 ## Gotchas / known issues
 
+- **⚠ Recipients attach to an `issueId`, so they cannot be configured in advance.** A new business
+  exception's recipients can only be added **after** the condition first fires and creates the
+  `Logs.Issue` row — declaring a stable `issueKey` in code does **not** let you pre-wire the
+  email list. Therefore the **first occurrence always routes to a developer ClickUp task**, and
+  somebody has to come back here and add recipients (which is also what flips `isManaged = 1`).
+  Live example: issue **208** `COMPASS_OFFICE_DEPOT_PO_IMPORT_REJECTED_OVER_QUANTITY` is still
+  ClickUp-routed because nobody did. See
+  [error reporting — Issue/Event capture](../../../../2.0/apps/_underscore/features/error-reporting-issue-event.md).
 - **⚠ OPEN BUG (found 2026-08-04, deliberately left unfixed pending the developer's go-ahead):
   `tools/mvc/errors/post.php` ~line 181, the merge-fingerprint action, will merge into the WRONG
   issue.** It takes a reference **or** a numeric id in **one** field and disambiguates with
@@ -312,6 +320,11 @@ They were renamed from plural on 2026-08-01, after the pipeline was already in p
 
 ## Change history
 
+- 2026-08-19 — Documented (no code change) that **email recipients are keyed by `issueId`, so they
+  cannot be pre-configured** for a business exception that has never fired — the first occurrence
+  always routes to a developer ClickUp task, and adding a recipient here is what converts it to
+  business email (and sets `isManaged = 1`). Found while wiring a new Rate business exception.
+  (mhammontree)
 - 2026-08-05 — **Built:** the `/errors` console surfaces the new Issue-level RESOLVED lifecycle —
   an **Open/Resolved/All** status filter (default Open, allowlisted value), a **Resolved badge**
   (listing + detail header), a **`dtAutoResolved`** fact row, and the ClickUp-episodes column

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -20,7 +20,7 @@
 | [Re-pointing a DB alias mid-request (_Database::register park/restore)](features/database-alias-repointing.md) | `_Database` keys **all live per-database runtime state by the connection ALIAS** (`Client` / `_underscore::DB_CLIENT`, `ClientLogs`, `Archive`), **not** by the | _underscore/Database.php, _underscore/Query.php, api2/Component/Api/V2/V2.php, api2/Component/Api/CrossClient/CrossClient.php |
 | [2.0 Email Send Pipeline (queue + Send worker)](features/email-send-pipeline.md) | In 2.0, `_Email::send()` **does not transmit** — it queues the message. | _underscore/Email.php, _underscore/String.php, worker2/Worker/Infrastructure/Email/Send.php, _underscore/Model/Client/Logs/Email.php, _underscore/Model/Client/Logs/EmailAttachment.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
-| [Error Reporting — Issue/Event Capture, Fingerprinting & Aggregation](features/error-reporting-issue-event.md) | Platform-wide error reporting for TOGA 2.0, built on an **Issue / Event** aggregation model in the **shared Core Logs DB**. | _underscore/Error.php, _underscore/Database.php, _underscore/Exception/Business.php, api2/Controller/Index.php, worker2/Controller/Index.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, _underscore/Model/Core/Logs/IssueFingerprint.php, _underscore/Model/Core/Logs/IssueClickupTask.php, _underscore/Model/Core/Logs/IssueEmailAddress.php, _underscore/Model/Core/Logs/IssueAreaOwner.php, dbchanges2/Logs/2026-07-30a - Error reporting Issues and Events.sql, dbchanges2/Logs/2026-08-01a - Rename tables to singular.sql, dbchanges2/Logs_Client/2026-08-01a - Drop Error table.sql, dbchanges2/Core/2026-07-30a - Error escalation cron job.sql |
+| [Error Reporting — Issue/Event Capture, Fingerprinting & Aggregation](features/error-reporting-issue-event.md) | Platform-wide error reporting for TOGA 2.0, built on an **Issue / Event** aggregation model in the **shared Core Logs DB**. | _underscore/Error.php, _underscore/Database.php, _underscore/Exception/Business.php, api2/Controller/Index.php, worker2/Controller/Index.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, _underscore/Model/Core/Logs/IssueFingerprint.php, _underscore/Model/Core/Logs/IssueClickupTask.php, _underscore/Model/Core/Logs/IssueEmailAddress.php, _underscore/Model/Core/Logs/IssueAreaOwner.php, worker2/Worker/Infrastructure/Errors.php, tools/mvc/errors/issue/get.php, tools/mvc/errors/post.php, dbchanges2/Logs/2026-07-30a - Error reporting Issues and Events.sql, dbchanges2/Logs/2026-08-01a - Rename tables to singular.sql, dbchanges2/Logs_Client/2026-08-01a - Drop Error table.sql, dbchanges2/Core/2026-07-30a - Error escalation cron job.sql |
 | [Record-Changed Event Publishing (_Event::publish to SQS)](features/event-publish-sqs.md) | `_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event pipeline. | _underscore/Event.php |
 | [FIELD_STORAGE fields — per-row lazy hydration and the platform-wide missing-column 500](features/field-storage-row-hydration.md) | `FIELD_STORAGE` is the 2.0 field type for blob-backed columns (S3 or local folder). | _underscore/Model.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/Invoice.php, dbchanges2/Core/HISTORIC/2024/2024-11b - item-fulfillments.sql |
 | [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/probe_je_shape.php, test/@dave/fixer.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |

package/knowledge/2.0/apps/_underscore/features/error-reporting-issue-event.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-12
+updated: 2026-08-19
 owners: ["dfranks", "jcardinal", "mhammontree", "ajean", "bala", "apeterson"]
 files:
   - _underscore/Error.php
@@ -20,6 +20,9 @@ files:
   - _underscore/Model/Core/Logs/IssueClickupTask.php
   - _underscore/Model/Core/Logs/IssueEmailAddress.php
   - _underscore/Model/Core/Logs/IssueAreaOwner.php
+  - worker2/Worker/Infrastructure/Errors.php
+  - tools/mvc/errors/issue/get.php
+  - tools/mvc/errors/post.php
   - dbchanges2/Logs/2026-07-30a - Error reporting Issues and Events.sql
   - dbchanges2/Logs/2026-08-01a - Rename tables to singular.sql
   - dbchanges2/Logs_Client/2026-08-01a - Drop Error table.sql
@@ -659,8 +662,52 @@ clientUserId). **Neither was built.** As built instead:
   clients) rather than client-user ids, so recipients who have **no login** can still be
   addressed.
 
+### ⚠ Recipients are keyed by `issueId`, NOT `issueKey` — so the FIRST occurrence always goes to a developer
+
+**Corrects a natural (and wrong) assumption:** that declaring an `issueKey` in code lets you
+pre-configure who gets emailed. It does not. Recipients attach to the **`Logs.Issue` row**, which
+does not exist until the condition **first fires**.
+
+- Path: **Tools → `/errors` → open the issue → "Email recipients" → "Add recipient"** (client,
+  email, TO/CC/BCC) — `tools/mvc/errors/issue/get.php` (~L959 "Email recipients"),
+  `tools/mvc/errors/post.php` (~L149).
+- That write inserts `Logs.IssueEmailAddress` (`uuid`, `issueId`, `clientId`, `emailAddress`,
+  `toCcBcc`) and sets `Issue.isManaged = 1`. worker2 reads them via
+  `worker2/Worker/Infrastructure/Errors.php::loadRecipientsByIssueId()`.
+- **Adding a recipient is what converts an issue from developer-ClickUp-task routing to business
+  email.** `clientId 0` = ALL CLIENTS (Rate is `Core.Clients` id 39).
+
+**Consequence to plan around:** every brand-new business exception routes its **first** occurrence to
+a **developer ClickUp task**; someone must then configure recipients. Production evidence — only two
+keyed business issues exist: id **24** ref `1X` `COMPASS_SALES_ORDER_MITS_TRANSMIT_REJECTED`,
+`isManaged = 1` (the working precedent), and id **208** ref `AG`
+`COMPASS_OFFICE_DEPOT_PO_IMPORT_REJECTED_OVER_QUANTITY`, `isManaged = 0` — a live example of a
+business issue still going to ClickUp because nobody ever configured recipients.
+
+### `captureException` without throwing is a supported pattern
+
+`_Error::captureException(new _Exception_Business(...))` **records and notifies without throwing**,
+which is the correct shape when one *leg* of a job is unresolved but the job itself is valid — see
+`worker2/Controller/Index.php:286` and the worked case in
+[Rate subscription cancellation](../../../clients/rate/features/subscription-cancellation.md)
+(carrier cancel abandoned while the deactivation is legitimate). Wrap the reporting call in
+`try/catch (Throwable)` so reporting can never fail the job, and `is_object()`-guard any property
+read you feed it — `_Error` promotes a *"read property on int"* warning into a job-killing exception.
+
 ## Change history
 
+- 2026-08-19 — Recorded that **email recipients are configured per `issueId`, not per `issueKey`**,
+  so they cannot be pre-configured before a condition first fires — the `Logs.Issue` row must exist
+  first, which means the **first occurrence of any new business exception always routes to a
+  developer ClickUp task**. Documented the Tools path (`/errors` → issue → "Email recipients" →
+  "Add recipient"), the `Logs.IssueEmailAddress` write + `Issue.isManaged = 1` side effect,
+  `loadRecipientsByIssueId()` on the worker2 side, `clientId 0` = all clients, and the production
+  census (only issue 24 `COMPASS_SALES_ORDER_MITS_TRANSMIT_REJECTED` is managed; issue 208
+  `COMPASS_OFFICE_DEPOT_PO_IMPORT_REJECTED_OVER_QUANTITY` still routes to ClickUp for want of
+  recipients). Also recorded **non-throwing
+  `_Error::captureException(new _Exception_Business(...))`** as a supported pattern for an
+  unresolved leg of an otherwise-valid job, with the Rate carrier-cancel worked case and the
+  `is_object()` guard. (mhammontree)
 - 2026-08-18 — Recorded the environment-provisioning gotcha: the `Logs` cluster tables
   (`Issue`/`Event`/`IssueFingerprint`/…) come from the `dbchanges2/Logs/` migrations, and an
   environment missing them fails inside `_Error::captureException()` (e.g. `"Table

package/knowledge/2.0/apps/toga2-commerce/features/expedited-shipping-gating.md

@@ -27,8 +27,12 @@ selected expedited method auto-resets to **"Standard Ground"**. The behavior is
 driven** — a tenant opts in per shipping-method field via an `optionGates` entry; there is no
 `if (clientSlug === ...)` branching. Omitting `optionGates` means expedited is always shown.
 
-Applies today to all three tenants: **COMPASS**, **COMPASSCANADA** (English + French), and
-**QUAD**.
+Applies today to: **COMPASS** (USER/MANAGER/SUPERUSER — **not ADMIN**, see below),
+**COMPASSCANADA** (English + French), and **QUAD**. Because configs are **per role**
+(`.../FIELDS/<CLIENT>/<LANG>/<ROLE>/CARTPAGE.ts`), opting a single role out of the gate is done
+by dropping `optionGates: [EXPEDITED_SHIPPING_GATE]` from that one role's shipping-method field —
+no shared-logic or client-branching change. **Compass USA ADMIN** now omits the gate, so admins
+always see every method (Standard Ground + both expedited) in both regular and edit-order mode.
 
 ## Key files / entry points
 - `src/pages/Cart/helpers/shippingOptionGates.ts` (NEW) — pure helpers + types:
@@ -40,8 +44,10 @@ Applies today to all three tenants: **COMPASS**, **COMPASSCANADA** (English + Fr
   `EXPEDITED_SHIPPING_GATE` config constant: `optionNames` `["2nd Day EOB","Next Day Air"]`,
   `visibleWhen { item: "primaryItem", path: "item.itemCategory.name", operator: "equals",
   value: "COMPUTERS" }`.
-- 15 `CARTPAGE.ts` files (COMPASS x4 roles, COMPASSCANADA ENGLISH x4 + FRENCH x4, QUAD x3) —
-  each shipping-method field opts in via `optionGates: [EXPEDITED_SHIPPING_GATE]`.
+- `CARTPAGE.ts` files (COMPASS USER/MANAGER/SUPERUSER — **ADMIN opted out**, COMPASSCANADA
+  ENGLISH x4 + FRENCH x4, QUAD x3) — each shipping-method field opts in via
+  `optionGates: [EXPEDITED_SHIPPING_GATE]`. `COMPASS/ENGLISH/ADMIN/CARTPAGE.ts` intentionally
+  omits it (and its now-unused import).
 - `src/pages/Cart/view/cartForm/CartForm.tsx` — filters `shippingMethodOptions` through the
   gates (reactive on `cartData.cartBundles`) before the select renders; resolves the shipping
   field via `findShippingMethodField`; uses `SHIPPING_OPTION_LABEL_SEPARATOR` for the
@@ -103,6 +109,14 @@ behavior is expressed in config, not in code branches.
   on that doc's slice-2 work-list.
 
 ## Change history
+- 2026-08-19 — **Compass USA ADMIN role opted out of the expedited gate.** Removed
+  `optionGates: [EXPEDITED_SHIPPING_GATE]` (and the now-unused import) from
+  `COMPASS/ENGLISH/ADMIN/CARTPAGE.ts`, so admins always see Standard Ground + Next Day Air +
+  2nd Day EOB in both regular commerce mode **and** edit-order mode. Because configs are per
+  role, dropping the gate on the ADMIN config alone is the scoped customization — no
+  shared-logic or client-branching change. Side effect: in edit-order mode an existing order's
+  expedited selection is no longer hidden/reset to Standard Ground for admins.
+  USER/MANAGER/SUPERUSER still gate expedited behind a computer kit. (apeterson)
 - 2026-08-19 — No change to expedited visibility. Noted that the shared shipping-rule type
   gained an optional `requireNoOtherItemsInKit` flag (+ `bundleHasOtherItems()` helper) used by
   the separate Standard Ground cost waiver — see

package/knowledge/2.0/apps/toga2-commerce/features/shipping-cost-waiver-gating.md

@@ -51,9 +51,18 @@ four Compass USA role configs (USER/ADMIN/MANAGER/SUPERUSER).
 4. When the selected method qualifies, the effect in `CartPage` waives its `c_cost` to 0 before
    writing `salesOrder.shipping`.
 
-Resulting Compass USA behavior: bare computer kit (primary computer only) → Standard Ground
-free; computer kit **with** other items → charged $10; all non-computer kits → charged;
-expedited methods unchanged (still priced).
+Resulting Compass USA behavior (full truth table, confirmed complete — no further code change):
+- **Solo computer kit on Standard Ground** → **$0** (waived; the freight is covered by the
+  `LT-FREIGHT` fee). "Solo" is scoped to the **kit** (`bundleProgressContents` has no non-primary
+  items), not the whole order.
+- **Computer kit WITH other items in the kit, or any non-computer kit** → charged Standard
+  Ground **$10** (not waived).
+- **Expedited (Next Day Air / 2nd Day EOB) + computers** → charged the method's `c_cost`
+  (2nd Day **$50**, Next Day **$100**), **never waived**.
+
+All dollar amounts live in **`ShippingMethods.c_cost` in the Compass USA client DB** (developer
+confirmed correct), **not** in frontend code — the waiver logic only zeroes a `c_cost`, it never
+sets a price.
 
 ## Gotchas
 - **The waiver only means what the flag says.** Before this fix the gate had no
@@ -68,6 +77,12 @@ expedited methods unchanged (still priced).
   a computer kit mis-categorized in the catalog will neither waive nor gate.
 
 ## Change history
+- 2026-08-19 — Confirmed the Compass USA shipping-charge truth table is fully satisfied by the
+  existing logic (no code change): solo computer kit on Standard Ground → $0 (waived, covered by
+  `LT-FREIGHT`); kit with other items or any non-computer kit → $10; expedited + computers →
+  method `c_cost` (2nd Day $50 / Next Day $100), never waived. Documented that all dollar amounts
+  live in `ShippingMethods.c_cost` in the Compass USA client DB, not in frontend code, and that
+  "solo computer" is scoped to the kit not the order. (apeterson)
 - 2026-08-19 — Fixed an over-broad Standard Ground waiver for Compass USA computer-kit carts:
   added the optional `requireNoOtherItemsInKit` flag on `PrimaryItemShippingRule` and the
   `bundleHasOtherItems()` helper, and set the flag on

package/knowledge/clients/rate/INDEX.md

@@ -2,7 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [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, worker2/Worker/Rate.php, api2/Component/Api/V2/V2.php, test/@Mark/Rate/verify_aig_contract_identifier_persistence.php, test/@Mark/Rate/audit_wh_missing_aig_contracts.php, test/@Mark/Rate/aig_contract_lookup.php |
+| [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, worker2/Worker/Rate.php, api2/Component/Api/V2/V2.php, test/@Mark/Rate/verify_aig_contract_identifier_persistence.php, test/@Mark/Rate/audit_wh_missing_aig_contracts.php, test/@Mark/Rate/aig_contract_lookup.php, test/@Mark/Rate/cancel_aig_contract.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-10, TRUE-80575) — A FIXED (uncommitted), B DECIDED (not built) > > **A. | worker2/Worker/Rate.php, worker2/Config/production.ini, api2/Config/production.ini, _underscore/Component/Api/Paypal/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 |

package/knowledge/clients/rate/features/aig-contract-creation.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: rate
 type: client-feature
 status: active
-updated: 2026-08-18
+updated: 2026-08-19
 owners: [mhammontree, tcox]
 files:
   - _underscore/Model/Rate/Entitlement.php
@@ -17,6 +17,7 @@ files:
   - test/@Mark/Rate/verify_aig_contract_identifier_persistence.php
   - test/@Mark/Rate/audit_wh_missing_aig_contracts.php
   - test/@Mark/Rate/aig_contract_lookup.php
+  - test/@Mark/Rate/cancel_aig_contract.php
 related:
   - clients/rate/profile.md
   - ../../../2.0/apps/api2/features/api-payload-interceptors.md
@@ -147,6 +148,23 @@ it sent blanks and AIG rejected them. `ET100014` was never "unexplained" — it
 All three now have both an address and a `ContactPhoneNumbers` row, so a replay should be accepted
 — **but read the duplicate-contract rule below first.**
 
+## Data repair — `ET100013` cancelled at the carrier (2026-08-19, production)
+
+Doug Winter — entitlement **39**, contact **226**, subscription **20** (`I-KE367533YH1L`):
+
+1. Backfilled `c_aigContractNumber = '1000045962407'` and `c_aigContractId = 45962407` (taken from
+   AIG's report; id derived by stripping `10000`). The developer ran the UPDATE directly — **no
+   `dbchanges2` migration retained**, matching the `ET100020` precedent.
+2. Cancelled at the **live** carrier — HTTP **200** `{"errors":null,"successful":true}`.
+
+The subscription was already `isActive 0`, `dateEnd = dateCancelled = 2026-08-18`, with
+`dtRequestToCancel` **NULL** — i.e. cancelled by the **webhook handler**, not the portal `cancelApi`.
+
+**STILL OPEN — `ET100014` (Kimberly Stearns) and `ET100015` (Daniel Moran)** are the same shape: WH,
+**both** identifiers NULL, previously 400'd by depth starvation. They need their **contract numbers
+from AIG's report** before they can be cancelled. Note this doc's replay guidance targets
+`POST /contract` (which *creates* coverage) — **these two need `/contract/cancel` instead.**
+
 ## ⚠ A NULL identifier does NOT mean the contract is missing (pre-TRUE-81049 rows)
 
 **The most important operational rule in this doc.** On any entitlement created **before**
@@ -157,12 +175,64 @@ the contract, our columns were NULL.
 **Replaying such a row creates a DUPLICATE contract at the carrier.** Before any replay or repair:
 
 1. Query `Logs_Rate.Api` for a **2xx `POST .../contract`** for that customer.
-2. **Match on the customer EMAIL, not `contractNumber`** — the `contractNumber` we sent was a
-   throwaway uuid that matches nothing on our side.
+2. **Match on the customer EMAIL, not `contractNumber`** — the `contractNumber` we sent was
+   *usually* a throwaway uuid that matches nothing on our side (but not always — see
+   "AIG holds contracts our API never created" below).
 3. If a success exists → **backfill** the identifiers from AIG's logged response. Never replay.
 4. If the log window contains **zero** rows at all → the answer is **INCONCLUSIVE**, not "never
    attempted."
 
+## ⚠⚠ `POST /contract/cancel` REQUIRES `contractNumber` — the shipped cancel had NEVER worked
+
+**Verified against the LIVE carrier on 2026-08-19** (`aigContractId 45962407`):
+
+| Payload | AIG response |
+|---|---|
+| `{aigContractId, cancelRequestDate}` — **what we shipped** | HTTP **400** `{"errors":[{"errorCode":"76","errorDescription":"Required fields not provided"}],"successful":false}` |
+| `{aigContractId, cancelRequestDate, contractNumber}` | HTTP **200** `{"errors":null,"successful":true}` |
+
+`worker2/Worker/Rate.php::cancelAigContract()` (~L566) sent only the first shape, so **every AIG
+cancellation we have ever attempted failed** — and because that method `catch`es, `error_log()`s and
+returns `false`, it failed **silently**. This doc previously recorded only that `/contract/cancel`
+exists; it did not record its required fields. That gap is the bug.
+
+**This is independent of the NULL-identifier problem.** Even a row with a populated
+`c_aigContractId` would have 400'd. Fixing the identifiers alone would not have cancelled anything.
+Working payload is `{aigContractId, cancelRequestDate, contractNumber}` — send the stored
+`c_aigContractNumber`.
+
+## `c_aigContractId` is derivable from `c_aigContractNumber` — strip the leading `10000`
+
+Verified across **all 7** `Client_Rate` entitlements that hold both values:
+
+`1000045859462`→`45859462` (ET100011) · `1000045886119`→`45886119` (ET100012) ·
+`1000046067341`→`46067341` (ET100016) · `1000046232878`→`46232878` (ET100017) ·
+`1000046411721`→`46411721` (ET100018) · `1000046482036`→`46482036` (ET100019) ·
+`1000046483092`→`46483092` (ET100020)
+
+AIG ids also run **sequentially by purchase date**, which independently corroborates a derived
+value. **Why it matters:** AIG exposes no lookup endpoint, so when all you have is a contract number
+off AIG's report, you can still compute the `aigContractId` the cancel call needs.
+
+## ⚠ AIG holds contracts our API never created — a NULL identifier does not prove *absence* either
+
+Doug Winter `ET100013` (entitlement 39) is the proof, and it **corrects** this doc's earlier claim
+that the `contractNumber` AIG holds is always a throwaway uuid matching nothing on our side:
+
+- Our **only** outbound `/contract` call for him was `Logs_Rate.Api` id `4180950`, 2026-04-01,
+  HTTP **400** (depth starvation — `contractNumber ""`, `saleItemId ""`, blank customer
+  id/name/email; AIG answered *"SaleItemId field is required / ContractNumber field is required"*).
+- **Zero** outbound calls on 2026-05-01 — so the recurring PayPal charge does **not** re-trigger
+  contract creation. Only *entitlement creation* does.
+- **Yet AIG's own report showed an ACTIVE contract**, CCN
+  `f8685561-2177-6e62-16d0-4d70865db51b` — **our real stored entitlement uuid** — under AIG CN
+  `1000045962407`.
+
+**Practical rule: our logs cannot prove a customer is uncovered. AIG's report is the authority.**
+A NULL identifier plus no logged success means *inconclusive*, in **both** directions — the earlier
+rule covered "coverage may exist despite NULL columns"; this adds "coverage may exist even when our
+only logged attempt failed."
+
 ## AIG exposes NO contract lookup endpoint (verified 2026-08-18)
 
 Only three AIG routes exist for us: `POST /authentication/login`, `POST /contract`, and
@@ -197,6 +267,22 @@ and every other `/authentication/login` row. Readable by anyone with production
 > The credential **value** is deliberately not recorded anywhere in this knowledge base — only
 > where the exposure lives.
 
+**Third instance of the same exposure class (found 2026-08-19):** an uncaught DB connect failure
+prints the production DB **username and password** in the stack trace — observed live this session
+with `ENVIRONMENT=production`.
+
+The mechanism is **not** positional arguments: `_Database_Driver_Mysql::connect()`
+(`_underscore/Database/Driver/Mysql.php:10`) already calls `mysqli_connect()` with **named**
+arguments. PHP renders the arguments of **every** stack frame, and PHP 8.2+ marks
+`mysqli_connect`'s password with `#[\SensitiveParameter]` — so *that* frame safely shows
+`Object(SensitiveParameterValue)`. **Our wrapper's own `string $password` parameter carries no such
+attribute, so the wrapper's frame prints it in plaintext.** There are **zero** uses of
+`#[\SensitiveParameter]` anywhere in the non-vendor codebase, so this applies to every credential
+our own code accepts as a parameter.
+
+Not Rate-specific; noted here only because it was hit while working this flow. (The other two: this
+AIG auth body, and the plaintext live PayPal secret in `api2/Config/production.ini`.)
+
 ## Diagnostic & repair tooling (`test/@Mark/Rate/`)
 
 Reusable team diagnostics, not throwaways. The CLI scripts bootstrap `worker2`/`_underscore`.
@@ -219,6 +305,25 @@ Reusable team diagnostics, not throwaways. The CLI scripts bootstrap `worker2`/`
   *If AIG ever provides a lookup endpoint, promote this into the `tools` repo behind the Active
   Directory login (TRUE-78064 SSO pattern) so support can self-serve.*
 
+- **`cancel_aig_contract.php`** — the reusable AIG cancel/repair one-off (TRUE-81049, 2026-08-19).
+  **Dry-run by default**; `APPLY=1` to act; `CONFIRM_PRODUCTION_AIG=1` required for the live
+  carrier; `NO_DB=1` for the prod-cluster-unreachable case (skips the DB read/backfill and prints
+  AIG's response as the only record); `CANCEL_EXTRA` takes JSON merged into the payload for field
+  iteration; `FORCE=1` overrides the refusal to cancel a subscription that is not already cancelled
+  on our side. It **backfills the identifiers BEFORE calling the carrier**, because the carrier call
+  is irreversible and the write is not. Prints AIG's verbatim response body.
+
+**⚠ Test-harness gotcha — a worker2-bootstrapped local script CANNOT reach `Client_<Tenant>` in
+production.** `worker2/Config/production.ini` has a **single** `[database] hostname` pointing at the
+**Core** cluster, and in production `Core` / `Client_*` / `Logs*` are **separate clusters** — so
+`_Database::register()` for `Client_Rate` fails with *"Unknown database"*. Locally everything sits
+behind one endpoint, so this **only bites against production**;
+`audit_wh_missing_aig_contracts.php` has the same limitation and was only ever run against
+sandbox-dev. That is what `NO_DB=1` above exists for. **Corollary:** setting
+`_ApiRequest::isLoggingEnabled = true` while `DB_CLIENT_LOGS` is unregistered makes the log write
+throw *after* the HTTP call, and `_underscore`'s error handler then **exits** — silently killing a
+script between two API calls with no output. **Logging must follow database availability.**
+
 **Test-harness gotcha (bit us live):** in a verify script, **reads go to the READ host and cannot
 see the WRITE host's uncommitted rows** — a successful write reads back as a silent no-op and a
 passing fix looks broken. Call `_Database::transactionCommit()` before **every** read-back, and
@@ -264,9 +369,11 @@ creation vs. cancellation. This is an accepted, documented limitation — not an
   **outbound response** (`api2/Component/Api/V2/V2.php:5934` passes `$outData`), which the engine
   returns and never saves. This is why the AIG identifiers silently never persisted. See the
   [API payload interceptors](../../../2.0/apps/api2/features/api-payload-interceptors.md) doc.
-- **`c_aigContractId` is what CANCELS the carrier contract** — `worker2` `_Worker_Rate:521` uses
-  it. A NULL means the AIG contract **can never be cancelled**: the customer stops paying us and
-  coverage stays active at AIG. That is the real cost of the persistence bug.
+- **Cancelling the carrier contract needs BOTH `c_aigContractId` AND `c_aigContractNumber`** —
+  `worker2` `_Worker_Rate:521` gates on the id, but `/contract/cancel` rejects a payload without the
+  number (see the required-fields section above). A NULL means the AIG contract **can never be
+  cancelled**: the customer stops paying us and coverage stays active at AIG. That is the real cost
+  of the persistence bug.
 - **Ordering: TRUE-81049 must land before/with TRUE-80575.** TRUE-80575's worker2 handler
   re-reads the entitlement and alerts when `c_aigContractId` is empty — until identifiers
   persist, that check false-alarms on **every** purchase. TRUE-80575 (1 `_underscore` commit + 3
@@ -295,6 +402,31 @@ creation vs. cancellation. This is an accepted, documented limitation — not an
 
 ## Change history
 
+- 2026-08-19 — TRUE-81049 (fix parked in that already-scheduled deployment; no new ticket):
+  **`POST /contract/cancel` requires `contractNumber`, so the shipped AIG cancel had NEVER
+  worked.** Verified against the live carrier on `aigContractId 45962407` — the shipped
+  `{aigContractId, cancelRequestDate}` returns HTTP 400 errorCode 76 *"Required fields not
+  provided"*; adding `contractNumber` returns HTTP 200 `successful: true`. Silent because
+  `cancelAigContract()` catches/logs/returns false; **independent of the NULL-identifier bug** (a
+  populated id would still have 400'd). Fixed in `worker2/Worker/Rate.php` (~L566), commit
+  `a399145` on branch TRUE-81049 — **committed, not pushed.** Also recorded: `c_aigContractId` is
+  **derivable** from `c_aigContractNumber` by stripping the leading `10000` (verified on all 7 rows
+  holding both; AIG ids are sequential by purchase date), which is the workaround for the missing
+  lookup endpoint; **AIG holds contracts our API never created** — `ET100013`'s only `/contract`
+  call was a 400 and the recurring PayPal charge does *not* retry creation, yet AIG's report shows
+  an ACTIVE contract carrying **our real entitlement uuid** as its CCN, correcting the
+  "throwaway uuid matches nothing" claim and establishing that **AIG's report, not our logs, is the
+  authority** on coverage; the **`ET100013` production repair** (backfill + live cancel, direct
+  UPDATE, no migration kept) with `ET100014`/`ET100015` **still open** pending their contract
+  numbers from AIG; the new `test/@Mark/Rate/cancel_aig_contract.php` repair tool; the
+  **prod-cluster test-harness limit** (worker2's single `production.ini` hostname cannot reach
+  `Client_Rate`; and enabling `_ApiRequest` logging without `DB_CLIENT_LOGS` kills the script
+  silently between API calls); and a **third instance of the credential-exposure class** —
+  an uncaught DB connect failure prints user+password in the stack trace, because our
+  `_Database_Driver_Mysql::connect()` wrapper's `string $password` parameter lacks
+  `#[\SensitiveParameter]` (PHP 8.2+ protects `mysqli_connect`'s own frame but not ours; zero uses
+  of the attribute exist in the non-vendor codebase). Location only, never the value.
+  (mhammontree)
 - 2026-08-18 — TRUE-81049: **corrected two claims in this doc that were wrong.** (1) The success
   path did **not** persist the generated uuid or the AIG identifiers — `postPost` receives the
   **outbound response** (`V2.php:5934` → `$outData`), so `$payload->c_aigContract*` and the

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: rate
 type: client-feature
 status: active
-updated: 2026-08-06
+updated: 2026-08-19
 owners: [mhammontree, tcox]
 files:
   - _underscore/Model/Rate/Subscription.php
@@ -39,6 +39,7 @@ related:
   - ../../../2.0/apps/_underscore/features/config-group-access.md
   - ../../../2.0/apps/api2/features/environment-variable-drives-underscore-branch.md
   - ../../../2.0/standards/backend-testing.md
+  - ../../../2.0/apps/_underscore/features/error-reporting-issue-event.md
 ---
 
 ## Summary
@@ -220,6 +221,46 @@ RecordFields id literals were verified correct per environment.
 read the cancellation columns.** This is why mirroring `dateEnd`'s grants was the right call rather
 than inventing a worker-specific role.
 
+## The carrier leg — a missing AIG identifier is now REPORTED, not silently skipped (2026-08-19)
+
+`handleSubscriptionDeactivation` (`worker2/Worker/Rate.php` ~L519) guarded the AIG cancel with
+`if ($entitlement && !empty($entitlement->c_aigContractId))` — and had **no `else`**. So a missing
+identifier abandoned the **carrier leg with no record anywhere**: the customer stopped paying while
+coverage stayed **active at AIG**. This defect was found by a **human noticing**, not by any system.
+
+Now the else branch calls `reportAigContractNotCancellable()`, which captures
+`_Exception_Business(issueKey: 'RATE_AIG_CONTRACT_CANCEL_MISSING_IDENTIFIER', URGENCY_HIGH)` naming
+**which column** is missing.
+
+**The pattern worth copying (general to 2.0):**
+`_Error::captureException(new _Exception_Business(...))` **records the issue and notifies WITHOUT
+throwing.** That is the right tool when *part* of a job is unresolved but the job itself is valid —
+throwing here would abort a subscription deactivation that is entirely correct; only the carrier leg
+is open. Precedent for the non-throwing call: `worker2/Controller/Index.php:286`. The whole
+reporting call sits inside `try/catch (Throwable)` so **a reporting path can never fail the job**.
+
+Splitting the failure modes also **sharpened the thrown exception**: a blank identifier no longer
+reaches the `throw`, so a thrown exception now means exactly one thing — **the carrier rejected a
+well-formed request.** Previously a blank `contractNumber` threw a *technical* exception and aborted
+a valid deactivation.
+
+### ⚠ The report MUST be gated on Whole Home Warranty, or it fires HIGH on every routine cancel
+
+Rate's data model makes most cancellation events legitimately carrier-free:
+
+- `Items.id 3` = **"Whole Home Warranty - Monthly"** — the **only** AIG-backed product.
+- `Items.id 1` and `2` are **tech-support** products with **no carrier contract by design**.
+- TRUE-80282's portal self-service cancellation **refuses warranties**, so **tech** cancellations
+  are the **dominant** `BILLING.SUBSCRIPTION.CANCELLED` case.
+
+Ungated, the missing-identifier report would raise a HIGH-urgency **business** alert on every
+routine tech cancellation. `isWholeHomeWarrantyEntitlement()` therefore uses the **same authority as
+the purchase guard and the DB dedup** — sale-item **title keyword `warranty`** OR **`saleItemId 3`**
+— and checks **both** the nested `saleItem` object **and** the flat `saleItemId` FK, so a **shallow
+payload cannot disable the gate**. It is `is_object()`-guarded because `_Error` promotes a
+*"read property on int"* warning into an **exception that would kill the job**. Verified
+`ET100013`/`14`/`15` all carry `saleItemId 3` / title "Whole Home Warranty - Monthly".
+
 ## ⚠ SECURITY — pre-existing unscoped ACL grant undermines this feature's core guarantee
 
 **Needs its own ticket. Found by reading the permission tables only — NOT exploited, NOT tested.**
@@ -327,6 +368,23 @@ feature rather than failing the page.
 
 ## Change history
 
+- 2026-08-19 — TRUE-81049 (fix parked in that scheduled deployment; commit `a399145`, branch
+  TRUE-81049 in worker2 — **committed, not pushed**): closed the **silent skip of the AIG carrier
+  leg** in `handleSubscriptionDeactivation`. The old `if (… !empty($entitlement->c_aigContractId))`
+  had no `else`, so a missing identifier left coverage **active at the carrier** with no record
+  anywhere — found by a human, not a system. New `reportAigContractNotCancellable()` captures a
+  **non-throwing** `_Exception_Business('RATE_AIG_CONTRACT_CANCEL_MISSING_IDENTIFIER',
+  URGENCY_HIGH)` naming the missing column, inside `try/catch (Throwable)` so reporting can never
+  fail the job; precedent `worker2/Controller/Index.php:286`. Splitting the failure modes means the
+  **thrown** exception now means exactly one thing (carrier rejected a well-formed request) instead
+  of also firing on a blank identifier and aborting a valid deactivation. Gated by new
+  `isWholeHomeWarrantyEntitlement()` on the purchase guard's authority (title keyword `warranty` OR
+  `saleItemId 3`, checked on **both** the nested object and the flat FK, `is_object()`-guarded)
+  because `Items.id 1`/`2` are tech products with no carrier contract and the portal refuses
+  warranties — so tech is the dominant cancellation case and an ungated report would alert HIGH on
+  every routine cancel. See also the AIG doc: `/contract/cancel` also **requires
+  `contractNumber`**, so the carrier cancel had never succeeded regardless of the identifiers.
+  (mhammontree)
 - 2026-08-06 — TRUE-80282 **testing & deploy**: **verified end-to-end on beta** (PayPal sandbox) —
   `POST /v2/subscriptions/cancel` returned 200 with `dateCancel: 2026-08-27`, a real sandbox
   agreement was cancelled, and `Subscriptions` id 84 confirmed `isActive = 1`, `dateEnd` untouched,

package/package.json

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