toga-ai 1.0.387 → 1.0.388

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/package.json

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