toga-ai 1.0.333 → 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

@@ -9,6 +9,7 @@
 | [ClickUp GitHub-tab Auto-linking & Ticket-id Branch Naming](features/clickup-github-autolink.md) | How ClickUp surfaces branches/PRs/commits in a ticket's **GitHub tab**, and the branch / PR-title naming convention that triggers it. |  |
 | [ClickUp Project & Opportunity Multi-List Routing](features/clickup-project-routing.md) | Routes ClickUp tasks into the correct **secondary multi-list memberships** based on their custom-field values, via the `clickup` webhook. | worker2/Worker/Clickup/Project.php, worker2/Worker/Clickup.php |
 | [ClickUp Rich-Text Custom Fields via Quill Delta (API)](features/clickup-richtext-api.md) | ClickUp custom text fields (type `text` and long-text) support rich formatting only through a **Quill Delta** written to the undocumented `value_richtext` key o | test/@dave/clickup_md2delta.js, .claude/skills/plan-ticket/scripts/clickup.js |
+| [ClickUp Subtask Activity → Parent Opportunity/Epic Comments](features/clickup-subtask-activity.md) | Surfaces **subtask** progress, completion, and discussion on the top-level **Opportunity** or **Epic** it rolls up to, so a deal/project owner sees activity whe | worker2/Worker/Clickup/Subtask.php, worker2/Worker/Clickup.php, dbchanges2/Team/2026-07-14a - Add ClickupSubtaskActivity ledger.sql |
 | [ClickUp Work Type Automation (Committed / Conditional / Stretch)](features/clickup-work-type-automation.md) | The ClickUp webhook handler (`_Worker_Clickup`) automatically maintains each task's **Work Type** custom field — `Committed`, `Conditional`, or `Stretch` — base | worker2/Worker/Clickup.php, worker2/Tests/Worker/ClickupWorkTypeTest.php |
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
@@ -20,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/clickup-project-routing.md

@@ -15,6 +15,7 @@ related:
   - ../architecture.md
   - ./creating-worker-actions.md
   - ./clickup-connectivity-watchdog.md
+  - ./clickup-subtask-activity.md
 ---
 
 ## Summary
@@ -78,8 +79,11 @@ ids are discovered. Configure via the `DiscoverTaskTypes()` / `DiscoverIds()` ac
 2. Each handler fetches task details via `_Worker_Clickup::getTaskDetails()` (a per-invocation
    `static` cache shared across all handlers in one job), then guards on **space id** and
    **top-level** (`parent` empty). The three routing handlers identify Epics/tasks
-   **structurally** (space + top-level). Custom **Task Types are now configured**, and the
-   newer `enforceHubPlacement` guard keys on `custom_item_id` to recognize Epics/Opportunities.
+   **structurally** (space + top-level). The `enforceHubPlacement` guard was written to key on
+   `custom_item_id`, but the Task-Types ClickApp is **not reliably enabled** on the hub spaces
+   and `TASK_TYPE_EPIC_ID` / `TASK_TYPE_OPPORTUNITY_ID` remain `null` — so that guard is
+   effectively **inert** in practice; structural (space + top-level) identification is what
+   actually runs (see Gotchas, and `./clickup-subtask-activity.md`).
 3. Custom fields are read by name via `extractCustomFields()` (one pass, last-non-null-wins,
    trimmed) → mapped to a target list id → reconciled by `applyMultiListPlacement()`:
    POST the target if absent, DELETE every other in-scope list (DELETE failures are caught
@@ -160,6 +164,7 @@ Read-only / setup actions, invoked via `curl -X POST https://worker.togahub.com/
 `RESULT: PASS`), `RegisterOpportunityWebhook` and `RegisterHubGuardWebhooks` (one-time setup).
 
 ## Change history
+- 2026-07-14 — Correction: `TASK_TYPE_EPIC_ID` / `TASK_TYPE_OPPORTUNITY_ID` are still `null` and the Task-Types ClickApp is not reliably enabled on the hub spaces, so `enforceHubPlacement`'s custom-Task-Type keying is inert; structural (space + top-level) identification is what actually runs. Cross-linked the new subtask-activity feature (same hub spaces/pipeline). (ajean)
 - 2026-06-23 — Added the hub-placement guard (`enforceHubPlacement` on `taskCreated`/`taskMoved`): re-anchors misplaced Epics/Opportunities to their hub by custom Task Type + home space, backfills Business Unit/Project Category, and notifies. Added `DiscoverTaskTypes`, `RegisterHubGuardWebhooks`, `TestHubGuardMappings`. Corrected the earlier "Task Types not enabled" note. (ajean)
 - 2026-06-09 — Documented ClickUp secondary multi-list routing (hybrid native-automation + worker design, three space handlers, self-trigger guard). (jcardinal)
 

package/knowledge/2.0/apps/worker2/features/clickup-subtask-activity.md

@@ -0,0 +1,117 @@
+---
+title: ClickUp Subtask Activity → Parent Opportunity/Epic Comments
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: draft
+updated: 2026-07-14
+owners: [ajean]
+files:
+  - worker2/Worker/Clickup/Subtask.php
+  - worker2/Worker/Clickup.php
+  - dbchanges2/Team/2026-07-14a - Add ClickupSubtaskActivity ledger.sql
+related:
+  - ./clickup-project-routing.md
+  - ../architecture.md
+---
+
+## Summary
+
+Surfaces **subtask** progress, completion, and discussion on the top-level **Opportunity**
+or **Epic** it rolls up to, so a deal/project owner sees activity where they actually look.
+On a `clickup` webhook for a subtask (a task with a non-empty `parent`) of event
+`taskStatusUpdated` or `taskCommentPosted`, the worker walks the parent chain to the
+top-level ancestor and, if that ancestor is an Opportunity (Opportunity/RFP Hub space
+`90113928591`) or an Epic (Project Hub space `90113939341`), posts **one** comment on the
+ancestor. Implemented in `_Worker_Clickup_Subtask` (extends `_Worker_Clickup`), fanned out
+from a pre-switch block in `_Worker_Clickup::Webhook()`.
+
+> **Status: not yet deployed / not live-verified.** PRs open: worker2 #110, dbchanges2 #427.
+> The dbchanges2 migration must run **before or with** the worker deploy (the worker reserves
+> a ledger row before every post).
+
+## Key files / entry points
+
+- `worker2/Worker/Clickup/Subtask.php` — `_Worker_Clickup_Subtask` (NEW), all subtask
+  fan-out / ancestor-walk / dedup / post logic.
+- `worker2/Worker/Clickup.php` — a **pre-switch fan-out block** in `_Worker_Clickup::Webhook()`
+  detects a subtask event and dispatches `_Worker::runTask('Clickup/Subtask/Process',
+  ['taskId', 'event', 'data' => history_items])`. The block is wrapped in a best-effort
+  `try/catch (Throwable)` and **deliberately does not `return`** — it falls through to the
+  existing `taskStatusUpdated` / `taskCommentPosted` switch, so sprint / work-type handling is
+  unaffected.
+- `dbchanges2/Team/2026-07-14a - Add ClickupSubtaskActivity ledger.sql` (NEW) — creates the
+  `ClickUpSubtaskActivity` dedup ledger table in the **Team** DB.
+
+## How it works
+
+1. Webhook arrives → `_Worker_Clickup::Webhook()`. The pre-switch block short-circuits **early
+   on the subtask's own space** before any parent walk (a subtask lives in the same space as its
+   ancestor, so a non-hub space is discarded before spending API calls).
+2. `Clickup/Subtask/Process` walks up the `parent` chain to the top-level (no-parent) ancestor
+   and confirms it is an Opportunity or Epic **structurally** — by home space id + top-level —
+   mirroring `handleEpicUpdate` / `handleOpportunityUpdate`. **Not** by custom Task Type: the
+   Task-Types ClickApp is not reliably enabled on the hub spaces (see Gotchas).
+3. Triggers:
+   - **Status** — post when the subtask status moves into `in progress`, `roadblocked`, or
+     `on hold` (matched by **lowercase status name**, consistent with existing status
+     comparisons in `Worker/Clickup.php`), OR into any completed status (matched by **status
+     TYPE** in `done`/`closed` via the inherited `COMPLETE_STATUS_TYPES`).
+   - **Comment** — any user comment posted on the subtask is mirrored to the ancestor as
+     `"💬 <author> commented on subtask …"`.
+4. Every post carries a trailing `(automated)` marker. Comments that already carry that marker
+   are **never** mirrored (loop guard).
+5. Posts use `_Component_Api_Clickup::send('POST', '/task/{id}/comment',
+   ['comment_text' => …, 'notify_all' => false])`; task lookups reuse
+   `_Worker_Clickup::getTaskDetails()` (in-process static cache);
+   `_Worker_Clickup_Project::RATE_LIMIT_DELAY_US` paces the parent walk.
+
+### Dedup ledger (the authoritative guard)
+
+Before posting, the worker **reserves a ledger row** (`INSERT` into `ClickUpSubtaskActivity`)
+so the `UNIQUE(subtaskId, activityKey)` constraint — not a check-then-act window — is the
+authoritative dedup guard against re-delivered webhooks. If the comment POST fails, the row is
+**released** (`DELETE`) so a retry can re-attempt. The `activityKey` is:
+- `status:<name>` for a watched named status,
+- `status:completed` for a completion,
+- `comment:<clickupCommentId>` for a mirrored comment — falling back to the history-item id,
+  then a per-event date, then `md5(text)`, so identical comment texts stay distinct.
+
+Ledger access follows the `ClickUpHealthState` pattern from `_Worker_Clickup_Health`: raw
+`_Query` on `_underscore::DB_TEAM` with `_Database::escape()`.
+
+## Data model
+
+`ClickUpSubtaskActivity` in the **Team** DB (dbchanges2 migration `2026-07-14a`):
+`id`, `uuid`, `subtaskId VARCHAR(32)`, `activityKey VARCHAR(255)`, `dtPosted`, with
+`UNIQUE(subtaskId, activityKey)`. All other state lives in ClickUp.
+
+## Client variations
+
+None — internal automation for Agilant's ClickUp workspace, uniform across clients.
+
+## Gotchas / known issues
+
+- **Ancestor identification is STRUCTURAL, not by Task Type.** The Task-Types ClickApp is not
+  reliably enabled on the hub spaces, and `_Worker_Clickup_Project`'s `TASK_TYPE_EPIC_ID` /
+  `TASK_TYPE_OPPORTUNITY_ID` remain `null` (inert). Identify Opportunities/Epics by home space
+  id + top-level, exactly like the routing handlers — do not rely on `custom_item_id` here.
+- **Completion matches by status TYPE (`done`/`closed`), not name** — it survives label
+  changes. The other watched statuses match by lowercase **name** (`in progress`,
+  `roadblocked`, `on hold`).
+- **Loop guard is the `(automated)` marker** — every automated post carries it, and any comment
+  carrying it is skipped on mirror. Removing/altering the marker text re-opens the mirror loop.
+- **Fan-out never returns** — it falls through to the existing switch on purpose; keep it that
+  way or existing sprint/work-type handling breaks.
+- **Migration ordering** — deploy the dbchanges2 `2026-07-14a` migration before/with the worker;
+  the worker reserves a ledger row on every post and will error without the table.
+
+## Change history
+- 2026-07-14 — Created (draft, not yet deployed): subtask status/completion/comment mirroring to the parent Opportunity/Epic via `_Worker_Clickup_Subtask`, guarded by the `ClickUpSubtaskActivity` UNIQUE-key dedup ledger. PRs worker2 #110 / dbchanges2 #427. (ajean)
+
+## Related docs
+
+- [ClickUp Project & Opportunity Multi-List Routing](./clickup-project-routing.md) — same hub spaces, same webhook pipeline, same structural identification.
+- [Worker (worker2) Architecture](../architecture.md) — always-HTTP-200, commit-before-SQS worker contract.

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,8 +17,8 @@ _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)
-- **worker2** (Worker) — 28 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/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)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.333",
+  "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",