toga-ai 1.0.325 → 1.0.326

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

@@ -9,6 +9,7 @@
 | [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 |
+| [_Cloud S3 helpers (copy / get / delete / list)](features/cloud-s3-helpers.md) | `_Cloud` centralizes AWS SDK S3 usage for the 2.0 stack so the `S3Client` never leaks into workers or app code. | _underscore/Cloud.php |
 | [_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps](features/component-model-namespace-registration.md) | Every **project-local** `_Component_*` and `_Model_*` class in a 2.0 app **must declare the project namespace** at the top of the file: ```php namespace <NAMESP | _underscore/Loader.php, worker2/_.php, api2/_.php, worker2/Component/Forecast/Db/Db.php, worker2/Component/Forecast/SaleImport/SaleImport.php, api2/Component/Api/Netsuite/Netsuite.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [Error Reporting — Issue/Event Aggregation (agreed POST-to-receiver design)](features/error-reporting-issue-event.md) | Platform-wide error-reporting infrastructure for TOGA 2.0, built around a two-table **Issue / Event** aggregation model in the shared **Core Logs DB**. | _underscore/Error.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, dbchanges2/Logs/2026-07-06 - Issue and Event tables.sql |

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

@@ -0,0 +1,54 @@
+---
+title: _Cloud S3 helpers (copy / get / delete / list)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-13
+owners: ["jcardinal"]
+files:
+  - _underscore/Cloud.php
+related:
+  - ../../worker2/features/oneuptime-worker2-monitoring.md
+---
+
+## Summary
+
+`_Cloud` centralizes AWS SDK S3 usage for the 2.0 stack so the `S3Client` never leaks into
+workers or app code. Alongside the existing copy / get / delete methods it now has a
+**LIST** method, `_Cloud::getS3Objects()`.
+
+## Key files / entry points
+
+- `_underscore/Cloud.php` — `_Cloud::getS3Objects($s3BucketName, $s3BucketPath = '')`.
+
+## How it works
+
+`getS3Objects()` uses the AWS SDK `S3Client->listObjectsV2` and **transparently paginates**
+(`listObjectsV2` caps at 1000 keys per page), returning entries shaped:
+
+- `Key` — object key
+- `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
+this helper over ad-hoc SDK calls.
+
+First consumer: the worker2 Office Depot EDI backlog monitor — see
+[OneUptime push-metric monitors](../../worker2/features/oneuptime-worker2-monitoring.md).
+
+## Client variations
+
+None — shared core helper.
+
+## Gotchas / known issues
+
+- Callers get every matching key regardless of count; pagination is handled internally, so
+  do not add your own `ContinuationToken` loop on top.
+
+## Change history
+- 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

@@ -20,6 +20,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 |
 | [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

@@ -0,0 +1,128 @@
+---
+title: OneUptime push-metric monitors for 2.0 workers
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-07-13
+owners: ["jcardinal"]
+files:
+  - worker2/Worker/Monitor/Compass.php
+  - _underscore/Cloud.php
+related:
+  - ./monitoring-framework.md
+  - ../../_underscore/features/cloud-s3-helpers.md
+  - ../../../1.0/apps/worker/features/oneuptime-worker-uptime-monitoring.md
+---
+
+## Summary
+
+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.
+
+This is distinct from the DB-driven email-orchestrator
+[Monitoring Framework](./monitoring-framework.md) (`_Worker_Monitor` orchestrator +
+`_Worker_Monitors_<Name>` children + `Core.Monitors` table, sends email). This pattern has
+**no orchestrator and no `Core.Monitors` table** — each monitor is a plain worker2 action
+that reports straight to OneUptime. Note the folder difference: these live under
+`Worker/Monitor/` (singular) vs. the framework's `Worker/Monitors/` (plural).
+
+## 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
+  (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()`:
+
+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.
+
+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.
+
+### The token-based alarm contract (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:
+
+- 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.
+
+### 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**.
+
+## 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
+   **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.
+
+## 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.
+
+## 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.
+- Keep the metric POST non-fatal (`throwExceptionsOnFailure` off) so a monitoring outage
+  never breaks the worker job it rides in.
+
+## Change history
+- 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)
+
+## 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

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)_ — 29 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 27 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **_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)
 - **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/knowledge/clients/compass-usa/profile.md

@@ -9,6 +9,7 @@ apps:
   - toga2-commerce
   - worker
   - worker1.5
+  - worker2
   - dbchanges2
 project: _Underscore
 client: compass-usa

package/package.json

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