toga-ai 1.0.848 → 1.0.849

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

@@ -249,40 +249,3 @@ names, reads `Core.ClientEmailDomains` / `Core.Clients`, and inserts into `Logs_
   added in worker2 on 2026-09-16, or the block silently under-covers the protected set.
 - **ops** — rotate every secret in `tools/config.production.ini`; consider a least-privilege
   Compass account.
-
-## Change history
-
-- 2026-09-16 — Recorded that worker2's cross-region protected list **grew from four addresses to
-  six** (`ALWAYS_ACTIVE_EMAILS_BOTH` + `ALWAYS_ACTIVE_EMAILS_CA`), so this tool's
-  `isCrossRegionProtectedEmail()` block now under-covers it: the two new `@compassdigital.io`
-  Canada-protected addresses can still be email-edited here and would silently drop out of the
-  protected set, because the worker2 match is on email. No `tools` code changed. Detail:
-  [PEOPLE-File User Lifecycle](../../../clients/compass-usa/features/people-file-user-lifecycle.md).
-  (bala)
-
-- 2026-09-04 — Added **email, phone and cost-center editing** (PR tools#14,
-  `feature/compass-user-field-edits`, **open / not merged / not deployed**): new `App_Compass`
-  setters plus the `normaliseEmail` / `normalisePhone` / `emailDomainIsRegistered` /
-  `usersWithEmail` / `isCrossRegionProtectedEmail` validators, a cost-center picker with a mandatory
-  before/after persona diff, and a `Users` + primary `Contacts` write in one transaction. No schema
-  change. Recorded the decision to ship **all three** fields against independent
-  architecture/security advice to defer email, and that the six safety rails (typed twice,
-  `Core.ClientEmailDomains` domain check, cross-row duplicate refusal, duplicate-twin confirmation,
-  cross-region address block, audit-before-write) are the conditions of that decision. Recorded that
-  **cost-center edits are deliberately temporary** because `c_erpSystemEntityId` is not overwritten.
-  **Resolved the "no staff-actor audit trail" open item** — `Logs_<Tenant>.Record.userId` is
-  nullable, so `recordId = 2` (`Users`) + `primaryKeyId` + staff identity in `note` works with no
-  schema change (`note` is 255 **characters** — truncate with `mb_substr`); hence the new
-  `[database_compasslogs]` / `[database_compasscanadalogs]` ini sections, still on the existing
-  `[database_true]` account. Prod-verified that **neither tenant has a `UNIQUE KEY` on
-  `Users.email`**, so the duplicate check must live in code, and that `compass-canada.com` is
-  registered to Compass **USA** (client 2), so an email-domain allowlist must span both Compass
-  clients. Marked PR tools#13 **merged** and the doc `active`. (ajean)
-- 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/worker/INDEX.md

@@ -6,7 +6,7 @@
 | [Canon received-PO → NetSuite sales order sync](features/canon-received-po-netsuite-order-sync.md) | Canon-only worker cron that reads Vision customer POs and creates the matching NetSuite sales order (bundles exploded, prefixes stripped); open before touching |
 | [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | Worker cron emailing ops the "Compass Refresh Exception Report" of `MA%` Compass sales orders whose ODP NetSuite order isn't created yet; open for the two-hop b |
 | [Compass Manager Approval Reminder Emails (1.0 worker crons)](features/compass-manager-approval-reminder-emails.md) | Two per-tenant Compass worker crons that email approvers about sales orders awaiting a decision; open before touching the approval `orderUrl` (both still send a |
-| [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. |
+| [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA + Canada per-package in-transit and delivered emails; open for the two-pass drain, the ASN-vs-TrackingNumbers window clock, the recipient fallback, |
 | [Elite TOGA 2.0 → TOGaDeskSupport Standalone Attachment Sync](features/elite-togadesk-attachment-sync.md) | Standalone 5-min Elite cron that downloads Freshservice-origin file attachments from TOGA 2.0 (`sourceUrl` S3) into TOGaDeskSupport; open for the uuid-resolutio |
 | [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools (`test/@dave/`, `tools/bin/forecast/`) that audit and repair drift between the prod `Forecast` DB and NetSuite; open when reconciling Sales / OpenOrde |
 | [Forecast2 Supporting-Records Nightly Import (1.0 cron) — Customers & ConsolidatedCustomers](features/forecast2-supporting-records-import.md) | Nightly 1.0 cron that pulls Forecast2 lookup/dimension tables (Accounts, Classifications, Customers, ConsolidatedCustomers, Employees) from NetSuite; open when |

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

@@ -30,6 +30,8 @@ related:
   - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
 ---
 
+Compass USA + Canada per-package in-transit and delivered emails; open for the two-pass drain, the ASN-vs-TrackingNumbers window clock, the recipient fallback, and the many freeze/backlog gotchas.
+
 ## Summary
 
 Compass USA and Compass Canada send a **per-package** in-transit email (and a matching
@@ -39,7 +41,9 @@ cron builds three zones: **Items in this shipment** (just that package), **Alrea
 and earlier packages). The dynamic HTML is injected into a stored `EmailTemplates` body via the
 `sendEmail` scripted API. Canada renders EN or FR per the user's language setting.
 
-## Key files / entry points
+## How it works
+
+### Key files / entry points
 
 - `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
@@ -55,7 +59,7 @@ and earlier packages). The dynamic HTML is injected into a stored `EmailTemplate
 - Shared helper set in each cron: `getOrderFulfillmentData`, `buildItemRowsHtml`,
   `buildSectionHeaderHtml`, `buildPackageBlockHtml`, `buildTrackingUrl`, `buildOrderItemsHtml`.
 
-## How it works
+### Mechanics
 
 1. **Driving query** finds shipped sales orders and their tracking numbers (`computedStatusSlug
    = 'shipped'`, `c_dtInTransitEmailSent IS NULL`, rolling date window on
@@ -214,7 +218,7 @@ the tracking number as emailed (it retries next run).
   `#111928`; P/N `#666666`; Qty regular dark `#111928`.
 - **20px** gap between consecutive "Already shipped" packages (16px spacer + 4px heading top).
 
-## Data model
+### Data model
 
 - `TrackingNumbers`: `number`, `trackingUrl`, `shippingCarrierId`, `dtCreated`, `status`,
   `c_dtInTransitEmailSent` (the idempotency flag the cron sets).
@@ -223,7 +227,7 @@ the tracking number as emailed (it retries next run).
   bridge). `ItemFulfillments.salesOrderId` ties a package to the buyer SO.
 - `EmailTemplates` — the stored template body with `{placeholder}` tokens.
 
-## Client variations
+### Client variations
 
 - **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()`,
@@ -350,74 +354,7 @@ the tracking number as emailed (it retries next run).
   tracking-numbers today; the plan (not built) is to move this email logic into a Compass `postPut`
   interceptor and retire this 1.0 cron.
 
-## Change history
-- 2026-09-16 — **Re-anchored the in-transit window on `AdvanceShippingNotices.dtCreated`** (was
-  `TrackingNumbers.dtCreated`, `update_salesorder_status_from_odp.php` line ~432);
-  `IN_TRANSIT_EMAIL_LOOKBACK_DAYS` stays 7 with a comment explaining why. Cause: commit `81824325`
-  (2026-09-15 11:35) cut the lookback 14 → 7 while the window still measured the **invoice** date,
-  so 22 shipments invoiced 2026-09-03 whose ASNs landed 2026-09-15 fell out of the window (only
-  MR245462 still owed a real email; the other 21 read DELIVERED). Verified on prod: 22 rows in,
-  0 rows lost, 1 catch-up email. **Corrected the old "invoice tracking numbers never touch the ASN
-  chain" gotcha** — the invoice sync is in fact the normal origin of Compass `TrackingNumbers` rows;
-  new doc
-  [tracking-number origin and the ASN link](../../../clients/compass-usa/features/tracking-number-origin-and-asn-link.md).
-  Recorded the **rejected** alternative of making 3b email for pre-existing tracking numbers (it
-  would downgrade split orders from the partial template to the plain one). Not yet committed or
-  deployed. (bala)
-
-- 2026-09-10 — Recorded that a zero-line-item ASN is invisible to this cron (candidates come from
-  `AdvanceShippingNoticeItemUnits(_TrackingNumbers)`), the failure mode Compass Canada's G&T
-  importer produced until 2026-09-08. (bala)
-
-- 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
-  `shipped`, and the pendingFulfillment gate was left byte-identical. No code change here. (bala)
-
-- 2026-08-24 — Recorded the **conflict with the new 2.0 platform-wide tracking-status refresh**: that
-  refresh writes `TrackingNumbers.status` via api2 PUT for all clients, and this cron's delivered
-  UPDATE is guarded by `WHERE status <> 'DELIVERED'` — so if the refresh marks a Compass row
-  `DELIVERED` first, the delivered email never sends. Noted there is no `postPut` interceptor on
-  tracking-numbers and the plan to move this email logic into a Compass `postPut` interceptor and
-  retire this cron. Added `send_delivered_email.php` to the file list. (bala)
-- 2026-08-03 — Compass Canada **item rows are now localized**: titles resolved from the
-  `ItemTranslations` sidecar (two-column select + PHP fallback, never a mixed-collation SQL
-  `COALESCE`) and translated `N/P` / `Qté` labels; language resolution moved onto the shared 1.0
-  helper `App_Client_CompassCanada::resolveUserLanguageCode()` with `try/catch` → English at every
-  call site so a lookup failure can't abort the rest of the run. Item text is entity-escaped for the
-  iso-8859-1 send. Flagged the **`library` deployment dependency** (uncommitted on `_production`;
-  all 8 Canada crons fatal without it). TRUE-80543, not yet deployed. Detail lives on
-  [Compass Canada French order emails](../../../clients/compass-canada/features/french-order-email-localization.md). (bala)
-- 2026-06-18 — Switched Canada `getOrderFulfillmentData` from the ASN chain to the
-  `ItemFulfillmentItems` line bridge (match Compass USA); item info all 14px. (bala)
-- 2026-06-18 — Brought both prod crons to parity: per-package partial assembly, `buildTrackingUrl`
-  carrier-URL precedence, POST body transport + `throwExceptionOnApiError=true`, mark-sent only
-  on success; restored crons after a git stash/merge had duplicated helper functions. (bala)
-- 2026-06-17 — Styling pass: 18px headers, medium dark item titles, regular dark Qty, 20px
-  between packages. (bala)
-
-## Related docs
+## Related
 
 - `2.0/apps/_underscore/features/email-template-sending.md` — the `sendEmail` scripted API +
   its silent-failure hardening.

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

@@ -2,7 +2,7 @@
 
 | Doc | Summary |
 |-----|---------|
-| [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. |
+| [API (api2 / TOGa API v2) Architecture](architecture.md) | Backend for the public TOGa 2.0 API — metadata/ACL-driven REST JSON (`/v2`) + a cXML gateway, both over `_underscore` `_Model`; open for the response-envelope c |
 | [API-Key Authentication (/v2/auth/api) and what a key can actually reach](features/api-key-authentication-and-scoping.md) | How a machine caller gets a bearer token from `POST /v2/auth/api` and exactly what that key can reach; open when scoping an API consumer or auditing what a key |
 | [API Payload Interceptors (metadata-registered prePost/postPut model hooks)](features/api-payload-interceptors.md) | How `_Model` prePost/postPost/prePut/postPut hooks are dispatched by the api2 /v2 engine only when a metadata row exists — the missing-row silent no-op, the wro |
 | [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | The scatter-gather engine that returns one entitled user's records across many client DBs from a single GET (triggered by a `client` query option); open when wo |