toga-ai 1.0.387 → 1.0.389

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

@@ -160,6 +160,19 @@ breaks logic.
   `_Model_<Client>_*` overrides + `Client_ApiPayloadInterceptor` hooks — the Surface layer does
   **not** absorb business logic.
 
+### How the backend Tier-2 gate ACTUALLY dispatches (and `config.tier2` is DEAD)
+The Tier-2 gate in `resolveRecordState → _resolveTier2State` (`Surface.php` ~line 280) dispatches
+**by the element's ACTION SLUG** to a model method named by `const TIER2_CAPABILITY_METHOD`
+(`resolveSurfaceActionState()`) on the resolved `_Model_<Client>_*` — it does **NOT** read
+`config.tier2`. **`config.tier2` on a SurfaceElement is a NON-FUNCTIONAL marker: nothing —
+backend or frontend — reads it** (the FE evaluator `resolveElementState.ts` never reads it
+either), so do **not** spend effort "moving" it. As of 2026-07-20 the surface Tier-2 path is
+effectively a **no-op**: **no model implements `resolveSurfaceActionState()`** (only `Surface.php`
+references it), and **`stepTwoAssigned` does not exist anywhere in the backend** — so a Tier-2
+predicate like the Approve `stepTwoAssigned` gate below cannot be resolved server-side today. It is
+currently evaluable only by the **legacy** FE rule engine (see
+[surface-frontend](../../toga25-supply/features/surface-frontend.md) — the two FE engines).
+
 ## Per-client override of the Tier-1 gating RULES (not just static flags)
 
 Originally only static flags (`isVisible`/`isEnabled`) and `config` were per-client overridable
@@ -219,9 +232,34 @@ semantics). Concrete per-client diffs, all via `SurfaceOverrides` (rule JSON is
 - **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]`.
+    `_status in [pendingApproval, pendingInitialApproval]`. (For approve, a Tier-2 `stepTwoAssigned`
+    predicate further gates *enabled* — see the corrected Approve rule below.) On the approvals filter
+    button: `IS_VISIBLE=1` + `CONFIG` `additionalData._status = [pendingApproval, pendingInitialApproval]`.
+
+### Corrected Approve-button enable rule (Compass / Compass Canada ADMIN) — decision 2026-07-20
+The correct enable predicate for the Approve button is
+**`(status pendingInitialApproval AND stepTwoAssigned) OR (status pendingApproval)`** — i.e. a
+first-stage order is approvable only once step two is assigned, but a second-stage order is always
+approvable. As DSL:
+```json
+{"any":[{"all":[{"field":"order._status","op":"in","value":["pendingInitialApproval"]},{"type":"stepTwoAssigned"}]},{"field":"order._status","op":"in","value":["pendingApproval"]}]}
+```
+**Decision:** this rule lives **ONLY in the per-client `SurfaceOverride` row** as attribute
+`ENABLED_RULE`, encoded in the **`c_longValue`** column (with `value` NULL) — it is **NOT** baked
+into Core's element `enabledRule`, keeping Core client-neutral (client/role-specific gating stays in
+overrides). This works because `_castOverride` reads `value` first and **falls back to `c_longValue`**
+(`Surface.php` ~line 871), and `c_longValue mediumtext` avoids the `varchar(255)` truncation the JSON
+rule would hit. **Scope:** the Approve element on **surface 8** (`sales-order-record-actions`, el 17)
+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
+> [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).
@@ -353,6 +391,17 @@ 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-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
+  Tier-2 path is currently a **no-op**: no model implements `resolveSurfaceActionState`, and
+  `stepTwoAssigned` doesn't exist in the backend. Recorded the **decision** on the corrected
+  Compass/CompassCanada ADMIN Approve rule — `(pendingInitialApproval AND stepTwoAssigned) OR
+  pendingApproval` — encoded as an `ENABLED_RULE` `SurfaceOverride` in `c_longValue` (value NULL;
+  `_castOverride` value→c_longValue fallback, ~line 871), scoped to surface 8 el 17 + surface 3 el 29,
+  NOT in Core; approval-workflow-modal Approve deferred. Flagged the rule's `{type:stepTwoAssigned}`
+  node is evaluable only by the legacy FE engine today (backend Tier-2 no-op + frozen `evaluateSurfaceRule`
+  throws on `{type}`). (apeterson)
 - 2026-07-20 — Extended the resolver to emit `messages.trueLabel`/`messages.falseLabel` per element,
   sourced from `trueMessageId`/`falseMessageId` (collected into the same message batch + id→key remap);
   additive + backward-compatible (unset → null). Closes a latent gap: the serializer historically emitted

package/knowledge/2.0/apps/api2/features/surface-meta-option.md

@@ -33,6 +33,23 @@ resolved in one batched pass, per row in `meta`). When the option is **absent**
 traffic), behavior is **byte-for-byte unchanged** — pure data, zero extra work. The path is
 **defensive**: it catches `Throwable` and omits `meta.surface` on error rather than failing the call.
 
+### `meta.surface` payload shapes (V2.php ~5688-5717)
+The state pass runs **only** when the request carries the `surface` option **AND** the action is
+**READ** — no other method computes it. The attached shapes:
+- **Single GET:** `{ slug, state: { <elementUuid>: { isVisible, isEnabled } } }`.
+- **LIST:** `{ slug, records: { <recordUuid>: { elements: { <elementUuid>: { isVisible, isEnabled } } } } }`.
+
+`recordSurfaceState` is the channel a **server-computed Tier-2 gate** rides down to the FE (see the
+Tier-2 dispatch note in [surface-resolver](../../_underscore/features/surface-resolver.md)). On the
+FE, the type `RecordSurfaceState` (`src/surface/types.ts`) is
+`Record<string, { isVisible?, isEnabled?, isComplete? }>`, and `resolveElementState` **ANDs**
+`elementState.isEnabled`/`isVisible` onto the static + Tier-1 result.
+
+> ⚠ **Keying caveat (unverified — confirm before relying on the Tier-2 record-state path).** The
+> backend keys `state`/`elements` by **element UUID**, but the FE `resolveElementState` looks the
+> state up by **`element.action.key`**. Confirm those two key spaces line up (or add a UUID→action-key
+> bridge) before a server-computed per-record gate can actually take effect on the FE.
+
 ## Key rules
 
 - **Presentation state lives in `meta.surface`, never `data`.** Integrations get pure business data.
@@ -77,6 +94,12 @@ traffic), behavior is **byte-for-byte unchanged** — pure data, zero extra work
   silently lack it.
 
 ## Change history
+- 2026-07-20 — Documented the `meta.surface`/`recordSurfaceState` payload flow: computed only when the
+  `surface` option is present AND action is READ (V2.php ~5688-5717); single-GET shape
+  `{slug, state:{<elementUuid>:{isVisible,isEnabled}}}`, LIST shape
+  `{slug, records:{<recordUuid>:{elements:{…}}}}`; FE type `RecordSurfaceState` + `resolveElementState`
+  ANDs it onto the static+Tier-1 result. Flagged a keying caveat: backend keys by element UUID, FE
+  looks up by `element.action.key` — alignment unverified. (apeterson)
 - 2026-07-15 — Documented the diagnostic tell (`identifiers.script` present on the 403 EZ-1 → it is
   the `AclRecordScripts` dispatch gate, not record READ); clarified the dispatch check reads the
   caller's **CORE** roles because `surfaces.aclDatabase = CORE` (contradicts the earlier "client

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-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 |
 | [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

@@ -50,6 +50,9 @@ files:
   - 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
 related:
   - ../../_underscore/features/surface-resolver.md
@@ -180,6 +183,33 @@ to `{}` so Core carries **no** `_status` default. Every client — even Quad, wh
 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.
 
+### Row-actions surface (`sales-order-listing-row-actions`, Core surface id 3) — do not confuse with surface 9
+The sales-order listing has **two distinct** action surfaces: `sales-order-listing-actions` (id 9,
+the listing **header** buttons — approvals filter / columns) and `sales-order-listing-row-actions`
+(id 3, the **per-row dropdown menu**). Row-actions surface 3 elements:
+
+| Element | id | Discriminator |
+|---|---|---|
+| View | 5 | — |
+| approve | 29 | action `salesOrder.approve` |
+| deny | 30 | action `salesOrder.deny` |
+| approvalWorkflow | 31 | action `salesOrder.approvalWorkflow` |
+
+**Default-visibility correction + client opt-in (2026-07-20e):**
+- `Core/2026-07-20e - RestoreApproveDenyRowActions.sql` **narrows** an earlier **over-broad
+  `2026-07-20d` hide**: it re-enables **Approve (29)** and **Deny (30)** `isVisible=1`, leaving only
+  **View (5)** and **Approval Workflow (31)** hidden by default. Per an explicit developer instruction
+  ("create new, don't edit"), the correction is a **new dated file** and `2026-07-20d` was left
+  unchanged (an in-place edit was reverted) — a deliberate departure from the local-only fold-back
+  practice below, for this change.
+- `Client_Compass/2026-07-20e` + `Client_CompassCanada/2026-07-20e -
+  RowActionsApprovalWorkflowAdminEnable.sql` (mirror) opt the **ADMIN** role (resolved id-agnostically
+  by `Roles.name='Admin'`) into the **Approval Workflow** row-action (el 31) with **two override
+  rows** — `IS_VISIBLE=1` and `VISIBILITY_RULE` (`pendingApproval OR pendingInitialApproval`) —
+  resolved by surface slug + `Core.Actions.slug='salesOrder.approvalWorkflow'`, `NOT EXISTS`-guarded.
+  This extends the established Surface-override opt-in house style (mirrors the `2026-07-17a`
+  `SalesOrderApprovalActionsOverride` files) to the listing row-action menu.
+
 ## Display-section visibility — two patterns (marker vs field-driven)
 
 A record-modal **display SECTION**'s own `Surfaces.isVisible` can never be client-overridden (the
@@ -395,6 +425,16 @@ rule resumes.
   override is added). **Open follow-up.**
 
 ## Change history
+- 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) +
+  Deny (el 30) `isVisible=1`, leaving only View (el 5) + Approval Workflow (el 31) hidden by default
+  (a **new** dated file per explicit developer instruction, `20d` left unchanged — a deliberate
+  departure from the local-only fold-back rule for this change). `Client_Compass`/`Client_CompassCanada`
+  `2026-07-20e` opt the ADMIN role (by `Roles.name='Admin'`) into the Approval Workflow row-action (el
+  31) via `IS_VISIBLE=1` + `VISIBILITY_RULE` (pendingApproval OR pendingInitialApproval), resolved by
+  surface slug + `Actions.slug='salesOrder.approvalWorkflow'`, NOT EXISTS-guarded. Recorded the surface-3
+  element-identity map and added the three files to the RUN ORDER README. (apeterson)
 - 2026-07-20 — Applied the Core-neutral-default → client-opt-in pattern to the **item-record modal**.
   Header Edit button seeded OFF in Core; Compass + Compass Canada opt in via `Client_*/2026-07-20c`,
   resolving the element id-agnostically by `renderType='BUTTON'`+`config.kind='itemEdit'` (NOT EXISTS,

package/knowledge/2.0/apps/toga25-supply/INDEX.md

@@ -9,6 +9,6 @@
 | [Column Visibility (URL-driven show/hide columns)](features/column-visibility.md) | A "Columns" header button that opens a modal listing every column from the table meta, lets the user show/hide columns, adjusts the table live, and persists the | toga25-supply/src/components/ColumnVisibilityModal/, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/GenericNestedTables.tsx, toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json, toga25-supply/src/hooks/useTableCellInteractions.ts, toga25-supply/src/hooks/useServerTableUrlState.ts |
-| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx |
+| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

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

@@ -20,6 +20,9 @@ files:
   - toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts
   - toga25-supply/src/surface/evaluateSurfaceRule.ts
+  - toga25-supply/src/surface/resolveElementState.ts
+  - toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts
+  - toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts
   - toga25-supply/src/surface/actionRegistry.ts
   - toga25-supply/src/surface/componentRegistry.tsx
   - toga25-supply/src/surface/SurfaceActionBar.tsx
@@ -257,6 +260,40 @@ in [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md):
 > shows **`leasePrice`** for all clients, whereas the old DEFAULT JSON showed only unit price. Confirm
 > that is the intended seed shape.
 
+## 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.
+- **`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`.)
+
+### 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`**.
+
+- **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.
+
 ## Gotchas
 
 - **The single-meta envelope can hide the real bundle behind a DECOY `elements: []`.** The V2 envelope
@@ -319,6 +356,11 @@ in [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md):
   (the path form 404s EV-6).
 - **Tier-1 only on the client.** Business-logic gates (Tier-2) arrive as resolved booleans from the
   backend (`meta.surface`); never re-encode business rules in the FE evaluator.
+- **`recordSurfaceState` keying mismatch (unverified).** The backend keys the per-record state by
+  **element UUID** (single: `state[<elementUuid>]`; list: `records[<recordUuid>].elements[<elementUuid>]`
+  — see [surface-meta-option](../../api2/features/surface-meta-option.md)), but `resolveElementState.ts`
+  looks the state up by **`element.action.key`**. Confirm the two key spaces line up (or bridge them)
+  before a server-computed Tier-2 gate can actually AND onto the FE result.
 - **A React portal overlay's click bubbles through the COMPONENT tree, not the DOM tree.** The
   SalesOrders row-actions menu (`SurfaceRowActions.tsx`) renders its dismiss overlay via a portal;
   an outside-click on that fixed overlay propagated up the React component tree to the row's
@@ -331,6 +373,16 @@ in [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md):
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-07-20 — Documented the **two FE rule engines** (frozen surface Tier-1 `evaluateSurfaceRule`,
+  which THROWS on `{type}` nodes, vs legacy `evaluateEnableRule` with `{type}` NAMED_RULES incl
+  `stepTwoAssigned` reading `ctx.currentStage`/`ctx.stages`) and why the corrected Approve rule is
+  evaluable only by the legacy engine today. **Built** the record-modal (surface 8) stage plumbing:
+  merged `approvalCurrentStage`/`approvalStages` onto the order (`orderWithPo`) as `currentStage`/`stages`
+  (additive) so the surface `stepTwoAssigned` predicate can read `order.currentStage`/`order.stages`.
+  Recorded remaining work: the listing row dropdown (surface 3, `useSalesOrderRowRecordState.ts`)
+  fetches order+PO but not approval stages — still needs `useFetchApprovalStages`+merge plus
+  `evaluateSurfaceRule` named-check support. Added a gotcha: `recordSurfaceState` keys by element UUID
+  server-side but `resolveElementState` looks up by `action.key` (alignment unverified). (apeterson)
 - 2026-07-20 — Migrated the **item-record modal VIEW** onto Surface for **ALL clients (no roster)** via
   the adapter seam: new `surfaceBundleToItemViewFields()` adapts the `item-record-*` surface group
   (`useFetchSurfaceMetaGroup`) into the existing `{header, editItem, sections, vendorItemsEnabled}`

package/knowledge/sessions/2026-07-21-surface-approve-steptwo-apeterson.md

@@ -0,0 +1,70 @@
+---
+type: session
+slug: surface-approve-steptwo
+title: Surface-drive the Approve step-two-assigned enable gate for Compass/Compass Canada
+author: apeterson
+repos: [toga25-supply, dbchanges2, _underscore, api2]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-07-21
+updated: 2026-07-21
+---
+
+# Session: surface-approve-steptwo
+**Date:** 2026-07-21
+**Project/Repo:** toga25-supply + dbchanges2 (2.0)
+**Task:** Move the Approve-button "step-two assigned" enable gate off the legacy per-client FE JSON and into the Surface layer (role-scoped SurfaceOverride ENABLED_RULE), for Compass/Compass Canada admins, on the record-actions bar (surface 8) and listing row-actions (surface 3).
+
+---
+
+## What WORKED
+<!-- Include specific file paths and evidence -->
+- **Record-actions (modal) data merge — DONE & verified.** In `toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx`, merged `currentStage: approvalCurrentStage ?? null` and `stages: approvalStages ?? []` onto the returned `orderWithPo` object (lines ~148-149), and added `approvalCurrentStage, approvalStages` to the useMemo deps (line ~172). Purely additive — parallel to the existing `purchaseOrderDetails` merge. `approvalCurrentStage/approvalStages` were already fetched in that hook via `useFetchApprovalStages` (lines ~105-113). Verified present with grep post-edit.
+- **DB — row-actions default-visibility correction (Core).** Created `dbchanges2/Core/2026-07-20e - Update - RestoreApproveDenyRowActions.sql` — narrows the earlier over-broad `2026-07-20d` hide: re-enables Approve (el 29) + Deny (el 30) `isVisible=1` on surface `sales-order-listing-row-actions` (id 3), leaving only View (el 5) and Approval Workflow (el 31) hidden by default. Scoped by surface slug + `e.id IN (29,30)`, idempotent.
+- **DB — Approval Workflow row-item ADMIN opt-in (Compass + Compass Canada).** Created `dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql` and the mirrored `dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql`. Each opts the `Admin` role (resolved id-agnostically by `Roles.name='Admin'`) into element 31 with two override rows — `IS_VISIBLE='1'` and `VISIBILITY_RULE` (`{"all":[{"field":"order._status","op":"in","value":["pendingApproval","pendingInitialApproval"]}]}`) — element resolved by surface slug + `Core.Actions.slug='salesOrder.approvalWorkflow'`. NOT EXISTS-guarded. Mirrors the 2026-07-17a `SalesOrderApprovalActionsOverride` precedent. NOTE: these are for the Approval WORKFLOW item's *visibility* (el 31), NOT the Approve-button ENABLED_RULE work (still TODO — see below).
+- **DB — RUN ORDER updated.** `dbchanges2/Core/2026-07-17 - README - RUN ORDER.md` lists the three new `2026-07-20e` files.
+- **Knowledge captured.** `/capture` updated 4 docs (surface-resolver, surface-meta-option, surface-frontend, surface-layer-schema) and pushed to `_main`.
+
+## What did NOT work — DO NOT RETRY THESE
+<!-- Exact failure reasons — do not vague-ify -->
+- **DO NOT "move `config.tier2` from Core into a SurfaceOverride" to control the disabled state.** `config.tier2 = "stepTwoAssigned"` on Core element 17 is a NON-FUNCTIONAL marker. Nothing reads it: the backend Tier-2 gate (`_underscore/Model/Core/Surface.php::resolveRecordState` → `_resolveTier2State`, ~line 280) dispatches by ACTION SLUG to a model method `resolveSurfaceActionState()` (const `TIER2_CAPABILITY_METHOD`), never by `config.tier2`; and the FE (`toga25-supply/src/surface/resolveElementState.ts`) never reads `config.tier2`. Moving/overriding it changes zero behavior.
+- **DO NOT rely on the backend Tier-2 path to gate this today.** No model implements `resolveSurfaceActionState` (only `Surface.php` references it), and `stepTwoAssigned` does not exist anywhere in the backend. So `_resolveTier2State` always returns null; `meta.surface` carries only Tier-1 results.
+- **DO NOT put `{"type":"stepTwoAssigned"}` into a rule and expect `evaluateSurfaceRule` to run it as-is.** `toga25-supply/src/surface/evaluateSurfaceRule.ts` has a DELIBERATELY FROZEN grammar (all/any/none + leaf field ops eq/ne/in/nin/gt/gte/lt/lte) and THROWS `"[surface] Unknown rule node"` on any `{type:...}` node. It needs named-check support added first (piece #3 below).
+- **DO NOT bake the Approve rule into Core's element `enabledRule`.** Per developer decision, the rule lives ONLY in the per-client SurfaceOverride `c_longValue` column (attribute `ENABLED_RULE`, `value` NULL). Core stays client-neutral.
+- **DO NOT edit an already-run migration file in place.** Developer instruction: create a NEW forward migration instead. (An in-place edit to `2026-07-20d` was made then reverted for this reason; the `2026-07-20e` Core file is the forward fix.)
+
+## Not tried yet (candidates for next session)
+- **[Piece 2 — row-actions data merge]** Add a `useFetchApprovalStages(enabled ? uuid : null, userUuid, {})` call to `toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts` (gated on `enabled`, like the order fetch) and merge `currentStage`/`stages` into its `order` object (currently `{ order: {...cleanedOrder, purchaseOrderDetails} }`). This is the heaviest piece — adds a per-row approval-stages fetch when a dropdown opens.
+- **[Piece 3 — evaluator]** Teach `toga25-supply/src/surface/evaluateSurfaceRule.ts` the `{"type":"stepTwoAssigned"}` named check, reusing the existing logic from `toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts` (`NAMED_RULES.stepTwoAssigned`). Surface record is shaped `{ order }`, so the surface predicate must read `order.currentStage` / `order.stages` (NOT top-level `ctx.currentStage` like the legacy engine). Add a code comment noting this intentionally deviates from the "frozen grammar / escalate to Tier-2" note.
+- **[Piece 4 — DB ENABLED_RULE overrides]** Write per-client SurfaceOverride rows (attribute `ENABLED_RULE`, `value` NULL, rule JSON in `c_longValue`, scoped to `@adminRoleId` via `Roles.name='Admin'`) on the Approve element for surface 8 el 17 (`sales-order-record-actions`) AND surface 3 el 29 (`sales-order-listing-row-actions`), for Compass + Compass Canada. Rule = `{"any":[{"all":[{"field":"order._status","op":"in","value":["pendingInitialApproval"]},{"type":"stepTwoAssigned"}]},{"field":"order._status","op":"in","value":["pendingApproval"]}]}`. Works because `_castOverride` (Surface.php ~line 871) reads `value` then falls back to `c_longValue`. Resolve element id-agnostically by surface slug + `Core.Actions.slug='salesOrder.approve'`. NOT EXISTS-guard; add to RUN ORDER.
+- **Verify keying caveat:** backend keys `meta.surface.state` by element UUID, but `resolveElementState` looks up `recordSurfaceState` by `element.action.key`. Confirm these line up (or Tier-2 state silently never matches). Not blocking the Tier-1 ENABLED_RULE plan, but relevant if backend Tier-2 is ever wired.
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx | Modified (DONE) | `currentStage`/`stages` merged onto `orderWithPo` + deps updated. Additive. |
+| toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts | Unchanged (TODO piece 2) | Still fetches order + PO only; no approval-stages fetch/merge. |
+| toga25-supply/src/surface/evaluateSurfaceRule.ts | Unchanged (TODO piece 3) | Frozen grammar; throws on `{type}`. Needs `stepTwoAssigned` named check. |
+| dbchanges2/Core/2026-07-20e - Update - RestoreApproveDenyRowActions.sql | Created | Re-enables Approve(29)+Deny(30) on surface 3; narrows 2026-07-20d. |
+| dbchanges2/Core/2026-07-20d - Update - HideSalesOrderRowActionsByDefault.sql | Unchanged (in-place edit reverted) | Original all-elements hide preserved. |
+| dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql | Created | Admin opt-in for Approval Workflow item (el 31): IS_VISIBLE + VISIBILITY_RULE. NOT the Approve ENABLED_RULE. |
+| dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql | Created | Mirror of Compass. |
+| dbchanges2/Core/2026-07-17 - README - RUN ORDER.md | Modified | Lists the three new 2026-07-20e files. |
+| (TODO) dbchanges2 Client_Compass/Client_CompassCanada Approve ENABLED_RULE override files | Not created | Piece 4 — Approve el 17 + el 29 ENABLED_RULE in c_longValue. |
+
+## Decisions made
+- **Approve step-two gate lives in the Surface layer, evaluated on the FE (Option B), not backend Tier-2 (Option C) and not legacy-only (Option A).** Rationale: the value changes live in-modal (user assigns a step-two approver right there), so instant FE evaluation beats a server snapshot that only refreshes on refetch; and the team is already creating separate Approve elements per surface. Rejected: A (legacy JSON only — can't reach the surface bar/row); C (backend `resolveSurfaceActionState` — snapshot-only, won't re-enable live after assignment).
+- **The rule JSON goes in the SurfaceOverride `c_longValue` column, attribute `ENABLED_RULE`, `value` NULL — NOT in Core.** Rationale: keep Core client-neutral; client/role gating stays in overrides; `_castOverride` falls back to `c_longValue`. (Note: the earlier 2026-07-17a files put shorter rule JSON in `value`; this longer OR-rule uses `c_longValue` per developer instruction.)
+- **Corrected Approve rule:** `(pendingInitialApproval AND stepTwoAssigned) OR (pendingApproval)` — only for the Approve button (not Deny / Approval Workflow).
+- **Scope for now:** only `sales-order-record-actions` (surface 8, el 17) and `sales-order-listing-row-actions` (surface 3, el 29). The approval-workflow-modal Approve element does NOT exist as a surface yet — deferred.
+- **Admin role resolved by `Roles.name='Admin'`** (id-agnostic; client role ids are not environment-stable), matching the 2026-07-17a precedent.
+
+## Blockers
+- None hard. Piece 2 (row-actions) requires an extra per-row approval-stages fetch — a performance consideration (fires on dropdown open only), not a blocker. Piece 3 intentionally deviates from the frozen-grammar design intent of `evaluateSurfaceRule` — acceptable per the Option B decision but worth a comment.
+
+## Exact next step
+> In `toga25-supply/src/surface/evaluateSurfaceRule.ts`, add support for a `{"type":"stepTwoAssigned"}` leaf node (a small named-predicate branch reusing the `stepTwoAssigned` logic from `src/pages/SalesOrders/helpers/evaluateEnableRule.ts`), reading `order.currentStage` / `order.stages` off the `{ order }`-shaped surface record. This is the smallest independent piece and unblocks testing the already-merged modal stage data (piece 1).
+
+---
+_Saved by /session-save on 2026-07-21_

package/package.json

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