toga-ai 1.0.772 → 1.0.774

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

@@ -6,6 +6,7 @@
 | [/clickup/aliases — ClickUp Label-Alias Admin (Tools → 2.0 Team schema)](features/clickup-label-aliases-admin.md) | The human side of the NetSuite→ClickUp **Stakeholders / End Customer** labels. | tools/mvc/clickup/aliases/get.php, tools/mvc/clickup/aliases/post.php, tools/_/app/clickup/aliases.php, tools/_/app/nav.php |
 | [Developer Dashboard (ClickUp Sprint, tools /developer)](features/clickup-sprint-dashboard.md) | A native **ClickUp sprint dashboard** in the 1.0 `tools` app at route `/developer` (the **"Developer Dashboard"**, renamed from `/clickup/react` / "Clickup" — s | tools/_/app/clickup/sprint.php, tools/v2/sprints/tile/index.php, tools/v2/sprints/current/index.php, tools/v2/sprints/status-breakdown/index.php, tools/v2/sprints/worktype-breakdown/index.php, tools/v2/sprints/points-by-dev/index.php, tools/v2/sprints/burndown/index.php, tools/assets/clickup/sprint-dashboard.html, tools/mvc/developer/get.php, tools/mvc/login/get.php, tools/_/app/nav.php |
 | [CloudFront Client Setup](features/cloudfront-client-setup.md) | An SSO-gated admin tool at **`/devops/cloudfront-clients`** in the Tools 1.0 app that onboards a client onto **CloudFront + Route 53 across multiple AWS account | tools/_/app/devops/cloudfront.php, tools/mvc/devops/cloudfront-clients/get.php, tools/mvc/devops/cloudfront-clients/post.php, tools/assets/js/cloudfront-clients.js, tools/assets/css/cloudfront-clients.css, tools/_/app/nav.php, tools/_/app/frameworkindex.php, tools/config.production.ini |
+| [Compass User & Persona Admin (tools /compass/users, /compass/personas)](features/compass-user-persona-admin.md) | Two pages in the Tools `developers` nav folder that let staff do, in a browser, the two Compass requests that used to mean "email a developer, who writes a `dbc | tools/_/app/compass.php, tools/mvc/compass/users/get.php, tools/mvc/compass/users/post.php, tools/mvc/compass/personas/get.php, tools/mvc/compass/personas/post.php, tools/_/app/nav.php, tools/config.production.ini |
 | [Design Demo Admin](features/design-demo-admin.md) | A self-serve admin UI at **`/design`** in the SSO-protected **Tools** app that lets the design team publish self-contained "Claude Design" HTML exports as **ver | tools/_/app/design/github.php, tools/mvc/design/get.php, tools/mvc/design/post.php, tools/assets/css/design.css, tools/assets/js/design.js, tools/_/app/frameworkindex.php, tools/_/app/nav.php, tools/composer.json |
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | The first two tools shipped in the Tools app, both under the **Developers** folder and gated to personas **Development Team** / **TOGa Technology**. | tools/mvc/developers/uuid/get.php, tools/mvc/developers/password/get.php, tools/mvc/developers/password/post.php |
 | [/errors Curation Console (Tools → shared Core Logs DB)](features/errors-curation-console.md) | Internal-only triage/curation screen for the 2.0 Issue/Event error-reporting pipeline, built as a 1.0 Tools MVC page reading the **shared Core Logs DB** through | tools/mvc/errors/get.php, tools/mvc/errors/post.php, tools/mvc/errors/issue/get.php, tools/assets/css/style.css, tools/_/app/nav.php, tools/config.production.ini |

package/knowledge/1.0/apps/tools/architecture.md

@@ -6,8 +6,8 @@ project: Tools
 client: shared
 type: architecture
 status: active
-updated: 2026-08-14
-owners: [jcardinal, kyalamarthi]
+updated: 2026-09-04
+owners: [jcardinal, kyalamarthi, ajean]
 files:
   - tools/index.php
   - tools/.ebextensions/020_setup_git_libraries.config
@@ -41,7 +41,11 @@ related:
 **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind
 simple interfaces, gated by Client_True staff persona. It is modeled on `togaview` and depends on
 the `library` core. Auth comes via the SAML gateway `?saml=` handoff; the app owns its own
-session and reads `Client_True` **read-only**. Adding a tool = create `mvc/<route>/get.php`
+session and reads `Client_True` **read-only** — but it is **no longer a read-only app**: as of
+PR tools#13 (unmerged) it also **WRITES** to client tenant databases (`Client_Compass` /
+`Client_CompassCanada`) through new `[database_compass]` / `[database_compasscanada]` ini
+sections that reuse the `[database_true]` account. That is the first non-read-only surface in
+Tools. Adding a tool = create `mvc/<route>/get.php`
 (copy `mvc/_TEMPLATE`) + add one `App_Nav::definition()` entry + `App_Auth::requireAuth([...])`.
 
 **Critical rules:** Do NOT use bare `<header>` elements in this app — they inherit the legacy
@@ -59,6 +63,11 @@ denied at the front controller / out of the web root. New CSS must use `--c-*` t
 `App_FrameworkIndex::setHeaderCode()` is the **only** hook for markup in `<head>`, and it
 **SETS rather than appends** — the theme bootstrap is its sole caller, so a second call
 silently clobbers it.
+**Any page that writes to a client tenant DB must `App_Auth::requireAuth()` an explicit, narrow
+persona list (`['Development Team']`) — never `App_Nav::personasForRoute()`**, which returns the
+UNION of the folder's personas and the action's personas and so widens the grant straight back to
+everyone who can see the nav group. Also: **persona checks read a 4-day session snapshot**, so
+removing someone's persona does **not** revoke their access — their session must be killed.
 
 ## Boot & structure
 

package/knowledge/1.0/apps/tools/features/compass-user-persona-admin.md

@@ -0,0 +1,138 @@
+---
+title: Compass User & Persona Admin (tools /compass/users, /compass/personas)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: draft
+updated: 2026-09-04
+owners: [ajean]
+files:
+  - tools/_/app/compass.php
+  - tools/mvc/compass/users/get.php
+  - tools/mvc/compass/users/post.php
+  - tools/mvc/compass/personas/get.php
+  - tools/mvc/compass/personas/post.php
+  - tools/_/app/nav.php
+  - tools/config.production.ini
+related:
+  - ./mvc-data-access-patterns.md
+  - ./persona-gated-navigation.md
+  - ./saml-sso-auth.md
+  - ../architecture.md
+  - ../../../2.0/apps/_underscore/features/effective-persona-resolution.md
+  - ../../../clients/compass-usa/features/people-file-user-lifecycle.md
+  - ../../../clients/compass-usa/features/persona-model-and-levy-gating.md
+  - ../../../clients/compass-usa/workflows/granting-persona-bundle-access.md
+---
+
+## Summary
+
+Two pages in the Tools `developers` nav folder that let staff do, in a browser, the two Compass
+requests that used to mean "email a developer, who writes a `dbchanges2` SQL file": **activate /
+deactivate a Compass user**, and **grant a persona**. Both tenants are covered by one tenant
+switcher — **US** (`Client_Compass`) and **Canada** (`Client_CompassCanada`).
+
+**This is the first thing in `tools` that WRITES to a client tenant database.** Until now the app
+read `Client_True` read-only. That single fact drives most of the design and every open risk below.
+
+Status: built on PR **tools#13**, **not yet merged**. `status: draft` until it ships.
+
+## Key files / entry points
+
+- **`tools/_/app/compass.php`** — `App_Compass`, all data access for both pages (search, persona
+  resolution, activate/deactivate, grant).
+- **`tools/mvc/compass/users/{get,post}.php`** — user search + activate/deactivate + grant persona.
+- **`tools/mvc/compass/personas/{get,post}.php`** — inspect one persona and who reaches it.
+- **`tools/_/app/nav.php`** — the two nav entries, inside the existing `developers` folder.
+- **`tools/config.production.ini`** — new `[database_compass]` / `[database_compasscanada]` sections.
+
+## How it works
+
+### What the pages do
+
+1. **Find a user** by `c_hrEmpUsername`, `email`, or `c_hrEmpPersonnelNbr`.
+2. **Activate / deactivate** them (`Users.isActive`).
+3. **See the personas that user reaches, and WHY** — direct row, own location, or sector.
+4. **Inspect a persona** and list who reaches it, from all three sources.
+5. **Grant a persona** — one `INSERT` into `Users_Personas`.
+
+The "why" column is the point of the tool. Answering "who has persona N" from `Users_Personas`
+alone badly under-reports on Compass, because most users hold their catalogue through their
+**sector**, not through a row of their own. The resolution rule the tool implements is the
+framework's own — see
+[Effective persona resolution](../../../2.0/apps/_underscore/features/effective-persona-resolution.md),
+which also carries the measured prod numbers and the "reverse lookups must be set-based" rule.
+
+### Access gating is deliberately tighter than the folder
+
+Both pages `requireAuth(['Development Team'])` — narrower than the `developers` folder's own
+persona set. That is on purpose: these are tenant **writes**, not read-only developer utilities.
+Passing `App_Nav::personasForRoute()` here would widen the grant back to the folder's set; see the
+nav-narrowing gotcha in [MVC data access patterns](./mvc-data-access-patterns.md).
+
+### Database connections
+
+New `[database_compass]` and `[database_compasscanada]` sections in `config.production.ini` reuse the
+**existing `[database_true]` account** — same client cluster, only `dbname` differs. **No new secret
+value was introduced.** See the accepted risk below.
+
+### Schema footprint: none
+
+The tool creates and alters **nothing**. It reads/writes only `Users`, `Users_Personas`,
+`Locations_Personas`, `Locations`, and reads `Personas` for names.
+
+## Decisions
+
+- **2026-09-04 — No new columns, no new tables (Jeff Cardinal, back-end review).** The tool talks
+  directly to production `Client_Compass` / `Client_CompassCanada` using the existing schema only.
+  This killed an earlier design that added `Users.c_isKeepActive` plus expiry/audit columns, an
+  `AdminAuditLogs` table, and three search indexes. `dbchanges2#478` and `worker2#160` were opened
+  and then **closed unmerged** — do not resurrect them without re-opening that decision.
+- **2026-09-04 — Reuse the `[database_true]` credential** rather than split out a least-privilege
+  Compass account. Raised twice in security review and consciously declined for now (see below).
+
+## Gotchas
+
+- **⚠ Activating a Compass user is TEMPORARY; deactivating is durable.** Because the
+  `c_isKeepActive` flag was dropped from scope, the nightly PEOPLE importer will deactivate anyone
+  absent from that day's file — so an activation only sticks if the person is actually in the file.
+  Deactivation holds, because the cron never reactivates anybody. Full lifecycle:
+  [PEOPLE-file User Lifecycle](../../../clients/compass-usa/features/people-file-user-lifecycle.md).
+- **A cross-region user still needs a code change and a deploy.** The only durable way to hold one
+  active is the hardcoded four-address list in `ensureCrossRegionUsersActive()` in
+  `worker2/Worker/Client/Compass/PeopleFile.php`. This tool does not change that.
+- **Every user search is a full table scan.** `Client_Compass.Users` has no index on `email`,
+  `c_hrEmpUsername`, `c_hrEmpPersonnelNbr` or `isActive` (176k rows; `EXPLAIN` reports `type=ALL`,
+  no possible keys). Same on `Client_CompassCanada`. Keep result sets bounded and do not add
+  per-row lookups against those columns in a loop.
+- **⚠ Accepted risk — the tool widens the blast radius of one shared credential.** It points the
+  `[database_true]` account at two more tenant schemas. `config.production.ini` is committed and was
+  web-readable until the 2026-07-24 `FilesMatch` deny blocks, so **rotation of that account is still
+  owed**. An inline comment in the ini records this and lists the exact grants a split-out Compass
+  account would need. Never paste the value anywhere.
+- **⚠ Persona revocation does not take effect for up to 4 days.** Tools snapshots persona names into
+  `$_SESSION` at login and sessions last 4 days, so removing someone's `Development Team` persona
+  does not lock them out of these pages until their session dies. See
+  [SAML SSO & persona-gated auth](./saml-sso-auth.md).
+- **No staff-actor audit trail exists for these writes.** `Logs_Compass.Record.userId` is a **tenant**
+  `Users.id`, so it cannot record a `Client_True` staff member — it is not usable as the audit log
+  for this tool, and `Logs_Compass.Record` is the client-facing activity log (3.6M rows) besides.
+  See
+  [Record Change Audit Log](../../../2.0/apps/_underscore/features/record-change-audit-log.md).
+  Auditing internal-tool actions remains an open item.
+- **Detecting a no-op UPDATE needs `App_Database::affectedRows()`** — `App_Database::query()` returns
+  the `App_Query` execute result, not a row count. Details in
+  [MVC data access patterns](./mvc-data-access-patterns.md).
+
+## Change history
+
+- 2026-09-04 — Initial: built the two-page Compass user/persona admin (PR tools#13, unmerged) — the
+  first `tools` pages that write to a client tenant DB, gated to `Development Team` only, with a
+  US/Canada switcher and new `[database_compass]` / `[database_compasscanada]` ini sections reusing
+  the existing `[database_true]` account. Recorded Jeff Cardinal's scope reset (no schema changes;
+  `dbchanges2#478` and `worker2#160` closed unmerged) and its consequence — **activation is temporary
+  because the `c_isKeepActive` flag was dropped**, while deactivation is durable. Logged the accepted
+  credential-reuse risk, the 4-day session persona staleness, the missing staff-actor audit trail, and
+  that every user search is a full scan. (ajean)

package/knowledge/1.0/apps/tools/features/mvc-data-access-patterns.md

@@ -6,8 +6,8 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
-owners: [jcardinal, bala]
+updated: 2026-09-04
+owners: [jcardinal, bala, ajean]
 files:
   - tools/_/app/nav.php
   - tools/mvc/get.php
@@ -15,6 +15,7 @@ files:
   - library/app/database.php
 related:
   - ./persona-gated-navigation.md
+  - ./compass-user-persona-admin.md
   - ./saml-sso-auth.md
   - ../architecture.md
   - ../../library/features/mvc-page-pattern-and-app-skeleton.md
@@ -57,6 +58,31 @@ add one expecting the framework to validate it.
   2.0 DB read-only through its own connection (e.g. `db_true → Client_True`); adding
   `db_team → Team` is the same pattern.
 
+### Detecting a no-op UPDATE — `App_Database::affectedRows()`
+`App_Database::query()` returns the `App_Query` execute result, **not** a row count, so it cannot
+tell you whether an `UPDATE` actually changed anything. Use
+`App_Database::affectedRows($linkRegistryString)` — pass the same alias you queried with. This is
+how a page distinguishes "saved" from "the value was already that".
+
+### DB credentials come straight from the ini — there is no secret store
+`App_Database::registerDatabaseConnect()` (`library/app/database.php:125-128`) reads
+**hostname / username / password / dbname directly from the config ini**. Only
+`database_reader_endpoint` goes through `App_Cloud::getParameter()`. So a 1.0 app **cannot** move a
+DB credential into a secret store without changing shared `library` core that every 1.0 app boots
+through. Plan around it: `config.*.ini` is where DB credentials live, and it is committed (see the
+config/secrets note in [the architecture doc](../architecture.md)).
+
+### Input filtering — `App_Page::getVarIfSet()` allows printable ASCII
+`getVarIfSet()` runs `App_String::filterCharactersValidCharactersOnly()`, which permits **ASCII
+32-126**. Emails, usernames and personnel numbers survive intact, so it is safe for those search
+inputs. It is a character filter, not an escaper — still escape/cast before the value reaches SQL.
+
+### Production MySQL runs `US/Central`
+The prod MySQL server timezone is **`US/Central`**, matching the 1.0 framework's `America/Chicago`
+and worker2's Central-time cron scheduling (verified 2026-09-02). So MySQL `CURDATE()` and PHP
+`date('Y-m-d')` agree — there is **no** day-boundary divergence to design around when the same date
+check exists in both SQL and PHP.
+
 ### Gotcha — by-reference row helpers
 `buildArrayOfRows`, `fetchOne`, and `fetchRow` take `$res` **by reference**. Assign the
 `query()` result to a **variable first**, then pass it — passing the call result inline emits
@@ -142,6 +168,14 @@ set_error_handler(fn(): bool => true); // swallow non-fatal notices/deprecations
 `App_Talos_Estimator` → `_/app/talos/estimator.php`.
 
 ## Change history
+- 2026-09-04 — Added four `App_Database` / input facts found building the Compass admin pages:
+  `affectedRows($alias)` is how you detect a no-op `UPDATE` (`query()` returns the `App_Query`
+  execute result, not a row count); `registerDatabaseConnect()` reads DB credentials **directly from
+  the config ini** (only `database_reader_endpoint` uses `App_Cloud::getParameter()`), so there is no
+  secret-store option without changing shared 1.0 core; `App_Page::getVarIfSet()` filters to
+  printable ASCII 32-126, so emails/usernames/personnel numbers pass through intact; and production
+  MySQL runs timezone **`US/Central`**, matching PHP's `America/Chicago`, so `CURDATE()` and
+  `date('Y-m-d')` agree. (ajean)
 - 2026-08-04 — Added two gotchas found rebuilding the Talos Pricing UI: (1) `App_Database::fetchOne()` is **not** an existence test — it `data_seek`s and returns `$row[$col]` with no empty check, so zero rows dereferences null → uncaught `ErrorException` → bare 500; a **library-wide** footgun affecting every 1.0 app (use `COUNT(*)` or `buildArrayOfRows` + `empty()`). (2) Tools runs **PHP 8.5**, where "using null as an array offset" is deprecated even inside `isset()` and the framework escalates deprecations to fatals — cast to `(string)` before indexing; PHP 8.2 local dev does not reproduce it. (jcardinal)
 - 2026-08-03 — Added the error-handler escalation gotcha: `App_Error::handleError` promotes ANY PHP
   notice/deprecation to a thrown `ErrorException` (ignoring `error_reporting`) and, without Sentry,

package/knowledge/1.0/apps/tools/features/saml-sso-auth.md

@@ -6,8 +6,8 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
-owners: [jcardinal]
+updated: 2026-09-04
+owners: [jcardinal, ajean]
 files:
   - tools/_/app/auth.php
   - tools/mvc/sso/initiate/get.php
@@ -20,6 +20,7 @@ files:
   - tools/config.local.ini
 related:
   - ../architecture.md
+  - ./compass-user-persona-admin.md
   - ../../library/features/app-sso-initiation.md
   - ../../../2.0/apps/saml/features/downstream-integration-contract.md
   - ../../../clients/true/features/users-personas-data-model.md
@@ -115,6 +116,17 @@ removed.
 
 ## Gotchas / known issues
 
+- **⚠ Personas are snapshotted at login and sessions last 4 days — revoking a persona does not
+  revoke access.** `App_Auth` caches the user's persona **names** into `$_SESSION` at sign-in and
+  `requireAuth()` / `App_Nav` both read that cache, never the live `Users_Personas` rows. So removing
+  someone's persona leaves them able to use every page it gated for up to **4 days**, until their
+  session expires. This matters most for pages that write to a client tenant — see the [Compass
+  admin pages](./compass-user-persona-admin.md). To cut access off now, kill the session, do not just
+  revoke the persona.
+- **The Tools session cookie has no `Secure` flag.** `App_Framework_Tools` sets `useSessions = false`,
+  so the parent `library` framework's `cookie_secure` setup never runs; Tools sets the cookie itself
+  with HttpOnly + SameSite=Lax only. Open item — do not assume the cookie is HTTPS-only.
+
 - **Consumer route runs mid-render → headers already sent.** The 1.0 framework runs `mvc/sso/get.php`
   **inside** the page render (`frameworkindex → body → loadFile`) after `common/header.php` has
   emitted output, so `session_regenerate_id(true)` fatals ("cannot be regenerated after headers
@@ -180,6 +192,11 @@ remains (already noted in tools knowledge) — **flag for rotation.** Document *
 never the values.
 
 ## Change history
+- 2026-09-04 — Recorded two standing security gaps found while adding tenant-writing pages: personas
+  are **snapshotted into `$_SESSION` at login** and sessions last **4 days**, so revoking a persona
+  does not revoke page access until the session dies (kill the session instead); and the Tools
+  session cookie carries **no `Secure` flag**, because `App_Framework_Tools` sets `useSessions =
+  false` and the parent framework's `cookie_secure` setup therefore never runs. (ajean)
 - 2026-06-30 — Fixed SSO "Sign in failed" (`/login?error=1`) regression and **corrected the earlier wrong "config tokens are removable" note**. The prior fix moved only the consumer/decrypt leg to `Core.Parameters` and advised the `[saml] api_secret_access_token` was removable — but the **initiate** leg (`mvc/sso/initiate/get.php`) still read it from config, so removing it made `App_Sso::initiate()` throw on an empty token (`library/app/sso.php:64-65`) → `/login?error=1`. Fix: **both** legs now source the rotating secret from `Core.Parameters` — added public `App_Auth::currentApiSecret()` (reuses cached `handoffKeys()`), and `sso/initiate/get.php` passes it instead of the config value. Documented the non-empty-token requirement, the `/login?error=1` (initiate) vs "Authentication failed" (consumer) leg distinction, the `true_client_uuid`-stays-in-config rule, and the `db_toga2core`-missing→500 diagnostic. `php -l` clean on both files. (jcardinal)
 - 2026-06-30 — Fixed prod SSO login failure: handoff decrypt keys now sourced from `Core.Parameters` (rotated `API_SECRET_ACCESS_TOKEN`/`_PREVIOUS`) via new `App_Auth::handoffKeys()` over `db_toga2core` (per-request cached, current→previous fallback), instead of the stale committed `config [saml]` tokens — the stale key was the root cause. Added `[database_toga2core]` connection requirement to every config and documented the AES-256-CBC crypto format. Fixed `tools_ssoFail()` 500→intended 401: `http_response_code(401)` fataled on headers-already-sent (preloader flushes before mvc page runs); guarded with `!headers_sent()`. (jcardinal)
 - 2026-06-26 — Wired up real SSO initiation via the new 1.0 `App_Sso` library class (`/sso/initiate`), replacing the `initiation_url` placeholder; registered the fixed-uuid Core.Domains return row (dbchanges2 `2026-06-26a`); fixed the `session_regenerate_id` headers-already-sent fatal (guarded with `!headers_sent()`) and documented the mid-render failure-path limitation; collapsed home → `/login` to one-step sign-in; noted prod secrets live in `config.production.ini [saml]` (jcardinal)

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

@@ -6,7 +6,7 @@
 | [Canon received-PO → NetSuite sales order sync](features/canon-received-po-netsuite-order-sync.md) | A 1.0 `worker` cron that reads Canon customer purchase orders out of the **Vision** databases and creates the matching **sales order in NetSuite**. | worker/crons/sync/sync_received_po.php, library/netsuitetoolkit/NSPHPClient.php |
 | [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%` sales orders whose corresponding Office Depot (ODP) sales order has | worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php, worker/schedules/cron.worker.sync.json |
 | [Compass Manager Approval Reminder Emails (1.0 worker crons)](features/compass-manager-approval-reminder-emails.md) | Two 1.0 worker crons nag approvers about sales orders still waiting on a decision — one per Compass tenant. | worker/crons/toga2/compass/compass_email_reminders.php, worker/crons/toga2/compasscanada/compass_email_reminders.php, worker/schedules/cron.worker.sync.json, worker1.5/crons/toga2/compass/compass_email_reminders.php, worker1.5/schedules/cron.worker.json |
-| [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compass/send_delivered_email.php, worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php, worker/crons/toga2/compasscanada/send_delivered_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_delivered_email.php, library/app/client/compasscanada.php |
+| [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compass/send_delivered_email.php, worker/crons/toga2/compasscanada/update_salesorder_status_from_g&t.php, worker/crons/toga2/compasscanada/send_delivered_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_delivered_email.php, library/app/client/compasscanada.php, worker/schedules/cron.worker.sync.json, worker2/Worker/Monitor/Compass.php, dbchanges2/Client_Compass/2026-09-03 - compass_intransit_email_backlog_backfill.sql |
 | [Elite TOGA 2.0 → TOGaDeskSupport Standalone Attachment Sync](features/elite-togadesk-attachment-sync.md) | `sync_togadesk_elite_attachments.php` is a standalone cron (every 5 minutes) that syncs file attachments from TOGA 2.0 into TOGaDeskSupport for Elite. | worker/crons/toga2/elite/sync_togadesk_elite_attachments.php, worker/crons/toga2/elite/test_sync_togadesk_elite_attachments.php |
 | [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/checker.php, worker2/Component/Forecast/SaleImport/SaleImport.php, test/@dave/looper.php, test/@dave/reconcile_netsuite_totals.php, test/@dave/fixer.php, tools/bin/forecast/fixer.php, tools/bin/forecast/checker.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/reconcile_drift_2023plus.php, test/@dave/probe_invoice_gap_2026.php, test/@dave/probe_creditmemo_gap_detail.php, test/@dave/trueup_open_orders.php, test/@dave/loop_trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_profit_invoices.php, test/@dave/probe_profit_gap.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/schedules/cron.worker.infrastructure.json |
 | [Forecast2 Supporting-Records Nightly Import (1.0 cron) — Customers & ConsolidatedCustomers](features/forecast2-supporting-records-import.md) | The nightly **1.0** pull that keeps the Forecast2 lookup/dimension tables (`Forecast.Accounts`, `Classifications`, `Customers`, `ConsolidatedCustomers`, `Employ | worker/crons/toga2/forecast2/import_supporting_records.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/schedules/cron.worker.infrastructure.json, worker/.ebextensions/009_setup_phpini.config, worker/crons/sync/netsuite/netsuite_customers.php, library/app/api/netsuite/rest.php, library/app/model/forecast2/customer.php, library/app/model/forecast2/consolidatedcustomer.php |

package/knowledge/1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md

@@ -6,18 +6,23 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-26
+updated: 2026-09-04
 owners: ["bala"]
 files:
   - worker/crons/toga2/compass/update_salesorder_status_from_odp.php
   - worker/crons/toga2/compass/send_delivered_email.php
-  - worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php
-  - worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php
+  - worker/crons/toga2/compasscanada/update_salesorder_status_from_g&t.php
   - worker/crons/toga2/compasscanada/send_delivered_email.php
   - worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php
   - worker/crons/toga2/compasscanada/workflow/test_partial_delivered_email.php
   - library/app/client/compasscanada.php
+  - worker/schedules/cron.worker.sync.json
+  - worker2/Worker/Monitor/Compass.php
+  - dbchanges2/Client_Compass/2026-09-03 - compass_intransit_email_backlog_backfill.sql
 related:
+  - ../../../clients/compass-usa/features/contact-email-resolution.md
+  - ../../../2.0/apps/worker2/features/tracking-status-refresh.md
+  - ../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md
   - ../../../clients/compass-canada/features/french-order-email-localization.md
   - ../../../clients/compass-usa/features/order-fulfillment-status-per-line.md
   - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
@@ -34,18 +39,28 @@ and earlier packages). The dynamic HTML is injected into a stored `EmailTemplate
 
 ## Key files / entry points
 
-- `worker/crons/toga2/compass/update_salesorder_status_from_odp.php` — Compass USA prod cron.
-- `worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php`
-  — Compass Canada prod cron.
+- `worker/crons/toga2/compass/update_salesorder_status_from_odp.php` — Compass USA prod cron,
+  registered in `worker/schedules/cron.worker.sync.json` as **"Update Compass SalesOrder Status
+  From ODP CXML"**, schedule **`0 */4 * * *`** — it fires at 00/04/08/12/16/20 **US/Central**
+  (the prod DB timezone). Every threshold below (batch cap, staleness, monitor alarms) is
+  calibrated to that 4-hour cadence.
+- `worker/crons/toga2/compasscanada/update_salesorder_status_from_g&t.php` — Compass Canada
+  prod cron, registered as "Update CompassCanada SalesOrder Status From G&T CXML".
+  **⚠ This filename contains `&` and therefore cannot run — see the gotcha below.** It was
+  renamed from `update_salesorder_status_from_odp.php` on 2026-09-03; the duplicate
+  `workflow/3_update_salesorder_status_from_grand_and_toy.php` was **deleted** in the same pass and
+  its stale `schedules/cron.worker.sync.json` entry removed.
 - Shared helper set in each cron: `getOrderFulfillmentData`, `buildItemRowsHtml`,
   `buildSectionHeaderHtml`, `buildPackageBlockHtml`, `buildTrackingUrl`, `buildOrderItemsHtml`.
 
 ## How it works
 
 1. **Driving query** finds shipped sales orders and their tracking numbers (`computedStatusSlug
-   = 'shipped'`, `c_dtInTransitEmailSent IS NULL`, date cutoff) via the ASN chain
-   (`AdvanceShippingNoticeItemUnits_TrackingNumbers`), one row per `TrackingNumbers.number`.
-2. Per tracking number: skip if the carrier API already reports delivered.
+   = 'shipped'`, `c_dtInTransitEmailSent IS NULL`, rolling date window) via the ASN chain
+   (`AdvanceShippingNoticeItemUnits_TrackingNumbers`), one row per `TrackingNumbers.number`,
+   **newest first and capped** — see *Draining the candidate set* below.
+2. Per tracking number: skip if the shipment is already finished — checked first against the
+   stored `TrackingNumbers.status` (free), and only then with a live carrier call.
 3. **`getOrderFulfillmentData`** returns the order's packages (grouped by tracking number,
    ordered by `dtCreated`) and ordered items, sourced from the **`ItemFulfillmentItems`** line
    bridge (`ItemFulfillmentItems` → `ItemFulfillments` (scoped to the buyer SO) →
@@ -58,6 +73,73 @@ and earlier packages). The dynamic HTML is injected into a stored `EmailTemplate
    `App_Api_Toga2::send(..., 'POST', '/email-templates/sendEmail', $payload, [], true)`.
 6. On a successful (non-throwing) send, set `c_dtInTransitEmailSent = NOW()`.
 
+### Draining the candidate set: two-pass, newest-first, bounded
+
+**This is the load-bearing part of the cron. Getting it wrong took Compass USA in-transit emails to
+near zero for a week** (2026-08-27 → 2026-09-03: 130–190 a day before, then 7 / 1 / 6 / 0 / 1).
+Customers were not told their order had shipped.
+
+The original shape was: select **every** unstamped `TrackingNumbers` row since a hardcoded
+`'2026-06-15'`, then call UPS/FedEx **live, one row at a time**. When a shipment turned out to be
+already delivered the loop `continue`d **without stamping `c_dtInTransitEmailSent`** — so the same
+row came back on the next run, forever. The candidate set grew to **2,379** and the run hit its
+`App_Framework::cronInitialization(3600)` one-hour limit while still inside the June rows. It never
+reached the day's new ASNs. Nothing errored; the cron just ran out of time on every tick.
+
+Four changes fix it, and they are the pattern to copy for any *"poll an external API per row, then
+mark the row done"* cron:
+
+1. **Two passes.** Pass 1 walks the candidates and **stamps** every already-finished row so it
+   retires from the candidate set permanently. Pass 2 sends. A row can never again be examined
+   forever without being retired.
+2. **Newest first, hard cap.** `ORDER BY MAX(TrackingNumbers.dtCreated) DESC` +
+   `LIMIT IN_TRANSIT_EMAIL_BATCH_SIZE` (**400**). Today's shipments are served before any backlog,
+   so a backlog can delay old mail but can never starve new mail.
+3. **Rolling window, not a fixed date.** `IN_TRANSIT_EMAIL_LOOKBACK_DAYS = 14` →
+   `dtCreated >= DATE_SUB(NOW(), INTERVAL 14 DAY)`. A hardcoded cutoff date guarantees an
+   ever-growing scan; a rolling window is self-limiting.
+4. **Trust the stored status before paying for a carrier call.** `isTrackingStatusFinal(?string)`
+   short-circuits when `TrackingNumbers.status` is already `DELIVERED` or `RETURNED_TO_SENDER`
+   (`TRACKING_FINAL_STATUSES`). worker2's
+   [centralized tracking-status refresh](../../../2.0/apps/worker2/features/tracking-status-refresh.md)
+   keeps that column current for every client, so this 1.0 cron should not re-ask the carrier about
+   a finished shipment.
+
+### Resolving the recipient: a `Users` row is NOT required (USA)
+
+The To address originally came only from `Users.email`, via `INNER JOIN Users ON Users.contactId =
+…`. **EDI-created MR orders never get a `Users` row**, so those orders were silently absent from
+the driving query — 12 MR orders with shipped parcels were never emailed and never even showed up
+as a backlog.
+
+The USA cron now resolves the address in this precedence:
+
+```
+LEFT OUTER JOIN Users
+    ON Users.contactId = ShippedSalesOrders.contactId
+    AND Users.email IS NOT NULL AND Users.email <> ''
+INNER JOIN Contacts
+    ON Contacts.id = ShippedSalesOrders.contactId
+LEFT OUTER JOIN ContactEmailAddresses
+    ON ContactEmailAddresses.id = Contacts.primaryContactEmailAddressId
+    AND ContactEmailAddresses.contactId = Contacts.id      # ownership guard
+…
+IFNULL(Users.email, ContactEmailAddresses.emailAddress) AS contactEmail
+```
+
+The same `IFNULL` resolves the display name, and the `WHERE` requires the resolved address to be
+non-empty.
+
+**The `ContactEmailAddresses.contactId = Contacts.id` predicate is not optional.** About 14% of
+Compass contacts point at an email row owned by a *different* contact, so without it the cron mails
+the wrong person — see
+[Compass contact email resolution](../../../clients/compass-usa/features/contact-email-resolution.md).
+
+**Regression-checked, not assumed.** Over 60 days and **4,419 SA tracking rows** the old and new
+queries both select **4,416**: 0 newly included, 0 lost, resolved address and name identical on all
+4,416. The `Users` address always wins because it is first in the `IFNULL`, so the change is
+strictly additive — it only reaches orders the old query could not see at all.
+
 ### Tracking-URL building (`buildTrackingUrl`)
 
 The "Track Shipment" button and each per-package link resolve in this precedence:
@@ -100,7 +182,22 @@ the tracking number as emailed (it retries next run).
 
 ## Client variations
 
-- **Compass USA** — English only; `update_salesorder_status_from_odp.php`.
+- **Compass USA** — English only; `update_salesorder_status_from_odp.php`. Has the full
+  2026-09-03 hardening: two-pass drain, 400-row cap, 14-day window, `isTrackingStatusFinal()`,
+  **and** the `Users` → `Contacts`/`ContactEmailAddresses` recipient fallback with the ownership
+  guard.
+- **⚠ Canada is only PARTLY at parity (verified 2026-09-04).**
+  `compasscanada/update_salesorder_status_from_g&t.php` has the batching changes
+  (`IN_TRANSIT_EMAIL_BATCH_SIZE = 400`, `IN_TRANSIT_EMAIL_LOOKBACK_DAYS = 14`,
+  `ORDER BY MAX(TrackingNumbers.dtCreated) DESC`, `isTrackingStatusFinal()`) but **still resolves
+  the recipient with `INNER JOIN Users … Users.email AS contactEmail`** — no `Contacts` /
+  `ContactEmailAddresses` fallback and no ownership guard. Canada therefore still cannot email a
+  contact that has no `Users` row. Port the recipient block if Canada ever gets EDI-created MR
+  orders.
+- **Canada keeps its own retry behaviour on a carrier throw.** It leaves the row **unstamped** when
+  the carrier lookup throws, so the next run retries it; only rows confirmed *final* are stamped.
+  That is deliberate and must survive any future parity pass — stamping on a throw would silently
+  drop the email.
 - **Compass Canada** — EN/FR by `UserGlobalSettings.settingId = 2` (FR when the value starts
   with `fr`); French section labels and a French (HTML-entity) status message; uses
   `htmlentities` in the section header builder and a 7-param French-aware `buildPackageBlockHtml`.
@@ -113,6 +210,33 @@ the tracking number as emailed (it retries next run).
 
 ## Gotchas / known issues
 
+- **⚠ A cron filename containing `&` cannot run at all.** `worker/ebs/cron.worker.php:41` builds
+  the crontab command by plain unquoted concatenation
+  (`'php /var/www/html/crons/' . $cron->cron`), so cron reads `&` as *"background this and start a
+  new command"*: `update_salesorder_status_from_g&t.php` executes as
+  `…/update_salesorder_status_from_g` plus a stray `t.php`, and the real script never runs —
+  silently, on every tick. **The Canada cron is in this state as of 2026-09-04 and must be renamed
+  (e.g. `update_salesorder_status_from_gt.php`) with `schedules/cron.worker.sync.json` repointed.**
+  Never put `&` (or any shell metacharacter) in a cron filename. See
+  [tracing a 1.0 worker cron run](../workflows/tracing-a-worker-cron-run-in-production.md).
+- **⚠ Invoice tracking numbers are NOT in scope and must never be counted as in-transit
+  backlog.** `POST /v2/invoice-tracking-numbers` creates `TrackingNumbers` rows bridged through the
+  **`InvoiceTrackingNumbers`** table — never the ASN chain. On 2026-09-03 alone, 98 were created
+  (11:15–11:40) and **zero** of them touch `AdvanceShippingNoticeItemUnits_TrackingNumbers`.
+  Anything that walks the ASN unit bridge (this cron, and the OneUptime queue monitor) correctly
+  ignores them. Their shape is distinctive: **`shippingCarrierId` set, `shippingMethodId` NULL**.
+  A naive `TrackingNumbers WHERE c_dtInTransitEmailSent IS NULL` count will read these as a backlog
+  that never drains.
+- **Clear an in-transit backlog by STAMPING, not by emailing — and refresh statuses first.**
+  Decided 2026-09-03 while draining the outage backlog
+  (`dbchanges2/Client_Compass/2026-09-03 - compass_intransit_email_backlog_backfill.sql`):
+  `c_dtInTransitEmailSent` was stamped on **64,132** rows older than the 14-day window and **421**
+  in-window rows already on a final status, leaving **68** genuinely still moving. Sending an
+  "in transit" email for a June order that arrived two months ago confuses the customer, so old
+  rows retire silently. **Ordering matters:** let worker2 `Sync/TrackingNumbers` refresh any
+  recently-unparked rows **before** running the backfill, otherwise a row with a stale status gets
+  a wrong in-transit email. (A parked row holds a stale status indefinitely — see
+  [tracking-status refresh](../../../2.0/apps/worker2/features/tracking-status-refresh.md).)
 - **Canada now uses the `ItemFulfillmentItems` line bridge, not the ASN chain**, for
   `getOrderFulfillmentData` — same query as Compass USA. Canada was originally on the ASN chain
   because it had **zero `ItemFulfillmentItems`**; if that line-bridge data is not populated for a
@@ -138,7 +262,7 @@ the tracking number as emailed (it retries next run).
   language even though the mail goes to the **manager**. Fixed 2026-08-03.
 - **⚠ Each cron keeps its OWN duplicated copy of the 2.0 `_status` CASE — a standing divergence
   risk.** `compass/update_salesorder_status_from_odp.php`,
-  `compasscanada/update_salesorder_status_from_odp.php` and
+  `compasscanada/update_salesorder_status_from_g&t.php` and
   `compass/workflow/test_partial_in_transit_email.php` each re-implement the model's status SQL as
   `computedStatusSlug`. Today that is safe by luck of scope: the copies only ever produce canceled /
   pendingApprovalUnknown / pendingFulfillment / shipped and they filter on
@@ -161,6 +285,27 @@ the tracking number as emailed (it retries next run).
 
 ## Change history
 
+- 2026-09-04 — **Fixed the Compass USA in-transit email outage (2026-08-27 → 2026-09-03, 130–190
+  emails/day → near zero).** Root cause: already-delivered rows were `continue`d without stamping
+  `c_dtInTransitEmailSent`, so the candidate set grew to 2,379 and every run burned its
+  `cronInitialization(3600)` hour inside rows dating back to a hardcoded `'2026-06-15'`, never
+  reaching new ASNs. Fix: two-pass drain (stamp finished rows, then send), newest-first
+  `ORDER BY MAX(dtCreated) DESC` with `IN_TRANSIT_EMAIL_BATCH_SIZE = 400`, rolling
+  `IN_TRANSIT_EMAIL_LOOKBACK_DAYS = 14` replacing the fixed date, and `isTrackingStatusFinal()`
+  short-circuiting the carrier call on `DELIVERED`/`RETURNED_TO_SENDER` using the status worker2
+  `Sync/TrackingNumbers` already maintains. Also **widened the recipient**: `LEFT OUTER JOIN Users`
+  + `Contacts`/`ContactEmailAddresses` with an ownership guard and
+  `IFNULL(Users.email, ContactEmailAddresses.emailAddress)`, which recovered 12 EDI-created MR
+  orders that have no `Users` row (regression-checked: 4,416 of 4,419 SA rows selected by both old
+  and new queries, 0 gained, 0 lost, identical resolved address/name). Backlog cleared by
+  **stamping** 64,132 out-of-window + 421 final-status rows rather than emailing them. Recorded
+  that **invoice tracking numbers are not in scope** (bridged via `InvoiceTrackingNumbers`, never
+  the ASN chain) and that a **`&` in a cron filename stops the cron dead**. Canada got the batching
+  changes only (renamed to `update_salesorder_status_from_g&t.php`; duplicate
+  `workflow/3_update_salesorder_status_from_grand_and_toy.php` deleted); its recipient block is
+  **still `INNER JOIN Users`**. New OneUptime monitor `Monitor/Compass/InTransitEmailQueue` now
+  watches this queue — see
+  [OneUptime push-metric monitors](../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md). (bala)
 - 2026-08-26 — Flagged the **duplicated `_status` CASE** in the three crons as a standing divergence
   risk after the 2.0 Compass fulfillment rule was rewritten. Verified the crons are unaffected: their
   copies only emit canceled / pendingApprovalUnknown / pendingFulfillment / shipped and filter on

package/knowledge/1.0/apps/worker/workflows/tracing-a-worker-cron-run-in-production.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: workflow
 status: active
-updated: 2026-09-01
+updated: 2026-09-04
 owners: ["bala", "kyalamarthi"]
 files:
   - worker/ebs/cron.worker.php
@@ -170,7 +170,28 @@ to **2.0 only**. The 1.0 standard wins in `library/`, `worker/` and every other
 `library/app/systemmonitor/500error.php` uses `str_contains()`; that file is not a version
 signal, it is a latent bug.
 
+## Deploy-time trap: a `&` (or any shell metacharacter) in the cron FILENAME silently kills it
+`ebs/cron.worker.php:41` builds each crontab line by plain string concatenation
+(`'php /var/www/html/crons/' . $cron->cron`) with **no quoting and no escaping**. Cron then parses
+that line as a shell command, so a `&` in the filename is read as *"run everything before this in
+the background and start a new command."*
+
+Worked example (found 2026-09-03): a developer renamed the Compass Canada status cron to
+`crons/toga2/compasscanada/update_salesorder_status_from_g&t.php` and repointed
+`schedules/cron.worker.sync.json` at it. The crontab line becomes two commands —
+`php .../update_salesorder_status_from_g` (a file that does not exist) and a stray `t.php` — so the
+real script **never executes**, on every tick, with no error anywhere. It looks exactly like
+"the cron never fired".
+
+**Rule: a cron filename must be plain `[a-z0-9_]` plus `.php`.** No `&`, no spaces, no `;`, `|`,
+`$`, `(`, `)`, `*`, `?`, or quotes. The *display name* in `schedules/*.json` is free text and may
+contain anything; only the `cron` path is shell-parsed.
+
 ## Change history
+- 2026-09-04 — Added the **`&`-in-a-cron-filename trap**: `ebs/cron.worker.php:41` concatenates the
+  path into the crontab line unquoted, so a shell metacharacter splits the command and the script
+  never runs while leaving no trace. Found via the renamed Compass Canada
+  `update_salesorder_status_from_g&t.php`. (bala)
 - 2026-09-01 — Added **Step 6: check the email log, not the inbox** — a 1.0 cron's sends land in
   the **legacy** env's `Logs.Emails` (schema `Logs`, table `Emails`), never prod `Logs` or
   `Logs_<Client>`; gave the verification query, and noted that a missing row usually means the job

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

@@ -19,6 +19,7 @@
 | [_Config group access — the two-argument "optional" form does NOT rescue a missing GROUP](features/config-group-access.md) | `_Config::<group>('<property>')` reads a value out of the active `Config/<ENVIRONMENT>.ini`, and **it throws when the requested group is absent from the ini.** | _underscore/Config.php, _underscore/Component/Api/Paypal/Paypal.php, _underscore/Worker.php, api2/Config/beta.ini, api2/Config/sandbox-dev.ini |
 | [Core.Domains — the app host registry (and why you cannot derive a host)](features/core-domains-app-host-registry.md) | `Core.Domains` is the **authoritative registry of which host serves which client's app in which environment**. | _underscore/Model/Core/Domain.php, api2/Component/Api/CrossClient/CrossClient.php, api2/Component/Api/V2/V2.php, worker/config.beta.ini |
 | [Re-pointing a DB alias mid-request (_Database::register park/restore)](features/database-alias-repointing.md) | `_Database` keys **all live per-database runtime state by the connection ALIAS** (`Client` / `_underscore::DB_CLIENT`, `ClientLogs`, `Archive`), **not** by the | _underscore/Database.php, _underscore/Query.php, api2/Component/Api/V2/V2.php, api2/Component/Api/CrossClient/CrossClient.php |
+| [Effective persona resolution (_Model_Client_User::_personaIds) — the three sources and the sector hop](features/effective-persona-resolution.md) | A user's **effective** persona set is **not** `Users_Personas`. | _underscore/Model/Client/User.php |
 | [2.0 Email Send Pipeline (queue + Send worker)](features/email-send-pipeline.md) | In 2.0, `_Email::send()` **does not transmit** — it queues the message. | _underscore/Email.php, _underscore/String.php, worker2/Worker/Infrastructure/Email/Send.php, _underscore/Model/Client/Logs/Email.php, _underscore/Model/Client/Logs/EmailAttachment.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/Quad/ApprovalDecision.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [Error Reporting — Issue/Event Capture, Fingerprinting & Aggregation](features/error-reporting-issue-event.md) | Platform-wide error reporting for TOGA 2.0, built on an **Issue / Event** aggregation model in the **shared Core Logs DB**. | _underscore/Error.php, _underscore/Query.php, _underscore/Database.php, _underscore/Exception/Business.php, _underscore/Exception/Database.php, _underscore/Test/DatabaseFingerprint.php, api2/Controller/Index.php, worker2/Controller/Index.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, _underscore/Model/Core/Logs/IssueFingerprint.php, _underscore/Model/Core/Logs/IssueClickupTask.php, _underscore/Model/Core/Logs/IssueEmailAddress.php, _underscore/Model/Core/Logs/IssueAreaOwner.php, worker2/Worker/Infrastructure/Errors.php, tools/mvc/errors/issue/get.php, tools/mvc/errors/post.php, dbchanges2/Logs/2026-07-30a - Error reporting Issues and Events.sql, dbchanges2/Logs/2026-08-01a - Rename tables to singular.sql, dbchanges2/Logs_Client/2026-08-01a - Drop Error table.sql, dbchanges2/Core/2026-07-30a - Error escalation cron job.sql |