toga-ai 1.0.567 → 1.0.569

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

@@ -34,6 +34,7 @@
 | [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | `_Model_Core_Page::meta()` is the **legacy** page-meta resolver behind `GET /pages/meta?slug=<slug>` — still the live path for `toga2-supply` and other pre-Surf | _underscore/Model/Core/Page.php, _underscore/Model/Client/TableView.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/Query.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, api2/Controller/Index.php |
 | [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona **names** in multiple languages by adding a per-language **sidecar** table `PersonaTranslations`, reusing the platform's existing metadata-driven | _underscore/Model/Client/PersonaTranslation.php, dbchanges2/Client/2026-07-22b - PersonaTranslations.sql, dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql, dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql, dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql, toga2-commerce/src/pages/Account/view/MySettingsView.tsx |
+| [Record Change Audit Log (Logs_<Client>.Record / RecordField) — reading a field's history](features/record-change-audit-log.md) | Every 2.0 client schema has a sibling **logs** schema `Logs_<Tenant>` (e.g. | _underscore/Model/Client/Logs/Record.php, _underscore/Model/Client/Logs/RecordField.php, _underscore/Model/Client/Logs/CustomRecordField.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [_String helpers — ASCII-safe HTML entity encoding (and the parseBetween trap)](features/string-html-entity-helpers.md) | `_String` is the 2.0 framework's static string utility class. | _underscore/String.php |
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Client_Compass/2026-07-15f - SalesOrderRecordActionsRemoveDeadConfigRuleOverrides.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php, api2/Component/Api/V2/V2.php |

package/knowledge/2.0/apps/_underscore/features/email-send-pipeline.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-05
+updated: 2026-08-13
 owners: ["bala", "tcox", "dfranks"]
 files:
   - _underscore/Email.php
@@ -52,6 +52,26 @@ SMTP** using PHPMailer, then flips each row to `SENT` or `FAILED`. So a 2.0 emai
 4. On success the row flips to `SENT`; on failure `retryCount` is incremented and the row is
    retried on subsequent runs until `MAX_RETRIES` (3), after which it is marked `FAILED`.
 
+### `send()` resolves the log database itself — from the clientIdentifier
+
+`send()` does not take a database name. It resolves `Logs_<Client>` by joining
+**`Core.Clients` → `Databases` → `DatabaseHosts`** for the current environment and region, and
+**throws unless exactly one row matches**. So the string passed to `setClientIdentifier()` must equal
+**`Core.Clients.clientIdentifier`** exactly — it is a lookup key, not a label.
+
+Verified in production, beta and dev: `Compass_Usa` → `Logs_Compass`, `Compass_Canada` →
+`Logs_CompassCanada` (note the identifier and the schema suffix are **not** the same string, so never
+derive one from the other).
+
+**Diagnosis order for a missing alert email**, in this order — each step tells you which side failed:
+
+1. **`Core.WorkerJobs`** — is there a row for the action? (Absent is ambiguous; see
+   [Creating Worker Actions](../../worker2/features/creating-worker-actions.md).)
+2. **`Logs_<Client>.Email`** — is there a `PENDING` row? If yes, `_Email::send()` worked and the
+   problem is transmission.
+3. **Does that row clear to `SENT`?** If it stays `PENDING`, the Send cron is not draining that
+   client's log DB.
+
 ## Gotchas / known issues
 
 - **It is a POLL, not an enqueue — and the docblock lies.** The comment at `_underscore/Email.php`
@@ -140,6 +160,13 @@ SMTP** using PHPMailer, then flips each row to `SENT` or `FAILED`. So a 2.0 emai
     for a hotfix.
 
 ## Change history
+- 2026-08-13 — Documented that **`send()` resolves the `Logs_<Client>` database itself** from the
+  client identifier (`Core.Clients` → `Databases` → `DatabaseHosts` for the environment + region) and
+  **throws unless exactly one row matches** — so `setClientIdentifier()` takes a lookup key that must
+  equal `Core.Clients.clientIdentifier`, not a display label (`Compass_Usa` → `Logs_Compass`,
+  `Compass_Canada` → `Logs_CompassCanada`; verified in prod, beta and dev). Added the three-step
+  diagnosis order for a missing alert (`Core.WorkerJobs` → a `PENDING` `Logs_<Client>.Email` row →
+  whether it clears), found while building the Compass PO-rejection alert. No code change. (bala)
 - 2026-08-05 — Corrected the model: this is a **poll**, not an enqueue — the `_Email::send()`
   docblock (~line 320) claiming it "enqueues a Worker 2 job" is **stale**; the Send action SELECTs
   `PENDING` rows per client. Recorded the consequence that a `PENDING` row written from a **local**

package/knowledge/2.0/apps/_underscore/features/record-change-audit-log.md

@@ -0,0 +1,121 @@
+---
+title: Record Change Audit Log (Logs_<Client>.Record / RecordField) — reading a field's history
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-08-13
+owners: [bala]
+files:
+  - _underscore/Model/Client/Logs/Record.php
+  - _underscore/Model/Client/Logs/RecordField.php
+  - _underscore/Model/Client/Logs/CustomRecordField.php
+related:
+  - ../../api2/features/request-logging.md
+  - ../../../../clients/compass-usa/features/approval-decision-flow.md
+---
+
+## Summary
+
+Every 2.0 client schema has a sibling **logs** schema `Logs_<Tenant>` (e.g. `Logs_Compass`) whose
+`Record` / `RecordField` tables are the platform's **field-level change audit trail**. Together they
+answer "who changed this field, to what, and when" for *any* model — which makes them the primary
+forensic tool when a record is in a state nobody can explain.
+
+The single most useful property: **a change made outside the API leaves a `Record` row's field
+children empty — or no row at all.** That absence is how you distinguish a direct SQL edit from an
+in-app change, which is usually the first fork in any "how did this record get like this?"
+investigation.
+
+This is the **model-write** audit log. It is a different thing from the **request** log
+(`Logs_<Client>.Api` / core `Logs.Api`) documented in
+[V2 Request Logging](../../api2/features/request-logging.md) — that one records HTTP traffic; this
+one records the resulting field mutations.
+
+## Key files / entry points
+
+- **`_underscore/Model/Client/Logs/Record.php`** — `_Model_Client_Logs_Record`,
+  `DATABASE = DB_CLIENT_LOGS`, `TABLE = 'Record'`. Columns:
+  `id`, `uuid`, `recordId` (FK → `_Model_Core_Record`), `primaryKeyId`, `clientId`, `apiId`,
+  `userId`, `timestamp`, `note`.
+- **`_underscore/Model/Client/Logs/RecordField.php`** — `_Model_Client_Logs_RecordField`,
+  `TABLE = 'RecordField'`. Columns: `id`, `uuid`, `logRecordId` (FK → `Record.id`),
+  `recordFieldId` (FK → `_Model_Core_RecordField`), `oldValue`, `newValue`. Also declares the
+  method constants `READ` / `ADD` / `EDIT` / `DELETE`.
+- `_Model_Client_Logs_Record::lookup(&$api, $route, $uuid)` — resolves a route + record uuid into
+  the record-logs read, i.e. the same lens the UI uses.
+
+## How it works
+
+### The two row shapes
+
+`Record` rows come in two distinct flavours, and reading them as one thing is a common mistake:
+
+1. **Field-change rows** — a `Record` row with one or more **`RecordField` children**. Each child
+   names the changed field (`recordFieldId` → `Core.RecordFields`) and carries `oldValue` /
+   `newValue`. This is a write that went **through the API/model layer**.
+2. **Milestone / note rows** — a `Record` row with a human-readable **`note`** and **no
+   `RecordField` children**. These are written deliberately by model interceptors to narrate
+   business events. Compass sales orders, for example, emit notes such as
+   `"Delegate manager assigned: <email>"`, `"Admin Approved"`, `"Manager Approved"`, and
+   `"Manager Approval Request Email sent to Manager (...)"`.
+
+### Reconstructing one record's history
+
+Scope by **model** and **primary key**:
+
+- `Record.recordId` is the **`Core.Records` id of the model**, not the row. Useful ids seen so far:
+  **`SalesOrders` = 14**, **`ApprovalDecisions` = 179**. Resolve others from `Core.Records`
+  (`route` / `model` columns) rather than guessing.
+- `Record.primaryKeyId` is the id of the row **in that model's table** (it is a foreign key to many
+  models, so it is meaningless without `recordId`).
+- Join `RecordField ON RecordField.logRecordId = Record.id` for the field-level detail, then
+  translate `recordFieldId` through `Core.RecordFields` to get the field name.
+
+Ordering by `Record.timestamp` for a fixed `(recordId, primaryKeyId)` gives the full narrative of a
+single record: the milestone notes are the chapter headings, the field changes are the detail.
+
+## Gotchas
+
+- **⚠ A change made by direct SQL leaves NO `RecordField` row.** Anything that bypasses the model
+  layer — a manual DB edit, a `dbchanges2` migration, or a worker that issues a raw
+  `_Query`/`UPDATE` — mutates the data without producing a field-change entry. So **absence of a
+  `RecordField` row is positive evidence that the change did not come through the app.** This is the
+  cleanest way to tell "someone edited the database" from "someone clicked a button", and it is
+  worth checking *before* hunting for a code path that could have produced the state.
+- **Therefore: a worker doing raw bulk updates is invisible here.** If a job needs its effects to be
+  auditable, it must write its own `Record` **note** row explicitly — it will get nothing
+  automatically. Real example:
+  [Compass PEOPLE-file user lifecycle](../../../../clients/compass-usa/features/people-file-user-lifecycle.md),
+  whose deactivation batch is a raw `UPDATE Users SET isActive = 0 WHERE id IN (...)`.
+- **⚠ `Logs_*` and `Core` are on different database clusters — you cannot join them in one query.**
+  `Record.recordId` → `Core.Records` and `RecordField.recordFieldId` → `Core.RecordFields` are
+  logical foreign keys across a cluster boundary. Resolve the `Core` ids in a **separate** query and
+  substitute the literals, or you will write a query that simply cannot run.
+- **`note` is free text, not an enum.** Milestone strings are written by interceptor code and can be
+  reworded by any change to that code. Match them with `LIKE` on a stable prefix, never on equality
+  with a full sentence, and treat their absence as weak evidence (the note may predate the code that
+  writes it).
+- **Do not paste logged values into tickets or the KB.** `oldValue`/`newValue` and note text
+  routinely contain user emails and other personal data. Reference the rows by location; quote the
+  mechanism, not the people.
+
+## Change history
+
+- 2026-08-13 — Documented the `Logs_<Tenant>.Record` / `RecordField` field-change audit trail as its
+  own subject: the two row shapes (field-change rows with `RecordField` children vs. milestone rows
+  carrying only a `note`), scoping by `Record.recordId` = the **`Core.Records` model id**
+  (`SalesOrders` = 14, `ApprovalDecisions` = 179) plus `primaryKeyId`, and the two rules that make it
+  a diagnostic: **a write outside the model layer leaves no `RecordField` row** (so absence proves a
+  direct-SQL edit), and **`Logs_*` is on a different cluster from `Core`**, so the id lookups cannot
+  be joined in a single query. Generalized from a Compass manager-assignment investigation; no code
+  change. (bala)
+
+## Related docs
+
+- [V2 Request Logging & Where Requests Land](../../api2/features/request-logging.md) — the HTTP
+  request log, the other half of "what happened to this record".
+- [Compass Approval-Decision Flow](../../../../clients/compass-usa/features/approval-decision-flow.md)
+  — the investigation this technique was generalized from.

package/knowledge/2.0/apps/_underscore/features/string-html-entity-helpers.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-05
+updated: 2026-08-13
 owners: ["bala"]
 files:
   - _underscore/String.php
@@ -58,6 +58,12 @@ numbers.
 - **Prefer this helper over a raw `htmlentities()` call** in 2.0 email code. Existing call sites
   that use the bare 4-argument `htmlentities()` are correct for *named*-entity characters only;
   they leak U+202F-class characters.
+- **⚠ The explicit-flags trap applies identically to `htmlspecialchars()`.** Passing any flags
+  (e.g. `ENT_QUOTES`) **overrides** PHP 8.1's default `ENT_QUOTES | ENT_SUBSTITUTE`, so on invalid
+  UTF-8 the call returns an **empty string** and the field silently disappears. Always write
+  **`ENT_QUOTES | ENT_SUBSTITUTE`**. Scope of the risk: `json_decode` rejects malformed UTF-8, so an
+  inbound API payload cannot deliver a bad byte — but a **directly invoked or DB-scheduled worker**
+  can, which is exactly where an escaping helper tends to live.
 - **⚠ OPEN BUG — `parseBetween()` throws whenever it is called case-sensitively with an ending
   string.** Two named arguments are wrong for `strpos()`, whose first parameter is `$haystack`,
   not `$string`:
@@ -73,6 +79,11 @@ numbers.
 
 ## Change history
 
+- 2026-08-13 — Recorded that the **explicit-flags / `ENT_SUBSTITUTE` trap is identical for
+  `htmlspecialchars()`** (passing flags drops PHP 8.1's default, so invalid UTF-8 returns an empty
+  string and the field vanishes), and scoped the exposure: `json_decode` rejects malformed UTF-8 so an
+  inbound API payload cannot carry it, but a directly invoked or DB-scheduled **worker** can. Surfaced
+  writing the Compass PO-rejection email escaper. (bala)
 - 2026-08-05 — Added `_String::encodeToAsciiHtmlEntities()`: `htmlentities` with
   `ENT_QUOTES | ENT_SUBSTITUTE` / `double_encode: false`, then a `preg_replace_callback` numbering
   **every** remaining character above U+007F, because `htmlentities()` only converts characters

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/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 |
+| [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/Compass/PurchaseOrder.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,12 +6,13 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-12
+updated: 2026-08-13
 owners: ["mhammontree", "dfranks", "bala", "snaredla"]
 files:
   - api2/Component/Api/V2/V2.php
   - api2/Controller/Index.php
   - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Model/Compass/PurchaseOrder.php
   - _underscore/Model/Elite/SalesOrder.php
   - _underscore/Model/Elite/ServiceRequest.php
   - _underscore/Model/Compass/SalesOrder.php
@@ -72,6 +73,24 @@ 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).
 
+The lookup predicate is **`apiId IS NULL OR apiId = <the caller's api>`**, so a row with a concrete
+`apiId` scopes the hook to exactly that one API and a row with `apiId NULL` opens it to all of them.
+
+**Worked example, verified in prod *and* dev-sandbox (2026-08-13):** `Core.ApiPayloadInterceptors`
+has **no row at all** for `recordId 17` (`purchase-orders`), while **both** Compass tenants carry
+their own `PRE` + `POST` rows in their client DB — `Client_Compass` and
+`Client_CompassCanada`, `isActive = 1`, `apiId = 2` (which is *MITS Service Hub* in Compass and
+*MITS Compass Canada* in Canada; the id happens to match, the name does not). Two consequences:
+
+- A guard in `_Model_Compass_PurchaseOrder::prePost` **cannot fire for the Agilant api (id 1)** —
+  the api the 1.0 worker ODP/EDI crons authenticate as (`App_Api_Toga2::API_UUID_COMPASS`). Their
+  header-only POs, which carry no `purchaseOrderItems` key at all, are structurally unreachable from
+  that hook. See
+  [Compass MITS PO zero-line-item rejection](../../../clients/compass-usa/features/mits-po-zero-line-item-rejection.md).
+- **A new sub-client tenant of an existing client family inherits the PHP but not the rows.** Add a
+  Compass sub-client and its interceptors never fire until someone inserts rows into *its* client DB
+  — silently, with no error.
+
 **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**
@@ -337,6 +356,19 @@ and the failing environment**. It is a small table, and the drift is usually exa
   `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`.
+- **⚠ Validate that a payload ARRAY's elements are objects before touching them — `property_exists()`
+  THROWS.** `property_exists()` raises a `TypeError` when argument 1 is an `array`, `int`, `null` or
+  `bool` (a *string* merely returns `false`). So a `foreach` over e.g. `$payload->purchaseOrderItems`
+  that calls `property_exists($item, …)` turns a malformed payload into an **HTTP 500** where the
+  interceptor was supposed to answer **400**. Reject non-array containers and non-object elements
+  **first**, with a plain `_Exception_Validation` (a sender coding fault is not a business condition —
+  it should not raise an Issue or page anyone). Worked example:
+  [Compass MITS PO zero-line-item rejection](../../../clients/compass-usa/features/mits-po-zero-line-item-rejection.md).
+- **⚠ A throw from a PRE interceptor leaves NO `Logs_<Client>.Api` row.** The transaction log is
+  written near the END of `_Component_Api_V2::execute()` (~L2225-2271), *after* route processing
+  (~L1742-2043), so an exception raised from `prePost` never reaches it and the rejected request
+  looks like it never arrived. See
+  [V2 request logging](./request-logging.md#-a-throw-from-a-pre-interceptor-leaves-no-api-log-row-at-all).
 - **⚠ 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
@@ -365,6 +397,18 @@ and the failing environment**. It is a small table, and the drift is usually exa
 
 ## Change history
 
+- 2026-08-13 — TRUE-80412, from building the Compass zero-line-item PO guard. (1) Recorded the
+  lookup predicate — **`apiId IS NULL OR apiId = <caller's api>`** — and the verified row set for
+  `recordId 17` (`purchase-orders`): **no `Core` row at all**, and a `PRE` + `POST` pair in **each**
+  Compass tenant's own client DB (`isActive = 1`, `apiId = 2` = *MITS Service Hub* in Compass,
+  *MITS Compass Canada* in Canada), identical in prod and dev-sandbox. So a guard in
+  `_Model_Compass_PurchaseOrder::prePost` **cannot fire for the Agilant api (id 1)** that the 1.0
+  ODP/EDI crons authenticate as, and **a new sub-client tenant inherits the PHP but not the rows** —
+  silently. (2) Added the **`property_exists()` `TypeError`** gotcha: it throws on an array/int/null/
+  bool argument, so a payload-element loop must reject non-object elements first or a malformed
+  payload 500s where the interceptor meant to answer 400. (3) Cross-linked the finding that a throw
+  from a **pre** interceptor leaves **no `Logs_<Client>.Api` row** (the log write sits near the end of
+  `execute()`, after route processing). (bala)
 - 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

package/knowledge/2.0/apps/api2/features/request-logging.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-11
+updated: 2026-08-13
 owners: ["mhammontree", "dfranks", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -56,12 +56,45 @@ transaction. A rejection therefore still writes a **full `Client_Logs.Api` / `Co
 row** — request payload, response payload, `apiId`, `sourceIp`, `transactionId` — while the
 business row is discarded.
 
-So a 400 **is** SQL-queryable and attributable to the calling credential. What a 400 lacks is a
-`Logs.Issue` row: **no alerting, no aggregation, no owner** (see
+So a 400 **is** SQL-queryable and attributable to the calling credential — **provided the request
+got far enough to be logged at all** (see the pre-interceptor exception below, which is the common
+case for a rejection and does **not** produce a row). What a 400 lacks is a `Logs.Issue` row:
+**no alerting, no aggregation, no owner** (see
 [Error Reporting — Issue/Event Capture](../../_underscore/features/error-reporting-issue-event.md)).
-That is the deciding factor when choosing between `_Exception_Validation` (400, logged as a
-request, no Issue) and `_Exception_Business` (500, Sentry + a routed Issue). Do **not** reach for
-`_Exception_Business` merely to "make sure the rejection is recorded" — it already is.
+That is the deciding factor when choosing between `_Exception_Validation` (400, no Issue) and
+`_Exception_Business` (**4xx** since 2026-08-04 — it extends `_Exception_Validation` — plus Sentry
+and a routed Issue).
+
+### ⚠ A throw from a PRE interceptor leaves NO Api-log row at all
+
+`_Component_Api_V2::execute()` writes the inbound transaction log **near its END**
+(`api2/Component/Api/V2/V2.php` ~L2225-2271), *after* the route processing that dispatches the
+interceptors (~L1742-2043). An exception raised from a `prePost` hook therefore unwinds straight to
+the outer `catch` in `api2/Controller/Index.php` and **skips the log write entirely** — the
+commit-the-logs / roll-back-the-data contract above has nothing to commit.
+
+**Symptom, and it is deeply misleading:** the caller gets a 400 whose envelope has
+`transactionId`, `timestamp`, `authority` and `audience` **all null**, `error` `EV-1`, and the real
+explanation buried in **`messages[0].identifiers.message`**. Meanwhile `Logs_<Client>.Api` and core
+`Logs.Api` contain **nothing** — so a deliberately rejected request is indistinguishable from a
+request that never arrived. This cost hours of wrong diagnosis on 2026-08-12.
+
+**Consequences:**
+
+- **The only durable record of an interceptor rejection is the `Logs.Issue` row** written by
+  `_Error::captureException` — which exists only if you threw `_Exception_Business` (a plain
+  `_Exception_Validation` raises no Issue, so that rejection leaves **no trace anywhere**).
+- **Never conclude "MITS/ServiceNow never posted" from an empty Api log** when the endpoint has a
+  validating pre-interceptor. Check `Logs.Issue` / `Logs.Event` first.
+- This applies to **every** pre-interceptor rejection on the platform, including Prudential's REQ
+  rejections and the Compass zero-line-item PO guard — which is why both of those alert through a
+  **worker-dispatched email**, not through the log.
+  See [Compass MITS PO zero-line-item rejection](../../../clients/compass-usa/features/mits-po-zero-line-item-rejection.md)
+  and [Prudential REQ rejection alert](../../../clients/prudential/features/service-request-rejection-alert-email.md).
+
+Do **not** reach for `_Exception_Business` merely to "make sure the rejection is recorded" — reach
+for it when the rejection is a **business condition someone must act on**, and accept that a plain
+validation rejection from an interceptor is genuinely unrecorded.
 
 ### ⚠ But an uncaught PHP **fatal** can leave NO log row anywhere
 
@@ -177,6 +210,16 @@ re-send.
 
 ## Change history
 
+- 2026-08-13 — **Important limit on the "an HTTP 400 leaves a full log row" rule** (TRUE-80412):
+  `execute()` writes the transaction log near its **end** (~L2225-2271), *after* route processing
+  (~L1742-2043), so **a throw from a PRE interceptor produces no `Logs.Api` row at all** — the
+  rejected request is indistinguishable from one that never arrived. Recorded the misleading
+  response shape (null `transactionId`/`timestamp`/`authority`/`audience`, `EV-1`, real text inside
+  `messages[0].identifiers.message`) and that the **`Logs.Issue`** row is then the only durable
+  record — which a plain `_Exception_Validation` does not create, leaving that rejection with no
+  trace anywhere. This cost hours of wrong diagnosis. Also corrected a stale line that still called
+  `_Exception_Business` a **500**; it has answered **4xx** since it began extending
+  `_Exception_Validation` on 2026-08-04. No code change. (bala)
 - 2026-08-11 — Documented how **apiproxy's cross-region 5xx retry distorts both logs**, found while
   reading prod 500s for Compass: one user action writes up to **six** near-identical core `Logs.Api`
   500 rows sharing a single `transactionId` (~2 s apart, alternating `instanceId`), so occurrence

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-13
 owners: [jcardinal, dfranks, mhammontree, tcox, bala]
 files:
   - worker2/Worker/
@@ -39,6 +39,11 @@ Lambda code changes are needed** — you just create the PHP file.
    (`$class::$method(...$parameters)`), which PHP binds as **named arguments** — so each method
    parameter name *is* the queue's parameter contract. Do **not** collapse a multi-param action
    into a single `array` argument: named-argument dispatch then has no key to bind to and breaks.
+   Two corollaries of named binding: a `parameters` key with **no matching parameter** is a **fatal
+   `Error: Unknown named parameter`**, and a parameter you declare **required** (no default) makes an
+   omission a loud `ArgumentCountError` instead of a silent default — which is what you want for
+   anything that selects a **tenant**, since a defaulted client identifier mis-attributes work to the
+   wrong client and nothing errors.
 3. **Return** — return `string`; `json_encode()` structured data.
 4. **`initialize()`** — optional `public static function initialize()` the framework calls
    automatically before any method in the class (register DB connections / shared setup).
@@ -223,6 +228,27 @@ 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.
 
+#### Telling "the tier stopped consuming" apart WITHOUT SQS metrics
+
+There is a database-side tell, because cron rows keep arriving from the scheduler even while nothing
+completes. Query `Core.WorkerJobs` for the environment and compare **created vs. completed** for the
+day:
+
+- **Healthy** — completions track creations, and the newest `dtCompleted` is minutes old.
+- **Dead tier** — a large created count with almost nothing completed, and the **last routine
+  completion hours in the past**. Measured on **dev-sandbox, 2026-08-12**: **1,548 jobs created that
+  day, 1,547 never completed**, last routine completion **2026-08-11 16:00**, while per-minute cron
+  rows kept accumulating.
+
+Two things follow, and both have misled people:
+
+- **A stalled tier produces no error anywhere.** Your own SQS-dispatched job yields *no `WorkerJobs`
+  row at all* (the row is written on consumption), so it reads exactly like "the caller never
+  queued it" — and if you conclude that, you go and debug working code.
+- **⚠ Backlogged messages fire RETROACTIVELY when the tier recovers.** A test you gave up on hours
+  ago will run — and send its email — later. Never assume a queued side effect is dead just because
+  it didn't happen; on an alerting action that means a real recipient gets a stale alert.
+
 ## ⚠ 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
@@ -287,6 +313,17 @@ Rules: rename **both sides in one PR and one deploy**; grep every repo for the o
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-08-13 — Added a **database-side test for "the tier stopped consuming"**, which resolves the
+  absent-`WorkerJobs`-row ambiguity without SQS metrics: compare created vs. completed
+  `Core.WorkerJobs` for the day — on dev-sandbox 2026-08-12, **1,548 created / 1,547 never
+  completed**, last routine completion 2026-08-11 16:00, while per-minute cron rows kept
+  accumulating. Recorded that a stalled tier is **indistinguishable from "never queued"** (no error
+  anywhere, because the row is written on consumption) and that **backlogged SQS messages fire
+  retroactively on recovery**, so an abandoned test can send its email hours later. Also noted two
+  corollaries of named-argument dispatch: an unmatched `parameters` key is a fatal
+  *Unknown named parameter*, and a **required** parameter is the right way to make a tenant selector
+  fail loudly (`ArgumentCountError`) instead of defaulting to the wrong client. Surfaced building the
+  Compass PO-rejection alert action. (bala)
 - 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 —

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 17 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 22 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 23 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 12 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
@@ -18,8 +18,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 56 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 48 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 58 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **worker2** (Worker) — 49 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 23 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 8 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 6 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/knowledge/clients/compass-usa/INDEX.md

@@ -2,22 +2,25 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [Compass Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) | 2.0 | Compass's sales-order approval flow — approval/notification email lists, **manager reassignment**, VIP auto-approve, and EN/FR localization — lives **entirely i | _underscore/Model/Compass/ApprovalDecision.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Usa/ApprovalDecision.php, _underscore/Model/Compass/Canada/ApprovalDecision.php |
+| [Compass Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) | 2.0 | Compass's sales-order approval flow — approval/notification email lists, **manager reassignment**, VIP auto-approve, and EN/FR localization — lives **entirely i | _underscore/Model/Compass/ApprovalDecision.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Usa/ApprovalDecision.php, _underscore/Model/Compass/Canada/ApprovalDecision.php, _underscore/Model/Client/ApprovalTemplateStage.php |
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/PurchaseOrder.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql, dbchanges2/Client_Compass/2026-06-16 - CleanupSA132763CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16b - CleanupSA132743CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16c - BackfillSA132763C40QYUCTracking.sql, dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql, dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Cost Centers — Unit Locations, numeric-only policy](features/cost-centers.md) | 2.0 | A Compass "cost center" — the value a user picks in commerce and that lands on an order — is **not** a `CostCenters` row. | toga2-commerce/src/pages/Cart/api/CartApi.ts, worker1.5/crons/toga2/compass/import_locations.php, _underscore/Model/Compass/SalesOrder.php, api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-06 - RemoveNonNumericCostCenters.sql |
 | [Compass isFulfillable — Data Quality & the Type-Derived Rule](features/isfulfillable-data-quality-and-type-rule.md) | 2.0 | A **prod-data investigation (2026-08-12, read-only)** into why so many Compass storefront lines still have a dead **Qty Fulfilled** cell. | _underscore/Model/Client/Item.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php, toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx |
 | [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql, dbchanges2/Client/2026-07-15a - ExcludeFeeItemsFromItemFulfillmentsForSalesOrdersView.sql |
 | [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Compass MITS PO Transmission to Vendors](features/mits-po-transmission-to-vendors.md) | 2.0 | The 1.0 worker cron `2_transmit_mits_purchase_orders_to_vendors.php` transmits Compass PurchaseOrders to their vendors (Office Depot, Strategic Systems, Compass | worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compasscanada/workflow/2_transmit_mits_purchase_orders_to_vendors.php, library/app/client/compass.php |
+| [Compass MITS PO rejection — zero line items (400 + Issue + PM alert email)](features/mits-po-zero-line-item-rejection.md) | 2.0 | MITS transmits Compass purchase orders that carry **`"purchaseOrderItems": []`** (real example: PO `50309196-1`, `mitsSalesOrder` `MR244630`). | _underscore/Model/Compass/PurchaseOrder.php, _underscore/Model/Compass/Usa/PurchaseOrder.php, _underscore/Model/Compass/Canada/PurchaseOrder.php, worker2/Worker/Client/Compass/reports/PurchaseOrderRejectionEmail.php |
 | [Compass MITS Sales-Order Transmission — Rejection Alerting (Issue/Event, not email-in-cron)](features/mits-sales-order-transmission-alerting.md) | 2.0 | When MITS **rejects** a Compass sales order transmitted by the 1.0 cron `1_transmit_compass_sales_orders_to_mits.php`, the alert is no longer an email built ins | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker2/Worker/Infrastructure/Errors.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/IssueEmailAddress.php, dbchanges2/Logs/2026-08-04a - MITS rejection business recipients.sql |
 | [Compass MR/MA Order Auto-Approval & Status Gate](features/mr-ma-order-approval-and-status.md) | 2.0 | Compass **MR** and **MA** sales orders are system-generated from the MITS / Office Depot EDI pipeline (they do not originate as user-entered SA orders) and must | _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
+| [Compass Office Depot EDI 855 Acknowledgement + Over-Quantity PO Guard](features/odp-edi-855-acknowledgement-and-overquantity-guard.md) | 1.0 | How Compass acknowledges Office Depot (ODP) inbound **EDI 850** purchase orders with an **X12 855**, and the **over-quantity guard** that rejects a duplicate PO | worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/4_transmit_office_depot_po_acknowledgements.php, library/app/edi.php |
+| [Compass PEOPLE-File User Lifecycle (duplicate accounts, reactivation grace window, raw-SQL deactivation)](features/people-file-user-lifecycle.md) | 2.0 | The nightly **PEOPLE** file cron (`_Worker_Client_Compass_PeopleFile`, `worker2/Worker/Client/Compass/PeopleFile.php`) owns the whole `Users` row lifecycle for | worker2/Worker/Client/Compass/PeopleFile.php |
 | [Persona Model & Levy-Sector Gating (worker2 PEOPLE cron)](features/persona-model-and-levy-gating.md) | 2.0 | Compass USA catalogue visibility is driven by **personas** in `Client_Compass`. | worker2/Worker/Client/Compass/PeopleFile.php |
 | [Compass Sales-Order Line-Number Renumbering (and why it hangs off the SO hooks)](features/sales-order-line-renumbering.md) | 2.0 | Compass sales-order lines must stay numbered **1..N with no gaps** after any add, edit, or delete — downstream MITS/PO linking reads `lineNumber` as an identity | _underscore/Model/Compass/SalesOrderItem.php, _underscore/Model/Compass/SalesOrder.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
 | [Compass Cross-Kit Bundle Corruption — Detection & Repair](workflows/cross-kit-bundle-corruption.md) | 2.0 | A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle (kit) line items and **fees/warranties** to the **wrong kit**, pe | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
 | [Compass Office Depot Duplicate PO-Line Cleanup (dual-catalog SKU)](workflows/odp-duplicate-po-line-cleanup.md) | 1.0 | The NetSuite fulfillment-sales-order importer duplicated Office Depot purchase-order lines on Compass USA because it reconciled the fulfillment SO against the e | library/app/api/toga2.php, dbchanges2/Client_Compass/2026-07-22a - CleanupOfficeDepotDuplicatePurchaseOrderItems.sql |
 | [Recovering a Lost Compass ODP EDI 850 Import (re-drop from Logs.FileLog)](workflows/odp-edi-import-recovery.md) | 1.0 | How to recover a Compass **Office Depot EDI 850** import that failed partway — the case where cron **3a** created the ODP SalesOrder header, the follow-up item | worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, worker/schedules/cron.worker.sync.json |
-| [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, worker/schedules/cron.worker.sync.json, library/app/client/compass.php |
+| [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/4_transmit_office_depot_po_acknowledgements.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, worker/schedules/cron.worker.sync.json, library/app/client/compass.php |
 | [Compass Order Lifecycle & Data-Integrity Invariants](workflows/order-lifecycle-and-data-integrity.md) | 2.0 | End-to-end map of how a Compass order flows through the `Client_Compass` (2.0) database and the **expected raw-data shape** at each link/ASN/IF level. |  |
 | [Comparing Compass Persona/Catalogue Effects across prod and dev-sandbox](workflows/persona-population-env-comparison.md) | 2.0 | How to prove what a persona/catalogue change actually does to **100% of Compass USA users**, by diffing production against dev-sandbox. | test/@Bala/generate_persona_test_data.py, test/@Bala/persona-refactor-full-user-export.sql, test/@Bala/TRUE-75705-persona-refactor-test-plan.md |
 | [Compass USA Persona Refactor — 8-Phase Migration & Deploy Order (TRUE-75705)](workflows/persona-refactor-migration.md) | 2.0 | Splits Compass USA's catch-all persona **1 ("All")** into **Base** (the six printer bundles, held by *everyone* including Levy) and a new **Non-Levy** persona ( | dbchanges2/Client_Compass/2026-08-06 - PersonaRefactor.sql, dbchanges2/Client_Compass/2026-08-06 - PersonaRefactor-Verification.sql, worker2/Worker/Client/Compass/PeopleFile.php, test/@Bala/TRUE-75705-persona-refactor-test-plan.md |