toga-ai 1.0.600 → 1.0.602

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 |
+| [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, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.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/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 |
@@ -24,24 +24,24 @@
 | [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/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/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 |
 | [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.php, _underscore/Model/Rate/Subscription.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
 | [NetSuite Sales Order sync — ship-to address, phone, and PO reference sourcing](features/netsuite-salesorder-address-phone-sync.md) | `_Trait_Netsuite_SalesOrder` is the **shared** sales-order importer composed into **22 client models** (every client on the dbchanges2 `netsuite` module). | _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Model.php, dbchanges2/_modules/netsuite/2026-08-10a - AddressPhoneNumberApiRoleAcl.sql |
-| [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | `_Model_Core_Page::meta()` is the **legacy** page-meta resolver behind `GET /pages/meta?slug=<slug>` — still the live path for `toga2-supply` and other pre-Surf | _underscore/Model/Core/Page.php, _underscore/Model/Client/TableView.php |
+| [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | `_Model_Core_Page::meta()` is the **legacy** page-meta resolver behind `GET /pages/meta?slug=<slug>` — still the live path for `toga2-supply` and other pre-Surf | _underscore/Model/Core/Page.php, _underscore/Model/Client/TableView.php, toga2-supply/src/components/ui/Tables/PrimaryTable/PrimaryTable.tsx |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/Model.php, _underscore/Query.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, api2/Controller/Index.php |
 | [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona **names** in multiple languages by adding a per-language **sidecar** table `PersonaTranslations`, reusing the platform's existing metadata-driven | _underscore/Model/Client/PersonaTranslation.php, dbchanges2/Client/2026-07-22b - PersonaTranslations.sql, dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql, dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql, dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql, toga2-commerce/src/pages/Account/view/MySettingsView.tsx |
 | [Record Change Audit Log (Logs_<Client>.Record / RecordField) — reading a field's history](features/record-change-audit-log.md) | Every 2.0 client schema has a sibling **logs** schema `Logs_<Tenant>` (e.g. | _underscore/Model/Client/Logs/Record.php, _underscore/Model/Client/Logs/RecordField.php, _underscore/Model/Client/Logs/CustomRecordField.php |
-| [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
+| [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql, dbchanges2/Client_Compass/2026-08-18 - FixSA135471HeroItemHalfQuantityFulfillment.sql |
 | [_String helpers — ASCII-safe HTML entity encoding (and the parseBetween trap)](features/string-html-entity-helpers.md) | `_String` is the 2.0 framework's static string utility class. | _underscore/String.php |
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Client_Compass/2026-07-15f - SalesOrderRecordActionsRemoveDeadConfigRuleOverrides.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, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php, api2/Component/Api/V2/V2.php |
 | [Table-View Hyperlink Columns (meta → ACL → computed URL → render)](features/tableview-hyperlink-columns.md) | Any 2.0 table-view column can render its value as a clickable link instead of plain text. | _underscore/Model/Client/TableView.php, _underscore/Model/Client/TrackingNumber.php, api2/Component/Api/V2/V2.php, toga2-supply/src/api/toga.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/convertData.tsx, toga2-supply/src/components/ui/Tables/hooks/useDataTableState.tsx, dbchanges2/Client/2026-07-20 - TrackingNumberHyperlinkAndFieldPermission.sql |
 | [TogaIQ Gateway Client (_Component_Api_Togaiq) — AI generate/translate from 2.0](features/togaiq-gateway-client.md) | `_Component_Api_Togaiq` is the 2.0 framework's client for the **TogaIQ** (Talos) AI gateway. | _underscore/Component/Api/Togaiq/Togaiq.php, _underscore/ApiRequest.php |
-| [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
-| [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView |  |
+| [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Elite/2026-08-17 - FulfillmentTableViews.sql |
+| [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView | _underscore/Model/Client/ServiceRequest.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql |
 | [USPS DPV Deliverability Verdict (is this address actually insurable/shippable?)](features/usps-dpv-deliverability.md) | **USPS returning HTTP 200 with a populated address is NOT evidence that the address is deliverable.** The authoritative signal is USPS's **DPV (Delivery Point V | _underscore/Component/Library/Carriers/Usps/Usps.php, _underscore/Model/Client/Address.php, _underscore/Model/Rate/Entitlement.php |
 | [Refreshing a Local Dev Database from Beta (dev-sandbox)](workflows/local-db-refresh-from-beta.md) | How to reset a local 2.0 dev database from the **beta / dev-sandbox** environment: dump each schema (`Core`, `Client_<Id>`, `Logs_<Id>`, …) from the beta host, | api2/Config/, _underscore/Loader.php, _underscore/Model/Client/BundleTranslation.php, api2/Component/Api/V2/V2.php, toga25-supply/sync_compasscanada_schema.sql |
 | [Running a 2.0 App Locally (browser, end-to-end via api2)](workflows/running-a-2.0-app-locally.md) | The full dependency chain required to run a 2.0 client app **through the browser**, end-to-end, against a **local `api2`** (e.g. | _underscore/Environment.php, _underscore/Config.php, _underscore/Database.php, _underscore/Route.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, api2/index.php, api2/.htaccess |

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-18
 owners: ["jcardinal", "mhammontree", "tcox", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -111,7 +111,9 @@ inserted zero rows**.
 
 Use **hardcoded `Core.RecordFields` id literals** instead: those ids are explicitly seeded and
 identical in every environment (the platform's only sanctioned hardcoded ids — see
-`2.0/apps/dbchanges2/architecture.md`).
+`2.0/apps/dbchanges2/architecture.md`). **Caveat: that holds for *established* rows only - the
+next free id differs per environment (a new field took 2483 in production and 2766 in
+dev-sandbox), so a row you are creating right now may need a per-environment literal.**
 
 **Known-broken existing files (same root cause):** `Client_Rate/2026-07-23a` and
 `Client/2026-07-16c`. A clean local run is never proof either worked.
@@ -357,6 +359,10 @@ hardcoded `Core.RecordFields` id literals instead of a subselect.
       and every repo is on the **same branch** so the generated model matches the DB.
 
 ## Change history
+- 2026-08-18 - Caveated "explicitly seeded and identical in every environment": true for
+  established `Core.RecordFields` rows, but the **next free id differs per environment** (a new
+  field took 2483 in prod, 2766 in dev-sandbox), so a newly created row may need a per-environment
+  literal. Keeps this doc consistent with `2.0/apps/dbchanges2/architecture.md`. (bala)
 
 - **2026-08-10** — Added the **custom (`c_`) field THREE-part anatomy** as the counterpart of the
   standard-field recipe — physical column (missing → MySQL 1054 → 500/`EO-1` on every load),

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

@@ -6,12 +6,18 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-13
-owners: [snaredla, jcardinal]
+updated: 2026-08-18
+owners: [snaredla, jcardinal, bala]
 files:
   - _underscore/Model.php
+  - _underscore/Model/Client/SalesOrder.php
+  - _underscore/Model/Client/ServiceRequest.php
+  - _underscore/Model/Elite/SalesOrder.php
+  - dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql
 related:
   - ../architecture.md
+  - ./acl-permission-chain.md
+  - ../../api2/features/v2-api-error-codes.md
   - ./model-magic-field-access.md
   - ./model-save-parent-cascade-stored-field-deadlock.md
 ---
@@ -50,8 +56,56 @@ fallback — `_serialNumbers` the property requires `_serialNumbers()` the metho
 Options: `FIELDOPT_SQL_TYPE` (defaults to `FIELD_CHAR`) and `FIELDOPT_SQL_STORED` (default `false`,
 recalculated per query; `true` persists to a real column on save).
 
+## Exposing a calculated field to the API - a client `CustomRecordFields` row is enough
+
+**Declaring the field on the model does not make it requestable.** A client whose DB has no
+metadata row for it gets api2 **`EV-8`** - *"A field specified in your request does not exist"* -
+even though the model inherits the field and the SQL is right there.
+
+**The mechanism, and it is counter-intuitive: a calculated field can be exposed purely through a
+client-scoped `CustomRecordFields` row. No `Core.RecordFields` row is required.** Compass proves
+it - `_purchaseOrders` is `CustomRecordFields` id **77** in `Client_Compass`, alongside
+`_totalLease` (81) and `_trackingNumbers` (83), with no Core registration - and the field returns
+fine. The natural assumption ("no Core `RecordFields` row, therefore impossible for any client") is
+**wrong**; it was reached and then disproved in this session, so do not re-derive it.
+
+That is what makes rolling a calculated field out to every client cheap: the SQL already lives on
+the shared `_Model_Client_*` model, so each client needs only the metadata row plus its ACL grant.
+`_purchaseOrders` on `SalesOrders` shipped this way in
+`dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql`.
+
+**Writing that migration idempotently:**
+
+- `INSERT ... SELECT ... WHERE NOT EXISTS`. `CustomRecordFields` is UNIQUE on
+  **(`recordId`, `field`)** and `AclCustomFieldPermissions` on
+  **(`customRecordFieldId`, `roleId`)**, so the guards line up with the unique keys.
+- **Resolve roles BY NAME** (`'Base'`, `'API'`) - role ids differ per client DB.
+- The grant table is `AclCustomFieldPermissions`, **not** `AclFieldPermissions` - see the
+  standard-vs-custom table in [acl-permission-chain](./acl-permission-chain.md).
+
+**Verified by running it twice:** against `Client_True` it created 1 field + 2 ACL rows on the
+first pass and nothing on the second; against `Client_Compass` it inserted nothing at all, leaving
+id 77 and its role 1/3/4 grants untouched. Prudential gains the field across **26,280**
+`SalesOrders_PurchaseOrders` rows.
+
 ## Gotchas / known issues
 
+- **⚠ Never add a parameter TYPE to an override whose parent declares the parameter untyped - it
+  is a FATAL, and `php -l` will not catch it.** Overriding a calculated field's static method on a
+  `_Model_<Client>_*` subclass is the common case. Because PHP parameter types are
+  **contravariant**, adding a type where the parent has none *narrows* the signature and PHP
+  refuses:
+
+  ```
+  Declaration of _Model_Elite_SalesOrder::_status(string $alias)
+  must be compatible with _Model_Client_SalesOrder::_status($alias)
+  ```
+
+  Adding a **return** type is fine (return types are covariant). `php -l` only checks syntax, so
+  the file lints clean and dies at runtime on the first model construction. Verified empirically
+  2026-08-17. This is the one place the team-wide "type-hint every parameter" standard does not
+  apply: **match the parent signature exactly.**
+
 - **The leading underscore is REQUIRED — it is not a camelCase-standard violation.** The TOGA
   naming standard says database/class fields are camelCase, and a reviewer (human or agent) will
   reflexively flag `_serialNumbers` and "fix" it to `serialNumbers`. Doing so **throws**:
@@ -72,6 +126,17 @@ recalculated per query; `true` persists to a real column on save).
 
 ## Change history
 
+- 2026-08-18 - Documented **how a calculated field becomes requestable**: a client-scoped
+  `CustomRecordFields` row is sufficient and **no `Core.RecordFields` row is needed** (Compass's
+  `_purchaseOrders` = id 77, with `_totalLease` 81 / `_trackingNumbers` 83, has no Core row and
+  works); without the row api2 returns **`EV-8`**. The opposite conclusion was reached and disproved
+  this session. Added the idempotent-migration shape (`INSERT ... SELECT ... WHERE NOT EXISTS`
+  against the UNIQUE keys `(recordId, field)` and `(customRecordFieldId, roleId)`, roles resolved
+  **by name** because role ids differ per client) as shipped in
+  `dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql`, verified by double-running
+  against `Client_True` and `Client_Compass`. Also added the **override-signature fatal**: adding a
+  parameter type to an override whose parent leaves it untyped is a fatal (parameter types are
+  contravariant) that `php -l` does not catch - adding a return type is fine. (bala)
 - 2026-08-13 — Added a gotcha: a `FIELDOPT_SQL_STORED` field that aggregates the model's own
   children deadlocks under the `_Model::save()` parent cascade (correlated-subquery recompute
   X-locks the parent + S-locks its children on every child insert). Cross-linked the new

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

@@ -6,13 +6,15 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
+updated: 2026-08-18
 owners: [bala]
 files:
   - _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
@@ -97,10 +99,23 @@ fulfillment statuses — filter widened to `['_picked','_packed','_shipped']`:
 |---|---|---|
 | Base, Quad (non-SA) | Pending → Picked → Packed → Partially Fulfilled → Fulfilled | all IF stages |
 | Compass USA + Canada | Pending → Partially Fulfilled → Fulfilled | **shipped IF stage only** |
+| 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
 calculated status everywhere.
 
+**Elite is a third policy, not a variant of Compass.** `_Model_Elite_SalesOrder::_status`
+(`FIELD_SQL` override, with four private helper builders, plus `_Model_Elite_SalesOrderStatus`) walks
+a **six-status ladder**: `pendingFulfillment`, `partiallyFulfilled`, `fulfilled`, `shipped`,
+`delivered`, `canceled`. The two new statuses (`shipped`, `delivered`) were seeded into
+`Client_Elite.SalesOrderStatuses`. **Elite has no approval model at all**, so the Compass status
+logic — which is written around the MR/MA approval flow — does not apply and must not be copied
+across. The override also fixed a **`billed` → `pendingFulfillment` mislabel affecting 13 orders**.
+
+> When overriding `_status` on a client model, **match the parent's parameter signature exactly** —
+> adding a parameter type the parent leaves untyped is a fatal that `php -l` does not catch. See
+> [calculated SQL fields](./calculated-sql-fields.md).
+
 ### Inventory movement (all clients)
 
 `_qtyFulfilled` and `_qtyCommitted` sum only IF items whose stage is **shipped** — picked/packed
@@ -153,6 +168,12 @@ Fan-out (`Client/`, every client) + a Compass-Canada-specific set. Execution is
   picked/packed constant would let the literal be removed.
 
 ## Change history
+- 2026-08-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
+  (shipped, delivered). **Elite has no approval model**, so the Compass logic does not transfer.
+  The override also corrected a `billed` -> `pendingFulfillment` mislabel on 13 orders. Noted the
+  override-signature fatal to watch for when writing a client `_status`. (bala)
 - 2026-06-30 — Built the IF stage lifecycle end-to-end: NetSuite sync imports all
   picked/packed/shipped statuses and advances stages on re-sync; base + Quad order `_status`
   picked/packed/partial/fulfilled machine; Compass USA + Canada order status shipped-only;

package/knowledge/2.0/apps/_underscore/features/page-meta-context-field-settings.md

@@ -6,11 +6,12 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-11
-owners: [tcox]
+updated: 2026-08-18
+owners: [tcox, bala]
 files:
   - _underscore/Model/Core/Page.php
   - _underscore/Model/Client/TableView.php
+  - toga2-supply/src/components/ui/Tables/PrimaryTable/PrimaryTable.tsx
 related:
   - surface-resolver.md
   - ../../api2/features/tableview-field-metadata.md
@@ -57,6 +58,29 @@ nothing. The row must carry **`contextRecordFieldId` = the table-view join's
 **When nothing resolves, the header falls back to the raw `TableViewFields.slug`** — which is why
 unlabeled joined columns render as camelCase identifiers rather than as blanks.
 
+> **⚠ CORRECTION (2026-08-17) — do not add a context row unless the context genuinely resolves.**
+> The table above describes where the frontend *looks*; it does **not** mean "add a context row and
+> the header appears." `PrimaryTable.tsx` takes the **context branch whenever `contextField` is
+> set and never falls back** to the plain lookup, so a `ClientRecordFieldSettings` row carrying a
+> `contextRecordFieldId` that does not resolve in the meta leaves the header rendering as its raw
+> slug — the same symptom you were trying to fix, now with a row that can also 500 other pages
+> (see the bug below). **Elite's `service-requests` headers were fixed with
+> `contextRecordFieldId = NULL`**, not with context rows. Keep label rows plain unless the context
+> really exists; treat context rows as the exception.
+
+### Check which page slug the frontend ACTUALLY requests
+
+Because every label and ACL lookup is filtered on the page's `Core.PageRecords`, the records must
+be attached to **the page the frontend asks for** — which is not always the page you built. Elite's
+`service-requests` view is requested as **`meta?page=sales-orders-listing`** (Elite reuses that
+page), so records 99 (Tickets) and 36 (ServiceRequestTypes) had to be attached to
+`sales-orders-listing`, **not** only to the new `service-requests-listing` page. Attaching them to
+the new page alone changed nothing.
+
+**Read the Network tab first.** This was mis-diagnosed twice before the actual request URL settled
+it. A missing header is a *page-attachment* question, and only the real request identifies the
+page.
+
 ### The `Core.PageRecords` gate
 
 `Page.php` assembles `settings.fields` from an **INNER JOIN** on `Core.RecordFields` (~L652) that is
@@ -89,6 +113,19 @@ because the service-requests row exists.
 **Fix:** an `isset()` guard around `Page.php` ~L822–829 — skip any context setting whose context
 field is not present on the requested page.
 
+**Only the client path is unguarded.** `Page.php:824` reads
+`$lookupRecordFieldSlugFromRecordFieldId[$row->contextRecordFieldId]` with no guard, while the
+**Core Default path at `Page.php:696` self-heals** by inserting the missing `PageRecords` row. So
+the same shape of data is harmless on the Core side and fatal on the client side — which is why
+this reads as a client-data problem when it is really a missing guard.
+
+**Concrete blast radius (Elite, 2026-08-17):** the offending row was `recordFieldId` **58**
+(`SalesOrders._total`) with `contextRecordFieldId` **190**. Record field 58 lives on `SalesOrders`,
+which appears on **six** supply pages, so one label override intended for `service-requests` 500'd
+the **Inventory** page. Applied fix: `contextRecordFieldId = NULL`. **Before adding any context row,
+check how many pages carry the labelled field's record** — a widely-shared field makes the row a
+platform-wide hazard rather than a local tweak.
+
 **Blast radius:** any client that uses context-scoped field settings can hit this on **every page
 that shares the base field**. The failure looks unrelated to the page you are debugging, and it can
 appear long after the settings row was authored — a redeploy that tightens error handling, not a
@@ -106,6 +143,16 @@ data change, is what makes it fatal.
   customization. The guard belongs in the framework.
 
 ## Change history
+- 2026-08-18 - **Corrected the "joined columns need a context row" guidance.** `PrimaryTable.tsx`
+  takes the context branch whenever `contextField` is set and **never falls back** to the plain
+  lookup, so a context row whose context does not resolve in the meta leaves the header as its raw
+  slug anyway — Elite's `service-requests` headers were fixed with `contextRecordFieldId = NULL`,
+  not with context rows. Added the diagnostic that the records must be attached to **the page the
+  frontend actually requests** (`meta?page=sales-orders-listing` for Elite's service-requests view,
+  not the new `service-requests-listing`) — read the Network tab first. Recorded that only the
+  **client** path is unguarded (`Page.php:824`) while the **Core Default path at `Page.php:696`
+  self-heals** by inserting the missing `PageRecords` row, and the concrete blast radius: field 58
+  (`SalesOrders._total`) sits on six supply pages, so one context row 500'd Inventory. (bala)
 - 2026-08-11 — Documented what context-scoped settings are actually **for**: table-view **column
   header labels**. A base-record column resolves as `settings.fields[record][field][label-singular]`
   but a **joined** column resolves the context-nested

package/knowledge/2.0/apps/_underscore/features/recursive-item-fulfillments.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-02
+updated: 2026-08-18
 owners: [jcardinal, rgirish]
 files:
   - _underscore/Model/Client/ItemFulfillment.php
@@ -17,6 +17,7 @@ files:
   - dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql
   - dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql
   - dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql
+  - dbchanges2/Client_Compass/2026-08-18 - FixSA135471HeroItemHalfQuantityFulfillment.sql
 related:
   - ../architecture.md
   - ../../api2/architecture.md
@@ -55,8 +56,10 @@ fire those records' interceptors) no-op. A `while` loop walks UP one level at a
 1. Load downstream IF; no `salesOrderId` (transfer order) → return null (out of scope).
 2. Resolve upstream SO via the **header walk** (bridge tables); none → null (top of chain).
 3. Build desired upstream items: map each downstream IFI's SOI up via the **item walk**,
-   GROUP BY upstream SOI, sum fulfilled qty, then **scale into upstream order units** for
-   bundle decomposition (see Gotchas).
+   GROUP BY upstream SOI, sum fulfilled qty, then **scale into upstream order units** — but
+   only for genuine multi-component bundles, keyed on **distinct downstream items** (see
+   Gotchas → Bundle scaling). A single distinct downstream item (incl. accepted over-ship)
+   mirrors unscaled.
 4. Resolve-or-create the upstream IF (**eager** — header-only POST still builds the chain):
    load existing via `upstreamItemFulfillmentId` and PUT changed header fields, or POST a
    new IF with mirrored header + upstream SO then PUT the downstream IF's link.
@@ -95,9 +98,36 @@ inheritance. Verified against prod `Client_Compass` chains (≥3 levels deep).
   `…Put.sql` for POST/PUT) against that env's Core DB — the PHP won't fire on PUT otherwise.
 - **`depth: -1` always** on orchestration calls. `depth => 0` means *unlimited* FK
   traversal → OOM. Never use 0.
-- **Bundle scaling:** `upstreamQty = totalDownstreamFulfilled × upstreamOrderedQty /
-  totalDownstreamOrderedQty`, **capped at the raw sum** so the factor can only reduce
-  (roll-up), never inflate. A qty-1 bundle of 6 fully-shipped components → upstream qty 1.
+- **Bundle scaling is gated on DISTINCT DOWNSTREAM ITEMS, not downstream SOI lines
+  (corrected 2026-08-18).** A "Recipe" query, per upstream SOI, takes **one ordered-qty slot
+  per distinct downstream `itemId`** (MAX ordered qty across duplicate same-item sourcing
+  lines) and counts the downstream lines. Scaling
+  (`upstreamQty = totalDownstreamFulfilled × upstreamOrderedQty / Σ distinctDownstreamOrderedQty`,
+  **capped at the raw sum** so it can only reduce, never inflate) applies **only when
+  `distinctDownstreamItemCount > 1`** — a genuine multi-component bundle. A qty-1 bundle of 6
+  fully-shipped distinct components still → upstream qty 1 (6×1/6); 3×2/6=1 preserved. When a
+  single distinct downstream item is sourced (incl. an accepted over-shipment split across
+  several downstream SOs/SOIs), the raw fulfilled qty mirrors up **unscaled** (round() applied
+  symmetrically on this branch too).
+- **Same-item over-shipment used to mis-scale into fractions (root cause, fixed 2026-08-18).**
+  Pre-fix the denominator summed ordered qty over *distinct downstream SOI lines*. A vendor
+  (e.g. Office Depot / ODP) can create **multiple downstream SalesOrders for the SAME item off
+  ONE upstream PO line** (accepted over-ship / re-send); each duplicate is another distinct
+  downstream SOI, inflating the denominator and shrinking the factor. Compass SA135471's hero
+  SOI (item 2682, qty 1) mapped to two ODP SOIs (same item, each qty 1) via one POI, so factor
+  = 1/2 and each of two customer IFs showed **qty 0.50** ("Quantity Fulfilled" 0.5 + 0.5). Two
+  physically distinct serials had shipped — a real over-ship, not a phantom duplicate. Fix:
+  distinct-item denominator (above) mirrors the raw qty (→ 2). Data repaired by
+  `dbchanges2/Client_Compass/2026-08-18 - FixSA135471HeroItemHalfQuantityFulfillment.sql`.
+- **Mixed topology (a real bundle whose component is ALSO sourced across multiple downstream
+  lines) is logged, not silently averaged.** When the Recipe's `lineCount > distinctItemCount`,
+  the engine `error_log()`s a diagnostic instead of averaging — same log-don't-swallow rule as
+  the broken-bridge guard.
+- **Diagnosing over-ship vs. phantom duplicate:** traverse the bridge — upstream SOI →
+  `SalesOrderItems_PurchaseOrderItems` → POI → `PurchaseOrders_SalesOrders` → downstream ODP
+  SOs (`customerId=1`); compare downstream vs. upstream `itemId` (**same itemId ⇒ over-ship /
+  duplicate sourcing, NOT a bundle**); then check `ItemFulfillmentItemUnits` serials — distinct
+  serials ⇒ genuine over-shipment, identical ⇒ phantom duplicate.
 - **DELETE propagation is NOT implemented.** The engine sets `$outData = null` on DELETE so
   post-delete hooks never fire; a standalone downstream DELETE doesn't immediately remove its
   upstream mirror. A later reconciling PUT cleans up stale records via set comparison. Full
@@ -131,6 +161,19 @@ inheritance. Verified against prod `Client_Compass` chains (≥3 levels deep).
   upstream record is written at most once — idempotent). Fine for normal fulfillment sizes.
 
 ## Change history
+- 2026-08-18 — **Bundle scaling now discriminates on distinct downstream items, not SOI lines
+  (CTO-approved "Option B").** `reconcileUpstreamLevel`'s Recipe query takes one ordered-qty
+  slot per distinct downstream `itemId` and scales only when `distinctDownstreamItemCount > 1`;
+  a single distinct item (incl. accepted over-ship split across multiple downstream SOs)
+  mirrors the raw fulfilled qty unscaled. Mixed topology (recipe lineCount > distinctItemCount)
+  is `error_log`'d, not averaged. Added `(int)` casts on the method's trusted-PK SQL
+  interpolations and round() symmetry on the unscaled branch. Root-caused on Compass prod
+  SA135471: the hero item (2682, qty 1) sourced via two ODP SalesOrders off one PO line showed
+  "Quantity Fulfilled" 0.5 + 0.5 across two customer IFs (old denominator summed distinct SOI
+  lines → factor 1/2); two distinct serials confirmed a genuine over-ship. Data repaired by the
+  idempotent retro migration `dbchanges2/Client_Compass/2026-08-18 - FixSA135471HeroItemHalfQuantityFulfillment.sql`
+  (IFI 302121 / 302126 quantity 0.50 → 1.00). Deploy order: `_underscore` code first, then the
+  SQL against the Compass DB. Neither deployed at capture time. (jcardinal)
 - 2026-07-02 — Added a **broken-bridge guard** to `reconcileUpstreamLevel`: when `$desiredItems`
   is empty but the downstream IF has items (broken SOI↔POI bridge), it logs and returns null
   instead of creating an empty header-only duplicate upstream IF. Root-caused on Compass SA133377

package/knowledge/2.0/apps/_underscore/features/tracking-number-bridges.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-06
+updated: 2026-08-18
 owners: ["jcardinal", "mhammontree", "dfranks", "apeterson", "bala", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -26,6 +26,7 @@ files:
   - dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql
   - dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql
   - dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql
+  - dbchanges2/Client_Elite/2026-08-17 - FulfillmentTableViews.sql
 related:
   - recursive-item-fulfillments.md
 ---
@@ -191,9 +192,63 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
   audit found `sales-order-shipments` (join 10) referencing dead RecordField **211 in
   `Client_Nychh` too** — that view is broken platform-wide and needs a backend decision, not a
   copy.
-- **Porting the item-fulfillment TableView fix to another client is two independent decisions, not a copy-paste.** The **re-root** (Units 31 → ItemFulfillmentItems 29 + OUTER unit chain) is universally portable and fixes the "0 records" bug everywhere. The **tracking source is client-specific**: Compass writes one tracking number per item fulfillment at the **item level (318)**, so its views read 318. Other clients populate different bridge levels — verify with `SELECT COUNT(*)` per bridge before choosing. As of 2026-06-19, **record 318 is empty in `Client_Nychh` and `Client_Quad`**; their tracking lives at the **IF/shipment level (317)** (covers IFIs: NYCHH 7955/10049 ≈ 79%, Quad 4878/4967 ≈ 98%) and the **unit level (319)** (≈ 7–9% — serialized only). Copying Compass's 318 join into a client that doesn't write 318 yields a structurally-correct view with permanently blank tracking until 318 is backfilled. (NYCHH's pre-fix view pointed at the now-deleted record 41 = old IF-level/package bridge, i.e. it originally intended IF-level 317.)
+- **Porting the item-fulfillment TableView fix to another client is two independent decisions, not a copy-paste.** The **re-root** (Units 31 -> ItemFulfillmentItems 29 + OUTER unit chain) is universally portable and fixes the "0 records" bug everywhere. The **tracking source is client-specific** and must be *measured*, never inherited from Compass. (NYCHH's pre-fix view pointed at the now-deleted record 41 = old IF-level/package bridge, i.e. it originally intended IF-level 317.)
+
+- **The bridge a client actually populates - measured 2026-08-17.** This is the single most
+  reusable fact in this doc: **two sibling bridges exist and they are not interchangeable.**
+
+  | Bridge | Record | Grain | Key fields |
+  |---|---|---|---|
+  | `ItemFulfillmentItems_TrackingNumbers` | **318** | per fulfillment **item** | 2178 `itemFulfillmentItemId` / 2179 `trackingNumberId` |
+  | `ItemFulfillmentItemUnits_TrackingNumbers` | **319** | per **unit** | 2183 `itemFulfillmentItemUnitId` / 2184 `trackingNumberId` |
+
+  Row counts per client DB:
+
+  | Client | 318 (item) | 319 (unit) | Which the views should read |
+  |---|---|---|---|
+  | Compass | 4,312 | 10,144 | 318 |
+  | CompassCanada | 169 | 138 | 318 |
+  | Elite | **0** | 109 | **319** (fixed 2026-08-17) |
+  | Prudential | **0** | 380 | **319** |
+  | Quad | **0** | 633 | **319** - but its views read 318 (**live bug**, see below) |
+  | NYCHH | **0** | unit-level | **319** |
+
+  Worked example: copying Compass's **318** join into Elite yields 402 rows with **zero** tracking
+  numbers; **319** yields 500 rows with 109 populated. `SELECT COUNT(*)` both bridges in the target
+  client DB **before** choosing - the wrong choice produces a structurally-correct view with a
+  permanently blank Tracking # / Carrier column, which reads as "the data is missing" rather than
+  "the join is wrong."
+
+- **Live bug: Quad's Tracking # column is empty today.** Quad's two fulfillment views are a direct
+  copy of Compass and read **318**, but Quad has **0** rows in 318 and **633** in 319. Same visible
+  symptom as the Elite bug, different cause (Elite's was dead ids; Quad's is the wrong bridge
+  level). **Not fixed** - out of scope when found 2026-08-17. This supersedes the earlier note that
+  Quad's tracking "lives at 317 (~98%)"; the unit-level bridge is where it is now.
+
+- **The dead-id breakage spans TEN clients, not just Elite (measured 2026-08-17).**
+  `item-fulfillments-for-sales-orders` / `item-fulfillments-for-sales-order-items` still carry
+  dangling `joinRecordId` **41** and dangling `parentRecordFieldId`s **211**, **321** in: **Elite**
+  (fixed 2026-08-17), **CompassCanada, Prudential, Nychh, Aig, Growrk, Managelife, Rate, SPGlobal**
+  (which has a fourth dangling id, **1431**) and **True**. **Only Compass and Quad are clean**,
+  because those two were migrated to base record 29. The per-client fix is **not a blind copy** -
+  the re-root is portable but the bridge (318 vs 319) must be chosen from that client's own row
+  counts above. A dead record is a **fatal**, not a skipped join: `TableView::meta` line 87 does
+  `($joinRecord->model)::TABLE`, and the dead record is not filtered out first because meta's join
+  query gates on `AclRecordPermissions.recordId` - and these clients still hold a permission row
+  for record 41.
 
 ## Change history
+- 2026-08-18 - **Measured which bridge each client actually populates, and it is not what "copy
+  Compass" assumes.** Added the 318-vs-319 row-count table (Compass 4,312/10,144; CompassCanada
+  169/138; Elite 0/109; Prudential 0/380; Quad 0/633; NYCHH 0/unit-level) and the rule to
+  `COUNT(*)` both bridges before porting a fulfillment view - the wrong level yields a
+  structurally-correct view with a permanently blank Tracking # column. Fixed **Elite** onto 319
+  (`Client_Elite/2026-08-17 - FulfillmentTableViews.sql`). Recorded a **live unfixed bug in Quad**
+  (views read 318, data is in 319, so its Tracking # column is empty today), superseding the older
+  "Quad's tracking lives at 317" note. Also measured the dangling `joinRecordId` 41 /
+  `parentRecordFieldId` 211+321 breakage across **ten** clients - only Compass and Quad are clean -
+  and recorded why a dead record is fatal rather than skipped (`TableView::meta` L87
+  `($joinRecord->model)::TABLE`, not filtered because meta gates on `AclRecordPermissions`). (bala)
 - 2026-08-06 — Recorded that the per-client TableView repointing left **unmigrated clients broken**:
   `Client_Elite` still has 11 references to deleted RecordFields (211/321/932/358/1431) across 9
   views in **prod and sandbox**, so its views 500 on `table-views/meta` and then on the data query

package/knowledge/2.0/apps/_underscore/features/units-for-items-for-purchase-orders.md

@@ -6,9 +6,11 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-06
+updated: 2026-08-18
 owners: ["bala", "tcox"]
-files: []
+files:
+  - _underscore/Model/Client/ServiceRequest.php
+  - dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql
 related:
   - ./tracking-number-bridges.md
   - ../../../clients/elite/features/supply2-tableview-config-drift.md
@@ -46,6 +48,51 @@ The receipt path requires both the item-level bridge **and** an item receipt aga
 bridged purchase-order line. The fulfillment path reaches `SalesOrderItems` directly by
 `salesOrderItemId` with no purchase order or bridge involved.
 
+**3. Direct item path (`Units.itemId`):**
+```
+Items
+  -> Units                                (Units.itemId = Items.id)
+```
+
+`Units.itemId` is the **only complete** item-to-unit path. Measured on `Client_Elite`
+(2026-08-11): **229 of 229** units resolve through `Units.itemId`, versus **97 of 229** through
+item receipts. Confirmed with the team before building on it. If a view needs "every unit for this
+item", walk `Units.itemId` - not a receipt or fulfillment chain.
+
+## The `inventory_units` view (2026-08-11, all clients)
+
+The all-clients `inventory_units` table view is built on this third path: base record **31**
+(Units) with **Items as the spine** - `joinRecordId` **21**, `joinOnRecordFieldId` **105**,
+`parentRecordFieldId` **238** - then 15 OUTER joins and 13 columns
+(`dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql`). This is the
+"resolver/view change that also walks past the receipt path" that the gotcha below asks for.
+
+**Per-client custom columns cannot live in that all-clients file.** A `customRecordFieldId` names
+a *different field per client*, so client custom columns (and their
+`ClientCustomRecordFieldSettings` labels) go in the client's own `Client_<Name>/` file - e.g.
+Elite's four columns at index 14-17 (`grade`, `chargingBrick`, `chargingCable`, `wipeStatus` via
+`c_deviceStatus`).
+
+## Serial numbers for a Service Request - the bridge table is empty, use the fulfillment chain
+
+`_Model_Client_ServiceRequest::_serialNumbers` (a `FIELD_SQL` field, so every client inherits it)
+`GROUP_CONCAT`s `Units.serialNumber`. The obvious source - the **`ServiceRequests_Units` bridge -
+has 0 rows**, so a field built on it alone returns nothing. The path that actually carries the
+data is the fulfillment chain off the service request's sales orders:
+
+```
+ServiceRequests
+  -> SalesOrders             (SalesOrders.serviceRequestId = ServiceRequests.id)
+  -> SalesOrderItems
+  -> ItemFulfillmentItems    (.salesOrderItemId = SalesOrderItems.id)
+  -> ItemFulfillmentItemUnits
+  -> Units
+```
+
+Coverage on `Client_Elite`: **224 of 229** units. The shipped expression selects
+`IN (<fulfillment chain> UNION <ServiceRequests_Units>)` so the bridge still counts once it is
+populated - keep the UNION rather than choosing one side.
+
 ## Data model
 Header-level vs item-level bridges, and the level each transaction is anchored at:
 
@@ -93,7 +140,28 @@ None — uniform. The linkage structure is framework-level and identical across
   [Elite TableView config drift](../../../clients/elite/features/supply2-tableview-config-drift.md).
   Check the view config before investigating the linkage paths above.
 
+- **A join can also be broken by a `parentRecordFieldId` that belongs to a record the view never
+  joins.** Distinct from the dead-id case above: the id **exists**, it is just on the wrong record.
+  Found 2026-08-17 - a join in this view carried `parentRecordFieldId` **92**, which belongs to
+  record **289** (`SalesOrderItemPurchaseOrderItems`), a record the view does not join anywhere, and
+  it **500'd** the view. **Proven by bisection:** all 23 other joins returned 200; adding this one
+  returned 500. No fields or joins depended on it, so the fix was a targeted `DELETE`. The same row
+  is present in **Elite, Compass and Prudential**. When a view 500s and the ids all resolve, check
+  that every `parentRecordFieldId` sits on a record the view actually joins - and bisect the joins
+  rather than reading the SQL.
+
 ## Change history
+- 2026-08-18 - Added the **third linkage path, `Units.itemId`** - the only *complete* item-to-unit
+  path (Elite: 229/229 units, vs 97/229 through item receipts) - and the all-clients
+  **`inventory_units`** view built on it (base 31, Items as spine via joinRecordId 21 /
+  joinOnRecordFieldId 105 / parentRecordFieldId 238, 15 OUTER joins, 13 columns), plus the rule that
+  per-client custom columns must stay in `Client_<Name>/` because a `customRecordFieldId` means a
+  different field per client. Documented **`ServiceRequest::_serialNumbers`**: the
+  `ServiceRequests_Units` bridge has **0 rows**, so serials come from the SalesOrders ->
+  SalesOrderItems -> ItemFulfillmentItems -> ItemFulfillmentItemUnits chain (224/229 on Elite),
+  UNIONed with the bridge so it still counts later. Added a second 500 cause - a
+  `parentRecordFieldId` (92) that **exists but belongs to a record the view never joins** (289),
+  found by bisecting joins; present in Elite, Compass and Prudential. (bala)
 - 2026-08-06 — Added the gotcha that a 500 on this view is usually **stale per-client
   `TableViewJoins`** left behind by the bridge migrations (records 319 / 289), not a data-linkage
   problem; confirmed on `Client_Elite` view 17. (tcox)