toga-ai 1.0.847 → 1.0.849

package/knowledge/1.0/apps/library/features/netsuite-suiteql-rest-shim.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-17
+updated: 2026-09-21
 owners: [dfranks, jcardinal, kyalamarthi, rgirish]
 files:
   - library/app/api/netsuite/rest.php
@@ -57,6 +57,7 @@ Field semantics (verified on the live account):
 - **Line number = `transactionline.id`, NOT `linesequencenumber`.** `tl.id` equals the REST `item[].line` value (the stable SOAP-era line key); `linesequencenumber` is physical order and re-maps/collides when SOAP-era records are edited. Verified: sales orders 106 orders / 344 lines (2019–2029, incl. edited orders with line-id gaps), invoices + cash sales 62/62. `listSales` historically resolved line via `uniquekey → REST lineUniqueKey → line`; `tl.id` gives the same answer in bulk without the per-id GET. **Re-confirmed at scale 2026-08-27:** the two columns diverge on **2,061 of 4,387** lines (~47%), and `Forecast.OpenOrderItems.lineNumber` (which stores REST `$line->line`) matched `transactionline.id` on **99 of 99** randomly sampled prod rows plus all 7 multi-root orders, with zero join misses. So keying a NetSuite ↔ Forecast line join on `linesequencenumber` silently mismatches about half the book — always join on `transactionline.id`.
 - **ShipItem lines have `costestimate = NULL`** (100% of 42K+ lines, 2025–26). In any profit expression `SUM(-foreignamount + costestimate)`, a NULL cost makes the whole term NULL and SQL **drops the row from the SUM** — so shipping *revenue* still counts but shipping *profit* does not, silently understating NS profit. Always `NVL(tl.costestimate, 0)`. (Caused a fake $663K "gap" in the audit tools — see the reconciliation doc.)
 - **Cash refunds & credit memos carry extra COGS/inventory lines.** SuiteQL `transactionline` with `mainline='F' AND item>0` returns, per item, the customer line **plus** a `CUSTOMERRETURN` and an `ASSET` posting (all `item>0`), which REST's `item[].items` sublist omits. They are distinguished by **`tl.iscogs = 'T'`** (and `accountinglinetype` IN `CUSTOMERRETURN`/`ASSET`). Filter **`tl.iscogs = 'F'`** to get exactly the customer-facing lines. Invoices/cash sales do not have this (0 extra lines). Without the filter, bulk imports duplicate refund/memo lines.
+- **⚠ `listSales()` takes a `$recordTypes` allowlist — pass `RECORD_TYPE_*` CONSTANTS, never raw SuiteQL codes (2026-09-21).** `listSales(...)`'s trailing `array $recordTypes` **defaults to all four** `RECORD_TYPE_INVOICE`/`_CASH_SALE`/`_CASH_REFUND`/`_CREDIT_MEMO`, which the **forecast import** (`worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php`, `periodic_forecast_discrepancy_fix.php`) relies on. `listSales` maps each constant to its SuiteQL code internally (`RECORD_TYPE_INVOICE`→`CustInvc`, `_CASH_SALE`→`CashSale`, `_CASH_REFUND`→`CashRfnd`, `_CREDIT_MEMO`→`CustCred`) and **throws on an unknown/empty type**. The **togasupply sync passes `[RECORD_TYPE_INVOICE]` — INVOICES only** — because a credit memo's `createdFrom` is the invoice it credits (not a sales order) and dead-ended `syncInvoiceFromNetsuite`; see the [per-client-sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md).
 - **Sign conventions are per-type and self-consistent.** SuiteQL returns `foreignamount`/`quantity`/`costestimate` **negative for invoices & cash sales, positive for credit memos & cash refunds**. A uniform `-foreignamount` therefore yields **positive** revenue for invoices and **negative** for reversals — the agreed Forecast2 convention. Do NOT also apply a per-type factor (it double-negates reversals back to positive). The shim flips `amount = -foreignamount`, `costEstimate = -costestimate`.
 - **⚠ `->holdInvoice` on a sales-order shim is NOT a native NetSuite field — it is normalised from the custom checkbox `custbody_asi_hold` (internal id 4082), and that field is SHARED by all clients.** NetSuite REST exposes no top-level `holdInvoice`. The `"asi"` prefix is **Agilant Solutions Inc** (the company), *not* a client prefix — do not read it as client-specific. The read lives **inside the shim**, in all three fetch paths: `buildSalesOrderShims()` (~L533, feeding both `listSalesOrders()` and `fetchSalesOrderByIdFull()`) and `fetchSalesOrderById()` (~L1537), so callers such as `App_Api_Toga2::isTransferOrder()` read an already-normalised boolean. (An earlier version read `$nsOrder->holdInvoice` in the caller with a `custbody_hold_invoice` fallback — the wrong field name; commit `07c31e24`, 2026-08-19, found the real one and moved the read down here.) `worker/crons/toga2/compass/edi/2_create_so_netsuite.php` **writes** the same field. **⚠ The SOAP client `library/app/netsuite.php` never sets `holdInvoice` at all**, so any detection that depends on it (e.g. the `zero_dollar_hold` transfer-order mode — see [per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md)) is **silently always-false** on a SOAP path. Verified not a live risk: the togasupply engine calls `App_Api_Netsuite_Rest::` on every sales-order/receipt/fulfillment path.
 - **`createdFrom` is not a usable SuiteQL column.** `transaction.createdfrom` is **always NULL** in SuiteQL (26/26). It is recoverable from `previoustransactionlinelink.previousdoc` excluding `previoustype = 'Opprtnty'` (an invoice links to both its SO and its opportunity; REST's `createdFrom` is the SO). **But this is non-deterministic for multi-link transactions** (credit memos return several non-Opprtnty `previousdoc` rows in arbitrary order) — two runs can pick different values. REST `createdFrom` (per-id GET) is the only deterministic source. Treat the link table as best-effort, not authoritative.
@@ -93,6 +94,9 @@ Field semantics (verified on the live account):
 - Field availability varies by NetSuite account **and** record type — probe the live account before assuming a column/relationship exists.
 - **`App_NetSuite::getCustomFieldValue()` (`library/app/netsuite.php`) must be warning-safe.** 1.0 runs on PHP 7.2 in an unguarded path, so any PHP warning → `exit()` (kills the cron). It was hardened 2026-08-27 with `?? []` / `?? null` guards on the custom-field-list traversal. Keep that discipline when touching it.
 
+## Change history
+- 2026-09-21 — `listSales()` gained a `$recordTypes` allowlist param (defaults to all 4 for the forecast import); callers pass `RECORD_TYPE_*` constants, not raw SuiteQL codes; throws on unknown/empty. Lets the togasupply sync request INVOICES only. (jcardinal)
+
 ## Related
 
 - `netsuite-suiteql-api-reference.md` — the broad API reference (auth, SuiteQL mechanics, table schemas, type/status codes, custom-field map, performance) these semantics sit on top of.

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-09-21
 owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
@@ -163,7 +163,7 @@ Signature takes `$integrationType` (`TICKETS` or `REPAIR_ORDERS`) plus **seven i
 ## Gotchas
 
 - **A 2.0 GET silently TRUNCATES a nested child collection — never trust a single response for a count.** When you read a parent with a nested `hasMany` collection in one GET, api2 can return the collection **partial** (observed: a fulfillment's nested `itemFulfillmentItemUnits` came back **45 of 70**) with no error and no obvious signal — so any verification that counts off the nested array is silently wrong. **Read the collection flat and fully paginated** (query the child resource directly with the universal `meta->nextPage` loop) and take counts from **`meta.totalRecordCount`**, not from a single nested response. Surfaced building the NYCHH fulfillment asset-tag verifier (`worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php`). **Confirmed again on the fulfillment reconcile (2026-09-13):** the `salesOrderItems` nested collection truncated at **25**, and a fulfillment's `itemFulfillmentItemUnits` re-created 25,766 links for 1,192 real units. The reconcile now reads both flat + fully paginated via two new private helpers, `getItemFulfillmentItemUnitsByItemFulfillmentUuid()` and `getSalesOrderItemsBySalesOrderUuid()` (`recordsPerPage` 1000, page-cap 500, `nextPage ?? null`) — detail on the [per-client sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md).
-- **🔐 Hardcoded credentials.** Every client's `CLIENT_UUID_*`, `API_UUID_*`, and `API_SECRET_*` (plus the "True Workers" master keys) are committed as plaintext class constants at the top of `toga2.php`. Treat them as **compromised-if-leaked**; do not reproduce the values in the KB, tickets, or logs. Long-term they should move to config/SSM. (Observed 2026-06-23.)
+- **🔐 Hardcoded credentials.** Every client's `CLIENT_UUID_*`, `API_UUID_*`, and `API_SECRET_*` (plus the "True Workers" master keys) are committed as plaintext class constants at the top of `toga2.php`. Treat them as **compromised-if-leaked**; do not reproduce the values in the KB, tickets, or logs. Long-term they should move to config/SSM. (Observed 2026-06-23.) **⚠ Also (found 2026-09-21, NOT fixed): a committed JWT (a dev/NYCHH token) sits inline at `library/app/api/toga2.php:641`, inside `App_Api_Toga2::send()` — the live sync call path.** Pre-existing, not introduced this session. **Rotate the token and delete the line;** record its location only, never the value.
 - **Two unrelated `sync_togasupply_<client>.php` families.** Files under `worker/crons/toga2/netsuite/` are the **NetSuite supply importer** (`require` the common engine). Files under `worker/crons/toga2/<client>/` (e.g. `aig/`, `wje/`) are this **bridge** (`syncWithToga`/`syncWithTogadesk`). Same filename, different integration, different parameter keys — they coexist harmlessly. Confirm which folder before editing.
 - **`syncWithToga` and the bridge build SQL by hand** with `App_Database::sqlEscape()` rather than the `App_Model` layer; follow the surrounding escaping discipline when modifying.
 - **Per-record error isolation** in the TOGaDesk sync is via `try/catch` → `\Sentry\captureException`; a thrown exception elsewhere (transport, checkpoint read) still aborts the whole run.
@@ -179,6 +179,9 @@ Signature takes `$integrationType` (`TICKETS` or `REPAIR_ORDERS`) plus **seven i
 - **This logic IS testable without a database — and there is a harness.** `App_Database::sqlEscape()` needs **no DB connection** (pure `str_replace`), so the email transform can be exercised statically. The TRUE-79401 transform is inlined in the DB-writing `private static syncContactToToga1Customer()`, so the harness **mirrors** it and guards against drift by asserting the production statements verbatim — see [static no-DB regression harness](../../test/features/static-no-db-regression-harness.md). **If you edit those 5 statements, the harness will refuse to report until it is updated.** The clean fix if you are already in there: extract the transform to a `public static` helper so the mirror disappears.
 - **Pre-existing (low severity, out of scope): a raw-vs-escaped comparison causes a redundant UPDATE every sync.** At the update path (~line 8584) `syncContactToToga1Customer` compares `$existingCustomer['emailAddress'] !== $emailAddress` — the DB value from `App_Database::fetchRow()` is **unescaped**, while `$emailAddress` has already been through `App_Database::sqlEscape()`. For any value containing `'`, `"` or `\` the two can **never** compare equal, so that column is rewritten on **every** run. Same pattern applies to `businessName` and `phoneNumber` just above. **Predates TRUE-79401**, is a redundant write (not data loss), and was deliberately left out of that ticket's scope — recorded here so a future reader knows it is known.
 
+## Change history
+- 2026-09-21 — Recorded a pre-existing committed JWT (dev/NYCHH token) at `toga2.php:641` inside `send()` (the sync call path); flagged to rotate + delete, location-only. (jcardinal)
+
 ## Related
 
 - [NetSuite → TOGa Supply per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md) — the importer that uses this class's transport and `*FromNetsuite()` methods.

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/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-18
+updated: 2026-09-21
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -834,10 +834,10 @@ then at header level:
 Prod check: 391 rows TO-side, 293 SO-side, **0 with both, 0 with neither**.
 
 **It throws — never skips — on:** more than one SalesOrder for the NetSuite id; a TO with no
-lines; an SO line with no matching TO line; a line carrying `InvoiceItems` (**`InvoiceItems` has no
-`transferOrderItemId`**, so they physically cannot be moved); or any bridge whose existence check
+lines; an SO line with no matching TO line; or any bridge whose existence check
 returns no `totalRecordCount` (see the ACL shape below). Consistent with the 2026-08-27 fail-loud
-policy.
+policy. **A stale transfer-order Invoice no longer freezes the run — it is now DELETED up front
+(2026-09-21, below);** the old per-line `InvoiceItems` throw is kept only as a safety net.
 
 **Bridge direction is PO-FIRST, confirmed from NYCHH data rather than guessed.** The naming rule is
 `<source>_<created from it>`. `Client_Nychh` populates `PurchaseOrderItems_TransferOrderItems` (98
@@ -922,6 +922,56 @@ actually have to write code for** — the schema alone would have sent us after
 | `PurchaseOrders_TransferOrders` | 17 → **104** |
 | `PurchaseOrderItems_TransferOrderItems` | 28 → **163** |
 
+#### ⚠ A stale transfer-order Invoice froze SALES_ORDERS — the retirement now DELETES it up front (fixed + deployed + prod-verified 2026-09-21, NYCHH)
+
+The retirement's old "throw on any `InvoiceItems`" rule froze NYCHH `SALES_ORDERS` at `1-RUNNING`
+(`Logs.Issue` **813**, `clientId 3`). NetSuite order **4680233** (number **172445**) was reclassified
+`SalesOrder`→`TransferOrder`; the stale `SalesOrder` **65** carried `Invoice` **297781** (id **1143**).
+`Invoices`/`InvoiceItems` have **no `transferOrderId`/`transferOrderItemId`**, so the retirement could
+not move them and threw *"resolve manually"* every run.
+
+**Team decision (jcardinal): a transfer-order's invoices are NOT imported, so a stale one is deleted,
+not preserved.** New `private static deleteStaleTransferOrderInvoicesForSalesOrder()` runs **first** in
+the retirement (before the line/header moves):
+
+- Deletes, in FK order, the stale TO invoice's **`InvoiceItems` → `InvoiceTrackingNumbers` → the
+  `Invoice` header** — both children are FK **RESTRICT**, so children first.
+- `Invoices` has **no soft-delete/void flag**, so it is a **hard delete**.
+- **Throws (refuses)** if the invoice also bills a **different** SalesOrder (a shared invoice) — never
+  deletes another order's billing.
+- The old per-line `InvoiceItems` throw is kept as a **safety net** for anything the up-front delete
+  didn't clear.
+- All GETs use `recordsPerPage` 1000 + `isset($meta->totalRecordCount)` guards; fail-loud preserved.
+
+Reviews: php-reviewer clean, cso SAFE TO SHIP, cto AGREE (cto caught the second FK child,
+`InvoiceTrackingNumbers`). **Verified prod:** SalesOrder 65 + Invoice 1143 deleted, TransferOrder 1929
+kept, `NETSUITE_EXECUTION_MODE_SALES_ORDERS` `1-RUNNING → 1-IDLE`, cursor advanced past `…|4680233`.
+
+#### ⚠ The togasupply sync imports INVOICES ONLY — a credit memo froze INVOICES (fixed + deployed + prod-verified 2026-09-21, NYCHH)
+
+NYCHH `INVOICES` froze at `1-RUNNING` (`Logs.Issue` **804**) because `syncInvoiceFromNetsuite` refused a
+**credit memo** (NetSuite **4446850**, type `CustCred`). A credit memo's `createdFrom` is the **INVOICE
+it credits, not a sales order** — chain: credit memo `4446850` → invoice `176645` (`CustInvc`) → sales
+order `2603333`. `syncInvoiceFromNetsuite` only resolves `createdFrom` as a sales/transfer order or
+RtnAuth, so a credit memo dead-ends and throws forever.
+
+**Root cause: the INVOICES header fetch was pulling four transaction types.** `App_Api_Netsuite_Rest::listSales()`
+returned `CustInvc`, `CashSale`, `CashRfnd`, `CustCred`; credit memos + cash refunds were never in scope
+for the togasupply sync. **Team decision (jcardinal): the togasupply sync imports INVOICES ONLY.**
+
+- **Fix (worker):** `common_sync_togasupply.php` (INVOICES section, ~L978) now calls `listSales()` with
+  `[App_Api_Netsuite_Rest::RECORD_TYPE_INVOICE]`.
+- **Fix (library):** `listSales()` gained a trailing `array $recordTypes` param defaulting to all four
+  `RECORD_TYPE_*` constants (so the **forecast import** —
+  `worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php` +
+  `periodic_forecast_discrepancy_fix.php` — is unaffected via the default). Callers pass **`RECORD_TYPE_*`
+  constants, never raw SuiteQL codes**; `listSales` maps constant→code internally and **throws on an
+  unknown/empty type**. Detail on the [SuiteQL/REST shim](../../library/features/netsuite-suiteql-rest-shim.md).
+
+php-reviewer clean (additive; forecast callers unaffected), sql-reviewer SAFE TO MERGE (allowlist
+mapping, no injection). **Verified prod:** `NETSUITE_EXECUTION_MODE_INVOICES` `1-RUNNING → 1-IDLE`
+(window still 1s; self-heals ×3 from 2024-02-22).
+
 ### ⚠ TWO code paths create `PurchaseOrderItems` — only one stamped `fulfillmentType` (fixed 2026-09-17)
 
 `fulfillmentType` was stamped by `syncPurchaseOrderFromNetsuite()` (from the order-level
@@ -1283,7 +1333,9 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
   **`lastmodifieddate`, NOT `trandate`** — `App_Api_Netsuite_Rest::listSales()` defaults
   `$dateField='lastmodifieddate'` and the engine calls it without the 4th arg. So a backdated
   `trandate` is irrelevant to whether an invoice imports, and a just-modified invoice still won't
-  import until it is >24h old (the upper-bound cap).
+  import until it is >24h old (the upper-bound cap). **The engine also now passes
+  `[RECORD_TYPE_INVOICE]` (INVOICES only — 2026-09-21); credit memos / cash refunds are out of scope
+  and a credit memo threw here — see the credit-memo freeze subsection above.**
 - **⚠ DEPLOY ORDER: the cursor-rename migration MUST run on EVERY client DB before the worker/library
   deploy — there is NO old-key fallback in code.** `Client/2026-09-02b - NetsuiteSyncCursorRename.sql`
   renames `NETSUITE_LAST_SYNC_DATETIME_<SECTION>` → `NETSUITE_LAST_SYNC_CURSOR_<SECTION>`. If the code
@@ -1995,6 +2047,15 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
   [NetSuite Sync Alert Monitor](../../library/features/netsuite-sync-alert-monitor.md).
 
 ## Change history
+- 2026-09-21 — **Two NYCHH sync freezes fixed, deployed (library + worker together) and prod-verified.**
+  (1) SALES_ORDERS froze (`Logs.Issue` 813) on a stale transfer-order invoice the retirement couldn't
+  move (`Invoices` has no `transferOrderId`). New `deleteStaleTransferOrderInvoicesForSalesOrder()`
+  deletes the stale TO invoice up front — `InvoiceItems` → `InvoiceTrackingNumbers` → header (both FK
+  RESTRICT), hard delete (no void flag), throws only if the invoice also bills a different SalesOrder;
+  team decision that TO invoices aren't imported. (2) INVOICES froze (`Logs.Issue` 804) on a credit
+  memo whose `createdFrom` is the invoice it credits, not a sales order; the sync now imports INVOICES
+  only — `listSales()` gained a `$recordTypes` param (defaults to all 4 for the forecast import) and the
+  engine passes `[RECORD_TYPE_INVOICE]`. Both verified `1-RUNNING → 1-IDLE`. (jcardinal)
 - 2026-09-18 — **Three corrections and one deployed fix.** (1) The stale-SalesOrder retirement
   method shipped **missing four FK dependencies** and failed on each in turn: `ItemFulfillments`
   **header** `salesOrderId` (all 218 orders), the **upstream** `PurchaseOrders_SalesOrders` header

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 |