toga-ai 1.0.535 → 1.0.536

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

@@ -14,6 +14,7 @@
 | [Running 2.0 code from a bare CLI script (bootstrap + transactions)](features/cli-script-bootstrap.md) | A throwaway CLI script (a data check, a backfill dry-run, a render harness) that wants the real 2.0 framework — `_Model`, `_Query`, `_Database` — is **not** the | _underscore/Database.php, _underscore/Environment.php, api2/Initialize.php |
 | [_Cloud S3 helpers (copy / get / delete / list)](features/cloud-s3-helpers.md) | `_Cloud` centralizes AWS SDK S3 usage for the 2.0 stack so the `S3Client` never leaks into workers or app code. | _underscore/Cloud.php |
 | [_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps](features/component-model-namespace-registration.md) | Every **project-local** `_Component_*` and `_Model_*` class in a 2.0 app **must declare the project namespace** at the top of the file: ```php namespace <NAMESP | _underscore/Loader.php, worker2/_.php, api2/_.php, worker2/Component/Forecast/Db/Db.php, worker2/Component/Forecast/SaleImport/SaleImport.php, api2/Component/Api/Netsuite/Netsuite.php, _underscore/Component/Api/Paypal/Paypal.php |
+| [_Config group access — the two-argument "optional" form does NOT rescue a missing GROUP](features/config-group-access.md) | `_Config::<group>('<property>')` reads a value out of the active `Config/<ENVIRONMENT>.ini`, and **it throws when the requested group is absent from the ini.** | _underscore/Config.php, _underscore/Component/Api/Paypal/Paypal.php |
 | [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 |
 | [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 |
@@ -23,7 +24,7 @@
 | [isFulfillable Propagation Up the SO↔PO Chain](features/fulfillable-item-propagation.md) | `Items.isFulfillable` is a boolean that gates whether a storefront line's **Qty Fulfilled** cell is actionable. | _underscore/Model/Client/Item.php, _underscore/Model/Compass/Item.php, dbchanges2/Core/2026-07-17 - Items isFulfillable RecordField.sql, dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql, dbchanges2/Client/2026-07-17 - ItemsisFulfillable.sql |
 | [Item-Fulfillment Stage Lifecycle (picked/packed/shipped) & Order Status](features/item-fulfillment-stage-lifecycle-and-order-status.md) | Every ItemFulfillment (IF) now carries an explicit **stage** — picked → packed → shipped — resolved through `ItemFulfillmentStages → ItemFulfillmentStatuses` (m | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Client/SalesOrderItem.php, _underscore/Model/Client/Item.php, _underscore/Model/Client/PurchaseOrderItem.php, library/app/api/toga2.php, dbchanges2/Client/2026-06-30a - BackfillNullStageItemFulfillmentsToShipped.sql, dbchanges2/Client/2026-06-30b - SalesOrderStatusesPickedPacked.sql, dbchanges2/Client/2026-06-30c - ItemFulfillmentStageIdNotNull.sql, dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql |
 | [DB-free unit testing for _underscore model interceptors](features/model-interceptor-unit-testing.md) | `_underscore` shipped with **no** PHPUnit setup (no `composer.json`/`phpunit`; only vendored PhpOffice tests existed). | _underscore/Test/bootstrap.php, _underscore/Test/Prudential/ServiceRequestTest.php |
-| [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
+| [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php, _underscore/Model.php, _underscore/Model/Rate/Subscription.php |
 | [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.php, _underscore/Model/Rate/Subscription.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/Query.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, api2/Controller/Index.php |

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -272,6 +272,52 @@ empty with no error anywhere**. The same audit found `lengthMeasureId`/`weightMe
 **role 3 only, not role 1** — grant fan-out is per-client and must be verified per client, not
 assumed from one.
 
+## ⚠ `appId` / `indirectRecordId` BOTH NULL = a grant with NO SCOPING AT ALL
+
+The optional `appId` and `indirectRecordId` columns on `AclRecordPermissions` are what narrow a
+grant to an app and to a related-record path. **When both are NULL the grant is unscoped**, and
+combined with an `AclRecordExpressions` `sqlExpression = '1'` there is *nothing left* restricting
+which rows the role reaches. Read those two columns as part of every grant review — an unscoped row
+looks identical to a scoped one at a glance.
+
+**Why this is easy to get catastrophically wrong: the `Base` role is not a low-privilege role.**
+Every portal end-customer carries `Base`, and so do API service users. A grant to `Base` is
+effectively a grant to *the public*, and `AclFieldPermissions.isWritable = 1` on a business-critical
+column then makes that column **customer-writable through ordinary CRUD** — completely independently
+of any scripted endpoint's server-side logic.
+
+**This is why a record script must do its own ownership check.** A scripted endpoint that computes a
+value server-side (precisely so the customer cannot choose it) is **not** protected if plain
+`PUT /v2/<record>/{uuid}` can write the same column. The explicit ownership check inside the script
+is load-bearing, not defensive coding.
+
+**Audit recipe.** For any record exposed to end customers, list every `AclRecordPermissions` row
+with its `appId`/`indirectRecordId`, then cross it with `AclFieldPermissions.isWritable = 1`. The
+dangerous combination is *unscoped record grant × writable business column*. Do it **per
+environment** — grant fan-out is per-client and per-environment (see the audit notes above).
+
+## Verified: role UNION means a service user inherits `Base`
+
+A row in `Client_<Slug>.Apis` can carry **more than one role**, and its effective permissions are
+the **union**. Confirmed 2026-08-06 in `Client_Rate`: the `Apis` row for the worker's API uuid
+carries **both `Base` and `API`**, so the worker inherits every `Base` field grant. Practical
+consequence, and the reason the "mirror a sibling field" practice works: **granting a column to
+`Base` also grants it to the worker.** Conversely, when auditing what an end customer can reach,
+remember the reverse — a grant added "for the worker" on `Base` reaches customers too.
+
+## Client-DB grant migrations are re-runnable NO-OPs, and that is the design
+
+A `NOT EXISTS`-guarded `AclFieldPermissions` insert that finds its grants already present inserts
+nothing and exits clean. **That is a success, not a wasted migration** — the file still protects a
+freshly-created blank client DB, and it is safe to re-run in every environment. Do not "clean up"
+such a file because it no-ops where you tested it.
+
+Distinguish this carefully from the **broken** silent no-op: a `Client_*` migration that
+cross-schema-subselects `Core` also inserts zero rows without erroring, but for the wrong reason.
+Live re-confirmation 2026-08-06: a `Client_Rate` → `Core` JOIN on the production cluster is
+**refused outright — `Unknown database 'Core'`**. That is exactly why `Client_*` migrations must use
+hardcoded `Core.RecordFields` id literals instead of a subselect.
+
 ## Checklist (so the chain is never half-built)
 
 - [ ] `AclRecordPermissions` row for the role × record with the right CRUD flags.
@@ -279,12 +325,28 @@ assumed from one.
 - [ ] `AclLogicGroups` row with `operator` set (AND/OR) referencing the permission.
 - [ ] `AclLogicGroupExpressions` row binding the group to the expression.
 - [ ] `AclFieldPermissions` rows for every field that must be readable/writable.
+- [ ] **`appId` / `indirectRecordId` are set** unless a genuinely unscoped grant is intended — both
+      NULL plus `sqlExpression='1'` means no row scoping whatsoever (see the section above).
+- [ ] **No business-critical column is `isWritable = 1` for `Base`** unless customers are genuinely
+      meant to write it via plain CRUD.
 - [ ] For `aclDatabase = 'CLIENT'` records: rows go in client DB(s); resolve `roleId` by subselect.
 - [ ] The field is declared on the **generated** `_underscore/Model/Client/<Name>.php` (else `EO-1`),
       and every repo is on the **same branch** so the generated model matches the DB.
 
 ## Change history
 
+- **2026-08-06** — TRUE-80282 testing: recorded that **`appId` + `indirectRecordId` both NULL is a
+  grant with no scoping at all**, that **`Base` is not a low-privilege role** (every portal customer
+  and API service user carries it), and that the dangerous combination to audit for is *unscoped
+  record grant × `isWritable = 1` business column* — which lets a customer write via plain
+  `PUT /v2/<record>/{uuid}` regardless of a script's server-side computation, and is therefore why a
+  record script's own ownership check is load-bearing. Added the per-environment audit recipe. Also
+  verified that an `Apis` row can carry **multiple roles with union semantics** (`Client_Rate`'s
+  worker API uuid carries both `Base` and `API`, so granting a column to `Base` also grants it to the
+  worker), and that a `NOT EXISTS`-guarded grant migration that no-ops where the grants already exist
+  is **working as designed** — distinct from the broken cross-schema no-op, whose cause was
+  re-confirmed live: a `Client_Rate` → `Core` JOIN on the prod cluster is refused with
+  **`Unknown database 'Core'`**. (mhammontree)
 - **2026-08-04** — TRUE-80282: sharpened the ungranted-field failure shapes — a directly-requested
   ungranted field is **absent, not null** (so `=== null` checks miss it), while an ungranted
   **joined** field fails the **whole request** (`EZ-2`), so one grant can blank an entire page. Added

package/knowledge/2.0/apps/_underscore/features/config-group-access.md

@@ -0,0 +1,95 @@
+---
+title: _Config group access — the two-argument "optional" form does NOT rescue a missing GROUP
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-08-06
+owners: ["mhammontree"]
+files:
+  - _underscore/Config.php
+  - _underscore/Component/Api/Paypal/Paypal.php
+related:
+  - ./cli-script-bootstrap.md
+  - ./model-magic-field-access.md
+  - ../../api2/features/environment-variable-drives-underscore-branch.md
+  - ../../../../clients/rate/features/subscription-cancellation.md
+---
+
+## Summary
+
+`_Config::<group>('<property>')` reads a value out of the active
+`Config/<ENVIRONMENT>.ini`, and **it throws when the requested group is absent from the ini.**
+The widely-assumed "optional" second argument — `_Config::paypal('client_id', false)` — **does not
+make a missing group safe.** It only rescues a missing *property inside a group that exists*.
+
+The only reliable way to read config that may not be present in every environment is to test the
+group first:
+
+```php
+if (!\_Config::isGroupSet('paypal')) {
+    throw new \_Exception_Business('Payment provider is not configured for this environment.');
+}
+$clientId = \_Config::paypal('client_id');
+```
+
+## How it works — why the `false` flag is ignored for a missing group
+
+`_Config::__callStatic` (`_underscore/Config.php:64-87`) receives the method name as the group and
+`$properties` as the argument list, where `$properties[0]` is the property **name** and
+`$properties[1]` is the optional/`false` flag.
+
+The missing-group branch tests **`$properties[0]`** to decide whether the caller asked for an
+optional read — but it does so **before `array_shift()` has run**, so at that moment
+`$properties[0]` is still the property *name* (a non-empty string, therefore truthy), not the
+`false` flag. The guard consequently never sees the caller's intent and execution falls through to
+the throw at **line 85**.
+
+So the behavior is:
+
+| Call | `[paypal]` group missing | property missing, group present |
+|---|---|---|
+| `_Config::paypal('client_id')` | **throws** | throws |
+| `_Config::paypal('client_id', false)` | **throws** (the flag is not consulted) | returns falsy — works as intended |
+
+This is an off-by-one in the argument inspection, not intended design. Do not "fix" a
+missing-group crash by adding the `false` flag; it will not help.
+
+## Why this matters more than it looks
+
+Config groups are **not uniform across environments.** `Config/<ENVIRONMENT>.ini` files are
+maintained per tier (see
+[ENVIRONMENT drives the branch and Config file](../../api2/features/environment-variable-drives-underscore-branch.md)),
+so a group added for one tier routinely does not exist in the others. Any code path reading a
+group that isn't universal — a payment provider, a carrier account, an optional integration — is
+one deploy away from throwing in a tier nobody tested.
+
+Because this throws rather than returning null, the failure surfaces to whoever triggered the
+request. Concrete case (Rate subscription cancellation, 2026-08-06): a cancel executed in any
+environment without a `[paypal]` section returned **`EO-1` with a stack trace to a logged-in
+retail customer** instead of failing cleanly with a business message. Guarding with
+`isGroupSet()` turned it into a controlled `_Exception_Business`.
+
+## Gotchas / known issues
+
+- **`_Config::<group>('prop', false)` is NOT a null-safe read.** It is property-optional only.
+  Group-optional requires `_Config::isGroupSet('<group>')`.
+- **A missing group is an uncaught throw on the user's request**, not a silent null — so the
+  blast radius is a visible 500/`EO-1`, not a quiet misbehavior. Guard before you read.
+- **Never guard by catching the exception broadly.** Wrap the `isGroupSet()` check in a
+  meaningful business error instead, so the caller learns *the environment is not configured*
+  rather than *something went wrong*.
+- **Do not record credential values anywhere.** Document only which ini and which group a
+  credential lives in (e.g. `api2/Config/beta.ini` `[paypal]`).
+
+## Change history
+
+- 2026-08-06 — TRUE-80282 testing: documented that `_Config::<group>()` **throws when the group is
+  absent** and that the two-argument "optional" form does **not** rescue a missing group —
+  `_Config::__callStatic` (`Config.php:64-87`) tests `$properties[0]` for the optional flag
+  **before `array_shift()`**, so it sees the property name (truthy) instead of `false` and reaches
+  the throw at line 85 anyway. `isGroupSet('<group>')` is the only working guard. Found because a
+  cancel in an environment with no `[paypal]` section returned `EO-1` with a stack trace to a
+  logged-in customer. (mhammontree)

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

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
-owners: ["dfranks", "jcardinal"]
+updated: 2026-08-06
+owners: ["dfranks", "jcardinal", "mhammontree"]
 files:
   - _underscore/Error.php
   - _underscore/Database.php
@@ -387,8 +387,32 @@ app that has not been wired up yet.
 in `_underscore` and `library` in the **same** release, and the `/errors` console work needs
 **both** `library` and `tools` deployed before it is visible.
 
+## ⚠ OPEN DEFECT (2026-08-06) — error capture is DEAD on sandbox-dev/beta: `Logs.Issue` is missing `clickupPriority`
+
+**Anyone debugging on that environment is flying blind.** The capture INSERT fails with **MySQL 1054
+(unknown column)** because `Logs.Issue` there has `clickupAssigneeId` and `createsClickupTask` but
+**not `clickupPriority`**. Consequences:
+
+- **No error is persisted at all** — no `Logs.Issue` row, no `Logs.Event` row, no ClickUp task.
+- The only trace is inline in the API response as **`identifiers.captureFailure`**. If you are
+  looking in the database or ClickUp for an error you just triggered and finding nothing, look at the
+  response body for `captureFailure` before concluding the error didn't happen.
+
+**Cause:** `_underscore` commit `4ebe12fe` *"Improve error fingerprinting, add ClickUp priority
+tracking"* shipped the code that writes the column **without its schema migration reaching that
+environment.** Fix is a one-column `dbchanges2` migration in the `Logs` folder.
+
+**The general lesson (this is the pipeline's structural weak point):** error capture is the one
+subsystem whose own failure cannot be reported through itself. A schema drift here does not degrade
+gracefully — it silently deletes all observability for the whole tier. Any change adding a column to
+`Logs.Issue`/`Logs.Event` must land its migration in **every** environment in the same release; see
+*Deploy order* above.
+
 ## Gotchas / known issues
 
+- **⚠ A missing `Logs.Issue` column silently disables ALL error capture on that environment** —
+  see the open defect above. Symptom: `identifiers.captureFailure` in the API response and nothing
+  anywhere else.
 - **Read-your-writes: reads go to the READ host and cannot see an uncommitted write.** A
   second `$issue->save()` re-reads the row via `_Model::initialize()`, and that SELECT goes to
   the read host — a separate connection that cannot see the still-uncommitted INSERT on the
@@ -539,6 +563,15 @@ clientUserId). **Neither was built.** As built instead:
 
 ## Change history
 
+- 2026-08-06 — Recorded an **open defect**: error capture is entirely dead on sandbox-dev/beta
+  because `Logs.Issue` there lacks the **`clickupPriority`** column, so the capture INSERT fails with
+  MySQL 1054 and **no** Issue row, Event row, or ClickUp task is written — the only trace is
+  `identifiers.captureFailure` inline in the API response. Cause: `_underscore` commit `4ebe12fe`
+  ("Improve error fingerprinting, add ClickUp priority tracking") shipped without its schema
+  migration reaching that environment; needs a one-column `dbchanges2` `Logs` migration. Generalized
+  the lesson — this subsystem cannot report its own failure, so `Logs` schema drift silently deletes
+  all observability for a whole tier rather than degrading. Found while debugging TRUE-80282 on beta.
+  (mhammontree)
 - 2026-08-05 — **Data model:** `Issue` gained an Issue-level **OPEN → RESOLVED** lifecycle
   (`status`, `dtAutoResolved`) plus a durable firing baseline (`baselineGapSeconds`,
   `baselineSampleCount`, `dtBaselineAnchor`, `baselineAnchorOccurrences`), migration

package/knowledge/2.0/apps/_underscore/features/model-magic-field-access.md

@@ -6,12 +6,16 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-28
-owners: ["jcardinal"]
+updated: 2026-08-06
+owners: ["jcardinal", "mhammontree"]
 files:
   - _underscore/Model/Core/Model.php
+  - _underscore/Model.php
+  - _underscore/Model/Rate/Subscription.php
 related:
   - ../../api2/features/language-translation-layer.md
+  - ./model-save-vs-query-atomic-update.md
+  - ../../../../clients/rate/features/subscription-cancellation.md
 ---
 
 ## Summary
@@ -41,6 +45,20 @@ if (array_key_exists('uuid', $model->getFieldConfig())) {
 Check `array_key_exists('field', $model->getFieldConfig())` first, then read via `__get`. Do **not**
 gate on `isset($model->field)` or `$model->field ?? $default` — both silently misbehave.
 
+**Safe pattern for "does this field have a value?" (the emptiness test):** cast, then test the
+cast — never `empty()`/`isset()` on the property itself.
+
+```php
+// WRONG — $isRequested is permanently false even when the column holds a date
+$isRequested = !empty($subscription->dtRequestToCancel);
+
+// CORRECT — read through __get, cast to string, test the string
+$isRequested = trim((string) $subscription->dtRequestToCancel) !== '';
+```
+
+`_Model` declares `__get`/`__set` only (`_underscore/Model.php:464,481`) — there is no `__isset` on
+the base `_Model` either, so this applies to **every** 2.0 model, not just the Core one.
+
 ## Gotchas / known issues
 
 - **Treat `empty()` / `isset()` / `??` on a magic field as simply UNRELIABLE — the exact behavior
@@ -51,6 +69,19 @@ gate on `isset($model->field)` or `$model->field ?? $default` — both silently
   value into a plain local variable first and test that local.** This cost three debugging rounds
   because it failed in the "looks unauthenticated" direction — a populated identity read as empty.
   A codebase-wide sweep for `empty(`/`isset(` on model fields is warranted.
+- **⚠ An `empty()` guard on a magic field can silently break IDEMPOTENCY.** Verified empirically
+  2026-08-06 on `_Model_Rate_Subscription`: `$s->dateCancelled` returns `'2026-08-26'` while
+  `empty($s->dateCancelled)` returns **TRUE** and `isset()` returns **FALSE** on the very same
+  read. The Rate cancellation idempotency guard was written as `empty($s->dtRequestToCancel)`, so
+  `$isRequested` was **permanently false**: an already-cancelled subscription never short-circuited,
+  every button click **re-called PayPal**, and the crash-recovery branch that was supposed to
+  *preserve* an earlier attempt's recorded intent **wiped it instead**. A magic-field `empty()` is
+  not a cosmetic smell — it makes "already done?" checks structurally impossible.
+- **This is the sibling of the `save()` field-diff trap.** Both are the same underlying hazard: the
+  magic accessor layer makes correct-*looking* code silently wrong, in the direction of "nothing is
+  there." When you touch a 2.0 model, distrust both **emptiness tests** (this doc) and
+  **rollback-by-re-save** (see
+  [_Model::save() vs raw _Query](./model-save-vs-query-atomic-update.md)).
 - `isset($model->magicField)` / `$model->magicField ?? null` cannot be trusted for DB-backed
   magic fields. Use `getFieldConfig()` + `array_key_exists` to test presence.
 - A bare `__get` on an unconfigured field **throws** — never read a maybe-absent field without the
@@ -60,6 +91,15 @@ gate on `isset($model->field)` or `$model->field ?? $default` — both silently
 
 ## Change history
 
+- 2026-08-06 — TRUE-80282 testing: confirmed the gap exists on the **base `_Model`** too (it
+  declares `__get`/`__set` only, `_underscore/Model.php:464,481`), so this applies to every 2.0
+  model. Recorded the sharpest empirical case yet: `$s->dateCancelled` returns `'2026-08-26'` while
+  `empty()` returns TRUE and `isset()` FALSE on the same read. It cost a real bug — the Rate cancel
+  **idempotency guard** used `empty()`, so an already-cancelled subscription never short-circuited,
+  every click re-called PayPal, and the crash-recovery branch wiped the earlier attempt's intent
+  instead of preserving it. Added the canonical emptiness test: `trim((string) $field) !== ''`. Also
+  linked this explicitly as the sibling of the `save()` field-diff trap — both are the magic layer
+  making correct-looking code silently wrong toward "nothing is there." (mhammontree)
 - 2026-07-28 — Broadened the rule after the cross-client work: `empty()` can report a **populated**
   field as absent while `??` reads it correctly — the inverse of the 2026-06-25 symptom. The safe
   rule is now "copy to a plain local, then test the local," and a codebase-wide sweep is warranted

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

@@ -6,7 +6,7 @@
 | [API Payload Interceptors (metadata-registered prePost/postPut model hooks)](features/api-payload-interceptors.md) | A `_Model`'s `prePost()` / `postPost()` / `prePut()` / `postPut()` hooks are **not** called by the model. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/ItemFulfillment.php, dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql |
 | [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | A single authenticated V2 GET listing can return records across **many** clients (designed for 1000+) that the caller is entitled to, honoring **each target cli | api2/Component/Api/CrossClient/CrossClient.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, _underscore/Model/Cache/Table.php, _underscore/Model/Cache/Tables/Client.php, _underscore/Model/Core/Record.php, worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Cache/2026-06-30a - MultiClientCacheTables.sql, dbchanges2/Core/2026-06-30b - CacheClusterRegistrationAndRecordTtl.sql, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
 | [Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)](features/encrypted-user-uuid-auth-handoff.md) | `POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**: given an encrypted `{client, user}` UUID pair, it mints a fr | api2/Component/Api/CrossClient/CrossClient.php |
-| [ENVIRONMENT (not the EB environment name) decides the _underscore branch and Config file](features/environment-variable-drives-underscore-branch.md) | An api2 Elastic Beanstalk instance decides **which `_underscore` branch it clones** and **which `Config/<env>.ini` it loads** from the EB environment property * | api2/.ebextensions/git.php, api2/.ebextensions/php_include_underscore.config, api2/Config/beta.ini, api2/Config/sandbox-dev.ini |
+| [ENVIRONMENT (not the EB environment name) decides the _underscore branch and Config file](features/environment-variable-drives-underscore-branch.md) | An api2 Elastic Beanstalk instance decides **which `_underscore` branch it clones** and **which `Config/<env>.ini` it loads** from the EB environment property * | api2/.ebextensions/git.php, api2/.ebextensions/php_include_underscore.config, api2/.ebextensions/git.sandbox-dev.json, api2/Config/beta.ini, api2/Config/sandbox-dev.ini, api2/Component/Api/V2/V2.php |
 | [Health-check endpoint (/health liveness short-circuit)](features/health-check-endpoint.md) | `_Controller_Index::api()` short-circuits **liveness/health-probe** requests to an HTTP 200 **before** any routing, DB bootstrap, or V2 engine work runs. | api2/Controller/Index.php |
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, plus item **feature** text — `Features.name`, `ItemCategoryFeatureGroups.name`, `ItemFeatures | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql |
 | [Nested FK object embedding is gated by the CHILD record's own ACL](features/nested-fk-acl-embedding.md) | When the V2 JSON engine serializes a foreign-key field into a **nested object** (in `getFullModelData()`, ~V2.php L6016-6060), it re-checks the **child** record | api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql |

package/knowledge/2.0/apps/api2/features/environment-variable-drives-underscore-branch.md

@@ -6,13 +6,15 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-05
-owners: ["bala"]
+updated: 2026-08-06
+owners: ["bala", "mhammontree"]
 files:
   - api2/.ebextensions/git.php
   - api2/.ebextensions/php_include_underscore.config
+  - api2/.ebextensions/git.sandbox-dev.json
   - api2/Config/beta.ini
   - api2/Config/sandbox-dev.ini
+  - api2/Component/Api/V2/V2.php
 related:
   - ../architecture.md
   - ../workflows/environment-configuration-and-provisioning.md
@@ -65,6 +67,38 @@ Never infer the environment from:
   point at the same cluster, `dev.sandbox.database.togahub.com`**, so querying "the dev-sandbox
   database" and finding your row proves nothing about which tier wrote it.
 
+## `api.beta.togahub.com` — the concrete mapping, and the leftover files that mislead
+
+Independently re-confirmed 2026-08-06 (cost **two deploy cycles**):
+
+- `api.beta.togahub.com` runs **`ENVIRONMENT=beta`** → reads `Config/beta.ini` → clones
+  `_underscore` branch **`_beta`**.
+- There is **deliberately NO `.ebextensions/git.beta.json`**, which is exactly why the branch falls
+  through to the derived `'_' . strtolower($env)` = `_beta`.
+- **`Config/sandbox-dev.ini` AND `.ebextensions/git.sandbox-dev.json` both still exist** and the
+  latter **pins `branch: _sandbox-dev`** — apparently left behind by a rename. They point at the
+  same host and they are **not what serves it.** They are the single most misleading pair of files
+  in the repo: they look authoritative and they are dead.
+- **Consequence: merging `_underscore` to `_sandbox-dev` does NOT reach that environment.**
+
+### ⚠ Diagnostic: `Call to undefined method _Model_Client_<X>::<method>()` means the CLASS ISN'T DEPLOYED
+
+When a client model override is missing from the deployed `_underscore`, V2 does **not** error at
+resolution time. `class_exists` fails, so V2 quietly **declines the override and falls back to the
+BASE model** (`V2.php:3155-3162`). The base model has no client-specific method, so you get:
+
+```
+Call to undefined method _Model_Client_Subscription::cancelApi()
+```
+
+**Read this error as "the override class is not on the server," not "the code is wrong."** The
+`_Model_Client_*` (base) prefix in the message — where you expected `_Model_<Slug>_*` — is the tell.
+Confirm by file presence on the box, then check which branch that tier actually clones (above).
+
+Related detail: **the slug V2 uses to pick the override class is `Clients.clientIdentifier`**
+(`V2.php:1521`), taken from the JWT. `Core.Clients` has **no `slug` column** — do not go looking for
+one.
+
 ## Gotchas / known issues
 
 - **⚠ Merging to the branch named after the EB environment can be a no-op.** Merge to
@@ -88,6 +122,17 @@ Never infer the environment from:
 
 ## Change history
 
+- 2026-08-06 — TRUE-80282 deploy: independently re-confirmed the mapping from a second tier
+  (`api.beta.togahub.com` = `ENVIRONMENT=beta` → `Config/beta.ini` → branch `_beta`) at a cost of two
+  deploy cycles, and recorded **why** the branch derives: there is deliberately **no
+  `git.beta.json`**, while the leftover `Config/sandbox-dev.ini` + `git.sandbox-dev.json` (which
+  pins `branch: _sandbox-dev`) survive a rename, point at the same host, and are dead. Added the
+  key diagnostic: a missing client override does **not** error at resolution — `class_exists` fails
+  and V2 silently falls back to the BASE model (`V2.php:3155-3162`), surfacing as
+  **`Call to undefined method _Model_Client_<X>::<method>()`**, which means *the class is not on the
+  deployed server*, not that the code is wrong (the `_Model_Client_` prefix is the tell). Also
+  recorded that the override slug is **`Clients.clientIdentifier`** (`V2.php:1521`) and that
+  `Core.Clients` has no `slug` column. (mhammontree)
 - 2026-08-05 — Documented that `ENVIRONMENT` (an EB environment property), **not** the EB
   environment name, drives both the `_underscore` branch cloned by `.ebextensions/git.php`
   (`'_' . strtolower($env)`, unless `git*.json` pins `branch`) and the `Config/<env>.ini` loaded via

package/knowledge/2.0/apps/api2/features/record-scripts.md

@@ -60,13 +60,33 @@ Rules the engine enforces (see `getRecordScriptPhpMethod()` + the dispatch in
 - **Remaining parameters are named** and are filled from the **query string**. Each query-string
   key maps to the same-named PHP parameter; unmatched named args land in a `...$args` variadic
   if the method declares one. (`transactionId` and `api` keys are reserved and never mapped.)
-- **The return value becomes the envelope `data` — but nested under the route segment.** The
-  engine does `$outData[$requestedUuid] = method(...)` then `return (object)$outData`
-  (`V2.php` ~:4121, :6305), so the script's payload lands **under the script's route-segment
-  key**, not flat. `GET /v2/sprints/tile` yields `data: { tile: {…} }`, not `data: {…}`;
-  `campaigns/jobs` yields `data: { jobs: … }`. **A consumer must unwrap `data[<route>]`.** The
-  method itself still returns the raw object/array — do not echo, and never build the
+- **The return value becomes the envelope `data` — nested TWICE.** The engine does
+  `$outData[$requestedUuid] = method(...)` then `return (object)$outData`
+  (`V2.php` ~:4121, :6305), and that sits under the **record route** in the envelope. So the full
+  path a consumer must read is:
+
+  ```
+  data.<recordRoute>.<scriptRoute>
+  ```
+
+  **and the second key is the script's `route`, not its `phpMethod`.** Concretely:
+
+  | Endpoint | route / phpMethod | Read from |
+  |---|---|---|
+  | `POST /v2/subscriptions/cancel` | `cancel` / `cancelApi` | `data.subscriptions.cancel` |
+  | `GET /v2/entitlements/warranty-availability` | `warranty-availability` / `warrantyAvailability` | `data.entitlements["warranty-availability"]` |
+  | `GET /v2/sprints/tile` | `tile` / `tile` | `data.sprints.tile` |
+
+  Working precedent to copy:
+  `toga2-view/src/pages/ZipValidation/api/zipValidation.ts:88` —
+  `response?.data?.entitlements?.["warranty-availability"]`.
+
+  The method itself still returns the raw object/array — do not echo, and never build the
   success/error envelope yourself.
+
+  > **⚠ A local test that calls the model method directly can NEVER catch a wrong unwrap**, because
+  > it never traverses the envelope. This is the one class of defect that requires an over-the-wire
+  > call to detect. Budget for it: see the gotcha below for what it cost.
 - Invocation is effectively `$model::$phpMethod(...$args)`.
 
 ### ⚠ Argument binding is PHP NAMED-ARGUMENT unpacking of the QUERY STRING — with two consequences
@@ -261,12 +281,20 @@ an `AclRecordScripts` grant in each client DB.
   ([cancellation doc](../../../../clients/rate/features/subscription-cancellation.md)).
 - **A scripted POST skips the record-level ACL check** — see the section above. Do not "fix" a
   scripted-POST 403 with an `AclRecordPermissions` CREATE grant.
-- **The response key is the ROUTE VERBATIM, not the `phpMethod`.** A script registered with
-  route `warranty-availability` and `phpMethod` `warrantyAvailability` returns
-  **`data.entitlements["warranty-availability"]`** — *not* `data.entitlements.warrantyAvailability`.
-  The sibling `addresses/validateAddress` reader looks camelCase only because **that script's
-  route is itself `validateAddress`.** Reading the wrong key yields `undefined` (and, in a
-  fail-closed consumer, correctly denies) — this cost a debug cycle in beta.
+- **The response is nested TWICE (`data.<recordRoute>.<scriptRoute>`) and the key is the ROUTE
+  VERBATIM, not the `phpMethod`.** A script registered with route `warranty-availability` and
+  `phpMethod` `warrantyAvailability` returns **`data.entitlements["warranty-availability"]`** —
+  *not* `data.entitlements.warrantyAvailability`. The sibling `addresses/validateAddress` reader
+  looks camelCase only because **that script's route is itself `validateAddress`.**
+- **⚠ Reading the wrong key is the most dangerous shape of bug this contract produces, because it
+  fails AFTER the side effect.** In a fail-closed *read* consumer an `undefined` correctly denies
+  (one debug cycle in beta, 2026-07-31). But on a **write/action** endpoint the backend has already
+  committed. Concrete case 2026-08-06: `POST /v2/subscriptions/cancel` was read as `data.cancel`
+  instead of `data.subscriptions.cancel`, so the result was `undefined`, the frontend threw, and the
+  customer was told **the cancellation FAILED** — while PayPal had already been cancelled and the
+  correct state written. That mismatch (user believes it failed, system knows it succeeded) is the
+  worst possible outcome: it invites a retry against a completed irreversible action. **Verify the
+  unwrap path with a real HTTP call before shipping any action endpoint.**
 - **No bound params in `_Query`.** Sanitize with `\_Database::escape()` (strings) and `(int)`
   casts (numerics) for every value placed into the query text — query-string args are user
   input.
@@ -287,6 +315,15 @@ an `AclRecordScripts` grant in each client DB.
 
 ## Change history
 
+- 2026-08-06 — TRUE-80282 testing: sharpened the envelope contract from ambiguous ("nested under the
+  route segment") to the explicit **two-level `data.<recordRoute>.<scriptRoute>`**, with a
+  route-vs-`phpMethod` table and the working precedent
+  (`toga2-view/.../zipValidation.ts:88`). Recorded that reading the wrong key is **most dangerous on
+  an action endpoint because it fails after the side effect**: reading `data.cancel` instead of
+  `data.subscriptions.cancel` told the customer the cancellation **failed** while PayPal was already
+  cancelled and correct state written — inviting a retry against a completed irreversible action.
+  Also recorded that a **local test calling the model method directly can never catch a wrong
+  unwrap**, so an over-the-wire call is mandatory before shipping an action endpoint. (mhammontree)
 - 2026-08-04 — TRUE-80282: documented that a **scripted POST bypasses the record-level
   `AclRecordPermissions` check entirely** (`V2.php:4472` guards it with
   `if (!$isUsingScriptedCall && empty($routePairs))`), so authorization rests solely on the script

package/knowledge/2.0/apps/toga2-view/INDEX.md

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa View Frontend (toga2-view) Architecture](architecture.md) | `toga2-view` is the **React/TypeScript single-page frontend** for the TOGa 2.0 platform — the customer-facing web app (home warranty / tech-support portals). | toga2-view/tsconfig.json, toga2-view/tsconfig.app.json, toga2-view/src/main.tsx, toga2-view/src/App.tsx, toga2-view/src/routes.tsx, toga2-view/src/api/axiosInstance.ts, toga2-view/src/api/apiFunctions.ts, toga2-view/src/utils/queryHelpers.ts, toga2-view/src/contexts/AuthContext.tsx, toga2-view/src/contexts/useUserStore.ts, toga2-view/src/hooks/useAuthenticationFlow.ts, toga2-view/vite.config.ts, toga2-view/package.json |
-| [Get Support — Subscription Details & Cancel Subscription Gating](features/get-support-cancel-subscription.md) | The Get Support page (`/get-support?itemUuid=…`) shows a **subscription details card** (plan · price · renewal date) for the service the user clicked, and — **o | toga2-view/src/pages/GetSupport/viewModels/getSupportPageViewModel.ts, toga2-view/src/pages/GetSupport/view/GetSupportPage.tsx, toga2-view/src/pages/GetSupport/viewModels/DUMMYFIELDS/SUPPORTDUMMYFIELDS.json, toga2-view/src/constants/featureFlags.ts, toga2-view/src/hooks/useBundleServices.ts |
+| [Get Support — Subscription Details & Cancel Subscription Gating](features/get-support-cancel-subscription.md) | The Get Support page (`/get-support?itemUuid=…`) shows a **subscription details card** (plan · price · renewal date) for the service the user clicked, and — **o | toga2-view/src/pages/GetSupport/viewModels/getSupportPageViewModel.ts, toga2-view/src/pages/GetSupport/api/getSupport.ts, toga2-view/src/pages/GetSupport/view/GetSupportPage.tsx, toga2-view/src/pages/GetSupport/viewModels/DUMMYFIELDS/SUPPORTDUMMYFIELDS.json, toga2-view/src/constants/featureFlags.ts, toga2-view/src/hooks/useBundleServices.ts |
 | [Mobile Nav Header](features/mobile-nav-header.md) | The `MobileNavToggle` component renders the fixed 72 px header (hamburger + Rate logo) and the slide-in drawer nav. | toga2-view/src/components/MobileNav/MobileNav.tsx, toga2-view/public/assets/Rate_Logo.svg |
 | [/v2 Query-String Builder (assembleOptions / where coercion)](features/query-string-builder.md) | `src/utils/queryHelpers.ts` converts a structured JS options object (`fields`, `where`, `join`/`ojoin`, `sort`, …) into the `api2` `/v2` query string. | toga2-view/src/utils/queryHelpers.ts, toga2-view/src/utils/queryHelpers.test.ts |
 | [Service Card Component](features/service-card.md) | The `ServiceCard` component renders a single service subscription (tech support or home warranty) on both the Home and Services pages. | toga2-view/src/components/ServiceCard/ServiceCard.tsx, toga2-view/src/pages/Services/view/ServicesPage.tsx, toga2-view/src/pages/Home/view/HomePage.tsx, toga2-view/src/constants/bundleConstants.ts, toga2-view/src/pages/Services/viewModels/DUMMYFIELDS/SERVICESDUMMYFIELDS.json |

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

@@ -6,10 +6,11 @@ project: TOGa View Frontend
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
+updated: 2026-08-06
 owners: ["tcox", "mhammontree"]
 files:
   - toga2-view/src/pages/GetSupport/viewModels/getSupportPageViewModel.ts
+  - toga2-view/src/pages/GetSupport/api/getSupport.ts
   - toga2-view/src/pages/GetSupport/view/GetSupportPage.tsx
   - toga2-view/src/pages/GetSupport/viewModels/DUMMYFIELDS/SUPPORTDUMMYFIELDS.json
   - toga2-view/src/constants/featureFlags.ts
@@ -140,6 +141,18 @@ not self-service cancellable from the portal; only tech-support subscriptions ar
   details card** — that is the intended kill-switch behavior.
 - **Never close the confirm modal on failure.** Closing it reads to the user as a successful
   cancellation.
+- **⚠ Unwrap the scripted response as `data.subscriptions.cancel` — nested TWICE, keyed by the
+  script's ROUTE (`cancel`), not its phpMethod (`cancelApi`).** Reading `data.cancel` yields
+  `undefined`, the view model throws, and the user is told **the cancellation FAILED — while the
+  backend has already cancelled at PayPal and written correct state.** On an irreversible action
+  that is the worst possible mismatch, because the user's natural response is to retry. This
+  actually shipped to beta. Copy the working precedent:
+  `src/pages/ZipValidation/api/zipValidation.ts:88`
+  (`response?.data?.entitlements?.["warranty-availability"]`). Contract:
+  [record scripts](../../api2/features/record-scripts.md).
+- **A failure message here does NOT mean nothing happened.** Because the PayPal cancel precedes the
+  response, any error surfaced after the request was accepted may sit on top of a **completed**
+  cancellation. Never present a failure as "nothing was changed," and never auto-retry the cancel.
 
 ## Client variations
 
@@ -151,6 +164,14 @@ same user, so the page must distinguish them per service rather than per account
 
 ## Change history
 
+- 2026-08-06 — TRUE-80282 testing: **UI verified on beta** — with a pending cancellation the card
+  renders "Service ends by Aug 27, 2026" and both the Cancel button and the "cancel anytime" note
+  disappear, while the subscription stays active. Fixed a shipped bug: the response was read as
+  `data.cancel` instead of **`data.subscriptions.cancel`** (the scripted envelope nests twice and is
+  keyed by the script **route**, not the phpMethod), so the result was `undefined`, the view model
+  threw, and the customer was told the cancellation **failed** even though PayPal had already been
+  cancelled and correct state written. Recorded the general rule that a failure message on this
+  action never implies nothing happened, and that the cancel must not be auto-retried. (mhammontree)
 - 2026-08-04 — TRUE-80282: **the backend shipped**, so `cancelSubscription()` is no longer a
   rejecting stub — it calls `POST /v2/subscriptions/cancel` with `{ entitlementUuid }` in the body.
   Recorded that the `serviceType === 'tech'` gate is a UX affordance only (the server refuses

package/knowledge/2.0/standards/backend-testing.md

@@ -5,12 +5,14 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-07-08
+updated: 2026-08-06
 owners: [mhammontree]
 files:
   - _underscore/Query.php
   - _underscore/Database.php
   - _underscore/Environment.php
+  - _underscore/Model.php
+  - test/@Mark/Rate/verify_cancel_subscription.php
 related:
   - ../apps/_underscore/architecture.md
   - ../apps/_underscore/features/per-client-database-connections.md
@@ -94,6 +96,69 @@ This is the same lazy-transaction write-drop family noted in the `_underscore` a
 it bites the standalone-script/verification case specifically. Demonstrated working in
 `test/@Mark/Rate/verify_wholehome_per_address_guard.php`.
 
+## Auto-detect the 2.0 Core database — NEVER default to `Core`
+
+**Locally the 2.0 Core schema is `Core_2`; the schema literally named `Core` is the 1.0 database.**
+So a `?: 'Core'` fallback does not fail — it silently registers the **1.0** DB, and every Core
+metadata lookup then quietly returns nothing. Nothing errors; your assertions just see empty
+results and you debug the wrong layer.
+
+Probe for the schema that actually has the 2.0 metadata tables, and **assert the result** rather
+than falling back:
+
+```php
+// Probe candidates for the 2.0 Core metadata tables, then ASSERT — never `?: 'Core'`.
+$coreDb = null;
+foreach (['Core_2', 'Core'] as $candidate) {
+    $row = (new \_Query("
+        SELECT COUNT(*) AS n
+        FROM information_schema.TABLES
+        WHERE
+            TABLE_SCHEMA = '" . \_Database::escape($candidate) . "' AND
+            TABLE_NAME IN ('Records', 'RecordFields')
+    "))->fetchRow();
+    if ((int) $row->n === 2) { $coreDb = $candidate; break; }
+}
+if ($coreDb === null) {
+    throw new \RuntimeException('Could not resolve the 2.0 Core schema (need Records + RecordFields).');
+}
+```
+
+`Records` + `RecordFields` are the right discriminator: the 1.0 `Core` has neither.
+
+> **Known latent bug:** `test/@Mark/Rate/verify_wholehome_per_address_guard.php` still uses the
+> `?: 'Core'` fallback. It is harmless **only** because nothing in it reads Core metadata — fix it
+> before adding any assertion that does.
+
+## A raw SQL `UPDATE` then a model reload returns a STALE row
+
+`_Model::load()` consults **`_Database::$_modelCache`**, which is a **separate cache from the query
+cache** — `useQueryCache(false)` does **not** disable it — and is flushed only by `_Model::save()`.
+So the "mutate via SQL, reload the model, assert" pattern silently asserts against the pre-update
+row, and a test of a *correct* fix fails (or a broken one passes).
+
+**When testing a pure function, mutate the loaded model in memory** and pass it in; do not round-trip
+through the database:
+
+```php
+$subscription->dateEnd = '2026-01-01';           // in-memory, no cache involved
+$result = _Model_Rate_Subscription::effectiveEndDate($subscription);
+```
+
+Reach for SQL only when you are testing persistence itself — and then re-`load()` through a
+**freshly constructed** model, not the cached instance.
+
+## Scripts that touch real data must be self-limiting
+
+A verification script runs against a **real client database**, so build in the guards up front:
+tag every seeded row with a **per-run token**, tear down in a **`finally`** block so a failed
+assertion still cleans up, and **abort at startup if the host looks production-shaped.** Pattern
+reference: `test/@Mark/Rate/verify_cancel_subscription.php` (34 assertions).
+
+Also design around what a direct-call script **cannot** see: calling a model method directly never
+traverses the API response envelope, so it can never catch a wrong `data.<record>.<script>` unwrap.
+Any endpoint with a side effect needs one real over-the-wire call in addition to the script.
+
 ## Rules
 
 - Do not add or assume a PHPUnit suite for 2.0 backend work; write a `test`-repo script instead.
@@ -102,3 +167,17 @@ it bites the standalone-script/verification case specifically. Demonstrated work
 - **Commit seeded rows before you read them back** — the read connection cannot see uncommitted
   writes; commit cleanup too so it persists.
 - Keep scripts in your per-dev `test` folder; never point them at production databases.
+- **Never default the Core schema to `Core`** — probe for `Records` + `RecordFields` and assert.
+  Locally, `Core` is the **1.0** database and every 2.0 Core lookup silently returns nothing.
+- **Do not `UPDATE` via raw SQL and then reload a model to assert** — `_Database::$_modelCache` is
+  separate from the query cache and is flushed only by `save()`, so the reload is stale. Mutate the
+  model in memory when testing a pure function.
+
+## Change history
+
+- 2026-08-06 — TRUE-80282: added Core-DB auto-detection (never `?: 'Core'` — locally `Core` is the
+  1.0 DB, so the fallback silently registers the wrong schema; flagged the latent bug in
+  `verify_wholehome_per_address_guard.php`), the `_Database::$_modelCache` staleness trap (separate
+  from `useQueryCache(false)`, flushed only by `save()`, so raw-UPDATE-then-reload asserts a stale
+  row), and self-limiting-script requirements (per-run token, `finally` teardown, production-host
+  abort). Derived from `verify_cancel_subscription.php`. (mhammontree)

package/knowledge/INDEX.md

@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 46 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 47 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 41 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 22 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)

package/knowledge/clients/rate/INDEX.md

@@ -9,6 +9,6 @@
 | [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 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, api2/.ebextensions/git.php, toga2-view/src/pages/GetSupport/api/getSupport.ts, toga2-view/src/pages/GetSupport/viewModels/getSupportPageViewModel.ts, test/@Mark/Rate/verify_cancel_subscription.php |
 | [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/subscription-cancellation.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: rate
 type: client-feature
 status: active
-updated: 2026-08-04
+updated: 2026-08-06
 owners: [mhammontree, tcox]
 files:
   - _underscore/Model/Rate/Subscription.php
@@ -21,6 +21,10 @@ files:
   - toga2-view/src/hooks/useBundleServices.ts
   - toga2-view/src/api/apiErrors.ts
   - api2/Config/beta.ini
+  - api2/.ebextensions/git.php
+  - toga2-view/src/pages/GetSupport/api/getSupport.ts
+  - toga2-view/src/pages/GetSupport/viewModels/getSupportPageViewModel.ts
+  - test/@Mark/Rate/verify_cancel_subscription.php
 related:
   - clients/rate/profile.md
   - service-card-entitlements.md
@@ -31,6 +35,10 @@ related:
   - ../../../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
+  - ../../../2.0/apps/_underscore/features/model-magic-field-access.md
+  - ../../../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
 ---
 
 ## Summary
@@ -141,6 +149,48 @@ agreement.
 
 **Never place the live pair in a non-prod ini — cancellation is irreversible at PayPal.**
 
+## Verification status (2026-08-06) — what is PROVEN and what is UNPROVABLE off production
+
+**✅ Verified end-to-end on beta (`api.beta.togahub.com`, PayPal SANDBOX).** One real cancellation
+was driven all the way through:
+
+- `POST /v2/subscriptions/cancel` → **200**, `dateCancel: 2026-08-27`.
+- A real PayPal **sandbox** billing agreement was actually cancelled at PayPal.
+- `Client_Rate.Subscriptions` id 84 inspected directly: **`isActive = 1`** (paid coverage
+  preserved — the whole point), **`dateEnd` untouched** at `2026-08-27`,
+  `dateCancelled = 2026-08-27`, `dtRequestToCancel` stamped.
+- UI: the card renders **"Service ends by Aug 27, 2026"**, and the Cancel button plus the
+  "cancel anytime" note both disappear.
+
+**❌ The entire worker2 half is UNVERIFIED and cannot be verified off production.** Non-prod
+**receives no PayPal webhooks** and **has no cron scheduler**, so these remain production-only
+checks, tracked under **TRUE-80575**:
+
+- `handleSubscriptionDeactivation` (the `BILLING.SUBSCRIPTION.CANCELLED` wind-down branch)
+- the webhook-side reconciliation `dateCancelled` stamp
+- the `Rate/ExpireCancelledSubscriptions` cron
+
+Do not read "verified on beta" as "verified." The half that protects the customer's paid coverage
+*after* the cancel — and the half that eventually revokes it — has never run. Combined with the
+known production webhook outage (see the last gotcha), treat the wind-down path as unexercised code.
+
+## Regression / verification script
+
+`test/@Mark/Rate/verify_cancel_subscription.php` — **34 assertions, all passing.** Covers the
+effective-date logic (including past and missing `dateEnd`), warranty-vs-tech discrimination, the
+borrower → item → subscription resolution join, **every `cancelApi` pre-PayPal rejection with an
+assertion that nothing was written**, the idempotent double-click return, and a NULL-rollback
+regression pinning the `save()` field-diff trap.
+
+**It never calls PayPal** — every covered path provably returns or throws before the PayPal call. It
+seeds a scratch graph tagged with a per-run token, tears down in `finally`, and aborts if the host
+looks production-shaped. Two reusable techniques it introduced (Core-DB autodetection and the
+`_Database::$_modelCache` staleness trap) are proposed for the
+[2.0 backend testing standard](../../../2.0/standards/backend-testing.md).
+
+Note the structural limit: because it calls the model method **directly**, it cannot catch a
+response-envelope unwrap error — which is exactly the bug that reached beta (see gotchas).
+
 ## Migration ordering is a dependency contract
 
 `dbchanges2` runs files **alphabetically within a folder**, so the same-day letter suffix is the
@@ -149,6 +199,57 @@ record-script registration (`2026-08-04b`)**. Reversed, the endpoint goes live w
 still cannot see the columns it needs — which is precisely the window in which a cancel truncates a
 customer's paid coverage.
 
+**Second ordering rule, learned the hard way: the CODE must be deployed BEFORE the registration
+migration runs.** If `2026-08-04b` registers the route while the deployed `_underscore` lacks
+`cancelApi`, the route resolves to a phpMethod that does not exist and you get a **confusing 500**
+instead of a clean "route not registered." Full order: **code → field grants (`a`) → registration
+(`b`)**.
+
+### Grant verification (2026-08-06) — the `a` migration is a NO-OP where the grants already exist
+
+Confirmed in **both sandbox-dev and production**: `Subscriptions.dtRequestToCancel` (RecordFields
+id **1698**), `dateCancelled` (**1697**) and `dateEnd` (**1696**) are all already granted to role
+`Base` with `isWritable = 1`, on `recordId 253` (route `subscriptions`). So
+`dbchanges2/Client_Rate/2026-08-04a` inserts nothing in those environments — **harmless,
+re-runnable, and still required** to protect a freshly-created blank client DB. The hardcoded Core
+RecordFields id literals were verified correct per environment.
+
+**The decisive link for worker2:** `Client_Rate.Apis` uuid
+`fe4df2e2-f685-4c03-a2d7-2015502dadc9` — which is exactly `_Worker_Rate::API_UUID_RATE` — carries
+**both the `Base` and `API` roles**. Roles union, so the worker inherits `Base`'s grants and **can
+read the cancellation columns.** This is why mirroring `dateEnd`'s grants was the right call rather
+than inventing a worker-specific role.
+
+## ⚠ 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.**
+
+In `Client_Rate`, role **`Base`** — which **every** portal customer carries, and which the Rate API
+user also carries — has an `AclRecordPermissions` row on the `subscriptions` record (**recordId
+253**) with `allowCreate` / `allowRead` / `allowUpdate` / `allowDelete` **all = 1** and **`appId`
+and `indirectRecordId` both NULL — i.e. no scoping whatsoever.** Combined with
+`AclFieldPermissions.isWritable = 1` on `isActive`, `dateEnd`, `dateCancelled`, `dtRequestToCancel`
+and `token`. **Identical in sandbox-dev AND production.**
+
+Per the ACL data, this permits a logged-in customer to `PUT /v2/subscriptions/{uuid}` and:
+
+- extend their own **`dateEnd`** indefinitely → **free coverage**;
+- clear **`dateCancelled`** → un-cancel;
+- overwrite the PayPal agreement **`token`**;
+- **DELETE** a subscription row;
+- and with **no row scoping**, potentially operate on **another customer's** subscription.
+
+**This directly undermines TRUE-80282's guarantee.** `cancelApi` computes the effective end date
+**server-side precisely so a customer cannot extend their own coverage** — but ordinary CRUD can
+write the same column, bypassing the script entirely. A scripted endpoint's server-side computation
+is only as strong as the CRUD permissions on the columns it writes.
+
+It is also **why `cancelApi`'s explicit borrower-ownership check is essential rather than
+defensive** — do not remove it as redundant.
+
+See [ACL permission chain — unscoped grants](../../../2.0/apps/_underscore/features/acl-permission-chain.md)
+for the general audit recipe.
+
 ## Frontend
 
 `GetSupport` now calls the real endpoint instead of the rejecting stub. `ServiceCard` /
@@ -169,6 +270,38 @@ feature rather than failing the page.
   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).
+- **⚠ Never test a cancellation column with `empty()` / `isset()`.** `_Model` has no `__isset`, so
+  `empty($s->dtRequestToCancel)` returns **TRUE while the column holds a date**. This broke the
+  **idempotency guard** here: `$isRequested` was permanently false, so an already-cancelled
+  subscription never short-circuited, **every click re-called PayPal**, and the crash-recovery branch
+  meant to preserve an earlier attempt's intent **wiped it instead**. Use
+  `trim((string) $field) !== ''`. See
+  [_Model magic-field access](../../../2.0/apps/_underscore/features/model-magic-field-access.md).
+- **⚠ Guard the PayPal config with `_Config::isGroupSet('paypal')` — the `false` "optional" flag
+  does NOT rescue a missing group.** `_Config::paypal('client_id', false)` still **throws** if
+  `[paypal]` is absent from the active ini. Before this was fixed, a cancel in any environment
+  without a `[paypal]` section returned **`EO-1` with a stack trace to a logged-in retail
+  customer**. See
+  [_Config group access](../../../2.0/apps/_underscore/features/config-group-access.md).
+- **⚠ The frontend must read `data.subscriptions.cancel` — nested TWICE, and keyed by the ROUTE
+  (`cancel`), not the phpMethod (`cancelApi`).** Reading `data.cancel` made the result `undefined`,
+  the frontend threw, and **the customer was told the cancellation FAILED while PayPal had already
+  been cancelled and correct state written** — the worst possible mismatch, because it invites a
+  retry against a completed irreversible action. Precedent that had it right:
+  `toga2-view/src/pages/ZipValidation/api/zipValidation.ts:88`. **A local test calling the model
+  method directly can never catch this** — it never traverses the envelope. See
+  [record scripts](../../../2.0/apps/api2/features/record-scripts.md).
+- **⚠ `Call to undefined method _Model_Client_Subscription::cancelApi()` means the class is not
+  deployed, not that the code is broken.** `api.beta.togahub.com` runs `ENVIRONMENT=beta` and clones
+  `_underscore` branch **`_beta`** — merging to `_sandbox-dev` never reaches it (the
+  `sandbox-dev.ini` / `git.sandbox-dev.json` files there are dead leftovers). `class_exists` fails,
+  V2 silently declines the client override and falls back to the base model. Cost two deploy cycles.
+  See [ENVIRONMENT drives the _underscore branch](../../../2.0/apps/api2/features/environment-variable-drives-underscore-branch.md).
+- **⚠ Errors are currently NOT captured on sandbox-dev/beta** — `Logs.Issue` is missing
+  `clickupPriority`, so the capture INSERT dies on MySQL 1054 and nothing is persisted; the only
+  trace is `identifiers.captureFailure` in the API response body. Debugging this feature on beta
+  means reading response bodies, not the Issues table. See
+  [error reporting](../../../2.0/apps/_underscore/features/error-reporting-issue-event.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
@@ -180,8 +313,10 @@ feature rather than failing the page.
 - **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.
+- **`api2/Config/production.ini` carries a plaintext live PayPal secret in the repo.** **Rotation
+  is outstanding as of 2026-08-06** — the credential was exposed again during this session's
+  testing. Treat it as compromised until rotated. Do not propagate the pattern, and never copy the
+  value into a doc, ticket, or scratch file (locations only).
 - **⚠ 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),
@@ -192,6 +327,30 @@ feature rather than failing the page.
 
 ## Change history
 
+- 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,
+  `dateCancelled` + `dtRequestToCancel` stamped, with the UI showing "Service ends by Aug 27, 2026"
+  and the Cancel affordance hidden. Recorded that the **entire worker2 half remains unverifiable off
+  production** (no webhooks, no cron scheduler) — gated on **TRUE-80575**. Fixed three bugs found in
+  testing: (1) the idempotency guard used `empty()` on a magic field, which is permanently true, so
+  every click re-called PayPal and the crash-recovery branch wiped the earlier attempt's intent;
+  (2) `_Config::paypal('client_id', false)` **still throws** when `[paypal]` is missing, so a cancel
+  in an unconfigured environment showed a logged-in customer an `EO-1` stack trace — `isGroupSet()`
+  is the only guard; (3) the frontend read `data.cancel` instead of `data.subscriptions.cancel`
+  (nested twice, keyed by **route** not phpMethod), telling the customer the cancellation **failed**
+  after PayPal had already been cancelled. Verified the `2026-08-04a` grants are already present in
+  sandbox-dev **and** prod (RecordFields 1696/1697/1698 on recordId 253) making the file a harmless
+  re-runnable no-op, and that `Client_Rate.Apis` uuid `fe4df2e2…` (`_Worker_Rate::API_UUID_RATE`)
+  carries **both `Base` and `API`**, so the worker inherits the grants. Added the second deploy-order
+  rule (**code before the registration migration**, else a confusing 500) and the beta branch trap
+  (`ENVIRONMENT=beta` → `_beta`; a missing override surfaces as
+  `_Model_Client_Subscription::cancelApi()` undefined — two deploy cycles lost). Logged a **⚠
+  pre-existing security finding**: role `Base` holds a fully unscoped CRUD grant on recordId 253 with
+  `isActive`/`dateEnd`/`dateCancelled`/`dtRequestToCancel`/`token` all writable in prod, letting a
+  customer extend their own coverage via plain CRUD and bypassing this feature's server-side date
+  computation — needs its own ticket. Added
+  `test/@Mark/Rate/verify_cancel_subscription.php` (34 assertions, never calls PayPal). (mhammontree)
 - 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

package/knowledge/sessions/2026-08-06-TRUE-80282-cancel-subscription-mhammontree.md

@@ -0,0 +1,91 @@
+---
+type: session
+slug: TRUE-80282-cancel-subscription
+title: Verify Rate self-service subscription cancellation end-to-end on beta
+author: mhammontree
+repos: [_underscore, api2, toga2-view, worker2, dbchanges2, test]
+framework: "2.0"
+client: rate
+status: active
+created: 2026-08-06
+updated: 2026-08-06
+---
+
+# Session: TRUE-80282-cancel-subscription
+**Date:** 2026-08-06
+**Project/Repo:** _underscore · api2 · toga2-view · worker2 · dbchanges2 · test (2.0)
+**Task:** Finish TRUE-80282 — prove the Rate portal's self-service tech-support cancellation works end-to-end (api2 → PayPal → DB → UI), fix whatever that surfaced, and commit. Continues the 2026-08-04 session of the same slug.
+
+---
+
+## What WORKED
+
+- **End-to-end cancellation verified on beta (api.beta.togahub.com), 2026-08-06.** `POST /v2/subscriptions/cancel` with `{"entitlementUuid":"9c827c5c-7779-b260-b0cb-1d047a937a03"}` returned **200**, `data.subscriptions.cancel = {isCancelled: true, dateCancel: "2026-08-27", message: "Your subscription will be canceled on August 27, 2026. You'll have access until then."}`. A real PayPal **sandbox** agreement was cancelled.
+- **Database state verified directly** (`Client_Rate.Subscriptions` id 84, sandbox-dev): `isActive = 1`, `dateEnd = 2026-08-27` (untouched), `dateCancelled = 2026-08-27`, `dtRequestToCancel = 2026-08-06 12:02:40`. That is the whole business rule proven — the customer keeps the coverage already paid for.
+- **UI verified after refresh**: card renders "Monthly · $9.97/mo · **Service ends by Aug 27, 2026**", the Cancel button is gone, and the "you can cancel anytime" note is gone with it.
+- **Verification script passes 34/34** — `test/@Mark/Rate/verify_cancel_subscription.php`. Covers the effective-date logic (incl. past/missing `dateEnd`), warranty-vs-tech discrimination, the borrower/item/subscription join, all six `cancelApi` pre-PayPal rejections (each asserting nothing was written), the idempotent double-click return, and the NULL-rollback regression. Never calls PayPal. Scratch rows self-clean (`leftover rows: 0` every run).
+- **Field grants confirmed present, so worker2's wind-down guard will work.** `Subscriptions.dateEnd` (1696), `dateCancelled` (1697), `dtRequestToCancel` (1698) are all granted to role `Base` in **both** sandbox-dev and production. Decisive link: `Client_Rate.Apis` uuid `fe4df2e2-f685-4c03-a2d7-2015502dadc9` — exactly `_Worker_Rate::API_UUID_RATE` — carries **both** `Base` and `API`, so the worker inherits Base's grants.
+- **Hardcoded Core.RecordFields id literals verified** — 1696/1697/1698 on `recordId 253` (route `subscriptions`) are correct per environment, so the migration's use of literals is sound.
+- **All three migrations landed on beta**: CustomRecordScripts id 2 (`POST` / route `cancel` / `cancelApi`, granted to `Base`), and `Core.CronJobs` id 27 (`Rate/ExpireCancelledSubscriptions`, `0 3 * * *`, active). `2026-08-04a` was a confirmed no-op (grants already existed).
+- **Commits** (all pushed except the last): `_underscore` `4636a8e` + `2fc8e450`, `worker2` `6de7fa7`, `dbchanges2` `df48181`, `api2` `47a4060`, `toga2-view` `6db0aec` + **`76d7d49` (not yet pushed)**.
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **`empty()` / `isset()` on a `_Model` field.** `_Model` defines `__get`/`__set` but **no `__isset`** (Model.php:464,481). Proven empirically: `$s->dateCancelled` returns `'2026-08-26'` while `empty($s->dateCancelled)` returns **true** and `isset()` returns **false**. This silently broke the cancel idempotency guard — `$isRequested` was permanently false, so an already-cancelled subscription never short-circuited, every click re-called PayPal, and the crash-recovery branch wiped the earlier attempt's intent instead of preserving it. **Use `trim((string) $field) !== ''`.** ⚠ This was **already documented** in `2.0/apps/_underscore/features/model-magic-field-access.md` — reading that doc first would have prevented the bug.
+- **`_Config::<group>('key', false)` to survive a missing group.** It still throws. In `_Config::__callStatic` the missing-**group** branch tests `$properties[0]` *before* `array_shift()` has run, so it sees the property NAME (truthy) not the `false` flag, and falls through to the throw at Config.php:85. The optional-property form only rescues a missing key inside a group that **exists**. **Guard with `_Config::isGroupSet('<group>')` first.** Symptom before the fix: EO-1 with a stack trace to a logged-in customer.
+- **Reading a scripted endpoint's response as `data.<script>`.** The real shape is **`data.<recordRoute>.<scriptRoute>`** — ours is `data.subscriptions.cancel` — and the key is the script's **route** (`cancel`), not its phpMethod (`cancelApi`). Reading `data.cancel` made the result `undefined`, so the frontend threw and told the customer the cancellation had **failed** while the backend had already cancelled at PayPal and written correct state. Precedent that had it right all along: `toga2-view/src/pages/ZipValidation/api/zipValidation.ts:88` → `response?.data?.entitlements?.["warranty-availability"]`.
+- **Merging `_underscore` to `_sandbox-dev` and expecting api.beta.togahub.com to have it.** That environment runs **`ENVIRONMENT=beta`**, so `.ebextensions/git.php` clones `_underscore` branch **`_beta`** (`'_' . strtolower($env)`), because there is **no `.ebextensions/git.beta.json`** to override it. A `Config/sandbox-dev.ini` and a `git.sandbox-dev.json` (which pins `branch: _sandbox-dev`) both exist and point at the same host, apparently from a rename — they are **not** what that environment reads. **This cost two deploy cycles.** Diagnostic rule: `Call to undefined method _Model_Client_Subscription::cancelApi()` means the **client override class is not on the deployed server** — `class_exists` fails so V2 declines the override at V2.php:3155-3162 and falls back to the base model. It is not a code bug. ⚠ Also **already documented**, in `2.0/apps/api2/features/environment-variable-drives-underscore-branch.md`.
+- **Raw SQL `UPDATE` then reload a model to assert** (in the test script). Returned the **stale pre-update row**: `_Model::load()` consults `_Database::$_modelCache`, which is a **separate cache from `useQueryCache(false)`** and is flushed **only** by `_Model::save()`. Two assertions failed against correct code. Fix: mutate the loaded model **in memory** when testing a pure function.
+- **Defaulting the test script's Core schema to `'Core'`.** Locally `Core` is the **1.0** database and `Core_2` is the 2.0 one — verified: `Core` has 0/2 of `Records`+`RecordFields`, `Core_2` has 2/2. The fallback does not error, it silently registers the wrong schema and every Core lookup returns nothing. Fix: probe for the metadata tables and **assert** the result.
+- **Cross-schema JOIN from `Client_Rate` to `Core` on the prod cluster.** Refused outright: `Unknown database 'Core'`. Live confirmation of why `Client_*` migrations cannot subselect `Core`.
+- **Redacting a JSON *array of objects* by filtering top-level keys.** My filter keyed on `password`/`username` but the top level was numeric indices, so nothing matched and **a GitHub PAT was printed into the session transcript**. Extract the specific keys you want instead of filtering a shape you have not inspected. The PAT is in `api2/.ebextensions/git.json` (committed) — **treat as compromised and rotate**.
+
+## Not tried yet (candidates for next session)
+
+- **The entire worker2 half — production-only.** `handleSubscriptionDeactivation`'s wind-down guard, the webhook `dateCancelled` reconciliation stamp, and `Rate/ExpireCancelledSubscriptions`. Non-prod receives **no** PayPal webhooks (no SQS on non-prod worker2; PayPal delivers to one configured URL) and has **no cron scheduler**, so none of it is reachable on beta. Consequence on beta: subscription 84 will sit at `isActive = 1` past 2026-08-27 — expected, not a bug. Gated on **TRUE-80575**.
+- The idempotency guard against the real stack. Now unreachable through the UI (hiding the Cancel button is what prevents the second click) — would need a direct API call. Already covered by section 6 of the local script.
+- The `Logs.Issue.clickupPriority` migration (offered, not written).
+- Committing `verify_cancel_subscription.php` to the `test` repo.
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `_underscore/Component/Api/Paypal/Paypal.php` | committed `2fc8e450`, pushed | `isGroupSet` guard; 422 narrowed to `SUBSCRIPTION_STATUS_INVALID` |
+| `_underscore/Model/Rate/Subscription.php` | committed `2fc8e450`, pushed | two-phase write; `empty()` replaced with cast-string compare |
+| `worker2/Worker/Rate.php` | committed `6de7fa7`, pushed | wind-down guard, webhook confirmation, extension guard, expiry cron, unconfirmed reporting |
+| `dbchanges2` × 3 | committed `df48181`, pushed | field grants (no-op where present), record script, cron |
+| `api2/Config/beta.ini` | committed `47a4060`, pushed | `[paypal]` sandbox section — correct file, since the env reads `beta.ini` |
+| `toga2-view` × 11 | committed `6db0aec`, pushed | button wiring, "Service ends by", error surfacing |
+| `toga2-view` GetSupport api + viewModel | committed **`76d7d49`, NOT pushed** | envelope path fix (`data.subscriptions.cancel`) |
+| `test/@Mark/Rate/verify_cancel_subscription.php` | **untracked** | 34/34 passing; not committed anywhere |
+| `_underscore` 3 vendored CSS files | modified, deliberately uncommitted | someone else's `-webkit-` prefix cleanup — not this ticket |
+| `worker2/Config/dev-markhammontree-laptop.ini` | modified, deliberately uncommitted | personal local config |
+| `toga2-view/src/styles/index.css` | modified, deliberately uncommitted | line-endings only |
+| `C:\WWW\TRUE-80282-Cancel-Plan.md` | rev 2 | team review doc |
+
+## Decisions made
+
+- **Kept the `?: 'Core'`-style detection as probe-and-assert rather than hardcoding either name.** In production the 2.0 Core genuinely *is* `Core`, so neither name can be baked in; detection works in both without a flag. Rejected: a `CORE_DATABASE` env var as the primary mechanism (still supported as an override).
+- **Unwrap the response envelope in the api layer, not the viewModel.** Keeps envelope knowledge in one place and gives the caller a single result to check — matching `zipValidation.ts`. Rejected: checking `response.data.subscriptions.cancel.isCancelled` in the viewModel.
+- **Did not promote the `_Model` `__isset` trap to a standard.** `model-magic-field-access.md` already owns the subject; a second home would fragment the rule. It is cross-linked to the `save()` field-diff trap as a sibling.
+- **Kept `dbchanges2/Client_Rate/2026-08-04a` even though it is a no-op** where the grants exist. It is harmless, re-runnable, documents the dependency, and still protects a fresh client blank.
+- **Reported rather than acted on the ACL exposure.** It is pre-existing, and fixing permissions platform-wide is out of this ticket's scope.
+
+## Blockers
+
+1. **TRUE-80575 is the gate on the remaining verification** (the developer is picking it up next). Until `Rate/Webhook` jobs stop dying on the watchdog, `BILLING.SUBSCRIPTION.CANCELLED` is not processed in production, so the reconciliation channel — the safety net for a crash between the PayPal call and the `dateCancelled` write — is dead there.
+2. **⚠ Security, needs its own ticket.** In `Client_Rate` (sandbox-dev **and** production) role `Base` has `AclRecordPermissions` on recordId 253 with allowCreate/Read/Update/Delete all = 1 and **`appId`/`indirectRecordId` both NULL — no scoping** — plus `isWritable = 1` on `isActive`, `dateEnd`, `dateCancelled`, `dtRequestToCancel`, `token`. Every portal customer carries `Base`. Per the ACL data that permits extending one's own `dateEnd` (free coverage), un-cancelling, overwriting the PayPal `token`, deleting rows, and possibly acting on another customer's subscription. **Not exploited — permission tables were read only.** It directly undermines this feature's server-side date computation.
+3. **Error capture is broken on sandbox-dev.** `Logs.Issue` lacks `clickupPriority`, so the capture INSERT fails (MySQL 1054) and **no error is persisted on that environment** — it only appears inline as `identifiers.captureFailure`. From `_underscore` `4ebe12fe` shipping without its migration. Anyone debugging on beta is flying blind.
+4. **Two credentials need rotating**: the live PayPal `client_secret` (committed in `api2/Config/production.ini` and `worker2/Config/production.ini`) and the GitHub PAT in `api2/.ebextensions/git.json`.
+
+## Exact next step
+
+> The developer is moving to **TRUE-80575** next. To close out TRUE-80282:
+> 1. `cd /c/WWW/toga2-view && git push` — `76d7d49` (the envelope fix) is committed but unpushed.
+> 2. Open the PRs **against the branch each environment actually reads** — this session proved `api.beta.togahub.com` runs `ENVIRONMENT=beta` and therefore `_beta`, **not** `_sandbox-dev`. Settle that mapping with Rohan before merging, since his instruction said `_sandbox-dev`. `dbchanges2` → `_main`.
+> 3. Decide whether `test/@Mark/Rate/verify_cancel_subscription.php` is committed to the `test` repo (it is the regression test for both bugs fixed in `2fc8e450`, which the testing standard requires).
+> 4. File the three follow-ups in blockers 2–4.
+
+---
+_Saved by /session-save on 2026-08-06_

package/package.json

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