toga-ai 1.0.230 → 1.0.231

package/knowledge/sessions/2026-06-29-surface-ui-config-layer-jcardinal.md

@@ -0,0 +1,73 @@
+---
+type: session
+slug: surface-ui-config-layer
+title: Surface UI config layer — deploy fixes + 3 screen migrations
+author: jcardinal
+repos: [dbchanges2, _underscore, api2, toga25-supply]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-06-29
+updated: 2026-06-29
+---
+
+# Session: surface-ui-config-layer
+**Date:** 2026-06-29
+**Project/Repo:** dbchanges2 / _underscore / api2 / toga25-supply (2.0)
+**Task:** Continue the platform-wide "Surface" UI presentation/config layer: fix the deployed layer's 403 + FE crash on dev.sandbox, then refactor toga25-supply screens onto Surface (Items done prior; VendorItems + Inventory this session; SalesOrders remaining).
+
+---
+
+## What WORKED
+- **403 (EZ-1) on `GET /v2/surfaces/meta` fixed.** Root cause found by reading V2.php `getRecordScriptPhpMethod` (~line 5803): RecordScript dispatch is authorized by the **Client-DB `AclRecordScripts`** table (`WHERE recordScriptId=? AND roleId IN(...)`), NOT `AclRecordPermissions`. Confirmed on dev.sandbox: surfaces meta script (id 25) had ZERO `AclRecordScripts` rows, while working TableView/Page `meta` scripts (ids 1,2) grant roles 1,3,4. Fix file `dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql` grants meta→{1,3,4}, debug→{3}; id-agnostic (route-join, works on 333 or 2300), NOT EXISTS-guarded. Developer applied it on dev.sandbox → 403 cleared.
+- **Latent fatal fixed** — `dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql`: idempotent UPDATE renaming surfaces `debug` RecordScript phpMethod `debug`→`metaDebug` on pre-rename envs.
+- **FE "s.elements is not iterable" crash fixed.** Root cause: V2 nests a scripted-API return under a route-keyed slot of `data` (e.g. `data.meta`/`data.surfaces`), one level deeper than the hook unwrapped. `useFetchSurfaceMeta.ts` `extractBundle()` now finds the bundle by structural fingerprint (the `elements` array) across `raw`/`raw.data`/`raw.data.<key>`, with empty-elements fallback. Hardened `SurfaceSection.tsx` + `SurfaceActionBar.tsx` to bail to null unless `elements` is a real array.
+- **VendorItems screen migrated** (screen 2/5). Seed `dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql` (vendor-items-list TABLE→TableView 10, vendor-items-list-actions BUTTON_BAR). FE rewired to bundle; legacy `vendorItemsPageFields.json` deleted + removed from fieldsConfig registry. Mirrors the prior Items migration exactly.
+- **Inventory screen migrated presentation-only** (screen 3/5). Seed `dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql` (inventory-list TABLE recordId/tableViewId NULL, carries groupByLabels+entityTags in config; inventory-list-actions BUTTON_BAR; Actions anchored to items(21)). FE sources title/buttons/entityTags/groupByLabels from the surface; grouping topology stays in JSON.
+- **/capture PUSHED** — 4 surface feature docs updated on team `_main`.
+
+## What did NOT work — DO NOT RETRY THESE
+- **Granting only `AclRecordPermissions` (record-level READ) does NOT authorize a RecordScript call.** The earlier fix `dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql` granted Public(1) READ (perm 313, complete logic chain) and the 403 PERSISTED — because dispatch checks `AclRecordScripts`, a different table. Record perms are necessary but NOT sufficient. Do not re-investigate the AclRecordPermissions chain for script 403s.
+- **Unwrapping only `raw.data` in the meta hook** left the FE reading `.elements` on the `{meta:{...}}` wrapper → "not iterable". Hard-coding a single nesting key (`data.meta` vs `data.surfaces`) is brittle — the structural-fingerprint extractor is the right approach.
+- **Swapping `SurfaceSection` into `SalesOrderSummaryGrid` would DESTROY bespoke rendering.** The grid renders via blox `DetailSection`/`OrderSectionCard`/`BaseTotals` (the last with client recurring-lease logic `_totalLease!==0`). Generic label/value `SurfaceSection` cannot represent totals or location cards. Do not attempt a generic-section swap there.
+
+## Not tried yet (candidates for next session)
+- **SalesOrders detail sections via a REGISTERED-RENDERER approach**: map surface element `config.kind` → bespoke component (detailSection→DetailSection, locationCard→OrderSectionCard, totalsCard→BaseTotals), keeping the recurring-lease logic in code/_underscore. Reconcile the early-seeded order-details/ship-to/bill-to/order-summary SECTION surfaces with the grid's actual client-keyed, data-driven section model (they don't currently map cleanly).
+- **add-notes (adminNotes) migration** — `getDetailSections.tsx` + `AdminNotesSection`; currently gated by `tenantFields[key].isVisible`. Move the section visibility gating to Surface while keeping the bespoke component.
+- **Compass approval modals** (`SalesOrderApprovalModalsLayout`) — the plan's explicitly-deferred bespoke surface; needs the blessed-component registry + `_underscore` capability methods, not generic config.
+- **Confirm BLANK_CLIENT_DATABASE provisioning** carries the `AclRecordScripts` grants for surface scripts (else a newly-provisioned client repeats the 403). Determine whether BLANK is a snapshot or replays dated migrations.
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql | created | The 403 fix; applied on dev.sandbox. Fan out to other client DBs + BLANK. |
+| dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql | created | debug→metaDebug phpMethod fix for pre-rename envs. |
+| dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql | created | VendorItems surface seed. |
+| dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql | created | Inventory presentation-only seed. |
+| toga25-supply/src/surface/useFetchSurfaceMeta.ts | modified | extractBundle() structural-fingerprint unwrap. |
+| toga25-supply/src/surface/SurfaceSection.tsx | modified | Array.isArray(elements) guard. |
+| toga25-supply/src/surface/SurfaceActionBar.tsx | modified | Array.isArray(elements) guard. |
+| toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx | modified | Title + button bar from bundle. |
+| toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx | modified | Dropped useClientFields/vendorItemsPageFields; in-memory columnsButton default. |
+| toga25-supply/src/pages/VendorItems/viewModel/FIELDS/DEFAULT/vendorItemsPageFields.json | deleted | Migrated to Surface. |
+| toga25-supply/src/fieldsConfig/index.ts | modified | Removed vendorItemsPageFields (import/type/Omit/const/2 injections). |
+| toga25-supply/src/pages/Inventory/Inventory.tsx | modified | Title + Refresh/GroupBy icon+label from bundle. |
+| toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx | modified | entityTags/groupByLabels/title/buttons from surface; groupings still from JSON. |
+| toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts | modified | entityTags/labels @deprecated optional on InventoryGroupingsConfig. |
+| toga25-supply/.../Inventory/.../DEFAULT/inventoryGroupings.json | modified | Stripped labels+entityTags; groupings only. |
+| toga25-supply/.../Inventory/.../NYCHH/inventoryGroupings.json | modified | Same strip (file is byte-identical to DEFAULT). |
+
+## Decisions made
+- **Inventory = presentation-only migration** (developer-approved). The `groupings[].levels[]` topology (fetchSlug/role/additionalDataSlug/urlParamKey) is data-fetch wiring → stays JSON; only title/buttons/modal-copy/entityTags moved to Surface. Rejected: migrating the whole groupings blob into surface config (would erode the config/logic boundary — the plan's #1 risk).
+- **SalesOrders deferred to a design-first session** (developer chose to stop here after the bespoke nature was discovered). Rejected: rushing a generic-section swap on this expensive thread (would destroy bespoke totals/location rendering and produce unverifiable output).
+- **Surface RecordScripts must be granted in `AclRecordScripts` (Client DB) per role** — this is the canonical dispatch-authorization mechanism; encode it in every surface ACL seed and in BLANK.
+
+## Blockers
+- **Cannot run `tsc`/build locally** — private `@agilant/toga-blox` registry needs auth (npm E401); FE changes verified by reading, built/deployed by the developer on dev.sandbox.
+- **File-vs-DB id drift** — seed files use renumbered ids (surfaces record 333), but dev.sandbox holds the originally-provisioned ids (2300). All fixes were made id-agnostic (match by route) to span both. Not blocking, but keep using route-based lookups.
+
+## Exact next step
+> In a fresh session: open `toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx` and design a **registered-renderer** that maps a surface element's `config.kind` (detailSection / locationCard / totalsCard) to its existing bespoke component (DetailSection / OrderSectionCard / BaseTotals), sourcing section title + visibility + field bindings from the `order-details`/`ship-to`/`bill-to`/`order-summary` surface bundles while keeping the recurring-lease logic in code. First reconcile those 4 seeded surfaces against the grid's actual client-keyed section model (query their SurfaceElements: order-details=4, ship-to=2, bill-to=1, order-summary=4).
+
+---
+_Saved by /session-save on 2026-06-29_

package/package.json

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