toga-ai 1.0.657 → 1.0.659

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/dbchanges2/INDEX.md

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [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 |
 | [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 |

package/knowledge/2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md

@@ -0,0 +1,139 @@
+---
+title: Re-runnable additive INSERTs (uuid4 in SQL, guards, and the DISTINCT trap)
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: shared
+type: feature
+status: active
+updated: 2026-08-26
+owners: [bala]
+files:
+  - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
+related:
+  - ../architecture.md
+  - ../../_underscore/features/acl-permission-chain.md
+  - ../../_underscore/features/tracking-number-bridges.md
+  - ../../../../clients/compass-usa/workflows/granting-persona-bundle-access.md
+---
+
+## Summary
+
+Most `dbchanges2` files are **additive data grants** run by hand against production, often more than
+once (once per environment, or twice because someone was not sure it took). Two mechanics decide
+whether that is safe: how you generate the `uuid` every 2.0 table demands, and how you guard the
+insert. Both have a trap that fails **silently** rather than erroring.
+
+Every 2.0 table carries a `uuid` column that is `char(36) NOT NULL` **with no default** — the model
+layer fills it in application code, so a hand-written `INSERT` must supply it itself.
+
+## How it works
+
+### Generating a real UUID4 inline
+
+The standard is "UUID4, random — never MySQL `UUID()`" (`UUID()` is v1: MAC address + timestamp, and
+sequential). MySQL 8's `RANDOM_BYTES()` gives a genuinely random, correctly **version-4-shaped** value
+in one expression:
+
+```sql
+LOWER(CONCAT(HEX(RANDOM_BYTES(4)), '-', HEX(RANDOM_BYTES(2)), '-4', RIGHT(HEX(RANDOM_BYTES(2)), 3), '-', SUBSTRING('89ab', FLOOR(1 + RAND() * 4), 1), RIGHT(HEX(RANDOM_BYTES(2)), 3), '-', HEX(RANDOM_BYTES(6))))
+```
+
+The two literals are what make it v4 rather than just random hex: the `'-4'` pins the version nibble,
+and `SUBSTRING('89ab', …)` picks the variant nibble. Verified working on prod MySQL **8.0.39**.
+
+**Existing rows are not the pattern to copy.** Plenty of live rows across these tables are random hex
+that is *not* v4-shaped (older migrations concatenated `RANDOM_BYTES` without the version/variant
+nibbles). They are fine and must not be "fixed" — but do not use them as the template for new SQL.
+
+### ⚠ `DISTINCT` cannot dedupe a row that carries a random uuid
+
+This is the silent one. In an `INSERT … SELECT`, putting the uuid expression inside a
+`SELECT DISTINCT` **disables the dedupe entirely** — the per-row random uuid makes every candidate
+row unique, so `DISTINCT` has nothing to collapse and every duplicate id passes through.
+
+```sql
+# WRONG — DISTINCT never removes anything; the uuid differs on every row
+INSERT INTO Personas_Items (uuid, personaId, itemId)
+SELECT DISTINCT
+	LOWER(CONCAT(HEX(RANDOM_BYTES(4)), …)),
+	@personaId,
+	bi.itemId
+FROM BundleItems bi
+INNER JOIN Bundles b ON b.id = bi.bundleId
+WHERE b.number = '243';
+
+# CORRECT — dedupe the id set in a derived table, generate the uuid in the OUTER select
+INSERT INTO Personas_Items (uuid, personaId, itemId)
+SELECT
+	LOWER(CONCAT(HEX(RANDOM_BYTES(4)), …)),
+	@personaId,
+	src.itemId
+FROM (
+	SELECT DISTINCT bi.itemId
+	FROM BundleItems bi
+	INNER JOIN Bundles b ON b.id = bi.bundleId
+	WHERE
+		b.number = '243' AND
+		bi.isActive = 1 AND
+		bi.itemId IS NOT NULL
+) src;
+```
+
+The same shape is the fix for the self-referencing `INSERT … NOT EXISTS` error 1093 (MySQL will not
+let you read the table you are inserting into) — wrap the read in a derived table.
+
+### Guarding the insert: know whether the table has a unique key
+
+Whether a re-run is loud or silent depends entirely on the target table's indexes, and bridge tables
+in 2.0 are **inconsistent** about this — some have a composite unique key, some do not. Check
+before you write, not after.
+
+- **Unique key present** — a re-run errors. Loud, recoverable, but it aborts the rest of the file.
+  Add a guard if you want a clean no-op.
+- **No unique key** — a re-run **silently duplicates every row**, and nothing tells you. Always guard
+  these.
+
+Both guard shapes are in use and equivalent:
+
+```sql
+# LEFT JOIN … IS NULL
+FROM Users u
+INNER JOIN Roles r ON r.name = 'SuperUser'
+LEFT JOIN Users_Roles ur ON ur.userId = u.id AND ur.roleId = r.id
+WHERE
+	u.email = '…' AND
+	ur.id IS NULL;
+```
+
+**A guarded insert that inserts zero rows is a success, not a wasted file** — see
+[Client-DB grant migrations are re-runnable NO-OPs](../../_underscore/features/acl-permission-chain.md).
+
+### `LAST_INSERT_ID()` into a session variable ties the whole file to one session
+
+The common shape — `INSERT` a parent, `SET @parentId = LAST_INSERT_ID();`, then insert children
+against `@parentId` — means **every phase must run in the same connection**. Reconnecting between
+phases leaves `@parentId` `NULL` and the child inserts either fail on the FK or write `NULL`. Say so
+in the file header, and make the unguarded parent insert the one phase you skip on a re-run (set
+`@parentId` to the existing row by hand instead).
+
+## Gotchas
+
+- **A "re-run safe" file is usually only re-run safe *per phase*.** If Phase 1 creates the parent row
+  with no `NOT EXISTS` guard, re-running the *whole file* creates a **second parent** and then hangs
+  a full set of children off it. Re-run safety of the child phases does not make the file idempotent.
+- **`number` columns are strings.** `Bundles.number`, `Personas.number` and friends are varchar, not
+  int — quote them (`WHERE b.number = '243'`) and `CAST(… AS UNSIGNED)` when you need numeric sort
+  order. An unquoted comparison forces a string→number coercion that will not use the index.
+- **`Client_*` files may not reach into `Core`.** Unrelated to uuids but it bites the same kind of
+  file: separate production clusters mean a `Core.` reference is unrunnable in prod even though it
+  works locally. Hardcode `Core.Records` / `Core.RecordFields` ids as literals — see
+  [dbchanges2 architecture](../architecture.md).
+
+## Change history
+- 2026-08-26 — Initial: recorded the inline **UUID4** expression built on MySQL 8 `RANDOM_BYTES()`
+  (version/variant nibbles pinned; verified on prod 8.0.39) and the silent
+  **`SELECT DISTINCT` + random-uuid** trap that lets duplicate rows through — dedupe the id set in a
+  derived table and generate the uuid in the outer select. Added the unique-key/guard rule for bridge
+  tables (no unique key = silent duplicates on re-run) and the `LAST_INSERT_ID()` one-session
+  constraint. Extracted from the Compass Creative Studio persona grant. (bala)

package/knowledge/INDEX.md

@@ -18,10 +18,10 @@ _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)_ — 9 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
+- **dbchanges2** (Database Changes) _(framework core)_ — 11 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 9 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 4 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 12 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/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,12 +14,14 @@
 | [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 |
 | [Stranded Approval Reassignment (repointing approvals off dead duplicate Compass Users rows)](features/stranded-approval-reassignment.md) | 2.0 | A Compass employee who leaves and comes back after more than `CONTACT_UNLINK_GRACE_DAYS` (5) is **inserted as a brand-new `Users` row** by the PEOPLE importer i | _underscore/Model/Compass/ApprovalDecision.php, worker2/Worker/Client/Compass/ApprovalReassignment.php, worker2/Worker/Client/Compass/PeopleFile.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
 | [Compass Cross-Kit Bundle Corruption — Detection & Repair](workflows/cross-kit-bundle-corruption.md) | 2.0 | A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle (kit) line items and **fees/warranties** to the **wrong kit**, pe | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
+| [Granting a Compass user access to a bundle (persona grant) and the SuperUser role](workflows/granting-persona-bundle-access.md) | 2.0 | "Give user X sight of kit N" is a **recurring** Compass request, usually paired with "and make them a super user". | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql |
 | [Compass Office Depot Duplicate PO-Line Cleanup (dual-catalog SKU)](workflows/odp-duplicate-po-line-cleanup.md) | 1.0 | The NetSuite fulfillment-sales-order importer duplicated Office Depot purchase-order lines on Compass USA because it reconciled the fulfillment SO against the e | library/app/api/toga2.php, dbchanges2/Client_Compass/2026-07-22a - CleanupOfficeDepotDuplicatePurchaseOrderItems.sql |
 | [Recovering a Lost Compass ODP EDI 850 Import (re-drop from Logs.FileLog)](workflows/odp-edi-import-recovery.md) | 1.0 | How to recover a Compass **Office Depot EDI 850** import that failed partway — the case where cron **3a** created the ODP SalesOrder header, the follow-up item | worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, worker/schedules/cron.worker.sync.json |
 | [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/4_transmit_office_depot_po_acknowledgements.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, worker/schedules/cron.worker.sync.json, library/app/client/compass.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/features/persona-model-and-levy-gating.md

@@ -6,7 +6,7 @@ project: Worker
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-13
+updated: 2026-08-26
 owners: [bala]
 files:
   - worker2/Worker/Client/Compass/PeopleFile.php
@@ -15,6 +15,7 @@ related:
   - ../profile.md
   - ../workflows/persona-refactor-migration.md
   - ../workflows/persona-population-env-comparison.md
+  - ../workflows/granting-persona-bundle-access.md
   - ../../compass-canada/profile.md
 ---
 
@@ -40,16 +41,25 @@ below.
 
 | Persona | id | Meaning |
 |---|---|---|
-| Base (was "All") | **1** | Printers only, after the refactor. Every US user holds it. |
+| Base (was "All") | **1** | Printers only, after the refactor. Every US user holds it. **Still named "All" in prod** — the refactor is not live there (verified 2026-08-26). |
 | Levy | **24** | Levy-sector catalogue. |
-| Non-Levy | **resolved by name** — 38 on dev-sandbox *and* prod | Everything that is not a printer. Granted to non-Levy users only. |
+| Non-Levy | **resolved by name** — **38 on dev-sandbox only; does not exist in prod** | Everything that is not a printer. Granted to non-Levy users only. |
 | VIP | 35 | VIP add-on. |
 | CDL (MacBook / Surface) | 30 | `@compassdigital.io` + VIP users. |
 
-**Never hardcode the Non-Levy id.** `Personas.AUTO_INCREMENT` is 38 on both dev-sandbox and prod
-(max existing id 37), so the migration's `number = '40'` yields **id 38**, not 40. The original
-plan and the (now closed) worker2 PR both hardcoded **40** and would have written to the wrong
-persona. `PeopleFile` resolves it at runtime:
+**Never hardcode the Non-Levy id.** On dev-sandbox `Personas.AUTO_INCREMENT` was 38 (max existing id
+37), so the migration's `number = '40'` yielded **id 38**, not 40. The original plan and the (now
+closed) worker2 PR both hardcoded **40** and would have written to the wrong persona.
+
+> **⚠ Correction (verified read-only against prod, 2026-08-26): "id 38" was never a prod fact, and is
+> now definitively wrong there.** Prod has **no Non-Levy persona**, and `Personas.id` **38** is
+> **"MyDining- KDS"** — prod's auto-increment moved past 38 after 2026-08-06. Persona **number 40** is
+> taken by that same row. Whenever the migration does run in prod the persona will land on some higher
+> id, which is precisely what name-resolution protects against. Current prod number map and the
+> knock-on effect on the migration's Phase 1:
+> [Persona Refactor](../workflows/persona-refactor-migration.md).
+
+`PeopleFile` resolves it at runtime:
 
 ```php
 const PERSONA_NAME_US_NON_LEVY = 'Non-Levy';
@@ -128,6 +138,14 @@ VIP (35) and CDL (30) handling is orthogonal and applies to both tenants unchang
   constants from this file into tickets, docs, or chat transcripts.
 
 ## Change history
+- 2026-08-26 — **Correction from a read-only prod check.** The "Non-Levy = id **38** on dev-sandbox
+  *and* prod" claim is wrong: prod has **no Non-Levy persona** and id 38 is **"MyDining- KDS"**, so
+  prod's auto-increment is past 38 and persona 1 is still named **"All"**. Reinforces resolve-by-name.
+  Also linked the new [bundle-grant workflow](../workflows/granting-persona-bundle-access.md), which
+  covers the *other* half of the persona model this doc does not: what a persona grant physically
+  consists of (`Personas_Bundles` + **`Personas_Items`** + `Personas_Assortments`) and that the
+  effective persona set is a UNION of the user's own personas, their location's, and their sector's.
+  (bala)
 - 2026-08-13 — Split the `Users` row lifecycle out of this doc into
   [PEOPLE-file User Lifecycle](./people-file-user-lifecycle.md) (duplicate accounts from the 5-day
   lookup window; raw-SQL deactivation that fires no model hook). This doc stays scoped to persona /

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

@@ -18,7 +18,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-08-25
+updated: 2026-08-26
 owners: [jcardinal, bala, tcox, apeterson, dfranks]
 files: []
 related:
@@ -27,8 +27,10 @@ related:
   - features/people-file-user-lifecycle.md
   - workflows/persona-refactor-migration.md
   - workflows/persona-population-env-comparison.md
+  - 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
@@ -132,8 +134,17 @@ separate, related client (see its own profile).
   users got the full catalogue). Never trust pre-2026-08 Levy persona state as intentional.
 - [Persona Refactor — 8-phase migration & deploy order](workflows/persona-refactor-migration.md)
   (TRUE-75705) — splits persona 1 into Base (printers, everyone) + Non-Levy. **Run on dev-sandbox
-  only; production is NOT migrated.** worker2 must deploy first; Phase 8 (ACL expression 235) ships
-  with the toga2-commerce hack removal.
+  only; production is NOT migrated** (re-verified 2026-08-26: prod persona 1 is still "All", there is
+  no Non-Levy persona, and id 38 is now "MyDining- KDS"). worker2 must deploy first; Phase 8 (ACL
+  expression 235) ships with the toga2-commerce hack removal.
+- [Granting a user access to a bundle (persona grant) + SuperUser](workflows/granting-persona-bundle-access.md)
+  — the recurring "give user X sight of kit N" request. **Five tables, not one**: a bundle grant
+  without `Personas_Items` renders a **half-visible kit**, because item-level ACL hides kit lines
+  whose item the persona cannot see. Also: a Compass persona needs **no** settings rows (all nine
+  persona-settings tables are empty across all 38 prod personas), "bundle 243" is `Bundles.number`
+  not `id`, and **`Users` has no `username` column** — it is `c_hrEmpUsername`, stored lowercase.
+  Super user = `Roles.id 5` added **additively** via `Users_Roles`, never replacing Base /
+  Compass Base.
 - [Prod ↔ dev-sandbox persona comparison](workflows/persona-population-env-comparison.md) — the
   full-population diff technique, the **join-on-email** rule (`Users.id` means different people per
   environment), and the drift bundles (188/191/242) that mimic a catalogue grant.
@@ -153,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/compass-usa/workflows/granting-persona-bundle-access.md

@@ -0,0 +1,163 @@
+---
+title: Granting a Compass user access to a bundle (persona grant) and the SuperUser role
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: compass-usa
+type: workflow
+status: active
+updated: 2026-08-26
+owners: [bala]
+files:
+  - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
+related:
+  - ../features/persona-model-and-levy-gating.md
+  - ./persona-refactor-migration.md
+  - ./persona-population-env-comparison.md
+  - ../profile.md
+  - ../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+---
+
+## Summary
+
+"Give user X sight of kit N" is a **recurring** Compass request, usually paired with "and make them a
+super user". It looks like a one-row insert into `Personas_Bundles`. It is not — a bundle grant
+without the matching **item** grant renders a **half-visible kit**, because item-level ACL hides any
+kit line whose item the persona cannot see.
+
+A complete grant touches **five tables**. `dbchanges2/Client_Compass/2026-08-26a -
+CompassCreativeStudioPersona.sql` is the working template: a 6-phase additive script that creates the
+persona "Compass Creative Studio" (number 41), grants bundle 243, its 19 items and the 6 assortments
+those items live in, assigns the persona to one user, and adds SuperUser.
+
+All facts below were verified read-only against **production `Client_Compass` on 2026-08-26**.
+
+## The five tables
+
+| Table | Grants | Composite unique key? | Optional? |
+|---|---|---|---|
+| `Personas` (`id`, `uuid`, `name`, `number`) | the persona itself | — | no |
+| `Personas_Bundles` (`personaId`, `bundleId`) | the kit appears | **yes** — re-run **errors** | no |
+| `Personas_Items` (`personaId`, `itemId`) | the kit's **lines** are visible | **no** — re-run **silently duplicates** | **no — see below** |
+| `Personas_Assortments` (`personaId`, `assortmentId`) | browsing the accessory categories | **no** — re-run **silently duplicates** | no |
+| `Users_Personas` (`userId`, `personaId`) | the user holds the persona | **yes** — re-run **errors** | no |
+
+That asymmetry is the thing to remember: the two bridges that most need a guard are exactly the two
+that will not protect themselves.
+
+### `Personas_Items` is not optional
+
+Every `BundleItems.itemId` of the bundle must also be granted to the persona. Concretely: of bundle
+243's **19** active line items, persona 1 ("All", which the user already held) covered only **2** —
+so a bundle-only grant would have shown the kit with 17 of its lines missing.
+
+### Derive the assortment set — never hardcode it
+
+An assortment qualifies when it holds one of the bundle's items **and** the persona that owns the
+bundle today already grants it. Joining it out means the new persona inherits exactly the browse
+scope the current owner has, with no list to maintain:
+
+```sql
+SELECT DISTINCT ai.assortmentId
+FROM Bundles b
+INNER JOIN BundleItems bi ON bi.bundleId = b.id AND bi.isActive = 1
+INNER JOIN AssortmentItems ai ON ai.itemId = bi.itemId
+INNER JOIN Personas_Bundles pbSource ON pbSource.bundleId = b.id AND pbSource.personaId <> @personaId
+INNER JOIN Personas_Assortments pa ON pa.assortmentId = ai.assortmentId AND pa.personaId = pbSource.personaId
+WHERE b.number = '243'
+```
+
+The `personaId <> @personaId` exclusion matters: by the time this phase runs, the **new** persona
+also owns the bundle, and without it the join would feed on itself.
+
+For bundle 243 this resolves to assortments **2** (Monitors), **4** (Computer Accessories), **6**
+(Apple Accessories), **8** (Keyboard/Keypad & Mouse), **10** (Cables) and **19** (Computers).
+**An inactive assortment in the set is normal** — 19 is `isActive = 0` and is still granted, because
+the grant mirrors the source persona rather than judging the data.
+
+## A new Compass persona needs NO settings rows
+
+Verified across **all 38** personas in prod: `PersonaAppSettings`, `PersonaGlobalSettings`,
+`PersonaPageSettings`, `PersonaRecordSettings`, `PersonaSectionSettings`,
+`PersonaRecordFieldSettings`, `PersonaTranslations`, `Personas_Currencies` and
+`Personas_VendorItems` are **all empty — 0 rows**. A Compass persona is purely **catalogue scoping**
+(bundles / items / assortments). Do not go hunting for supporting configuration; there is none.
+
+## Persona numbers in prod (2026-08-26)
+
+**38 personas.** Numbers in use: **1-23, 27-40, and 100** ("QA Full Access", id 37). **The next free
+number is 41.** `Personas.number` is a *string* column, so quote it.
+
+## "Bundle 243" is `Bundles.number`, not `Bundles.id`
+
+The business always quotes the **number**. Bundle **243** is `Bundles.id` **171** ("Compass Creative
+Studio MacBook"). Resolve it in the query (`WHERE b.number = '243'`) rather than pasting an id, and
+never assume the two match.
+
+## Finding the user
+
+**`Client_Compass.Users` has no `username` column** — the natural first query fails with
+`Unknown column 'username'`. The Compass login / personnel username lives in **`c_hrEmpUsername`**,
+and it is stored **lowercase**: people quote it uppercase ("KINGK01") but the row says `kingk01`.
+Look users up by `email` or `c_hrEmpUsername` (lowercased), which is also how the nightly PEOPLE cron
+matches them — see [PEOPLE-File User Lifecycle](../features/people-file-user-lifecycle.md).
+
+## Making someone a super user
+
+There is **no `isSuperUser` flag on `Users`** — it is a role row. `Client_Compass.Roles.id` **5**,
+name **`SuperUser`** (113 holders as of 2026-08-26), granted **additively** through
+`Users_Roles (userId, roleId)`, which is unique on the pair.
+
+**SuperUser is never a replacement for the base roles.** The established prod pattern for a Compass
+super user is **Base (1) + SuperUser (5) + Compass Base (7)**, optionally **+ Manager (8)**. Role
+permissions resolve as a **union** (see
+[ACL Permission Chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md)), so adding
+role 5 while removing 1 or 7 takes access *away*.
+
+## Verify the way the ACL actually resolves personas
+
+A user's **effective** persona set is three UNIONed sources, not just `Users_Personas`:
+
+1. `Users_Personas` — personas held directly.
+2. `Locations_Personas` for the user's own `locationId`.
+3. `Locations_Personas` on the user's **sector** — five `parentLocationId` hops up
+   (location → complex → district → region → division → sector).
+
+**Check all three before adding anything** — the user may already reach the bundle through their
+location, in which case the right answer is "no change needed". After the grant, re-run the same
+resolution and confirm the bundle number appears; the verification block at the end of the template
+file does exactly this. The same three-source resolution is what the full-population comparison
+tooling uses — see
+[Prod vs dev-sandbox persona comparison](./persona-population-env-comparison.md).
+
+## Gotchas
+
+- **⚠ Re-running the whole file creates a SECOND persona.** Phase 1's `INSERT INTO Personas` has no
+  guard, so a second run inserts another persona with the same name and number, and the child phases
+  then hang a full set of rows off it. The child phases are individually re-run safe; the **file is
+  not idempotent**. To repeat any phase, set `@personaId` to the existing persona id by hand and skip
+  Phase 1.
+- **`@personaId` is a session variable — run every phase in ONE session.** A reconnect between phases
+  leaves it `NULL`.
+- **`SELECT DISTINCT` will not dedupe a row carrying a generated uuid.** The per-row random value
+  makes every row distinct. Dedupe the id set in a derived table and generate the uuid in the outer
+  select — full explanation and the UUID4 expression in
+  [Re-runnable additive INSERTs](../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md).
+- **⚠ Do not write this SQL against the persona-refactor target state.** As of 2026-08-26 the refactor
+  has **not** shipped to prod: persona 1 is still named **"All"** (not "Base"), there is **no
+  "Non-Levy" persona**, and persona **number 40 belongs to id 38 "MyDining- KDS"**. See
+  [Persona Refactor](./persona-refactor-migration.md).
+- **Everything here is additive.** The user keeps persona 1 and their existing roles; nothing is
+  removed. A "remove access" request is a different, destructive job and needs its own review.
+
+## Change history
+- 2026-08-26 — Initial: documented the five-table bundle grant (and that **`Personas_Items` is
+  mandatory** — item-level ACL hides kit lines whose item the persona cannot see; persona 1 covered
+  only 2 of bundle 243's 19 items), the unique-key asymmetry that makes `Personas_Items` /
+  `Personas_Assortments` duplicate silently on re-run, the **derived** assortment join, and that
+  **every persona settings table in prod is empty across all 38 personas** so a new persona needs no
+  config. Added the `Bundles.number` vs `Bundles.id` trap, the missing `Users.username` column
+  (`c_hrEmpUsername`, lowercase), the SuperUser role recipe (`Roles.id 5`, additive, Base + SuperUser
+  + Compass Base), and the three-source effective-persona verification. Template file:
+  `2026-08-26a - CompassCreativeStudioPersona.sql` (written, not executed). (bala)

package/knowledge/clients/compass-usa/workflows/persona-refactor-migration.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-08-06
+updated: 2026-08-26
 owners: [bala]
 files:
   - dbchanges2/Client_Compass/2026-08-06 - PersonaRefactor.sql
@@ -16,6 +16,7 @@ files:
 related:
   - ../features/persona-model-and-levy-gating.md
   - ./persona-population-env-comparison.md
+  - ./granting-persona-bundle-access.md
   - ../profile.md
 ---
 
@@ -29,6 +30,32 @@ Levy-sector users). One SQL file, **8 phases**, plus a companion verification sc
 > (toga2-commerce #306, dbchanges2 #368, worker2 #43) were closed and the work rewritten against
 > current code and data — treat any plan or skill text predating 2026-08-06 as stale.
 
+### ⚠ Everything below Phase 1 describes a TARGET state. Prod is not in it (re-verified 2026-08-26)
+
+The phase table, the persona ids and the post-migration figures in this doc describe what prod will
+look like **after** the migration. Read read-only against production `Client_Compass` on
+**2026-08-26**, prod is still pre-migration:
+
+| Claim you might carry over | Production reality, 2026-08-26 |
+|---|---|
+| Persona 1 is named "Base" | Persona 1 is still named **"All"** |
+| A "Non-Levy" persona exists | **It does not exist in prod at all** |
+| Non-Levy will land on `Personas.id` **38** | **Id 38 is already taken** — it is **"MyDining- KDS"** |
+| Phase 1's hardcoded `number = '40'` is free | **Number 40 is in use** (by id 38). Numbers **1-23, 27-40 and 100** are taken across **38** personas; **41 is the next free number** |
+
+Two consequences before this is ever run in prod:
+
+1. **Phase 1's hardcoded `number = '40'` must be re-checked** — it would create a second persona
+   carrying a number that already belongs to "MyDining- KDS".
+2. **The "id will be 38" reasoning no longer holds in prod.** `Personas.AUTO_INCREMENT` has moved
+   past 38 since 2026-08-06, so the new persona will get some higher id. This is exactly why
+   `PeopleFile` resolves Non-Levy **by name** — see
+   [Persona Model & Levy-Sector Gating](../features/persona-model-and-levy-gating.md). Never hardcode
+   the id, and re-read prod rather than this table before running.
+
+**Any other Compass persona work must target prod-as-it-is, not this target state** — see
+[Granting a Compass user access to a bundle](./granting-persona-bundle-access.md).
+
 The persona semantics and the Levy-detection code this depends on live in
 [Persona Model & Levy-Sector Gating](../features/persona-model-and-levy-gating.md). Read that first;
 the migration is meaningless without the `isLevySector` fix.
@@ -130,6 +157,12 @@ All checks are written as **invariants** or as comparisons against a captured **
 | Fixed verification user list (HAQIKAH.AARON, KYLE.AARON) | HAQIKAH.AARON is inactive, KYLE.AARON does not exist — **find test users dynamically** |
 
 ## Change history
+- 2026-08-26 — **Correction, not new work.** Re-verified read-only against prod: the refactor is
+  **still not live**. Prod persona 1 is named **"All"** (not "Base"), there is **no Non-Levy
+  persona**, and **id 38 is now "MyDining- KDS"** — so the "Non-Levy = id 38" reasoning and Phase 1's
+  hardcoded `number = '40'` (number 40 belongs to id 38) are both stale for prod. Prod holds 38
+  personas using numbers 1-23, 27-40 and 100; next free number is 41. Added the target-state warning
+  block so nobody writes prod SQL against the post-migration table. (bala)
 - 2026-08-06 — Initial: rewritten 8-phase migration (earlier draft's Phase 5+9 collapsed into one
   Levy-excluding assignment; Phase 6 restricted to active users; Phase 7f deletes the retired persona
   by name; Phase 8 makes ACL expression 235 purely additive). Documented the B2 verification-order

package/package.json

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