toga-ai 1.0.240 → 1.0.242

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

@@ -13,6 +13,6 @@
 | [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 |
-| [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, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.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, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.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_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView |  |

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

@@ -6,10 +6,12 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-29
+updated: 2026-06-30
 owners: [jcardinal]
 files:
   - _underscore/Model/Core/Surface.php
+  - dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql
+  - dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql
   - dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql
   - dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql
   - dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql
@@ -69,6 +71,29 @@ Inputs come from `$api` (the same accessor `_Model_Client_TableView::meta` uses)
 A `metaDebug()` inspector returns the resolved bundle plus the raw cascade layers (shipped with the
 resolver, not "later"). It is **not** named `debug()` — see gotchas.
 
+## Grouped resolution — `metaGroup()`
+
+`_Model_Core_Surface::metaGroup(&$api, string $slugs): object` — a scripted-API method exposed at
+`GET /v2/surfaces/meta-group?slugs=a,b,c` for screens (e.g. a record-detail modal) that need many
+section surfaces at once: **one round trip instead of N**. It splits the comma-separated `slugs`
+list (capped at `const META_GROUP_MAX_SLUGS = 25`, logging truncation), resolves **each slug via the
+existing per-slug `resolve()` cache path**, and returns `{group, surfaces: {slug => bundle|null}}`.
+It is **composition only** — no new cache layer; an unknown slug yields the structured **empty
+bundle** so one missing surface never fails the whole group. (Chosen over a `parentSurfaceId` GROUP
+row after CTO review — a slug list keeps the model schema-stateless and avoids id drift.)
+
+`resolve()` now declares an explicit `: object` return type.
+
+### Message/label resolution fixes (latent SECTION/BUTTON_BAR bugs)
+The grouped SalesOrders section migration is the first real consumer of the SECTION/BUTTON_BAR path,
+which surfaced latent resolution gaps in `_buildBundle`/`_resolveElement`:
+- Element message slots (`label`/`tooltip`/`placeholder`/`disabledTooltip`) are now remapped from
+  **message-id → messageKey** before return, because `bundle.messages` is keyed by `messageKey` —
+  previously labels silently fell back to the element key.
+- `disabledTooltipMessageId` is collected into the batch and emitted as a `disabledTooltip` slot.
+- `bundle.surface.titleMessageKey` is set from `titleMessageId`.
+- The 2nd `_loadMessages` return is merged into `$messageKeyById`; dangling message ids are logged.
+
 ## Caching & invalidation
 
 - Disk cache keyed `surface:meta:{app}:{slug}:{client}:{sortedPersonaIds}:{sortedRoleIds}:{lang}`.
@@ -137,7 +162,20 @@ resolver, not "later"). It is **not** named `debug()` — see gotchas.
   `record-fields` already expose Public READ. Only the `surfaces` record gets Public read — the
   admin-CRUD sibling records stay Super-User-only (the resolver reads their tables server-side).
 
+- **The meta-group dispatch grant is per-client-DB too.** A 403 EZ-1 on `meta-group` on dev-sandbox
+  was the same mechanism as the original `meta` 403: the `meta-group` RecordScript needs its own
+  per-role `Client.AclRecordScripts` dispatch grant. Verified via toga-db — `meta` script id 25 was
+  granted roles 1/3/4 but `meta-group` (id 27) had **none** until the grant ran. Any new surfaces
+  scripted-API method repeats this: record READ never authorizes dispatch.
+
 ## Change history
+- 2026-06-30 — Added `metaGroup()` (`GET /v2/surfaces/meta-group?slugs=a,b,c`): batched composition
+  over the existing per-slug `resolve()` cache, capped at `META_GROUP_MAX_SLUGS=25`, unknown slug →
+  empty bundle (chosen over a `parentSurfaceId` GROUP row post-CTO-review). Fixed latent
+  SECTION/BUTTON_BAR resolution (message-id→messageKey remap for label/tooltip/placeholder/
+  disabledTooltip, titleMessageKey, dangling-id logging); added `: object` to `resolve()`. The
+  `meta-group` script needed its own per-client `AclRecordScripts` dispatch grant (403 EZ-1 until
+  granted). (jcardinal)
 - 2026-06-29 — Deploy fixes (round 2): grant the surfaces `meta`/`debug` RecordScripts in
   `Client.AclRecordScripts` per role (Public/SuperUser/Base) — record-level `AclRecordPermissions`
   alone left every meta call 403 EZ-1 because V2 dispatch authorizes via `AclRecordScripts`

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-06-29
+updated: 2026-06-30
 owners: [jcardinal]
 files:
   - api2/Component/Api/V2/V2.php
@@ -56,7 +56,14 @@ traffic), behavior is **byte-for-byte unchanged** — pure data, zero extra work
   meta 403'd until the `meta`/`debug` scripts were granted per role in `AclRecordScripts`. See
   [surface-resolver](../../_underscore/features/surface-resolver.md) gotchas.
 
+- **Grouped meta endpoint `GET /v2/surfaces/meta-group?slugs=a,b,c`** (one round trip for a
+  multi-section screen) is a distinct RecordScript and needs its **own** per-role
+  `Client.AclRecordScripts` dispatch grant — it 403'd EZ-1 on dev-sandbox until granted, exactly like
+  `meta` did. See [surface-resolver](../../_underscore/features/surface-resolver.md).
+
 ## Change history
+- 2026-06-30 — Noted the grouped `meta-group` endpoint (batched multi-slug resolve) and that it needs
+  its own per-role `AclRecordScripts` dispatch grant (403 EZ-1 until granted). (jcardinal)
 - 2026-06-29 — Documented the second ACL layer: scripted-API dispatch is authorized via
   `Client.AclRecordScripts` (per `recordScriptId`+`roleId`), not record `AclRecordPermissions` —
   record READ alone still 403'd meta until the dispatch grants were seeded. (jcardinal)

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/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/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/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 |
 | [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-06-29
+updated: 2026-06-30
 owners: [jcardinal]
 files:
   - dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql
@@ -18,6 +18,11 @@ files:
   - 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
@@ -82,6 +87,19 @@ SurfaceElements`). Core migrations run first; Client after. The session built/se
   purchase-orders/items/units via per-level fetchSlugs and has no single backing Record; carries
   `groupByLabels` + `entityTags` in surface `config`) + `inventory-list-actions` (BUTTON_BAR:
   Group by / Refresh). Actions anchored to `items(21)` because `Actions.recordId` is NOT NULL.
+- `Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql` — registers the `meta-group`
+  RecordScript; seeds the previously-missing `order-recurring` SECTION surface (cardType
+  `recurringFields`, `isVisible 0`); seeds 5 display-toggle SECTION surfaces (invoices / shipments /
+  additional-order-details / notes / admin-notes), **each carrying a single `sectionVisibility`
+  marker element** (see gotcha — the override cascade only overrides ELEMENTS, never a surface's own
+  `isVisible`, so display-section visibility cannot be per-role-overridden without a marker element).
+  Core→Core only, so this file is prod-safe.
+- `Client/2026-06-30a - SurfaceMetaGroupAcl.sql` — the `meta-group` `AclRecordScripts` dispatch grant
+  (roles 1/3/4), mirroring the `meta` grant.
+- `Client_Compass/2026-06-30a` / `Client_CompassCanada/2026-06-30a` — per-client **MANAGER**-scope
+  SalesOrder section overrides; `Client_Quad/2026-06-30a` — Quad's **client-level** section deltas.
+  ⚠ These three Client-DB seeds currently resolve **Core** ids via cross-DB subselect — see the
+  prod cross-cluster gotcha; they are paused before prod.
 - `Client/2026-06-29c - SurfaceRecordScriptAcl.sql` — grants the surfaces `meta`/`debug` RecordScripts
   in **`Client.AclRecordScripts`** per role (meta → Public(1)/SuperUser(3)/Base(4); debug →
   SuperUser(3)). V2 authorizes scripted-API dispatch via `AclRecordScripts`, NOT record
@@ -122,7 +140,31 @@ SurfaceElements`). Core migrations run first; Client after. The session built/se
 - **CLIENT-aclDatabase records** (`SurfaceOverrides`, `MessageTranslations`, `ThemeTokens`) need the
   full 4-step ACL chain + field permissions in **each** client DB; resolve `roleId` by subselect.
 
+- **⚠ PROD BLOCKER (ON HOLD) — Client-DB surface seeds must NOT resolve Core ids via cross-DB
+  subselect.** The `Client_Compass`/`Client_CompassCanada`/`Client_Quad` SalesOrder override seeds
+  resolve Core ids (`Core.RecordScripts`/`Core.Surfaces`/`Core.SurfaceElements`) with a cross-DB
+  subselect. This works only on the dev-sandbox **all-in-one** instance; in **production Core is a
+  separate cluster** and cross-DB queries require a single instance, so these seeds **break in prod**.
+  The established prod-safe pattern is `Client/2026-06-23b - ItemTranslationsAcl.sql`: **hardcode Core
+  ids as literals**, resolve only Client-local ids (e.g. `roleId` by name). The fix is paused; the
+  earlier `2026-06-25c` / `2026-06-29c` / `2026-06-25d` surface seeds **likely share the same
+  anti-pattern** and need auditing. Core→Core seeds are fine (same cluster). Also still open:
+  re-seeding NYCHH/Prudential/SPGlobal (deferred).
+- **Display-section visibility cannot be per-role-overridden without an element.** The override
+  cascade overrides **ELEMENTS only**, never a surface's own `isVisible`. The 5 display-toggle SECTION
+  surfaces therefore each carry a single `sectionVisibility` marker element so a Client override can
+  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).
+
 ## Change history
+- 2026-06-30 — Added the SalesOrders SECTION-surface migration seeds: Core `meta-group` RecordScript +
+  `order-recurring` + 5 display-toggle SECTION surfaces (each with a `sectionVisibility` marker
+  element, since the cascade overrides elements not a surface's own isVisible), the `meta-group`
+  dispatch ACL grant, and per-client (Compass/CompassCanada MANAGER, Quad client-level) section
+  overrides. Recorded the ⚠ prod blocker: Client-DB seeds resolving Core ids via cross-DB subselect
+  break in prod (Core is a separate cluster) — must hardcode Core id literals per the
+  `ItemTranslationsAcl.sql` pattern; fix paused, earlier surface seeds likely share it. (jcardinal)
 - 2026-06-29 — Added VendorItems + Inventory LIST seeds (`VendorItemsSurfaceSeed.sql` recordId 19 /
   TableView 10; `InventorySurfaceSeed.sql` presentation-only, recordId+tableViewId NULL, Actions
   anchored to items(21)). Added `SurfaceRecordScriptAcl.sql` (per-role `AclRecordScripts` dispatch

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

@@ -8,4 +8,5 @@
 | [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/, toga25-supply/src/hooks/useTableCellInteractions.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/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, 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/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 |
+| [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/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, 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/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/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 |
+| [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/record-modals-and-nested-tables.md

@@ -141,7 +141,22 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
   configs must use a `scope` discriminator in the query key or they overwrite each other's cache
   (record modal vs. approval modal: the approval modal omitting item-image fields blanked the
   record modal's images until scoping isolated the entries).
+- **`poNumber` does NOT go through the approval modal.** `SalesOrderView` routes
+  `activeModal === "poNumber"` to a **separate** `EnterPoNumberModal` and explicitly excludes it
+  from `SalesOrderApprovalModalsLayout` (`activeModal !== "poNumber"`). The approval-modal
+  `modalSelected` union still lists `"poNumber"`, but that path is handled by the PO modal, not
+  the approval flow — don't add PO-number handling to the approval layout.
+- **Approval submit payload: workflow vs single decision differ.** A single approve/deny posts a
+  **boolean** `isApproved` (`true`/`false`). The workflow path
+  (`handleFormatApprovalWorkflowPayload`) posts a **string** `"1"`/`"0"`, emits a request **only**
+  for stages whose `note` / `assignedTo` / `decision` actually changed, and chooses verb by
+  `stage.ApprovalDecisions.uuid` — `null` → POST `/approval-decisions`, otherwise PUT
+  `/approval-decisions/{uuid}`.
 
 ## Change history
+- 2026-06-30 — Recorded two behaviors confirmed while building approval-modal tests: `poNumber`
+  is handled by a separate `EnterPoNumberModal` (excluded from the approval layout), and the
+  workflow vs single-decision submit payloads differ (string `"1"`/`"0"` + changed-stages-only +
+  POST/PUT by decision uuid, vs boolean `isApproved`). (apeterson)
 - 2026-06-23 — Documented from CLAUDE.md Modal Patterns 1–5 + the `create-record-modal` skill during
   initial knowledge seed. (apeterson)

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

@@ -6,10 +6,13 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-06-29
+updated: 2026-06-30
 owners: [jcardinal]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
+  - toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
+  - 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/SurfaceActionBar.tsx
@@ -51,6 +54,12 @@ feature flag — see below). Backend: [surface-resolver](../../_underscore/featu
   `raw` / `raw.data` / `raw.data.<route-key>` — because V2 nests a scripted-API return value one
   level deeper, under a route-keyed slot of `data` (e.g. `data.meta`, `data.surfaces`). On a malformed
   payload it falls back to an empty-elements bundle so the page never crashes.
+- **`useFetchSurfaceMetaGroup(slugs[])`** — the grouped sibling of `useFetchSurfaceMeta`, for a screen
+  needing many section surfaces at once. **Order-insensitive** (the slug list is normalized so cache
+  hits don't depend on argument order), `staleTime: Infinity`, hits the grouped endpoint
+  `GET /v2/surfaces/meta-group?slugs=...`, and extracts the `{surfaces}` map via `extractGroup()` /
+  `looksLikeGroup()` (the same structural-fingerprint approach as `extractBundle`). Returns `{}` for
+  unmigrated screens (`enabled:false`), so a non-roster client does no fetch.
 - **`evaluateSurfaceRule`** — the Tier-1 rule evaluator: a **frozen `all/any/none` + `{field,op,value}`
   grammar** that **throws on an unknown op** (generalized from the SalesOrders
   `buildPatchedTenantFields`/`evaluateEnableRule`/`resolveFlag` helpers). Evaluated client-side against
@@ -114,20 +123,35 @@ modal copy, visibility/enable) to Surface; **leave data-fetch wiring (fetch slug
 nested-table topology) in JSON/code.** Not every screen reduces to a generic `SurfaceSection` swap —
 see SalesOrders below.
 
-## SalesOrders remaining migration — bespoke, NOT a generic SurfaceSection swap (deferred)
-
-The SalesOrders detail migration is the plan's explicitly-deferred "blessed escape hatch"/approval
-work — it is bespoke-component + business-logic work, not a generic swap. `SalesOrderSummaryGrid` is
-fully tenant-data-driven through three **bespoke renderers**: `detailSection` (blox `DetailSection` +
-custom `renderField`), `locationCard` (`OrderSectionCard`, structured contact data), and `totalsCard`
-(blox `BaseTotals` **with client-specific recurring-lease business logic**:
-`_totalLease !== 0 → recurringKey` fields). The generic `SurfaceSection` (label/value) cannot
-represent `BaseTotals`/`OrderSectionCard`, and the early-seeded order-details/ship-to/bill-to/
-order-summary SECTION surfaces do **not** cleanly map onto the grid's arbitrary client-keyed section
-model. A faithful migration needs a **registered-renderer approach** keyed off surface element config
-(`detailSection`/`locationCard`/`totalsCard` → their components), with the lease logic staying in
-code/`_underscore`, plus reconciling those seeds and the Compass approval-modal state machine.
-**Deferred to a dedicated design-first session.**
+## SalesOrders record-modal sections — migrated via the registered-renderer seam (roster-gated)
+
+The SalesOrders detail sections are now migrated onto Surface for the **seeded roster clients only**,
+via the registered-renderer approach (not a generic `SurfaceSection` swap — `SalesOrderSummaryGrid`'s
+three bespoke renderers `detailSection`/`locationCard`/`totalsCard` are untouched).
+
+- **`surfaceBundleToTenantFields()`** (`SalesOrders/helpers/`) adapts the grouped Surface bundle into
+  the existing **`TenantFields`** shape, so the existing `SalesOrderSummaryGrid` renderers and
+  `getDetailSections` are untouched — **only the SOURCE of section config moves JSON → Surface.**
+  Business logic stays in code: the recurring-lease `_totalLease` gate in the grid and approval
+  gating are **not** moved. (Registered-renderer seam: *config describes, code decides.*)
+- **Roster gate — `SALES_ORDER_SURFACE_MIGRATED_CLIENTS = [COMPASS, COMPASSCANADA, QUAD]`** (an
+  in-code roster in `surfaceBundleToTenantFields.ts`; the view-model
+  `useSalesOrderRecordModalLayoutModel.tsx` consults it). The view-model resolves sections from
+  Surface **only** for roster clients; every other client (incl. never-migrated
+  NYCHH/Prudential/SPGlobal) skips the fetch and stays fully JSON-driven. Merge is **JSON-base +
+  Surface-wins.** ⚠ **Why a roster, not a flag:** the Core SECTION surfaces are **shared** and seeded
+  from Compass's shape — without the gate every client would inherit Compass's base and regress. A
+  **code** roster (not an env flag) is deliberate: a client is removed from the roster only once its
+  own seeds are verified.
+- **JSON cleanup:** the migrated section blocks (orderDetails/shipTo/billTo/orderSummary/
+  orderRecurring + the 5 display sections) were **deleted** from the COMPASS / COMPASSCANADA / QUAD
+  `orderViewFields.json` files. Data-wiring (`salesOrderDetailsConfig`/`itemFulfillmentClickRule`/
+  `recordActionFields`/`recordApprovals`) was **kept**. The DEFAULT `orderViewFields.json` is left
+  **intact** — non-roster clients are still JSON-driven.
+
+**Still JSON / deferred:** the SalesOrders **action-bar / approval-modal** migration remains on JSON;
+seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster seed fix is on hold
+(see [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md)).
 
 ## Gotchas
 
@@ -147,6 +171,14 @@ code/`_underscore`, plus reconciling those seeds and the Compass approval-modal
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-06-30 — Migrated the SalesOrders record-modal sections onto Surface for the roster clients
+  [COMPASS, COMPASSCANADA, QUAD] via the registered-renderer seam: added `useFetchSurfaceMetaGroup`
+  (order-insensitive grouped `/surfaces/meta-group` fetch) + `surfaceBundleToTenantFields()` (adapts
+  the grouped bundle to the existing `TenantFields` shape; bespoke grid renderers + lease/approval
+  logic stay in code). Roster-gated (code roster, JSON-base + Surface-wins) so non-roster clients
+  don't inherit Compass's shared base. Deleted the migrated section blocks from COMPASS/COMPASSCANADA/
+  QUAD `orderViewFields.json` (data-wiring kept; DEFAULT intact). Action-bar/approval-modal still
+  JSON. (jcardinal)
 - 2026-06-29 — Migrated VendorItems (screen 2, recipe-exact) and Inventory (screen 3,
   **presentation-only by decision** — fetch topology stays JSON; only title/buttons/modal copy/entity
   tags moved). Fixed the "s.elements is not iterable" crash: `extractBundle()` now finds the bundle by

package/knowledge/2.0/apps/toga25-supply/workflows/cypress-testing.md

@@ -0,0 +1,143 @@
+---
+title: Cypress Testing Harness (component + e2e)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: workflow
+status: active
+updated: 2026-06-30
+owners: [apeterson]
+files:
+  - 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
+related:
+  - ../features/record-modals-and-nested-tables.md
+  - ../features/action-button-rule-engine.md
+  - ../architecture.md
+---
+
+## What it is
+
+The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch
+(`cypress` was already a dependency but there was no config, no `cypress/` dir, and zero
+tests anywhere in the repo). It defines **both** a `component` project (Vite devServer,
+mounts a single component) and an `e2e` project, plus reusable support code for mounting
+components with the app's providers, mocking a component's data hook without a network or
+tenant config, and sharing fixtures. The first specs cover the Sales Order **approval
+modal flow**. Use this doc when adding any new test to the repo.
+
+## How the harness is wired
+
+### `cypress.config.ts` — two projects
+
+- **`component`** — `devServer: { framework: "react", bundler: "vite" }` with a `viteConfig`
+  that **mirrors the app's `vite.config.ts`**: the `@` → `src` alias, the regex aliases that
+  force a single React copy, `optimizeDeps.exclude: ["@agilant/toga-blox"]` +
+  `optimizeDeps.include: ["dayjs"]`. This is the load-bearing part — toga-blox must resolve
+  the same way it does under `npm run dev`, or mounted components fail to bundle or get a
+  second React copy.
+- **`e2e`** — standard `baseUrl` + `supportFile` setup for full-journey specs.
+
+### `cypress/support/component.tsx` + `commands.ts` — mounting with providers
+
+`cy.mountWithProviders` is a custom command that wraps the mounted component in
+`QueryClientProvider` + `ToasterProvider`. It accepts an **injectable `queryClient`** so a
+spec can `cy.spy()` on `removeQueries` / `invalidateQueries` and assert the cache routine a
+component runs on success. The default QueryClient is configured with `retry: false` for
+determinism. Support also imports `@/index.css` (styling) and `@/api/api` — the latter so
+toga-blox's `apiPost` / `apiPut` have a configured axios instance available during component
+tests.
+
+### Window-backed hook-mock pattern (key technique)
+
+`cypress/support/mocks/useApprovalModalViewModel.ts` lets you unit-test a data-binding
+component **without** a network or tenant config. The component devServer aliases the
+component's **relative** import of its view model to the mock:
+
+```ts
+// in the component viteConfig resolve.alias
+{ find: /^\.\/viewModel\/useApprovalModalViewModel$/, replacement: "<abs>/cypress/support/mocks/useApprovalModalViewModel.ts" }
+```
+
+The mock returns whatever the spec parked on `window.__approvalModalViewModel`. In Cypress
+component testing the spec and the component share the **same `window`**, so a plain
+assignment before `cy.mount` is visible to the hook. Helpers `setApprovalModalViewModel` /
+`resetApprovalModalViewModel` set and clear it. To mock a different component's hook, add a
+parallel regex alias + a parallel `window.__<name>` mock.
+
+### `cypress/support/fixtures.ts` — shared fixtures
+
+Imports the **real shipped** tenant config
+`src/pages/SalesOrders/.../viewModel/FIELDS/QUAD/approvalActionFields.json` as
+`recordActionFields`, so tests track the actual field / label / guardrail config the app
+ships (not a hand-rolled copy that drifts). Adds synthetic order / approval-stages / PO
+fixtures alongside it. (The QUAD file is reused only as a representative real config — this
+harness is generic test infra, not Quad-specific behavior.)
+
+## What the specs cover
+
+- **`SalesOrderApprovalModalsLayout.cy.tsx`** (component) — the sales-order binding:
+  null-guards, `isApproveButtonEnabled` derivation, and the documented `onSuccess` cache
+  routine asserted via the spied QueryClient.
+- **`RecordApprovalModalLayout.cy.tsx`** (component) — the generic approval modal flow: deny
+  requires a reason (approve optional), submit fires the decision API + `onSuccess`/`onClose`,
+  discard-reason guardrail on Cancel/backdrop, workflow approve-enablement, deep workflow
+  stage editing (deny one stage with a required note → submits only that stage; an empty
+  required note blocks submit), and the **decision-failure path** (500 → modal stays open,
+  `onSuccess`/`onClose` not called).
+- **`EnterPoNumberModal.cy.tsx`** (component) — the PO-number action: create requires a PO#,
+  POST `/purchase-orders/`, credit-card flag `0`/`1`, edit → PUT.
+- **`salesOrderApproval.cy.ts`** (e2e) — full journey: seed auth via
+  `localStorage.accessToken`, row-action menu → Deny → submit, stubbing only the write.
+
+## Conventions for writing tests here
+
+- **Component test of a data-binding component** → use the window-backed hook mock so you
+  never need a real network/tenant config; park state on `window.__<hook>` before `cy.mount`.
+- **Asserting a cache side-effect** (invalidate/remove queries on success) → inject a spied
+  `queryClient` into `cy.mountWithProviders`.
+- **Testing an async error path** → use `cy.on("uncaught:exception", ...)` to swallow the
+  rejected `mutateAsync` so the rejection doesn't fail the spec, then assert the modal stayed
+  open and `onSuccess`/`onClose` were not called.
+- **e2e auth** → seed `localStorage.accessToken`; stub only the write request, let reads hit
+  the configured backend (document any backend prerequisites in the spec).
+- **Keep the component devServer config in sync with `vite.config.ts`** — when the app's
+  Vite aliases or `optimizeDeps` change, mirror the change into `cypress.config.ts` or
+  component mounts break.
+
+## package.json scripts
+
+`cy:open`, `cy:run:ct` (component), `cy:run:e2e`, `test:ct`.
+`.gitignore` excludes `cypress/videos|screenshots|downloads`.
+
+## Gotchas
+
+- **Cypress's bundled Electron cannot launch in the sandboxed macOS dev environment** — it
+  fails the pre-run smoke test (`bad option: --no-sandbox / --smoke-test / --ping`), which
+  blocks **all** specs before any run. The specs in this harness were validated by
+  `tsc -p cypress/tsconfig.json` (0 errors) and `eslint cypress` (clean) but **could not be
+  executed in that sandbox** — run them locally with `npm run cy:run:ct`.
+- **`eslint.config.js` is protected by a config-protection hook.** When a spec/support file
+  trips a lint rule (e.g. `no-explicit-any`), **fix the source to satisfy the linter** (use
+  `unknown` / typed shapes) — do **not** weaken the shared eslint config to make tests pass.
+  The override edit to `eslint.config.js` is blocked by the hook by design.
+- **`@agilant/toga-blox` consumes `dist/`** — same as the app, the harness sees built
+  toga-blox, so a toga-blox source change needs a rebuild before tests observe it.
+
+## Change history
+- 2026-06-30 — Bootstrapped the Cypress harness from scratch (dual component + e2e config,
+  `cy.mountWithProviders`, window-backed hook-mock pattern, shared fixtures off the real
+  QUAD `approvalActionFields.json`) and added the first specs for the Sales Order approval
+  modal flow. Documented the sandbox-Electron blocker and the protected-eslint decision.
+  (apeterson)

package/knowledge/INDEX.md

@@ -28,7 +28,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 7 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 7 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 8 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 
 ## standalone framework

package/knowledge/clients/compass-canada/profile.md

@@ -5,6 +5,7 @@ apps:
   - _underscore
   - api2
   - toga2-supply
+  - toga25-supply
   - toga2-commerce
   - worker
   - worker2

package/knowledge/clients/compass-usa/profile.md

@@ -5,6 +5,7 @@ apps:
   - _underscore
   - api2
   - toga2-supply
+  - toga25-supply
   - toga2-commerce
   - worker
   - dbchanges2

package/knowledge/clients/quad/profile.md

@@ -5,6 +5,7 @@ apps:
   - _underscore
   - api2
   - toga2-supply
+  - toga25-supply
   - toga2-commerce
   - worker2
   - dbchanges2
@@ -12,7 +13,7 @@ project: _Underscore
 client: quad
 type: profile
 status: active
-updated: 2026-06-26
+updated: 2026-06-30
 owners: ["jcardinal", "bala"]
 files: []
 related:

package/package.json

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