toga-ai 1.0.334 → 1.0.335

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

@@ -6,6 +6,7 @@
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql |
 | [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php |
+| [_ApiRequest ENCODE__JSON now sends Content-Type: application/json](features/apirequest-json-content-type.md) | `_ApiRequest::execute()`'s `ENCODE__JSON` branch json-encoded the request body but never set a `Content-Type` header. | _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 |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |

package/knowledge/2.0/apps/_underscore/features/apirequest-json-content-type.md

@@ -0,0 +1,39 @@
+---
+title: _ApiRequest ENCODE__JSON now sends Content-Type: application/json
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-14
+owners: ["jcardinal"]
+files:
+  - _underscore/ApiRequest.php
+related:
+  - ../../worker2/features/oneuptime-worker2-monitoring.md
+---
+
+## Summary
+`_ApiRequest::execute()`'s `ENCODE__JSON` branch json-encoded the request body but never set
+a `Content-Type` header. cURL therefore defaulted to `application/x-www-form-urlencoded`, and
+receivers parsed the entire JSON string as a single form-field NAME — observed at OneUptime as
+`{"<json>":""}`. Every 2.0 `ENCODE__JSON` POST/PUT/PATCH caller was silently shipping
+form-urlencoded bodies.
+
+## How it works
+The `ENCODE__JSON` branch now adds `Content-Type: application/json`. It is guarded by a
+case-insensitive scan of already-set headers, so a caller-supplied `Content-Type` still wins
+(no override). All other encodings are unaffected.
+
+## Gotchas / known issues
+- This changes the wire format of ALL existing `ENCODE__JSON` callers (they were previously
+  sending form-urlencoded). This is a correction, but smoke-test heavy JSON callers post-deploy:
+  ClickUp, NetSuite, Vapi.
+
+## Change history
+- 2026-07-14 — Fixed `ENCODE__JSON` to send `Content-Type: application/json` (guarded so a
+  caller-set Content-Type wins). Root-caused via OneUptime receiving `{"<json>":""}`. Affects
+  all 2.0 ENCODE__JSON callers. (jcardinal)
+</content>
+</invoke>

package/knowledge/2.0/apps/_underscore/features/cloud-s3-helpers.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-13
+updated: 2026-07-14
 owners: ["jcardinal"]
 files:
   - _underscore/Cloud.php
@@ -22,7 +22,7 @@ workers or app code. Alongside the existing copy / get / delete methods it now h
 
 ## Key files / entry points
 
-- `_underscore/Cloud.php` — `_Cloud::getS3Objects($s3BucketName, $s3BucketPath = '')`.
+- `_underscore/Cloud.php` — `_Cloud::getS3Objects($s3BucketName, $s3BucketPath = '', ?string $awsRegion = null)`.
 
 ## How it works
 
@@ -33,10 +33,18 @@ workers or app code. Alongside the existing copy / get / delete methods it now h
 - `LastModified` — ISO-8601 string
 - `Size`
 
-The method is **purely additive** — no existing `_Cloud` method signature changed. Keeping
-S3 listing here (rather than instantiating `S3Client` in a worker) is the reason to prefer
+The method is **additive** — the optional 3rd param `?string $awsRegion = null` falls back
+to `_Config::cloud('aws_region')`, so existing 2-arg callers are unchanged. Keeping S3
+listing here (rather than instantiating `S3Client` in a worker) is the reason to prefer
 this helper over ad-hoc SDK calls.
 
+### Per-bucket region override
+
+The config-default region is **us-east-1**. Buckets in another region must pass
+`$awsRegion` explicitly or the SDK throws `AuthorizationHeaderMalformed`. Notably the
+**`agilant-as2`** bucket lives in **us-west-2** — the worker2 Office Depot S3 monitors pass
+`'us-west-2'`.
+
 First consumer: the worker2 Office Depot EDI backlog monitor — see
 [OneUptime push-metric monitors](../../worker2/features/oneuptime-worker2-monitoring.md).
 
@@ -48,7 +56,12 @@ None — shared core helper.
 
 - Callers get every matching key regardless of count; pagination is handled internally, so
   do not add your own `ContinuationToken` loop on top.
+- A bucket outside the config-default us-east-1 (e.g. `agilant-as2` in us-west-2) throws
+  `AuthorizationHeaderMalformed` unless you pass `$awsRegion`.
 
 ## Change history
+- 2026-07-14 — `getS3Objects()` gained an optional `?string $awsRegion = null` 3rd param
+  (falls back to `_Config::cloud('aws_region')`); needed because `agilant-as2` is in
+  us-west-2, not the config-default us-east-1. Additive — 2-arg callers unchanged. (jcardinal)
 - 2026-07-13 — Added `_Cloud::getS3Objects()` S3 LIST helper (paginated `listObjectsV2`,
   returns `{Key, LastModified, Size}`); additive, no existing signatures changed. (jcardinal)

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

@@ -21,7 +21,7 @@
 | [NetSuite Supporting-Record Webhook Importer (the reusable recipe)](features/netsuite-supporting-record-webhook-importer.md) | A single **repeatable recipe** for porting a legacy daily-pull NetSuite *supporting-record* importer (the lookup/dimension tables behind Forecast2 — Employees, | worker2/Worker/Netsuite/Employee.php, worker2/Worker/Netsuite/Account.php, worker2/Worker/Netsuite/Classification.php, worker2/Worker/Netsuite/Customer.php, worker2/Worker/Netsuite/Item.php, worker2/Worker/Netsuite.php, _underscore/Model/Forecast/Employee.php, _underscore/Model/Forecast/Account.php, _underscore/Model/Forecast/Classification.php, _underscore/Component/Forecast/Db/Db.php, test/@dave/test_employee_lifecycle.php, test/@dave/test_account_lifecycle.php, test/@dave/test_classification_lifecycle.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, worker/crons/toga2/forecast2/import_supporting_records.php |
 | [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, _underscore/Model/Client/EmailTemplate.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.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, _underscore/Cloud.php |
+| [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 |
 | [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 — AWS Actuals, Calibration, Monthly Report)](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 |

package/knowledge/2.0/apps/worker2/features/oneuptime-worker2-monitoring.md

@@ -6,10 +6,12 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-13
+updated: 2026-07-14
 owners: ["jcardinal"]
 files:
   - worker2/Worker/Monitor/Compass.php
+  - worker2/Worker/Client/Compass.php
+  - worker2/composer.json
   - _underscore/Cloud.php
 related:
   - ./monitoring-framework.md
@@ -22,10 +24,10 @@ related:
 A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from
 the 1.0 `App_SystemMonitor_Compass` monitors. A worker2 cron action runs a self-contained
 check, decides pass/fail itself, and POSTs a JSON metric body to a OneUptime "Incoming
-Request" monitor — replacing the 1.0 tier's email alerts. First monitor:
-`_Worker_Monitor_Compass::OfficeDepotEdiImportQueue()`, which watches the Office Depot
-inbound EDI import backlog. Designed to be **client-agnostic** — a reusable template for
-future monitors and clients.
+Request" monitor — replacing the 1.0 tier's email alerts. The class is
+`abstract class _Worker_Monitor_Compass` and now carries a **suite of 9 monitors** covering
+the Compass USA / Office Depot integration (S3, DB, and mailbox checks). Designed to be
+**client-agnostic** — a reusable template for future monitors and clients.
 
 This is distinct from the DB-driven email-orchestrator
 [Monitoring Framework](./monitoring-framework.md) (`_Worker_Monitor` orchestrator +
@@ -37,92 +39,159 @@ that reports straight to OneUptime. Note the folder difference: these live under
 ## Key files / entry points
 
 - `worker2/Worker/Monitor/Compass.php` — `abstract class _Worker_Monitor_Compass`; each
-  monitor is a `public static` action method returning a summary string recorded in
-  `WorkerJobs` (standard worker2 action conventions). First method:
-  `OfficeDepotEdiImportQueue()`.
-- `_underscore/Cloud.php` — `_Cloud::getS3Objects()` list helper this monitor relies on
+  monitor is a `public static` action method dispatched via a `Core.CronJobs` action
+  `Monitor/Compass/<Method>` and returning a summary string recorded in `WorkerJobs`
+  (standard worker2 action conventions). `initialize()` registers the Compass client DB by
+  delegating to `_Worker_Client_Compass::initialize()` (not per-method).
+- `worker2/Worker/Client/Compass.php` — `_Worker_Client_Compass`; owns the Compass id
+  constants and the `DB_CLIENT_COMPASS` connection name the monitors query against.
+- `_underscore/Cloud.php` — `_Cloud::getS3Objects()` list helper the S3 monitors rely on
   (see [Cloud S3 helpers](../../_underscore/features/cloud-s3-helpers.md)).
 
-## How it works
-
-Registered as a `Core.CronJobs` entry: schedule `*/5 6-20 * * *`, action
-`Monitor/Compass/OfficeDepotEdiImportQueue`. Each tick, `OfficeDepotEdiImportQueue()`:
+## The 9 monitors
+
+Each measures one Compass/Office Depot integration metric and pushes a decided alarm token.
+- **OfficeDepotEdiImportQueue** (S3) — counts files >10 min old in
+  `s3://agilant-as2/OfficeDepot/`, excluding `OUTBOX/`, `SENT/` and directory placeholders.
+- **CompassSalesOrderTransmission** (DB) — approved SOs (both approval stages) with
+  `c_dtTransmittedToCompass` NULL (not yet transmitted to MITS).
+- **CompassIncomingPurchaseOrders** (DB) — `SA%` SOs transmitted to MITS >4h ago (on/after
+  the 2026-04-30 cutoff) with no PO returned.
+- **CompassPurchaseOrderTransmissionsToVendors** (DB) — unsubmitted POs for monitored
+  vendors (Office Depot, Strategic Systems, Compass, Presidio) due today or earlier.
+- **EmailedAsnImport** (mailbox) — counts inbox messages in the emailed-ASN mailbox via
+  IMAP XOAUTH2 (see mailbox decision below).
+- **OfficeDepotPoAcknowledgements** (DB) — Office Depot POs with `dtAcknowledged` NULL
+  through the OD→Compass PO/SO chain.
+- **OfficeDepotNetsuiteIntegration** (DB) — OD SOs not in NetSuite
+  (`c_dtTransmittedToNetsuite` NULL) with a 30-min PO-grace subquery.
+- **OfficeDepotAsnExport** (DB) — OD orders whose ASN not sent (ItemFulfillments with
+  `c_dtEdi856Sent` NULL + a tracking number, on/after the 2025-02-04 cutover). Covers all
+  order types (SA/MR/MA) via ItemFulfillments/tracking-number logic. (The 1.0 monitor
+  TRUE-75101 in `library/app/systemmonitor/compass.php` was intentionally NOT ported — its
+  logic is superseded by this corrected definition.)
+- **OfficeDepotAs2Outbox** (S3) — counts ONLY top-level files in
+  `s3://agilant-as2/OfficeDepot/OUTBOX/` (skips subfolders + directory placeholders).
 
-1. Lists `s3://agilant-as2/OfficeDepot/` via `_Cloud::getS3Objects()`, then counts files
-   older than `AGED_FILE_MINUTES` (10), **excluding** the `OUTBOX/` and `SENT/` sub-prefixes
-   and directory-placeholder keys.
-2. Decides the alarm state itself and POSTs a JSON metric body to the OneUptime "Incoming
-   Request" monitor via `_ApiRequest` — with **logging disabled** and
-   **`throwExceptionsOnFailure` disabled**, so a failed ping never fails the worker job.
-3. On S3 failure it still POSTs `{"status":"error"}` so a blind/dead checker is
-   distinguishable from a real backlog.
+## How it works
 
-Body tokens (see the alarm contract below): `"alarm":"HIGH"` when the aged-file count is
-over threshold, else `"alarm":"OK"`; `"status":"error"` on S3 failure.
+Each monitor is a self-contained method: per-monitor config as `ALL_CAPS` local variables
+(PHP disallows `const` at function scope), plus a `$push` closure using `_ApiRequest` — all
+inside the method, so the class scales cleanly as monitors accumulate. The metric POST runs
+with **logging disabled** and **`throwExceptionsOnFailure` disabled**, so a failed ping
+never fails the worker job.
 
-### The token-based alarm contract (critical — OneUptime cannot compare numbers)
+### Payload contract & OneUptime criteria (critical — OneUptime cannot compare numbers)
 
 OneUptime **Incoming Request** monitors **cannot** do numeric threshold comparison on a
-pushed body. Verified in OneUptime source (`Common/Server/.../IncomingRequestCriteria.ts`):
-a `checkOn: "Request Body"` filter supports only `Contains` / `NotContains` **string**
-matching — it does **not** JSON-parse the body, does **not** target a nested key, and does
-**not** support Greater Than / Less Than (those filter types apply only to
-outgoing/synthetic checks like Response Time / Status Code / Metric Value).
-
-Consequence: the "dumb reporter, smart monitor" ideal (push a raw number, let OneUptime
-compare `> threshold`) is **not achievable for push monitors**. Instead the **worker makes
-the threshold decision** and emits a string token that OneUptime matches with `Contains`.
-OneUptime criteria for this monitor:
+pushed body (`checkOn: "Request Body"` supports only `Contains` / `NotContains` **string**
+matching — no JSON parse, no nested-key targeting, no Greater/Less Than). So the **worker
+makes the threshold decision** and emits a string token OneUptime matches with `Contains`.
 
+Payload body: `{status:"reporting"|"error", alarm:"HIGH"|"OK", <metric fields>, checkedAtUtc}`.
+OneUptime criteria:
 - Request Body **Contains** `"alarm":"HIGH"` → Offline + incident.
-- Request Body **Contains** `"status":"error"` → Offline + incident.
-- **Online** requires BOTH "received in 1 min" AND Request Body **Contains** `"alarm":"OK"`
-  — so status does not flap back to Operational while the alarm is still HIGH.
+- Request Body **Contains** `"status":"error"` → Offline + incident (distinguishes a
+  blind/dead checker from a real backlog).
+- **not received in 10 min** → Degraded.
+- **received in 1 min AND Contains `"alarm":"OK"`** → Online (the OK-gated recovery
+  prevents flapping back to Operational while the alarm is still HIGH).
+- **not received in 15 min** → Offline.
 
 ### Heartbeat / cron cadence timing
 
-Heartbeat missed-ping thresholds must match the cron cadence. With a **5-minute** push
-cadence: **Degraded at 10 min / Offline at 15 min**. An initial 3/5-min setting
-false-alarmed on a single missed ping. The Office Depot backlog alarm threshold is
-**10 aged files**.
+The 10-min-Degraded / 15-min-Offline heartbeat thresholds pair with a **5-minute** cron
+cadence. An initial 3/5-min setting false-alarmed on a single missed ping.
 
 ## Provisioning a monitor (runbook)
 
-1. Write the monitor method on `_Worker_Monitor_Compass` (or a new `_Worker_Monitor_<X>`
-   class). Keep it **fully self-contained**: no private helpers, no class constants — all
-   per-monitor config lives as `ALL_CAPS` local variables inside the method (PHP disallows
-   `const` at function scope), so the class stays clean as monitors accumulate.
-2. Provision the OneUptime monitor by cloning the reusable import/export template at
-   `monitor-import-OfficeDepot-EDI-1.0.json` (a local dev artifact, not a repo file) and
-   importing it into OneUptime; wire the Contains criteria above.
-3. Register the OneUptime push URL as a local/constant in the monitor method — it is a
+1. Write the monitor method on `_Worker_Monitor_Compass` (or a new `_Worker_Monitor_<X>`),
+   fully self-contained per above.
+2. Set the OneUptime heartbeat URL as an in-file constant/local in the method — it is a
    **push credential**; never log it and never record its value in a doc.
-4. Add the `Core.CronJobs` row (`action = 'Monitor/<Class>/<Method>'`) with the schedule,
-   and set OneUptime's Degraded/Offline thresholds to match the cadence.
+3. Provision the OneUptime monitor by importing the monitor's OneUptime resource-export
+   JSON (authored under a local staging dir, e.g. `d:\STAGE` — these are import artifacts,
+   not repo files) and wiring the Contains criteria above.
+4. Add the `Core.CronJobs` row: `action = 'Monitor/Compass/<Method>'`, schedule
+   `*/5 * * * *`, `maxExecutionTime` 120s, `parameters` NULL. Then deploy worker2.
+
+### CronJob scheduling for these monitors
+
+Run **all hours**, `*/5 * * * *` (every 5 min) — **not** the 1.0 `6-20` business-hours
+window. Integration backlogs must be caught outside business hours too.
+
+## DB monitor conventions
+
+- Query via `new _Query($sql, _Worker_Client_Compass::DB_CLIENT_COMPASS)`.
+- `_Query::fetchRow()` returns an **OBJECT** (`$row->pendingCount`), not an array.
+- The client DB connection is registered by the class `initialize()` hook (delegating to
+  `_Worker_Client_Compass::initialize()`), not per method.
+- All Compass id constants live on **`_Worker_Client_Compass`** (VENDOR_ID__*,
+  CUSTOMER_ID__*, UUID_*, DB_CLIENT_COMPASS) — moved out of the 1.0 `App_Client_Compass`.
+  Never reference `App_Client_Compass` from worker2 (see gotcha below).
+
+## Mailbox monitoring (EmailedAsnImport) — IMAP XOAUTH2, not Graph
+
+Use **IMAP with XOAUTH2** via the `javanile/php-imap2` library (mirrors the 1.0 monitor),
+**not** Microsoft Graph. The Graph `messages/$count` approach returned HTTP 403 because the
+app lacks Graph `Mail.Read` application consent and Entra consent cannot be obtained. IMAP
+XOAUTH2 uses the app's existing `IMAP.AccessAsApp` permission (the 1.0 monitor already
+relies on it) — no new Entra consent.
+
+- OAuth token scope: `https://outlook.office365.com/.default`.
+- Then `imap2_open('{outlook.office365.com:993/imap/ssl/novalidate-cert}INBOX', $mailbox,
+  $accessToken, OP_XOAUTH2|OP_READONLY)` → `imap2_num_msg`.
+- Guarded by `function_exists('imap2_open')` so a missing library reports `status:error`
+  rather than throwing an uncatchable `Error`.
+- Requires the `[mailbox_compass_statuses]` config group (`tenant_id`, `client_id`,
+  `client_secret`, `mailbox`) in each `Config/*.ini`, and **ext-imap enabled** on the
+  worker EB tier. The `client_secret` is a credential — it lives in the ini config group,
+  never in a doc.
+
+## Composer / deploy dependency
+
+`worker2/composer.json` added `javanile/php-imap2` (`^0.1.10`) for the IMAP path. The
+`composer require` refreshed `composer.lock`, bumping in-range packages (sentry, aws-sdk,
+phpseclib, phpspreadsheet) and transitive majors (psr/log 1→3, symfony/options-resolver
+5.4→7.4, paragonie/constant_time_encoding 2→3). `composer audit` reported 16 advisories.
+**Review the lockfile diff + `composer audit` before a production deploy.**
 
 ## Client variations
 
-None — the pattern is shared infrastructure. The first monitor targets Compass USA's
-Office Depot inbound EDI (vendor ODP), but the class and template are client-agnostic;
-clone the template to provision the same check for another client.
+None — the pattern is shared infrastructure. This suite targets Compass USA's Office Depot
+integration, but the class and templates are client-agnostic; clone to provision the same
+check for another client.
 
 ## Gotchas / known issues
 
 - OneUptime Incoming Request bodies are matched **as strings only** (Contains/NotContains) —
   no numeric comparison, no JSON key targeting. Always emit a decided token, never a raw
   number, for push monitors.
-- The OneUptime push URL is a credential — keep it as a local/constant in the method; never
-  log it or write its value into knowledge docs.
+- The OneUptime push URL is a credential — keep it as an in-file constant in the method;
+  never log it or write its value into knowledge docs.
+- **`App_Client_Compass` (1.0) is unavailable in worker2.** Referencing it throws a
+  class-not-found `Error`, which `catch (Exception)` does NOT catch — the whole monitor
+  dies uncaught. Use `_Worker_Client_Compass::` constants only.
+- `_Query::fetchRow()` returns an object, not an array — access `$row->field`.
 - Keep the metric POST non-fatal (`throwExceptionsOnFailure` off) so a monitoring outage
   never breaks the worker job it rides in.
+- The `agilant-as2` S3 bucket is in **us-west-2**, not the config-default us-east-1 — S3
+  monitors must pass the region (see [Cloud S3 helpers](../../_underscore/features/cloud-s3-helpers.md)).
 
 ## Change history
+- 2026-07-14 — Grew `_Worker_Monitor_Compass` to a 9-monitor suite (S3/DB/mailbox);
+  finalized the payload contract (`status`/`alarm`/`checkedAtUtc`) and the not-received
+  10-min-Degraded / 15-min-Offline + OK-gated recovery criteria; standardized cron on
+  `*/5 * * * *` all-hours (120s); chose IMAP XOAUTH2 over Graph for the emailed-ASN mailbox
+  (Graph 403, no Entra consent); moved Compass id constants to `_Worker_Client_Compass` and
+  registered its DB via `initialize()`; added `javanile/php-imap2`. (jcardinal)
 - 2026-07-13 — Ported Compass monitoring from the 1.0 worker tier into worker2 reporting to
-  OneUptime; built `_Worker_Monitor_Compass::OfficeDepotEdiImportQueue()` (Office Depot EDI
-  backlog), the token-based alarm contract (OneUptime Incoming Request can only string-match
-  Contains, not compare numbers), and the 5-min cadence → 10/15-min heartbeat timing. (jcardinal)
+  OneUptime; built `OfficeDepotEdiImportQueue()`, the token-based alarm contract, and the
+  5-min cadence → 10/15-min heartbeat timing. (jcardinal)
 
 ## Related docs
 - [Monitoring Framework](./monitoring-framework.md) — the parallel DB-driven, email-alert monitoring pattern
 - [Cloud S3 helpers](../../_underscore/features/cloud-s3-helpers.md) — `_Cloud::getS3Objects()` used to list the EDI bucket
 - [OneUptime 1.0 worker uptime monitoring](../../../1.0/apps/worker/features/oneuptime-worker-uptime-monitoring.md) — the 1.0 push-heartbeat predecessor
+</content>
+</invoke>

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 31 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 32 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 29 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 10 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/package.json

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