toga-ai 1.0.400 → 1.0.401

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

@@ -23,7 +23,7 @@
 | [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 |
 | [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/ApiRequest.php, _underscore/Model/Client/Logs/Api.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 |
-| [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 |
+| [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 |
 | [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 |  |

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-20
+updated: 2026-07-21
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Core/Surface.php
@@ -36,6 +36,7 @@ files:
   - _underscore/Model/Client/MessageTranslation.php
   - _underscore/Model/Client/ThemeToken.php
   - _underscore/Model/Core/Page.php
+  - api2/Component/Api/V2/V2.php
 related:
   - ../../dbchanges2/features/surface-layer-schema.md
   - ../../api2/features/surface-meta-option.md
@@ -253,22 +254,34 @@ rule would hit. **Scope:** the Approve element on **surface 8** (`sales-order-re
 and **surface 3** (`sales-order-listing-row-actions`, el 29). The approval-workflow-modal Approve
 element does not exist yet and is **deferred**.
 
-> ⚠ **Not resolvable server-side today.** The rule carries a `{"type":"stepTwoAssigned"}` named node,
-> which the backend Tier-2 path cannot resolve (see the Tier-2 dispatch note above — no
-> `resolveSurfaceActionState`, no backend `stepTwoAssigned`) **and** the frozen Tier-1 FE evaluator
-> `evaluateSurfaceRule` **throws** on `{type}` nodes by design. Only the **legacy** FE engine
-> (`evaluateEnableRule`) can evaluate it today; enabling the surface path needs both (a) teaching
-> `evaluateSurfaceRule` the named check and (b) feeding it live approval-stage data. See
+> ⚠ **Resolved on the FE, not server-side (Option B, 2026-07-21).** The rule carries a
+> `{"type":"stepTwoAssigned"}` named node, which the backend Tier-2 path cannot resolve (no
+> `resolveSurfaceActionState`, no backend `stepTwoAssigned`). Rather than build the Tier-2 capability,
+> **Option B** teaches the FE `evaluateSurfaceRule` a `SURFACE_NAMED_RULES` escape hatch
+> (`stepTwoAssigned`/`poNumberEntered`) and feeds it live approval-stage data on both consuming
+> surfaces — an **intentional deviation** from the frozen-grammar/escalate-to-Tier-2 design note. The
+> gate is now evaluated live on the FE. See
 > [surface-frontend](../../toga25-supply/features/surface-frontend.md).
   - **MANAGER**: opts into **approve + deny only** (`IS_VISIBLE=1`); rules left at the Core base
     (`pendingApproval` only, single-stage). No approvals-filter override → inherits Core `isVisible=0`
     (hidden).
-- **Quad** — Approve + Deny only, visible for **role ids 7/8/9** (`IS_VISIBLE=1`), with **no** rule
-  override (status stays at the Core base `pendingApproval`). This is deliberately **per-role**, unlike
-  Quad's usual client-wide (`roleId NULL`) pattern — per request. Approvals filter button is
+- **Quad** — Approve + Deny visible for **role ids 7/8/9** (`IS_VISIBLE=1`, deliberately per-role
+  unlike Quad's usual client-wide pattern). **New 2026-07-21:** Approve carries a client-wide
+  (`roleId NULL`) `ENABLED_RULE` = `{"type":"poNumberEntered"}` on **both** surface 8 (el 17) and
+  surface 3 (el 29) — "disable Approve until a PO is entered" (the `isPoComplete` semantic), plus a
+  `MessageTranslations` row overriding the disabled-tooltip text. Approvals filter button is
   client-wide with `CONFIG` `_status=[pendingApproval]`; the "Enter PO Details" button (element 32) is
   made client-wide visible (⚠ dual-gate — see the schema doc; the FE may also read `config.isVisible`).
 
+**Approvals-gate marker (Compass / Compass Canada, 2026-07-21).** The corrected Approve `ENABLED_RULE`
+(`(pendingInitialApproval AND stepTwoAssigned) OR pendingApproval`) was applied to both surfaces (el 17
++ el 29, ADMIN-scoped, rule JSON in `c_longValue`, `value` NULL). Because Compass's `2026-07-17a`
+already inserted an `ENABLED_RULE` for approve el 17, the migration **UPDATEs** that row then
+guarded-INSERTs el 29. This also required enabling the **approvals-gate marker** for Compass/CC
+(`Client_<X>/2026-07-21b - SalesOrderApprovalsGateEnable.sql`) — without it `approvalsEnabled=false`
+FE-side, stage data never fetches, and `stepTwoAssigned` **fails open** (silently enabling the button).
+See the fail-open gotcha in [surface-frontend](../../toga25-supply/features/surface-frontend.md).
+
 > ✅ **Regression (mostly) closed:** the two-stage rule overrides and the record-action/filter opt-ins
 > for Compass / Compass Canada that were wiped in the earlier rebuild were **re-added 2026-07-17**
 > (`Client_Compass`/`Client_CompassCanada/2026-07-17a`+`b`). These surface DB changes remain **local/
@@ -309,6 +322,22 @@ Core record grants + their logic-group expressions all evaluate `all`/`"1"`. The
 
 ## Gotchas
 
+- **Per-client surface message overrides silently never apply unless the JWT carries
+  `id.client.languageId`.** `_Model_Core_Surface::_loadMessages` overlays `Core.Messages.defaultValue`
+  with `Client_<X>.MessageTranslations` rows **only when `languageId > 0`**, and `Surface.php` resolves
+  `languageId` **solely** from the JWT `id.client.languageId` claim. But auth (`api2/V2.php`)
+  historically set only `id.language` (the string code `"en"`) and **never** `id.client.languageId`, so
+  `languageId` was always `0`, the overlay was skipped, and every per-client surface message override
+  (e.g. a client-specific disabled-tooltip) fell back to the Core default with **no error**. (There was
+  an explicit TODO at `V2.php` ~L5738.) **Fix (2026-07-21):** `/auth/login` now embeds
+  `$id->client->languageId = (int)$language->id` in **both** the configured-language and default-`en`
+  branches (English gets a real `languageId` too; the overlay keys on `languageId > 0` and falls back
+  to Core defaults where a client has no `MessageTranslations` row). ⚠ **CAVEAT — only `/auth/login`
+  was fixed.** The refresh (`V2.php` ~L1227), oauth, api, delegator, encrypted, and public token paths
+  still don't embed `id.client.languageId`, so **after an access-token refresh (~3600s) `languageId` is
+  lost** and per-client surface messages revert until those paths are updated too. (This is a **separate
+  claim** from `id.language`, which drives the data-translation sidecar — see
+  [language-translation-layer](../../api2/features/language-translation-layer.md); do not conflate.)
 - **A `SurfaceOverrides` row with `attribute='CONFIG'` carrying a RULE value is silently DEAD —
   encode rules as `VISIBILITY_RULE`/`ENABLED_RULE`, never as `CONFIG`.** `_castOverride` routes the
   `CONFIG` attribute into `$config`, **NOT** `$visibilityRule`/`$enabledRule`; a `CONFIG` row whose
@@ -391,6 +420,18 @@ Core record grants + their logic-group expressions all evaluate `all`/`"1"`. The
   match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-07-21 — Recorded **Option B**: the Approve step-two/PO gate is now evaluated **live on the FE**
+  (FE `evaluateSurfaceRule` gained a `SURFACE_NAMED_RULES` escape hatch) rather than via the no-op
+  backend Tier-2 — an intentional deviation from the frozen-grammar/escalate note (updated the
+  "not resolvable server-side" caveat). Added the **Quad** Approve `ENABLED_RULE`
+  `{"type":"poNumberEntered"}` (client-wide, both surfaces) + disabled-tooltip `MessageTranslations`
+  override, and the **Compass/CC** approvals-gate marker enable (`2026-07-21b`) needed so
+  `stepTwoAssigned` doesn't fail open. New gotcha: per-client surface **message** overrides silently
+  never apply unless the JWT carries `id.client.languageId` (`_loadMessages` overlays
+  `MessageTranslations` only when `languageId>0`; `Surface.php` reads it solely from that claim, but
+  auth only set `id.language`) — fixed in `api2/V2.php` `/auth/login` (both language branches), with the
+  caveat that refresh/oauth/api/delegator/encrypted/public paths still lose it after a token refresh.
+  (apeterson)
 - 2026-07-20 — Clarified the **backend Tier-2 gate reality**: `_resolveTier2State` (Surface.php ~280)
   dispatches by **action slug** to `resolveSurfaceActionState()` (`TIER2_CAPABILITY_METHOD`), **not**
   by `config.tier2` — `config.tier2` is a **dead marker nothing reads** (backend or FE). The surface

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 |
+| [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 |
 | [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-20
+updated: 2026-07-21
 owners: [jcardinal, apeterson]
 files:
   - dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql
@@ -54,6 +54,12 @@ files:
   - 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
 related:
   - ../../_underscore/features/surface-resolver.md
 ---
@@ -403,6 +409,17 @@ rule resumes.
   earlier `2026-06-25c` / `2026-06-29c` / `2026-06-25d` surface seeds **likely share the same
   anti-pattern** and need auditing. Core→Core seeds are fine (same cluster). Also still open:
   re-seeding NYCHH/Prudential/SPGlobal (deferred).
+- **A `VISIBILITY_RULE`/`ENABLED_RULE` override row can exist in the DB with the CORRECT `c_longValue`
+  yet be silently ignored because its `attribute` coerced to `''`.** The `SurfaceOverrides.attribute`
+  ENUM must be widened per client (`Client/2026-07-15 - SurfaceOverridesAttributeRuleValues.sql`)
+  **before** any rule-override insert. If a client (this session: **Quad**) never ran it, MySQL
+  **non-strict mode silently coerces** the invalid `VISIBILITY_RULE`/`ENABLED_RULE` value to `''`
+  (empty string) on INSERT — the row lands with the right `c_longValue` but `attribute=''`, so the
+  resolver ignores it and the rule never ships. **Symptom:** the override row is visibly present in the
+  DB (correct `c_longValue`) but `enabledRule`/`visibilityRule` is absent or wrong in the
+  `/surfaces/meta` API response. **Fix:** run the ENUM-widening file for the client, DELETE the junk
+  `attribute=''` rows, then re-insert. (`NOT EXISTS` guards keyed on `attribute` never match the junk
+  rows, so duplicates also pile up.)
 - **Display-section visibility cannot be per-role-overridden without an element.** The override
   cascade overrides **ELEMENTS only**, never a surface's own `isVisible`. The 5 display-toggle SECTION
   surfaces therefore each carry a single `sectionVisibility` marker element so a Client override can
@@ -425,6 +442,16 @@ rule resumes.
   override is added). **Open follow-up.**
 
 ## Change history
+- 2026-07-21 — Added the sales-order **Approve enable-gate** per-client overrides (`Client_*/2026-07-21a`):
+  Compass/CC ADMIN `ENABLED_RULE` = `(pendingInitialApproval AND stepTwoAssigned) OR pendingApproval`
+  on surface 8 el 17 + surface 3 el 29 (rule JSON in `c_longValue`; Compass UPDATEs its existing
+  `07-17a` el-17 row then guarded-INSERTs el 29), plus a Compass/CC **approvals-gate enable**
+  (`2026-07-21b`) required so the FE `stepTwoAssigned` predicate doesn't fail open. Quad = client-wide
+  Approve `ENABLED_RULE` `{"type":"poNumberEntered"}` on both surfaces + a disabled-tooltip
+  `MessageTranslations` override. Sharpened the ENUM-coercion gotcha: a rule-override row can exist with
+  the correct `c_longValue` yet be silently ignored because `attribute` coerced to `''` (Quad never ran
+  the ENUM-widening file) — symptom is the row present in DB but the rule absent from the `/surfaces/meta`
+  response; fix = run the ENUM file, delete the `attribute=''` junk rows, re-insert. (apeterson)
 - 2026-07-20 — Corrected the **row-actions surface** (`sales-order-listing-row-actions`, Core id 3;
   distinct from the header-actions surface 9) default visibility and added the client opt-in.
   `Core/2026-07-20e` narrows an earlier over-broad `2026-07-20d` hide — re-enables Approve (el 29) +

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

@@ -264,40 +264,70 @@ in [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md):
 
 ## Two FE rule engines (surface Tier-1 vs legacy named-rule) — do not conflate
 
-There are **two** rule evaluators in this app, and a business predicate like the corrected Approve
-rule can only run on the legacy one today:
-
-- **`src/surface/evaluateSurfaceRule.ts`** — the **surface Tier-1** evaluator. Grammar is
-  **deliberately FROZEN**: `all`/`any`/`none` + leaf field ops (`eq`/`ne`/`in`/`nin`/`gt`/`gte`/`lt`/`lte`).
-  It **THROWS on any `{type:…}` named node by design** ("new logic does NOT go here — escalate to a
-  Tier-2 PHP capability method"). Evaluated client-side against the loaded record.
+There are **two** rule evaluators in this app. As of 2026-07-21 the surface evaluator now has a
+**sanctioned named-predicate escape hatch** (Option B — see below), so a business predicate like the
+Approve gate can finally run on the surface path FE-side:
+
+- **`src/surface/evaluateSurfaceRule.ts`** — the **surface Tier-1** evaluator. Base grammar is
+  `all`/`any`/`none` + leaf field ops (`eq`/`ne`/`in`/`nin`/`gt`/`gte`/`lt`/`lte`). It historically
+  **THREW on any `{type:…}` node** ("escalate to a Tier-2 PHP capability method"). It now instead
+  resolves `{type:<SurfaceNamedRule>}` nodes against a **`SURFACE_NAMED_RULES` map** (still throws
+  `"Unknown rule node"` on an unregistered type). `SurfaceNamedRule` (`src/surface/types.ts`) =
+  `"stepTwoAssigned" | "poNumberEntered"`. Both predicates read off the `{order}`-shaped surface
+  record: `stepTwoAssigned` reads `order.currentStage`/`order.stages`; `poNumberEntered` =
+  `!!order.purchaseOrderDetails.purchaseOrder` (mirrors the legacy `isPoComplete`). Evaluated
+  client-side against the loaded record.
 - **`src/pages/SalesOrders/helpers/evaluateEnableRule.ts`** (`evaluateRule`) — the **legacy** engine:
-  `all`/`any`/`not` + `field` + **`{type}` NAMED_RULES**, including **`stepTwoAssigned`** (which reads
-  `ctx.currentStage`/`ctx.stages`).
-
-**Consequence:** the corrected Approve enable rule
-(`(pendingInitialApproval AND stepTwoAssigned) OR pendingApproval` — see
-[surface-resolver](../../_underscore/features/surface-resolver.md)) carries a `{type:stepTwoAssigned}`
-node, so **only the legacy engine can evaluate it today**. Moving the Approve button fully onto the
-surface path requires **both** (a) teaching `evaluateSurfaceRule` the named `stepTwoAssigned` check and
-(b) feeding it live approval-stage data — neither is done. (The backend Tier-2 path is also a no-op:
-no `resolveSurfaceActionState`, no backend `stepTwoAssigned`.)
+  `all`/`any`/`not` + `field` + **`{type}` NAMED_RULES** (`stepTwoAssigned` reading
+  `ctx.currentStage`/`ctx.stages`). Still present for the JSON-driven path.
+
+### Option B — named predicates evaluated live on the FE (design deviation, intentional)
+This **intentionally deviates** from the original "frozen grammar → escalate to a Tier-2 PHP
+capability method" design note (see
+[surface-resolver](../../_underscore/features/surface-resolver.md)). Per **Option B** the Approve
+step-two / PO gate is evaluated **live on the FE**, because the backend Tier-2 path is a no-op (no
+model implements `resolveSurfaceActionState`, no backend `stepTwoAssigned`) and the rule is not in
+legacy JSON. Named predicates (`stepTwoAssigned`/`poNumberEntered`) are the sanctioned FE-side escape
+hatch for logic the frozen field grammar cannot express; the rule JSON itself lives in each client's
+`SurfaceOverride` `c_longValue` (Core stays neutral).
+
+### `resolveElementState` — the flag composition
+`resolveElementState.ts` computes an element's `isEnabled` as **`staticFlag AND enabledRule AND
+meta.surface`** (static flag AND the Tier-1/named-predicate `enabledRule` result AND any
+server-computed `meta.surface` state). ⚠ **`SurfaceActionBar` carries its own DUPLICATE copy of
+`resolveElementState`** — any change to the composition logic must be made in **both** places or the
+action bar and the generic path will diverge.
 
 ### Approval-stage data plumbing for `stepTwoAssigned`
 `stepTwoAssigned` needs the order's approval-stage data on the surface record. The surface record is
-shaped `{ order }`, so the predicate reads **`order.currentStage` / `order.stages`**.
+shaped `{ order }`, so the predicate reads **`order.currentStage` / `order.stages`**. Both surfaces
+now carry it (2026-07-21):
 
-- **Record-modal action bar (surface 8) — DONE.** `useSalesOrderRecordModalLayoutModel.tsx` already
-  fetches `approvalCurrentStage`/`approvalStages`; they are now **merged onto the order (`orderWithPo`)
-  as `currentStage`/`stages`** (parallel to the existing `purchaseOrderDetails` merge). Purely additive.
-- **Listing row dropdown (surface 3) — PENDING.** `src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts`
-  currently fetches `order` + `purchaseOrderDetails` but **NOT** approval stages, so `stepTwoAssigned`
-  cannot resolve on the row path yet. It needs a `useFetchApprovalStages` call + the same
-  `currentStage`/`stages` merge (a per-open fetch cost tradeoff on the row path), **and**
-  `evaluateSurfaceRule` still needs the named-check support above.
+- **Record-modal action bar (surface 8) — DONE.** `useSalesOrderRecordModalLayoutModel.tsx` fetches
+  `approvalCurrentStage`/`approvalStages`, merged onto the order (`orderWithPo`) as
+  `currentStage`/`stages` (parallel to the `purchaseOrderDetails` merge). Additive.
+- **Listing row dropdown (surface 3) — DONE.** `useSalesOrderRowRecordState.ts` now calls
+  `useFetchApprovalStages` (gated on `enabled && approvalsEnabled`) and merges `currentStage`/`stages`
+  onto `record.order`, mirroring the record-modal view model. Both FE surfaces now carry
+  `order.currentStage`/`order.stages`/`order.purchaseOrderDetails`.
 
 ## Gotchas
 
+- **A named predicate that FAILS OPEN silently enables a button when its data isn't fetched.**
+  `stepTwoAssigned` returns `true` when `order.currentStage` is `null` (a fail-OPEN default). So if the
+  surface's approval-stage data is not plumbed in (e.g. `approvalsEnabled=false`, so
+  `useFetchApprovalStages` never runs, or the row-path merge is missing), the predicate resolves `true`
+  and the Approve button is **silently enabled** regardless of stage. A named predicate's default
+  branch is load-bearing — decide fail-open vs fail-closed deliberately, and confirm the data it reads
+  is actually fetched on **every** surface that uses the rule (surface 8 AND surface 3). This is why
+  the Compass/CC approvals-gate marker (`approvalsEnabled`) must be enabled per client — without it the
+  stage data never fetches and `stepTwoAssigned` fails open.
+- **Surface meta is cached `staleTime: Infinity` / `gcTime: Infinity` for the whole session
+  (`useFetchSurfaceMeta.ts`).** After ANY `SurfaceOverride` / `MessageTranslation` DB change, a **hard
+  reload / re-login is required** or the browser keeps the pre-change meta for the entire session. This
+  repeatedly presents as "I ran the SQL but nothing changed" during debugging — the SQL is fine; the
+  meta is cached. (Server-side raw-SQL surface edits ALSO need the on-disk resolver cache cleared — see
+  [surface-resolver](../../_underscore/features/surface-resolver.md); both caches must be busted.)
 - **The single-meta envelope can hide the real bundle behind a DECOY `elements: []`.** The V2 envelope
   can arrive as `{ surfaces: { meta: <real-bundle> }, elements: [] }` — a decoy empty `elements: []`
   sits at the top level with **no `surface` descriptor**. A `looksLikeBundle` check matching on
@@ -394,6 +424,20 @@ shaped `{ order }`, so the predicate reads **`order.currentStage` / `order.stage
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-07-21 — **Option B: moved the Approve enable-gate onto the surface FE path.** Added a
+  `SURFACE_NAMED_RULES` map + a `{type:SurfaceNamedRule}` branch to `evaluateSurfaceRule.ts`
+  (`SurfaceNamedRule` = `"stepTwoAssigned"|"poNumberEntered"` in `types.ts`) — the sanctioned FE-side
+  escape hatch for logic the frozen field grammar can't express, an intentional deviation from the
+  original "frozen grammar → escalate to Tier-2 PHP" note (backend Tier-2 is a no-op). `stepTwoAssigned`
+  reads `order.currentStage`/`order.stages`; `poNumberEntered` = `!!order.purchaseOrderDetails.purchaseOrder`.
+  Plumbed approval-stage data onto the **row-actions** surface (surface 3): `useSalesOrderRowRecordState.ts`
+  now calls `useFetchApprovalStages` (gated on `enabled && approvalsEnabled`) + merges `currentStage`/`stages`
+  onto `record.order` (previously PENDING; record-modal surface 8 was already done). Documented that
+  `resolveElementState` composes `isEnabled = staticFlag AND enabledRule AND meta.surface` and that
+  `SurfaceActionBar` holds a DUPLICATE copy. Gotchas added: (1) `stepTwoAssigned` FAILS OPEN when
+  `currentStage` is null → silently enables the button if stage data isn't fetched (hence the per-client
+  approvals-gate marker); (2) surface meta is `staleTime/gcTime: Infinity` so a DB override change needs a
+  hard reload/re-login ("ran the SQL but nothing changed"). (apeterson)
 - 2026-07-21 — Fixed the surface-driven **status badge dot rendering colorless** in the sales-order
   record-modal header: the resolved bundle ships vocabulary color TOKEN SLUGS
   (`color.status.*`/`bg.status.*`) but its `theme` map is empty (`{}`), so `resolveThemeToken` returns

package/package.json

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