toga-ai 1.0.241 → 1.0.243

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,5 +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/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/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/knowledge/sessions/2026-06-30-surface-layer-jcardinal.md

@@ -0,0 +1,74 @@
+---
+type: session
+slug: surface-layer
+title: Surface grouped-meta + SalesOrders section migration (Compass/CompassCanada/Quad)
+author: jcardinal
+repos: [_underscore, dbchanges2, toga25-supply]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-06-30
+updated: 2026-06-30
+---
+
+# Session: surface-layer
+**Date:** 2026-06-30
+**Project/Repo:** _underscore / dbchanges2 / toga25-supply (2.0)
+**Task:** Build a grouped surface-meta resolver and migrate the toga25-supply SalesOrders record-modal sections onto the Surface UI presentation layer for the seeded clients (Compass, CompassCanada, Quad), keeping non-migrated clients on JSON.
+
+---
+
+## What WORKED
+- **`metaGroup` grouped resolver** — `_Model_Core_Surface::metaGroup(&$api, string $slugs): object` at `GET /v2/surfaces/meta-group?slugs=a,b,c`. Splits/dedupes the slug list (cap `META_GROUP_MAX_SLUGS=25`, logs truncation), calls the existing `resolve()` per slug (shares its per-slug file cache), returns `{group, surfaces:{slug=>bundle|null}}`. `php -l` clean. Verified live on dev-sandbox (200 after the ACL grant).
+- **Resolver message-resolution fixes** (`Surface.php` `_buildBundle`/`_resolveElement`): remap element message slots id→messageKey before return (labels previously fell back to the element key); collect `disabledTooltipMessageId` + emit `disabledTooltip`; set `surface.titleMessageKey`; merge the 2nd `_loadMessages` return into `$messageKeyById`; log dangling message ids; `resolve()` now `: object`. These were latent because SECTION/BUTTON_BAR rendering was never shipped.
+- **FE grouped fetch + adapter**: `useFetchSurfaceMetaGroup(slugs[])` (order-insensitive key, staleTime Infinity, `extractGroup` by `{surfaces}` fingerprint) and `surfaceBundleToTenantFields()` adapter → existing `TenantFields` shape, so `SalesOrderSummaryGrid` renderers + `getDetailSections` are untouched.
+- **Migrated-client roster gate**: `SALES_ORDER_SURFACE_MIGRATED_CLIENTS=[COMPASS,COMPASSCANADA,QUAD]` in the view-model; only roster clients fetch+resolve Surface sections (merge = JSON-base + Surface-wins), everyone else stays JSON.
+- **DB seeds (applied on dev-sandbox, working)**: Core `2026-06-30a` (meta-group RecordScript + `order-recurring` surface + 5 display-toggle marker surfaces); Client `2026-06-30a` meta-group AclRecordScripts grant; Compass/CompassCanada/Quad `2026-06-30a` SurfaceOverrides for section deltas.
+- **403 EZ-1 on meta-group fixed** by applying the Client AclRecordScripts dispatch grant per client DB. Verified via toga-db: `meta` script id 25 → roles 1,3,4; `meta-group` id 27 had no grant until applied.
+- **JSON cleanup**: removed the migrated section blocks from COMPASS/COMPASSCANADA/QUAD `orderViewFields.json` (kept salesOrderDetailsConfig/itemFulfillmentClickRule/recordActionFields/recordApprovals). DEFAULT left intact.
+- **/capture PUSHED** — 4 surface feature docs + 3 client profiles updated on team `_main` (commits f732160 + fc8de41).
+
+## What did NOT work — DO NOT RETRY THESE
+- **Client-DB seeds resolving Core ids via cross-DB subselect** (`Core.RecordScripts`/`Core.Surfaces`/`Core.SurfaceElements` from a `Client_*` file). Works on the dev-sandbox all-in-one instance but **WILL FAIL in production** — Core is a separate MySQL cluster there, and cross-DB queries require one instance. This is the current id-agnostic approach in all 4 Client seeds; it is the prod blocker (see Blockers).
+- **Parent `parentSurfaceId` GROUP-row design for grouped meta** — rejected by CTO review: adds Core schema state + a new TYPE, must be seeded per-client per-env for a grouping the FE already knows statically, and reintroduces id drift. The slug-list `metaGroup` is schema-stateless.
+- **Surface-only cutover for all clients** (no roster gate) — would regress non-seeded clients (NYCHH/Prudential/SPGlobal/DEFAULT) because the Core section surfaces are SHARED and seeded from Compass's shape; they'd inherit it.
+- **Overriding a section's visibility via the Surface row's own `isVisible`** — the resolver cascade (`_loadOverrides`) only overrides ELEMENTS, never a surface's `isVisible`. Hence each display-toggle surface carries one `sectionVisibility` marker element that the overrides target.
+- **Removing MANAGER/Quad summary shipping/tax tooltips via override** — `_castOverride` treats `TOOLTIP_MESSAGE` as numeric-only, so it can't null a tooltip. Cosmetic; deferred.
+- **Seeding `elementType` for Quad** — confirmed dead config (no `.ts/.tsx` reads it); needs no migration.
+
+## Not tried yet (candidates for next session)
+- **Prod cross-cluster seed fix** (the on-hold blocker): rewrite the 4 Client seeds to hardcode Core ids as literals + resolve `roleId` by name (per `Client/2026-06-23b - ItemTranslationsAcl.sql`), zero `Core.` refs. User chose "I'll give you the prod ids" — apply the Core seed to prod Core, run the lookup query (in session memory / below) to get literal recordScriptId/surfaceId/surfaceElementId, then bake them in. Also audit the EXISTING `2026-06-25c`/`2026-06-29c`/`2026-06-25d` surface seeds for the same anti-pattern.
+- **Action-bar / approval-modal migration** — still JSON; pulls in the Compass approval state machine + Tier-2 `stepTwoAssigned`. The `sales-order-actions` BUTTON_BAR surface is already seeded but not yet consumed by the FE.
+- **Seed NYCHH / Prudential / SPGlobal** (and add to the roster) once confirmed live on toga25-supply; they need Quad-like client-level overrides to match the DEFAULT shape.
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| _underscore/Model/Core/Surface.php | modified | metaGroup() + message-resolution fixes; php -l clean |
+| dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql | created | meta-group script + order-recurring + 5 display surfaces + markers. Prod-safe (Core→Core). |
+| dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql | created | meta-group dispatch grant. ⚠ cross-DB Core ref — prod fix pending. |
+| dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql | created | MANAGER hide invoices/admin-notes. ⚠ cross-DB. |
+| dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql | created | MANAGER deltas (shippingMethod/invoices/admin-notes), role by name. ⚠ cross-DB. |
+| dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql | created | client-level deltas (costCenter/shippingMethod/recurringTotal + 3 display hides). ⚠ cross-DB. |
+| toga25-supply/src/surface/useFetchSurfaceMeta.ts | modified | added useFetchSurfaceMetaGroup + extractGroup |
+| toga25-supply/src/surface/index.ts | modified | re-export group hook |
+| toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts | created | adapter + slug list + migrated-client roster |
+| toga25-supply/.../SalesOrderRecordModalLayout/helpers/index.ts | modified | re-export adapter + roster |
+| toga25-supply/.../viewModel/useSalesOrderRecordModalLayoutModel.tsx | modified | roster-gated Surface merge |
+| toga25-supply/.../FIELDS/{COMPASS,COMPASSCANADA,QUAD}/orderViewFields.json | modified | section blocks deleted; data-wiring kept |
+
+## Decisions made
+- **Grouped meta = slug-list `metaGroup`, not a parent GROUP row** (CTO AGREE-with-alternative): schema-stateless, reuses resolve()/cache, avoids id drift.
+- **Migrated-client roster gate in code, not an env flag**: protects unseeded/unknown clients from the shared Compass-shaped Core base. Remove a client from the roster only after its seeds are verified; then its JSON sections are safe to delete.
+- **Display sections = field-less SECTION surfaces with one `sectionVisibility` marker element**: only way to express per-role section visibility given the resolver overrides elements, not surface.isVisible.
+- **Data-wiring stays JSON** (salesOrderDetailsConfig, itemFulfillmentClickRule): presentation-only migration, config/logic boundary (Inventory precedent).
+- **Prod-safe Client-seed pattern = literal Core ids + Client-local roleId-by-name** (per ItemTranslationsAcl). Deferred to the prod pass.
+
+## Blockers
+- **PROD CROSS-CLUSTER (on hold, user-paused):** the 4 Client-DB seeds use `Core.*` cross-DB subselects that break against prod's separate Core cluster. Fix recorded in memory [[surface-prod-crossdb-fix-pending]]. Lookup query to get prod literal ids is in the session thread. Dev-sandbox is unaffected (all-in-one) and fully working.
+
+## Exact next step
+> When resuming the prod fix: apply `Core/2026-06-30a` to the prod Core cluster, then run the labeled lookup query against prod Core (returns meta-group recordScriptId + surfaceId/surfaceElementId for order-details/c_erpEntityId, ship-to/shippingMethod.name, order-recurring/isTotal, and the invoices/admin-notes/additional-order-details/notes `sectionVisibility` markers). Paste results, then rewrite the 4 Client `2026-06-30a` seeds to hardcode those Core ids as literals and resolve only `roleId` by name — removing every `Core.` reference — following `dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql`.
+
+---
+_Saved by /session-save on 2026-06-30_

package/package.json

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