toga-ai 1.0.988 → 1.0.989

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

@@ -7,6 +7,7 @@
 | [API Request Logging & Retention (App_ApiTransaction → Logs.API / Logs_<Tenant>)](features/api-request-logging-and-retention.md) | Where every outbound API call is logged (1.0 `Logs.API` vs the 2.0 `Logs_<Tenant>` cluster), how the routing is chosen, and the 30-day retention trim; open befo |
 | [Where a new App_ class goes — the app/ folder IS a behavioral contract](features/app-class-placement-base-contracts.md) | Where a new `App_` class goes — each `app/` folder's base class carries real inherited behavior; open before creating any class under `app/model|client|api`. |
 | [App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)](features/app-sso-initiation.md) | Reusable 1.0 SP-initiated SAML SSO via `saml.togahub.com` (`App_Sso::initiate`); the canonical doc to follow for any "add SSO to `<1.0 app>`" request. |
+| [Carrier detection from a tracking number (App_Misc) — patterns, check digits, shipping-method fallback](features/carrier-detection-from-tracking-number.md) | How 1.0 decides which carrier a tracking number belongs to (`App_Misc`, `library/app/misc.php`): certain vs shared-shape patterns, the FedEx check digit, and th |
 | [Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)](features/cron-execution-monitoring.md) | 1.0 cron check-in/out lifecycle via `App_Framework::cronInitialization()`/`cronFinished()` → `Common.CronJobExecutions`; open to monitor a 1.0 cron or read its |
 | [1.0 MySQL Connection Lifecycle — wait_timeout, the 2006 Reconnect Gap, keepAlive/reconnect/queryForked](features/db-connection-lifecycle-and-reconnect.md) | How a 1.0 mysqli connection dies during a long external call ("MySQL server has gone away"), why the built-in 2006 reconnect never fired, and the three helpers |
 | [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | TOGa Refresh 2026 "View Recommended Services" routing — per-device diagnostic `resultCode` decides serviceselection vs techsupport; open when touching that rout |

package/knowledge/1.0/apps/library/features/carrier-detection-from-tracking-number.md

@@ -0,0 +1,170 @@
+---
+title: Carrier detection from a tracking number (App_Misc) — patterns, check digits, shipping-method fallback
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-10-09
+owners: [bala]
+files:
+  - library/app/misc.php
+  - library/app/api/toga2.php
+  - library/app/api/netsuite/rest.php
+  - dbchanges2/Client_Nychh/2026-10-09 - NewYorkMinuteShippingCarrier.sql
+related:
+  - ./netsuite-suiteql-rest-shim.md
+  - ./toga2-api-client-and-bridge.md
+  - ../../worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../../../2.0/apps/_underscore/features/shipping-carriers-and-accounts.md
+  - ../../../../clients/nychh/features/transfer-order-notification-emails.md
+  - ../../../../clients/compass-usa/features/odp-strategic-systems-asn-csv-import.md
+---
+
+How 1.0 decides which carrier a tracking number belongs to (`App_Misc`, `library/app/misc.php`): certain vs shared-shape patterns, the FedEx check digit, and the shipping-method fallback for local couriers. Open before touching a carrier pattern, a tracking link, or anything that writes `TrackingNumbers.shippingCarrierId`.
+
+## Summary
+
+`App_Misc` is the **only** place 1.0 derives a carrier from a tracking number. Entry point
+`findShippingCarrierForTrackingNumber(string $trackingNumber, string $shippingMethodCarrierName = '')`
+(`misc.php:601`), with `getCarrierFromTrackingNumber()` (`:654`) as the name-returning wrapper that
+~20 worker crons use for email tracking links.
+
+**The tracking number decides first. The shipping method's carrier is a fallback, never an override.**
+Before 2026-10-09 the NetSuite item-fulfillment sync wrote tracking numbers with **no**
+`shippingCarrierId` at all, so emails and screens showed no carrier and no tracking link.
+`App_Api_Toga2::syncItemFulfillmentFromNetsuite` (`library/app/api/toga2.php` ~8355-8410) now reads the
+fulfillment's shipping-method carrier **once per fulfillment** and passes it in.
+
+## How it works
+
+Decision order inside `findShippingCarrierForTrackingNumber()`:
+
+1. `stripPunctuationAroundTrackingNumber()` (`:755`) — trims **edges only**.
+2. `listCertainCarrierPatterns()` (`:678`) — shapes **one** carrier owns. Trusted over whatever the
+   shipping system recorded.
+3. FedEx check digit — narrows the shapes a length match cannot prove.
+4. `listSharedShapeCarrierPatterns()` (`:719`) — shapes several carriers share; the shipping method
+   breaks the tie.
+5. `looksLikeACourierJobNumber()` (`:625`) — the local-courier fallback, gated by
+   `hasTrackingNumberPatterns()` (`:638`).
+
+### Certain vs shared shape
+
+- **Certain:** UPS `1Z`; USPS `/^9[1-5]\d{20}$/` and `/^9[1-5]\d{24}$/`; the USPS UPU S10
+  international forms `/^(EA|EC|CP|RA)\d{9}(\D{2})?$/i` and `/^[A-Za-z]{2}[0-9]+US$/`; Amazon
+  `/^:?TBA[0-9]{12,15}$/i`.
+- **Shared shape:** the loose 11-character UPS form, the bare 10-digit form (DHL), and the FedEx digit
+  runs.
+
+**Every pattern is anchored.** An unanchored 12-digit run matched *inside* free text like
+`INV 986578788855 paid`.
+
+Patterns deleted 2026-10-09 as **proven wrong against prod data**: AIT (both patterns — matched one
+SAIA freight row and typed dates such as `11152024`), Dunham (matched nothing; the company closed in
+2017), the DHL "three letters + seven digits" form (all 8 matching rows were Ingram Micro and New York
+Minute references, and it squatted on Amazon `TBA`), and VYLI's space-padded 19-digit form (it needed
+literal spaces the ODP import trims away). USPS was narrowed from `/^9\d{15,21}$/` because that also
+took `96` and `98` prefixes, which are FedEx — and the tie meant **neither** carrier won. There is **no
+real 14-digit FedEx form**; the 77 Compass rows of that shape are ODP carriers.
+
+### The FedEx check digit does what a pattern cannot
+
+12 digits **is** FedEx's published length, so no pattern can exclude a local courier using the same
+length. Two validators:
+
+- `doesFedExTwelveDigitCheckDigitPass()` (`:782`) — digits 1-11 weighted 3,1,7 repeating; sum `MOD 11`
+  then `MOD 10` must equal digit 12.
+- `doesFifteenDigitCheckDigitPass()` (`:794`) — the GS1 rule FedEx Ground uses; weights 3,1 walking
+  left from the check digit.
+
+Measured over **all 13,685** twelve-digit rows in `Client_Compass`: FDEG **2,744 of 2,745** pass, RPSI
+794 of 794, FDXG 114 of 114 — but VYLI only **104 of 1,371** and SAIA freight **0 of 6**. Prudential:
+**47,462 of 47,469**. So the check digit is exactly what separates real FedEx from Veyer and LTL
+freight. **A carrier with no rule defined always passes**, so this only ever narrows FedEx.
+
+### Edge punctuation only — middles are left alone deliberately
+
+9 real `Client_Nychh` rows are a valid FedEx number with a leading colon (e.g. `:557705166169`), and
+the patterns are anchored, so one stray edge character hides a good number. Middle punctuation stays
+untouched so `2848880,2849200` and `512181and3174` remain unmatched.
+
+### Local couriers resolve through the shipping method, not a pattern
+
+A local courier must be a **database row**, never a pattern in shared library code — the per-client
+carrier signal is the `ShippingMethods` row (see below), not the number.
+
+`looksLikeACourierJobNumber()` accepts a **5 to 9 digit** run (spaces and dashes allowed). The 9-digit
+cap is what stops a client carrier code such as `FDEG` from claiming a 12-digit number when the name
+check misses it. `hasTrackingNumberPatterns($carrierName)` returns true when a carrier could ever be
+named by a number alone; if so, the shipping method is **not** allowed to override a blank result — a
+real FedEx number would have matched above, so the method is lying.
+
+NYCHH is the first client wired this way: `dbchanges2/Client_Nychh/2026-10-09 - NewYorkMinuteShippingCarrier.sql`
+adds carrier **New York Minute** (uuid `6f3c8d47-21ba-4e95-b70d-5c91a4f8e2d3`) and repoints
+`ShippingMethods` id 5 (`c_netsuiteInternalShipMethodId = 33322`) onto it. The blank-named carrier id 12
+is **deliberately left alone** — the sync reuses it as a placeholder.
+
+### The shipping method is the only per-client carrier signal
+
+NetSuite has **no usable carrier field** on an item fulfillment: `transaction.shipcarrier` is the
+literal grouping string `FedEx/USPS/More` on every row, and a `shipitem` record has no carrier column.
+The only signal is the TOGa `ShippingMethods` row matched on `c_netsuiteInternalShipMethodId`.
+`App_Api_Netsuite_Rest::fetchItemFulfillmentById` therefore exposes `shipMethod` (internalId + name) on
+its shim — see [the REST shim doc](./netsuite-suiteql-rest-shim.md).
+
+## Gotchas / known issues
+
+- **⚠ api2 treats `tracking-numbers.shippingCarrierId` as a MATCH field.** Sending a carrier name the
+  client has no `ShippingCarriers` row for does **not** fall back to NULL — it fails the **whole**
+  tracking-number write with *unable to find a unique match*. The sync therefore only ever sends a
+  carrier the client already has, and **never creates one**. Auto-creating carriers is what produced
+  340 duplicate `ShippingCarriers` rows across 14 clients (TRUE-81576); see
+  [shipping carriers & accounts](../../../../2.0/apps/_underscore/features/shipping-carriers-and-accounts.md).
+- **⚠ KNOWN GAP — `hasTrackingNumberPatterns()` compares the carrier NAME**, so client-specific codes
+  (`FDEG`, `FEDX`, `UPSG`) defeat it. Only the 9-digit cap bounds the damage. The proper fix is a
+  local-courier flag driven through settings, **not** a new field. Not built yet.
+- **A bare 10-digit number must NOT resolve to DHL on its own (decided 2026-10-09).** A CodeRabbit
+  review asked `generateTrackingNumberLink()` / `displayTrackingNumberWithCarrier()` to fall back to
+  "exactly one shared-shape match" when no shipping method is passed. **Rejected:** a bare 10-digit
+  number matches only the DHL pattern (shared UPS needs 11), so "exactly one match" *always* means DHL.
+  Prod 10-digit rows: Compass 25 FedEx, 3 FXFE, 1 Tripp Lite against only 3 DHL; NYCHH 57 labelled DHL
+  although NYCHH never ships DHL; Prudential 2. **Of 103 rows, 5 are really DHL.** The wrong NYCHH
+  labels came from the old loose DHL pattern in the 2.0 route
+  (`_underscore/Trait/Netsuite/ItemFulfillment.php`). Accepted cost: 5 rows lose the `(DHL)` label and
+  fall back to the Google-search link `generateTrackingNumberLink()` already uses for unknown numbers.
+- **A vendor-feed import already knows its carrier — do not re-guess it.** The Compass ODP and Compass
+  Canada G&T ASN crons take tracking numbers from the vendor feed, which carries the real carrier code
+  (`VYLI`, `FDEG`, `SAIA`, `RPSI`), and the import maps it into `shippingCarrierId` at
+  `worker/crons/toga2/compass/workflow/3b_import_strategic_systems_advance_shipping_notices.php:495`.
+  They call `getCarrierFromTrackingNumber()` only afterwards, for the carrier name in the email link,
+  and need **no** NetSuite shipping method. Follow-up: read the name off the row just saved.
+- **NYCHH has 860 tracking numbers in the 5-9 digit job-number shape** (sample `001056`), all with no
+  carrier today. They only get New York Minute on **future** syncs unless someone backfills.
+
+## Testing
+
+**197 tests** across three suites (patterns, check digits, shipping-method fallback), all passing.
+
+Measured regression on NYCHH, 2,952 tracking numbers that have a carrier today: **2,869 keep the same
+carrier**, 58 DHL and 25 FedEx go **blank**, and **none** move to a wrong carrier.
+
+The three USPS shapes the old code caught and the new one does not (short `9x` numbers of 16-21 digits,
+the `82` + 8-digit form, and `E` + 9 digits that is not EA/EC/CP/RA) return **zero rows across the 12
+biggest prod clients** — so the ~20 worker crons that call `getCarrierFromTrackingNumber()` for email
+links are unaffected.
+
+## Change history
+- 2026-10-09 — **Built.** Carrier is now set on tracking numbers during the NetSuite item-fulfillment
+  sync (TRUE-82527): new `findShippingCarrierForTrackingNumber()`, patterns split into certain vs
+  shared-shape with the wrong ones deleted, FedEx check-digit validation, edge-punctuation stripping,
+  and a shipping-method-driven local-courier fallback (NYCHH New York Minute). Decided that a bare
+  10-digit number must not resolve to DHL. (bala)
+
+## Related
+- [NetSuite SuiteQL/REST shim](./netsuite-suiteql-rest-shim.md) — the `shipMethod` field, and why
+  `shipcarrier` is useless
+- [NetSuite → TOGa Supply per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md)
+- [Shipping carriers & accounts](../../../../2.0/apps/_underscore/features/shipping-carriers-and-accounts.md)
+- [NYCHH transfer-order emails](../../../../clients/nychh/features/transfer-order-notification-emails.md)

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

@@ -6,14 +6,15 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-21
-owners: [dfranks, jcardinal, kyalamarthi, rgirish]
+updated: 2026-10-09
+owners: [dfranks, jcardinal, kyalamarthi, rgirish, bala]
 files:
   - library/app/api/netsuite/rest.php
   - library/app/netsuite.php
   - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
 related:
   - netsuite-suiteql-api-reference.md
+  - ./carrier-detection-from-tracking-number.md
   - ../architecture.md
   - ../../worker/features/forecast2-netsuite-reconciliation.md
   - ../../../2.0/apps/_underscore/features/netsuite-rest-client.md
@@ -54,6 +55,8 @@ Header SuiteQL → per-record detail → line SuiteQL, assembled into SOAP-shape
 
 Field semantics (verified on the live account):
 
+- **⚠ There is NO usable carrier field on an item fulfillment — read the ship method instead.** `transaction.shipcarrier` is the literal grouping string `FedEx/USPS/More` on **every** row, and a `shipitem` record has no carrier column. So `fetchItemFulfillmentById` now exposes **`shipMethod`** on the shim (internalId + name, read from the REST GET body like opportunity / terms / createdFrom), and the carrier is resolved on the TOGa side from the `ShippingMethods` row matched on `c_netsuiteInternalShipMethodId`. Anything needing a carrier reads that, never `shipcarrier`. See [carrier detection from a tracking number](./carrier-detection-from-tracking-number.md).
+
 - **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.
@@ -95,6 +98,7 @@ Field semantics (verified on the live account):
 - **`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-10-09 — `fetchItemFulfillmentById` now exposes `shipMethod` (internalId + name), because `transaction.shipcarrier` is the useless literal `FedEx/USPS/More` on every row and `shipitem` has no carrier column. It feeds the 1.0 carrier resolver. (bala)
 - 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

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-10-06
+updated: 2026-10-09
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -35,6 +35,7 @@ related:
   - ../../../clients/elite/features/netsuite-togasupply-sync.md
   - ../../library/features/netsuite-item-class-sync.md
   - ../../library/features/netsuite-item-description-sync.md
+  - ../../library/features/carrier-detection-from-tracking-number.md
   - ../../../clients/compass-usa/features/sales-order-line-renumbering.md
   - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
   - ../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
@@ -751,6 +752,19 @@ the [Quad profile](../../../clients/quad/profile.md) and the
 Design rationale for putting this at the source writer rather than a 317 interceptor lives on the
 [recursive item fulfillments doc](../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md).
 
+### The fan-out now also sets the CARRIER on the tracking number (2026-10-09)
+
+`syncItemFulfillmentFromNetsuite` used to write package tracking numbers with **no**
+`shippingCarrierId`, so every screen and email showed a bare number with no carrier and no tracking
+link. It now reads the fulfillment's **shipping-method carrier once per fulfillment** (from the shim's
+new `shipMethod` field — NetSuite has no carrier field worth reading) and passes it to
+`App_Misc::findShippingCarrierForTrackingNumber()`, which decides from the **number first** and uses
+the method only as a fallback.
+
+**It never creates a carrier row.** `tracking-numbers.shippingCarrierId` is an api2 MATCH field, so a
+name the client has no row for fails the **whole** tracking-number write. Full rules, patterns and
+measured results: [carrier detection from a tracking number](../../library/features/carrier-detection-from-tracking-number.md).
+
 ### Fulfillment line → sales-order line matching is a 4-step chain (2026-09-13)
 
 The fulfillment matcher in `syncItemFulfillmentFromNetsuite` resolves each fulfillment line back
@@ -2126,6 +2140,7 @@ 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-10-09 — **Item-fulfillment tracking numbers now carry a carrier** (TRUE-82527). The fan-out passes the fulfillment’s shipping-method carrier into ; the number decides, the method is only a fallback, and no carrier row is ever created. (bala)
 - 2026-10-06 — Added "Fix rules" section: self-heal, repair-by-code, fail-loud, dependencies-first, no forward cursor skip, links-are-data, Compass delete boundary. (jcardinal)
 - 2026-10-06 — NYCHH ITEM_FULFILLMENTS frozen 09-30→10-06 (Event issue 483, FK 1451 on IA→IF line link) fixed: reverse retire TO→SO + IA-link move before every IF-line delete (library only). Corrected "NYCHH once a day" — it runs every 5 min. (jcardinal)
 - 2026-10-05 — Closed-order delete now per-client SO scoped (Compass dual-SO freeze, Issue 940); details in [closed-order rule](../../library/features/netsuite-closed-order-rule.md). Library only. (jcardinal)

package/knowledge/2.0/apps/_underscore/features/shipping-carriers-and-accounts.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
-owners: [mhammontree]
+updated: 2026-10-09
+owners: [mhammontree, bala]
 files:
   - _underscore/Trait/Netsuite/SalesOrder.php
   - _underscore/Component/Library/Carriers/Fedex/Fedex.php
@@ -24,6 +24,7 @@ related:
   - ../../toga2-supply/features/fulfill-and-ship.md
   - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
   - ../../../clients/growrk/features/shipping-carrier-cleanup.md
+  - ../../../../1.0/apps/library/features/carrier-detection-from-tracking-number.md
 ---
 
 Per-client `ShippingCarriers` / `ShippingCarrierAccountNumbers` model, how the syncs match/create carrier rows, and the duplication + blank-carrier + pagination traps; open before touching carrier sync, the Fulfill & Ship dropdown, or deleting a carrier.
@@ -57,6 +58,16 @@ The Fulfill & Ship **Carrier dropdown only lists carriers with at least one `Shi
 
 **Fix:** a paged `GET /shipping-carriers` loop that **seeds the lookup directly**, using the same `for ($page = 1, $nextPage = 0; ...)` idiom and `MAX_RECORDS_PER_PAGE_TO_FETCH_FROM_TOGA_API` (1000) as the neighbouring lookups. Blank names are skipped — they are unusable as keys.
 
+### ⚠ NEVER auto-create a carrier — and NEVER send a carrier name the client does not have
+
+`tracking-numbers.shippingCarrierId` is a **MATCH field** in api2. Sending a carrier name with no
+`ShippingCarriers` row for that client does **not** degrade to NULL — it fails the **whole**
+tracking-number write with *unable to find a unique match*. So a writer has exactly two safe moves:
+send a carrier the client already has, or send none. **Creating the missing row is what produced the
+duplicates above** (340 rows across 14 clients). The 1.0 carrier-detection path follows this rule as of
+2026-10-09: it looks the carrier up and sends nothing when there is no row. See
+[carrier detection from a tracking number](../../../../1.0/apps/library/features/carrier-detection-from-tracking-number.md).
+
 ### A blank-named carrier is a WILDCARD (PHP stripos with an empty needle)
 
 The carrier matcher keys on `stripos($nsShippingMethodName, $carrierName) === 0`. Under PHP 8 an **empty needle returns `int(0)`** — verified directly:
@@ -96,11 +107,18 @@ Before deleting a `ShippingCarriers` row in a client DB, check **all** of:
 ## Gotchas / known issues
 
 - **Cleaning duplicates before the fix is deployed is wasted work** — the syncs refill the rows on the next run (every 5 minutes). Deploy first, clean second.
-- Compass (98 carriers) and NYC Health & Hospitals (100) are **not** cleaned yet — separate tasks.
+- **CLEANED. Swept all 37 prod client DBs on 2026-10-09: zero duplicate carriers remain and zero `ShippingMethods` rows have a NULL `shippingCarrierId`.** The merge collapsed **340** duplicate rows across **14** clients. **The merge needed a Part 1 that merged duplicate `ShippingMethods` first** — merging carriers alone hits `Duplicate entry '6-UPS' for key 'ShippingMethods.shippingCarrierId_name'`. ⚠ The merge SQL is **not in dbchanges2 on any branch** (checked 2026-10-09) — it was run ad-hoc, so re-create it if the merge has to be repeated anywhere.
+- **A blank-named carrier row is NORMAL, not damage.** Eight clients have exactly one (Canon id 5, Compass 23, Endeavorhealth 5, Growrk 29, Nychh 12, Prudential 6, Spglobal 60, Wmchealth 6). Each is attached to 1-5 shipping methods and to **zero** tracking numbers — it is the placeholder the sync reuses (see above). **Do not delete it** and do not repoint its methods blindly; give the method a real carrier instead, the way NYCHH's method id 5 was repointed onto *New York Minute*.
 - The `[fedex]` config group contains a key literally named **`_`** with a 32-character value. Purpose unknown; no reader has been traced.
 
+## Change history
+- 2026-10-09 — **Duplicate carriers are gone** (sweep of all 37 prod client DBs) and the blank-named
+  placeholder row is documented as expected. Added the rule that `tracking-numbers.shippingCarrierId`
+  is an api2 MATCH field, so a writer must never invent a carrier. (bala)
+
 ## Related
 
+- [carrier detection from a tracking number](../../../../1.0/apps/library/features/carrier-detection-from-tracking-number.md)
 - [carrier-shipping-labels](carrier-shipping-labels.md)
 - [address-validation](address-validation.md)
 - [fulfill-and-ship](../../toga2-supply/features/fulfill-and-ship.md)

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 34 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 35 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 42 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)

package/knowledge/clients/compass-usa/features/odp-strategic-systems-asn-csv-import.md

@@ -6,8 +6,8 @@ project: Worker
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-09-22
-owners: ["rgirish"]
+updated: 2026-10-09
+owners: ["rgirish", "bala"]
 files:
   - worker/crons/toga2/compass/workflow/3b_import_strategic_systems_advance_shipping_notices.php
   - worker/crons/toga2/compass/DOA_Scripts/DOA_compass_statuses.php
@@ -18,6 +18,7 @@ related:
   - ../../compass-canada/features/grand-and-toy-asn-import.md
   - ../../quad/features/po-asn-email-import.md
   - ../../../1.0/apps/worker/architecture.md
+  - ../../../1.0/apps/library/features/carrier-detection-from-tracking-number.md
 ---
 The 1.0 worker cron that reads Office Depot / Strategic Systems ASN CSVs from email, why it routes by column count, and why a tracking number can arrive as `8.77536E+11` with its digits already gone. Open before touching tracking-number parsing in this file or its DOA copy.
 
@@ -59,6 +60,15 @@ Both files parse tracking numbers in two branches each — ODP and Strategic Sys
 
 ## Gotchas
 
+- **The carrier on an ODP / Strategic Systems row comes from the FEED, not from the tracking number.**
+  The import maps the feed’s carrier code (`VYLI`, `FDEG`, `SAIA`, `RPSI`) into `shippingCarrierId` at
+  `3b_import_strategic_systems_advance_shipping_notices.php:495`; `App_Misc::getCarrierFromTrackingNumber()`
+  runs only **afterwards**, for the carrier name in the email link. So this cron needs **no** NetSuite
+  shipping method (same for the Compass Canada G&T ASN cron). **Follow-up:** read the name off the row
+  just saved instead of re-guessing — the number cannot tell VYLI from FedEx (only 104 of 1,371 VYLI
+  numbers pass the FedEx check digit). See
+  [carrier detection from a tracking number](../../../1.0/apps/library/features/carrier-detection-from-tracking-number.md).
+
 - **⚠ A scientific-notation tracking number is a DATA bug, not a display bug — and the digits are gone before our code runs.** `Client_Compass.TrackingNumbers.number` literally stores the 11-character string `8.77536E+11` (e.g. id 80112, `shippingCarrierId` NULL). 44 such rows exist, Sep 2025 → 2026-09-22. The cause is upstream: a 12-digit number like `877536271001` becomes `8.77536E+11` when a spreadsheet saves the column as a number rather than text. Only 6 significant digits survive. Reported on order **SA137640**.
 
 - **⚠ NEVER "recover" a scientific-notation number with `number_format()` — it pads zeros and fabricates a believable-but-wrong tracking number.** A guard added 2026-10-17 (commit `be8ff1d14`) ran `number_format($n, 0, '', '')` on any value containing `e+`. Verified by running it: `number_format("8.77536E+11")` returns **`877536000000`**, while the real value was **`877536271001`**. The result is a 12-digit number that looks perfectly valid, so nobody can spot it as fake — strictly worse than failing the row. Removed 2026-09-22; all four sites now reject instead. **A silent wrong tracking number is worse than a loud rejected row.**
@@ -80,5 +90,7 @@ Both files parse tracking numbers in two branches each — ODP and Strategic Sys
 - The Compass **Canada** G&T importer already rejects scientific-notation tracking as a row-level guard; its read-only inbox inspector reports it as a dry-run category. That is the pattern Compass USA now matches.
 
 ## Change history
+- 2026-10-09 — Recorded that the feed, not the tracking number, is the carrier source here; the 1.0
+  pattern rewrite does not change what this cron stores. (bala)
 - 2026-09-22 — Removed the lossy `number_format()` "recovery" from all 4 guard sites in both files; now split-then-guard, appending to `$validationErrors` instead. Fixes the fabricated-tracking-number bug and the multi-value PHP fatal. Written and linted (`php -l` passes), **not deployed**. (rgirish)
 - 2026-09-22 — Documented CSV-vs-XLSX as unrecoverable-at-source, column-count file routing, the unknown 06:22 writer, and the 168-row data-quality survey. (rgirish)

package/knowledge/clients/nychh/features/transfer-order-notification-emails.md

@@ -6,7 +6,7 @@ project: Worker
 client: nychh
 type: client-feature
 status: active
-updated: 2026-10-05
+updated: 2026-10-09
 owners: ["bala", "rgirish", "jcardinal"]
 files:
   - worker2/Worker/Client/Nychh/TransferOrderEmails.php
@@ -17,6 +17,7 @@ files:
   - dbchanges2/Client_Nychh/2026-09-15b - TransferOrderEmailGoLiveRecipient.sql
   - dbchanges2/Core/2026-09-16a - NychhTransferOrderEmailsCron.sql
   - dbchanges2/Client_Nychh/2026-10-05a - TransferOrderShippedEmailOnTrackingCutover.sql
+  - dbchanges2/Client_Nychh/2026-10-09 - NewYorkMinuteShippingCarrier.sql
 related:
   - ./transfer-order-netsuite-push.md
   - ../../../2.0/apps/_underscore/features/units-for-items-for-purchase-orders.md
@@ -29,6 +30,7 @@ related:
   - ../../../2.0/apps/worker2/features/creating-worker-actions.md
   - ../../../2.0/apps/worker2/features/sandbox-dev-worker-environments.md
   - ../profile.md
+  - ../../../1.0/apps/library/features/carrier-detection-from-tracking-number.md
 ---
 
 ## Summary
@@ -207,7 +209,7 @@ Added 2026-09-30 (TRUE-82111). `SendFulfillment` runs `readLinesMissingAssetTags
 
 - the item is **`SERIALIZED`** and it has **fewer linked units than its quantity**
   (`unitsLinked < ItemFulfillmentItems.quantity`), or
-- a linked unit has a **blank `Units.assetTag`** — that half holds whatever the item type is.
+- a linked unit has a **blank `Units.assetTag`** — SERIALIZED or HYBRID only since 2026-10-09.
 
 **⚠ The unit-count half is SERIALIZED-only.** `Client_Nychh.Items.inventoryType` is
 `enum('SERIALIZED','NON_SERIALIZED','HYBRID')`; only SERIALIZED items are expected to carry units,
@@ -221,6 +223,12 @@ passed at 10:10 and Order Packed went out with the accessory line correctly igno
 underlying rule lives in
 [inventoryType determines unit existence](../../../2.0/apps/_underscore/features/units-for-items-for-purchase-orders.md).
 
+**⚠ NON_SERIALIZED is now excluded from BOTH reads (2026-10-09).** `readLinesMissingAssetTags()`
+(the blank-`assetTag` half, `:354`) **and** `readUnitsForEmail()` (`:676`, the asset-tag table printed
+in the customer email) both skip `NON_SERIALIZED`. Item **580-BBQL** had been set up as serialized in
+NetSuite by mistake, so the email rendered an **empty asset-tag table** and ops got a **false**
+exception email. A mis-typed item in NetSuite must not produce either.
+
 When any line is short, `SendFulfillment` **returns before writing
 `c_transferOrderEmailStageSent`** — so packed stays pending and the backstop cron re-sends it by
 itself the moment the tags arrive. **The hold covers shipped too**, because the early return happens
@@ -307,6 +315,17 @@ Cost of the split, stated so nobody is surprised later:
   when there is no number and drops the button when there is no URL (since 2026-10-05 Shipped needs a
   number, so this now matters only for the Packed email). Placeholders are
   **`{trackingIntroSuffix}`** and **`{trackingSection}`**.
+- **Carrier logos are a hardcoded map, because `ShippingCarriers.urlLogo` is an app path an inbox
+  cannot open.** `CARRIER_LOGO_URL_BY_CARRIER_NAME` (`:46`) keys on the **uppercased** carrier name,
+  which is read by joining `ShippingCarriers` on `TrackingNumbers.shippingCarrierId` (`:701`). Added
+  2026-10-09: **`NEW YORK MINUTE`** → `NYMinuteMessenger_Logo_2022_4C.png` on `toga-public`. **New York
+  Minute has no tracking website**, so that email shows the logo plus the plain number and **no link**.
+  The carrier reaches the number through the ship method — `ShippingMethods` id 5
+  (`c_netsuiteInternalShipMethodId = 33322`) was repointed onto the new carrier by
+  `dbchanges2/Client_Nychh/2026-10-09 - NewYorkMinuteShippingCarrier.sql`; see
+  [carrier detection from a tracking number](../../../1.0/apps/library/features/carrier-detection-from-tracking-number.md).
+  **⚠ 860 existing NYCHH numbers in the 5-9 digit job-number shape still have no carrier** (sample
+  `001056`) — only future syncs fix them unless someone backfills.
 - **Gmail clips a message past about 102,400 bytes.** `MAXIMUM_EMAIL_BODY_BYTES = 80000` budgets the
   **item block only**; the remainder is summarised as *"and N more"*. 80,000 (not the earlier
   92,000) because the stored shipped template is **11,695 bytes** on its own and a 25-package
@@ -396,6 +415,12 @@ loaded out of the dbchanges2 file so an unresolved `{placeholder}` fails a test.
 unescaped values and both detail-box defects were all found there, not in production.
 
 ## Change history
+- 2026-10-09 — **New York Minute shows its logo, and NON_SERIALIZED lines are ignored by the asset-tag
+  reads** (TRUE-82527). `CARRIER_LOGO_URL_BY_CARRIER_NAME` gained `NEW YORK MINUTE` (no tracking site,
+  so logo + plain number, no link), paired with `Client_Nychh/2026-10-09 - NewYorkMinuteShippingCarrier.sql`
+  and the new 1.0 carrier resolver. `readUnitsForEmail()` and `readLinesMissingAssetTags()` now exclude
+  `NON_SERIALIZED`, after item 580-BBQL (mis-set as serialized in NetSuite) produced a blank asset-tag
+  table and a false exception email. (bala)
 - 2026-10-05 — **Shipped now fires on the first tracking number, not the NetSuite shipped stage**
   (warehouse marks shipped after delivery). Shared `buildHasTrackingNumberSql()`, new
   `resolveStagesStillToAnnounce()` table, matching `SendPending` WHERE; removed dead

package/package.json

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