toga-ai 1.0.229 → 1.0.231

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

@@ -46,7 +46,11 @@ feature flag — see below). Backend: [surface-resolver](../../_underscore/featu
 - **`useFetchSurfaceMeta`** — the single fetch-once/React-Query-cached choke point for a surface's
   meta. Loading a different *record* into the same surface reuses cached meta. Builds the URL as
   `/surfaces/meta?slug=...` (query string), **not** `/surfaces/<slug>/meta` (the path form makes the
-  engine parse the slug as a record uuid → 404 EV-6).
+  engine parse the slug as a record uuid → 404 EV-6). Unwraps the bundle via **`extractBundle()`**,
+  which locates the bundle by its **structural fingerprint** (the `elements` array) across
+  `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.
 - **`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
@@ -66,13 +70,14 @@ legacy pre-Surface fallback branches at the wired screens removed). Legacy per-s
 
 ## What's wired
 
-Login + sales-orders list + the sales-order modal + the **Items LIST** screen. The SalesOrder action
+Login + sales-orders list + the sales-order modal + the **Items**, **VendorItems**, and
+**Inventory** LIST screens. The SalesOrder action
 bar reproduces `orderViewFields.json` approve/deny/approvalWorkflow/viewLog/editOrder by delegating
 to the existing `onActionClick`/`onOpenLog` handlers. TABLE-type surfaces stay on the existing
 TableView pipeline via `tableViewSlug` (see [meta-driven-table-data](meta-driven-table-data.md)) —
 the Surface layer references the TableView, never replaces it.
 
-## Per-screen migration recipe (proven on SalesOrders + Items)
+## Per-screen migration recipe (proven on SalesOrders + Items + VendorItems + Inventory)
 
 The screen-by-screen full-app refactor follows one recipe:
 1. Seed the screen's surface(s) in a `Core/*SurfaceSeed.sql` — a TABLE surface that references the
@@ -87,8 +92,51 @@ Keep TABLE rendering on the existing TableView pipeline; only the chrome (action
 moves to Surface. A screen with no client/role/lang variance ships a single DEFAULT bundle (no
 Client overrides), as Items did.
 
+**VendorItems (screen 2)** followed the recipe exactly: `vendor-items-list` (TABLE → TableView 10,
+recordId 19) + `vendor-items-list-actions` (Refresh / Columns[hidden+disabled] / New Vendor Item),
+page+view-model rewired to resolve title+buttons from the bundle, dropped the
+`useClientFields`/`vendorItemsPageFields` dependency, deleted `vendorItemsPageFields.json` + its
+`fieldsConfig/index.ts` entry.
+
+**Inventory (screen 3) — presentation-only, by decision.** Only the page title, header buttons
+(Group by / Refresh), the Group-by modal copy, and the entity icon/color tag map moved to Surface.
+The `inventoryGroupings` `groupings[].levels[]` topology
+(`fetchSlug`/`role`/`additionalDataSlug`/`urlParamKey` driving `GenericNestedTables`) is **data-fetch
+wiring, not presentation**, so per the config/logic boundary it **stays as JSON**. The
+`inventory-list` surface carries `groupByLabels` + `entityTags` in its surface `config`, with
+**recordId+tableViewId NULL** (the page has no single backing Record — it composes
+purchase-orders/items/units via per-level fetchSlugs). Labels + `entityTags` were stripped from both
+DEFAULT and NYCHH `inventoryGroupings.json` (groupings kept) and marked `@deprecated`/optional in the
+`InventoryGroupingsConfig` type.
+
+**The config/logic line for migration:** move presentation (titles, button labels, icons, colors,
+modal copy, visibility/enable) to Surface; **leave data-fetch wiring (fetch slugs, roles, URL params,
+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.**
+
 ## Gotchas
 
+- **Scripted-API GET return values land under `data.<scriptRoute>`, not `data` directly.** V2 nests a
+  scripted-API return value inside the envelope under a route-keyed slot of `data` (e.g. `data.meta`,
+  `data.surfaces`), one level deeper than a normal data fetch. The bundle hook unwraps this with
+  `extractBundle()` by structural fingerprint (the `elements` array). Consumers (`SurfaceSection`,
+  `SurfaceActionBar`) are hardened to bail to `null` unless `elements` is a real array, so a malformed
+  payload never crashes the page. (Root cause of the "s.elements is not iterable" runtime crash.)
 - **No feature flag, no fallback.** Surface is the enforced path; a missing/broken surface bundle
   does not silently fall back to legacy JSON — that path is deleted per screen as it migrates.
 - **Endpoint is query-string form** — `GET /v2/surfaces/meta?slug=...`, not `/surfaces/<slug>/meta`
@@ -99,6 +147,13 @@ Client overrides), as Items did.
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 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
+  its `elements`-array fingerprint across `raw`/`raw.data`/`raw.data.<route-key>` (V2 nests
+  scripted-API returns under `data.<scriptRoute>`), with an empty-bundle fallback + hardened
+  SurfaceSection/SurfaceActionBar guards. Recorded SalesOrders detail as deferred bespoke
+  (registered-renderer + lease logic + approval-modal) work. (jcardinal)
 - 2026-06-29 — DECISION: Surface is now enforced, not flagged — removed `VITE_SURFACE_ENABLED`/
   `SURFACE_ENABLED` (deleted `featureFlag.ts` + all gating/legacy-fallback branches). Fixed
   `useFetchSurfaceMeta` to the query-string endpoint `/surfaces/meta?slug=` (path form 404'd EV-6).

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 17 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 21 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 22 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

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.229",
+  "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",