toga-ai 1.0.535 → 1.0.537

package/knowledge/1.0/apps/library/features/startech-pcmaticb2b-sync.md

@@ -6,8 +6,8 @@ project: Library
 client: pcmaticb2b
 type: client-feature
 status: active
-updated: 2026-07-29
-owners: [snaredla]
+updated: 2026-08-10
+owners: [snaredla, mhammontree]
 files:
   - library/app/api/toga2.php
   - library/app/api/startechticket.php
@@ -59,6 +59,32 @@ $payload['ticketType'] = ['code' => $toga2TicketTypeCode];
 
 Both `PCS Ticket` and `TOGaDesk-PCS` map to `PCS` in TOGA 2.0.
 
+## Onboarding a new StarTech client — `STARTECH_TOGADESK_CLIENTS`
+
+`App_Api_Toga2::STARTECH_TOGADESK_CLIENTS` (`library/app/api/toga2.php`, top of the class) is the
+registry that identifies StarTech-integrated clients. It maps **TOGaDesk client id => the client's
+TOGA 2.0 API credentials**:
+
+```php
+const STARTECH_TOGADESK_CLIENTS = [
+    App_Model_TogaDesk_Ticket::TOGADESK_CLIENT_ID__PCMATICB2B => [
+        'clientUuid' => self::CLIENT_UUID_PCMATICB2B,
+        'apiUuid'    => self::API_UUID_PCMATICB2B,
+        'apiSecret'  => self::API_SECRET_PCMATICB2B,
+    ],
+];
+```
+
+- **A new row must be added per client onboard.** Consumers (e.g.
+  `getStartechSelectableTicketStageNames`) look the client up here and **short-circuit to an empty
+  result with no DB hit** when absent — so a missing row is a silent no-op (an empty status
+  dropdown), not an error. This is the operational step to remember.
+- The row's values are references to the per-client `CLIENT_UUID_*` / `API_UUID_*` /
+  `API_SECRET_*` class constants declared at the top of the same file — that is **where** the
+  credentials live. Do not reproduce their values in the KB, tickets, or logs (see the hardcoded-credentials
+  gotcha in [toga2-api-client-and-bridge](./toga2-api-client-and-bridge.md)).
+- Currently **one** row: TOGaDesk client **177** (PC Matic B2B).
+
 ## Gotchas
 
 - **Do not add a NULL early-return guard in this function.** NULL `c_escalateToStartech` means the ticket was created in TOGaDesk — it must still sync to TOGA 2.0. The Startech gate lives in `_Trait_Startech_Ticket::postPost`, not here.
@@ -93,16 +119,12 @@ Imports Startech (Easeedesk V3) config into TOGA 2.0 — users, groups, devices,
   the 1.0 → 2.0 payload. Both reference the client's 2.0 schema **by name** (from
   `App_Model_Client::getClientDatabaseNames()`) so the JOIN stays inside one client schema — do not use
   `qqJoinClientsTable(…, true)` here, its UNION-across-all-clients form would cross-match ids between
-  clients. StarTech clients are identified by `App_Api_Toga2::STARTECH_TOGADESK_CLIENTS`
-  (TOGaDesk client id => TOGA 2.0 client id); non-StarTech clients short-circuit with no DB hit.
-- 2026-07-29: Added two per-ticket-type stage helpers to `App_Api_Toga2` (see
-  `clients/pcmaticb2b/features/startech-per-ticket-type-stages.md`):
-  `getStartechSelectableTicketStageNames($togadeskClientId, $togadeskDepartmentId)` resolves the
-  agent-selectable stage names for TOGaDesk's status dropdown (department → ticket type via
-  `TicketTypes.c_togadeskTicketDepartmentId`, filtered by `c_isSelectable = 1`), and
-  `getStartechTicketStageUuid($ticketTypeName, $ticketStageName)` resolves a stage within a type for
-  the 1.0 → 2.0 payload. Both reference the client's 2.0 schema **by name** (from
-  `App_Model_Client::getClientDatabaseNames()`) so the JOIN stays inside one client schema — do not use
-  `qqJoinClientsTable(…, true)` here, its UNION-across-all-clients form would cross-match ids between
-  clients. StarTech clients are identified by `App_Api_Toga2::STARTECH_TOGADESK_CLIENTS`
-  (TOGaDesk client id => TOGA 2.0 client id); non-StarTech clients short-circuit with no DB hit.
+  clients. StarTech clients are identified by `App_Api_Toga2::STARTECH_TOGADESK_CLIENTS`;
+  non-StarTech clients short-circuit with no DB hit.
+- 2026-08-10: **Corrected** the description of `STARTECH_TOGADESK_CLIENTS` — it maps TOGaDesk client
+  id to the client's **TOGA 2.0 API credentials** (`clientUuid`/`apiUuid`/`apiSecret`, referencing the
+  `CLIENT_UUID_*`/`API_UUID_*`/`API_SECRET_*` class constants), **not** to a TOGA 2.0 client id as the
+  two 2026-07-29 entries stated. Added the onboarding section: a row must be added per client onboard
+  or the client silently short-circuits (empty stage list, no error). Also deduplicated the
+  accidentally-doubled 2026-07-29 entry. Observed while resolving a `_production` merge on TRUE-79401;
+  the const itself was authored by a teammate. (mhammontree)

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-05
+updated: 2026-08-10
 owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
@@ -213,6 +213,10 @@ tickets) was **explicitly rejected** — see the gotcha about the single-recipie
    intact under a large merge. **Still open: whether it is deployed to the prod worker.**
    Review technique worth reusing: `git diff _production...HEAD -- <file>` isolates a ticket's real
    contribution from merge noise when an old branch is finally synced.
+   **Re-synced 2026-08-10** (`c64164fe`, pushed): `_production` merged into `TRUE-79401` again; the
+   only conflict was a positional collision in the class const block of `app/api/toga2.php` (this
+   ticket's `CUSTOMER_EMAIL_DELIMITER` landing next to incoming consts) — resolved by keeping both,
+   no logic change. Patch still intact; **deploy to the prod worker remains unverified.**
 2. **Beta verification of the nested write is outstanding.** Assert real
    `Client_Aig.ContactEmailAddresses` **row counts** (never the HTTP status), covering **both** a
    brand-new contact (CREATE) **and** a second entitlement for an **existing** contact (UPDATE).
@@ -361,6 +365,10 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-08-10 — TRUE-79401 re-synced with `_production` (`c64164fe`, pushed); the sole conflict was a
+  positional const-block collision, resolved by keeping both sides. Patch intact; deploy still
+  unverified. `STARTECH_TOGADESK_CLIENTS` (credential registry, add a row per client onboard) is
+  documented on [startech-pcmaticb2b-sync](./startech-pcmaticb2b-sync.md). (mhammontree)
 - 2026-08-05 — Recorded that a 2.0 GET **silently truncates a nested child collection** (observed
   `itemFulfillmentItemUnits` 45 of 70) with no error — so verification/counts must read the child
   resource **flat + fully paginated** and use `meta.totalRecordCount`, never a single nested

package/knowledge/1.0/standards/backend-php.md

@@ -5,8 +5,8 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-08-05
-owners: [jcardinal, rgirish, mhammontree]
+updated: 2026-08-06
+owners: [jcardinal, rgirish, mhammontree, ajean]
 files: []
 related:
   - ../apps/library/architecture.md
@@ -442,33 +442,44 @@ class Browser_Datagrid_Accounts extends Browser_Datagrid {
 * The `@` error-suppression operator is acceptable only for defensive file I/O (e.g. reading an optional cache file); do not use it to hide real errors.
 * Use structured logging to capture application behavior and errors.
 
-### PHP warnings throw — guard fragile I/O, do not rely on `!== false`
-
-The bootstrap sets `error_reporting(E_ALL)` and `App_Error::handleError` (`library/app/error.php`)
-converts **every** PHP warning into an `ErrorException`. Consequences you must design around:
-
-- Warning-emitting calls **throw at the call site** rather than returning their documented
-  failure value. `file_get_contents()` on an unreachable/403/timed-out URL raises an
-  `ErrorException` **inside** the call — so a following `if ($x !== false)` guard never runs.
-- In a loop (e.g. a cron), one such throw aborts the **entire** remaining batch, not just the
-  current item. This is especially dangerous in two-phase "stamp then act" crons where earlier
-  phases have already committed state.
-
-Wrap fragile I/O and return the failure value yourself:
-
-```php
-function safeFetchPdf(string $url) {
-    try {
-        return file_get_contents($url);
-    } catch (\ErrorException $e) {
-        error_log('PDF fetch failed: ' . $e->getMessage());
-        return false;
-    }
-}
-```
-
-Then guard each dependent step **independently** (not a joint `&&`) so one failure degrades
-gracefully instead of dropping unrelated work or crashing the loop.
+### A notice/warning cannot be contained by `try/catch` — and it jams queues
+
+**Canonical mechanics are above:** see
+[*Any PHP warning terminates the request — how to opt out locally*](#any-php-warning-terminates-the-request--how-to-opt-out-locally).
+`App_Error::handleError` does **not** throw; it calls `handleException`, which `exit`s. Two
+sanctioned opt-outs (a local `set_error_handler`, or
+`App_Error::setThrowExceptionsEnabled(false)` with a `finally` restore) are documented there.
+This section records what that means for **job/queue code** specifically.
+
+Additional verified detail:
+
+- **Both exit paths.** `handleException` ends in `exit` whether Sentry is absent
+  (`library/app/error.php` ~L407) or present (~L671). Apps that call `\Sentry\init` in
+  `_/app/framework.php` — `worker` included — take the Sentry path, so "Sentry is configured"
+  does **not** mean execution continues.
+- **The `return false;` after `exit;` in `handleError` is unreachable dead code.** Do not read
+  it as a signal that the handler returns control to the call site.
+- **A notice jams a queue exactly like an uncaught exception would.** In an inbox- or
+  queue-driven loop, any statement *after* the failure point — an ack, an
+  `$imap->deleteMessage()`, a status stamp — never executes, so the same item is re-read and
+  re-fails on every run, forever. Confirmed against production evidence: after the notice
+  fired, the importer made **zero** further api2 calls in that run.
+- **Diagnostic fingerprint:** an occurrence count that is an exact multiple of the job's
+  scheduled frequency (e.g. 20/hour for `*/3 * * * *`) means **one** poisoned item retried,
+  not many distinct failures.
+- **In job code, prevention beats containment.** Guard optional data with `isset()` before
+  reading it, and consume/ack the item in a `finally` (or under a `catch (Throwable)`) so a
+  genuine exception cannot strand it. You cannot wrap your way out of a notice.
+
+> **Existing guidance under review.** An earlier version of this section recommended
+> wrapping fragile I/O in `try { ... } catch (\ErrorException $e)` relying on the GLOBAL
+> handler to convert a warning. Given the `exit` above, that cannot work for a PHP
+> warning or notice — the process ends before the `catch`. Uses of that pattern need
+> **re-verifying** rather than assuming they are safe or assuming they are broken: the
+> call may be throwing a genuine exception, or installing a local handler. Known
+> occurrences to check: `clients/prudential/features/transmit-ordershipped-email.md`
+> (~L112-123), `clients/prudential/profile.md` (~L75). Prefer the local-handler pattern
+> from the canonical section above for anything new.
 
 ## Security Best Practices
 

package/knowledge/1.0/standards/framework-rules.md

@@ -5,8 +5,8 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-06-16
-owners: [jcardinal]
+updated: 2026-08-06
+owners: [jcardinal, ajean]
 files: []
 related:
   - ../apps/library/architecture.md
@@ -114,9 +114,13 @@ repos is only query strings embedded in PHP code — not standalone migration fi
 
 ## PHP 8.x deprecations abort the request (audit before running on 8.5)
 
-The 1.0 framework's error handler promotes PHP **deprecation notices to `ErrorException`**,
-which aborts the request. On PHP 8.5, a single deprecated call in a live code path is therefore
-a hard failure, not a silent notice — it surfaces to users as a generic error.
+The 1.0 framework's error handler **terminates** on a PHP deprecation notice
+(`App_Error::handleError` → `handleException` → `exit`; it does not throw a catchable
+`ErrorException`), so the request/job dies where the deprecation fires. On PHP 8.5 a single
+deprecated call in a live code path is therefore a hard, uncontainable failure — a
+surrounding `try/catch` will not save it. See the back-end standard's
+*"Any PHP warning terminates the request — how to opt out locally"* section for the two
+sanctioned local opt-outs.
 
 - When porting or running 1.0 code on PHP 8.x, **audit for deprecated-in-8.x calls** in every
   reachable code path before deploy.

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", "ajean"]
 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
@@ -442,6 +466,23 @@ in `_underscore` and `library` in the **same** release, and the `/errors` consol
   `varchar(255)` (`errorMessage`, `subject`) **throws** on `->save()`. Inside the handler's
   `catch(Throwable)` the throw is swallowed and the row is silently dropped — precisely when a
   long message matters most. Truncate to column width before `save()`.
+- **A truncated `errorMessage` reads as "the API returned nothing" — it did not.** When a
+  captured message is a `print_r`-dumped api2 response envelope, the `varchar(255)` cut lands
+  **exactly where `status`, `error.code` and `messages[]` begin**, so the console shows an
+  envelope with no verdict in it and the field looks empty rather than severed. (Observed: a
+  pasted error cut at precisely 255 chars sent an investigation after a phantom empty field.)
+  Escalation path when the console message stops mid-envelope:
+  **(1)** the **full** request/response is in the **client-scoped** `Logs_<Client>.Api`
+  (e.g. `Logs_Quad.Api`) — **not** core `Logs.Api`; **(2)** the original inbound payload is in
+  `Logs.Event.context` (for an email importer, the attachment content verbatim — this is how a
+  poison file was recovered). Pull `context` before the **7-day** `Event` retention purges it.
+- **`_Error::buildContext` redacts the DECODED token but not the RAW response string (OPEN
+  security note).** `access_token` is stripped from the decoded response object while the raw
+  `rawResponse` / `lastResponse` strings are stored intact, so live bearer JWTs reach
+  `Logs.Event.context` in **cleartext**. Two consequences: the raw strings need adding to the
+  redactor (in `_underscore/Error.php` **and** `library/app/error/capture.php` together, per the
+  gotcha above), and until then **never paste a `Logs.Event.context` or `Logs_<Client>.Api` row
+  into a ticket, chat, or knowledge doc** — those rows carry live tokens and customer PII.
 - **Hand-written SQL is what a table rename actually breaks — and it fails *after* the model
   succeeds.** The singular rename left plural literals in hand-written statements across four
   files, so `$issue->save()` succeeded and then `UPDATE Issues …` threw **1146** before the
@@ -539,6 +580,23 @@ clientUserId). **Neither was built.** As built instead:
 
 ## Change history
 
+- 2026-08-06 — Added two debugging/security notes found while unjamming the Quad PO/ASN importer:
+  (1) a `varchar(255)`-truncated `errorMessage` severs a dumped api2 envelope exactly at
+  `status`/`error.code`/`messages[]`, so escalate to the **client-scoped** `Logs_<Client>.Api`
+  for the full envelope and to `Logs.Event.context` (7-day purge) for the original payload;
+  (2) OPEN — `_Error::buildContext` redacts `access_token` in the decoded object but not in the
+  raw `rawResponse`/`lastResponse` strings, so `Event.context` holds cleartext JWTs; do not paste
+  those rows anywhere. (ajean)
+
+- 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/_underscore/features/tracking-number-bridges.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-05
-owners: ["jcardinal", "mhammontree", "dfranks", "apeterson", "bala"]
+updated: 2026-08-06
+owners: ["jcardinal", "mhammontree", "dfranks", "apeterson", "bala", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php
@@ -177,9 +177,29 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
   `toga25-supply/sync_compasscanada_schema.sql` against `Client_CompassCanada` (local-only — prod
   already has the tables). See the
   [local-DB-refresh-from-beta workflow](../workflows/local-db-refresh-from-beta.md).
+- **⚠ Clients that were not hand-migrated still carry `TableViewJoins` pointing at the DELETED
+  RecordFields — and nothing validates them until a user opens the view.** The per-client TableView
+  repointing was done one client at a time (Compass, NYCHH, Quad); a client onboarded before it, or
+  skipped, keeps joins on dropped ids and its views **500** — first
+  `table-views/meta` with *"Model build for primary key id '1431' for `_Model_Core_RecordField` … 0
+  rows"*, then the data query with *"Unknown column … in 'on clause'"* once the missing bridge join
+  record leaves the alias undefined. **`Client_Elite` has 11 such references across 9 views, in
+  production as well as sandbox** — see
+  [Elite supply2 TableView config drift](../../../clients/elite/features/supply2-tableview-config-drift.md)
+  for the full map and the NYCHH-mirroring fix. Before switching on a supply surface for a client
+  onboarded before 2026-06, diff its `TableViewJoins` against a migrated client. Note the same
+  audit found `sales-order-shipments` (join 10) referencing dead RecordField **211 in
+  `Client_Nychh` too** — that view is broken platform-wide and needs a backend decision, not a
+  copy.
 - **Porting the item-fulfillment TableView fix to another client is two independent decisions, not a copy-paste.** The **re-root** (Units 31 → ItemFulfillmentItems 29 + OUTER unit chain) is universally portable and fixes the "0 records" bug everywhere. The **tracking source is client-specific**: Compass writes one tracking number per item fulfillment at the **item level (318)**, so its views read 318. Other clients populate different bridge levels — verify with `SELECT COUNT(*)` per bridge before choosing. As of 2026-06-19, **record 318 is empty in `Client_Nychh` and `Client_Quad`**; their tracking lives at the **IF/shipment level (317)** (covers IFIs: NYCHH 7955/10049 ≈ 79%, Quad 4878/4967 ≈ 98%) and the **unit level (319)** (≈ 7–9% — serialized only). Copying Compass's 318 join into a client that doesn't write 318 yields a structurally-correct view with permanently blank tracking until 318 is backfilled. (NYCHH's pre-fix view pointed at the now-deleted record 41 = old IF-level/package bridge, i.e. it originally intended IF-level 317.)
 
 ## Change history
+- 2026-08-06 — Recorded that the per-client TableView repointing left **unmigrated clients broken**:
+  `Client_Elite` still has 11 references to deleted RecordFields (211/321/932/358/1431) across 9
+  views in **prod and sandbox**, so its views 500 on `table-views/meta` and then on the data query
+  once the bridge join record (319 / 289) is missing. Added the pre-go-live check (diff a new
+  client's `TableViewJoins` against a migrated one) and noted `sales-order-shipments` join 10
+  references dead 211 in `Client_Nychh` as well. (tcox)
 - 2026-08-05 — Recorded that the 1.0 `App_Api_Toga2::syncItemFulfillmentFromNetsuite` full reconcile
   now maintains **all three** IF bridges (317/318/319) and, when pruning units/items NetSuite dropped,
   **deletes their bridge links first** because the bridge parent FKs are `RESTRICT` (no cascade) —