toga-ai 1.0.430 → 1.0.432

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

@@ -18,6 +18,7 @@
 | [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, 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 |
+| [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 |
 | [_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 |
 | [_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 |
 | [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 |

package/knowledge/2.0/apps/_underscore/features/model-interceptor-unit-testing.md

@@ -0,0 +1,67 @@
+---
+title: "DB-free unit testing for _underscore model interceptors"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-24
+owners: ["bala"]
+files:
+  - _underscore/Test/bootstrap.php
+  - _underscore/Test/Prudential/ServiceRequestTest.php
+related:
+  - ../../../../clients/prudential/features/service-request-address-validation.md
+---
+
+## Summary
+
+`_underscore` shipped with **no** PHPUnit setup (no `composer.json`/`phpunit`; only vendored
+PhpOffice tests existed). This is the first test scaffold in the repo and establishes a runnable,
+**DB-free** pattern for exercising the pure-validation logic inside a model's `prePost` /
+interceptor methods without a database or the full framework bootstrap. It was introduced with the
+Prudential `validateCustomer()` guard (see the service-request address-validation client-feature).
+
+## Key files / entry points
+
+- `_underscore/Test/bootstrap.php` — the test bootstrap. It **stubs `_Model_Client_ServiceRequest`**
+  (the DB-backed base class) and then `require`s the real `Exception/Validation.php` and the real
+  model under test, so the guard code runs unchanged with **no DB connection**.
+- `_underscore/Test/Prudential/ServiceRequestTest.php` — 6 regression tests for the private
+  `validateCustomer()` guard.
+
+## How it works
+
+1. The bootstrap defines a minimal stub for the model's DB-backed parent
+   (`_Model_Client_ServiceRequest`) so the class under test can be loaded without the ORM/DB layer.
+2. It `require`s the **real** `_Exception_Validation` and the **real** model file, so the actual
+   production validation code executes — only its persistence base is stubbed.
+3. Private validators (e.g. `validateCustomer()`) are invoked through **PHP reflection**, letting a
+   test assert on a single private method's behaviour directly instead of driving a full POST.
+4. Run it with:
+
+   ```
+   phpunit --bootstrap _underscore/Test/bootstrap.php _underscore/Test
+   ```
+
+The initial suite covers the `validateCustomer()` guard: absent `customer`, null `uuid`,
+empty-string `uuid`, whitespace-only `uuid`, error-message content, and a valid `uuid` passing.
+Verified 6/6 passing against the real code.
+
+## Gotchas / known issues
+
+- **Reflection on private methods is the pattern here** — the interceptor validators are private,
+  so tests use `ReflectionMethod::setAccessible(true)`. Keep testing them directly rather than
+  making them public just to test them.
+- **Stub only the persistence base, load the real logic.** The value of the pattern is that the
+  production validator runs unchanged; do not reimplement the validator in the stub.
+- There is still no `composer.json`/autoloader for the repo — tests rely on the explicit
+  `--bootstrap` file to wire up requires. Adding more model tests means extending
+  `Test/bootstrap.php` with the stubs that model needs.
+
+## Change history
+- 2026-07-24 — Created: first PHPUnit scaffold in `_underscore` (`Test/bootstrap.php` +
+  `Test/Prudential/ServiceRequestTest.php`), a DB-free pattern that stubs the model's persistence
+  base and reflects into private interceptor validators; seeded with 6 regression tests for the
+  Prudential `validateCustomer()` guard. (bala)

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

@@ -7,6 +7,7 @@
 | [Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)](features/encrypted-user-uuid-auth-handoff.md) | `POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**: given an encrypted `{client, user}` UUID pair, it mints a fr | api2/Component/Api/CrossClient/CrossClient.php |
 | [Health-check endpoint (/health liveness short-circuit)](features/health-check-endpoint.md) | `_Controller_Index::api()` short-circuits **liveness/health-probe** requests to an HTTP 200 **before** any routing, DB bootstrap, or V2 engine work runs. | api2/Controller/Index.php |
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, plus item **feature** text — `Features.name`, `ItemCategoryFeatureGroups.name`, `ItemFeatures | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql |
+| [Nested FK object embedding is gated by the CHILD record's own ACL](features/nested-fk-acl-embedding.md) | When the V2 JSON engine serializes a foreign-key field into a **nested object** (in `getFullModelData()`, ~V2.php L6016-6060), it re-checks the **child** record | api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql |
 | [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php |
 | [Record Scripts (computed/aggregate /v2 endpoints — the authoring contract)](features/record-scripts.md) | In api2 you almost never write a controller. | api2/Component/Api/V2/V2.php, _underscore/Model/Team/Sprint.php |
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |

package/knowledge/2.0/apps/api2/features/nested-fk-acl-embedding.md

@@ -0,0 +1,79 @@
+---
+title: Nested FK object embedding is gated by the CHILD record's own ACL
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-23
+owners: [apeterson]
+files:
+  - api2/Component/Api/V2/V2.php
+  - dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql
+related:
+  - cross-client-data-retrieval.md
+  - tableview-apiwhereclause-row-filtering.md
+---
+
+## What it is
+
+When the V2 JSON engine serializes a foreign-key field into a **nested object** (in
+`getFullModelData()`, ~V2.php L6016-6060), it re-checks the **child** record's own
+`AclRecordPermissions` against the caller's roles before embedding it. If no grant exists, the
+engine records a debug `"No ACL Record Permissions records exist"` and **silently drops the nested
+object** — still HTTP 200, `isSuccess: true`, no error or warning `message`. This is why a linked
+object can silently disappear from an API payload for one client but embed fine for another.
+
+## How it works
+
+- The gate needs only an `AclRecordPermissions` **row** for the child record on one of the caller's
+  roles. Unlike a direct top-level GET of that record, the embedding path does **not** call
+  `buildSqlExpression` — an ACL row alone (no logic-group expression) is sufficient to embed.
+- Which roles are checked depends on the child `Records.aclDatabase`. A **CLIENT**-acl record checks
+  only the caller's **client** roles; a CORE-acl record checks CORE roles (mirrors the dispatch/record
+  rules in [surface-meta-option](surface-meta-option.md)).
+- The drop is **silent by design**: absence of a grant is treated as "not authorized to see this
+  linked object", collapsed to omission rather than an error. There is no `messages[]` entry, so the
+  symptom presents purely as a missing key in `data`.
+
+## The role-3-vs-role-1 mis-seed pattern (the durable gotcha)
+
+The most common cause of a silently-missing nested object is an ACL **mis-seed on the wrong role**:
+a child record granted to a service role no human carries (e.g. role **3 "API"**) instead of the
+base role every user carries (role **1 "Base"**). Because a CLIENT-acl record checks only the
+caller's client roles, a human user authenticated with role 1 gets no grant → the child is dropped;
+a machine/API caller on role 3 sees it fine.
+
+- **Confirmed instances:** the sales-order↔purchase-order join. On **Compass** the `purchase-orders`
+  record (Core Record 17, `_Model_Client_PurchaseOrder`, `aclDatabase=CLIENT`) was granted in
+  `Client_Compass` only to role 3, so the nested `purchaseOrder` dropped from the
+  sales-order-purchase-orders join response; **Quad** had it on role 1 (perm + logic group → `all`
+  expression) and embedded fine. The **same** mis-seed was previously found on **CompassCanada**
+  (record 275). It is **not** a single-client quirk — audit every client when a nested object is
+  reported missing for some tenants only.
+- **The fix mirrors the working tenant:** add a role-1 `AclRecordPermissions` (full CRUD,
+  app-agnostic) + `AclLogicGroups` (AND) + `AclLogicGroupExpressions` reusing the existing `all`
+  record expression on the child record. Field-read perms on role 1 usually already exist (no
+  `AclFieldPermissions` insert needed). Author it **id-agnostically** (natural keys, not hardcoded
+  ids), `NOT EXISTS`-guarded, wrapping any self-referencing subquery in a derived table to avoid MySQL
+  error 1093. See `dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql`.
+
+## Diagnostic tell
+
+A top-level GET of the child record **works** but the **nested embed of the same record under a
+parent is missing**, with a 200/`isSuccess:true` response and no `messages[]`. Chase the child
+record's `AclRecordPermissions` for the caller's role — not the parent's grant, and not field
+permissions.
+
+## Change history
+- 2026-07-23 — Documented that V2 nested-FK embedding (`getFullModelData`) re-checks the CHILD
+  record's own `AclRecordPermissions` and SILENTLY drops the nested object (200, isSuccess true, no
+  message) when no grant exists — needing only an ACL row, not a logic-group expression. Fixed the
+  Compass sales-order↔PO join: `purchase-orders` (record 17, CLIENT-acl) was granted only to role 3
+  ("API") not role 1 ("Base"), so humans lost the nested `purchaseOrder` while Quad (role-1 grant)
+  embedded fine; mirrored Quad's role-1 grant (`Client_Compass/2026-07-23b`). Confirmed this is the
+  SAME role-3-vs-role-1 mis-seed pattern already seen on CompassCanada (record 275) — not
+  CompassCanada-only. (apeterson)
+</content>
+</invoke>

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

@@ -3,5 +3,5 @@
 | 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/ |
-| [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/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 |
+| [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/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 |
 | [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/ |

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

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
+updated: 2026-07-23
 owners: [jcardinal, apeterson]
 files:
   - dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql
@@ -65,6 +65,7 @@ files:
   - 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
 related:
   - ../../_underscore/features/surface-resolver.md
 ---
@@ -499,6 +500,14 @@ rule resumes.
   override is added). **Open follow-up.**
 
 ## Change history
+- 2026-07-23 — Repointed the Order Details **"PO Number"** detail field (all clients, Core seed).
+  `Core/2026-07-23a - PoNumberDetailFieldValueKey.sql` updates the `SurfaceElements` row (uuid
+  `d45c51d8-8211-11f1-bfa7-a30f63c3a801`, label `salesOrder.field.poNumber`) `config` from
+  `{"valueKey":"_purchaseOrders","isPersonaValue":true}` to
+  `{"valueKey":"purchaseOrderDetails.purchaseOrder.number"}`. The FE DetailSection resolves a field
+  value by plain dot-path against the order object, and the real PO number lives at
+  `purchaseOrderDetails.purchaseOrder.number`; `isPersonaValue` was dropped (it applies only to
+  persona arrays, not scalars). Keyed by stable uuid. (apeterson)
 - 2026-07-21 — Seeded the **per-client decision-summary overrides** off the shared
   `sales-order-decision-summary` surface (all `2026-07-21c`, client-level — `roleId`/`personaId`/
   `languageId` NULL): **Quad** hides three summary rows (`assignedTo._name`, `c_erpEntityId`,

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

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
+updated: 2026-07-23
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
@@ -165,11 +165,37 @@ modal copy, visibility/enable) to Surface; **leave data-fetch wiring (fetch slug
 nested-table topology) in JSON/code.** Not every screen reduces to a generic `SurfaceSection` swap —
 see SalesOrders below.
 
-## SalesOrders record-modal sections — migrated via the registered-renderer seam (roster-gated)
-
-The SalesOrders detail sections are now migrated onto Surface for the **seeded roster clients only**,
-via the registered-renderer approach (not a generic `SurfaceSection` swap — `SalesOrderSummaryGrid`'s
-three bespoke renderers `detailSection`/`locationCard`/`totalsCard` are untouched).
+## Surface on/off is 100% BACKEND-driven — no FE roster (2026-07-23)
+
+**A client turns Surface on purely by backend state — never a hardcoded FE allowlist.** The
+SalesOrders record modal previously gated surface resolution on an in-code roster
+(`SALES_ORDER_SURFACE_MIGRATED_CLIENTS = ["COMPASS","COMPASSCANADA","QUAD"]`): it fetched the surface
+group only for rostered clients, and everyone else fell back to JSON. That roster was the **last FE
+gate** blocking BE-driven resolution — and it blocked NYCHH from ever receiving a corrected surface
+field even though its API returned the data. **It has been removed entirely.**
+
+- The SO modal now **ALWAYS** fetches the surface group and spreads
+  `surfaceBundleToTenantFields(surfaces)` **unconditionally** (view-model
+  `useSalesOrderRecordModalLayoutModel.tsx`; roster constant deleted from
+  `surfaceBundleToTenantFields.ts` and `helpers/index.ts`).
+- Fetch is **failure-isolated** (`retry:false`, errors → `isError`, `surfaces` defaults to `{}`), and
+  `surfaceBundleToTenantFields` returns `{}` for an empty/unauthorized bundle — so a client the backend
+  does **not** serve stays JSON-driven with no roster. Merge remains **JSON-base + Surface-wins**.
+- A client now "turns on" Surface by two backend facts only: (1) being granted the `surfaces`/`meta-group`
+  script ACL (`AclRecordScripts` — see [surface-meta-option](../../api2/features/surface-meta-option.md)),
+  **and** (2) having its surfaces seeded/overridden server-side. No FE change is ever needed to onboard a
+  client onto Surface.
+- **Audit outcome:** every other `useFetchSurfaceMeta`/`useFetchSurfaceMetaGroup` call site (item-record
+  modal, approval-decision modal, Items/VendorItems/Inventory/Login) was already BE-driven — the SO modal
+  roster was the ONLY offending gate. The `clientSlug` conditionals in `src/fieldsConfig/` (`resolveRole`,
+  `FIELDS[clientSlug]`) are the **legacy JSON fallback layer, NOT surface gating**, and are correctly left
+  in place (they serve clients the backend doesn't yet drive via Surface).
+
+## SalesOrders record-modal sections — migrated via the registered-renderer seam
+
+The SalesOrders detail sections are migrated onto Surface via the registered-renderer approach (not a
+generic `SurfaceSection` swap — `SalesOrderSummaryGrid`'s three bespoke renderers
+`detailSection`/`locationCard`/`totalsCard` are untouched).
 
 - **`surfaceBundleToTenantFields()`** (`SalesOrders/helpers/`) adapts the grouped Surface bundle into
   the existing **`TenantFields`** shape, so the existing `SalesOrderSummaryGrid` renderers and
@@ -178,8 +204,9 @@ three bespoke renderers `detailSection`/`locationCard`/`totalsCard` are untouche
   gating are **not** moved. (Registered-renderer seam: *config describes, code decides.*)
 - **Full adapter-seam data path (verified this session, no direct `<SurfaceSection>`):**
   `useFetchSurfaceMetaGroup(SALES_ORDER_SURFACE_SLUGS)` → `surfaceBundleToTenantFields(surfaces)` →
-  merged into `tenantFields` (roster clients only; `clientSlug` is the **uppercased** `getHostname()`
-  result matched against the roster) → **`buildPatchedTenantFields`** (which only overrides
+  merged into `tenantFields` (**unconditionally, for every client**; an empty/unauthorized bundle
+  adapts to `{}` so unseeded clients stay JSON-driven) → **`buildPatchedTenantFields`** (which only
+  overrides
   `recordActionFields`, so it **preserves all surface section keys**) → `SalesOrderView` →
   **`SalesOrderSummaryGrid`** (renders by `section.type` / `cardType`:
   `detailSection`/`locationCard`/`totalsCard`, where `cardType` comes from `surface.config.cardType`)
@@ -212,15 +239,14 @@ from "≥1 field visible", and bind an array-derived value via element `config`
 resolved on the FE. This is the presentation counterpart of the schema's field-driven pattern and the
 third section pattern alongside card sections (`cardType` → grid renderer) and marker toggles.
 
-- **Roster gate — `SALES_ORDER_SURFACE_MIGRATED_CLIENTS = [COMPASS, COMPASSCANADA, QUAD]`** (an
-  in-code roster in `surfaceBundleToTenantFields.ts`; the view-model
-  `useSalesOrderRecordModalLayoutModel.tsx` consults it). The view-model resolves sections from
-  Surface **only** for roster clients; every other client (incl. never-migrated
-  NYCHH/Prudential/SPGlobal) skips the fetch and stays fully JSON-driven. Merge is **JSON-base +
-  Surface-wins.** ⚠ **Why a roster, not a flag:** the Core SECTION surfaces are **shared** and seeded
-  from Compass's shape — without the gate every client would inherit Compass's base and regress. A
-  **code** roster (not an env flag) is deliberate: a client is removed from the roster only once its
-  own seeds are verified.
+- **No roster (as of 2026-07-23).** The former
+  `SALES_ORDER_SURFACE_MIGRATED_CLIENTS = [COMPASS, COMPASSCANADA, QUAD]` in-code gate was **removed**;
+  the view-model now resolves sections from Surface for every client, and an empty/unauthorized bundle
+  adapts to `{}` so unseeded clients stay JSON-driven. Merge is still **JSON-base + Surface-wins**. The
+  guardrail that used to justify the roster (shared Core SECTION surfaces seeded from Compass's shape)
+  is now enforced backend-side by the **Core-neutral-default → per-client opt-in** seeding rule (see
+  [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md)) — Core no longer ships
+  Compass's shape as a live default, so removing the roster does not regress unseeded clients.
 - **JSON cleanup:** the migrated section blocks (orderDetails/shipTo/billTo/orderSummary/
   orderRecurring + the 5 display sections) were **deleted** from the COMPASS / COMPASSCANADA / QUAD
   `orderViewFields.json` files. Data-wiring (`salesOrderDetailsConfig`/`itemFulfillmentClickRule`/
@@ -471,6 +497,19 @@ now carry it (2026-07-21):
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-07-23 — **DECISION + FIX: surface on/off per client is now 100% backend-driven — removed the FE
+  roster entirely.** Deleted `SALES_ORDER_SURFACE_MIGRATED_CLIENTS = [COMPASS,COMPASSCANADA,QUAD]` from
+  `surfaceBundleToTenantFields.ts` + `helpers/index.ts`; `useSalesOrderRecordModalLayoutModel.tsx` now
+  ALWAYS fetches the surface group and spreads `surfaceBundleToTenantFields(surfaces)` unconditionally.
+  The fetch is failure-isolated (`retry:false` → `surfaces` defaults to `{}`) and the adapter returns
+  `{}` for an empty/unauthorized bundle, so a client the BE doesn't serve stays JSON-driven with no
+  roster. A client "turns on" Surface purely via backend state: the `surfaces`/`meta-group`
+  `AclRecordScripts` grant + seeded/overridden surfaces. This unblocked NYCHH (was blocked by the roster
+  from receiving the corrected PO-number field). Swept every other `useFetchSurfaceMeta(Group)` call
+  site (item-record modal, approval-decision modal, Items/VendorItems/Inventory/Login) — all already
+  BE-driven; the SO modal roster was the only FE gate. Confirmed the `src/fieldsConfig/` `clientSlug`
+  conditionals are the legacy JSON fallback layer (not surface gating) and left them in place.
+  (apeterson)
 - 2026-07-21 — Extended `surfaceBundlesToDecisionFields.ts` to emit **`isConcatenated`** on
   decision-summary rows: new exported `DecisionSummaryConcat` type (string shorthand | descriptor
   `{valueKey, prefix?, suffix?, valueType?, layout?, label?}`, mirroring blox `BaseDetailField`); optional

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 37 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 38 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 31 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 14 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/prudential/INDEX.md

@@ -3,9 +3,9 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [Prudential: Dell ASN units PRE/POST interceptor (legacy key + flat tracking)](features/dell-asn-units-interceptor.md) | 2.0 | After the tracking-number bridge migration, the ASN unit route was renamed (`advance-shipping-notice-units` → `advance-shipping-notice-item-units`), so the inhe | _underscore/Model/Prudential/AdvanceShippingNotice.php, dbchanges2/Client_Prudential/2026-06-10 - AsnUnitsInterceptor.sql |
-| [Prudential: Dell LCH IOP transmissions (LCHRequestV2)](features/dell-lch-iop-transmissions.md) | 1.0 | Outbound order transmissions from the 1.0 worker tier to Dell's Lifecycle Hub (LCH) ITSM integration. | library/app/api/delllch.php, worker/crons/toga2/prudential/transmissions_to_dell.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_india.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_ireland.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_usa.php |
+| [Prudential: Dell LCH IOP transmissions (LCHRequestV2)](features/dell-lch-iop-transmissions.md) | 1.0 | Outbound order transmissions from the 1.0 worker tier to Dell's Lifecycle Hub (LCH) ITSM integration. | library/app/api/delllch.php, library/app/apitransaction.php, worker/crons/toga2/prudential/transmissions_to_dell_usa.php, worker/crons/toga2/prudential/transmissions_to_dell_ireland.php, worker/crons/toga2/prudential/transmissions_to_dell_india.php |
 | [Prudential: Device information import + unit→contact linking (import_device_information.php)](features/device-information-import-and-contact-linking.md) | 1.0 | Prudential's **device-sync** cron (`worker/crons/toga2/prudential/import_device_information.php`) pulls device/asset records (from ServiceNow / the Dell CMDB fe | worker/crons/toga2/prudential/import_device_information.php, worker/crons/toga2/prudential/backfill_unit_contacts.php, dbchanges2/Client_Prudential/2026-07-07 - Contact Dedup Merge.sql |
-| [Prudential: Service Request Regional Address Validation](features/service-request-address-validation.md) | 2.0 | The `prePost` interceptor on `_Model_Prudential_ServiceRequest` validates `deliverToAddress` fields differently depending on which Prudential regional customer | _underscore/Model/Prudential/ServiceRequest.php |
+| [Prudential: Service Request Regional Address Validation](features/service-request-address-validation.md) | 2.0 | The `prePost` interceptor on `_Model_Prudential_ServiceRequest` validates `deliverToAddress` fields differently depending on which Prudential regional customer | _underscore/Model/Prudential/ServiceRequest.php, _underscore/Test/Prudential/ServiceRequestTest.php |
 | [Prudential Order Shipped Email — transmit_ordershipped_updates_prudential.php](features/transmit-ordershipped-email.md) | 1.0 | Cron script that transmits "Order Shipped" updates to ServiceNow (RITM) and sends a shipped notification email to the end user. | worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php, worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php, worker/crons/toga2/prudential/transmit_rejected_cancelled_updates_prudential.php, worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/notifications/reports/prudential_exception_report.php |
 | [Prudential Financial](profile.md) | 2.0 | Prudential is a TOGA client whose device-fulfillment flow is driven by **Dell** via the Dell API (`Client_Prudential.Apis.id = 2`). |  |
 | [Prudential: Dell ASN failed POST backfill replay](workflows/dell-asn-backfill-replay.md) | 2.0 | When Dell ASN POSTs fail in bulk (e.g. |  |

package/knowledge/clients/prudential/features/dell-lch-iop-transmissions.md

@@ -6,14 +6,14 @@ project: Worker
 client: prudential
 type: client-feature
 status: active
-updated: 2026-06-30
-owners: ["rgirish"]
+updated: 2026-07-24
+owners: ["rgirish", "bala"]
 files:
   - library/app/api/delllch.php
-  - worker/crons/toga2/prudential/transmissions_to_dell.php
-  - worker/crons/toga2/prudential_beta/transmissions_to_dell_india.php
-  - worker/crons/toga2/prudential_beta/transmissions_to_dell_ireland.php
-  - worker/crons/toga2/prudential_beta/transmissions_to_dell_usa.php
+  - library/app/apitransaction.php
+  - worker/crons/toga2/prudential/transmissions_to_dell_usa.php
+  - worker/crons/toga2/prudential/transmissions_to_dell_ireland.php
+  - worker/crons/toga2/prudential/transmissions_to_dell_india.php
 related:
   - ../profile.md
   - dell-asn-units-interceptor.md
@@ -31,6 +31,68 @@ only the request route and payload schema changed.
 This is the **outbound** counterpart to the 2.0 inbound Dell ASN flow (see
 `dell-asn-units-interceptor.md`).
 
+## Which cron is live (READ THIS FIRST)
+
+The current **production** Dell transmitters are the three regional split files in
+`worker/crons/toga2/prudential/`: `transmissions_to_dell_usa.php`,
+`transmissions_to_dell_ireland.php`, `transmissions_to_dell_india.php`. They are active in
+`worker/schedules/cron.worker.sync.json`, run every 5 minutes, and are each scoped to one
+region by `Customers.uuid`. Only the split files have the pre-send `validateLCHRequestV2`
+step and Apple-device handling.
+
+- The 119 KB monolith `transmissions_to_dell.php` is **DISABLED** — do not debug or edit it.
+- `transmissions_to_dell_v1.php` is a **dead backup** — ignore it.
+- The regional files were formerly under `crons/toga2/prudential_beta/`; they have since been
+  promoted to `crons/toga2/prudential/` and are the live production crons.
+
+## Selection query (how a REQ becomes a Dell send)
+
+Each regional cron selects Dell POs that have not yet been transmitted:
+
+```
+INNER JOIN Customers ON Customers.id = ServiceRequests.customerId
+WHERE PurchaseOrders.vendorId = 1        # Dell = Vendors.id 1
+  AND PurchaseOrders.dtSubmitted IS NULL
+  AND Customers.uuid = '<region-uuid>'
+```
+
+- **Region lives on `ServiceRequests.customerId`**, resolved through the join to
+  `Client_Prudential.Customers`. Region rows: **USA = id 3, uuid
+  `b3f7a2c1-4e89-4d6a-9c3b-8f1e5d2a7b04`**; India and Ireland are separate `Customers` rows /
+  uuids. This is NOT the SalesOrder customer — the SO customer is always
+  **"Agilant - Tech Hub" (id 1, uuid `36da53f8-38d2-404f-becf-f58f33c215d3`)**.
+- A REQ is only ever transmitted, validated, or marked once it is selected here. Unit/bundle/SO/PO
+  creation happens elsewhere and does **not** send anything to Dell.
+
+## Send mechanism
+
+- `App_Api_Delllch::send` (`library/app/api/delllch.php`) POSTs to route
+  `api/v2/request/LCHRequestV2`. Prod host `https://cms-iop.us.dell.com/iopv2/`; non-prod
+  `.../iopv2np/`.
+- Auth: OAuth2 client-credentials Bearer token obtained via `auth/token` (credentials stored in
+  config, not in this doc).
+- The split files first call `validateLCHRequestV2` (route `api/v2/validate/LCHRequestV2`) before
+  the real submit.
+
+## Transaction log (where to pull any Dell send for an audit/RCA)
+
+Dell's requested transaction record (date/time, payload, response code, response body) lives in
+`Logs_Prudential.Api`:
+
+| Column | Meaning |
+| --- | --- |
+| `dtStamp` | timestamp (indexed) |
+| `direction` | `'OUT'` for our sends to Dell |
+| `method` / `hostname` / `route` | HTTP verb, `https://cms-iop.us.dell.com`, e.g. `.../request/LCHRequestV2` |
+| `requestPayload` / `responseCode` / `responsePayload` | outbound body, HTTP status, Dell response body |
+
+Reading it:
+- A row with a `requestPayload` but **NULL `responseCode`** = curl never got an answer.
+- A `/validate/` row with **no** matching `/request/` row = validated but never submitted.
+- **Do not `LIKE`-scan on `requestPayload`** — `Logs_Prudential.Api` is millions of rows and the
+  payload is not indexed, so a `requestPayload LIKE '%REQ%'` query times out. Filter by `dtStamp`
+  (indexed) + `direction` + exact `route` instead.
+
 ## How it works
 
 - **Route:** `api/v2/request/LCHRequest` → **`api/v2/request/LCHRequestV2`** in all four
@@ -101,6 +163,23 @@ This is the established pattern for all Prudential script changes.
 3. After beta passes a full order cycle (New → shipped), confirm the production script is live.
 
 ## Gotchas
+- **NULL `ServiceRequests.customerId` = order silently never reaches Dell.** The selection
+  query's `INNER JOIN Customers ON Customers.id = ServiceRequests.customerId` drops any REQ whose
+  `customerId` is NULL, so it is never selected, never validated, never POSTed — and the Dell PO's
+  `dtSubmitted` stays NULL forever (not sent, not marked, invisible). This is the sole
+  differentiator behind "Dell has no trace of the REQ though Talos says we sent it": SO/PO/unit
+  creation all succeeded, only transmission was skipped. At one investigation 79 Dell POs were
+  stuck this way, all with `customerId` NULL. The 2.0-side guard added in
+  `service-request-address-validation.md` stops NEW customer-less REQs; already-stuck ones need a
+  `customerId` backfill from ship-to country.
+- **`dtSubmitted` is stamped without inspecting the response (latent bug, not yet fixed).** Every
+  regional cron sets `PurchaseOrders.dtSubmitted = NOW()` immediately after the send without
+  checking Dell's HTTP status, and `App_ApiTransaction::execute()` (`library/app/apitransaction.php`)
+  only throws on curl transport failure / empty / non-JSON body — **not** on HTTP >= 400. So a Dell
+  4xx/5xx rejection is recorded as "sent", the PO drops out of the `dtSubmitted IS NULL` queue, and
+  is never retried — it looks sent internally while Dell never accepted it. `getAccessToken()` also
+  does not check the token-call result (silent 401 path). This is a second way an order can silently
+  fail to reach Dell; fix later by inspecting the response before stamping.
 - `requestType` is the SR type only (Refresh/Breakfix/Reclaim/Bulk) — do **not** put the event
   there. Event signalling moved to the separate required `requestEvent` field
   (Create/Update/Cancel). Conflating them is the easiest way to reproduce the old overloaded
@@ -111,6 +190,12 @@ This is the established pattern for all Prudential script changes.
   do not reintroduce them.
 
 ## Change history
+- 2026-07-24 — Documented the live-cron reality (production is the three regional split files under
+  `crons/toga2/prudential/`; monolith `transmissions_to_dell.php` disabled, `_v1` dead), the
+  selection query, region model on `ServiceRequests.customerId` (USA id 3), the `App_Api_Delllch`
+  send route/host/auth, and the `Logs_Prudential.Api` transaction-log location + safe-query rule.
+  Recorded two silent-failure gotchas: NULL `customerId` excluded by the inner join (root cause of
+  79 stuck Dell POs) and `dtSubmitted` stamped without response inspection (latent bug). (bala)
 - 2026-06-30 — Migrated all Prudential Dell transmissions (3 beta regional + production) and
   `App_Api_Delllch` from deprecated `LCHRequest` to `LCHRequestV2` per Dell's May 2025 IOP
   spec: re-shaped payload (employee/ship/return objects, renamed return-item keys), new

package/knowledge/clients/prudential/features/service-request-address-validation.md

@@ -6,13 +6,16 @@ project: _Underscore
 client: prudential
 type: client-feature
 status: active
-updated: 2026-06-16
-owners: ["rgirish"]
+updated: 2026-07-24
+owners: ["rgirish", "bala"]
 files:
   - _underscore/Model/Prudential/ServiceRequest.php
+  - _underscore/Test/Prudential/ServiceRequestTest.php
 related:
   - clients/prudential/profile.md
   - clients/prudential/features/dell-asn-units-interceptor.md
+  - clients/prudential/features/dell-lch-iop-transmissions.md
+  - ../../../2.0/apps/_underscore/features/model-interceptor-unit-testing.md
 ---
 
 ## Summary
@@ -27,12 +30,20 @@ back to USA rules.
 ## Key files / entry points
 
 - `_underscore/Model/Prudential/ServiceRequest.php` — `prePost` interceptor; private methods
-  `resolveRegion()`, `validateUsaAddress()`, `validateIndiaAddress()`, `validateIrelandAddress()`
+  `validateCustomer()`, `resolveRegion()`, `validateUsaAddress()`, `validateIndiaAddress()`,
+  `validateIrelandAddress()`
 
 ## How it works
 
 1. `prePost` fires before each POST to `/v2/service-requests` for the Prudential client.
-2. `resolveRegion()` reads `payload->customer->uuid`, escapes it, and queries
+2. **`validateCustomer()` is the first check** (before `deliverToAddress` / region resolution). It
+   rejects the create when `customer.uuid` is missing/null/blank — the test is
+   `trim($payload->customer->uuid ?? '') === ''` — by throwing `_Exception_Validation`, which
+   `Controller/Index.php` maps to **HTTP 400**. This stops customer-less / unroutable REQs at the
+   API boundary. A customer-less REQ that slips through is exactly what strands an order: with a
+   NULL `ServiceRequests.customerId` it is silently excluded from every regional Dell
+   transmission cron (see `dell-lch-iop-transmissions.md`).
+3. `resolveRegion()` reads `payload->customer->uuid`, escapes it, and queries
    `Client_Prudential.Customers` for the matching `name`. Returns `'India'`, `'Ireland'`, or
    `'USA'` (default for anything unrecognised or when uuid is null).
 3. A `match` expression dispatches to the correct validator.
@@ -82,9 +93,12 @@ with a space (e.g. `F92 FP83`). No numeric restriction.
 
 ## Gotchas / known issues
 
-- **Null UUID = USA fallback.** All requests sent before Prudential added `customer.uuid` to
-  their payload lacked the field entirely; those are treated as USA and pass through unchanged.
-  This is intentional backward compatibility.
+- **Null/blank UUID is now REJECTED (changed 2026-07-24).** Previously a missing `customer.uuid`
+  silently fell through `resolveRegion()` to the USA default — which is how customer-less,
+  unroutable REQs (NULL `ServiceRequests.customerId`) got created and then silently dropped by the
+  Dell crons. The new `validateCustomer()` guard rejects a blank uuid with a 400, so region
+  fallback to USA now only ever applies to a uuid that is *present but unrecognised*. Already-stuck
+  REQs created before this guard still need a `customerId` backfill from ship-to country.
 - **Region check is by `Customers.name` string, not by id.** If the customer name is ever
   changed in the DB (e.g. `'USA'` → `'United States'`), the validator will silently fall
   back to USA rules for all regions. The match arms are `'India'` and `'Ireland'` only;
@@ -97,5 +111,10 @@ with a space (e.g. `F92 FP83`). No numeric restriction.
   their Dell spec). If Dell starts sending it for USA/Ireland it is silently ignored.
 
 ## Change history
+- 2026-07-24 — Added `validateCustomer()` as the first check in `prePost`: rejects a create when
+  `customer.uuid` is missing/null/blank (`trim(... ?? '') === ''`) via `_Exception_Validation`
+  (→ HTTP 400), stopping customer-less/unroutable REQs at the boundary. Previously a blank uuid
+  silently defaulted to USA, producing NULL-`customerId` REQs that the Dell transmission crons
+  drop. Backed by 6 regression tests in `_underscore/Test/Prudential/ServiceRequestTest.php`. (bala)
 - 2026-06-16 — Created: regional address validation (USA/India/Ireland) replacing the single
   USA-only `validateDeliverToAddress` method; region resolved from `customer.uuid` lookup (rgirish)

package/package.json

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