toga-ai 1.0.792 → 1.0.794

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-04
+updated: 2026-09-10
 owners: ["bala"]
 files:
   - worker/crons/toga2/compass/update_salesorder_status_from_odp.php
@@ -209,6 +209,14 @@ the tracking number as emailed (it retries next run).
   [Compass Canada French order emails](../../../clients/compass-canada/features/french-order-email-localization.md).
 
 ## Gotchas / known issues
+- **An ASN with zero line items is invisible to this cron — no partial in-transit and no delivered
+  email, and no error.** Candidates are selected through `AdvanceShippingNoticeItemUnits` +
+  `AdvanceShippingNoticeItemUnits_TrackingNumbers`, so an ASN whose `AdvanceShippingNoticeItems` is
+  empty can never reach it. Compass Canada's G&T importer produced exactly that class of ASN until
+  2026-09-08 (validation guard sat inside the serial-number branch) — the shipment looked real and
+  the customer was never told. When a Compass order is "shipped but no email", check for an empty
+  ASN before looking at this cron. See
+  [G&T ASN Import](../../../clients/compass-canada/features/grand-and-toy-asn-import.md).
 
 - **⚠ A cron filename containing `&` cannot run at all.** `worker/ebs/cron.worker.php:41` builds
   the crontab command by plain unquoted concatenation
@@ -284,6 +292,9 @@ the tracking number as emailed (it retries next run).
   interceptor and retire this 1.0 cron.
 
 ## Change history
+- 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

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -5,7 +5,7 @@
 | [TOGa Commerce (toga2-commerce / commerce2-react) Architecture](architecture.md) | `toga2-commerce` (npm package name **`commerce2-react`**, product name **TOGa Commerce**) is the customer-facing **B2B commerce storefront** of the 2.0 platform |
 | [Bundle item visibility & selectability (the three flags, and why they are enforced nowhere but the client)](features/bundle-item-visibility-and-selectability.md) | Which components of a kit a shopper can see and choose is decided **entirely in the browser**. |
 | [Cart Bundle Submission & the bundleUuid Identity Contract](features/cart-bundle-submission-and-identity.md) | How cart **bundles** (kits) are turned into `SalesOrderItems` when a cart is submitted or an existing order is edited, and the **identity-field contract** every |
-| [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. |
+| [Cart Notification Emails — auto-add/remove lifecycle + duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. |
 | [Cart Order-Total & Shipping Computation](features/cart-order-total-computation.md) | The Cart summary section (subtotal / shipping / tax / total) is **data-driven** from `cartData`. |
 | [Cart Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. |
 | [Catalog cache freshness — the 24h persisted query cache, and how to opt a query out of it](features/catalog-cache-freshness.md) | TOGa Commerce runs a **single `QueryClient` with a 24-hour default `staleTime`**, and persists it to **`localStorage["commerce"]`** through `PersistQueryClientP |

package/knowledge/2.0/apps/toga2-commerce/features/cart-notification-emails.md

@@ -1,16 +1,18 @@
 ---
-title: Cart Notification Emails — duplicate prevention
+title: Cart Notification Emails — auto-add/remove lifecycle + duplicate prevention
 framework: "2.0"
 repo: toga2-commerce
 project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-07-27
+updated: 2026-09-10
 owners: ["bala", "tcox"]
 files:
   - src/pages/Cart/CartPage.tsx
   - src/pages/Cart/view/cartForm/CartForm.tsx
+  - src/pages/Cart/view/cartForm/EditCart.tsx
+  - src/pages/Cart/view/cartForm/EditOrder.tsx
   - src/stores/useEmailOptionsStore.ts
   - src/stores/useCartSalesQuoteZu.ts
   - src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts
@@ -21,12 +23,19 @@ related:
 ---
 
 ## Summary
-On the cart "Notifications" section a user can add CC email addresses to an order. Adding the
-same address twice (often with different casing) used to slip through to the API and blow up on
-submit with a MySQL 1062 duplicate-key error on the `SalesOrderEmailAddresses.salesOrderId_emailAddress`
-unique index (whose collation `utf8mb4_0900_ai_ci` is case-insensitive). This feature blocks
-duplicates case-insensitively in the frontend and shows a sapphire info message instead of letting
-the error reach the user.
+On the cart "Notifications" section a user can add CC email addresses to an order. Two jobs live
+here:
+
+1. **Duplicate prevention.** Adding the same address twice (often with different casing) used to
+   slip through to the API and blow up on submit with a MySQL 1062 duplicate-key error on the
+   `SalesOrderEmailAddresses.salesOrderId_emailAddress` unique index (collation
+   `utf8mb4_0900_ai_ci` is case-insensitive). The frontend blocks duplicates case-insensitively and
+   shows a sapphire info message instead of letting the error reach the user.
+2. **Auto-add/remove lifecycle.** Picking an **order-for user** or a **Delegate Manager**
+   auto-adds their notification emails. **Changing the pick must remove the previous person's
+   auto-added emails.** Until 2026-09-10 it did not: the old person and their manager stayed in the
+   list, still checked, and still in the submit payload — so notifications went to the wrong
+   people unless the buyer noticed and unchecked them.
 
 ## Key files / entry points
 - `CartPage.tsx` — `handleAddEmail`: validates the email regex, then on success calls
@@ -35,10 +44,23 @@ the error reach the user.
 - `CartForm.tsx` — owns the duplicate UX. `handleAddEmailWithDuplicateCheck` wraps the passed-in
   `handleAddEmail`: it case-insensitively checks the existing `emails` list and, on a match, shows
   the message instead of adding. The **Add Email** button calls this wrapper.
-- `useEmailOptionsStore.ts` — `addEmailOption` de-dupes the checkbox list.
-- `useCartSalesQuoteZu.ts` — `addEmail` de-dupes the actual `salesOrderEmailAddresses` payload.
+- `CartPage.tsx` — also owns the **Delegate Manager** lifecycle:
+  `advancedSelectConfig.delegateManager.onSelect` / `.onClearInput`, the
+  `lastDelegateManagerEmailRef` (useRef), the `removeDelegateManagerEmail` guard, the
+  `watch("hasDelegateManager")` and `watch("delegateManager")` effects, and `handleClearUser`.
+- `EditCart.tsx` — cart-checkout mode. The order-for change effect (`onSuccess` of the user fetch)
+  owns add **and** remove of the order-for user's emails, plus the local `ensureEmailSelected`
+  helper and the `orderForUserChanged` flag.
+- `EditOrder.tsx` — edit-order mode. Still has the **original add-only** order-for pattern.
+- `useEmailOptionsStore.ts` — `addEmailOption` de-dupes the checkbox list; `removeEmailOption`
+  removes case-insensitively; `selectEmailOption(email)` marks an option checked (idempotent —
+  never toggles).
+- `useCartSalesQuoteZu.ts` — `addEmail` de-dupes and `removeEmail` removes from the actual
+  `salesOrderEmailAddresses` payload, both case-insensitively.
 
 ## How it works
+
+### Duplicate prevention
 1. **Before (manual add):** clicking Add Email runs `handleAddEmailWithDuplicateCheck` in
    `CartForm`. It compares `(e.email ?? "").trim().toLowerCase()` against the normalized input. On a
    match it sets `duplicateEmailMessage` and returns (does not add).
@@ -53,6 +75,41 @@ the error reach the user.
 5. A `useEffect` clears the message when the input, selected user (`orderForUser?.uuid`), or email
    list (`emails.length`) changes.
 
+### Order-for user — add AND remove (`EditCart.tsx`, cart-checkout mode only)
+Auto-added set per user: **their email**, `supervisorUser.email`, and
+`c_supportedByUserId.email`.
+
+1. On success of the order-for user fetch, read the **previous** user from
+   `useSelectedUserZu.getState().selectedUser` — the store, **not** the render closure (the closure
+   is stale inside the query callback).
+2. If the previous uuid differs from the new one (`orderForUserChanged`), remove that person's three
+   auto-added addresses from **both** `useEmailOptionsStore` and
+   `useCartSalesQuoteZu.salesOrder.salesOrderEmailAddresses`. **Never remove the logged-in user's
+   own address** even if it matches one of the three.
+3. Re-seed the new user's addresses through the local **`ensureEmailSelected(email)`** helper:
+   `addEmailOption` → `selectEmailOption` → `addEmail`. Idempotent, so re-running it is safe.
+4. The seeding block runs when `salesOrderEmailAddresses` is empty **or** when
+   `orderForUserChanged`. Before the fix it ran only on empty, so the second pick's emails were
+   added **un-checked** and never reached the payload.
+
+### Delegate Manager email lifecycle (`CartPage.tsx`, cart-checkout mode)
+"Associate" in the Compass UI = Delegate Manager. Its email is tracked by
+**`lastDelegateManagerEmailRef`** (a `useRef`), because the form value cannot be used (see
+Gotchas). The email is parsed out of the option label, which has the shape
+`"First Last (email)"`.
+
+| Action | What happens |
+|---|---|
+| Pick a manager | `onSelect` removes the *previous* ref email if different, adds the new one checked, sets the ref |
+| Click the field's **X** | `onClearInput` removes the ref email and clears the ref |
+| Un-check "has delegate manager" | the `watch("hasDelegateManager")` effect removes the ref email and empties the field |
+| Clear the order-for user | `handleClearUser` also un-checks the box, empties the field, and clears the ref |
+| Restore a saved cart | the `watch("delegateManager")` effect seeds the ref; a restored name has no `"(email)"`, so it falls back to `salesOrder.approvalUser.email` |
+
+**`removeDelegateManagerEmail` never removes an address that is also** the order-for user's, their
+supervisor's, their support tech's, or the logged-in user's — those are owned by the order-for
+lifecycle above.
+
 ## Data model
 Frontend only. The payload list maps to the `SalesOrderEmailAddresses` table (api2/backend), which
 has a case-insensitive unique index on `(salesOrderId, emailAddress)`.
@@ -67,19 +124,57 @@ the message resolves to `undefined` and renders blank.
 - The real source of the 1062 was `useCartSalesQuoteZu.addEmail` comparing with `===`
   (case-sensitive). Both stores must compare case-insensitively; fixing only the UI list is not
   enough because `addEmail` builds the payload.
+- **Removes must be case-insensitive too, not just adds.** Both stores' *adds* were already
+  case-insensitive while their *removes* used exact match, so a hand-typed `Bob@X.com` survived a
+  remove of `bob@x.com` and shipped in the payload. `removeEmailOption` and `removeEmail` are now
+  case-insensitive.
+- **`handleEmailChange` TOGGLES — never use it to seed.** Re-running it on an already-checked
+  address **un-checks** it. Use the idempotent `ensureEmailSelected` /
+  `selectEmailOption` path for any auto-seeding.
+- **`CartFormSection` overwrites the form value BEFORE your handler runs.** It calls
+  `field.onChange(value)` and *then* `config.onSelect(value, valueKey)` (same for
+  `field.onChange(null)` before `config.onClearInput`). So
+  `formMethods.getValues("delegateManager")` inside those handlers already holds the **new** value
+  — you **cannot** read the previous pick from the form. Keep the previous value in a `useRef`.
+- **Read the previous order-for user from the store, not the closure.** Inside the user-fetch
+  `onSuccess` the render closure's `selectedUser` is stale; use
+  `useSelectedUserZu.getState().selectedUser`.
+- **`delegateManager` defaults to a truthy object** (`{uuid:"",name:""}`) now that it is a typed
+  form field, so `if (formValues.delegateManager)` is always true. Check
+  `formValues.delegateManager?.uuid` instead (3 call sites: `EditCart.tsx` ×2, `EditOrder.tsx` ×1).
+- **`EditOrder.tsx` (edit-order mode) still has the add-only order-for pattern** — the same
+  wrong-recipient bug very likely exists there. Left alone deliberately: edit-order has different
+  manager rules (`assignedTo`). Fix it as its own task.
 - Normalize with `(x ?? "").trim().toLowerCase()`, not `x?.trim().toLowerCase()` — both are
   nullish-safe (optional chaining short-circuits the whole chain, it does not throw), but `(x ?? "")`
   guarantees a string and avoids an `undefined === undefined` match edge.
 - Adding the label to only some `CARTPAGE.ts` files leaves other client/role/language users with a
   blank message.
 - Do not use a toaster or `setError` (red) for this — product wants the sapphire info style.
-- **Now pinned by e2e.** `cypress/e2e/cartPage/cartV2.cy.ts` covers both the auto-population
-  (order-for user + supervisor emails, protected rows unremovable) and the case-insensitive
-  duplicate block surfacing the *"This email has already been added"* banner. These are exactly
-  the parity behaviors the config-cart refactor spike silently lost, so keep the spec green when
-  touching this flow (see [cypress-testing](../workflows/cypress-testing.md)).
+- **e2e coverage is branch-dependent — check before you rely on it.** On `_production`,
+  `cypress/e2e/cartPage/cartV2.cy.ts` covers both the auto-population (order-for user + supervisor
+  emails, protected rows unremovable) and the case-insensitive duplicate block surfacing the
+  *"This email has already been added"* banner — the exact parity behaviors the config-cart
+  refactor spike silently lost, so keep it green (see
+  [cypress-testing](../workflows/cypress-testing.md)). But on `#sprint86` that file **does not
+  exist** and every spec in `cypress/e2e/cartPage/cart.cy.ts` is **commented out**, so there is no
+  net for this flow there. Verify manually on such a branch.
+- **ESLint cannot run in this repo checkout** (pre-existing): `.eslintrc.cjs` references
+  `eslint-plugin-react-compiler`, which is not installed. Type-check with
+  `npx tsc --noEmit -p tsconfig.app.json` instead.
 
 ## Change history
+- 2026-09-10 — FIXED: changing the order-for user or the Delegate Manager left the previous
+  person's auto-added emails checked and in the submit payload, so notifications went to the wrong
+  people (reported by a Compass USA user on `compass.togacommerce.com`; fix is client-neutral).
+  Order-for path (`EditCart.tsx`) now removes the prior user's three auto-added addresses and
+  re-seeds via the idempotent `ensureEmailSelected` (replacing the toggling `handleEmailChange`),
+  and seeds on `orderForUserChanged` as well as on empty. Delegate Manager path (`CartPage.tsx`)
+  gained `lastDelegateManagerEmailRef` + `removeDelegateManagerEmail` covering pick / re-pick / X /
+  un-check / clear-user / restore. Stores: added `selectEmailOption`, made `removeEmailOption` and
+  `removeEmail` case-insensitive. `hasDelegateManager` / `delegateManager` are now typed form fields
+  with defaults, so delegate checks moved to `?.uuid`. Edit-order mode not fixed (different manager
+  rules). (tcox)
 - 2026-07-27 — No behavior change. This duplicate-prevention UX (email auto-population +
   case-insensitive duplicate banner) is now covered by cart e2e slice 1 (`cartV2.cy.ts`); linked
   the [cypress-testing](../workflows/cypress-testing.md) workflow doc. (tcox)

package/knowledge/2.0/apps/toga2-commerce/features/cart-page-config-architecture.md

@@ -6,7 +6,7 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-07-27
+updated: 2026-09-10
 owners: ["apeterson", "tcox"]
 files:
   - src/pages/Cart/CartPage.tsx
@@ -85,6 +85,17 @@ based on `inEditMode`. `CartFormRenderer.tsx` exists only on the `implement-conf
   Two mode-change `reset()` effects (~lines 267, 282) re-seed from that same union shape. This is
   wrong for per-client field sets: it registers fields a client never renders and bakes one client's
   default into all of them, and risks RHF controlled/uncontrolled warnings.
+  As of 2026-09-10 `hasDelegateManager` (`false`) and `delegateManager` (`{uuid:"",name:""}`) are
+  part of that union and are typed in `CartFormFieldNames` — previously they were undefined and
+  untyped. Because the default object is **truthy**, any check on the field must test
+  `delegateManager?.uuid`, not the object.
+- **`CartFormSection` runs `field.onChange` BEFORE the config handler.** For an `advancedSelect` it
+  calls `field.onChange(value)` then `config?.onSelect(value, valueKey)` (and
+  `field.onChange(null)` then `config?.onClearInput(valueKey)`). So a config handler can never read
+  the field's **previous** value from the form — it is already overwritten. Handlers that need the
+  prior pick must keep it in a `useRef` (see
+  [cart-notification-emails](cart-notification-emails.md) for the Delegate Manager case). The
+  planned `hydrateCartConfig` (Phase 5) must preserve this ordering contract or document a change.
 - **Client differences are hardcoded, not config.** Examples observed: COMPASS renders
   `DuplicateKitGuardrail`, QUAD does not; COMPASS seeds the cart form (cost center / manager / emails)
   from the order-for user, QUAD does not. These are per-client conditionals in cart code today.
@@ -285,6 +296,11 @@ extension** of toga2.5's philosophy, not a literal copy.
    edit-order mode?
 
 ## Change history
+- 2026-09-10 — Two gotchas added from cart-notification work: `hasDelegateManager` /
+  `delegateManager` are now typed form fields in the union `defaultValues` (truthy default → check
+  `?.uuid`), and documented that `CartFormSection` calls `field.onChange` **before** the
+  `advancedSelect` config's `onSelect`/`onClearInput`, so a handler cannot read the field's previous
+  value. No refactor progress. (tcox)
 - 2026-07-27 — Phase 0 oracle is now partly real: cart e2e slice 1 (`cartV2.cy.ts`, 12 tests)
   landed and pins the exact parity behaviors the prior spike lost (notification-email
   auto-population, duplicate-email surfacing) plus render/gating/clear/empty flows. Corrected the

package/knowledge/clients/compass-canada/features/grand-and-toy-asn-import.md

@@ -5,11 +5,12 @@ project: _Underscore
 client: compass-canada
 type: client-feature
 status: active
-updated: 2026-08-20
+updated: 2026-09-10
 owners: ["bala"]
 files:
   - api2/Component/Api/Cxml/Cxml.php
   - worker/crons/toga2/compasscanada/workflow/3_import_grand_and_toy_advance_shipping_notices.php
+  - worker/crons/toga2/compasscanada/workflow/check_grand_and_toy_inbox.php
   - worker/crons/toga2/compasscanada/workflow/import_grand_and_toy_asn_from_file.php
   - worker/crons/toga2/compasscanada/workflow_beta/import_grand_and_toy_asn_from_file.php
   - worker/schedules/cron.worker.sync.json
@@ -21,6 +22,7 @@ related:
   - ../workflows/grand-and-toy-asn-backfill.md
   - ../../../2.0/apps/api2/features/cxml-shipnotice-gateway.md
   - ../../compass-usa/features/asn-to-item-fulfillment.md
+  - ../../../1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md
 ---
 
 ## Summary
@@ -30,10 +32,19 @@ G&T's ASN CSV from a mailbox, posts each shipped line to the 2.0 API as an Advan
 an in-transit email in English or French. It mirrors the Compass USA ODP / Strategic-Systems ASN
 flow, adapted for Canadian carriers and bilingual email.
 
-**The live path today is cXML, not the CSV cron.** G&T transmits ship notices to the api2 cXML
-gateway (`cxml-writer`), which translates them into the same `POST /v2/advance-shipping-notices`.
-The 24-column CSV cron below is **retired** — it remains documented because it is the only source of
-serial numbers and the reference for the field mapping.
+**Both transports are live — the CSV cron is NOT retired (corrected 2026-09-10).** G&T transmits
+ship notices to the api2 cXML gateway (`cxml-writer`), which translates them into the same
+`POST /v2/advance-shipping-notices`. **In parallel**, G&T emails the 24-column CSV and the 1.0
+worker cron `3_import_grand_and_toy_advance_shipping_notices.php` still runs on schedule
+(`0 */4 * * *`, six runs a day) and was fixed and deployed to production on **2026-09-08**. The CSV
+cron matters for two reasons beyond the field mapping: it is the **only source of serial numbers**,
+and it is the **only thing that sends the in-transit email** (api2 does not — see *In-transit email
+is owned by the cron*).
+
+> **The importer was renamed** `4_import_grand_and_toy_advance_shipping_notices.php` →
+> `3_import_grand_and_toy_advance_shipping_notices.php` (commit `d38d0c33`) and
+> `worker/schedules/cron.worker.sync.json` was repointed. Any older note referring to the `4_` name
+> is stale.
 
 > ### Outage 2026-03 to 2026-08-20 — two stacked defects, 518 shipments lost
 >
@@ -86,7 +97,10 @@ serial numbers and the reference for the field mapping.
 3. **Before the row loop** — build three lookup maps once per file: `$purchaseOrderUuidByNumber`
    (`SELECT number, uuid FROM PurchaseOrders`), `$shippingMethodByCarrierId`, `$carrierIdByName`.
 4. Per row: validate PO / part / tracking (early `continue` with error recording on missing
-   critical fields); look up SO + contact user + CC addresses; resolve carrier →
+   critical fields). **The item lookup (`PurchaseOrderItems` → `VendorItems.vendorPartNumber` →
+   `Items.id`, PO-scoped) runs for EVERY row, before anything is written** — it is not inside the
+   serial-number branch (see the 2026-09-08 zero-line-item gotcha). Then look up SO + contact user
+   + CC addresses; resolve carrier →
    Ground shipping method (falls back to `DEFAULT_GROUND_SHIPPING_METHOD_ID = 3`); upsert
    `TrackingNumbers`; resolve item by `Items.partNumber` joined through `VendorItems`; find-or-create
    a `Units` row per serial.
@@ -113,6 +127,67 @@ serial numbers and the reference for the field mapping.
 - Interceptor wiring: `Core.RecordScripts` + `Core.ApiPayloadInterceptors`, `recordId 55`
   (AdvanceShippingNotice). The `sendEmail` POST record script is `Core.RecordScripts recordId 202`.
 
+## CSV file shape — what silently rejects a whole file
+
+The importer's only file-level gate is the **column count of the first line, which must be exactly
+24**. It does **not** check the file name, the extension, or the header names — every field is read
+**by position**. Consequences seen live (three real files rejected in a row, 2026-09-03 → 2026-09-08):
+
+- An Apple **`.numbers`** file is a zip (first bytes `PK`), so line 1 parses as **1 column** → whole
+  file rejected.
+- A CSV **exported from Numbers** carries the sheet-name **title row on line 1**, which is also
+  **1 column** → whole file rejected, even though the real 24-column header sits on line 2.
+- Rejection sends the *"CompassCanada G&T ASN: Unexpected column count, file not processed"* email to
+  `vburks@togatech.com` + `devTeam@togatech.com` and the file is skipped. Nothing is imported.
+
+**The cron drains the mailbox on every run.** Each message is moved out of INBOX after processing —
+to **ARCHIVE** when it carried an attachment, to **Junk Email** when it did not. So a file that
+already ran is never in INBOX; look in ARCHIVE. Schedule is `0 */4 * * *` in
+`worker/schedules/cron.worker.sync.json` (six runs a day, on the hour), and the worker server clock
+is **America/Chicago** (set by `App_Framework::cronInitialization`). Run history for any 1.0 worker
+cron is in the legacy **`Common.CronJobExecutions`** table (`job` = the script path, `dtCheckIn` /
+`dtCheckOut`) — see [Cron Execution Monitoring](../../../1.0/apps/library/features/cron-execution-monitoring.md).
+
+## Reading the mailbox without touching it (`check_grand_and_toy_inbox.php`)
+
+Because the cron drains INBOX, there was no way to answer *"did G&T actually mail a file?"*.
+`worker/crons/toga2/compasscanada/workflow/check_grand_and_toy_inbox.php` is a **read-only
+inspector** for `compasscanada.status@togatech.com`. It opens `INBOX`, `ARCHIVE` and `Junk Email`
+with `OP_XOAUTH2 | OP_READONLY` and **never moves, deletes, imports or emails anything**, so it is
+safe to run in production.
+
+Per attachment it reports: byte size; the first line's column count against the 24-column contract;
+the first 3 lines each with their own column count (a stray title row is the usual culprit); and a
+**row-level dry run** mirroring the importer's per-row guards — importable / no tracking / no PO /
+no part number / scientific-notation tracking / electronic delivery. `--save=<folder>` dumps each
+attachment to disk for offline checking. It reads the Azure OAuth values **out of the importer file
+at runtime** rather than duplicating the client secret.
+
+Two 1.0 IMAP gotchas encoded in it (they cost real time to find):
+- **`imap2_headerinfo()` fails on this setup** — it needs `ZBateson\MailMimeParser`, which is not
+  installed. Read raw headers with **`imap2_fetchheader()`** and parse `Date` / `From` / `Subject`
+  with a regex instead.
+- **`App_Framework::registerPhpImap2()` does not load `php-imap2/src/Polyfill.php`**, so loading
+  that file does not give you `imap2_headerinfo()` either.
+
+## In-transit email is owned by the cron, not api2
+
+The importer sends the Compass Canada in-transit email itself and stamps
+`TrackingNumbers.c_dtInTransitEmailSent`, guarded by
+`if (!empty($salesOrderNumber) && $isNewTrackingNumber)`. So **the email fires only when the cron
+creates a brand-new `TrackingNumbers` row.** Two practical consequences:
+
+1. **Never delete a `TrackingNumbers` row during cleanup.** A replay then recreates it as new and
+   sends a **duplicate** in-transit email to that contact. Keep the row and its
+   `c_dtInTransitEmailSent` stamp instead.
+2. **Posting an ASN by hand through api2 emails nobody**, because the send lives in the cron. Useful
+   for a silent data repair, and the reason a hand-posted ASN looks "complete but nobody was told".
+
+Downstream, `worker/crons/toga2/compasscanada/update_salesorder_status_from_g&t.php` selects its
+candidates via `AdvanceShippingNoticeItemUnits` + `AdvanceShippingNoticeItemUnits_TrackingNumbers`,
+so an ASN with **zero items** can never reach it — no partial in-transit or delivered email either.
+See [Compass Partial In-Transit & Delivered Emails](../../../1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md).
+
 ## The cXML documents G&T actually sends
 
 Measured across **all 1,074** stored documents in `Logs_CompassCanada.Api` — the shape never varies:
@@ -161,6 +236,13 @@ created and linked to the ASNIU, and interceptor **55** then propagates it to
 `ItemFulfillmentItemUnits`. Verified in prod (Units row created + linked, IFIU populated).
 
 Constraints:
+- **A bare `unit.uuid` will NOT create the Unit.** Posting
+  `advanceShippingNoticeItemUnits[].unit.uuid` for a uuid that has no `Units` row returns
+  **400 `EV-12`** *"unable to find a unique match based on the provided search criteria"* on field
+  `unit` — api2 only *resolves* an existing Unit by uuid. `MATCH_UPSERT` can only create when the
+  nested object carries enough to build the row (`itemId` + `serialNumber`). The CSV importer works
+  around this by `INSERT`ing the `Units` row itself (`uuid`, `itemId`, `dtUpdated`, `serialNumber`)
+  **before** it builds the payload, so **any manual replay must create the Unit first**.
 - `Units.itemId` is **NOT NULL**, so the item must be supplied.
 - The `Units` identifiers are `uuid`, `itemId`, `serialNumber`, `assetTag`, `vendorId`, `macAddress`
   — so **item + serialNumber** gives find-or-create on that pair.
@@ -174,6 +256,21 @@ Compass-Canada-specific; parallels Compass USA's ODP / Strategic-Systems ASN imp
 a bilingual EN/FR in-transit email (USA is English only) and uses Canadian carriers.
 
 ## Gotchas / known issues
+- **⚠ A validation guard placed inside the serial-number branch produced ASNs with ZERO line
+  items, silently (fixed + deployed to prod 2026-09-08).** The PO-scoped part-number lookup
+  (`VendorItems.vendorPartNumber` on the PO) sat **inside** `if (!empty($serialNumbersForLine))`.
+  A CSV row with **no serial number** skipped the check entirely, so the cron wrote the ASN
+  **header**, then found no PO line to attach, and left the ASN with **zero
+  `AdvanceShippingNoticeItems`**. No error was raised — it looked like a real shipment but shipped
+  nothing. A row **with** a serial hit the check and was correctly rejected into the error report.
+  **That is why one bug produced two unrelated-looking symptoms** (empty ASN vs. rejected row).
+  Fix: the lookup moved out of the serial branch so it runs for every row before anything is
+  written, and a failing row returns a validation error naming the part number and the PO. An empty
+  ASN is also invisible downstream — the status cron selects via
+  `AdvanceShippingNoticeItemUnits(_TrackingNumbers)`, so it never reaches it.
+- **⚠ The in-transit email is gated on `$isNewTrackingNumber`, so deleting a `TrackingNumbers`
+  row during cleanup re-emails the customer.** See
+  [In-transit email is owned by the cron](#in-transit-email-is-owned-by-the-cron-not-api2).
 - **⚠ `PurchaseOrderItems_SalesOrderItems` is EMPTY across ALL 865 Compass Canada purchase orders —
   this is NORMAL and must NOT be "repaired".** `_Model_Compass_AdvanceShippingNotice::postPost`
   resolves PO to SO without that bridge for this client. Inserting bridge rows to make one ASN
@@ -228,6 +325,20 @@ a bilingual EN/FR in-transit email (USA is English only) and uses Canadian carri
   before `fetchOne()`.
 
 ## Change history
+- 2026-09-10 — **Corrected the "CSV cron is retired" claim: both transports are live.** The CSV
+  importer (renamed `4_…` → `3_import_grand_and_toy_advance_shipping_notices.php`, commit
+  `d38d0c33`) still runs `0 */4 * * *` and is the only source of serials and the only sender of the
+  in-transit email. **Fixed (prod 2026-09-08) the guard-placement bug that created ASNs with zero
+  line items** — the PO-scoped part-number lookup was inside the serial-number branch, so
+  serial-less rows bypassed it; now it runs for every row before any write and returns a named
+  validation error. Documented: the file-shape rules that reject a whole file (first line only,
+  exactly 24 columns, position-based — so `.numbers` zips and Numbers-exported title rows both
+  count as 1 column); the mailbox drain to ARCHIVE / Junk Email; `Common.CronJobExecutions` as the
+  run log and the America/Chicago worker clock; the `$isNewTrackingNumber` email gate (never delete
+  a `TrackingNumbers` row, and a hand-posted ASN emails nobody); and that a bare `unit.uuid` returns
+  400 EV-12 rather than creating the Unit. Built the read-only inbox inspector
+  `check_grand_and_toy_inbox.php` with its two IMAP gotchas (`imap2_headerinfo()` needs
+  `ZBateson\MailMimeParser`; `registerPhpImap2()` skips `Polyfill.php`). (bala)
 - 2026-08-20 — **Root-caused and fixed a 67-day, 100%-rejection outage on the G&T cXML ASN feed and
   backfilled 518 shipments.** Root cause: nested tracking-number creation is governed by the
   per-API `Client_<x>.Apis_RecordFields.overrideChildPolicy`, and Canada's "Grand & Toy (Cxml)" API

package/knowledge/clients/compass-canada/profile.md

@@ -17,7 +17,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-09-04
+updated: 2026-09-10
 owners: [jcardinal, bala, tcox, apeterson, ajean]
 files: []
 related:
@@ -65,8 +65,11 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
 - **Grand & Toy (G&T)** — primary hardware vendor. SOs flow toga → MITS → PO to G&T; G&T sends
   back ASNs. ASN ingestion (email CSV + the auto-created ItemFulfillment chain + bilingual
   in-transit email) is documented in [Grand & Toy ASN Import](features/grand-and-toy-asn-import.md).
-  Vendor uuid: `App_Client_CompassCanada::UUID_VENDOR__GRAND_TOY`. **The live ASN path is cXML**
-  (api2 `cxml-writer`), not the retired 24-column CSV cron; carrier codes G&T sends are `UPS`,
+  Vendor uuid: `App_Client_CompassCanada::UUID_VENDOR__GRAND_TOY`. **Two ASN paths are live at
+  once (corrected 2026-09-10):** the api2 `cxml-writer` cXML gateway **and** the 24-column CSV
+  email cron `workflow/3_import_grand_and_toy_advance_shipping_notices.php` (`0 */4 * * *`) — the
+  CSV cron is **not** retired, and it is the only source of serial numbers and the only sender of
+  the in-transit email. Carrier codes G&T sends are `UPS`,
   `FDXH`, `PUROL`, `PRECI`, `NATEX`, `GANDT`, `DHL`, `XXXX` (placeholder, TrackingID = `DIRECT`).
   The cXML path needs **no** Ground `ShippingMethod` per carrier (`TrackingNumbers.shippingMethodId`
   is nullable and cXML sends no method) — that requirement came from the CSV cron only.
@@ -81,8 +84,11 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   client.** `postPost` resolves PO to SO without it; never insert bridge rows to "repair" an ASN
   failure here.
 - Worker crons for the G&T flow live under `worker/crons/toga2/compasscanada/workflow/`
-  (`1_…` transmit SOs to MITS, `2_…` transmit POs to vendors, `3_…` status from G&T cXML,
-  `4_…` import G&T ASNs).
+  (`1_…` transmit SOs to MITS, `2_…` transmit POs to vendors, `3_import_grand_and_toy_advance_shipping_notices.php`
+  import G&T ASNs). **The importer was renamed `4_…` → `3_…` (commit `d38d0c33`) and
+  `cron.worker.sync.json` repointed** — any note using the `4_` name is stale. SO-status updates
+  live one level up in `update_salesorder_status_from_g&t.php`, and the read-only mailbox inspector
+  is `workflow/check_grand_and_toy_inbox.php`.
 - **⚠ MITS transmit alerting has diverged from Compass USA.** Canada's `1_…transmit…to_mits`
   cron still raises all **three** of its failure alerts as in-cron `App_Email_Agilant` emails
   (No Items Found / more than 15 items / Invalid response from MITS API), so changing who is

package/knowledge/clients/compass-canada/workflows/grand-and-toy-asn-backfill.md

@@ -5,10 +5,11 @@ project: _Underscore
 client: compass-canada
 type: workflow
 status: active
-updated: 2026-08-20
+updated: 2026-09-10
 owners: ["bala"]
 files:
   - worker/crons/toga2/compasscanada/workflow_beta/import_grand_and_toy_asn_from_file.php
+  - worker/crons/toga2/compasscanada/workflow/3_import_grand_and_toy_advance_shipping_notices.php
   - api2/Component/Api/Cxml/Cxml.php
   - _underscore/Model/Compass/AdvanceShippingNotice.php
 related:
@@ -57,6 +58,41 @@ original EV-12 rejections — see
    **vendor** part number, and reference the item **by uuid only**. See the ASN-import doc's
    serial-number section for the constraints.
 
+## Route C — SQL backfill of a missing ASN line (a zero-line-item ASN)
+
+Used 2026-09-08 to repair ASNs the importer had created with **zero
+`AdvanceShippingNoticeItems`** (guard-placement bug — see the
+[import doc](../features/grand-and-toy-asn-import.md)). This route is only tractable because of one
+fact about how api2 builds the fulfillment side.
+
+**`ItemFulfillments.number` IS the sales-order number, and the column is UNIQUE.** So there is at
+most **one `ItemFulfillment` per sales order**, and when a second ASN arrives for the same SO api2
+attaches its items to the **existing** fulfillment rather than creating another one. Verified in
+prod: posting a new ASN for `SAC100689` attached to the existing `ItemFulfillment 671` instead of
+failing on a duplicate number.
+
+**Consequence — whenever the sales order already has a fulfillment, a hand backfill needs no new
+`Addresses` row and no `ItemFulfillments.number` allocation.** That matters: allocating a `SAC`
+number by hand in prod risks colliding with a live fulfillment.
+
+Rows to insert per missing ASN line:
+
+1. `AdvanceShippingNoticeItems`
+2. `AdvanceShippingNoticeItems_TrackingNumbers`
+3. `ItemFulfillmentItems`
+4. `ItemFulfillmentItems_TrackingNumbers`
+5. `ItemFulfillments_TrackingNumbers` — **only** where the fulfillment header does not already
+   carry that tracking number.
+
+**Do not delete the `TrackingNumbers` row and replay the cron instead.** The importer's email is
+gated on `$isNewTrackingNumber`, so a recreated row counts as new and sends a **duplicate**
+in-transit email to the customer. Keep the row and its `c_dtInTransitEmailSent` stamp, and repair
+the missing children around it. (Posting the ASN through api2 by hand emails nobody, because the
+send lives in the cron.)
+
+**A `Units` row must exist first** if the line is serialized — a bare `unit.uuid` in an ASN POST
+returns 400 `EV-12`, it does not create the Unit.
+
 ## Dedupe and safety guards
 
 - **`TrackingNumbers.number` carries a UNIQUE key**, so a replayed tracking number `MATCH`es rather
@@ -87,6 +123,13 @@ original EV-12 rejections — see
 - **One `TrackingID` even when `TotalPackages > 1`** — do not synthesize per-package numbers.
 
 ## Change history
+- 2026-09-10 — Added **Route C — SQL backfill of a zero-line-item ASN**, after repairing the
+  Compass Canada ASNs the importer created with no `AdvanceShippingNoticeItems`. Recorded that
+  `ItemFulfillments.number` is the sales-order number **and UNIQUE**, so there is one
+  `ItemFulfillment` per SO and api2 attaches later ASN items to it (proven in prod: `SAC100689`
+  → existing `ItemFulfillment 671`) — which means a backfill needs **no** new `Addresses` row and
+  **no** `SAC` number allocation. Listed the five row types per missing line, and the rule to
+  **keep** (never delete) the `TrackingNumbers` row so a replay cannot re-email the customer. (bala)
 - 2026-08-20 — Documented the two-route backfill after recovering the 67-day G&T outage (518
   shipments / 536 ASNs / 512 TrackingNumbers / 406 ItemFulfillments / 332 Units). Recorded the cXML
   replay source and the ~20s `maxAuthsPerHour` pacing, the three-bridge JSON payload requirement,

package/package.json

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