toga-ai 1.0.370 → 1.0.371

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

@@ -21,7 +21,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, _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 |
 | [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 |  |
 | [Refreshing a Local Dev Database from Beta (dev-sandbox)](workflows/local-db-refresh-from-beta.md) | How to reset a local 2.0 dev database from the **beta / dev-sandbox** environment: dump each schema (`Core`, `Client_<Id>`, `Logs_<Id>`, …) from the beta host, | api2/Config/, _underscore/Loader.php, _underscore/Model/Client/BundleTranslation.php, api2/Component/Api/V2/V2.php, toga25-supply/sync_compasscanada_schema.sql |

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-16
+updated: 2026-07-17
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Core/Surface.php
@@ -20,6 +20,13 @@ files:
   - 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
@@ -186,16 +193,35 @@ Compass's shape. Core was re-baselined as a true shared default so clients store
 4. Edit-in-Commerce only for Compass / CompassCanada.
 5. Columns button hidden by default.
 
-Per-client diffs layered on top:
-- **Quad** — Approve + Deny only; filter narrowed to `pendingApproval`; filter button visible.
-- **Compass USA / Compass Canada** — two-stage approvals: record-action `visibilityRule`/`enabledRule`
-  = `in [pendingApproval, pendingInitialApproval]`. **Compass Canada** additionally gets a `CONFIG`
-  override on the approvals filter button (surface `sales-order-listing-actions`) to add
-  `pendingInitialApproval`.
-
-> ⚠ **Regression left open:** the Compass / CompassCanada **non-rule** overrides (Edit-in-Commerce
-> flags, role-8 Manager hides) were **wiped during the rebuilds and not re-added**. The two-stage rule
-> overrides are also LOCAL only (see above).
+### Per-client sales-order button diffs — materialized 2026-07-17
+The Core neutral default now covers the **approvals filter button too**: `Core/2026-07-17h` cleared
+element 22's `config` to `{}`, so Core carries no `_status` default and **every** client (even Quad,
+whose value matches the old default) supplies the whole filter `CONFIG` via its own override (REPLACE
+semantics). Concrete per-client diffs, all via `SurfaceOverrides` (rule JSON is
+`{"all":[{"field":"order._status","op":"in","value":[…]}]}`; seed authoring/element-id map in the
+[surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md) doc):
+
+- **Compass USA / Compass Canada** (mirror each other) — two-stage approval:
+  - **ADMIN**: opts into all four gated record-action buttons (approve/deny/approvalWorkflow/editOrder)
+    `IS_VISIBLE=1`, and widens **both** `VISIBILITY_RULE` **and** `ENABLED_RULE` to
+    `_status in [pendingApproval, pendingInitialApproval]`. (For approve, the Tier-2 `stepTwoAssigned`
+    predicate still further gates *enabled* in PHP.) On the approvals filter button: `IS_VISIBLE=1` +
+    `CONFIG` `additionalData._status = [pendingApproval, pendingInitialApproval]`.
+  - **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
+  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`).
+
+> ✅ **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/
+> beta only** pending promotion; the `_underscore` rule-override code + the ENUM widening still ship
+> together on promotion, and the php-reviewer pass + PHPUnit regression for the rule-override path are
+> still outstanding.
 
 ### Operational gotcha — raw SQL bypasses the cache-bust
 Raw SQL against the surface tables bypasses the model-layer cache-bust, so the on-disk bundle cache
@@ -312,6 +338,14 @@ 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-17 — Materialized the per-client sales-order button diffs (re-adding the overrides wiped in
+  the earlier rebuild): Compass/CompassCanada ADMIN = all four record-action buttons visible + both
+  `VISIBILITY_RULE`/`ENABLED_RULE` widened to `[pendingApproval, pendingInitialApproval]`, MANAGER =
+  approve+deny visible with Core-base rules; Quad = approve+deny visible per-role (ids 7/8/9), no rule
+  override. Extended the Core neutral default to the **approvals filter button** — `Core/2026-07-17h`
+  cleared element 22's config so every client (including Quad) now supplies the full filter `CONFIG`
+  (REPLACE semantics): Compass/CC admin = two statuses, Quad client-wide = `pendingApproval`. Overrides
+  remain local/beta only pending promotion. (apeterson)
 - 2026-07-16 — Recorded a resolver gotcha: a `SurfaceOverrides` row with `attribute='CONFIG'` carrying
   a rule value is silently dead — `_castOverride` routes CONFIG→`$config`, not
   `$visibilityRule`/`$enabledRule` (logs + returns null), and `overridesByElementAndAttr` keyed by

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 |
+| [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 |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | How to manually stand up a new 2.0 client (tenant). | 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-16
+updated: 2026-07-17
 owners: [jcardinal, apeterson]
 files:
   - dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql
@@ -31,6 +31,13 @@ files:
   - 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
 related:
   - ../../_underscore/features/surface-resolver.md
 ---
@@ -114,6 +121,52 @@ it `isVisible: true`. Both `Core/2026-06-29a` (Item) and `Core/2026-06-29d` (Ven
 off." A client opts a role in via a `SurfaceOverride` (`IS_VISIBLE=1`), scoped by role/persona. This is
 the seed-authoring corollary of the Core neutral-default re-baseline recorded in the resolver doc.
 
+## Sales-order button overrides — element identities & the id-agnostic authoring house style
+
+When a client opts its roles into the sales-order action/filter buttons (the resolved per-client
+*behavior* lives in the [surface-resolver](../../_underscore/features/surface-resolver.md)
+per-client-diffs section), the override seeds follow a strict **id-agnostic house style** so one file
+runs unchanged across local/beta/prod:
+
+- **Resolve `roleId` by `Roles.name`** (`'Admin'`/`'Manager'`) — client role ids are environment-specific.
+- **Resolve the Core element by surface slug + one discriminator**, never a hardcoded Core id:
+  `Core.Actions.slug` for action buttons; the **label `messageKey`** (`salesOrder.filter.approvals`)
+  for the approvals filter button — it has no `actionId` and, after the Core config wipe (below), no
+  `config` left to match on; or `config.valueKey` (`poNumber`) for the "Enter PO Details" button.
+- **`personaId`/`languageId` NULL** for role/client scope (language-agnostic).
+- **Every INSERT guarded by `NOT EXISTS`** on `(surfaceElementId, roleId, attribute, personaId NULL,
+  languageId NULL)` so the file is re-runnable. A per-role Quad seed does this with a
+  `CROSS JOIN (SELECT 7 UNION ALL SELECT 8 UNION ALL SELECT 9)` + a `Roles` existence join, so a
+  missing role id is skipped rather than erroring.
+- Cross-DB read of `Core.*` from the client seed mirrors the established Surface override pattern
+  (safe where Core+client are co-located; the prod cross-cluster caveat in the gotchas applies).
+
+**Which attribute for which change:** `IS_VISIBLE`/`CONFIG` are in the base attribute ENUM;
+`VISIBILITY_RULE`/`ENABLED_RULE` require the widened ENUM
+(`Client/2026-07-15 - SurfaceOverridesAttributeRuleValues.sql`) applied per-tenant first (see the
+resolver doc — an unknown ENUM value silently coerces to `''` in non-strict mode). A `CONFIG` override
+**replaces the whole object**, so a filter override must carry the full config
+(`role`+`filterKey`+`additionalData`), never just the changed key.
+
+**Sales-order surface element identities** (Core seed `2026-07-17c` assigns EXPLICIT, stable ids — but
+author overrides by slug/messageKey/valueKey, not by these numbers):
+
+| Surface (id) | Element | id | Discriminator |
+|---|---|---|---|
+| `sales-order-record-actions` (8) | approve | 17 | action `salesOrder.approve` |
+| | deny | 18 | action `salesOrder.deny` |
+| | approvalWorkflow | 19 | action `salesOrder.approvalWorkflow` |
+| | viewLog | 20 | always-visible / ungated (excluded from overrides) |
+| | editOrder | 21 | action `salesOrder.editOrder` |
+| | Enter PO Details | 32 | no `actionId`; `config.valueKey='poNumber'` |
+| `sales-order-listing-actions` (9) | approvals filter | 22 | label messageKey `salesOrder.filter.approvals` |
+| | columns | 23 | — |
+
+**Core approvals-filter default removed (`Core/2026-07-17h`).** Core element 22's `config` was cleared
+to `{}` so Core carries **no** `_status` default. Every client — even Quad, whose config matches the
+old default — now declares the full filter config via its own `CONFIG` override. This makes the Core
+seed a true neutral default for the filter button, matching the action-button rule above.
+
 ## ThemeTokens — per-tenant, physically isolated in each client DB
 
 `ThemeTokens` lives **inside each tenant's own database** (`Client_Compass.ThemeTokens`,
@@ -251,8 +304,32 @@ rule resumes.
   flip a section per role/persona. Also discovered: `elementType` in `orderViewFields.json` is **dead
   config** (no renderer reads it); and MANAGER/Quad summary tooltips can't be removed via the cascade
   because `TOOLTIP_MESSAGE` is numeric-only (cosmetic, deferred).
+- **`Client_CompassCanada` may be missing the `SurfaceOverrides` table entirely** (its beta reset
+  predates the surface rollout). Prereqs — in order — **before any CompassCanada surface override
+  runs:** `Client/2026-06-25a - SurfaceClientTables.sql` (creates `ThemeTokens`/`MessageTranslations`/
+  `SurfaceOverrides`), then `Client/2026-07-15 - SurfaceOverridesAttributeRuleValues.sql` (ENUM
+  widening for the rule attributes); and for the `/surfaces/meta` endpoint to resolve at all, the ACL
+  dispatch grants (`Client/2026-06-25c`, `2026-06-29c`, `2026-06-30a`). Skipping the table/ENUM
+  bring-up makes the `2026-07-17a/b` override inserts fail or silently coerce.
+- **"Enter PO Details" (element 32) has a DUAL visibility gate.** Its rendering is gated by BOTH the
+  element-level `isVisible` flag AND a `config`-embedded `"isVisible":false` (migrated from Quad's
+  legacy field JSON, alongside `isEnabled`/`isComplete`). Flipping the element-level `IS_VISIBLE=1`
+  (as `Client_Quad/2026-07-17b` block 3 does) may **not** render the button if the FE
+  (`SalesOrderTopBar`) reads `config.isVisible` — in which case a `CONFIG` override is also needed.
+  Element 32 is likewise `isEnabled=0` (appears but disabled until an `IS_ENABLED`/`ENABLED_RULE`
+  override is added). **Open follow-up.**
 
 ## Change history
+- 2026-07-17 — Applied the Core-neutral-default → client-opt-in pattern to the sales-order action &
+  filter buttons across Compass, CompassCanada, and Quad (`Client_*/2026-07-17a`+`b`). Cleared the
+  Core approvals-filter `_status` default (`Core/2026-07-17h`) so every client declares its own filter
+  `CONFIG`. Documented the sales-order surface **element-identity map** (surface 8 elements 17-21/32;
+  surface 9 elements 22-23) and the **id-agnostic override authoring house style** (resolve `roleId`
+  by name; resolve Core elements by surface slug + `Actions.slug`/label messageKey/`config.valueKey`;
+  `personaId`/`languageId` NULL; `NOT EXISTS`-guarded). Added gotchas: `Client_CompassCanada` may lack
+  the `SurfaceOverrides` table (beta reset predates rollout — table/ENUM/ACL prereqs must run first),
+  and "Enter PO Details" (element 32) has a dual visibility gate (element-level `isVisible` AND a
+  `config.isVisible` the FE may also read). (apeterson)
 - 2026-07-16 — Documented `SurfaceElements`' two orthogonal axes (`valueType` display vs `inputType`
   edit widget — neither derived from the other) and the edit-mode columns added in `Core/2026-06-25a`
   (`inputType`, `validationType` [renamed from `hasTypeCheck`], `showRequiredIndicator`, `isSearchable`,

package/package.json

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