toga-ai 1.0.520 → 1.0.522

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

@@ -13,7 +13,7 @@
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [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 |
+| [_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 |
 | [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, 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 |
@@ -24,7 +24,7 @@
 | [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::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 |
+| [_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 |
 | [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona **names** in multiple languages by adding a per-language **sidecar** table `PersonaTranslations`, reusing the platform's existing metadata-driven | _underscore/Model/Client/PersonaTranslation.php, dbchanges2/Client/2026-07-22b - PersonaTranslations.sql, dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql, dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql, dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql, toga2-commerce/src/pages/Account/view/MySettingsView.tsx |

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-03
+updated: 2026-08-04
 owners: ["jcardinal", "mhammontree", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -75,6 +75,47 @@ writable). Without it the field is rejected on write **and** is unreadable:
   role 1 actually reads the field). Grant `isWritable = 0` for a server-written field; resolve the role
   by name/subselect (ids differ per client DB). Beta-proven on Rate `Client_Rate` 2026-07-23.
 
+### ⚠ An ungranted field is ABSENT, not null — and an ungranted JOINED field fails the WHOLE request
+
+Two distinct failure shapes, and the second is a page-killer:
+
+- **A directly-requested field with no grant is simply missing from the response object** — it is
+  not `null`, so `'field' in obj` is false and any consumer that spreads or destructures gets
+  `undefined`. Code that checks `=== null` will not detect it.
+- **A requested JOINED field with no grant fails the ENTIRE request with `EZ-2`.** One missing grant
+  on one joined column therefore blanks every record the page asked for — not just that column.
+
+**Two practices follow directly:**
+
+1. **Mirror grants from a sibling field that is PROVABLY READ by every consumer you need — never
+   hardcode a role name.** A wrong role name **inserts cleanly and fails silently** (no FK error, no
+   rows matched, no signal). For Rate's cancellation columns the mirror was `Subscriptions.dateEnd`,
+   chosen because it is demonstrably read by **both** worker2 and the portal — so any role that can
+   see a subscription's end date can see its cancellation state.
+2. **Request non-essential fields as OPTIONAL and drop only the rejected field on `EZ-2`/`EV-8`.**
+   Then a missing grant degrades one feature instead of failing the page. `toga2-view`'s
+   `src/api/apiErrors.ts` is the precedent (see
+   [service card entitlements](../../../../clients/rate/features/service-card-entitlements.md)).
+   This is also why an API is sometimes designed to take a *different* identifier: Rate's cancel
+   endpoint takes the **entitlement** uuid precisely to avoid requesting the joined
+   `subscription.uuid` and betting the whole entitlements page on one more grant.
+
+### ⚠ Resolve `Core.RecordFields` ids by HARDCODED LITERAL in a `Client_*` migration — the subselect cannot run
+
+This **overrides** the general "resolve by subselect, never hardcode" rule *for Core lookups from a
+client-database file*. `Core` and `Client_*` are on **physically separate clusters**, so a
+`SELECT … FROM Core.RecordFields` subselect inside a `Client_*` migration cannot resolve in
+production — and locally the schema literally named `Core` is the **1.0** database, so it resolves
+to the wrong schema there too. Either way the guarded `INSERT` matches nothing and **succeeds having
+inserted zero rows**.
+
+Use **hardcoded `Core.RecordFields` id literals** instead: those ids are explicitly seeded and
+identical in every environment (the platform's only sanctioned hardcoded ids — see
+`2.0/apps/dbchanges2/architecture.md`).
+
+**Known-broken existing files (same root cause):** `Client_Rate/2026-07-23a` and
+`Client/2026-07-16c`. A clean local run is never proof either worked.
+
 ### Standard field vs. custom (`c_`) field — TWO different permission tables
 
 The permission table depends on whether the field is a platform **standard** field or a client
@@ -244,6 +285,18 @@ assumed from one.
 
 ## Change history
 
+- **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
+  the two practices that follow: **mirror a sibling field provably read by every consumer you need**
+  (Rate's cancellation columns mirrored `Subscriptions.dateEnd`, read by both worker2 and the
+  portal) rather than hardcoding a role name — a wrong role name inserts cleanly and fails silently;
+  and **request non-essential fields as optional**, dropping only the rejected field on
+  `EZ-2`/`EV-8`. Also recorded the **exception to "resolve by subselect"**: a `Core.RecordFields`
+  subselect from inside a `Client_*` migration **cannot resolve** (separate clusters in prod; `Core`
+  is the 1.0 DB locally) and inserts zero rows without erroring — use hardcoded Core RecordFields id
+  literals. Flagged `Client_Rate/2026-07-23a` (and the previously known `Client/2026-07-16c`) as
+  broken by this pattern. (mhammontree)
 - **2026-08-03** — TRUE-80494: reconfirmed the **silent-omission** read rule in a second environment
   (`measures.measureType` ungranted in dev-sandbox `Client_Growrk` → absent from `GET /v2/measures` →
   empty unit dropdowns, no error) and added the **verify-the-mirror-sibling** rule: a clone migration

package/knowledge/2.0/apps/_underscore/features/component-model-namespace-registration.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-08
-owners: [dfranks]
+updated: 2026-08-04
+owners: [dfranks, mhammontree]
 files:
   - _underscore/Loader.php
   - worker2/_.php
@@ -15,6 +15,7 @@ files:
   - worker2/Component/Forecast/Db/Db.php
   - worker2/Component/Forecast/SaleImport/SaleImport.php
   - api2/Component/Api/Netsuite/Netsuite.php
+  - _underscore/Component/Api/Paypal/Paypal.php
 related:
   - ../architecture.md
   - ./forecast-sale-import.md
@@ -40,6 +41,25 @@ is no config toggle. If the class is declared in the **global** namespace instea
 **This is NOT caught by `php -l`** (parse-only) — it only surfaces at autoload/runtime, so
 lint-clean code can still fatally throw on the first request that touches the class.
 
+## ⚠ FILE LAYOUT — a `_Component_*` is a DIRECTORY, never a flat file
+
+Before the namespace rule even applies, the autoloader has to *find* the file.
+`_Loader::autoloader()` (`Loader.php:60-67`) **pops the last `_`-segment of the class name and
+appends it as BOTH an extra directory AND the filename**:
+
+```
+_Component_Api_Paypal  →  Component/Api/Paypal/Paypal.php     ✅
+                       →  Component/Api/Paypal.php            ❌ fatal
+```
+
+A flat `Component/Api/Paypal.php` fatals with **"Could not find required file"** on first use — a
+runtime-only failure, invisible to `php -l`, exactly like the namespace error below.
+
+**Every existing `_Component_Api_*` is a directory** — `Toga`, `Clickup`, `Elite`, `Hubspot`,
+`Netsuite`, `Startech`, `Wje`. Match that shape when adding a new one (first re-confirmed
+2026-08-04 adding `_Component_Api_Paypal` for
+[Rate subscription cancellation](../../../../clients/rate/features/subscription-cancellation.md)).
+
 ## How it works — `_underscore/Loader.php` (lines ~71-83)
 For a project-local `_Component_*` / `_Model_*` class the autoloader:
 1. `require`s the local file.
@@ -85,6 +105,9 @@ transactions, the symptom **presented as ~7 months of historical drift** rather
 project-local `_Component_*`/`_Model_*` must still declare the project namespace.)
 
 ## Gotchas / known issues
+- **A `_Component_*` placed as a flat file instead of `<Name>/<Name>.php` fatals with "Could not
+  find required file"** — the autoloader appends the trailing segment as both directory and
+  filename. Also runtime-only. Check the file *path* before debugging the namespace.
 - `php -l` will **not** catch a missing/global namespace or an unqualified `catch`/`throw`/
   `extends` — boot the class (autoload it) to verify. A wrong autoload path is likewise a
   runtime-only failure.
@@ -92,6 +115,13 @@ project-local `_Component_*`/`_Model_*` must still declare the project namespace
   unqualified `catch (Exception $e)` fails **silently** — the more insidious of the two.
 
 ## Change history
+- 2026-08-04 — TRUE-80282: documented the **file-layout** half of `_Component_*` loading, which
+  precedes the namespace rule — `_Loader::autoloader()` (`Loader.php:60-67`) pops the trailing
+  `_`-segment and appends it as **both a directory and the filename**, so
+  `_Component_Api_Paypal` must live at `Component/Api/Paypal/Paypal.php`; a flat
+  `Component/Api/Paypal.php` fatals with "Could not find required file" on first use (runtime-only,
+  invisible to `php -l`). Confirmed every existing `_Component_Api_*` (Toga, Clickup, Elite, Hubspot,
+  Netsuite, Startech, Wje) is a directory. (mhammontree)
 - 2026-07-08 — **Production recurrence** of this exact fatal (concrete fingerprint, no doc change
   to the mechanism): a worker2 deploy declared `_Component_Forecast_SaleImport`
   (`Worker/Netsuite/Invoice.php` autoload) and its sibling `_Component_Forecast_Db`

package/knowledge/2.0/apps/_underscore/features/model-save-vs-query-atomic-update.md

@@ -6,14 +6,16 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-17
-owners: ["dfranks"]
+updated: 2026-08-04
+owners: ["dfranks", "mhammontree"]
 files:
   - _underscore/Model.php
   - _underscore/Query.php
+  - _underscore/Model/Rate/Subscription.php
 related:
   - ./model-magic-field-access.md
   - ../../worker2/features/netsuite-opportunity-sync.md
+  - ../../../../clients/rate/features/subscription-cancellation.md
 ---
 
 ## Summary
@@ -57,8 +59,50 @@ write-drop). All **non-claim** writes stay on the ORM — `save()` is fine for p
 load → set → save → `transactionCommit` by primary key (the idiom
 `_Worker_Netsuite_Opportunity::delete()` already uses).
 
+## ⚠ `initial` is never resynced after a save — so a SECOND `save()` on the same instance silently drops the column
+
+`save()` only emits columns where **`initial !== value`** (`Model.php:244`), and `initial` is
+populated **only at load/initialize** (`Model.php:702`) — it is **never refreshed after a save**.
+Consequences on a **reused instance**:
+
+```php
+$m->f = $v;   $m->save();   // UPDATE … SET f = $v      (initial['f'] is still the ORIGINAL)
+$m->f = null; $m->save();   // f is OMITTED entirely — the rollback does NOTHING
+```
+
+The second write compares `null` against the *pre-first-save* `initial`, which was already `null`,
+sees "no change", and emits no column. **Any "set it back and save" rollback / compensating write on
+a reused `_Model` instance is a silent no-op.** This is broader than the no-diff rule below: the
+diff is computed against stale state, not against what is actually in the database.
+
+**It fails in the most dangerous possible way** — the code lints, reads correctly, and returns
+success. Concrete cost: a PayPal-failure rollback in
+[Rate subscription cancellation](../../../../clients/rate/features/subscription-cancellation.md)
+would have left customers **marked cancelled while PayPal kept billing them**, with no error
+anywhere.
+
+**Fix — load a FRESH instance per write:**
+
+```php
+// Do NOT reuse the instance across writes. Reload, and defeat both caches so the
+// reload cannot hand back the pre-write row from earlier in this same request.
+\_Database::useQueryCache(false);
+$model->setIsReadHostEnabled(false);   // don't read the replica
+// … load fresh, set the field, save.
+```
+
+Both flags matter: the query cache can return the pre-write row within the same request, and the
+read host is a replica that may not have the write yet. (`useQueryCache` is a **global** toggle —
+capture and restore the prior value.)
+
+Applies to **any** multi-write sequence on one instance, not just rollbacks: two-phase writes,
+retry loops, and compensating transactions all need the reload.
+
 ## Gotchas / known issues
 
+- **Never reuse a `_Model` instance for a second write** (see above) — `initial` is not resynced, so
+  the second `save()` drops the column and the write silently vanishes. Reload a fresh instance with
+  `useQueryCache(false)` + `setIsReadHostEnabled(false)`.
 - Do **not** reach for `save()` to implement a row-claim / optimistic-concurrency guard — it silently
   degrades to a non-atomic check-then-act because its `WHERE` is primary-key-only and it exposes no
   affected-rows count. Use raw `_Query` + `getAffectedRows()`.
@@ -67,6 +111,14 @@ load → set → save → `transactionCommit` by primary key (the idiom
 
 ## Change history
 
+- 2026-08-04 — TRUE-80282: documented that **`initial` is never resynced after a save**
+  (`Model.php:244` diffs on `initial !== value`; `initial` set only at load/initialize,
+  `Model.php:702`), so a **second `save()` on the same instance omits the column entirely** — every
+  "set it back to null and save" rollback / compensating write on a reused instance is a silent
+  no-op. Recorded the required fix (fresh instance per write, with `_Database::useQueryCache(false)`
+  + `setIsReadHostEnabled(false)` so the reload can't return the pre-write row). Found via a PayPal
+  rollback that would have left Rate customers marked cancelled while still being billed.
+  (mhammontree)
 - 2026-07-17 — Documented that `_Model::save()` cannot perform an atomic conditional update
   (primary-key-only `WHERE`, skips no-diff writes, no affected-rows count) and that raw `_Query` +
   `_Query::getAffectedRows()` is the required surface for any DB row-claim / optimistic-concurrency

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-03
+updated: 2026-08-04
 owners: ["kyalamarthi", "mhammontree"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -218,6 +218,29 @@ CLIENT database as a `CustomRecordScript` — NOT in `Core.RecordScripts`.** Fir
 - Verified by applying the file **twice** to two environments: exactly one script row and one
   grant row each.
 
+## 🔒 A scripted POST BYPASSES the record-level `AclRecordPermissions` check entirely
+
+`V2.php:4472` guards the record-permission check with:
+
+```php
+if (!$isUsingScriptedCall && empty($routePairs)) { /* … record-level ACL check … */ }
+```
+
+So for a scripted call, **authorization comes solely from `AclCustomRecordScripts` /
+`AclRecordScripts`** — the four-table record-CRUD chain is never consulted.
+
+**⚠ Therefore: never add an `AclRecordPermissions` CREATE grant to "make a scripted POST work."**
+It cannot be the cause, and it opens a real hole. Concrete case: adding a CREATE grant on
+`Subscriptions` (to debug a 403 on `POST /v2/subscriptions/cancel`) would have let **any portal
+customer insert arbitrary subscription rows via ordinary CRUD** — the script grant was the actual
+missing piece.
+
+**Debugging rule: an `EZ-1` on a scripted POST means the SCRIPT grant is missing** (or the
+`RecordScripts`/`CustomRecordScripts` row doesn't match method+route), never a missing CREATE
+permission. See the
+[ACL permission chain](../../_underscore/features/acl-permission-chain.md) for the CRUD chain this
+path deliberately skips.
+
 ## Data source note (core DB hosts/credentials)
 
 The core cluster hosts and credentials this endpoint reads through are **not** documented here;
@@ -231,6 +254,13 @@ an `AclRecordScripts` grant in each client DB.
 
 ## Gotchas / known issues
 
+- **A scripted route cannot carry an id BEFORE the script segment.** The dispatcher consumes the
+  **trailing path segment as the script name**, so `/v2/<record>/{id}/<script>` does not match —
+  pass the id in the query string or the JSON body instead. This is why Rate's cancel endpoint is
+  `POST /v2/subscriptions/cancel` with `{entitlementUuid}` in the body
+  ([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`.
@@ -257,6 +287,14 @@ an `AclRecordScripts` grant in each client DB.
 
 ## Change history
 
+- 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
+  grant — and that adding a CREATE grant to "fix" a scripted-POST `EZ-1` is both ineffective and a
+  privilege escalation (on `Subscriptions` it would let any portal customer insert subscription rows
+  via normal CRUD). Also recorded that a scripted route **cannot carry an id before the script
+  segment** (the trailing segment *is* the script name), so ids go in the query string or body.
+  (mhammontree)
 - 2026-08-03 — TRUE-80494: documented that argument binding is **PHP named-argument unpacking of the
   query string** (`parse_str` + merged JSON body, query wins, `$args['api']` last, then
   `$model::$phpMethod(...$args)`; `V2.php` ~4202/~4468) and its two consequences: (a) a script

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

@@ -2,7 +2,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/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 |
+| [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 |
 | [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 |

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

@@ -6,9 +6,11 @@ project: TOGa View Frontend
 client: shared
 type: architecture
 status: active
-updated: 2026-06-24
-owners: [apeterson]
+updated: 2026-08-04
+owners: [apeterson, mhammontree]
 files:
+  - toga2-view/tsconfig.json
+  - toga2-view/tsconfig.app.json
   - toga2-view/src/main.tsx
   - toga2-view/src/App.tsx
   - toga2-view/src/routes.tsx
@@ -148,6 +150,12 @@ Routes are defined in `src/routes.tsx` with `createBrowserRouter`:
 - **Tooling:** `npm run dev` (Vite dev server, port 5173), `npm run build`
   (`tsc && vite build --mode production`), plus `buildBeta` / `buildGamma`. `npm run lint`
   runs ESLint with `--max-warnings 0`. E2E via Cypress (`npm run cypress`).
+- **⚠ `npx tsc --noEmit` at the repo root checks NOTHING.** The root `tsconfig.json` is a
+  **references-only solution file**, so it type-checks zero files — a deliberately injected type
+  error still exits 0. This makes it a silent false-green in any pre-commit or CI-style check.
+  **Always type-check with `npx tsc -p tsconfig.app.json --noEmit`.** That config has
+  **pre-existing errors**, so the pass criterion is "no *new* errors vs. a stashed baseline", not
+  zero errors — diff against the baseline rather than expecting a clean run.
 - **Many environments:** `.env.{development,alpha,beta,gamma,sprint,stage,test,production}`.
   Each supplies the `VITE_API_*` base URLs consumed by `axiosInstance.ts`. A client/brand is
   selected by hostname at runtime (not a separate build), via the `VITE_API_<SUBDOMAIN>`
@@ -169,6 +177,9 @@ Routes are defined in `src/routes.tsx` with `createBrowserRouter`:
   page/viewModel that consumes it — check call sites before changing its shape.
 - **Tokens live in `localStorage`** (`accessToken`/`refreshToken`/`user`). Treat them as
   sensitive; never log token values or echo them into Sentry extras.
+- Type-check with `npx tsc -p tsconfig.app.json --noEmit` — the root `tsconfig.json` is
+  references-only and checks nothing (false green). Compare against a stashed baseline; the app
+  config has pre-existing errors.
 
 ## Client notes
 

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

@@ -92,9 +92,15 @@ Two things about this flow are easy to get wrong and are the reason it is docume
 
 5. **Confirm flow.** `handleConfirmCancel()` awaits `cancelSubscription()`; it closes the modal
    **only** on a genuine resolve, and on rejection keeps the modal open and renders
-   `subscriptionFields.confirm.errorMessage`. Since the stub always throws, today's real-world
-   outcome is always the error state — intentional, so nothing reports a cancellation that did not
-   happen.
+   `subscriptionFields.confirm.errorMessage`. `cancelSubscription()` now issues the real
+   `POST /v2/subscriptions/cancel`, so a resolve means the server both wrote the cancellation
+   request **and** got a PayPal confirmation. Preserve the reject-on-anything-else behavior: the
+   server intentionally fails the call rather than half-cancelling.
+
+6. **Post-cancellation display.** Once a cancellation is pending, the service card renders
+   **"Service ends by \<date\>"** instead of "Renews", and the Cancel affordance is hidden — the
+   subscription stays `isActive = 1` until its period ends, so the *absence* of a cancel button (not
+   the absence of the card) is what signals the pending state.
 
 ## Decision — gate on `serviceType`, not on `isRateWarranty`
 
@@ -115,9 +121,13 @@ not self-service cancellable from the portal; only tech-support subscriptions ar
 - **The cancel UI lives only on `GetSupportPage.tsx`.** `ServiceCard` has no cancel affordance —
   do not go looking for one in `components/`, and do not add a second entry point without
   reproducing the same `showCancelUi` gate.
-- **No backend endpoint exists.** `cancelSubscription()` throws
-  `"Subscription cancellation is not available yet."` by design (reject, never resolve). Swap the
-  body for the real API call when the endpoint ships; do not "fix" it by resolving.
+- **The `serviceType === 'tech'` gate is a UX affordance, NOT the enforcement point.** The backend
+  refuses warranty cancellations independently, using the WH purchase guard's authority (title
+  keyword or `Items.id 3`). Do not weaken the server check because the button is already hidden.
+- **The cancel endpoint takes `entitlementUuid`, not the subscription uuid.** Passing
+  `subscription.uuid` will not work and requesting that field would need a new joined-field ACL
+  grant whose absence fails the whole entitlements request. See the
+  [cancellation doc](../../../../clients/rate/features/subscription-cancellation.md).
 - **`detectServiceType` now has a second consumer with a policy consequence.** Widening its
   `'tech'` keywords does not just change a card row any more — it **exposes the cancel button** for
   whatever newly matches. Check both call sites before touching the classifier.
@@ -141,6 +151,14 @@ same user, so the page must distinguish them per service rather than per account
 
 ## Change history
 
+- 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
+  warranties on its own authority), that the argument is the **entitlement** uuid, and that a
+  pending cancellation renders "Service ends by \<date\>" with the Cancel affordance hidden while
+  the subscription stays active. Full backend behavior:
+  [Rate tech-support subscription cancellation](../../../../clients/rate/features/subscription-cancellation.md).
+  (mhammontree)
 - 2026-07-28 — Cancel Subscription UI gated by service type: viewModel exposes
   `canCancelSubscription` (`activeService?.serviceType === "tech"`), and the view's `showCancelUi`
   now gates the button, the confirm modal, and the `cancelNote` sentence. WH warranty and

package/knowledge/clients/rate/INDEX.md

@@ -5,7 +5,7 @@
 | [Rate AIG Warranty Contract Creation (silent-failure interceptor)](features/aig-contract-creation.md) | 2.0 | When a Rate entitlement is created, `_Model_Rate_Entitlement::postPost` (`_underscore/Model/Rate/Entitlement.php`) creates an **AIG warranty contract** as a non | _underscore/Model/Rate/Entitlement.php, _underscore/ApiRequest.php, worker2/Worker/Monitors/RateEntitlement.php |
 | [Rate Monthly Reconciliation Report](features/monthly-reconciliation-report.md) | 1.0 | A monthly cron that emails an Excel reconciliation report covering all Rate subscription sales orders and their linked PayPal payments for the prior calendar mo | worker/crons/notifications/reports/rate/send_monthly_rate_purchases_report.php, worker/schedules/cron.worker.notification.json |
 | [Rate SalesOrder → NetSuite CashSale Export (postPost)](features/netsuite-cashsale-export.md) | 2.0 | Rate sells home-warranty / home-tech-support products. | _underscore/Model/Rate/SalesOrder.php, _underscore/Model/Rate/Item.php |
-| [Rate PayPal Subscription Purchase & Webhook Pipeline](features/paypal-subscription-purchase-webhook.md) | 2.0 | > # ⚠ STATUS (2026-08-04, TRUE-80575) — TWO INDEPENDENT LIVE DEFECTS > > **A. | worker2/Worker/Rate.php, worker2/Config/production.ini, api2/Config/production.ini, _underscore/Component/Api/Paypal.php, toga2-view/src/hooks/usePayPalSubscription.ts, toga2-view/src/services/paypalService.ts, toga2-view/src/pages/CheckOut/viewModel/useCheckoutPageViewModel.ts, toga2-view/src/pages/CheckOut/api/checkoutApi.ts, toga2-view/src/pages/Activation/view/Activation.tsx |
+| [Rate PayPal Subscription Purchase & Webhook Pipeline](features/paypal-subscription-purchase-webhook.md) | 2.0 | > # ⚠ STATUS (2026-08-04, TRUE-80575) — TWO INDEPENDENT LIVE DEFECTS > > **A. | worker2/Worker/Rate.php, worker2/Config/production.ini, api2/Config/production.ini, _underscore/Component/Api/Paypal/Paypal.php, toga2-view/src/hooks/usePayPalSubscription.ts, toga2-view/src/services/paypalService.ts, toga2-view/src/pages/CheckOut/viewModel/useCheckoutPageViewModel.ts, toga2-view/src/pages/CheckOut/api/checkoutApi.ts, toga2-view/src/pages/Activation/view/Activation.tsx |
 | [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
 | [Service Card Entitlement Display](features/service-card-entitlements.md) | 2.0 | Rate's home and services pages display one service card per purchased entitlement. | src/components/ServiceCard/ServiceCard.tsx, src/components/ServiceCard/index.ts, src/hooks/useBundleServices.ts, src/hooks/useActiveServices.ts, src/pages/Home/api/homeApi.ts, src/pages/Home/view/HomePage.tsx, src/pages/Home/viewModels/useHomePageViewModel.ts, src/pages/Services/view/ServicesPage.tsx, src/pages/Services/viewModels/useServicePageViewModel.ts, src/api/serviceAddressApi.ts, src/api/apiErrors.ts, dbchanges2/Client_Rate/2026-07-24a - AddressIdFieldPermission.sql |
 | [Rate Service-Purchase Confirmation Emails (Tech / Warranty)](features/service-purchase-emails.md) | 2.0 | When a Rate customer purchases a service, a confirmation email is sent. | _underscore/Model/Rate/Entitlement.php, worker2/Worker/Notification/EmailTemplate.php, dbchanges2/Client_Rate/2026-06-30a - Rate purchase email templates.sql |

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: rate
 type: client-feature
 status: active
-updated: 2026-07-27
+updated: 2026-08-04
 owners: [mhammontree, tcox]
 files:
   - _underscore/Model/Rate/Entitlement.php
@@ -15,6 +15,7 @@ files:
 related:
   - clients/rate/profile.md
   - clients/rate/features/whole-home-warranty-purchase-guard.md
+  - clients/rate/features/subscription-cancellation.md
   - ../../../2.0/apps/worker2/features/monitoring-framework.md
 ---
 
@@ -99,6 +100,12 @@ creation vs. cancellation. This is an accepted, documented limitation — not an
   address, so an entitlement with no address never even attempts contract creation (and
   never logs a `/contract` call).
 - **Auth-induced failures are blind to the monitor** — see the detection limitation above.
+- **The AIG carrier cancel (`/contract/cancel`) is chained off the SAME
+  `BILLING.SUBSCRIPTION.CANCELLED` event** that worker2 uses to confirm a portal cancellation — so
+  the two flows share a trigger and a failure mode: while `Rate/Webhook` jobs are timing out, neither
+  the AIG cancel nor the `dateCancelled` stamp happens. See
+  [subscription cancellation](subscription-cancellation.md). **"AIG" here is the *carrier*, not the
+  `Client_Aig` tenant** — do not resolve it as a client slug.
 - **The AIG-success branch REASSIGNS `$payload->uuid`** (`$payload->uuid = _String::generateUuid()`,
   repurposed as the AIG contract number) — and it does so **in the same `postPost`** that pins the WH
   service address. On the pre-redesign build the pin step ran **after** this reassignment and keyed
@@ -110,6 +117,11 @@ creation vs. cancellation. This is an accepted, documented limitation — not an
 
 ## Change history
 
+- 2026-08-04 — TRUE-80282: noted that the AIG carrier cancel (`/contract/cancel`) is chained off the
+  **same** `BILLING.SUBSCRIPTION.CANCELLED` webhook event that confirms a portal subscription
+  cancellation, so both share a trigger and are both blocked by the current `Rate/Webhook` watchdog
+  failures; and that "AIG" in this flow is the **carrier**, not the `Client_Aig` tenant.
+  (mhammontree)
 - 2026-07-27 — TRUE-79533 beta-verified: updated the service-address note to the **standard**
   `Entitlements.serviceAddressId` FK (the Rate-custom `c_serviceAddressId` was promoted to a
   base-model standard field), and noted that this AIG block and the WH pin read the **same**

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

@@ -12,7 +12,7 @@ files:
   - worker2/Worker/Rate.php
   - worker2/Config/production.ini
   - api2/Config/production.ini
-  - _underscore/Component/Api/Paypal.php
+  - _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
@@ -70,7 +70,7 @@ token"*, `Rate.php:394` throws *"Entitlement not found"*.
 ## Gotchas
 
 - **The watchdog timeout is NOT the PayPal-egress problem — do not re-chase egress.**
-  `worker2/Worker/Rate.php:59-77` and `_underscore/Component/Api/Paypal.php:13-18` both
+  `worker2/Worker/Rate.php:59-77` and `_underscore/Component/Api/Paypal/Paypal.php:13-18` both
   assert that webhook stalls come from the EB worker tier being unable to reach
   `api-m.paypal.com`. That egress problem is real but is **not** what kills these jobs:
   `verify_signature = false` in `worker2/Config/production.ini`, so the signature/OAuth

package/knowledge/clients/rate/features/service-card-entitlements.md

@@ -6,7 +6,7 @@ project: TOGa View Frontend
 client: rate
 type: client-feature
 status: active
-updated: 2026-07-28
+updated: 2026-08-04
 owners: ["bala", "tcox", "mhammontree"]
 files:
   - src/components/ServiceCard/ServiceCard.tsx
@@ -24,6 +24,7 @@ files:
 related:
   - clients/rate/profile.md
   - whole-home-warranty-purchase-guard.md
+  - subscription-cancellation.md
   - 2.0/apps/toga2-view/features/get-support-cancel-subscription.md
 ---
 
@@ -107,8 +108,21 @@ product types would need `detectServiceType` extended or overridden.
 unclassified services get no cancel path). See
 [Get Support — Subscription Details & Cancel Subscription Gating](../../../2.0/apps/toga2-view/features/get-support-cancel-subscription.md).
 
+## Pending-cancellation display ("Service ends by …")
+
+A cancelled-but-not-yet-expired subscription **still has `isActive = 1`** (access is deliberately
+retained through the paid period — see
+[subscription cancellation](subscription-cancellation.md)), so it keeps rendering a card. The card
+switches its date row from **"Renews \<date\>"** to **"Service ends by \<date\>"** once
+`dtRequestToCancel` is set, and the Cancel affordance is hidden. `homeApi` / `useBundleServices`
+therefore also request the cancellation columns — as **optional** fields, dropped on `EZ-2`/`EV-8`
+by `apiErrors.ts`, so a missing grant loses the "ends by" wording rather than the whole page.
+
 ## Gotchas / known issues
 
+- **A pending cancellation is NOT visible in `isActive`.** `isActive` stays `1` until the nightly
+  expiry cron. Any UI that infers "still subscribed" from `isActive` alone will show "Renews" to a
+  customer who already cancelled — read `dtRequestToCancel` / `dateCancelled`.
 - **`ojoin` is required for address** — using INNER JOIN (`join`) drops every entitlement
   whose contact has no `primaryContactAddressId`, silently hiding those cards.
 - **`T00:00:00` in date formatting** — `formatDate` appends this before parsing to avoid
@@ -147,6 +161,11 @@ unclassified services get no cancel path). See
 
 ## Change history
 
+- 2026-08-04 — TRUE-80282: cards now render **"Service ends by \<date\>"** instead of "Renews" for a
+  pending cancellation (and hide the Cancel affordance). Recorded that such a subscription still has
+  `isActive = 1` until the nightly expiry cron, so `isActive` alone must not be read as "still
+  subscribed", and that the new cancellation columns are requested as **optional** fields so a
+  missing grant degrades the wording rather than the page. (mhammontree)
 - 2026-07-28 — `detectServiceType` gained a second, non-display consumer: the Get Support page gates
   its Cancel Subscription UI on `serviceType === 'tech'`, so the classifier now decides which
   entitlements are self-service cancellable. (tcox)

package/knowledge/sessions/2026-08-04-surface-approval-details-layout-apeterson.md

@@ -0,0 +1,69 @@
+---
+type: session
+slug: surface-approval-details-layout
+title: SalesOrder approval-details card — layout split, title, submitted-by suffix
+author: apeterson
+repos: [toga25-supply, dbchanges2]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-08-04
+updated: 2026-08-04
+---
+
+# Session: surface-approval-details-layout
+**Date:** 2026-08-04
+**Project/Repo:** toga25-supply (2.0) + dbchanges2 (Core SQL)
+**Task:** Reshape the SalesOrders record-modal approval-details card — separate approval-stage layout, surface-driven section title, and an inline "submitted by" title suffix — while keeping the surface/FE boundary clean.
+
+---
+
+## What WORKED
+<!-- Include specific file paths and evidence -->
+- **Two-layout component split** (approval vs standard). `SalesOrderView.tsx` branches on `isApprovalDetailsActive` → `SalesOrderApprovalSummaryGrid` (new) vs `SalesOrderSummaryGrid`. Approval grid: approval-details spans 3 cols, order-summary totals 1 col (`.approvalSummaryGrid`/`.approvalDetailsSpan`). Chosen over prop-driven branching because the difference is placement across the DOM tree, not styling. tsc -b clean on all touched files.
+- **Shared machinery extracted** so both grids reuse it: `helpers/sectionRenderers.tsx` (`createSectionRenderers` factory — detailSection/approvalDetails/locationCard/totalsCard) and `helpers/getVisibleSections.ts` (isVisible + visibilityRule + approval-suppression filter).
+- **Section relocation in approval view** via `getDetailSections.tsx`: Order Details + Bill To move below the Items table, side-by-side (Order Details first, then Bill To — user reordered); Admin Notes moves to the TOP of the modal (rendered in `SalesOrderView`, suppressed from below-items). Guarded so absent sections don't throw for non-approval clients.
+- **Surface-driven 2-col field grid** for the approval-details card (`.approvalFieldsGrid` = `repeat(2, minmax(0,1fr))`), reflows via BaseDetailField's `grid-column: span var(--field-col-span,1)`.
+- **Section title** wired end-to-end from surface: confirmed resolver emits `titleMessageKey` from `Core.Surfaces.titleMessageId` (`_underscore/Model/Core/Surface.php:634-635`); `buildSection` already resolves `sectionTitle` from it — so it's a pure DB change. Migration `dbchanges2/Core/2026-08-04a - ApprovalDetailsSectionTitle.sql` inserts the message + links the surface.
+- **"Submitted by {name}" title suffix**: added a `config.role: 'titleSuffix'` marker pattern. `buildSection` pulls that element OUT of the grid fields and exposes `section.titleSuffix = {label, valueKey}`; the `approvalDetails` renderer draws it inline in the `<h2>` (dot-path value resolve), styled `.cardTitleSuffix` (muted/italic). Migration `2026-08-04b` stamps the role on the `createdByUser._name` element. tsc clean.
+
+## What did NOT work — DO NOT RETRY THESE
+<!-- Exact failure reasons — do not vague-ify -->
+- **Surface-driving grid GEOMETRY (column count + per-field colSpan) via surface config.** Tried `config.columns` on the surface + `config.colSpan` on elements. Dead end: the resolver's `CONFIG` SurfaceOverride REPLACES an element's whole config blob rather than merging (`_underscore/Model/Core/Surface.php` ~L827: `$config = $value`). So per-client colSpan would force adding a first-class `COL_SPAN` to the `SurfaceOverrides.attribute` ENUM + resolver + schema + framework deploy — far too much machinery for "this box is 2 columns wide". Reverted ALL of it (deleted the columns migration, removed the adapter passthroughs and `--approval-cols` var). Geometry is FE-driven; the 2-col grid is a fixed CSS choice. See KB memory `surface-vs-fe-layout-boundary`.
+- **Stable-sort reorder to float approval-details to the front of the shared summary grid** — superseded and removed by the component split. Net state is the split; do not reintroduce the sort.
+
+## Not tried yet (candidates for next session)
+- Run the two Core migrations (`2026-08-04a`, then `2026-08-04b`) local → beta → prod; add PLAYBOOK change-log + env-status rows; commit dbchanges2 with a `TRUE-#####:` message.
+- QA in the Compass/CompassCanada sandbox: (1) approval-stage order shows the new layout, 2-col field grid, "Approval Details — submitted by {name}" title, and Submitted By no longer in the grid; (2) a non-approval order is visually unchanged.
+- Optional copy tweak: lowercase the mock's "submitted by" by changing `Core.Messages 'salesOrder.approvalDetails.field.submittedBy'` defaultValue to `submitted by` (left as-is — copy decision).
+- Consider whether any approval-stage order can lack `createdByUser._name` (would show Submitted By in neither grid nor title — acceptable but confirm).
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| toga25-supply/.../helpers/sectionRenderers.tsx | Created | `createSectionRenderers` factory + `resolvePath`; approvalDetails renders titleSuffix inline |
+| toga25-supply/.../helpers/getVisibleSections.ts | Created | Extracted visibility filter for the standard grid |
+| toga25-supply/.../layoutComponents/SalesOrderApprovalSummaryGrid.tsx | Created | Approval top grid (approval-details span 3 + totals 1) |
+| toga25-supply/.../layoutComponents/SalesOrderSummaryGrid.tsx | Modified | Slimmed to delegate to the two helpers |
+| toga25-supply/.../view/SalesOrderView.tsx | Modified | Branches on approvalActive; Admin Notes at top in approval view |
+| toga25-supply/.../helpers/getDetailSections.tsx | Modified | Approval-only: Order Details + Bill To below items; adminNotes suppressed below |
+| toga25-supply/.../SalesOrderRecordModalLayout/index.ts | Modified | Exports SalesOrderApprovalSummaryGrid |
+| toga25-supply/.../helpers/surfaceBundleToTenantFields.ts | Modified | `titleSuffix` role marker → section.titleSuffix, excluded from grid; geometry passthroughs reverted |
+| toga25-supply/.../SalesOrderRecordModal.module.css | Modified | .approvalSummaryGrid/.approvalDetailsSpan, .approvalFieldsGrid (fixed 2-col), .cardTitleSuffix |
+| dbchanges2/Core/2026-08-04a - ApprovalDetailsSectionTitle.sql | Created | Message "Approval Details" + link surface.titleMessageId (NOT YET RUN) |
+| dbchanges2/Core/2026-08-04b - ApprovalDetailsSubmittedByTitleSuffix.sql | Created | Stamp config.role='titleSuffix' on createdByUser._name element (NOT YET RUN) |
+
+## Decisions made
+- **Component split, not prop-driven**, for approval vs standard — the layouts differ in DOM placement (sections move relative to the Items table), not just CSS. Rejected: one prop-driven `SalesOrderSummaryGrid` (would leak branch logic into SalesOrderView anyway).
+- **Grid geometry lives in the FE; surface owns content/visibility/order/ACL.** Rejected surface-driven columns/colSpan (see failure above). Saved as KB feedback memory `surface-vs-fe-layout-boundary`.
+- **Title suffix via a `config.role` marker**, mirroring the existing `sectionLayoutRule`/`sectionVisibility` markers — surface declares the semantic role + value/label (content), FE renders placement. Rejected: hardcoding the value/label in the FE.
+- **Section title stays surface-driven** (it's content, not geometry) — pure DB change, no FE edit needed.
+
+## Blockers
+None. FE is committed-ready and typechecks; the two Core migrations are authored but NOT yet run against any DB.
+
+## Exact next step
+> Run `dbchanges2/Core/2026-08-04a - ApprovalDetailsSectionTitle.sql` then `2026-08-04b - ApprovalDetailsSubmittedByTitleSuffix.sql` against the LOCAL Core DB, then load an approval-stage order in the Compass sandbox and verify: title reads "Approval Details — submitted by {name}", the field grid is 2-col, and Submitted By is gone from the grid.
+
+---
+_Saved by /session-save on 2026-08-04_

package/package.json

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