toga-ai 1.0.658 → 1.0.660

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-24
+updated: 2026-08-26
 owners: ["bala"]
 files:
   - worker/crons/toga2/compass/update_salesorder_status_from_odp.php
@@ -19,6 +19,8 @@ files:
   - library/app/client/compasscanada.php
 related:
   - ../../../clients/compass-canada/features/french-order-email-localization.md
+  - ../../../clients/compass-usa/features/order-fulfillment-status-per-line.md
+  - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
 ---
 
 ## Summary
@@ -134,6 +136,17 @@ the tracking number as emailed (it retries next run).
 - **Pick the template from the language of the person actually being emailed.** The manager-approval
   reminder cron (`compass_email_reminders.php`) selected the template from the **requester's**
   language even though the mail goes to the **manager**. Fixed 2026-08-03.
+- **⚠ Each cron keeps its OWN duplicated copy of the 2.0 `_status` CASE — a standing divergence
+  risk.** `compass/update_salesorder_status_from_odp.php`,
+  `compasscanada/update_salesorder_status_from_odp.php` and
+  `compass/workflow/test_partial_in_transit_email.php` each re-implement the model's status SQL as
+  `computedStatusSlug`. Today that is safe by luck of scope: the copies only ever produce canceled /
+  pendingApprovalUnknown / pendingFulfillment / shipped and they filter on
+  `computedStatusSlug = 'shipped'`, so the 2026-08-26 rewrite of the fulfilled-vs-partiallyFulfilled
+  rule (which left the "has an ASN" pendingFulfillment gate byte-identical) did not touch them. **Any
+  future change to the pendingFulfillment or canceled branches of
+  `_Model_Compass_SalesOrder::_status()` must be mirrored into all three crons by hand.** See
+  [Compass Fulfilled vs Partially Fulfilled](../../../clients/compass-usa/features/order-fulfillment-status-per-line.md).
 - **⚠ Conflict with the new 2.0 centralized tracking-status refresh.** The delivered-email cron
   (`worker/crons/toga2/compass/send_delivered_email.php`) polls UPS itself, sends the delivered
   template (uuid `fe961c7c-277b-4a89-be1d-3d318d8c7718`) via api2 `GET /email-templates/sendEmail`,
@@ -148,6 +161,11 @@ the tracking number as emailed (it retries next run).
 
 ## Change history
 
+- 2026-08-26 — Flagged the **duplicated `_status` CASE** in the three crons as a standing divergence
+  risk after the 2.0 Compass fulfillment rule was rewritten. Verified the crons are unaffected: their
+  copies only emit canceled / pendingApprovalUnknown / pendingFulfillment / shipped and filter on
+  `shipped`, and the pendingFulfillment gate was left byte-identical. No code change here. (bala)
+
 - 2026-08-24 — Recorded the **conflict with the new 2.0 platform-wide tracking-status refresh**: that
   refresh writes `TrackingNumbers.status` via api2 PUT for all clients, and this cron's delivered
   UPDATE is guarded by `WHERE status <> 'DELIVERED'` — so if the refresh marks a Compass row

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -10,7 +10,7 @@
 | [_ApiRequest — JSON encode/decode & api-logging behavior](features/apirequest-json-content-type.md) | `_ApiRequest` is the 2.0 outbound HTTP client. | _underscore/ApiRequest.php |
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [Asynchronous Query Execution (writes-only, via Worker)](features/async-query-execution.md) | `_Query` can run a **write** query asynchronously so a long/slow write does not hold a request-scoped DB connection open long enough to hit **"MySQL server has | _underscore/Query.php, worker2/Worker/Infrastructure/Database.php, worker2/Worker/Team/Transcripts.php |
-| [FIELD_SQL calculated fields — the underscore-prefix + same-name-method contract](features/calculated-sql-fields.md) | A `FIELD_SQL` (calculated) field on a `_Model` is bound by a **two-part contract that `_Model` enforces by throwing at model-construction time**, not by convent | _underscore/Model.php, _underscore/Model/Client/SalesOrder.php, _underscore/Model/Client/ServiceRequest.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Quad/Item.php, _underscore/Model/Quad/VendorItem.php, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql |
+| [FIELD_SQL calculated fields — the underscore-prefix + same-name-method contract](features/calculated-sql-fields.md) | A `FIELD_SQL` (calculated) field on a `_Model` is bound by a **two-part contract that `_Model` enforces by throwing at model-construction time**, not by convent | _underscore/Model.php, _underscore/Model/Client/SalesOrder.php, _underscore/Model/Client/ServiceRequest.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Canada/SalesOrder.php, api2/Component/Api/V2/V2.php, _underscore/Model/Quad/Item.php, _underscore/Model/Quad/VendorItem.php, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | test/@Mark/true-80824-fedex-inflate-test.php, dbchanges2/Client_Growrk/2026-08-10e - GrowrkUpsServiceMethodCodes.sql, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Component/Library/Carriers/Usps/Usps.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Running 2.0 code from a bare CLI script (bootstrap + transactions)](features/cli-script-bootstrap.md) | A throwaway CLI script (a data check, a backfill dry-run, a render harness) that wants the real 2.0 framework — `_Model`, `_Query`, `_Database` — is **not** the | _underscore/Database.php, _underscore/Environment.php, api2/Initialize.php |
 | [_Cloud S3 helpers (copy / get / delete / list)](features/cloud-s3-helpers.md) | `_Cloud` centralizes AWS SDK S3 usage for the 2.0 stack so the `S3Client` never leaks into workers or app code. | _underscore/Cloud.php |
@@ -25,7 +25,7 @@
 | [FIELD_STORAGE fields — per-row lazy hydration and the platform-wide missing-column 500](features/field-storage-row-hydration.md) | `FIELD_STORAGE` is the 2.0 field type for blob-backed columns (S3 or local folder). | _underscore/Model.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/Invoice.php, dbchanges2/Core/HISTORIC/2024/2024-11b - item-fulfillments.sql |
 | [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/probe_je_shape.php, test/@dave/fixer.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [isFulfillable Propagation Up the SO↔PO Chain](features/fulfillable-item-propagation.md) | `Items.isFulfillable` is a boolean that gates whether a storefront line's **Qty Fulfilled** cell is actionable. | _underscore/Model/Client/Item.php, _underscore/Model/Compass/Item.php, toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx, dbchanges2/Core/2026-07-17 - Items isFulfillable RecordField.sql, dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql, dbchanges2/Client/2026-07-17 - ItemsisFulfillable.sql |
-| [Item-Fulfillment Stage Lifecycle (picked/packed/shipped) & Order Status](features/item-fulfillment-stage-lifecycle-and-order-status.md) | Every ItemFulfillment (IF) now carries an explicit **stage** — picked → packed → shipped — resolved through `ItemFulfillmentStages → ItemFulfillmentStatuses` (m | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/SalesOrderStatus.php, _underscore/Model/Client/SalesOrderItem.php, _underscore/Model/Client/Item.php, _underscore/Model/Client/PurchaseOrderItem.php, library/app/api/toga2.php, dbchanges2/Client/2026-06-30a - BackfillNullStageItemFulfillmentsToShipped.sql, dbchanges2/Client/2026-06-30b - SalesOrderStatusesPickedPacked.sql, dbchanges2/Client/2026-06-30c - ItemFulfillmentStageIdNotNull.sql, dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql |
+| [Item-Fulfillment Stage Lifecycle (picked/packed/shipped) & Order Status](features/item-fulfillment-stage-lifecycle-and-order-status.md) | Every ItemFulfillment (IF) now carries an explicit **stage** — picked → packed → shipped — resolved through `ItemFulfillmentStages → ItemFulfillmentStatuses` (m | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Canada/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/SalesOrderStatus.php, _underscore/Model/Client/SalesOrderItem.php, _underscore/Model/Client/Item.php, _underscore/Model/Client/PurchaseOrderItem.php, library/app/api/toga2.php, dbchanges2/Client/2026-06-30a - BackfillNullStageItemFulfillmentsToShipped.sql, dbchanges2/Client/2026-06-30b - SalesOrderStatusesPickedPacked.sql, dbchanges2/Client/2026-06-30c - ItemFulfillmentStageIdNotNull.sql, dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql |
 | [DB-free unit testing for _underscore model interceptors](features/model-interceptor-unit-testing.md) | `_underscore` shipped with **no** PHPUnit setup (no `composer.json`/`phpunit`; only vendored PhpOffice tests existed). | _underscore/Test/bootstrap.php, _underscore/Test/Prudential/ServiceRequestTest.php, test/@Bala/tests/netsuite_salesorder_payload_tests.php |
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php, _underscore/Model.php, _underscore/Model/Rate/Subscription.php |
 | [_Model::save() parent FK cascade — stored-SQL-field recompute deadlocks](features/model-save-parent-cascade-stored-field-deadlock.md) | `_Model::save()` runs a **generic parent foreign-key cascade**: inserting (or saving) a child row that carries an FK to a parent causes `_Model` to **re-load an | _underscore/Model.php, _underscore/Model/Client/PurchaseOrder.php, _underscore/Model/Client/AdvanceShippingNotice.php |

package/knowledge/2.0/apps/_underscore/features/calculated-sql-fields.md

@@ -13,12 +13,17 @@ files:
   - _underscore/Model/Client/SalesOrder.php
   - _underscore/Model/Client/ServiceRequest.php
   - _underscore/Model/Elite/SalesOrder.php
+  - _underscore/Model/Compass/SalesOrder.php
+  - _underscore/Model/Compass/Canada/SalesOrder.php
+  - api2/Component/Api/V2/V2.php
   - _underscore/Model/Quad/Item.php
   - _underscore/Model/Quad/VendorItem.php
   - dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql
   - dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql
 related:
   - ../architecture.md
+  - ./item-fulfillment-stage-lifecycle-and-order-status.md
+  - ../../../clients/compass-usa/features/order-fulfillment-status-per-line.md
   - ./acl-permission-chain.md
   - ../../api2/features/v2-api-error-codes.md
   - ./model-magic-field-access.md
@@ -136,6 +141,38 @@ The ACL convention for these rows: grants go to the **`Base` and `API` roles onl
 NAME**. Most other `SalesOrders` custom fields carry `Base` alone, so `Base + API` is already the
 generous end; `Developer` and `Public` get no ACL row for any field.
 
+## Overriding a calculated field per client (and per sub-client)
+
+**A client subclass override of a calculated field IS picked up, including a sub-client one.** Two
+mechanisms have to line up, and both do:
+
+1. **api2 resolves the model class from `Core.Clients.clientIdentifier`** with
+   `str_replace('_Model_Client_', '_Model_' . $clientIdentifier . '_', get_class($model))`
+   (`api2/Component/Api/V2/V2.php`, ~10 call sites), falling back to the `_Model_Client_*` class when
+   the candidate does not exist. So `Compass_Usa` (id 2) and `Compass_Canada` (id 43) resolve to
+   `_Model_Compass_Usa_SalesOrder` / `_Model_Compass_Canada_SalesOrder`.
+2. **The field expression is invoked late-bound** — `get_called_class()::$field($this::TABLE)` in
+   `Model.php` (`getSqlFieldValue` / `buildSqlFieldValue`) — so whichever class api2 resolved supplies
+   the SQL.
+
+**The safe way to give one region its own behaviour is to split the field's body into a
+`protected static` helper and call it with `static::`.** The region subclass then overrides only the
+helper, leaving the shared parts of the expression in one place. This is how
+`_Model_Compass_SalesOrder::_status()` isolates its fulfillment branch into
+`_fulfillmentStatus()` so Compass Canada can change the fulfilled-vs-partial rule with provably zero
+effect on Compass USA (see
+[Compass fulfillment status](../../../clients/compass-usa/features/order-fulfillment-status-per-line.md)).
+
+**Prove an extraction is behaviour-preserving by diffing the emitted SQL**, not by reading the diff:
+simulate the PHP string concatenation for both versions, normalize whitespace, and compare lengths
+and content. The `_status` extraction above came out whitespace-identical at 7,548 normalized
+characters — that is the standard of evidence for touching a field that runs on 112k live rows.
+
+> **⚠ `self::` defeats the whole mechanism.** A *different* method on the parent that calls
+> `self::_status()` (rather than `static::_status()`) always evaluates the **parent's** expression,
+> even for a client whose subclass overrides it. `_Model_Compass_SalesOrder` has exactly this in its
+> ApprovalDecision notification query. Late static binding only happens with `static::`.
+
 ## Gotchas / known issues
 
 - **⚠ Never add a parameter TYPE to an override whose parent declares the parameter untyped - it
@@ -173,6 +210,14 @@ generous end; `Developer` and `Public` get no ACL row for any field.
   [save-cascade stored-field deadlocks](./model-save-parent-cascade-stored-field-deadlock.md).
 
 ## Change history
+- 2026-08-26 - Documented **how to override a calculated field for one client / sub-client**: api2
+  resolves the model class by `str_replace('_Model_Client_', '_Model_' . $clientIdentifier . '_', ...)`
+  (`Component/Api/V2/V2.php`), and because the expression is invoked as
+  `get_called_class()::$field(...)` the subclass version wins - so `Compass_Usa` / `Compass_Canada`
+  each get their own SQL. Added the recommended shape (split the varying branch into a
+  `protected static` helper called via **`static::`**), the emitted-SQL diff as the standard of proof
+  for such an extraction, and the **`self::` trap** (another parent method calling `self::_status()`
+  never sees a subclass override - live example in `_Model_Compass_SalesOrder`). (bala)
 - 2026-08-26 - **`FIELDOPT_SQL_TYPE` casts the returned VALUE, not just sort/pagination cursors.**
   `getSqlFieldValue()` (`Model.php` ~L509-520) hands the fetched value to `formatValueForField()`
   (~L728), which `(float)`s a `FIELD_DECIMAL` field - so a text-returning calculated field declared

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

@@ -6,12 +6,13 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-18
+updated: 2026-08-26
 owners: [bala]
 files:
   - _underscore/Model/Client/SalesOrder.php
   - _underscore/Model/Quad/SalesOrder.php
   - _underscore/Model/Compass/SalesOrder.php
+  - _underscore/Model/Compass/Canada/SalesOrder.php
   - _underscore/Model/Compass/SalesOrderStatus.php
   - _underscore/Model/Elite/SalesOrder.php
   - _underscore/Model/Elite/SalesOrderStatus.php
@@ -29,6 +30,8 @@ related:
   - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
   - ../../../clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md
   - ../../../clients/compass-usa/features/asn-to-item-fulfillment.md
+  - ../../../clients/compass-usa/features/order-fulfillment-status-per-line.md
+  - ../../../clients/compass-canada/features/order-fulfillment-status-per-line.md
 ---
 
 ## Summary
@@ -43,7 +46,11 @@ This makes the *picked/packed* portion of the fulfillment lifecycle visible (pre
   Partially Fulfilled → Fulfilled — so non-Compass clients see the picked/packed lifecycle.
 - **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.
+  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
+  [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).
 
 Independently of order status, **inventory movement (`qtyFulfilled` / `qtyCommitted`) is
 shipped-only for ALL clients** — picked/packed quantities never count as inventory movement.
@@ -59,6 +66,11 @@ shipped-only for ALL clients** — picked/packed quantities never count as inven
 - **`Model/Compass/SalesOrder.php`** — Compass `_status`, shipped-only: both the existence
   `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
+  `_status()` and is region-independent.
+- **`Model/Compass/Canada/SalesOrder.php`** — Canada's `_fulfillmentStatus()` override (per-line,
+  ASN-bridge only).
 - **`Model/Compass/SalesOrderStatus.php`** — adds `const SLUG__PICKED = 'picked'` and
   `SLUG__PACKED = 'packed'`.
 - **`Model/Client/{SalesOrderItem,Item,PurchaseOrderItem}.php`** — the `_qtyFulfilled` /
@@ -98,7 +110,7 @@ fulfillment statuses — filter widened to `['_picked','_packed','_shipped']`:
 | Client | Statuses walked | Driven by |
 |---|---|---|
 | Base, Quad (non-SA) | Pending → Picked → Packed → Partially Fulfilled → Fulfilled | all IF stages |
-| Compass USA + Canada | Pending → Partially Fulfilled → Fulfilled | **shipped IF stage only** |
+| Compass USA + Canada | Pending → Partially Fulfilled → Fulfilled | **shipped IF stage only**; fulfilled-vs-partial rule differs per region (`_fulfillmentStatus()`) |
 | Elite | pendingFulfillment → partiallyFulfilled → fulfilled → shipped → delivered (+ canceled) | fulfillment + shipment state; **no approval stage** |
 
 Quad `SA%` orders delegate to the base machine; an explicit `salesOrderStageId` overrides the
@@ -163,11 +175,29 @@ Fan-out (`Client/`, every client) + a Compass-Canada-specific set. Execution is
   IFs changes a Compass order's status — by design it does not (the Compass supply UI must show
   shipped-only progression). This supersedes the old "stages 1/2 are unused in prod" assumption in
   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.
+- **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
+  specifically want the parent.
 - The base/Compass picked check is a string literal `'picked'` (no `SLUG__PICKED` on
   `_Model_Client_ItemFulfillmentStatus`); only the shipped check uses a constant. Adding a base IF
   picked/packed constant would let the literal be removed.
 
 ## Change history
+- 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
+  SQL proved identical), and `_Model_Compass_Canada_SalesOrder` overrides it. The shipped-only
+  **stage** policy is unchanged for both regions. Added the general gotcha that an order-level
+  ordered-total vs shipped-total comparison is not a fulfillment test, and the `self::` vs `static::`
+  trap. (bala)
 - 2026-08-18 - Added **Elite** as a third order-status policy: `_Model_Elite_SalesOrder::_status`
   walks a six-status ladder (pendingFulfillment / partiallyFulfilled / fulfilled / shipped /
   delivered / canceled) with four private helper builders and two new `SalesOrderStatuses` rows
@@ -193,3 +223,7 @@ Fan-out (`Client/`, every client) + a Compass-Canada-specific set. Execution is
   — the stage-3-Shipped invariant updated by this work.
 - [Compass ASN → ItemFulfillment Auto-Creation](../../../clients/compass-usa/features/asn-to-item-fulfillment.md)
   — ASN-created IFs now resolve the shipped stage.
+- [Compass USA — Fulfilled vs Partially Fulfilled](../../../clients/compass-usa/features/order-fulfillment-status-per-line.md)
+  — the per-region fulfillment rule (order aggregate AND per-line).
+- [Compass Canada — Fulfilled vs Partially Fulfilled](../../../clients/compass-canada/features/order-fulfillment-status-per-line.md)
+  — Canada's per-line, ASN-bridge-only override.

package/knowledge/2.0/apps/_underscore/features/surface-resolver.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-25
+updated: 2026-08-26
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Client/Language.php
@@ -79,6 +79,12 @@ with `const DATABASE`/`TABLE`, typed public-prop fields, and array FKs declaring
 `FIELDOPT_FOREIGNKEY_MODEL` (cross-DB FKs are soft — no SQL constraint). Modeled on
 `RecordField.php`/`TableView.php`.
 
+**That Core/Client split is a CLUSTER boundary, not just a schema one.** `SurfaceOverrides` lives in
+`DB_CLIENT` (there is no `Model/Core/SurfaceOverride.php`), so a question like "how many clients
+override this element?" **cannot be answered with a join** on prod — resolve the element ids in Core
+first, then count per client DB with those ids as literals. Same rule that forces client override
+seeds to inline Core ids (below).
+
 ## How `resolve()` works
 
 Inputs come from `$api` (the same accessor `_Model_Client_TableView::meta` uses):
@@ -606,6 +612,10 @@ Core record grants + their logic-group expressions all evaluate `all`/`"1"`. The
   match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-08-26 — Recorded that the Core/Client model split is a **cluster** boundary: `SurfaceOverrides`
+  is a CLIENT-DB model, so override counts across clients must be a two-step (Core ids → per-client
+  count with literal ids), never a join. Matters when deciding whether to fork or share a surface,
+  since a fork starts with **zero** overrides. (apeterson)
 - 2026-08-25 — Fixed a **whole-platform gap**: Surface message translations were inert for **every
   API-authenticated request, for every client**. `_resolveLanguageId` returned `0` when the JWT carried
   neither `id.client.languageId` nor `id.language`, and `0` makes `_loadMessages` skip the

package/knowledge/2.0/apps/dbchanges2/INDEX.md

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
 | [Re-runnable additive INSERTs (uuid4 in SQL, guards, and the DISTINCT trap)](features/rerunnable-additive-inserts.md) | Most `dbchanges2` files are **additive data grants** run by hand against production, often more than once (once per environment, or twice because someone was no | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql |
-| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Quad/2026-07-21b - ApproveDisabledTooltipPoNumber.sql, dbchanges2/Client_Quad/2026-08-21 - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Core/2026-07-29a - SalesOrderApprovalDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-05b - ApprovalDetailsShippingMethodConcatCharge.sql, dbchanges2/Core/2026-08-14a - NoteBadgesVocabularySurface.sql, dbchanges2/Client/2026-08-14a - NoteBadgeThemeTokens.sql, dbchanges2/Client/2026-08-14b - NoteBadgeUserColorFix.sql, dbchanges2/Client_Compass/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Client_CompassCanada/2026-08-14a - NoteBadgeDelegateThemeTokens.sql |
+| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Quad/2026-07-21b - ApproveDisabledTooltipPoNumber.sql, dbchanges2/Client_Quad/2026-08-21 - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Core/2026-07-29a - SalesOrderApprovalDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-05b - ApprovalDetailsShippingMethodConcatCharge.sql, dbchanges2/Core/2026-08-14a - NoteBadgesVocabularySurface.sql, dbchanges2/Client/2026-08-14a - NoteBadgeThemeTokens.sql, dbchanges2/Client/2026-08-14b - NoteBadgeUserColorFix.sql, dbchanges2/Client_Compass/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Client_CompassCanada/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Core/2026-08-26a - ServiceRequestRecordHeaderSurfaceSeed.sql, dbchanges2/Core/2026-08-26b - ServiceRequestDetailsSurfaceSeed.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | > **A local browser wizard now automates this.** Steps 2–9 below (create DBs, generate Core/API > inserts, append to `Clients_Db.txt`) — plus the dbchanges2 bla | Client/, Client_<Tenant>/, Core/, Logs_Client/ |
 | [Auditing a client DB that drifted from its models (partially applied module migration)](workflows/client-schema-drift-audit.md) | A recurring 2.0 failure mode: **one client's database drifts from what the PHP models declare**, usually because a `_modules/<module>/` migration was applied to | dbchanges2/Client_Growrk/2026-05-28.sql, dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/_modules.txt |
 | [Local vs prod MySQL config parity — why “it passed locally” is not evidence](workflows/local-vs-prod-mysql-config-parity.md) | Several migration failures that look like "prod-only bugs" are actually **per-machine MySQL server-configuration differences**. |  |

package/knowledge/2.0/apps/dbchanges2/features/surface-layer-schema.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-08-25
+updated: 2026-08-26
 owners: [jcardinal, apeterson]
 files:
   - dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql
@@ -86,6 +86,8 @@ files:
   - dbchanges2/Client/2026-08-14b - NoteBadgeUserColorFix.sql
   - dbchanges2/Client_Compass/2026-08-14a - NoteBadgeDelegateThemeTokens.sql
   - dbchanges2/Client_CompassCanada/2026-08-14a - NoteBadgeDelegateThemeTokens.sql
+  - dbchanges2/Core/2026-08-26a - ServiceRequestRecordHeaderSurfaceSeed.sql
+  - dbchanges2/Core/2026-08-26b - ServiceRequestDetailsSurfaceSeed.sql
 related:
   - ../../_underscore/features/surface-resolver.md
 ---
@@ -730,7 +732,61 @@ rule resumes.
   Element 32 is likewise `isEnabled=0` (appears but disabled until an `IS_ENABLED`/`ENABLED_RULE`
   override is added). **Open follow-up.**
 
+## Forking a surface — Service Request record surfaces (Core 45/46, 2026-08-26)
+
+The Service Request modal needed header chrome and a details section that **diverge** from the sales
+order's, so two surfaces were forked (not the whole set — `Surfaces` are per-region, so forking one
+region is the right granularity).
+
+| File | Ids | Forked from |
+|---|---|---|
+| `Core/2026-08-26a - ServiceRequestRecordHeaderSurfaceSeed.sql` | `Surfaces` **45** (`service-request-record-header`), `SurfaceElements` **161–165**, `recordId` **35** (`Records` `service-requests`, hardcoded) | `sales-order-record-header` (Surfaces 11 / elements 25–28) |
+| `Core/2026-08-26b - ServiceRequestDetailsSurfaceSeed.sql` | `Surfaces` **46** (`service-request-details`), `SurfaceElements` **166–169** | the `order-details` section |
+
+The header adds a modal tag reading "Service Request" (new `Core.Messages` key
+`serviceRequest.header.tag`) and a new **Type** FIELD element (165) between order date and status
+badge. Element **164**'s `labelTemplate` still reads `'Order {order.number}'` — **intentional**,
+confirmed by the developer; do not "fix" it.
+
+The details surface adds Type and drops Cost Center: Customer (`contact._name`), PO Number
+(`_purchaseOrders`), Type (`serviceRequest.serviceRequestType.name`), Description (`description`).
+A **Provider** field was requested but **not seeded** — no `provider` field exists on
+`_Model_Client_SalesOrder` or `_Model_Client_ServiceRequest` and nothing in `toga25-supply`
+references one. Still unresolved.
+
+> Valuekey trap: section elements use **bare** keys while header elements use `order.`-prefixed keys,
+> and the SR modal actually fetches the **linked Sales Order** — see
+> [surface-frontend](../../toga25-supply/features/surface-frontend.md#gotchas).
+
+### 🚨 Forking a surface silently DROPS every client override of the original
+`SurfaceOverrides` rows are keyed **per surface element**, so a fork starts with zero overrides — every
+per-client customization of the original section is silently gone on the new surface. **The fork-vs-share
+decision should be driven by an override count**, taken before writing the seed.
+
+Counting them is **not a join**: `Surfaces`/`SurfaceElements` are **Core** models
+(`Model/Core/Surface.php`, `Model/Core/SurfaceElement.php` → `DB_CORE`) but `SurfaceOverrides` is a
+**Client** model (`Model/Client/SurfaceOverride.php` → `DB_CLIENT`; there is no
+`Model/Core/SurfaceOverride.php`). "How many clients override this element?" spans the prod-core and
+prod-client **clusters**, so it must be two steps: resolve the element ids in Core, then count per
+client DB using those ids as **literals**.
+
+### `Surfaces`/`SurfaceElements` ids are per-ENVIRONMENT AUTO_INCREMENT — re-verify before every run
+House style seeds these with literal ids, but they are **not** among the two team-maintained-id tables
+(`Records`/`RecordFields`), so the next free value **can differ per environment** and must be
+re-verified before a migration runs anywhere new. On 2026-08-26 local and production happened to agree
+exactly (`MAX(Surfaces.id)` 44, `MAX(SurfaceElements.id)` 160) — that was **verified, not assumed**.
+Using literals is still correct: a collision then fails loudly on the primary key instead of silently
+mis-wiring (which is what `INSERT IGNORE` did in the 2026-08-24 incident above).
+
 ## Change history
+- 2026-08-26 — Seeded the **Service Request** record surfaces as a **fork** of the sales-order ones:
+  `Core/2026-08-26a` (Surfaces **45** / elements **161–165**, recordId 35) and `Core/2026-08-26b`
+  (Surfaces **46** / elements **166–169**). Recorded three durable rules: forking a surface **drops
+  every client `SurfaceOverride`** of the original, so fork-vs-share should be decided by an override
+  count; that count **cannot be a join** because `SurfaceOverrides` is a **CLIENT**-DB model while
+  `Surfaces`/`SurfaceElements` are **CORE**; and `Surfaces`/`SurfaceElements` ids are per-environment
+  `AUTO_INCREMENT` (not team-maintained), so the free block must be re-verified per environment —
+  local and prod agreed at 44/160 this time, verified not assumed. (apeterson)
 - 2026-08-25 — Added a **worked before/after cluster-isolation example** on a real client migration:
   `Client_Quad/2026-07-21b - ApproveDisabledTooltipPoNumber.sql` joins **`Core.Messages` to
   `Client_Quad.Languages`**, so it runs locally (all-in-one endpoint) and can **never** run on prod or

package/knowledge/2.0/apps/toga25-supply/INDEX.md

@@ -10,7 +10,7 @@
 | [Force Logout on Deployment (useDeploymentGuard)](features/force-logout-on-deployment.md) | On large deployments the backend bumps the Core parameter `META_LAST_REFRESH_DATETIME`. | toga25-supply/src/hooks/useDeploymentGuard.tsx, toga25-supply/src/App.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/layout/PrimaryTableServerLayout/PrimaryTableServerLayout.tsx, toga25-supply/src/layout/PrimaryTableServerLayout/types.ts, toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/GenericNestedTables.tsx, toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json, toga25-supply/src/hooks/useTableCellInteractions.ts, toga25-supply/src/hooks/useServerTableUrlState.ts, toga25-supply/src/layout/RecordApprovalModal/helpers/handleFormatApprovalWorkflowPayload.ts, toga25-supply/src/layout/RecordApprovalModal/api/approvalDecisionsApi.ts |
-| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/App.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
+| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/App.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/useServiceRequestRecordModalLayoutModel.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [Talos Integration (AppLayout host + adapter wiring)](features/talos-integration.md) | toga25-supply is the first host of the shared blox [Talos assistant](../../toga-blox/features/talos-assistant.md). | toga25-supply/src/layout/AppLayout/AppLayout.tsx, toga25-supply/src/components/Header/Header.tsx, toga25-supply/src/components/Header/Header.module.css, toga25-supply/src/index.css, toga25-supply/src/assets/talos-owl.png |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

package/knowledge/2.0/apps/toga25-supply/features/surface-frontend.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-24
+updated: 2026-08-26
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/App.tsx
@@ -17,6 +17,11 @@ files:
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
   - toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts
+  - toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx
+  - toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx
+  - toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/useServiceRequestRecordModalLayoutModel.tsx
+  - toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/FIELDS/apiFields.json
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx
   - toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx
@@ -674,7 +679,75 @@ developer asked for the **whole component**, not just badges. The old
 - **`tsc` not yet run** this session (the private `@agilant/toga-blox` registry needs npm creds);
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
+- **🚨 The Service Request modal renders the LINKED SALES ORDER, not the ServiceRequest record.**
+  `ServiceRequestRecordModalLayout.tsx` resolves the SR uuid to a SalesOrder uuid via
+  `SalesOrders.serviceRequestId` and fetches `/sales-orders/{uuid}`. So **any SR-specific field is one
+  hop further out**: the Type element was first seeded as `order.serviceRequestType.name`, which
+  resolves to nothing (SalesOrders has `serviceRequestId`, not `serviceRequestTypeId`) — the correct
+  path is `order.serviceRequest.serviceRequestType.name`. And **both halves are required**: the field
+  must ALSO be added to the modal's `apiFields.json` `fields` list or the API never returns it, and the
+  element renders blank with no error either way.
+- **🚨 Header surfaces use `order.`-prefixed valueKeys; section surfaces use BARE keys.** The record
+  modal top bar builds its surface record as `{ order }`, so header elements read `order.dateOrder`,
+  `order._status`. Section surfaces (`order-details` etc.) resolve against the order **directly**, so
+  their keys are bare: `contact._name`, `_purchaseOrders`, `description`. The same field therefore has
+  two different valueKeys depending on which surface it lives in, and copying one into the other
+  renders blank with no error.
+
+## Service Request record modal — forked from the SalesOrder modal (2026-08-26)
+
+The Service Request (SR) modal was split off the SalesOrder record modal rather than being made a
+mode of it. Three seams carry the fork; nothing else in the surface plumbing changed.
+
+**1. Its own view model.** `useServiceRequestRecordModalLayoutModel.tsx` is a fork of
+`useSalesOrderRecordModalViewModel` that keeps the record fetch, items, bundle items, invoices,
+shipments, surface sections and contact-VIP, and **drops** `useFetchApprovalStages` + the approvals
+surface gate, `usePurchaseOrderDetails` and the `meta.surface.poNumber.isComplete` derivation, and
+assignee-VIP enrichment. It uses a distinct React Query cache scope **`"service-request-modal"`** so
+it can never clobber the SO modal's `"record-modal"` scope — the two modals fetch the *same* record
+shape, so a shared key would cross-contaminate.
+
+**2. Its own view.** `ServiceRequestsView.tsx` drops `SalesOrderApprovalModalsLayout`,
+`EnterPoNumberModal`, `AdminNotesSection`, the `approvalActive` gate and the approval/standard
+summary-grid ternary.
+
+**3. A parameterized slug map (the FE decides which tenantFields slot a section fills).**
+`surfaceBundleToTenantFields(surfaces, slugToKey = SECTION_SLUG_TO_KEY)` now takes the map as an
+argument. `SERVICE_REQUEST_SECTION_SLUG_TO_KEY` maps `service-request-details` → the **same**
+`orderDetails` slot, so a forked surface renders in the existing `SalesOrderSummaryGrid` with no grid
+change. `SalesOrderTopBar` gained an optional `headerSurfaceSlug` prop (default
+`sales-order-record-header`) so the SR view passes `service-request-record-header`.
+
+> Interim seam, deliberately. Extracting the top bar into a generic `RecordModalTopBar` was explicitly
+> deferred by the developer — do not "clean this up" unprompted.
+
+### Decision — FE-passed slug map, NOT a backend-declared `config.sectionKey`
+Three options were weighed for how the FE maps a section surface to a tenantFields slot:
+- **(a) derive the key from the slug** (kebab→camel) — rejected: breaks *silently* the moment slugs
+  diverge, which is exactly what forking does.
+- **(b) key off `config.cardType`** — rejected: cardType is a *renderer* type shared by several
+  sections, so it cannot identify a slot.
+- **(c) have each surface declare `config.sectionKey` and make the adapter generic** — drafted,
+  including a Core backfill migration for the 11 existing section surfaces, then **rejected by the
+  developer because of the backfill**. It remains the cleaner long-term design if the backfill is
+  ever accepted.
+
+Final: the parameterized FE map above.
+
+### Open — the SR modal still resolves `sales-order-record-actions`
+`SurfaceActionBar` in the SR modal still resolves the sales-order actions surface, so every action
+button except **View Log** renders and does nothing on click. Whether the SR modal gets its own
+actions surface is **still an open decision**, not an oversight.
+
 ## Change history
+- 2026-08-26 — Forked the **Service Request record modal** off the SalesOrder modal: own view model
+  (`"service-request-modal"` query scope; no approvals/PO-details/assignee-VIP), own view (no approval
+  modals, EnterPoNumberModal or AdminNotesSection), and a parameterized
+  `surfaceBundleToTenantFields(surfaces, slugToKey)` + `SalesOrderTopBar.headerSurfaceSlug` so forked
+  surfaces render in the existing grid. Recorded the decision to use an FE-passed slug map over a
+  backend `config.sectionKey` (backfill rejected), and two gotchas: the SR modal actually renders the
+  **linked Sales Order**, and header vs section surfaces use `order.`-prefixed vs **bare** valueKeys.
+  SR modal still resolves `sales-order-record-actions` — open. (apeterson)
 - 2026-08-24 — **Corrected the surface-meta cache gotcha (supersedes the prior "a hard reload /
   re-login is required" wording, which was wrong enough to misdirect debugging).** The React Query
   cache is **persisted to `localStorage`**: `App.tsx` uses `PersistQueryClientProvider` +

package/knowledge/INDEX.md

@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 67 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 69 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 57 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 11 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

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

@@ -5,5 +5,6 @@
 | [French (fr-CA) Item Feature Translations (Compass Canada)](features/french-item-feature-translations.md) | 2.0 | Renders item **feature** text on the Compass Canada French storefront — feature names, feature-group headers (e.g. | _underscore/Model/Compass/Canada/Feature.php, _underscore/Model/Compass/Canada/ItemCategoryFeatureGroup.php, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, worker2/Worker/Etilize/ItemTranslations.php, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql, dbchanges2/Client_CompassCanada/2026-07-13 - FeatureAttributeCustomFields.sql, dbchanges2/Client_CompassCanada/2026-07-13 - DedupeItemFeaturesAndGroups.sql, dbchanges2/Client_CompassCanada/2026-07-13 - SeedFrenchFeatureTranslations.sql |
 | [French (fr-CA) Order Email Localization (Compass Canada)](features/french-order-email-localization.md) | 2.0 | Compass Canada order emails (order requested, manager-approval request, approved/rejected, in-transit, delivered, reminders) are sent in **each recipient's own | _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/ApprovalDecision.php, _underscore/Component/Api/Togaiq/Togaiq.php, _underscore/String.php, library/app/client/compasscanada.php, worker/crons/toga2/compasscanada/send_delivered_email.php, worker/crons/toga2/compasscanada/compass_email_reminders.php, worker/crons/toga2/compasscanada/compass_cancel_pending_approval_orders.php, worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php, worker/crons/toga2/compasscanada/workflow/4_import_grand_and_toy_advance_shipping_notices.php, worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_delivered_email.php, worker/crons/toga2/compasscanada/workflow/test_email_previews_prod.php |
 | [Grand & Toy ASN Import (Compass Canada)](features/grand-and-toy-asn-import.md) | 2.0 | Imports Grand & Toy (G&T) Advance Shipping Notices for Compass Canada. | api2/Component/Api/Cxml/Cxml.php, worker/crons/toga2/compasscanada/workflow/4_import_grand_and_toy_advance_shipping_notices.php, worker/crons/toga2/compasscanada/workflow/import_grand_and_toy_asn_from_file.php, worker/crons/toga2/compasscanada/workflow_beta/import_grand_and_toy_asn_from_file.php, worker/schedules/cron.worker.sync.json, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/Canada/AdvanceShippingNotice.php, dbchanges2/Client_CompassCanada/ |
+| [Compass Canada — Fulfilled vs Partially Fulfilled (per-line, ASN bridge only)](features/order-fulfillment-status-per-line.md) | 2.0 | TOGa Supply showed **Fulfilled** on Compass Canada orders that were only partly shipped. | _underscore/Model/Compass/Canada/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php |
 | [Compass Canada](profile.md) | 2.0 | Compass Canada is the Canadian arm of the Compass account — a separate TOGA tenant, related to but distinct from Compass USA. |  |
 | [Grand & Toy ASN Backfill (cXML replay + CSV-to-JSON)](workflows/grand-and-toy-asn-backfill.md) | 2.0 | How to recover Compass Canada shipments whose ASN never landed — used on 2026-08-20 to backfill the 67-day Grand & Toy outage (**518 shipments**: 171 via cXML r | worker/crons/toga2/compasscanada/workflow_beta/import_grand_and_toy_asn_from_file.php, api2/Component/Api/Cxml/Cxml.php, _underscore/Model/Compass/AdvanceShippingNotice.php |

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

@@ -0,0 +1,130 @@
+---
+title: Compass Canada — Fulfilled vs Partially Fulfilled (per-line, ASN bridge only)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: compass-canada
+type: client-feature
+status: active
+updated: 2026-08-26
+owners: ["bala"]
+files:
+  - _underscore/Model/Compass/Canada/SalesOrder.php
+  - _underscore/Model/Compass/SalesOrder.php
+related:
+  - ../../compass-usa/features/order-fulfillment-status-per-line.md
+  - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
+  - ../../../2.0/apps/_underscore/features/calculated-sql-fields.md
+  - grand-and-toy-asn-import.md
+  - ../../../1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md
+---
+
+## Summary
+
+TOGa Supply showed **Fulfilled** on Compass Canada orders that were only partly shipped. Reported on
+`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
+> [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.
+
+## 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
+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.
+
+### The per-line shipped source (ASN bridge, and only the ASN bridge)
+
+```
+AdvanceShippingNoticeItems.purchaseOrderItemId
+  -> SalesOrderItems_PurchaseOrderItems.purchaseOrderItemId
+  -> SalesOrderItems_PurchaseOrderItems.salesOrderItemId
+```
+
+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.
+
+## 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.
+- **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.
+
+## Gotchas / known issues
+
+- **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
+  (`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.
+- **⚠ 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.**
+- **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.
+
+## 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)
+
+## 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.
+- [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.

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

@@ -16,7 +16,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-08-20
+updated: 2026-08-26
 owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:
@@ -29,6 +29,7 @@ related:
   - ../compass-usa/features/people-file-user-lifecycle.md
   - ../compass-usa/features/isfulfillable-data-quality-and-type-rule.md
   - features/french-order-email-localization.md
+  - features/order-fulfillment-status-per-line.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
   - ../../2.0/apps/_underscore/features/surface-resolver.md
@@ -143,10 +144,19 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   207 → 1. See
   [isFulfillable — Data Quality & the Type-Derived Rule](../compass-usa/features/isfulfillable-data-quality-and-type-rule.md).
 - The 2026-06-08 ASN → ItemFulfillment work was for **Compass USA**, not Compass Canada.
-- **Order status is shipped-only**, same as Compass USA (shared `_Model_Compass_SalesOrder`).
-  Compass Canada's own IF lifecycle stages (picked/packed/shipped) + shipped backfill are seeded by
+- **Order status is shipped-only** (shared `_Model_Compass_SalesOrder`). Compass Canada's own IF
+  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
+  [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
   as a SQL `COALESCE` — the two columns' collations differ and differ *per client DB*.

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

@@ -14,6 +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 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/mr-ma-order-approval-and-status.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-05
+updated: 2026-08-26
 owners: ["rgirish", "bala"]
 files:
   - _underscore/Model/Compass/SalesOrder.php
@@ -14,6 +14,7 @@ files:
   - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
 related:
   - mits-po-to-so-item-linking.md
+  - order-fulfillment-status-per-line.md
   - ../workflows/odp-order-pipeline-to-netsuite.md
   - ../workflows/order-lifecycle-and-data-integrity.md
   - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
@@ -32,9 +33,11 @@ source (auto-approval + item population), **not** in the status SQL.
 
 ## Key files / entry points
 - **`_underscore/Model/Compass/SalesOrder.php`**
-  - `_status` calculated field — approval gate runs before the shipped-only fulfillment machine
-    (see [IF stage lifecycle & order status](../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md)
-    for the fulfillment half).
+  - `_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
+    [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
     `internalApiRequest('POST', '/approval-decisions', …)` with `isApproved=true`,
     note `'Auto-approved: MR order'`. **Went live 2026-06-03.**
@@ -120,6 +123,10 @@ Safe scoping baked in — **decisions only, never Approvals**:
   from the sibling ODP SO first).
 
 ## Change history
+- 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.
+  (bala)
 - 2026-08-05 — Recorded an **open, unfixed** defect in the MR auto-approval path: the
   `ApprovalTemplateStage`-not-found `throw new _Exception(...)` passes 1 argument to a 5-argument
   constructor, so that failure raises `ArgumentCountError` and loses its own diagnostic message.

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

@@ -0,0 +1,181 @@
+---
+title: Compass USA — Fulfilled vs Partially Fulfilled (order aggregate AND per-line)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-08-26
+owners: ["bala"]
+files:
+  - _underscore/Model/Compass/SalesOrder.php
+  - _underscore/Model/Compass/Canada/SalesOrder.php
+related:
+  - ../../compass-canada/features/order-fulfillment-status-per-line.md
+  - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
+  - ../../../2.0/apps/_underscore/features/calculated-sql-fields.md
+  - ../../../2.0/apps/_underscore/features/sales-order-status-filter-surface.md
+  - mr-ma-order-approval-and-status.md
+  - asn-to-item-fulfillment.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.
+
+## 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.
+- 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()`
+
+`_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.**
+
+### pendingFulfillment (byte-identical to the old logic)
+
+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*).
+
+### Fulfilled now requires two independent conditions
+
+```
+partiallyFulfilled  WHEN  NOT ( legacyAggregateCondition )  OR  ( any purchased line is short )
+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())`.
+
+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.**
+
+### Telling a shippable line from a service line
+
+A line is expected to ship only when it has a `SalesOrderItems_PurchaseOrderItems` link reaching a
+`PurchaseOrders` row whose `vendorId <> VENDOR_ID__COMPASS`.
+
+**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`,
+`LT-FREIGHT`, `LT-PROPERTY TAX`, `LTX-SALES TAX`, `LT-HPWARRANTY`, `TabAdminSupp`,
+`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.
+
+## 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.
+
+## Blast radius — fulfilled vs partiallyFulfilled is display-only
+
+Every consumer was audited before shipping, which is why this carries no downstream risk:
+
+- **The status is computed live and never stored.** No backfill; reverting the code fully reverts the
+  behaviour.
+- **In-transit / delivered email crons are unaffected.**
+  `worker/crons/toga2/compass/update_salesorder_status_from_odp.php`,
+  `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
+  [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.
+
+## 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)
+
+## Related docs
+- [Compass Canada — per-line, ASN-only rule](../../compass-canada/features/order-fulfillment-status-per-line.md)
+- [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

@@ -30,6 +30,7 @@ related:
   - workflows/granting-persona-bundle-access.md
   - features/mits-sales-order-transmission-alerting.md
   - features/asn-to-item-fulfillment.md
+  - features/order-fulfillment-status-per-line.md
   - features/cost-centers.md
   - features/isfulfillable-data-quality-and-type-rule.md
   - features/approval-decision-flow.md
@@ -163,6 +164,15 @@ 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](features/order-fulfillment-status-per-line.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/knowledge/clients/elite/profile.md

@@ -6,6 +6,7 @@ apps:
   - worker2
   - library
   - toga2-supply
+  - toga25-supply
   - dbchanges2
   - _underscore
   - api2
@@ -15,7 +16,7 @@ project: Worker
 client: elite
 type: profile
 status: active
-updated: 2026-08-20
+updated: 2026-08-26
 owners: [snaredla, apeterson, tcox, bala]
 files:
   - worker2/Worker/Elite.php

package/package.json

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