toga-ai 1.0.669 → 1.0.671

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/2.0/apps/saml/INDEX.md

@@ -6,3 +6,4 @@
 | [SAML Downstream Integration Contract](features/downstream-integration-contract.md) | The contract a **downstream TOGa app** implements to authenticate users through the SAML gateway (`saml.togahub.com`). | saml/Controller/Index.php, _underscore/Model/Core/ClientAuthentication.php, _underscore/Model/True/ClientAuthentication.php |
 | [Rate SAML User Provisioning](features/rate-user-provisioning.md) | When a Rate user authenticates via SSO, `_Model_Rate_ClientAuthentication::getAuthenticatedSsoUser()` is called by the saml gateway. | _underscore/Model/Rate/ClientAuthentication.php, _underscore/Model/Rate/User.php, _underscore/Model/Rate/Customer.php, _underscore/Model/Rate/Contact.php |
 | [Onboarding a New SSO Client with Just-In-Time User Provisioning](workflows/onboarding-a-new-sso-client.md) | The repeatable procedure for adding a new client to the 2.0 `saml` gateway when that client's users do **not** pre-exist in our database and must be created on | saml/Controller/Index.php, _underscore/Model/Core/ClientAuthentication.php, _underscore/Model/Rate/ClientAuthentication.php, _underscore/Database.php |
+| [Rotating the SAML SP Certificate](workflows/rotating-the-saml-sp-certificate.md) | The repeatable procedure for replacing the TOGa **SAML Service Provider (SP) credential** — the X.509 cert + private key at `_underscore/Assets/ssl/togahub_com. | _underscore/Assets/ssl/togahub_com.crt, _underscore/Assets/ssl/togahub_private_key.key, _underscore/Model/Core/ClientAuthentication.php, saml/Controller/Index.php |

package/knowledge/2.0/apps/saml/workflows/rotating-the-saml-sp-certificate.md

@@ -0,0 +1,109 @@
+---
+title: Rotating the SAML SP Certificate
+framework: "2.0"
+repo: saml
+project: SAML SSO Gateway
+client: shared
+type: workflow
+status: active
+updated: 2026-08-27
+owners: ["jcardinal"]
+files:
+  - _underscore/Assets/ssl/togahub_com.crt
+  - _underscore/Assets/ssl/togahub_private_key.key
+  - _underscore/Model/Core/ClientAuthentication.php
+  - saml/Controller/Index.php
+related:
+  - 2.0/apps/saml/architecture.md
+  - 2.0/apps/saml/workflows/onboarding-a-new-sso-client.md
+---
+
+## Summary
+
+The repeatable procedure for replacing the TOGa **SAML Service Provider (SP) credential** — the
+X.509 cert + private key at `_underscore/Assets/ssl/togahub_com.crt` and
+`_underscore/Assets/ssl/togahub_private_key.key`. This credential is the SP's own identity, used
+to **sign outgoing AuthnRequests** and to **decrypt inbound assertions**. It is a bilateral,
+partner-pinned trust artifact, **not** the TLS cert that terminates browser HTTPS. There was no
+rotation runbook before this (git shows two prior undocumented swaps); this closes that gap.
+
+For *why* a self-signed, long-lived cert is the correct choice here (rather than a public-CA TLS
+cert), see the SSL certificate trust-model strategy standard.
+
+## How the SP credential is used
+
+- **Private key — signs outgoing SP AuthnRequests.** `_Model_Core_ClientAuthentication`
+  (`_underscore/Model/Core/ClientAuthentication.php`) points its `PATH_TO_PRIVATE_KEY` constant
+  at `_underscore/Assets/ssl/togahub_private_key.key` and signs with XMLSecLibs `RSA_SHA256`
+  (around lines 11 / 95 / 107).
+- **Public cert — published in SP metadata and used to decrypt assertions.** The `saml` repo's
+  `Controller/Index.php` uses the cert for assertion decryption; the `/meta` route publishes it
+  in SP metadata via `file_get_contents` read fresh on each request (no server-side cache).
+- **IdPs cache metadata up to 7 days** (`cacheDuration PT604800S`), so a cert change is not
+  guaranteed to be picked up by every IdP immediately after deploy.
+
+## Current credential (as of 2026-08-27, staged — cutover pending)
+
+A dedicated **self-signed** replacement was generated to decouple the SP credential from the
+short-lived DigiCert/Thawte TLS wildcard that had been reused as the SP cert (see Background):
+
+- Self-signed X.509, RSA 2048, SHA-256.
+- Subject/Issuer: `C=US, ST=Illinois, L=Naperville, O=TOGA Technology, Inc., CN=togahub.com`
+  (reflects the new company name TOGA Technology, Inc. / Naperville, IL — formerly Agilant
+  Solutions, Inc.). CN only, **no SANs** — SANs are meaningless for bilateral SAML/AS2 trust.
+- Validity: **2026-08-27 → 2036-08-27** (10 years). Capped at 10y because RSA 2048 is
+  NIST-assured only to ~2030; a longer term would call for RSA 4096, and client compatibility
+  with 4096 is unconfirmed.
+- SHA-256 fingerprint:
+  `0E:1E:9E:11:35:B9:74:79:6F:07:2B:1F:E7:05:B8:B6:E9:07:00:0B:9E:A2:36:94:04:F6:AC:65:AC:B0:03:78`
+
+### Where the material lives (never paste the key)
+
+- **AWS Secrets Manager**, account **654654170868**, region **us-east-1**.
+- Secret name: **`toga/ssl/togahub_com-selfsigned-2036`**.
+- ARN: `arn:aws:secretsmanager:us-east-1:654654170868:secret:toga/ssl/togahub_com-selfsigned-2036-S2r3SR`.
+- JSON keys: `{certificate, privateKey}`. Retrieve the private key from here at cutover — it is
+  **not** stored anywhere else and must never be committed or pasted into chat/docs.
+- The public cert only was staged locally at `C:\TEMP\toga-ssl-2026\togahub_com.crt`; the local
+  private key was deleted.
+
+## Cutover procedure
+
+1. **PRE-CUTOVER SAFETY CHECK — confirm this cert is not serving live TLS.** Before replacing a
+   real CA cert with a self-signed one, verify the `.crt`/`.key` at `_underscore/Assets/ssl/` is
+   **not** also terminating browser/API TLS anywhere (check the `saml` repo + its EB/Apache
+   config). TLS is normally ACM-terminated at the ALB, so this repo file should only be the
+   SAML/AS2 credential — but verify against the checked-out `saml` repo first.
+2. **Distribute the new public cert to every pinning partner** (SAML IdPs, AS2 partners, any
+   PunchOut buyer that pins our leaf) and let them import it. Include the SHA-256 fingerprint
+   above as the verification line.
+3. **Coordinate a cutover date/time** with those partners.
+4. **Replace both files in `_underscore` on the `_production` branch** — via a feature branch +
+   PR, **never a direct commit to `_production`**. No code change is needed: the path constants
+   already point at these filenames.
+5. **Redeploy `saml` after the `_underscore` merge.** `saml` pulls `_underscore` from
+   `_production` at EB build time (`.ebextensions/git.php` + prebuild hook), so a saml-only
+   deploy will **not** pick up the new cert. Deploy target: `saml-production` EB env, us-east-1,
+   DNS `saml.togahub.com`.
+6. **Deploy the cert+key to the other bilateral services** that use the same SP credential —
+   AS2 (AWS Transfer Family) and any other pinned endpoint — importing both cert and key.
+
+## Background — why the change
+
+The old `_underscore/Assets/ssl/togahub_com.crt` was a **reused DigiCert/Thawte multi-domain
+wildcard TLS cert** (issuer "Thawte TLS RSA CA G1"; SANs for togahub.com, togacommerce.com,
+togadesk.com, togaretail.com, togasupply.com, togaview.com, togaiq.com plus `*.` of each; RSA
+2048; validity Mar 2 2026 → Sep 16 2026, ~6.5 months). Reusing a short-lived public-CA TLS cert
+as the SAML SP credential accidentally coupled SAML to a ~6-month renewal treadmill and forced
+every pinning partner to reinstall on each renewal. The dedicated self-signed 10-year cert
+**decouples the SP credential from TLS renewals** — that is the whole point of the change.
+
+## Change history
+- 2026-08-27 — Created while replacing the SAML SP credential. Documented the SP cert's dual use
+  (signing AuthnRequests / decrypting assertions), the new self-signed 10-year cert identity and
+  its AWS Secrets Manager location, the pre-cutover TLS-usage safety check, and the
+  `_underscore`-then-`saml` cutover ordering. Discovered the prior cert was a reused short-lived
+  DigiCert wildcard TLS cert, which is the reason for the switch. Cutover itself still pending.
+  (jcardinal)
+</content>
+</invoke>

package/knowledge/2.0/standards/ssl-certificate-trust-model.md

@@ -0,0 +1,82 @@
+---
+title: SSL Certificate Trust-Model Strategy
+framework: "2.0"
+project: _Underscore
+client: shared
+type: standard
+status: active
+updated: 2026-08-27
+owners: [jcardinal]
+files: []
+related:
+  - ../apps/saml/workflows/rotating-the-saml-sp-certificate.md
+  - ../apps/saml/architecture.md
+---
+
+## Summary
+
+Which kind of SSL/TLS certificate to use is decided by the **trust model** of the endpoint, not
+by habit. Pick wrong and you land on a renewal treadmill; pick right and renewals become either
+invisible or irrelevant. This standard is platform-wide (1.0, 2.0, standalone, and pure-AWS
+infra). It was established while replacing the 2.0 SAML SP credential — see the
+[SAML SP certificate rotation runbook](../apps/saml/workflows/rotating-the-saml-sp-certificate.md).
+
+**Critical rule:** if a partner installs/pins OUR specific cert, use a **self-signed, long-lived**
+cert. If AWS terminates the TLS for browsers/generic clients, use **ACM public, auto-renewing**.
+Never reuse a public-CA TLS cert as a pinned bilateral credential.
+
+## The decision
+
+### 1. Bilateral / pinned trust → self-signed, long-lived
+The partner installs and pins our specific certificate: SAML SP credential, AS2 (AWS Transfer
+Family), PunchOut endpoints a buyer pins. Use a **self-signed** cert with a multi-year validity
+(we generate 10-year). Distribute the public cert to the partner; import cert + key into the
+service. Because trust is by pinning, no public CA is involved and validity can be long.
+
+### 2. Standard HTTPS, AWS-terminated → ACM public, non-exportable, auto-renewing
+Browsers / generic clients reach the endpoint through an ALB, CloudFront, or API Gateway that AWS
+terminates. Use an **ACM public certificate** (non-exportable, auto-renewing). Distribute nothing;
+renewal is invisible.
+
+### 3. Standard HTTPS, NOT AWS-terminated → ACM exportable, or move behind an ALB
+A server terminates its own TLS (e.g. the legacy Vision box). Options: an **ACM *exportable*
+public cert** (a real 2025 AWS feature) — but still ~13-month validity, so you must redeploy on
+every renewal — OR move the endpoint behind an ALB to get free auto-renew (option 2).
+
+## Why long-lived ⇒ self-signed
+
+**Every publicly-trusted cert, exportable or not, is capped at ~398 days** by the CA/Browser
+Forum, dropping toward ~47 days by 2029. Only **self-signed / private-CA** certs can be
+multi-year. So "long-lived AND distributable" necessarily means self-signed (or AWS Private CA at
+~$400/mo — rejected here as overkill).
+
+The pain of "shrinking public-cert validity" is really a **distribution problem**: automate
+distribution via ACM and it disappears; a partner who pins the leaf breaks on every rotation.
+That is exactly why bilateral, pinned credentials should be self-signed and long-lived — and why
+reusing a short-lived public-CA TLS cert as a pinned SP/AS2 credential (as we accidentally did for
+SAML) couples an otherwise stable credential to a ~6-month treadmill.
+
+## Key sizing
+
+Self-signed long-lived certs use RSA 2048 / SHA-256 with validity capped at ~10 years, because
+RSA 2048 is NIST-assured only to ~2030. A longer term would want RSA 4096, but partner
+compatibility with 4096 is often unconfirmed — verify before choosing it.
+
+## Worked example — Vision / Canon cXML PunchOut (a split-trust endpoint)
+
+The Vision cXML PunchOut endpoint (`vision.asisystem.com`, a separate domain/cert from
+togahub.com) is a single cert serving **two legs with different trust models**, which is why its
+renewals are painful:
+
+- **Server-to-server cXML leg** — auth is a `<Credential>` **SharedSecret** (localVerifyIdentity),
+  not a client cert; our cert there is only the endpoint's TLS wrapper. The buyer reinstalling our
+  cert on every renewal indicates they **pin our leaf** — effectively bilateral trust → a
+  self-signed long-lived cert fits.
+- **PunchOut portal StartPage** (`punchoutSetupResponseUrlPrefix`) is a real **browser** session →
+  needs a public-CA cert (option 2).
+
+Bundling both on one cert is the root of the pain. The fix is to **split** them: ACM for the
+browser portal, self-signed for the pinned cXML endpoint. StartPage host is per-identity
+configurable, so the split is feasible. Canon is slated to move from Vision to TOGa Commerce (2.0,
+already ALB+ACM), which auto-solves the browser leg.
+</content>

package/knowledge/INDEX.md

@@ -23,7 +23,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 13 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 9 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
-- **saml** (SAML SSO Gateway) — 4 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
+- **saml** (SAML SSO Gateway) — 5 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 12 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
 - **talos** (TOGa IQ) — 7 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)

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