toga-ai 1.0.399 → 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/assortment-name-translation.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-26
+updated: 2026-07-21
 owners: ["bala"]
 files:
   - _underscore/Model/Client/AssortmentTranslation.php
@@ -25,9 +25,15 @@ Serves Assortment (product-grouping) **names** in multiple languages by adding a
 English stays in `Assortments.name`; the sidecar holds only non-English overlays. Because the
 translation layer is fully metadata-driven (see
 [Language Translation Layer](../../api2/features/language-translation-layer.md)), wiring this up
-required **no api2 code change** — only a new table, model, Core record registration, ACL grant,
-and a single field link. Compass Canada's French (fr-CA) assortment names are seeded as the first
-consumer.
+required only a new table, model, Core record registration, ACL grant, and a single field link.
+Compass Canada's French (fr-CA) assortment names are seeded as the first consumer.
+
+> **Correction (2026-07-21):** the original "no api2 code change needed" claim was only true for the
+> **FK/top-level** read paths. Assortment names are surfaced on the storefront **category browse** via a
+> `join=` request (`Assortments.name`), and the joined-select-fields read path did **not** consult the
+> sidecar — it copied the raw SQL column straight into the response, so the seeded French names stayed
+> English there. That required a real api2 change (the 5th serialization site) — see the
+> [Language Translation Layer](../../api2/features/language-translation-layer.md) 2026-07-21 change history.
 
 ## Key files / entry points
 
@@ -51,8 +57,10 @@ The mechanism itself is the data-driven translation layer documented in
 4. **The field link (what makes it translate automatically).** The translatable `Assortments.name`
    RecordField gets its `Core.RecordFields.translationRecordFieldId` set to the sidecar's `name`
    RecordField. The api2 V2 layer reads `translationRecordFieldId` for every field and automatically
-   returns the sidecar value for the caller's resolved language (falling back to English when absent) —
-   so assortment names now translate **without any api2 code change**.
+   returns the sidecar value for the caller's resolved language (falling back to English when absent).
+   This works with no api2 code change for FK/top-level reads; the storefront's `join=` (joined-select)
+   read path additionally required the 5th-serialization-site fix landed 2026-07-21 (see the correction
+   note above and the Language Translation Layer doc).
 5. **ACL.** A full ACL chain grants the **Base** role read/write on the new record. Because the
    record's `aclDatabase = 'CLIENT'`, the grant lives in each client DB — see
    [ACL Permission Chain](./acl-permission-chain.md).
@@ -75,6 +83,11 @@ The mechanism itself is the data-driven translation layer documented in
 
 ## Change history
 
+- 2026-07-21 — Correction: the "no api2 code change needed" claim held only for FK/top-level reads. The
+  storefront category browse surfaces `Assortments.name` via a `join=` request, and the joined-select read
+  path in api2 did not consult the sidecar (raw column copied through), so seeded fr-CA names stayed English
+  there. Fixed by the 5th-serialization-site change in the Language Translation Layer (V2.php); no change to
+  this sidecar/model/metadata was required. (bala)
 - 2026-06-26 — Initial build: `AssortmentTranslations` sidecar table + `_Model_Client_AssortmentTranslation`
   model + `Core.Records` 332 registration + `translationRecordFieldId` link on `Assortments.name` + Base-role
   ACL chain. Reuses the existing metadata-driven translation layer, so no api2 code change was needed.

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/api2/features/language-translation-layer.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-14
+updated: 2026-07-21
 owners: ["jcardinal", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -110,8 +110,11 @@ RecordField. `buildLookups`/RecordFields-load resolves this into
 `lookupTranslatableFieldByRecordFieldId[sourceRecordFieldId] => {sidecarRecordId, sidecarField}`.
 
 **Read path (PHP `_Model::load()`, NOT a SQL JOIN — deliberate choice).** At every response
-serialization site (top-level full-model, custom-fields, FK child, both inherent-child paths)
-`getTranslatedFieldValue($record, $field, $sourceModel, $defaultValue)` is called. When a non-base
+serialization site `getTranslatedFieldValue($record, $field, $sourceModel, $defaultValue)` is called.
+There are now **five** serialization sites, all of which must route through the helper: (1) top-level
+full-model fields, (2) custom-field options, (3) foreign-key child objects, (4) inherent-child arrays
+(both the specific-fields and the all-fields/expand-everything branches), and (5) **joined-select
+fields** (fields requested from a `join=` table, e.g. `Assortments.name`). When a non-base
 language is active and the field is translatable, it loads the sidecar row for that source row +
 `languageId` (cached per row so multiple fields = one load) and returns the sidecar value if non-null;
 otherwise it returns the English default and queues a fallback warning. The warning now carries the
@@ -119,6 +122,21 @@ missing record's `uuid` in its `identifiers` and dedupes per-field-**and**-per-r
 (key `recordFieldId:uuid`) rather than once-per-field — so every record lacking a translation for a
 field is reported individually.
 
+**Joined-select fields (site 5) — how the source row is reached.** A `join=` field's value arrives as
+a flat SQL column (`$row->{Alias_field}`), so the helper needs the joined row's identity to load its
+sidecar. In the LIST/GET branch of `processRoutePairs` (joined-select SQL build ~L3700-3800,
+serialization ~L4038-4060): when `shouldTranslate()` is true and a selected joined field is translatable
+(`lookupRecordFieldByRecordIdAndField` + `lookupTranslatableFieldByRecordFieldId`), the SQL build also
+SELECTs that joined table's primary key (`` `Alias`.`id` AS `Alias_id` ``), tracked in
+`$joinedTableRecordsByAlias` and `$joinedTablePrimaryKeyAliasByAlias`; the hidden PK column is only
+appended when not already requested (`in_array` guard). At serialization the joined source model is
+instantiated by that PK (`new $joinedSourceModelName((int)$row->$alias)`) and each joined value routes
+through `getTranslatedFieldValue()`. English and API-credential/public traffic is byte-identical (all
+new logic gated behind `shouldTranslate()`, which is false for en / API / public — no extra SQL column,
+no extra model load, output unchanged). This is why a metadata-only sidecar (e.g. `AssortmentTranslations`)
+still needed an api2 code change to translate on the `join=` read path even though FK/top-level reads
+worked with no code change.
+
 **Write path.** On create and update, `extractTranslationWrites()` pulls translatable fields out of
 the write set for a non-base language (so the English source is never overwritten), and after the
 source row saves, `saveTranslationWrites()` upserts them into the sidecar for the current language.
@@ -191,6 +209,25 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
   (matching `ItemTranslations`) while the source fields are `utf8mb4_0900_ai_ci`. Ad-hoc queries that
   compare a sidecar string against a source string must add `COLLATE utf8mb4_bin` or MySQL throws a
   collation-mismatch error.
+- **GROUP BY gotcha on translatable joined fields (site 5).** The sibling joined-field code pushes each
+  selected joined field into `$groupBy` under aggregates; the hidden PK column added for translation must
+  **also** be pushed to `$groupBy` when `!empty($aggregateFunctionFields)`, or a non-English list request
+  combining a translatable `join=` with an aggregate/`group=` throws MySQL 1055 under `ONLY_FULL_GROUP_BY`.
+  Mirror the sibling `$groupBy[]` push for the PK column.
+- **DISTINCT granularity (site 5).** The list path always runs `SELECT DISTINCT`, so adding the hidden PK
+  to the SELECT can in theory change DISTINCT granularity. Only reachable with distinct + join + a
+  translatable joined field whose rows share values but differ by PK; verified harmless for the real
+  storefront query (a `WHERE` pinning one assortment yields the same 4 rows). Worth checking if a
+  translatable join is added to a query that relies on DISTINCT collapsing duplicate rows.
+- **Per-row cost on translatable-join lists (site 5).** `getTranslatedFieldValue` dereferences the source
+  model key via `_Model __get`, forcing a full row load, so ~2 queries per row (source + sidecar) for
+  non-English translatable-join lists — consistent with the feature's per-row-load tradeoff. Candidate
+  future optimization: let the helper accept a known id instead of a live `_Model`.
+- **Pre-existing (not introduced by site 5): `join=`/`ojoin=` identifiers are unvalidated.** Table/alias/
+  ON-clause identifiers flow from the query string into SQL with no validation/escaping (`V2.php` ~L3416-3463,
+  `parseOptionsJoin` ~L7874-7920). The new PK-select line reuses the same already-tainted `$tableAlias` as the
+  adjacent pre-existing lines, so it adds no new injection class — but the underlying tainted-identifier path
+  is a standing concern flagged for separate follow-up.
 - Reading a possibly-absent magic field off a generic `_Model` needs `array_key_exists(...)` +
   `__get` — `isset()`/`?? null` always read false/null. See
   [_Model magic-field access](../../_underscore/features/model-magic-field-access.md); this was the
@@ -202,6 +239,20 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
 
 ## Change history
 
+- 2026-07-21 — Wired translation into the **joined-select-fields** path (the 5th and final read-path
+  serialization site) in `V2.php` `processRoutePairs` (joined-select SQL build ~L3700-3800, serialization
+  ~L4038-4060). `join=` fields (e.g. `Assortments.name`) previously copied the raw SQL column straight into
+  the response and never consulted the sidecar, so Compass Canada's already-seeded French assortment/category
+  names stayed English on the storefront category browse. Fix (gated behind `shouldTranslate()`, so en/API/
+  public output is byte-identical): SELECT the joined table's PK as a hidden `` `Alias`.`id` AS `Alias_id` ``
+  (tracked in `$joinedTableRecordsByAlias`/`$joinedTablePrimaryKeyAliasByAlias`, `in_array`-guarded), then at
+  serialization instantiate the joined source model by that PK and route the value through
+  `getTranslatedFieldValue()`. Also fixed a GROUP BY 1055 bug (the hidden PK must be pushed to `$groupBy` when
+  aggregates are present). Noted the DISTINCT-granularity edge, the ~2-queries-per-row cost, and that the
+  pre-existing unvalidated `join=` identifier path is unchanged (no new injection class). No toga2-commerce or
+  DB/metadata change needed — sidecar rows, the `Assortments.name` `translationRecordFieldId` link, and the
+  fr-CA storefront request all already existed. cso: SAFE TO SHIP; php-reviewer: safe after the GROUP BY fix
+  (applied), remaining items non-blocking follow-ups. (bala)
 - 2026-07-13 — Extended the translation layer to item **feature** text: three new sidecar tables
   (`FeatureTranslations`, `ItemCategoryFeatureGroupTranslations`, `ItemFeatureTranslations`; Records
   343/344/345, RecordFields 2442–2457) with `translationRecordFieldId` wired to the source fields,

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.399",
+  "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",