toga-ai 1.0.560 → 1.0.562

package/knowledge/1.0/apps/library/INDEX.md

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. | library/_.php, library/app/, library/browser/ |
+| [Where a new App_ class goes — the app/ folder IS a behavioral contract](features/app-class-placement-base-contracts.md) | In `library/app/`, choosing a folder is **not** a filing decision — the autoloader maps `App_<Folder>_<File>` to `app/<folder>/<file>.php`, and each folder's ba | library/app/model.php, library/app/client.php, library/app/api.php, library/app/api/servicerequest.php, library/app/api/volt.php, library/app/api/carrier/fedex.php |
 | [App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)](features/app-sso-initiation.md) | `App_Sso` (`library/app/sso.php`) is the **1.0 port of the 2.0 SAML gateway's SP-initiated SSO initiation**, packaged as a reusable, framework-level capability | library/app/sso.php, library/sso/togahub_private_key.key |
 | [Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)](features/cron-execution-monitoring.md) | `App_Framework::cronInitialization()` / `App_Framework::cronFinished()` (in `library/app/framework.php`) give every 1.0 (`App_`) cron job a check-in/check-out l | library/app/framework.php |
 | [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | Two "View Recommended Services" buttons exist in the TOGa Refresh 2026 SR view: 1. | library/app/model/toga/diagnostic.php, library/app/model/servicerequest.php |
@@ -15,5 +16,6 @@
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem, test/@dave/Junk Drawer/nsq.php |
 | [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. | library/app/api/netsuite/rest.php |
 | [NetSuite Sync Alert Monitor (App_SystemMonitor_NetSuiteIntegration)](features/netsuite-sync-alert-monitor.md) | `App_SystemMonitor_NetSuiteIntegration` (`library/app/systemmonitor/netsuiteintegration.php`, title **"NetSuite Sync Alert"**) is a 1.0 system monitor that watc | library/app/systemmonitor/netsuiteintegration.php, worker/crons/infrastructure/system_monitors.php |
+| [App_Api_ServiceRequest — provisioning a TOGa 2.0 Service Request from 1.0](features/service-request-toga2-provisioning.md) | `App_Api_ServiceRequest` (`library/app/api/servicerequest.php`) is the shared 1.0-side class that turns a posted form into a **TOGa 2.0 Service Request** — it v | library/app/api/servicerequest.php, library/app/api/toga2.php, togadesk/desk/includes/classes/class.ticket.php |
 | [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | `library/app/api/toga2.php` handles bidirectional ticket sync for PC Matic B2B between TOGaDesk 1.0 and TOGA 2.0. | library/app/api/toga2.php, library/app/api/startechticket.php, worker/crons/toga2/startech/common_import_supporting_records.php |
 | [App_Api_Toga2 — TOGa2 API Client & 1.0↔2.0 Sync Bridge](features/toga2-api-client-and-bridge.md) | `App_Api_Toga2` (`library/app/api/toga2.php`, ~8400 lines) is the **1.0-side client for the TOGa 2 (`_underscore`/api2) public API** *and* the home of the cross | library/app/api/toga2.php, worker/crons/toga2/aig/sync_togasupply_aig.php, worker/crons/toga2/wje/sync_togasupply_wje.php, test/@Mark/AIG/test_multi_email.php |

package/knowledge/1.0/apps/library/features/app-class-placement-base-contracts.md

@@ -0,0 +1,75 @@
+---
+title: Where a new App_ class goes — the app/ folder IS a behavioral contract
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-08-12
+owners: [snaredla]
+files:
+  - library/app/model.php
+  - library/app/client.php
+  - library/app/api.php
+  - library/app/api/servicerequest.php
+  - library/app/api/volt.php
+  - library/app/api/carrier/fedex.php
+related:
+  - ../architecture.md
+  - ../../../clients/elite/features/togadesk-service-request-intake.md
+---
+
+## Summary
+
+In `library/app/`, choosing a folder is **not** a filing decision — the autoloader maps
+`App_<Folder>_<File>` to `app/<folder>/<file>.php`, and each folder's base class carries **real
+inherited behavior**. Put a class in the wrong folder and it inherits a contract that does not
+apply, silently. This cost three relocations of one class on 2026-08-12; the rule below is the
+outcome.
+
+**The rule:** a class that only makes HTTP calls to an external (or cross-framework) API belongs in
+`app/api/` and should **extend nothing**.
+
+## What each base class actually obliges you to
+
+| Folder | Base | What it really means |
+|---|---|---|
+| `app/model/` | `App_Model` | Requires `const TABLENAME` **and** `const DATABASE`, and constructs **by primary key**. Only for a class backed by a real 1.0 table. |
+| `app/client/` | `App_Client` | Fiscal calendars and retail store mappings — `getName()`, `convertToFiscalPeriod()`, `getFiscalPeriods()`, `parseStoresRegionsMappingFile()`, `isEnabledForStore()`. It is **not** "the folder for client-specific code", and the folder is **FLAT** (no per-client subfolders). |
+| `app/api/` | `App_Api` | The 1.0 **fulfilment-vendor** base: `submitFromPending($aryServiceRequestItemStatusIds)`, `getDatesForServiceRequest()`. It declares **no abstract members**, so extending it compiles cleanly and silently grants your class a vendor-submission API it cannot honour. |
+
+The `App_Api` case is the trap: nothing forces you to implement anything, so the mistake never
+surfaces as an error — it surfaces later as a caller invoking `submitFromPending()` on a class that
+was never a fulfilment vendor.
+
+## Placement guidance
+
+1. **Backed by a 1.0 table?** → `app/model/…`, extend `App_Model`, declare `TABLENAME` + `DATABASE`.
+2. **Fiscal calendar / store-mapping behavior?** → `app/client/…` (flat), extend `App_Client`.
+3. **A vendor that fulfils service-request items?** → `app/api/…`, extend `App_Api`.
+4. **Anything else that just talks HTTP** (a REST client, a cross-framework provisioner) →
+   `app/api/…`, **extend nothing**. `App_Api_ServiceRequest` and `App_Api_Toga2` are both of this
+   kind.
+
+**Nesting is fine and has precedent:** `app/api/volt.php` sits beside `app/api/volt/user.php`, and
+`app/api/carrier/fedex.php` nests a carrier under a family folder. Grouping a family of API classes
+in a subfolder does not require a shared base class.
+
+## Gotchas / known issues
+
+- **"Extends cleanly" is not evidence of correct placement** in 1.0 — the bases have no abstract
+  members, so the compiler will never tell you.
+- **`app/client/` is flat.** Do not create `app/client/<client>/` — that is not how the autoloader
+  or the existing tree is organised.
+- All folder and file names under `app/` must be **lowercase** (autoloader lowercases before
+  lookup) — see [library architecture](../architecture.md).
+
+## Change history
+
+- 2026-08-12 — Captured after `App_Api_ServiceRequest` was relocated three times (model → client →
+  api). Recorded what each base class actually carries — `App_Model` needs `TABLENAME`/`DATABASE`
+  and constructs by primary key; `App_Client` is fiscal-calendar/store-mapping behavior and its
+  folder is flat; `App_Api` is the fulfilment-vendor base whose lack of abstract members makes a
+  wrong `extends` silent — and the resulting rule: an HTTP-only class lives in `app/api/` and
+  extends nothing. (snaredla)

package/knowledge/1.0/apps/library/features/service-request-toga2-provisioning.md

@@ -0,0 +1,135 @@
+---
+title: App_Api_ServiceRequest — provisioning a TOGa 2.0 Service Request from 1.0
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-08-12
+owners: [snaredla]
+files:
+  - library/app/api/servicerequest.php
+  - library/app/api/toga2.php
+  - togadesk/desk/includes/classes/class.ticket.php
+related:
+  - ./toga2-api-client-and-bridge.md
+  - ./app-class-placement-base-contracts.md
+  - ../../../clients/elite/features/desk-service-request-creation.md
+---
+
+## Summary
+
+`App_Api_ServiceRequest` (`library/app/api/servicerequest.php`) is the shared 1.0-side class that
+turns a posted form into a **TOGa 2.0 Service Request** — it validates and normalises the posted
+values, resolves the related 2.0 records it needs, refuses a duplicate, and POSTs the Service
+Request with its nested units in a single request. All transport goes through
+[`App_Api_Toga2::send()`](./toga2-api-client-and-bridge.md); this class holds no 1.0 table and does
+no SQL.
+
+First consumer is the Elite "New Service Request" button in TOGa Desk (see
+[Elite desk Service Request creation](../../../clients/elite/features/desk-service-request-creation.md)),
+but the class itself is client-agnostic — the caller passes the API endpoint in.
+
+## Key files / entry points
+
+`abstract class App_Api_ServiceRequest` — public:
+
+- `buildFromPostedValues(array $postedValues, string $ticketUuid, ?string $overrideWithApiEndpoint = null): array`
+  — validates + normalises the modal post into the 2.0 payload array (throws on a validation
+  failure; the caller converts that into the UI message).
+- `searchTicketFromToga2(string $ticketUuid, ?string $overrideWithApiEndpoint = null)` — the
+  **duplicate guard**: does a Service Request already exist for this ticket?
+- `createServiceRequestInToga2(array $serviceRequest, ?string $overrideWithApiEndpoint = null)` —
+  the POST (parent + nested units).
+- `describeApiFailureMessage($response): string` — turns a 2.0 failure response into an
+  agent-readable message.
+
+Private: `isStateInCountry()`, `findContactUuidByEmailAddress()`, `cleanPostedValue()`.
+
+## How it works
+
+1. **Build** — `buildFromPostedValues()` trims/length-caps every posted value
+   (`cleanPostedValue()`), resolves the requester contact by email, checks the selected state
+   really belongs to the selected country, and assembles the parent payload plus one nested
+   `serviceRequestUnits` entry per line.
+2. **Duplicate guard** — `searchTicketFromToga2()` looks the ticket uuid up in 2.0 before creating
+   anything.
+3. **Create** — `createServiceRequestInToga2()` POSTs **parent + nested `serviceRequestUnits` in
+   ONE request**. Related records inside that payload resolve by **natural key** — the request type
+   by *name*, the item by *partNumber* — while **customer, state and ticket are matched by uuid**.
+4. The caller (TOGa Desk) maps the outcome to its own status code and writes the ticket
+   history/reply.
+
+## The failure-check contract — `empty($response->isSuccess)` is always safe
+
+This is the load-bearing fact behind three bugs fixed on 2026-08-12, and it is not obvious from the
+call site.
+
+`App_Api_Toga2::send()` (`library/app/api/toga2.php`, ~L432–450) **always returns a response object
+that carries `isSuccess`**:
+
+- it returns early **only** when `isSuccess` is true;
+- when `isSuccess` is false and `$throwExceptionOnApiError = false`, it falls through the retry loop
+  and ends at `return $response` — **a failure arrives as a return value, not an exception**;
+- if the response is not an object, or lacks the `isSuccess` property at all, it **throws**.
+
+Therefore anything `send()` hands back can be checked with `empty($response->isSuccess)` — including
+GETs. There is no "successful response without the property" case to defend against.
+
+**The bug class this prevents:** every helper here calls `send()` with
+`$throwExceptionOnApiError = false`, so a network blip, an auth failure or a 500 comes back as a
+*response*. Code that reads straight past it to `$response->data->{resource}` sees "no records" and
+concludes **"the thing does not exist"** — the most dangerous possible misreading for a lookup.
+
+## Fixed 2026-08-12 — three silent failures, one root cause
+
+| Lookup | Old behavior on API failure | Consequence |
+|---|---|---|
+| duplicate Service Request | returned `null` | read as "no duplicate exists" → **a second Service Request on a ticket that already had one** |
+| contact by email | returned `null` | read as "no contact exists" → **a duplicate contact created in 2.0** for someone 2.0 already held |
+| state-belongs-to-country | returned `false` | a blip told the agent *"the selected state does not belong to the selected country"* — a **false accusation of bad input** |
+
+`isStateInCountry()` now returns **`?bool` as a tri-state**: `true` confirmed, `false` a genuine
+mismatch, **`null` unconfirmed** (exception or empty result). The submission is refused in both the
+`false` and `null` cases — the difference is the **message**: only `false` blames the input, `null`
+says the check could not be completed. Do not collapse this back into a `bool`.
+
+## 2.0 API rules this class had to learn the hard way
+
+- **Naming `fields` on `GET /states` SUPPRESSES the nested country.** A plain request returns the
+  nested `country`; adding a `fields` list drops it. If a nested relation vanishes, suspect the
+  field list before suspecting the data.
+- **Post a state by UUID, never by code.** `WA` and `NT` each belong to **two** countries, and the
+  API matches on code alone. `States.countryId` has `isIdentifier = 0`, so the nested country cannot
+  disambiguate it either — the uuid is the only unambiguous handle.
+- **Natural-key resolution inside a nested write:** type by name, item by partNumber. Only
+  customer / state / ticket go by uuid.
+
+## Gotchas / known issues
+
+- **A uuid is environment-scoped.** Any flow that reads uuids from one 2.0 environment and posts
+  them to another will fail or, worse, resolve to a different record. Read and write against the
+  **same** endpoint — see the hardcoded-endpoint gotcha in the
+  [Elite desk feature](../../../clients/elite/features/desk-service-request-creation.md).
+- **This class extends nothing, deliberately.** Extending `App_Api` silently inherits the 1.0
+  fulfilment-vendor contract. See
+  [where a new App_ class goes](./app-class-placement-base-contracts.md).
+- **Credentials.** Elite's `CLIENT_UUID_ELITE` / `API_UUID_ELITE` / `API_SECRET_ELITE` are class
+  constants on `App_Api_Toga2` (`library/app/api/toga2.php`). Read them from source; never
+  reproduce the values. An API secret living in a git-tracked constant is a standing concern — see
+  the credentials gotcha on [the transport doc](./toga2-api-client-and-bridge.md).
+
+## Change history
+
+- 2026-08-12 — TRUE-80497: created `App_Api_ServiceRequest` as the shared 1.0→2.0 Service Request
+  provisioner. Recorded the `send()` failure contract (**`empty($response->isSuccess)` is always a
+  safe check, including on GETs**) and fixed **three** silent failures that all came from reading
+  past a failure response returned under `$throwExceptionOnApiError = false`: the duplicate-SR
+  lookup and the contact lookup both reported "does not exist" (allowing a second SR and a
+  duplicate contact), and the state/country check reported a genuine mismatch for an exception or
+  empty result. `isStateInCountry()` now returns `?bool` — `null` = unconfirmed, with its own
+  message; both `null` and `false` still refuse. Also recorded the 2.0 rules: `fields` on
+  `GET /states` suppresses the nested country; states must be posted by uuid (`WA`/`NT` are
+  ambiguous across countries and `States.countryId` has `isIdentifier = 0`); parent + nested
+  `serviceRequestUnits` post in one request with type/item resolved by natural key. (snaredla)

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

@@ -23,6 +23,7 @@ related:
   - ../../worker/features/netsuite-togasupply-per-client-sync.md
   - ../architecture.md
   - ./error-capture-1-0.md
+  - ../../../clients/elite/features/togadesk-service-request-intake.md
 ---
 
 ## Summary
@@ -78,6 +79,22 @@ belong to the NetSuite importer — documented in the per-client-sync doc, not h
 - Returns the decoded response object; callers read `->data->{resource}`, `->meta->nextPage`,
   `->isSuccess`, `->status`, `->messages[].code`.
 
+> **`send()` ALWAYS returns something carrying `isSuccess` — so `empty($response->isSuccess)` is a
+> safe failure check on anything it returns, GETs included** (verified 2026-08-12, ~L432–450). It
+> returns early **only** when `isSuccess` is true; when `isSuccess` is false and
+> `$throwExceptionOnApiError = false` it falls out of the retry loop to `return $response`; and if
+> the response is not an object or lacks the property at all it **throws**. There is no
+> "successful response without `isSuccess`" case to defend against.
+>
+> **The corollary is the dangerous part:** with `$throwOnError = false`, a network blip, an auth
+> failure or a 500 arrives as a **response**, not an exception. Code that reads straight on to
+> `->data->{resource}` sees an empty result and concludes **"the record does not exist"** — which,
+> for a duplicate check or a contact lookup, is exactly the wrong conclusion (it creates a second
+> record). Check `empty($response->isSuccess)` *first*, and keep "unknown" distinct from "absent".
+> See [Elite Service Request intake](../../../clients/elite/features/togadesk-service-request-intake.md)
+> for the bugs this
+> caused and the `?bool` tri-state fix.
+
 > **`authenticate()` is also 1.0's ambient-client choke point for error reporting** (added
 > 2026-08-04). Every 1.0→2.0 cron passes through it holding its `UUID_CLIENT`, so it calls
 > `App_Error_Capture::setCurrentClientUuid()` — **store only, no lookup**: this is a happy-path
@@ -300,6 +317,10 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
   the `App_Model` layer; follow the surrounding escaping discipline when modifying.
 - **Per-record error isolation** in the TOGaDesk sync is via `try/catch` → `\Sentry\captureException`;
   a thrown exception elsewhere (transport, checkpoint read) still aborts the whole run.
+- **Naming `fields` can SUPPRESS a nested relation that a plain request returns.** Observed
+  2026-08-12 on `GET /states`: a bare request comes back with the nested `country`, but adding a
+  `fields` list drops it. This is the mirror image of the reverse-hasMany rule below — when a nested
+  object you expected is missing, suspect the field list before suspecting the data.
 - **A reverse hasMany collection is only returned if you add it to the fetch `fields` whitelist.**
   The `/contacts` fetch requests an **explicit** `fields` list from the 2.0 metadata API; a reverse
   hasMany collection (e.g. `contactEmailAddresses.emailAddress`) is **not** returned unless it is
@@ -365,6 +386,14 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-08-12 — Recorded the **`send()` return contract**: it always returns a response carrying
+  `isSuccess` (early-returns on true, falls through to `return $response` on false, throws when the
+  property is absent), so `empty($response->isSuccess)` is a safe failure check on anything it
+  returns — including GETs — and a `$throwOnError = false` failure must never be read as "the record
+  does not exist". Also recorded that naming `fields` on `GET /states` **suppresses** the nested
+  country a plain request returns. Surfaced building
+  [App_Api_ServiceRequest](../../../clients/elite/features/togadesk-service-request-intake.md)
+  (TRUE-80497). (snaredla)
 - 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

package/knowledge/1.0/apps/test/features/static-no-db-regression-harness.md

@@ -87,9 +87,27 @@ already editing the method.
   write only in your own folder and ask before touching another developer's.
 - Lint 1.0 code with your **PHP 7.2** CLI (`php -l <file>`) — the prod worker/library target is
   7.2, so 7.4+/8.x syntax must not appear.
+- **⚠ `php -l` with the default CLI PROVES NOTHING about 7.2.** On a normal dev box the `php` on
+  `PATH` is 8.x (8.1.10 on the machine where this was checked), and 8.x happily parses arrow
+  functions, typed properties, `??=` and `match` — the exact constructs that break the prod
+  worker. You must invoke a **real 7.2 binary** (e.g. the PHP 7.2.33 build bundled with Laragon;
+  per-machine paths are a developer-local detail and are deliberately not recorded here). Two
+  practical wrinkles when you do:
+  - if that build's own `php.ini` is broken (one was, a syntax error on line 1939), run it with
+    **`-n`** to skip the ini entirely;
+  - `-n` also drops **mbstring**, so anything using `mb_*` needs it re-added:
+    `-d extension_dir=<php>/ext -d extension=php_mbstring.dll`.
+
+  Targets to keep straight: **`library` (and its 1.0 consumers) is PHP 7.2+**, while
+  **`worker2` / `_underscore` enforce 8.1** — a helper shared between the two must satisfy 7.2.
 
 ## Change history
 
+- 2026-08-12 — Sharpened the 7.2 lint gotcha into a real verification procedure: the default CLI is
+  PHP 8.x, so `php -l` there proves nothing; use an actual 7.2 binary, add `-n` if its `php.ini` is
+  broken, and re-add mbstring via `-d extension_dir=… -d extension=php_mbstring.dll` when `-n`
+  drops it. Recorded the split targets (library 7.2+, worker2/_underscore 8.1). (snaredla)
+
 - 2026-08-03 — Documented the static no-DB 1.0 harness technique, built for TRUE-79401
   (`test/@Mark/AIG/test_multi_email.php`, 12 cases, PHP 7.2.33). Key enabler recorded:
   `App_Database::sqlEscape()` is a pure `str_replace` (the `mysqli_real_escape_string` path is

package/knowledge/1.0/apps/togadesk/workflows/standalone-test-scripts.md

@@ -44,6 +44,22 @@ web stack. Example harness: `C:\WWW\test\@Mark\TOGaDeskSupport\test_derive_custo
   output-buffer wrap (step 6).
 - Scripts should stay read-only against shared/mirrored data unless explicitly doing a data
   fix.
+- **A desk method that calls `isOwner()` will REDIRECT AND EXIT under CLI unless you seed the
+  session globals.** `isOwner()` reads the `$isAdmin` / `$liu` globals and, when they are absent,
+  emits a `header('Location: …')` + `exit` — from a CLI harness that looks like the script simply
+  stopping with no output and no error. Seed both globals before calling in
+  (`$isAdmin`, `$liu` with at least `id`/`clientid`). **Be explicit about what that means:** the
+  harness then tests everything *after* the permission gate — it does **not** test the gate itself,
+  so a permission regression will pass. Hit while harnessing
+  `Ticket::createEliteServiceRequest()` (see the
+  [Elite desk Service Request feature](../../../clients/elite/features/togadesk-service-request-intake.md)).
+- **Lint/run with the right PHP.** Desk + library code targets **7.2**, and the default CLI on a dev
+  box is 8.x — see the
+  [7.2 verification procedure](../../test/features/static-no-db-regression-harness.md).
 
 ## Change history
+- 2026-08-12 — Added the `isOwner()` CLI trap: a desk method that calls it redirects + exits when
+  `$isAdmin`/`$liu` are unset, which reads as "the script did nothing"; seed the globals, and record
+  that doing so means the harness covers everything **after** the permission gate but not the gate.
+  Also cross-linked the PHP 7.2 verification procedure. (snaredla)
 - 2026-06-12 — captured from deriveCustomerId test harness work (mhammontree)

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

@@ -10,6 +10,7 @@
 | [_ApiRequest — JSON encode/decode & api-logging behavior](features/apirequest-json-content-type.md) | `_ApiRequest` is the 2.0 outbound HTTP client. | _underscore/ApiRequest.php |
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [Asynchronous Query Execution (writes-only, via Worker)](features/async-query-execution.md) | `_Query` can run a **write** query asynchronously so a long/slow write does not hold a request-scoped DB connection open long enough to hit **"MySQL server has | _underscore/Query.php, worker2/Worker/Infrastructure/Database.php, worker2/Worker/Team/Transcripts.php |
+| [FIELD_SQL calculated fields — the underscore-prefix + same-name-method contract](features/calculated-sql-fields.md) | A `FIELD_SQL` (calculated) field on a `_Model` is bound by a **two-part contract that `_Model` enforces by throwing at model-construction time**, not by convent | _underscore/Model.php |
 | [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 | test/@Mark/true-80824-fedex-inflate-test.php, dbchanges2/Client_Growrk/2026-08-10e - GrowrkUpsServiceMethodCodes.sql, _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 |

package/knowledge/2.0/apps/_underscore/features/calculated-sql-fields.md

@@ -0,0 +1,71 @@
+---
+title: FIELD_SQL calculated fields — the underscore-prefix + same-name-method contract
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-08-12
+owners: [snaredla]
+files:
+  - _underscore/Model.php
+related:
+  - ../architecture.md
+  - ./model-magic-field-access.md
+---
+
+## Summary
+
+A `FIELD_SQL` (calculated) field on a `_Model` is bound by a **two-part contract that `_Model`
+enforces by throwing at model-construction time**, not by convention:
+
+1. the field name **must** begin with `_`;
+2. a **`public static` method of the EXACT same name** must exist on the model.
+
+Both are checked in `_underscore/Model.php` (~L130 and ~L132) while the field definitions are
+parsed, so a violation is not a lint smell — the model is simply unusable.
+
+## How it works
+
+```php
+public $_serialNumbers = [self::FIELD_SQL, self::FIELDOPT_SQL_TYPE => self::FIELD_CHAR];
+
+public static function _serialNumbers(string $table = self::TABLE) {
+    return "(SELECT … FROM … WHERE …)";
+}
+```
+
+The name must match exactly because the expression is invoked **by variable method name**
+(`_underscore/Model.php:641`):
+
+```php
+$value = '(' . get_called_class()::$field($this::TABLE) . ')';
+```
+
+`$field` is the property name, so there is no mapping layer, no camelCase conversion and no
+fallback — `_serialNumbers` the property requires `_serialNumbers()` the method.
+
+Options: `FIELDOPT_SQL_TYPE` (defaults to `FIELD_CHAR`) and `FIELDOPT_SQL_STORED` (default `false`,
+recalculated per query; `true` persists to a real column on save).
+
+## Gotchas / known issues
+
+- **The leading underscore is REQUIRED — it is not a camelCase-standard violation.** The TOGA
+  naming standard says database/class fields are camelCase, and a reviewer (human or agent) will
+  reflexively flag `_serialNumbers` and "fix" it to `serialNumbers`. Doing so **throws**:
+  *"All field which are of the type 'FIELD_SQL' must begin with an underscore"*. Calculated fields
+  are the documented exception; leave the underscore alone.
+- **Renaming a calculated field is a two-line change.** Rename the property without renaming the
+  static method (or vice versa) and construction throws with *"A function returning a SQL
+  expression has not been defined…"*.
+- **`FIELDOPT_SQL_STORED => true` needs a refresh after bulk migrations** — the stored value is
+  written on save, so rows changed by raw SQL keep a stale value.
+
+## Change history
+
+- 2026-08-12 — Documented the enforced `FIELD_SQL` contract after `_serialNumbers` was queried as a
+  camelCase violation: `_Model` **throws** both when the field lacks the `_` prefix
+  (`_underscore/Model.php` ~L130) and when a static method of the exact same name is missing
+  (~L132), because the expression is invoked as `get_called_class()::$field($this::TABLE)` (L641).
+  The underscore prefix is therefore required, not stylistic. (snaredla)

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
-| [API Payload Interceptors (metadata-registered prePost/postPut model hooks)](features/api-payload-interceptors.md) | A `_Model`'s `prePost()` / `postPost()` / `prePut()` / `postPut()` hooks are **not** called by the model. | api2/Component/Api/V2/V2.php, api2/Controller/Index.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderItem.php, dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql |
+| [API Payload Interceptors (metadata-registered prePost/postPut model hooks)](features/api-payload-interceptors.md) | A `_Model`'s `prePost()` / `postPost()` / `prePut()` / `postPut()` hooks are **not** called by the model. | api2/Component/Api/V2/V2.php, api2/Controller/Index.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/ServiceRequest.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderItem.php, dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Core/2026-08-06a - Service request and sales order payload interceptors.sql |
 | [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | A single authenticated V2 GET listing can return records across **many** clients (designed for 1000+) that the caller is entitled to, honoring **each target cli | api2/Component/Api/CrossClient/CrossClient.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, _underscore/Model/Cache/Table.php, _underscore/Model/Cache/Tables/Client.php, _underscore/Model/Core/Record.php, worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Cache/2026-06-30a - MultiClientCacheTables.sql, dbchanges2/Core/2026-06-30b - CacheClusterRegistrationAndRecordTtl.sql, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
 | [Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)](features/encrypted-user-uuid-auth-handoff.md) | `POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**: given an encrypted `{client, user}` UUID pair, it mints a fr | api2/Component/Api/CrossClient/CrossClient.php |
 | [ENVIRONMENT (not the EB environment name) decides the _underscore branch and Config file](features/environment-variable-drives-underscore-branch.md) | An api2 Elastic Beanstalk instance decides **which `_underscore` branch it clones** and **which `Config/<env>.ini` it loads** from the EB environment property * | api2/.ebextensions/git.php, api2/.ebextensions/php_include_underscore.config, api2/.ebextensions/git.sandbox-dev.json, api2/Config/beta.ini, api2/Config/sandbox-dev.ini, api2/Component/Api/V2/V2.php |

package/knowledge/2.0/apps/api2/features/api-payload-interceptors.md

@@ -6,16 +6,18 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-11
-owners: ["mhammontree", "dfranks", "bala"]
+updated: 2026-08-12
+owners: ["mhammontree", "dfranks", "bala", "snaredla"]
 files:
   - api2/Component/Api/V2/V2.php
   - api2/Controller/Index.php
   - _underscore/Model/Client/ItemFulfillment.php
   - _underscore/Model/Elite/SalesOrder.php
+  - _underscore/Model/Elite/ServiceRequest.php
   - _underscore/Model/Compass/SalesOrder.php
   - _underscore/Model/Compass/SalesOrderItem.php
   - dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql
+  - dbchanges2/Core/2026-08-06a - Service request and sales order payload interceptors.sql
 related:
   - ./record-scripts.md
   - ../architecture.md
@@ -70,6 +72,13 @@ and prod — so a validation added to `_Model_Compass_PurchaseOrder::prePost` ca
 tenant's other APIs at all. See
 [Compass MITS PO → SO Item Linking](../../../clients/compass-usa/features/mits-po-to-so-item-linking.md).
 
+**One client / all APIs is the `Core` table with `clientId` set and `apiId` NULL** — it does not
+have to live in `Client_<X>.ApiPayloadInterceptors`. Elite's service-request and sales-order rows
+were registered that way in `Core` (`clientId 41`, `apiId NULL`, `minDepth 1`, records **35**
+`service-requests` and **14** `sales-orders`) — see
+[Elite SalesOrder → NetSuite push](../../../clients/elite/features/salesorder-netsuite-push.md).
+**So "this client has no interceptors" is only true after you have checked BOTH tables.**
+
 ## The interceptor sees payload keys **verbatim** (no `c_` stripping, no rename)
 
 **Verified empirically** by a live HTTP probe against local dev
@@ -90,6 +99,25 @@ tenant's other APIs at all. See
 > result above is authoritative; the code path is misleading. Anyone tempted to reason it out
 > from V2.php will reach the wrong answer.
 
+### In a POST-processing interceptor, `$payload` is the RECORD — not a route-keyed envelope
+
+A `postPost` / `postPut` hook receives **the record object itself, or an array of record objects**.
+It is **not** wrapped under a route key, because api2 wraps the response into
+`{ salesOrders: … }` **after** the post-processing interceptors have run. So the correct read is:
+
+```php
+$record = (is_array($payload) ? ($payload[0] ?? null) : $payload);
+$uuid   = (string)($record->uuid ?? '');
+```
+
+Two consequences worth internalising:
+
+- **Never reassign `$payload` to the single record you pulled out.** `$payload` is by reference; a
+  multi-record response would lose everything after the first. Read into a local variable.
+- Reaching for `$payload->salesOrders` (the HTTP-response shape) yields `null` and the hook
+  silently does nothing — the same class of failure as the `internalApiRequest` `data`-envelope
+  trap below.
+
 ## The dispatch is UNGUARDED — a row naming a method that does not exist hard-fatals the endpoint
 
 The derived name (step 2 above) is **pure convention with nothing validating it**, and there is
@@ -147,6 +175,16 @@ when `$outData` is non-null**, and a **successful DELETE always sets `$outData =
 `(recordId, POST, DELETE)` row is dead on arrival: the method is never called, and — exactly like
 the missing-row case — there is no error and no log line to tell you.
 
+**The same `if ($outData)` guard (~L5932) is why an interceptor problem is scoped, not global.**
+The whole post-processing block is skipped whenever there is no response data, and it only ever
+resolves a class for the record the request actually touched. So a *missing* row, or a model with
+no such method, cannot break unrelated traffic. This was checked under fire: during a "this will
+break production" alarm, **254 live PUTs kept returning 200** while the suspect record had no
+usable hook. The alarm was wrong. What *is* fatal is narrower and precise: a row that resolves to
+a class which does not define the derived method — *"Call to undefined method"* — for **that**
+record's writes only. Precedent for the cleanup:
+`dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql`.
+
 **Therefore any logic that must react to a deletion runs in `preDelete`, and must exclude the row
 that is about to disappear**, because at `preDelete` time it is still present. The Compass line
 renumberer takes the id explicitly for this reason:
@@ -169,6 +207,17 @@ The chain is `_Model_Compass_Usa_X extends _Model_Compass_X extends _Model_Clien
 defined on the shared Compass base is inherited by both the Usa and Canada subclasses** — a
 per-region subclass does *not* need its own copy. Do not add duplicate hooks per region.
 
+**⚠ …and by the same inheritance, a hook on the shared `_Model_Client_X` runs for EVERY tenant that
+has a row for that record.** Client-specific behaviour must go on `_Model_<Client>_X`, never on
+`_Model_Client_X`. Worked near-miss (Elite, 2026-08-12): putting the NetSuite push on
+`_Model_Client_SalesOrder::postPost` would have pushed **Compass and Quad** sales orders to NetSuite
+too — both subclasses call `parent::postPost()`, and Compass has an active `recordId 14` interceptor
+row. The behaviour was placed on `_Model_Elite_SalesOrder` / `_Model_Elite_ServiceRequest` instead.
+
+The corollary is that **reading the client subclass is not enough to know who a hook affects** —
+you must also read the parent chain *and* the interceptor rows of every tenant that overrides the
+same record.
+
 ### `Core.Records` facts for interceptor debugging
 
 - **`Core.Records.model` is UNIQUE** — exactly one record row per model class, so an interceptor's
@@ -286,6 +335,12 @@ and the failing environment**. It is a small table, and the drift is usually exa
   change that switches on a *code* path; if the PHP defining the method is not confirmed deployed to
   that environment, the row takes the endpoint down. Insert inactive, verify the deploy, then flip
   `isActive = 1` — and remember every environment activates independently.
+- **⚠ A post interceptor's `$payload` is the record, not a route-keyed envelope** — and it is
+  by-reference, so pull the record into a local instead of reassigning `$payload`.
+- **⚠ Client behaviour never goes on `_Model_Client_X`.** Every tenant with a row for that record
+  inherits it through `parent::` calls. Put it on `_Model_<Client>_X`.
+- **A client's rows may be in `Core` (with `clientId`), not in `Client_<X>`** — check both before
+  concluding a client has no interceptors.
 - **The method name is derived, so a typo'd enum silently misses.** A row with
   `prePostProcessing = 'PRE'`, `httpMethod = 'PUT'` resolves to `prePut`, not `prePost`; the engine
   will simply find no method and move on.
@@ -310,6 +365,23 @@ and the failing environment**. It is a small table, and the drift is usually exa
 
 ## Change history
 
+- 2026-08-12 — TRUE-80498/80501, from building the Elite service-request chain. (1) **A
+  post-processing `$payload` is the record itself (or an array of records), NOT wrapped in a route
+  key** — api2 applies the route envelope only *after* the post interceptors run, so
+  `$payload->salesOrders` is `null` and the hook silently no-ops; read into a local
+  (`is_array($payload) ? $payload[0] : $payload`) and never reassign the by-reference `$payload`,
+  which would drop every record after the first. (2) Recorded what the `if ($outData)` guard
+  (~L5932) actually buys: the post block is skipped when there is no response data and only
+  resolves the touched record's class, so a missing row or absent method **cannot** break unrelated
+  traffic — a "this will break prod" alarm was disproved by **254 live PUTs still returning 200**;
+  the fatal case remains narrow (a row resolving to a class without the derived method), with
+  `dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql` as the
+  cleanup precedent. (3) **A hook on the shared `_Model_Client_X` runs for every tenant with a row
+  for that record** — putting the Elite NetSuite push there would have pushed Compass and Quad
+  orders too (both call `parent::postPost()`, Compass has an active `recordId 14` row), so it went
+  on `_Model_Elite_*`. (4) **One-client/all-APIs registration lives in `Core` with `clientId` set
+  and `apiId NULL`** (Elite: `clientId 41`, records 35 + 14, `minDepth 1`) — "this client has no
+  interceptors" requires checking **both** tables. Line numbers are approximate. (snaredla)
 - 2026-08-11 — Three findings from the post-mortem of the `_Model_Compass_Usa_SalesOrderItem::postPost()`
   outage (investigation only, no code change). (1) **`postDelete` can never fire** — the
   post-processing block at `V2.php` ~L5692 runs only when `$outData` is non-null and a successful

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

@@ -35,6 +35,7 @@
 | [OneUptime Incident → ClickUp Task Sync (Monitor/Oneuptime/SyncIncidents)](features/oneuptime-incident-clickup-sync.md) | An internal/shared TOGA ops feature: worker2 polls the OneUptime API every 15 minutes for **currently-open** incidents and ensures a ClickUp task exists for eac | worker2/Component/Api/Oneuptime/Oneuptime.php, worker2/Worker/Monitor/Oneuptime.php, worker2/Config/production.ini, dbchanges2/Team/2026-08-10a - OneUptime Incident ClickUp Tasks.sql, dbchanges2/Core/2026-08-10b - OneUptime Incident Sync CronJob.sql, dbchanges2/Team/2026-08-12a - OneUptime Incident Tasks Closed Marker.sql |
 | [OneUptime push-metric monitors for 2.0 workers](features/oneuptime-worker2-monitoring.md) | A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from the 1.0 `App_SystemMonitor_Compass` monitors. | worker2/Worker/Monitor/Compass.php, worker2/Worker/Client/Compass.php, worker2/composer.json, _underscore/Cloud.php, worker2/Worker/Monitor/Operations.php |
 | [Platform Cache Cleanup (_Worker_Platform_Cache — Clean + Truncate)](features/platform-cache-cleanup.md) | `_Worker_Platform_Cache` owns maintenance of the shared **Cache** cluster that backs api2's [multi-client data retrieval](../../api2/features/cross-client-data- | worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
+| [Service Request → Sales Order → Purchase Order generation (Sync/ServiceRequest)](features/service-request-sales-order-generation.md) | `_Worker_Sync_ServiceRequest` turns a **Service Request into a Sales Order, and then into one Purchase Order per vendor**, for **any** tenant. | worker2/Worker/Sync/ServiceRequest.php, _underscore/Model/Elite/ServiceRequest.php, dbchanges2/Core/2026-08-06a - Service request and sales order payload interceptors.sql |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |
 | [Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)](features/talos-meeting-notes-integration.md) | How a **dev tool / agent consumes Talos (TOGa IQ)** to query the team meeting-notes corpus programmatically. | .claude/skills/plan-ticket/scripts/talos.js |
 | [Talos Pricing Automation (worker2 Cron — Usage Import, AWS Actuals, Margins, Profiles)](features/talos-pricing-automation.md) | The worker2 half of the **Talos Pricing Platform** (see the talos `pricing-cogs-model` and tools `talos-pricing-ui` docs for the other halves). | worker2/Worker/Talos/Pricing.php, worker2/Database/TalosPricingCrons.sql, dbchanges2/Team/2026-08-03a - TalosPricingTokenCostModel.sql, dbchanges2/Team/2026-08-03b - TalosInternalTenant.sql, dbchanges2/Team/2026-08-03c - TalosIntegrationCostFactor.sql, dbchanges2/Core/2026-08-03a - Talos pricing cron jobs.sql |

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -223,6 +223,24 @@ Debugging consequence: **no row means either "the caller never queued it" or "th
 and never consumed."** Those have completely different fixes. Distinguish them with the **SQS queue
 metrics**, not the database.
 
+## ⚠ Renaming an action is a CROSS-REPO rename — deploy both sides together
+
+The action name is a **string** held by the producers, not a symbol the compiler can check. Renaming
+a method in `worker2` without renaming every `runTask(action: '…')` string — which usually lives in
+**another repo** (`_underscore` models, api2 interceptor code, crons, `Core.CronJobs.action` rows) —
+makes the dispatcher target a name that no longer exists.
+
+**And the failure is silent.** Producers routinely wrap `runTask` in `try/catch` + `error_log` so a
+queue failure cannot fail the originating write, so the user's record saves, nothing downstream
+happens, and no error surfaces. Worked example: `GenerateSalesOrder` →
+`GenerateSalesOrderFromServiceRequest` spans `worker2/Worker/Sync/ServiceRequest.php` and the
+dispatch string in `_underscore/Model/Elite/ServiceRequest.php:44` — see the
+[Service Request → Sales Order generation](./service-request-sales-order-generation.md).
+
+Rules: rename **both sides in one PR and one deploy**; grep every repo for the old string (including
+`Core.CronJobs.action` and migrations) before merging; and treat it exactly like the
+`WorkerJobs.output` multi-producer column rename in [architecture.md](../architecture.md).
+
 ## Gotchas
 
 - Class must be **`abstract`** and methods **`public static`** or routing fails.
@@ -269,6 +287,13 @@ metrics**, not the database.
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-08-12 — Added **"renaming an action is a cross-repo rename"**: the action name is a string
+  held by the producer (usually an `_underscore` model, a cron row or a migration in another repo),
+  so renaming the worker method alone makes `runTask` dispatch to a name that no longer exists —
+  and because producers wrap `runTask` in try/catch + `error_log`, the whole downstream chain stops
+  **silently**. Rename both sides in one PR/deploy. Worked example: `GenerateSalesOrder` →
+  `GenerateSalesOrderFromServiceRequest` across worker2 and
+  `_underscore/Model/Elite/ServiceRequest.php:44`. (snaredla)
 - 2026-08-11 — Added the **nested-JSON-object → `stdClass` dispatch gotcha**: the dispatcher casts
   only the top level of `CronJobs.parameters` to an array before spreading as named args
   (`Controller/Index.php` ~L455/692), so a nested JSON object stays `stdClass` and a strict