toga-ai 1.0.669 → 1.0.670

package/knowledge/2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-26
+updated: 2026-08-27
 owners: [bala]
 files:
   - _underscore/Model/Client/SalesOrder.php
@@ -47,8 +47,11 @@ This makes the *picked/packed* portion of the fulfillment lifecycle visible (pre
 - **Compass USA + Compass Canada:** all IF stages are *imported*, but order status counts
   **shipped only** — picked/packed never advance a Compass order's status. Compass walks
   Pending → Partially Fulfilled → Fulfilled by shipped quantity alone. **The shipped-only *stage*
-  policy is shared, but since 2026-08-26 the fulfilled-vs-partiallyFulfilled *rule* is per region:**
-  the fulfillment branch lives in `_fulfillmentStatus()` and Canada overrides it. See
+  policy is shared, but the fulfilled-vs-partiallyFulfilled *rule* is now per region.** **Only Canada
+  actually changed:** the fulfillment branch lives in `_fulfillmentStatus()`, Canada overrides it with
+  a pure per-line rule, and **Compass USA still runs the original order-total logic on purpose**
+  (its ASN feed is not trustworthy at line level). The seam was reverted in git on 2026-08-26 and
+  rebuilt uncommitted. See
   [Compass USA](../../../clients/compass-usa/features/order-fulfillment-status-per-line.md) and
   [Compass Canada](../../../clients/compass-canada/features/order-fulfillment-status-per-line.md).
 
@@ -67,7 +70,8 @@ shipped-only for ALL clients** — picked/packed quantities never count as inven
   `COUNT` and the shipped-qty `SUM` subqueries `INNER JOIN ItemFulfillmentStages →
   ItemFulfillmentStatuses` filtered to the shipped status slug. Shared by Compass USA + Canada.
   Its **fulfillment half is a separate `protected static _fulfillmentStatus()`** called via
-  `static::` — that is the per-region seam (see the Compass docs above). The approval gate stays in
+  `static::` — that is the per-region seam (see the Compass docs above), and its **body is the original
+  order-total logic that USA still runs**. The approval gate stays in
   `_status()` and is region-independent.
 - **`Model/Compass/Canada/SalesOrder.php`** — Canada's `_fulfillmentStatus()` override (per-line,
   ASN-bridge only).
@@ -177,11 +181,15 @@ Fan-out (`Client/`, every client) + a Compass-Canada-specific set. Execution is
   the Compass order-lifecycle workflow.
 - **⚠ An order-level "ordered total vs shipped total" comparison is not a fulfillment test.** A
   grand total lets one line's surplus cancel another line's gap, so an order with one line short and
-  another over-shipped reads **Fulfilled**. This is exactly what the Compass `_status` did until
-  2026-08-26 (its two sides did not even count the same lines — the ordered side filtered
-  `parentSalesOrderItemId IS NULL`, the shipped side did not), and it mislabeled **5,234** USA and
-  **115** Canada orders on prod. Any client `_status` that judges completeness must compare **per
-  line**. See the two Compass docs linked above.
+  another over-shipped reads **Fulfilled**. This is what the Compass `_status` does for **USA
+  today** — and its two sides do not even count the same lines (the ordered side filters
+  `parentSalesOrderItemId IS NULL`, the shipped side does not). Measured on prod: **90** Canada orders
+  were mislabeled and have been corrected by a per-line rule, and **5,223** USA orders would move —
+  but the USA change was **deliberately not made**, because duplicate Office Depot ASNs make its
+  per-line shipped quantity unreliable. Any client `_status` that judges completeness must compare
+  **per line**, and must not do so on a feed that double-credits lines. **⚠ Earlier figures of 5,234
+  USA / 115 Canada are void** (the first attempt was reverted in git). See the two Compass docs
+  linked above.
 - **A `self::`-qualified call to a calculated field inside the same model always uses the parent's
   logic.** `_Model_Compass_SalesOrder` calls `self::_status()` in its ApprovalDecision notification
   query, so that one call site never sees a region subclass override. Use `static::` unless you
@@ -191,6 +199,15 @@ Fan-out (`Client/`, every client) + a Compass-Canada-specific set. Execution is
   picked/packed constant would let the literal be removed.
 
 ## Change history
+- 2026-08-27 — **Corrected the 2026-08-26 entry below: that work was reverted in git (`90c964f1`
+  reverted by `43049d1d`) and the "5,234 USA / 115 Canada" figures are void.** Rebuilt state: the
+  `_fulfillmentStatus()` per-region seam exists again but is **uncommitted**, `_fulfillmentStatus()`'s
+  body is the **original order-total logic that Compass USA still runs deliberately**, and **only
+  Compass Canada overrides it** — with a pure per-line rule, no order-total condition, correcting **90**
+  prod orders (not 115). A USA per-line rule was measured (5,223 orders would move) and rejected
+  because duplicate Office Depot ASNs make USA's per-line shipped quantity unreliable. The
+  order-total-is-not-a-fulfillment-test gotcha now records that a per-line test also needs a
+  trustworthy line-level feed. (bala)
 - 2026-08-26 — Recorded that the Compass **fulfilled-vs-partiallyFulfilled** rule is now **per
   region**: the fulfillment branch of `_Model_Compass_SalesOrder::_status()` was extracted into a
   `protected static _fulfillmentStatus()` invoked via `static::` (approval gate untouched, emitted

package/knowledge/clients/compass-canada/features/order-fulfillment-status-per-line.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: compass-canada
 type: client-feature
 status: active
-updated: 2026-08-26
+updated: 2026-08-27
 owners: ["bala"]
 files:
   - _underscore/Model/Compass/Canada/SalesOrder.php
@@ -25,43 +25,62 @@ TOGa Supply showed **Fulfilled** on Compass Canada orders that were only partly
 `SAC100664` (`SalesOrders.id 665`): line 1 the ZBOOK `C40QYUC#ABA` ordered 1 / shipped 0, line 2 the
 mouse `9VA80AA#ABA` ordered 1 / shipped 1, and the badge read **Fulfilled**.
 
-Root cause was in the shared parent `_Model_Compass_SalesOrder::_status()`, which compared two
-**order-level grand totals** whose two sides did not count the same lines: the ordered side filtered
-`SalesOrderItems.parentSalesOrderItemId IS NULL` (dropping bundle child lines) while the shipped side
-summed **every** ASN quantity on the order with no such filter. On `SAC100664` the mouse is a child
-of the ZBOOK (`parentSalesOrderItemId = 1131`), so ordered = 1 and shipped = 1 and it read fulfilled.
-Confirmed by running the exact expression on prod: orderedSide `1.00`, shippedSide `1`.
-
-Canada's fix is a clean **per-line** rule in its own subclass. Prod impact: **115 Canada orders
-corrected Fulfilled to Partially Fulfilled, zero orders moving the other way**, and
-pendingFulfillment / canceled / pendingApproval / pendingInitialApproval counts all unchanged.
-
-> **Canada's rule is NOT the USA rule, and the two must not be merged.** Compass USA needs a second,
-> aggregate condition on top of the per-line check; porting Canada's clean rule to USA creates
-> thousands of *new* false Fulfilleds. See
+Root cause is in the shared parent `_Model_Compass_SalesOrder`, which decided fulfilled vs.
+partiallyFulfilled by comparing two **order-level grand totals** whose two sides did not count the
+same lines: the ordered side filtered `SalesOrderItems.parentSalesOrderItemId IS NULL` (dropping
+bundle child lines) while the shipped side summed **every** ASN quantity on the order with no such
+filter. On `SAC100664` the mouse is a child of the ZBOOK (`parentSalesOrderItemId = 1131`), so
+ordered = 1 and shipped = 1 and it read fulfilled. Confirmed by running the exact expression on prod:
+orderedSide `1.00`, shippedSide `1`.
+
+Canada's fix is a **pure per-line rule** in its own subclass, with **no order-total check at all**.
+Measured on prod after the rule: **489 fulfilled / 184 pendingFulfillment / 109 partiallyFulfilled**,
+which is **90 orders corrected** from Fulfilled to Partially Fulfilled, plus 3 corrected from
+partiallyFulfilled to pendingFulfillment.
+
+> **⚠ Read this before trusting any older note.** An earlier version of this work was **reverted in
+> git** and its published numbers were wrong — see *History: the first attempt was reverted* below.
+> The rule described on this page was rebuilt from scratch and is **uncommitted working-tree code**.
+
+> **Canada's rule is NOT the USA rule, and the two must not be merged.** Compass **USA is
+> deliberately unchanged** and still runs the order-total logic, because the Office Depot ASN feed is
+> not trustworthy at line level. See
 > [the USA doc](../../compass-usa/features/order-fulfillment-status-per-line.md).
 
 ## Key files / entry points
 
 - **`_underscore/Model/Compass/Canada/SalesOrder.php`** — `_fulfillmentStatus()`, a `protected static`
-  override of the shared parent method. This is the whole Canada rule.
-- **`_underscore/Model/Compass/SalesOrder.php`** — the parent `_status()` (approval gate untouched)
-  now calls `static::_fulfillmentStatus()`, which is what makes the Canada override reachable. It
-  also supplies the `_qtyShippedByAsn()` helper Canada reuses.
+  override. **Self-contained:** it builds its own expected-line set and its own per-line shipped
+  quantity and borrows nothing conditional from the parent. This is the whole Canada rule.
+- **`_underscore/Model/Compass/SalesOrder.php`** — the parent. The fulfillment branch of `_status()`
+  was extracted into `protected static _fulfillmentStatus()` and is called via `static::`, which is
+  what makes the Canada override reachable. **The parent body is the ORIGINAL order-total logic,
+  moved verbatim** — the seam exists only so Canada can override. Proved behaviour-neutral by
+  diffing the emitted `_status` SQL: whitespace-identical, **7,548 normalized characters** both ways.
+- `const ITEM_TYPES__NOT_SHIPPABLE` (Canada) — `SERVICE`, `SERVICES`, `CONSULTING`, `WARRANTY`.
 
 ## How it works
 
 ```
-pendingFulfillment   WHEN the order has no ASN at all
-partiallyFulfilled   WHEN any line with price > 0 has quantity > that line's own shipped quantity
+pendingFulfillment   WHEN every expected-to-ship line has received ZERO quantity
+partiallyFulfilled   WHEN any expected-to-ship line has received LESS than its ordered quantity
 fulfilled            otherwise
 ```
 
-- **No ASN** is `COUNT(*) = 0` over `AdvanceShippingNotices` joined to the order through
-  `SalesOrders_PurchaseOrders`.
-- **Per-line shipped quantity** comes from `_qtyShippedByAsn()` on the shared parent, correlated to
-  the individual `SalesOrderItems.id`.
-- No parent/child line filter, so bundle children are judged on their own merits — that is the fix.
+**Both branches read the same expected-line set and the same per-line quantity**, so the gate and
+the shortfall test can never disagree. That symmetry is the design; keep it if you edit the method.
+
+### "Expected to ship" — all four conditions
+
+A `SalesOrderItems` row counts only when:
+
+1. `price > 0`;
+2. it has a `SalesOrderItems_PurchaseOrderItems` link (it was actually purchased);
+3. its `ItemTypes.name` is **not** in `ITEM_TYPES__NOT_SHIPPABLE`; and
+4. `COALESCE(Items.isFulfillable, 1) = 1`.
+
+No parent/child line filter, so bundle children are judged on their own merits — that is the
+original fix.
 
 ### The per-line shipped source (ASN bridge, and only the ASN bridge)
 
@@ -74,57 +93,136 @@ AdvanceShippingNoticeItems.purchaseOrderItemId
 This mapping is **100% complete in `Client_CompassCanada`**: all **947** ASN items have a
 `purchaseOrderItemId` and every one resolves to a sales-order line. Both join columns are indexed.
 Canada ships through Grand & Toy ASNs only (see
-[G&T ASN Import](grand-and-toy-asn-import.md)), so this single source is sufficient here — Canada
-needs none of USA's TOGa Tech / Office Depot fulfillment chain.
+[G&T ASN Import](grand-and-toy-asn-import.md)), so this single source is sufficient — Canada needs
+none of USA's TOGa Tech / Office Depot fulfillment chain.
+
+## Why each condition is there (measured, prod)
+
+- **Condition 3 (item type) is what corrected the over-correction.** Canada has SERVICE and
+  CONSULTING lines that **do carry PO links but never ship**: `COMPASS-IPAD-ABM` (Apple Business
+  Manager enrolment — 53 lines, only 9 ever on an ASN), `SDU42Z/A` and `SDRU2Z/A` (AppleCare for
+  Enterprise), `CN-COMP-DED-IN` / `CN-CONE-SHR-WS1` (Profile SKUs), and `COMPASS-MACBOOK-ABM-ACE`.
+  Requiring them to ship held **25 fully-delivered orders** at partiallyFulfilled — e.g. `SAC100041`,
+  `SAC100088`, `SAC100523`. Excluding the item types fixed all 25. **This is the 115 to 90 correction.**
+- **Condition 2 (purchased line) is still required.** Canada has **100 priced lines with no PO link
+  across 48 orders**; without the link test those lines can never ship and would strand their orders.
+- **Condition 4 (`isFulfillable`) is a no-op in Canada today.** `Items.isFulfillable` is **NULL on
+  every Canada item**, so the `COALESCE(...,1)` always passes. It is in the expression so the rule
+  starts honouring the flag automatically once Canada is stamped — the **item-type list does all the
+  real work right now**. See
+  [isFulfillable — Data Quality & the Type-Derived Rule](../../compass-usa/features/isfulfillable-data-quality-and-type-rule.md).
+- **`ItemTypes` is the only usable column in Canada.** Canada's `AssetTypes` are only
+  `Equipment` / `Hardware` / `Tablets` — **there is no `FEE` asset type in Canada at all**, so
+  `AssetTypes` gives zero signal here. USA is the opposite case; see the USA doc.
+- **Keep the `price > 0` filter.** Only **9** of Canada's **69** zero-price lines ever receive an
+  ASN, so requiring them to ship would strand orders in partiallyFulfilled forever.
+
+## Why per-line QUANTITY is the right unit (the counter-examples)
+
+- **Order totals fail.** `SAC100664`: the mouse's shipment paid for the ZBOOK's quantity.
+- **Line counts fail.** `SAC100108`: both expected lines had an ASN, so a line-count check matched —
+  but only 1 of 2 iPads and 1 of 2 accessories actually shipped. Also **96 Canada lines carry 2 to 3
+  ASN lines each**, so an ASN-line count can exceed the order-line count while the order is still
+  short.
+- **There is no line-coverage gap to catch.** Across **601** Canada orders past approval with
+  shipments, **zero** read fulfilled while an expected line had no ASN line — a line with no ASN has
+  shipped 0 and is always caught as short. A line-count check would add nothing and only weaken the
+  rule.
+- **Going per line also neutralises duplicate ASNs for the verdict.** A surplus stays on its own line
+  and can no longer cover another line's gap, so no clamping or de-duplication is needed.
+
+## The pendingFulfillment gate reads quantity, not "an ASN exists"
+
+The gate is **not** `COUNT(ASNs on the order) = 0`. Three orders (`SAC100131`, `SAC100509`,
+`SAC100522`) had an ASN raised only against an AppleCare / ABM line while **zero physical goods had
+shipped**, and therefore read partiallyFulfilled. Reading the expected-line quantity instead makes
+them correctly read **pendingFulfillment**.
 
 ## Design decisions worth keeping
 
 - **⚠ Do NOT switch Canada to the local `ItemFulfillments` / `ItemFulfillmentItems` tables**, even
   though the line-level `_qtyFulfilled` UI column does read them. They are **incomplete** in Canada:
   **47** orders have ASN shipments with no local `ItemFulfillment` at all and **52** more disagree on
-  quantity, so moving the order-level rule onto the base `_Model_Client_SalesOrder` logic would have
-  regressed roughly **99** orders.
-- **Keep the `price > 0` filter.** Only **9** of Canada's **69** zero-price lines ever receive an ASN,
-  so requiring them to ship would strand orders in partiallyFulfilled forever.
+  quantity, so moving this rule onto the base `_Model_Client_SalesOrder` logic would regress roughly
+  **99** orders.
+- **Canada deliberately has NO order-total condition.** USA keeps one; Canada does not need it,
+  because its ASN bridge is complete and its expected-line set is never empty in the way USA's is.
 - **Canada deliberately omits any Compass-vendor exclusion.** `VENDOR_ID__COMPASS = 26` on the parent
   is the **US** Compass vendor id. In `Client_CompassCanada` all **901** POs are GRAND & TOY
-  (`vendorId 1`), and "COMPASS CANADA" is `vendorId 4` with **zero** POs — so the inherited constant
-  was a latent wrong-id no-op. Do not "restore" it here.
-- **Canada needs no purchased-line filter** (unlike USA) precisely because the ASN bridge is complete
-  and the vendor set is a single vendor.
+  (`vendorId 1`), and "COMPASS CANADA" is `vendorId 4` with **zero** POs — the inherited constant is
+  a latent wrong-id no-op. Do not "restore" it here.
 
 ## Gotchas / known issues
 
+- **⚠ Uncommitted.** Both touched files pass `php -l`, nothing was committed or pushed, and the repo
+  is sitting on **`_production`** — a branch is required before committing. Canada has **not** been
+  exercised through the Supply UI yet.
 - **The badge is display-only and never stored.** The status is computed live, so there is no
-  backfill and reverting the code fully reverts the behaviour. Canada's in-transit email cron
+  backfill and reverting the code fully reverts the behaviour. **No cron, email or report reads the
+  fulfilled vs partiallyFulfilled distinction.** Canada's in-transit email cron
   (`worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php`) keeps its **own
   duplicated copy** of the `_status` CASE, but it only ever produces canceled /
   pendingApprovalUnknown / pendingFulfillment / shipped and filters on
-  `computedStatusSlug = 'shipped'` — and the pendingFulfillment gate was left byte-identical, so it
-  is unaffected.
+  `computedStatusSlug = 'shipped'`. Note the Canada pendingFulfillment gate is **no longer
+  byte-identical** to that copy (it now reads quantity, not ASN existence). The cron's copy is
+  unchanged and still only acts on `'shipped'`, so behaviour is unaffected, but the two are now a
+  genuine divergence.
 - **⚠ Canada's order status is no longer identical to Compass USA.** Older notes (and the profile)
   said "order status is shipped-only, same as Compass USA". The *stage* policy is still shared
-  (shipped-only), but the **fulfilled vs partiallyFulfilled rule now diverges by region.**
+  (shipped-only), but the **fulfilled vs partiallyFulfilled rule now diverges by region** — and it
+  diverges because **only Canada changed**.
 - **The ApprovalDecision notification query on the parent calls `self::_status()`**, not `static::`,
-  so it always evaluates the **parent** fulfillment rule even for Canada. Harmless today (it only
-  branches on pendingApproval / canceled / pendingFulfillment, and pendingFulfillment is identical
-  in both regions) but it is a trap if Canada ever changes those.
+  so it always evaluates the **parent** fulfillment rule even for Canada. Because Canada's
+  pendingFulfillment gate now differs from the parent's, that query sees the **parent's** gate for
+  Canada orders. Harmless today (it only branches on pendingApproval / canceled / pendingFulfillment
+  and acts on approvals) but it is now a real divergence, not a theoretical one.
+- **Canada's approval gate is healthy**, unlike USA's: 733 approved, 30 denied, only **19** stuck at a
+  pending-approval status. Canada also has all ten `SalesOrderStages` rows, where USA has only ids
+  5 to 9.
+
+## History: the first attempt was reverted
+
+- The original fix, commit **`90c964f1`** "Updating the status logic as per the client", was
+  **reverted by commit `43049d1d`** ("Revert …", kmaramreddy08, 2026-08-26 16:19). The revert is on
+  **`#sprint85`, `TRUE-81284`, `_beta`, `_production` and `_sandbox-client`**; only **`_sandbox-dev`**
+  still carries the original fix.
+- Every refinement made after `90c964f1` was **never committed** and is gone from git. The rule on
+  this page was therefore **rebuilt from scratch** on `_production`.
+- The ticket branch for this work is **`TRUE-81284`**, not `TRUE-80431`.
+- **Any statement that this shipped is wrong**, including the previously published "115 Canada
+  orders corrected" figure.
 
 ## Change history
-- 2026-08-26 — Fixed the false **Fulfilled** on partly-shipped Canada orders (reported via
-  `SAC100664`): the shared parent compared two order-level totals whose ordered side dropped bundle
-  child lines while the shipped side did not. Added a `_fulfillmentStatus()` override in
-  `_Model_Compass_Canada_SalesOrder` — pendingFulfillment with no ASN, otherwise partiallyFulfilled
-  if any `price > 0` line is short of its **own** ASN-bridge shipped quantity. Prod: 115 orders
-  corrected Fulfilled to Partially Fulfilled, zero promoted, all other status counts unchanged.
-  Recorded why the ASN bridge (100% complete, 947 items) is the source and the local
-  `ItemFulfillments` tables are not (would regress ~99 orders), why `price > 0` stays, and that the
-  inherited `VENDOR_ID__COMPASS = 26` is a US-only id and a no-op here. Not committed or pushed; not
-  yet exercised through the Supply UI. (bala)
+- 2026-08-27 — **Corrects the 2026-08-26 entry below, which described work that was reverted in git
+  (`90c964f1` reverted by `43049d1d`) and published a wrong count.** Canada's `_fulfillmentStatus()`
+  rebuilt from scratch as a self-contained pure per-line rule with **no order-total check**:
+  pendingFulfillment when every expected-to-ship line has received zero, partiallyFulfilled when any
+  expected line is short, else fulfilled — both branches reading the same expected-line set and the
+  same per-line quantity. "Expected to ship" now also requires `ItemTypes.name NOT IN
+  ITEM_TYPES__NOT_SHIPPABLE` (SERVICE/SERVICES/CONSULTING/WARRANTY) and
+  `COALESCE(Items.isFulfillable,1) = 1`, which released **25 fully-delivered orders** wrongly held at
+  partiallyFulfilled by PO-linked-but-never-shipped AppleCare/ABM/Profile SKUs — so the real impact is
+  **90 orders corrected, not 115**. The pendingFulfillment gate now reads expected-line quantity
+  instead of "any ASN exists", correcting `SAC100131` / `SAC100509` / `SAC100522`. Prod after:
+  489 fulfilled / 184 pendingFulfillment / 109 partiallyFulfilled. Recorded that `isFulfillable` is
+  NULL on every Canada item (so the item-type list does the work), that Canada has no `FEE` asset
+  type, and why per-line **quantity** beats order totals (`SAC100664`) and line counts (`SAC100108`).
+  Uncommitted; repo on `_production`; not yet exercised through the Supply UI. (bala)
+- 2026-08-26 — **REVERTED IN GIT — do not rely on this entry.** Original per-line
+  `_fulfillmentStatus()` override for Canada (pendingFulfillment when the order had no ASN at all,
+  otherwise partiallyFulfilled if any `price > 0` line was short of its own ASN-bridge quantity),
+  reported as 115 orders corrected. Commit `90c964f1` was reverted by `43049d1d` on 2026-08-26; the
+  rule over-corrected by 25 orders and its gate tested ASN existence rather than quantity. Superseded
+  by the 2026-08-27 entry. Still valid from this work: the ASN bridge is the correct source (100%
+  complete, 947 items), the local `ItemFulfillments` tables are not (would regress ~99 orders),
+  `price > 0` stays, and the inherited `VENDOR_ID__COMPASS = 26` is a US-only id and a no-op here.
+  (bala)
 
 ## Related docs
-- [Compass USA — order aggregate AND per-line](../../compass-usa/features/order-fulfillment-status-per-line.md)
-  — the shared parent rule, and why USA cannot use this page's rule.
+- [Compass USA — order aggregate, deliberately unchanged](../../compass-usa/features/order-fulfillment-status-per-line.md)
+  — the parent rule, and why USA was not touched.
 - [Grand & Toy ASN Import](grand-and-toy-asn-import.md) — where Canada's ASN rows come from.
 - [IF Stage Lifecycle & Order Status](../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md)
   — the shipped-only stage policy shared by both Compass regions.
+- [FIELD_SQL calculated fields](../../../2.0/apps/_underscore/features/calculated-sql-fields.md)
+  — why a region-subclass override of a calculated field is picked up at all.

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

@@ -16,7 +16,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-08-26
+updated: 2026-08-27
 owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:
@@ -148,14 +148,20 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   lifecycle stages (picked/packed/shipped) + shipped backfill are seeded by
   `dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql`.
   See [IF stage lifecycle & order status](../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md).
-- **⚠ Order status is no longer identical to Compass USA — the fulfilled-vs-partiallyFulfilled rule
-  diverged 2026-08-26.** Canada overrides `_fulfillmentStatus()` in
-  `_Model_Compass_Canada_SalesOrder` with a clean **per-line** rule sourced from the **ASN bridge
-  only** (`AdvanceShippingNoticeItems.purchaseOrderItemId` -> `SalesOrderItems_PurchaseOrderItems`,
-  100% complete here). Do not read Canada's local `ItemFulfillments` tables for this (incomplete:
-  ~99 orders would regress), and do not port USA's rule or its `VENDOR_ID__COMPASS = 26` (a US
-  vendor id; all 901 Canada POs are Grand & Toy `vendorId 1`). Fixed 115 falsely-Fulfilled prod
-  orders. See
+- **⚠ Order status is no longer identical to Compass USA — Canada is the only region whose
+  fulfilled-vs-partiallyFulfilled rule changed (2026-08-27).** Canada overrides
+  `_fulfillmentStatus()` in `_Model_Compass_Canada_SalesOrder` with a **pure per-line** rule and **no
+  order-total condition**, sourced from the **ASN bridge only**
+  (`AdvanceShippingNoticeItems.purchaseOrderItemId` -> `SalesOrderItems_PurchaseOrderItems`, 100%
+  complete here). A line counts as expected-to-ship only when `price > 0`, it has a PO-item link, its
+  `ItemTypes.name` is not in `ITEM_TYPES__NOT_SHIPPABLE` (SERVICE/SERVICES/CONSULTING/WARRANTY) and
+  `COALESCE(Items.isFulfillable,1) = 1` — the item-type list matters because Canada has PO-linked
+  AppleCare/ABM SKUs that never ship, and `isFulfillable` is NULL on every Canada item. Do not read
+  Canada's local `ItemFulfillments` tables for this (incomplete: ~99 orders would regress), and do
+  not port USA's rule or its `VENDOR_ID__COMPASS = 26` (a US vendor id; all 901 Canada POs are Grand
+  & Toy `vendorId 1`). **Corrects 90 prod orders, not the 115 previously published** — the first
+  attempt was reverted in git and over-corrected by 25 orders. **Uncommitted** (repo on
+  `_production`). See
   [Fulfilled vs Partially Fulfilled](features/order-fulfillment-status-per-line.md).
 - **Item titles in customer emails** come from the `ItemTranslations` sidecar (prod: 220 fr-CA rows,
   100% coverage of every item ever ordered). Resolve the English/translated fallback **in PHP**, never

package/knowledge/clients/compass-usa/INDEX.md

@@ -5,7 +5,7 @@
 | [Compass Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) | 2.0 | Compass's sales-order approval flow — approval/notification email lists, **manager reassignment**, VIP auto-approve, and EN/FR localization — lives **entirely i | _underscore/Model/Compass/ApprovalDecision.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Usa/ApprovalDecision.php, _underscore/Model/Compass/Canada/ApprovalDecision.php, _underscore/Model/Client/ApprovalTemplateStage.php, _underscore/Model/Quad/SalesOrder.php |
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/PurchaseOrder.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql, dbchanges2/Client_Compass/2026-06-16 - CleanupSA132763CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16b - CleanupSA132743CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16c - BackfillSA132763C40QYUCTracking.sql, dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql, dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Cost Centers — Unit Locations, numeric-only policy](features/cost-centers.md) | 2.0 | A Compass "cost center" — the value a user picks in commerce and that lands on an order — is **not** a `CostCenters` row. | toga2-commerce/src/pages/Cart/api/CartApi.ts, worker1.5/crons/toga2/compass/import_locations.php, _underscore/Model/Compass/SalesOrder.php, api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-06 - RemoveNonNumericCostCenters.sql |
-| [Compass isFulfillable — Data Quality & the Type-Derived Rule](features/isfulfillable-data-quality-and-type-rule.md) | 2.0 | A **prod-data investigation (2026-08-12, read-only)** into why so many Compass storefront lines still have a dead **Qty Fulfilled** cell. | _underscore/Model/Client/Item.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php, toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx |
+| [Compass isFulfillable — Data Quality & the Type-Derived Rule](features/isfulfillable-data-quality-and-type-rule.md) | 2.0 | A **prod-data investigation (2026-08-12, read-only)** into why so many Compass storefront lines still have a dead **Qty Fulfilled** cell. | _underscore/Model/Client/Item.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php, dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql, toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx |
 | [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql, dbchanges2/Client/2026-07-15a - ExcludeFeeItemsFromItemFulfillmentsForSalesOrdersView.sql |
 | [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Compass MITS PO Transmission to Vendors](features/mits-po-transmission-to-vendors.md) | 2.0 | The 1.0 worker cron `2_transmit_mits_purchase_orders_to_vendors.php` transmits Compass PurchaseOrders to their vendors (Office Depot, Strategic Systems, Compass | worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compasscanada/workflow/2_transmit_mits_purchase_orders_to_vendors.php, library/app/client/compass.php |
@@ -14,7 +14,7 @@
 | [Compass MR/MA Order Auto-Approval & Status Gate](features/mr-ma-order-approval-and-status.md) | 2.0 | Compass **MR** and **MA** sales orders are system-generated from the MITS / Office Depot EDI pipeline (they do not originate as user-entered SA orders) and must | _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Compass ODP EDI 850 Line-Item Resolution (VA part number to IN SKU fallback)](features/odp-edi-850-item-resolution.md) | 1.0 | How each **PO1 line** on an inbound Office Depot (ODP) **EDI 850** is resolved to a real `Client_Compass` catalog item before cron `3a_import_office_depot_purch | worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, library/app/Edi.php |
 | [Compass Office Depot EDI 855 Acknowledgement + Over-Quantity PO Guard](features/odp-edi-855-acknowledgement-and-overquantity-guard.md) | 1.0 | How Compass acknowledges Office Depot (ODP) inbound **EDI 850** purchase orders with an **X12 855**, and the **over-quantity guard** that rejects a duplicate PO | worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/4_transmit_office_depot_po_acknowledgements.php, library/app/edi.php |
-| [Compass USA — Fulfilled vs Partially Fulfilled (order aggregate AND per-line)](features/order-fulfillment-status-per-line.md) | 2.0 | TOGa Supply showed **Fulfilled** on Compass orders that were only partly shipped. | _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Canada/SalesOrder.php |
+| [Compass USA — Fulfilled vs Partially Fulfilled (order total kept; per-line rule built then rejected)](features/order-fulfillment-status-per-line.md) | 2.0 | TOGa Supply shows **Fulfilled** on Compass USA orders that are only partly shipped. | _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Canada/SalesOrder.php |
 | [Compass PEOPLE-File User Lifecycle (duplicate accounts, reactivation grace window, raw-SQL deactivation)](features/people-file-user-lifecycle.md) | 2.0 | The nightly **PEOPLE** file cron (`_Worker_Client_Compass_PeopleFile`, `worker2/Worker/Client/Compass/PeopleFile.php`) owns the whole `Users` row lifecycle for | worker2/Worker/Client/Compass/PeopleFile.php |
 | [Persona Model & Levy-Sector Gating (worker2 PEOPLE cron)](features/persona-model-and-levy-gating.md) | 2.0 | Compass USA catalogue visibility is driven by **personas** in `Client_Compass`. | worker2/Worker/Client/Compass/PeopleFile.php |
 | [Compass Sales-Order Line-Number Renumbering (and why it hangs off the SO hooks)](features/sales-order-line-renumbering.md) | 2.0 | Compass sales-order lines must stay numbered **1..N with no gaps** after any add, edit, or delete — downstream MITS/PO linking reads `lineNumber` as an identity | _underscore/Model/Compass/SalesOrderItem.php, _underscore/Model/Compass/SalesOrder.php |

package/knowledge/clients/compass-usa/features/asn-to-item-fulfillment.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-20
+updated: 2026-08-27
 owners: [jcardinal, bala]
 files:
   - _underscore/Model/Compass/AdvanceShippingNotice.php
@@ -26,6 +26,7 @@ related:
   - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
   - ../../../2.0/apps/_underscore/features/model-save-parent-cascade-stored-field-deadlock.md
   - ../../../2.0/apps/api2/features/v2-deadlock-retry.md
+  - order-fulfillment-status-per-line.md
 ---
 
 ## Summary
@@ -244,8 +245,88 @@ Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass c
   Forward-only; SA132898 repaired by `2026-06-18a` (delete the later tracking + orphaned package
   row, keep the original; no backfill needed since the correct number is already present).
 
+## Office Depot sends duplicate ASN messages (measured 2026-08-27)
+
+**When an Office Depot PO line has more than one shipping notice, it is a DUPLICATE, not a partial
+shipment.** This removes the "maybe it is a split shipment" caveat that earlier notes on this page
+left open. Line-level shape of **every** ODP PO line on prod:
+
+| Shape | ODP PO lines |
+|---|---|
+| never notified | 132,520 |
+| exactly one notice, quantity matches | 35,362 |
+| **multiple notices that EXCEED the PO line quantity** | **10,012** |
+| multiple notices that legitimately add up to the quantity | **8** |
+
+Order-level, of **30,431** ODP POs that have an ASN: **5,621** have a line credited over its PO
+quantity, **6,874** have a line that was never notified, and **1,260** have **both** — that last
+shape is the one that can mislead an order status, because a surplus on one line masks a gap on
+another.
+
+### It is being fixed, but ~7% remains
+
+Share of ASN items landing on an over-credited line, by month:
+
+| Month | Over-credited | Share |
+|---|---|---|
+| 2026-02 | 10,812 / 10,870 | 99% |
+| 2026-03 | — | 66% |
+| 2026-04 | — | 69% |
+| 2026-05 | — | 41% |
+| 2026-06 | — | 9% |
+| 2026-07 | — | 8% |
+| 2026-08 | — | 7% |
+
+Something was clearly fixed around **May/June 2026**. It is not fully fixed.
+
+### Worked example — SA135272 (raw payload evidence)
+
+PO `50309979-1` (`PurchaseOrders.id 108979`): line 1 = `9X3V1UT` qty 4, line 2 = `9D9L6UT` qty 4,
+both cleanly linked 1:1 to their sales-order lines. **Both ASNs (99473, 99685) referenced
+`lineNumber 1`; line 2 was never mentioned.** Verified from the raw payloads in
+`Logs_Compass.Api` ids **9111442** and **9152991**.
+
+The second payload is a **bad message**, not a second shipment: same line, same qty 4, but **no
+`shipToAddress`, no `trackingUrl`**, and `dateShipped = 2026-08-04T06:01:34` which is the earlier
+batch run's timestamp, where the first carried a real date of `2026-08-11`. The tracking numbers
+differ, so it is also not one shipment logged twice.
+
+**Each ASN was ALSO POSTed twice, seconds apart, with identical payloads** (`9111442`/`9111477` and
+`9152991`/`9152994`) — the sender double-fires. That is a second, separate duplication on top of the
+wrong-line problem, and it is the same traffic pattern behind the
+[same-PO deadlocks](../../../2.0/apps/_underscore/features/model-save-parent-cascade-stored-field-deadlock.md).
+
+### Ruled out: "ODP numbers lines per shipment"
+
+ODP does use **real PO line numbers**, so the drift is not a numbering convention: 45,995 ASN items
+land on line 1, 12,774 on line 2, 5,772 on line 3, continuing past line 12. On two-line POs it
+referenced line 2 **correctly in 3,447 of 4,797 cases**.
+
+### ⚠ Contract weakness to record
+
+The ASN payload identifies the PO item **positionally**, by `purchaseOrderItem.lineNumber`, **not by
+uuid**. So any line-numbering drift — on either side — silently credits the wrong item, with no
+error. This is the same positional-identity class as the PO-local `lineNumber` collision fixed in
+2026-06 (see the change history below) and it is why
+[Compass USA's per-line fulfillment rule was rejected](order-fulfillment-status-per-line.md): the
+feed cannot currently support a line-level completeness test.
+
 ## Change history
 Dated one-liners, newest first.
+- 2026-08-27 — Quantified the **Office Depot duplicate-ASN** problem on prod and settled what it is:
+  of ODP PO lines with more than one shipping notice, **10,012 exceed the PO line quantity and only 8
+  are genuine split shipments**, so a second notice on an ODP line is a **duplicate**, not a partial.
+  1,260 ODP POs carry both an over-credited line and a never-notified line — the shape that misleads
+  order status. Trend shows a fix around May/June 2026 (99% of Feb ASN items landed on over-credited
+  lines, down to ~7% in August). Worked `SA135272` back to the raw `Logs_Compass.Api` payloads
+  (9111442, 9152991): both ASNs referenced `lineNumber 1` and line 2 was never mentioned, and the
+  second payload is malformed (no `shipToAddress`, no `trackingUrl`, `dateShipped` = the earlier batch
+  run timestamp). Each ASN was also POSTed twice seconds apart with identical payloads
+  (9111442/9111477, 9152991/9152994) — the sender double-fires. Ruled out the "per-shipment line
+  numbering" theory (ODP uses real PO line numbers; line 2 referenced correctly in 3,447 of 4,797
+  two-line POs). Recorded the underlying contract weakness: the payload identifies the PO item
+  **positionally by `purchaseOrderItem.lineNumber`, not by uuid**. Investigation only, no code change;
+  this is the evidence that blocked the Compass USA per-line fulfillment rule. (bala)
 - 2026-08-20 — Recorded an **open, deterministic 500 `EO-1`** in `postPost`: an ASN item whose
   SalesOrderItem has one already-tracked `ItemFulfillmentItem` takes the reconcile path, the IFI is
   skipped by `itemFulfillmentItemHasTracking()`, and the handler then fails rather than completing —

package/knowledge/clients/compass-usa/features/isfulfillable-data-quality-and-type-rule.md

@@ -6,12 +6,13 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-12
+updated: 2026-08-27
 owners: ["bala"]
 files:
   - _underscore/Model/Client/Item.php
   - library/app/api/toga2.php
   - worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php
+  - dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql
   - toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx
 related:
   - ../profile.md
@@ -19,6 +20,7 @@ related:
   - ../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md
   - ../../../1.0/apps/library/features/netsuite-item-isfulfillable-sync.md
   - ../../../1.0/apps/worker/workflows/isfulfillable-multi-client-backfill.md
+  - ../../compass-canada/features/order-fulfillment-status-per-line.md
 ---
 
 ## Summary
@@ -30,8 +32,9 @@ set are partly wrong. This doc records the measured state of `Client_Compass` /
 **decision** to override NetSuite with a type-derived rule for Compass, and the **write-time guard**
 that decision requires in order to survive the daily NetSuite sync.
 
-No source files were changed and **no migration has been written yet**. All figures below were read
-from **production** on **2026-08-12**.
+No source files were changed and **no migration has been written yet**. Figures in the sections dated
+2026-08-12 were read from **production** on that date; the later sections (retraction, column choice,
+data-fix status) were measured on **2026-08-27** against prod and **client-sandbox** as marked.
 
 ## Measured state (prod, 2026-08-12)
 - **`Client_Compass`, catalog 1:** **770 NULL / 25 zero / 697 one.**
@@ -164,7 +167,103 @@ Because these tables are `utf8mb4_0900_ai_ci` (**case-insensitive**), the single
 data. **Do not hand-maintain two string lists**, but **do** re-confirm the Canada vocabulary
 separately, since the names genuinely differ and a US list *looks* wrong for Canada.
 
+## ⚠ RETRACTED (2026-08-27) — "it appears on an ASN, so it must be fulfillable"
+
+An in-session proposal to run `UPDATE Items SET isFulfillable = 1` for **7 Compass items — 691, 237,
+661, 2004, 2005, 703, 657** — on the grounds that they appeared to ship was **wrong and was
+withdrawn.**
+
+All 7 have `AssetTypes.name = 'FEE'` and their own descriptions confirm it: *"5-Year Comprehensive
+Coverage"*, *"Printer Warranty 3 Year Plan"*, *"Staging and Kitting Charge"*, *"Tablet Lab fee"*,
+*"Config fee for Samsung Configurations"*. **`isFulfillable = 0` is CORRECT for all of them.**
+
+They "ship" only because the vendor lists the warranty / staging charge as a **line on the shipping
+notice next to the hardware**. This is the same ride-along phenomenon measured above, seen from the
+other direction:
+
+> **Appearing on an ASN is NOT the same as being a physical good.** Never promote an item to
+> `isFulfillable = 1` on shipment evidence alone.
+
+## Never hand-edit `Items.isFulfillable`
+
+Two independent reasons, both verified:
+
+1. **It is written by the NetSuite sync.** Beyond the Phase 1 existing-item refresh already
+   documented, `dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql`
+   (`recordId 21`) registers interceptors that **copy the value up the SO / PO chain**. A manual
+   value is therefore transient by design.
+2. **It drives UI behaviour, not just data.** `toga2-supply`
+   `pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx` gates the
+   **Qty Fulfilled** cell's clickability on `String(item?.Items?.isFulfillable) === "1"`, alongside a
+   separate Compass-only check on `AssetTypes.name === "FEE"`. Flipping the flag silently changes what
+   a user can click.
+
+## Which column does code read — `ItemTypes` or `AssetTypes`? (USA)
+
+The two columns disagree, and the gap matters:
+
+| Signal | Priced Compass USA order lines | Lines ever on an ASN |
+|---|---|---|
+| `AssetTypes.name = 'FEE'` | 90,857 | 732 |
+| `ItemTypes.name = 'FEE'` | 89,921 | 70 |
+
+**936 lines are assetType FEE but NOT itemType FEE.**
+
+**Decision (developer's call): code reads `ItemTypes`, and lets `Items.isFulfillable` carry the
+assetType meaning**, because the data fix below folds **both** columns into the flag. So the flag is
+the single source of truth for consumers and `ItemTypes` is only a secondary, code-side signal.
+
+**Compass Canada has no such choice.** Canada's `AssetTypes` are only `Equipment` / `Hardware` /
+`Tablets` — **there is no `FEE` asset type in Canada at all** — so `ItemTypes` is the only usable
+column there, and Canada's fulfillment rule uses an item-type exclusion list
+(`SERVICE`, `SERVICES`, `CONSULTING`, `WARRANTY`) rather than the flag. See
+[Compass Canada — Fulfilled vs Partially Fulfilled](../../compass-canada/features/order-fulfillment-status-per-line.md).
+
+## Status of the type-derived data fix (verified 2026-08-27)
+
+The developer's two-statement `UPDATE`, scoped to **`catalogId = 1`**, sets `isFulfillable = 0` where
+`ItemTypes.name` **or** `AssetTypes.name` `IN ('FEE','SERVICEFEES')` and `1` otherwise. It is
+**pending Alex's sign-off before prod**. Verified environment state:
+
+| Environment | State |
+|---|---|
+| **client-sandbox** | **applied** — 58 fee items now `0` |
+| **dev-sandbox** | **NOT applied** — fee items still NULL or 1 |
+| prod | not applied |
+
+Two gaps to carry forward:
+
+- **⚠ The NetSuite sync rewrites some of them back.** On client-sandbox **6 fee items are back at
+  `isFulfillable = 1` despite matching the WHERE** — `US-AND-CROTHALL-PO`, `LVY_MobileOps`,
+  `US-TASKS-TECHS-IN`, `US-IOS-ESFM-NUVOLO`, `HDL-TASKUP-IN`, `Unidine-Knox` — with `dtUpdated`
+  18–25 Aug, i.e. **after** the fix ran. Their `itemType` is `SOFTWARE` / `SERVICES` / `HARDWARE`
+  while only their `assetType` says FEE, so **an itemType-based code test will not catch these if the
+  flag drifts.** This is the concrete failure mode of the column decision above, and it re-proves the
+  write-time-guard requirement recorded further up this page.
+- **⚠ The `catalogId = 1` scope misses 49 items carrying 52,367 priced order lines** —
+  `PC-KIT-OPT2` (33,259 lines), `CG-MEDKITTING` (6,317), `CG-MEDKITTING-NWN-APPLE`, `ASI-WAREHAND`,
+  `ODP-COMPASS_KIOSKBUILD` — all on **catalog 2 or NULL**, all flagged `isFulfillable = 1`, and
+  **none has ever shipped**. They cause no problem *today* only because none of them has a PO link,
+  so a purchased-line test excludes them anyway. Widen the scope or accept that the flag is wrong on
+  the largest-volume non-shipping SKU in the catalog.
+
 ## Change history
+- 2026-08-27 — **Retracted a wrong in-session proposal** to set `isFulfillable = 1` on 7 Compass items
+  (691, 237, 661, 2004, 2005, 703, 657) because they appeared on shipping notices: all 7 are
+  `AssetTypes.name = 'FEE'` warranty/staging/config charges, so `0` is correct — **appearing on an ASN
+  is not the same as being a physical good.** Recorded two hard reasons never to hand-edit the column:
+  the NetSuite sync owns it (`dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql`,
+  `recordId 21`, copies the value up the SO/PO chain) and it gates the toga2-supply Qty Fulfilled
+  cell's clickability. Settled the **column question** — code reads `ItemTypes` and lets the flag carry
+  the assetType meaning (USA: 90,857 assetType-FEE priced lines vs 89,921 itemType-FEE, **936 lines
+  assetType-only**); Canada has no `FEE` assetType at all, so it uses an item-type exclusion list
+  instead. Verified the **data fix state**: applied on **client-sandbox** (58 fee items now 0), **not**
+  in effect on dev-sandbox, not on prod. Two gaps: 6 client-sandbox fee items are **back at 1** with
+  `dtUpdated` 18–25 Aug (`US-AND-CROTHALL-PO`, `LVY_MobileOps`, `US-TASKS-TECHS-IN`,
+  `US-IOS-ESFM-NUVOLO`, `HDL-TASKUP-IN`, `Unidine-Knox` — all assetType-only FEE, so an itemType code
+  test misses them), and the `catalogId = 1` scope **misses 49 items carrying 52,367 priced lines**
+  (`PC-KIT-OPT2` at 33,259, `CG-MEDKITTING` at 6,317, …) on catalog 2 or NULL, all flagged 1 and never
+  shipped. Investigation only, no code or migration written. (bala)
 - 2026-08-12 — Prod read-only investigation of `Items.isFulfillable` across `Client_Compass` /
   `Client_CompassCanada`. Established that remaining NULLs are **structurally unreachable**
   (vendor-direct POs have no Agilant-tier SO, so the chain walk has nothing to walk — 0 NULL items

package/knowledge/clients/compass-usa/features/mr-ma-order-approval-and-status.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-26
+updated: 2026-08-27
 owners: ["rgirish", "bala"]
 files:
   - _underscore/Model/Compass/SalesOrder.php
@@ -31,11 +31,19 @@ the active `ApprovalTemplate` has no `ApprovalDecision`, `_status` returns the p
 Two independent root causes produced the stuck-order population, and both are addressed at the
 source (auto-approval + item population), **not** in the status SQL.
 
+> **⚠ Scope update (2026-08-27).** This page started as an MR/MA story, but the approval gate strands
+> **11,341** Compass USA orders overall — MR is now clean, and Office Depot (9,926) plus a live
+> Agilant Drop Ship spike account for most of it. Read
+> [The stuck population is no longer MR/MA-shaped](#-the-stuck-population-is-no-longer-mrma-shaped-re-measured-2026-08-27)
+> before acting on the older figures on this page.
+
 ## Key files / entry points
 - **`_underscore/Model/Compass/SalesOrder.php`**
-  - `_status` calculated field — approval gate runs before the fulfillment machine. **Since
-    2026-08-26 the fulfillment half is a separate `protected static _fulfillmentStatus()` called via
-    `static::`;** the approval gate described on this page is unchanged and stays in `_status()`. See
+  - `_status` calculated field — the approval gate runs **before** the fulfillment machine (gates 1–3
+    of 4). The fulfillment half sits in a separate `protected static _fulfillmentStatus()` called via
+    `static::`, which **only Compass Canada overrides — Compass USA's rule is unchanged**. That seam
+    was reverted in git on 2026-08-26 and rebuilt uncommitted; either way **the approval gate
+    described on this page is untouched and stays in `_status()`.** See
     [Fulfilled vs Partially Fulfilled](order-fulfillment-status-per-line.md) and
     [IF stage lifecycle & order status](../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md).
   - `postPost` — the `if ($isMrOrder)` block loops `foreach ([1,2] as $step)` and issues two
@@ -56,6 +64,16 @@ row on **any** order whenever an active template exists. Compass `_status` then
 `ApprovalDecision` for every active-template stage before it will look at fulfillment. No
 decision on a stage ⇒ `_status` short-circuits to that stage's slug.
 
+
+`_status` evaluates **four gates in this order**, and only the last one looks at shipping:
+
+1. an explicit `salesOrderStageId` (and not 2) wins outright;
+2. then any **denied** `ApprovalDecision` returns `canceled`;
+3. then any active-template stage with **no decision** returns that stage's slug — and **never looks
+   at shipping**;
+4. only then fulfillment (`static::_fulfillmentStatus()`).
+
+Gate 3 is where the stuck orders live.
 ### Auto-approval (the intended MR path)
 `_Model_Compass_SalesOrder::postPost` auto-approves MR orders by POSTing an approval decision for
 each of the two stages (`isApproved=true`). `_status` only checks `isApproved` on the decision —
@@ -92,7 +110,61 @@ columns is fully valid.
   `_String::parseBetween()` — see
   [_String helpers](../../../2.0/apps/_underscore/features/string-html-entity-helpers.md).
 
-## Prod status buckets (2026-07-13)
+## ⚠ The stuck population is no longer MR/MA-shaped (re-measured 2026-08-27)
+
+**The MR/MA framing on this page now understates and mislocates the problem.** The 2026-07-13 entry
+below recorded **3,119** stuck orders scoped to MR/MA. Re-measured across **all** Compass USA orders
+on the computed path:
+
+| `_status` outcome (USA, computed path) | Orders |
+|---|---|
+| fully approved, reaches fulfillment | 37,173 |
+| **stuck at a pending-approval status** | **11,341** |
+| correctly has no `Approval` row at all | 21,362 |
+| denied (returns `canceled`) | 353 |
+
+**The true figure is ~3.5x the recorded one**, and most of it is not MR/MA. Stuck orders by customer:
+
+| Customer | Stuck |
+|---|---|
+| Office Depot | 9,926 |
+| Compass | 950 |
+| Agilant | 465 |
+
+- **MR is now clean — 0 stuck against 4,584 approved.** The 2026-07-13 decisions-only backfill worked
+  and the 2026-06-03 auto-approval holds.
+- **MA is 222 and growing.**
+- The problem is **ongoing**, generating **1,200–2,000 new stuck orders a month**, and the
+  **Compass-customer share is rising**: 280 in August against 70–148 in earlier months.
+
+### ⚠ NEW LIVE SIGNAL — Agilant stuck orders spiked
+
+Agilant stuck orders ran at roughly **5 a month**, then **268 appeared on 2026-08-11**, and the rate
+has been **17–51 a day since 2026-08-24**. Every one is **`salesOrderTypeId 2` (Drop Ship)** with
+**`createdByUserId NULL`** — i.e. system-created orders on a path with no auto-approval, the same
+class of defect as the original MR problem but on a different order type. This is live and
+unresolved.
+
+### Compass Canada's gate is healthy
+
+For contrast: **733 approved, 30 denied, only 19 stuck.** Canada does not share this problem.
+
+### Verified clean (negatives worth recording)
+
+Audited in both Compass clients on 2026-08-27:
+
+- each client has exactly **one** active `ApprovalTemplate` (id 1) with two stages mapping to
+  `pendingInitialApproval` / `pendingApproval`, so the approval gate **cannot return NULL**;
+- **no order has more than one `Approval` row**, and no stage has duplicate decisions;
+- every `salesOrderStageId` in use resolves to a real `SalesOrderStages` row — no orphans;
+- therefore **`_status` cannot return NULL in either client today.**
+
+So the stuck orders are a **data-population** problem (missing decisions), not a schema or
+template-integrity problem. The 2026-07-13 ruling still stands: **do not fix them in `_status`.** The
+fulfillment rule is gate 4 and never runs for any of these 11,341 orders — see
+[Fulfilled vs Partially Fulfilled](order-fulfillment-status-per-line.md).
+
+## Prod status buckets (2026-07-13 — historical, superseded by the section above)
 | Type | NO_APPROVAL (correct — pre-template, gate falls through) | APPROVAL_NO_DECISION (STUCK) | FULLY_APPROVED |
 |---|---|---|---|
 | MR | 5922 (Sep 2025–Jan 2026) | 2927 | 583 |
@@ -123,6 +195,24 @@ Safe scoping baked in — **decisions only, never Approvals**:
   from the sibling ODP SO first).
 
 ## Change history
+- 2026-08-27 — **Re-measured the stuck-order population and reframed this page: the true figure is
+  11,341, ~3.5x the 3,119 recorded on 2026-07-13, and it is no longer MR/MA-shaped.** USA
+  computed-path split is 37,173 approved / 11,341 stuck / 21,362 correctly with no `Approval` row /
+  353 denied; by customer the stuck are Office Depot 9,926, Compass 950, Agilant 465. **MR is now
+  clean (0 stuck vs 4,584 approved), so the backfill worked**, while MA is 222 and growing and the
+  whole problem still generates 1,200–2,000 new stuck orders a month with the Compass-customer share
+  rising (280 in August vs 70–148 earlier). **New live signal: Agilant went from ~5/month to 268 on
+  2026-08-11 and 17–51/day since 2026-08-24, all `salesOrderTypeId 2` (Drop Ship) with
+  `createdByUserId NULL`.** Canada's gate is healthy (733 approved, 30 denied, 19 stuck). Recorded
+  `_status`'s explicit four-gate order, and the clean-audit negatives that make this a data-population
+  problem rather than a template one: one active template per client, no duplicate `Approval` rows or
+  decisions, no orphan `salesOrderStageId`, so `_status` cannot return NULL in either client.
+  Investigation only, no code change. (bala)
+- 2026-08-27 — Corrected the entry below: the `_fulfillmentStatus()` extraction it describes was
+  **reverted in git** (`90c964f1` reverted by `43049d1d`) and rebuilt this session. The seam is real
+  again in the working tree but **uncommitted**, and **only Compass Canada overrides it — Compass USA
+  is deliberately unchanged**. The approval gate this page documents remains untouched either way.
+  (bala)
 - 2026-08-26 — Noted that `_status()`'s fulfillment half moved into `_fulfillmentStatus()` (per-region
   seam); the approval gate this page documents is untouched, and the "do not fix stuck MR/MA orders in
   `_status`" ruling still stands — the stuck orders are empty, so no fulfillment rule helps them.

package/knowledge/clients/compass-usa/features/order-fulfillment-status-per-line.md

@@ -1,12 +1,12 @@
 ---
-title: Compass USA — Fulfilled vs Partially Fulfilled (order aggregate AND per-line)
+title: Compass USA — Fulfilled vs Partially Fulfilled (order total kept; per-line rule built then rejected)
 framework: "2.0"
 repo: _underscore
 project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-26
+updated: 2026-08-27
 owners: ["bala"]
 files:
   - _underscore/Model/Compass/SalesOrder.php
@@ -18,79 +18,127 @@ related:
   - ../../../2.0/apps/_underscore/features/sales-order-status-filter-surface.md
   - mr-ma-order-approval-and-status.md
   - asn-to-item-fulfillment.md
+  - isfulfillable-data-quality-and-type-rule.md
   - ../../../1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md
 ---
 
 ## Summary
 
-TOGa Supply showed **Fulfilled** on Compass orders that were only partly shipped. The cause was
-structural, not a data problem: the fulfillment half of `_Model_Compass_SalesOrder::_status()`
-decided fulfilled vs. partiallyFulfilled by comparing **two order-level grand totals** — an
-"ordered" sum against a "shipped" sum. A grand total lets one line's surplus cancel another line's
-gap, so an order with line 1 short and line 2 over-shipped read as complete.
-
-**"Everything shipped" is a per-line fact.** As of 2026-08-26 an order is Fulfilled only when the
-legacy aggregate condition still passes **AND** no purchased line is short of its own ordered
-quantity. Prod impact across all ~112k `Client_Compass` orders: **Fulfilled fell by exactly 5,234**
-(26,856 to 21,622), partiallyFulfilled rose by the same amount, and **nothing** moved
-partiallyFulfilled to Fulfilled.
-
-Compass Canada has the same false-Fulfilled bug but a **different** correct rule — see the
-[Canada doc](../../compass-canada/features/order-fulfillment-status-per-line.md). USA cannot use
-Canada's rule; that is the subject of the design gotcha below and is the most important thing on
-this page.
+TOGa Supply shows **Fulfilled** on Compass USA orders that are only partly shipped. The cause is
+structural: the fulfillment half of `_Model_Compass_SalesOrder` decides fulfilled vs.
+partiallyFulfilled by comparing **two order-level grand totals** — an "ordered" sum against a
+"shipped" sum. A grand total lets one line's surplus cancel another line's gap, so an order with
+line 1 short and line 2 over-shipped reads as complete.
+
+**As of 2026-08-27 Compass USA is deliberately NOT fixed.** A per-line rule was written, measured
+against prod, and then **reverted on purpose**. The parent method now holds the **original
+order-total logic moved verbatim**; the only change to USA's code path is a refactor seam so
+Compass **Canada** can override the rule.
+
+> **The reason USA was left alone is the Office Depot ASN feed, not the SQL.** ODP sends
+> **duplicate ASN messages** that credit the same PO line twice: of ODP PO lines with more than one
+> shipping notice, **10,012 exceed the PO line quantity and only 8 are legitimate split shipments**.
+> A per-line rule fed by that data would move ~5,223 orders to Partially Fulfilled, many of which
+> were probably delivered. Full evidence lives in
+> [ASN → ItemFulfillment](asn-to-item-fulfillment.md#office-depot-sends-duplicate-asn-messages-measured-2026-08-27).
+> **Revisit this page only after the ODP feed is fixed.**
+
+Compass Canada has the same false-Fulfilled bug and **has** been changed, to a pure per-line rule —
+see the [Canada doc](../../compass-canada/features/order-fulfillment-status-per-line.md). USA cannot
+adopt it as-is; that is the subject of the design gotchas below.
+
+## Status of the code (read this first)
+
+- **USA behaviour is unchanged.** The extraction was proved behaviour-neutral by simulating the PHP
+  concatenation and diffing the emitted `_status` SQL: **whitespace-identical, 7,548 normalized
+  characters both ways**.
+- An earlier attempt at a real USA change shipped as commit **`90c964f1`** and was **reverted by
+  `43049d1d`** (2026-08-26 16:19) on `#sprint85`, `TRUE-81284`, `_beta`, `_production` and
+  `_sandbox-client`. Only **`_sandbox-dev`** still carries it. So **any claim that a USA per-line
+  rule shipped — including the previously published "Fulfilled fell by exactly 5,234" — is wrong.**
+- The current working tree is **uncommitted**, on branch `_production`, and both touched files pass
+  `php -l`. The ticket branch for this work is **`TRUE-81284`**.
 
 ## Key files / entry points
 
 - **`_underscore/Model/Compass/SalesOrder.php`**
-  - `_status()` — unchanged approval gate; its fulfillment branch now calls
-    **`static::_fulfillmentStatus($alias_SalesOrders)`**.
-  - `_fulfillmentStatus()` (`protected static`, new) — the pendingFulfillment / partiallyFulfilled /
-    fulfilled decision. Shared parent, used by Compass USA; overridden by Canada.
-  - `_isPurchasedLine()` — is this line expected to ship at all?
-  - `_qtyShippedByAsn()` — per-line shipped qty from the ASN bridge.
-  - `_qtyShippedByTogaTech()` — per-line shipped qty through the Compass to ODP to TOGa Tech item chain.
-- `const VENDOR_ID__COMPASS = 26` — the **US** Compass vendor id, excluded from "purchased" lines.
+  - `_status()` — four gates, in order (see *The `_status` gate order* below). Its fulfillment branch
+    now calls **`static::_fulfillmentStatus($alias_SalesOrders)`**.
+  - `_fulfillmentStatus()` (`protected static`) — **the original order-total logic, verbatim.** This
+    is what Compass USA runs. Canada overrides it.
+  - `const VENDOR_ID__COMPASS = 26` — the **US** Compass vendor id, excluded from "purchased" lines.
+- **`_underscore/Model/Compass/Canada/SalesOrder.php`** — the only region that actually overrides the
+  rule.
 - Front end (labels only): toga2-supply `FILTERFIELDS.ts` (user-selectable status filter) and
   `renderBadge.tsx` (badge text).
 
-## How it works
-
-### The seam: `_status()` vs `_fulfillmentStatus()`
+## The `_status` gate order (unchanged, and the reason fulfillment often never runs)
 
-`_status()` keeps its original three-part shape — an explicit `salesOrderStageId` wins; then the
-approval gate (denials to canceled, any undecided stage to that stage's slug); only then fulfillment.
-The refactor moved **only** the fulfillment branch into `_fulfillmentStatus()` and calls it with
-`static::`, so a region subclass can replace the rule without touching the approval logic. The
-extraction was proved behaviour-preserving by simulating the PHP concatenation and diffing the
-emitted `_status` SQL: **whitespace-identical, same 7,548 normalized characters.**
+`_status` evaluates four gates in this order:
 
-### pendingFulfillment (byte-identical to the old logic)
+1. an explicit `salesOrderStageId` (and not 2) wins outright;
+2. then any **denied** `ApprovalDecision` returns `canceled`;
+3. then any active-template stage with **no decision** returns that stage's slug and **never looks at
+   shipping**;
+4. only then fulfillment.
 
-Still `COUNT(shipped TOGa Tech ItemFulfillments) + COUNT(ASNs on the order) = 0`. This gate was
-deliberately left untouched, which is why the in-transit email crons are unaffected (see
-*Blast radius*).
+**Gate 3 is the bigger live problem on USA.** Of USA orders on the computed path, **37,173** are
+fully approved and reach fulfillment while **11,341 are stuck at a pending-approval status** — so
+roughly a quarter of computed-path orders never reach any fulfillment rule at all. That population,
+its per-customer breakdown, and the live Agilant spike are documented in
+[MR/MA Order Approval & Status Gate](mr-ma-order-approval-and-status.md). Fixing the fulfillment rule
+would not touch a single one of them.
 
-### Fulfilled now requires two independent conditions
+## What USA runs today
 
 ```
-partiallyFulfilled  WHEN  NOT ( legacyAggregateCondition )  OR  ( any purchased line is short )
+pendingFulfillment  WHEN  COUNT(shipped TOGa Tech ItemFulfillments) + COUNT(ASNs on the order) = 0
+partiallyFulfilled  WHEN  NOT ( orderedSum <= shippedSum )        # order-level grand totals
 fulfilled           otherwise
 ```
 
-- **legacyAggregateCondition** — the original order-level `orderedSum <= shippedSum`, kept verbatim.
-- **per-line condition** — `COUNT(*) > 0` over `SalesOrderItems` where `price > 0` **AND**
-  `_isPurchasedLine()` **AND** `quantity > (_qtyShippedByAsn() + _qtyShippedByTogaTech())`.
+Both the ordered and shipped sides are the legacy expressions, with all their known defects intact:
+
+- the **ordered side filters `parentSalesOrderItemId IS NULL`** while the shipped side does not, so
+  the two sides never count the same lines. USA has **62,865** child lines, so this is widespread.
+  Canada's `SAC100664` is the minimal reproduction.
+- the **ordered side explicitly INCLUDES lines with no PO link**, i.e. it expects tax, freight and
+  service lines to ship — which is what makes the comparison unreachable for many orders.
+- the **order-level TOGa Tech shipped sum is inflated by bridge fan-out**, because it correlates
+  nothing at item level: on `SA136116` the order-level chain returns **48** where a per-item chain
+  returns **32**.
+
+These are recorded as known-wrong, not fixed. They are the case *for* a per-line rule; the ODP feed
+is the case against it.
 
-Because *new-fulfilled implies legacy-fulfilled* by construction, the change is **strictly
-corrective**: it can only downgrade a wrong Fulfilled, never promote an order that used to read
-Partially Fulfilled. That property is the whole reason the change was safe to make against 112k
-live orders, and **anyone editing this method must preserve it.**
+## The per-line rule that was built and rejected
+
+Shape tested (kept the order total as an AND, exactly so the change could only ever downgrade):
+
+```
+partiallyFulfilled  WHEN  NOT ( legacyOrderTotalCondition )  OR  ( any expected-to-ship line is short )
+```
 
-### Telling a shippable line from a service line
+Measured on prod:
 
-A line is expected to ship only when it has a `SalesOrderItems_PurchaseOrderItems` link reaching a
-`PurchaseOrders` row whose `vendorId <> VENDOR_ID__COMPASS`.
+- **5,223 orders** would move fulfilled → partiallyFulfilled.
+- **3,728 orders** were correctly held back **by keeping the order-total check as an AND** — without
+  it they would have been *promoted* to Fulfilled.
+- **1,550 USA orders have ZERO expected-to-ship lines** (priced hardware with no PO-item link at
+  all). A pure per-line rule passes **vacuously** on those and returns fulfilled on nothing. Worked
+  example: `SA127967` has five priced hardware lines (`AW5M5UT-EW`, `S24D402GAN`, `HDMM6---ODP`,
+  `9VA80AA`, `9SR37UT`), none PO-linked.
+
+**Decision (2026-08-27): reverted, not shipped.** The 5,223 cannot be trusted as corrections while
+ODP duplicate ASNs make a line's shipped quantity unreliable. Two independent conclusions follow, and
+both must survive any future attempt:
+
+- **⚠ Any future USA per-line rule MUST keep an order-total guard** (or an equivalent non-vacuous
+  check), because of the 1,550 zero-expected-line orders.
+- **⚠ Do NOT port Canada's clean per-line rule to USA.** Canada has no order-total condition at all;
+  on USA that omission alone promotes thousands of orders to a *new* false Fulfilled.
+
+## Telling a shippable line from a service line (USA column choice)
 
 **Neither `price > 0` nor `Items.inventoryType` separates shippable from non-shippable** — HYBRID
 dominates both groups. Verified on prod: `PC-KIT-OPT2`, `Tech Support`, `LEASE REFRESH`,
@@ -98,43 +146,59 @@ dominates both groups. Verified on prod: `PC-KIT-OPT2`, `Tech Support`, `LEASE R
 `CG-MEDKITTING-NWN-APPLE` and `ODP-COMPASS_MERAKI` have **zero** PO links, while real hardware does
 (`C40QYUC`: 1,208 of 1,362 lines; `MD4A4LL/A-S`: 130 of 137).
 
-> **The same `partNumber` can exist as several `Items` rows, some purchased and some not.** The test
-> must be **per line**, never per part number.
+USA fees are identifiable through **either** type column, and the two do not agree:
+
+| Signal | Priced order lines | Lines ever on an ASN |
+|---|---|---|
+| `AssetTypes.name = 'FEE'` | 90,857 | 732 |
+| `ItemTypes.name = 'FEE'` | 89,921 | 70 |
+
+**936 lines are assetType FEE but not itemType FEE.** The developer's decision is that **code reads
+`ItemTypes` and lets `Items.isFulfillable` carry the assetType meaning**, because the planned data
+fix folds both columns into the flag — see
+[isFulfillable — Data Quality & the Type-Derived Rule](isfulfillable-data-quality-and-type-rule.md).
+Note the risk that leaves: if the flag drifts back to 1, an itemType-only code test will not catch an
+assetType-only FEE item.
+
+> **The same `partNumber` can exist as several `Items` rows, some purchased and some not.** Any such
+> test must be **per line**, never per part number.
 
 ## Gotchas / known issues
 
-- **⚠ Do NOT "simplify" this to Canada's clean per-line rule.** Tested against prod: a straight port
-  of the Canada rule to USA would move **3,727 orders from partiallyFulfilled to Fulfilled** — i.e.
-  create thousands of *new* false Fulfilleds. Cause: many USA **priced hardware** lines have no
-  purchase-order-item link at all, so the purchased-line filter skips them and an order with zero
-  eligible lines passes **vacuously**. Worked example: `SA127967` has five priced hardware lines
-  (`AW5M5UT-EW`, `S24D402GAN`, `HDMM6---ODP`, `9VA80AA`, `9SR37UT`), none PO-linked, and a pure
-  per-line rule returns fulfilled. Keeping **both** conditions is what makes the direction of change
-  one-way.
-- **Duplicate ASNs over-credit a line.** A line can be credited twice, so one line shipping double
-  masks another shipping nothing. Confirmed on `SA135272` (line 1 ordered 4 / shipped 8, line 2
-  ordered 4 / shipped 0 — the old rule said fulfilled) and `SA135308` (line 3 ordered 1 / shipped 0);
-  PO item **207281** carries two ASNs each claiming qty 4. Neither order has bundle children, so
-  this is a defect distinct from the parent/child line mismatch. The per-line rule reduces but does
-  not eliminate it — a genuinely short line can still read fulfilled when its own ASNs double-count.
-- **The old ordered side explicitly INCLUDED lines with no PO link**, i.e. it expected tax, freight
-  and service lines to ship. That clause is what made the aggregate unreachable for many orders.
-- **The old ordered side filtered `parentSalesOrderItemId IS NULL` while the shipped side did not** —
-  the two sides never counted the same lines. USA has **62,865** child lines, so this was widespread.
-  Canada's `SAC100664` is the minimal reproduction; see the Canada doc.
-- **4.3% of USA ASN shipped quantity cannot be attributed to a sales-order line**, and this fix does
-  not solve it: **5,536** `AdvanceShippingNoticeItems` have a NULL `purchaseOrderItemId`, and
-  **12,163** more point at a `purchaseOrderItemId` with no `SalesOrderItems_PurchaseOrderItems` link
-  (**26,770 of 617,166 units**). Treat per-line shipped quantity as a floor, not a truth.
-- **The legacy order-level TOGa Tech shipped sum is inflated by bridge fan-out**, because it
-  correlates nothing at item level: on `SA136116` the order-level chain returns **48** where the
-  per-item chain returns **32**. `_qtyShippedByTogaTech()` is the correlated (correct) version; the
-  aggregate inside `_fulfillmentStatus()` is the legacy one and was kept only because removing it
-  would break the one-way-change guarantee.
+- **Duplicate ASNs over-credit a line — this is the blocker, not a footnote.** Confirmed on
+  `SA135272`: PO line 1 was credited twice (ordered 4 / shipped 8) while line 2 was never mentioned
+  (ordered 4 / shipped 0), and the order-total rule said fulfilled. Both ASN payloads referenced
+  `lineNumber 1`. Full analysis, the trend by month, and the payload evidence are in
+  [ASN → ItemFulfillment](asn-to-item-fulfillment.md#office-depot-sends-duplicate-asn-messages-measured-2026-08-27).
+- **4.3% of USA ASN shipped quantity cannot be attributed to a sales-order line at all**: **5,536**
+  `AdvanceShippingNoticeItems` have a NULL `purchaseOrderItemId` and **12,163** more point at a
+  `purchaseOrderItemId` with no `SalesOrderItems_PurchaseOrderItems` link (**26,770 of 617,166
+  units**). Treat per-line shipped quantity as a floor, not a truth.
+- **⚠ `self::` defeats the region seam.** `_Model_Compass_SalesOrder` calls **`self::_status()`** (not
+  `static::`) in its ApprovalDecision notification query, so that query always evaluates the parent
+  rule even for Canada orders.
+- **`salesOrderStageId = 2` is a dormant, USA-impossible branch.** `_status` hardcodes stage 2 as a
+  recompute trigger, but USA's `SalesOrderStages` table contains **only ids 5 to 9** (Pending
+  Billing, Pending Billing/Partially Fulfilled, Billed, Canceled, Closed) — stage 2 does not exist
+  there, so setting it would be an orphan. Canada has all ten. No order in either client currently
+  uses stage 2.
+
+## Verified clean (worth recording as negatives)
+
+Audited across both Compass clients on 2026-08-27:
+
+- every `salesOrderStageId` in use resolves to a real `SalesOrderStages` row — **no orphans**;
+- the approval half is structurally sound too (one active template, no duplicate `Approval` rows or
+  decisions), so **`_status` cannot return NULL in either client today** — details in
+  [MR/MA Order Approval & Status Gate](mr-ma-order-approval-and-status.md).
+
+Post-fulfillment tail (USA, explicit stage): **473** Pending Billing, **39,869** Billed, **1,592**
+Canceled, **809** Closed — the lifecycle continues Fulfilled → Pending Billing → Billed via the
+stored stage, not the computed status.
 
 ## Blast radius — fulfilled vs partiallyFulfilled is display-only
 
-Every consumer was audited before shipping, which is why this carries no downstream risk:
+Re-confirmed 2026-08-27: **no cron, email or report reads the distinction.**
 
 - **The status is computed live and never stored.** No backfill; reverting the code fully reverts the
   behaviour.
@@ -143,39 +207,47 @@ Every consumer was audited before shipping, which is why this carries no downstr
   `worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php` and
   `compass/workflow/test_partial_in_transit_email.php` each keep their **own duplicated copy** of the
   `_status` CASE, but those copies only ever produce canceled / pendingApprovalUnknown /
-  pendingFulfillment / shipped and they filter on `computedStatusSlug = 'shipped'`. They never
-  compute fulfilled or partiallyFulfilled, and the "has an ASN" condition they rely on was left
-  byte-identical. **That duplication is itself a divergence risk** — see the
+  pendingFulfillment / shipped and they filter on `computedStatusSlug = 'shipped'`. **That
+  duplication is itself a divergence risk** — see the
   [in-transit email doc](../../../1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md).
 - **The MA sales-order exception report**
   (`compass/workflow/7_generate_ma_sales_order_exception_report.php`) filters the **stored**
   `salesOrderStageId` column, not the computed status.
 - **toga2-supply** sends only the approvals filter values (`pendingInitialApproval` /
   `pendingApproval`) to the server; `fulfilled` and `partiallyFulfilled` appear only in
-  `FILTERFIELDS.ts` (user-selectable filter) and `renderBadge.tsx` (a label).
-- **⚠ One call site always uses the parent rule.** `_Model_Compass_SalesOrder` calls
-  **`self::_status()`** (not `static::`) in its ApprovalDecision notification query, so that query
-  never picks up a region override. Harmless today — it only branches on pendingApproval / canceled /
-  pendingFulfillment, and the pendingFulfillment gate is byte-identical across both regions — but it
-  is a live trap if a region ever changes those three.
+  `FILTERFIELDS.ts` and `renderBadge.tsx`.
 
 ## Change history
-- 2026-08-26 — Fixed the false **Fulfilled** on partly-shipped orders. Split the fulfillment half of
-  `_status()` into `protected static _fulfillmentStatus()` called via `static::` (proved
-  SQL-identical), then made Fulfilled require the legacy order-level aggregate **AND** no short
-  purchased line, with new helpers `_isPurchasedLine()`, `_qtyShippedByAsn()`,
-  `_qtyShippedByTogaTech()`. Fixed two USA-only defects along the way: duplicate ASNs double-crediting
-  a line, and the ordered side explicitly *including* non-PO-linked tax/freight/service lines. Prod:
-  Fulfilled 26,856 to 21,622 (down 5,234), zero orders promoted. Recorded why a clean per-line port
-  of Canada's rule is **wrong** here (3,727 new false Fulfilleds), how to identify a shippable line
-  (PO link, not price or `inventoryType`), and the ASN attribution limits that bound accuracy. Not
-  committed or pushed; not yet exercised through the Supply UI. (bala)
+- 2026-08-27 — **Corrects the 2026-08-26 entry below: no USA rule change ever shipped, and the
+  "Fulfilled fell by exactly 5,234" figure is void.** Commit `90c964f1` was reverted by `43049d1d`
+  (2026-08-26), and this session **deliberately kept USA unchanged**: `_fulfillmentStatus()` holds the
+  original order-total logic verbatim and the seam exists only for Canada's override (emitted `_status`
+  SQL whitespace-identical, 7,548 chars). A per-line USA rule was built and measured (**5,223** orders
+  would move fulfilled → partiallyFulfilled; **3,728** correctly held back by keeping the order total
+  as an AND) then reverted, because the **Office Depot ASN feed is not trustworthy at line level** —
+  10,012 ODP PO lines are credited over quantity by duplicate notices against only 8 genuine split
+  shipments. Recorded the two constraints on any future attempt: **1,550 USA orders have zero
+  expected-to-ship lines** (so a pure per-line rule passes vacuously) and Canada's rule must not be
+  ported. Also recorded the full `_status` gate order and that gate 3 (approvals) strands **11,341**
+  USA orders before fulfillment is ever evaluated, the USA FEE column choice (`ItemTypes` in code,
+  936 lines are assetType-FEE only), the dormant `salesOrderStageId = 2` branch that cannot exist in
+  USA, and the clean-audit negatives (`_status` cannot return NULL in either client).
+  Uncommitted; on `_production`; not exercised through the Supply UI. (bala)
+- 2026-08-26 — **REVERTED IN GIT — do not rely on this entry.** Reported USA as fixed by requiring the
+  legacy order-level aggregate **AND** no short purchased line, with helpers `_isPurchasedLine()`,
+  `_qtyShippedByAsn()`, `_qtyShippedByTogaTech()`, and claimed prod impact "Fulfilled 26,856 → 21,622
+  (down 5,234)". Commit `90c964f1` was reverted by `43049d1d`; the refinements after it were never
+  committed. Superseded by the 2026-08-27 entry. Still valid from this work: the false-Fulfilled root
+  cause, the shippable-line test (PO link, not price or `inventoryType`), the ASN attribution limits,
+  and that a clean per-line port of Canada's rule is wrong here. (bala)
 
 ## Related docs
 - [Compass Canada — per-line, ASN-only rule](../../compass-canada/features/order-fulfillment-status-per-line.md)
+  — the region that did change, and why its rule is safe there.
+- [Compass ASN → ItemFulfillment](asn-to-item-fulfillment.md) — the ODP duplicate-ASN evidence that
+  blocks the USA change.
+- [Compass MR/MA Order Approval & Status Gate](mr-ma-order-approval-and-status.md) — the approval
+  gate that strands more USA orders than the fulfillment rule mislabels.
 - [IF Stage Lifecycle & Order Status](../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md)
-  — the shipped-only stage policy that feeds both sides of this comparison.
 - [FIELD_SQL calculated fields](../../../2.0/apps/_underscore/features/calculated-sql-fields.md)
   — why a region-subclass override of a calculated field is picked up at all.
-- [Compass MR/MA Order Approval & Status Gate](mr-ma-order-approval-and-status.md) — the approval
-  half of `_status()`, which this change did not touch.

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

@@ -165,15 +165,22 @@ separate, related client (see its own profile).
   shared by Compass USA + Canada) counts **shipped only** — picked/packed never advance a Compass
   order. Contrast Quad, which gets the full picked/packed machine. See
   [IF stage lifecycle & order status](../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md).
-- **Fulfilled requires the order aggregate AND every purchased line (2026-08-26).** The old
-  order-level ordered-total vs shipped-total comparison let one line's surplus hide another line's
-  gap, so 5,234 prod orders read **Fulfilled** while partly shipped. `_status()`'s fulfillment branch
-  now lives in `_fulfillmentStatus()` and requires the legacy aggregate **plus** no short purchased
-  line — strictly corrective, it can only downgrade. **⚠ Do not "simplify" it to Compass Canada's
-  clean per-line rule:** many USA priced hardware lines have no PO-item link, so a pure per-line rule
-  passes vacuously and would create 3,727 *new* false Fulfilleds. Full evidence, the shippable-line
-  test, and the ASN attribution limits:
+- **⚠ Fulfilled vs Partially Fulfilled is still the old order-total rule, on purpose (2026-08-27).**
+  The order-level ordered-total vs shipped-total comparison lets one line's surplus hide another
+  line's gap, so USA orders read **Fulfilled** while partly shipped. A per-line fix was built,
+  measured (5,223 orders would move) and **deliberately reverted**, because Office Depot sends
+  **duplicate ASN messages** — 10,012 ODP PO lines are credited over quantity against only 8 genuine
+  split shipments — so line-level shipped quantity cannot be trusted yet. `_status()`'s fulfillment
+  branch does live in `_fulfillmentStatus()`, but **only Compass Canada overrides it**; the USA body
+  is the original logic verbatim. **⚠ Do not port Canada's clean per-line rule:** 1,550 USA orders
+  have no expected-to-ship line at all, so it passes vacuously and would create *new* false
+  Fulfilleds. Any earlier "5,234 orders fixed" note is void — that commit was reverted in git.
   [Fulfilled vs Partially Fulfilled](features/order-fulfillment-status-per-line.md).
+- **⚠ The approval gate strands far more orders than the fulfillment rule mislabels (2026-08-27).**
+  **11,341** Compass USA orders sit at a pending-approval status and never reach the fulfillment
+  branch at all (Office Depot 9,926, Compass 950, Agilant 465), growing 1,200–2,000 a month. MR is
+  clean; a **live Agilant Drop Ship spike** started 2026-08-11.
+  [MR/MA Order Approval & Status Gate](features/mr-ma-order-approval-and-status.md).
 - Built on the shared 2.0 Recursive Item Fulfillments engine (upstream mirroring).
 - **`Items.isFulfillable` gates the storefront Qty Fulfilled cell (2026-07).** Sourced from
   NetSuite onto the Agilant source item during the 1.0 item sync

package/package.json

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