toga-ai 1.0.579 → 1.0.580

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
+updated: 2026-08-14
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Core/Surface.php
@@ -322,6 +322,18 @@ Core record grants + their logic-group expressions all evaluate `all`/`"1"`. The
 
 ## Gotchas
 
+- **An empty bundle (`{surface:null, elements:[], vocabularies:{}, messages:{}, theme:{}}`) means the
+  Core.Surfaces row for that slug isn't seeded — NOT an ACL denial and NOT a client/scoping mismatch.**
+  `_buildBundle()` (`Surface.php` ~L516-532) sets `surface=null` and short-circuits when `$surface->load()`
+  fails (`metaGroup` ~L191 calls `resolve` ~L50 per slug). The lookup is **SLUG-ONLY** — it does NOT
+  filter by `appId`, `isVisible`, client, role, persona, or language, and `Surfaces` is a Core/shared
+  (not client-partitioned) table. Consequences when diagnosing an empty/blank surface: (a) a null surface
+  is **not** an ACL denial (that returns **403 EZ-1**, not a 200 with a null bundle) and **not** a
+  client/scoping mismatch (those only filter *overrides* on an already-found surface); it **always** means
+  the `Core.Surfaces` row for that slug isn't seeded **in that environment**; (b) `isVisible=0` does NOT
+  hide a surface at this layer. Verify with `SELECT slug FROM Core.Surfaces WHERE slug LIKE '...'`. (For
+  the FE-side crash when a summary surface IS seeded but its action siblings are NOT, see the partial-seed
+  gotcha in [surface-frontend](../../toga25-supply/features/surface-frontend.md).)
 - **Per-client surface message overrides silently never apply when `languageId` resolves to `0`.**
   `_Model_Core_Surface::_loadMessages` overlays `Core.Messages.defaultValue` with
   `Client_<X>.MessageTranslations` rows **only when `languageId > 0`**. The JWT carries the language as
@@ -420,6 +432,12 @@ Core record grants + their logic-group expressions all evaluate `all`/`"1"`. The
   match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-08-14 — **Discovered/documented** why a surface meta request returns an empty bundle
+  (`surface:null`, empty elements/vocabularies/messages/theme): `_buildBundle()` short-circuits when the
+  slug-only `Surfaces` load fails, and the lookup filters by slug ONLY (no appId/isVisible/client/role/
+  persona/language; `Surfaces` is Core/shared). So a null bundle always = the `Core.Surfaces` row for
+  that slug isn't seeded in that environment — it is NOT a 403 ACL denial and NOT a client/scoping
+  mismatch, and `isVisible=0` does not hide a surface at this layer. Added as a gotcha. (apeterson)
 - 2026-07-21 — Recorded **Option B**: the Approve step-two/PO gate is now evaluated **live on the FE**
   (FE `evaluateSurfaceRule` gained a `SURFACE_NAMED_RULES` escape hatch) rather than via the no-op
   backend Tier-2 — an intentional deviation from the frozen-grammar/escalate note (updated the

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

@@ -10,6 +10,6 @@
 | [Force Logout on Deployment (useDeploymentGuard)](features/force-logout-on-deployment.md) | On large deployments the backend bumps the Core parameter `META_LAST_REFRESH_DATETIME`. | toga25-supply/src/hooks/useDeploymentGuard.tsx, toga25-supply/src/App.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/GenericNestedTables.tsx, toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json, toga25-supply/src/hooks/useTableCellInteractions.ts, toga25-supply/src/hooks/useServerTableUrlState.ts |
-| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
+| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

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

@@ -6,9 +6,10 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-05
+updated: 2026-08-14
 owners: [jcardinal, apeterson]
 files:
+  - toga25-supply/src/surface/applyColSpan.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx
@@ -458,6 +459,29 @@ machinery for "this box is two columns wide", which is exactly the signal that i
 FE. Use this as the config/logic line for surface geometry questions: **presentation geometry →
 FE/CSS; content/visibility/order/ACL → Surface.**
 
+#### Where per-field `colSpan` lives in the FE (CTO-reviewed, AGREE 2026-08-14)
+Once colSpan is actually assigned FE-side, the durable rule is: **span VALUES stay per-consumer/adapter,
+keyed by `valueKey` only — do NOT centralize colSpan as a universal per-element value, and do NOT store
+it as SurfaceElement DB metadata (both rejected).** The reasoning is that colSpan is inherently
+**(field × grid)-scoped**: a span number only means something relative to a *specific* grid's column
+count, and the SAME surface element (e.g. `valueKey "reasonForRequest"`) is rendered by multiple
+consumers into different grids — the SalesOrders modal `.approvalFieldsGrid` is 2-col, while
+`RecordApprovalModal`'s `.approvalDetailsGrid` / `.approvalWorkflowDetailsGrid` differ. Storing one
+per-element span is therefore semantically impossible across differing column counts (and violates the
+"layout is FE presentation, not surface metadata" boundary above).
+- Each adapter renders into exactly one grid, so **the adapter IS the grid scope** — no surface-slug
+  layer is introduced (slug ≠ grid). Value tables stay **local to each adapter**
+  (`surfaceBundleToTenantFields.ts`, `surfaceBundlesToDecisionFields.ts`).
+- Share ONLY the trivial assignment plumbing: **`applyColSpan(field, span)`** helper in `@/surface`
+  (`src/surface/applyColSpan.ts`, exported from `src/surface/index.ts`). `BaseDetailField` (in
+  `@agilant/toga-blox`) reads `field.colSpan` → CSS var `--field-col-span`; it is grid-agnostic.
+- This deliberately prevents a future "consolidate the span maps into one" regression (which would be a
+  bug generator).
+- **Caveat (in code):** the decision adapter feeds BOTH the single-action and workflow grids from the
+  same field array (`overlayDecisionSurfaceFields` points `orderContentDetails` and
+  `orderContentDetailsWorkflow` at one array), so those two grids currently **share one span value**;
+  splitting them requires two arrays.
+
 ## Gotchas
 
 - **A named predicate that FAILS OPEN silently enables a button when its data isn't fetched.**
@@ -548,6 +572,17 @@ FE/CSS; content/visibility/order/ACL → Surface.**
   `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.)
+- **A PARTIAL decision-surface seed CRASHES the approval modal (a TOTAL miss falls back cleanly).**
+  The SalesOrders approve/deny decision modal gates on the **SUMMARY surface only**
+  (`isDecisionSurfaceEnabled` = the summary bundle has any visible element). If the summary surface
+  (dbchanges2 seed `Core/2026-07-21a`) is seeded but the approve/deny **ACTION** surfaces
+  (`Core/2026-07-21b`) are NOT, the gate flips `true` while the action bundles are empty →
+  `buildActionChrome` yields an undefined icon/label → runtime crash `"Cannot read properties of
+  undefined (reading 'charAt')"` (undefined Font Awesome icon), then `reading 'label'`. A **total**
+  seed miss falls back cleanly to JSON; a **partial** miss crashes. Fix = ensure the whole
+  `2026-07-21a`+`b` seed set ran in that environment. (Both seeds are additive + `NOT EXISTS`-guarded
+  and inherit `appId`/`recordId` from the existing `order-details` sibling surface — so if
+  `order-details` isn't seeded the surface INSERT silently inserts nothing.)
 - **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`
@@ -571,6 +606,19 @@ FE/CSS; content/visibility/order/ACL → Surface.**
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-08-14 — **DECIDED (CTO-reviewed, AGREE)** where per-field grid `colSpan` lives in the FE Surface
+  layer: span VALUES stay per-consumer/adapter keyed by `valueKey` (the adapter IS the grid scope, since
+  each adapter renders into exactly one grid), NOT centralized as a universal per-element value and NOT
+  stored as SurfaceElement DB metadata (both rejected — colSpan is (field × grid)-scoped, and the same
+  element reuses across grids of differing column counts). Shared only the trivial `applyColSpan(field,
+  span)` plumbing in `@/surface` (`src/surface/applyColSpan.ts`); `BaseDetailField` reads
+  `field.colSpan`→`--field-col-span`. Prevents a future "consolidate the span maps" regression. Caveat:
+  the decision adapter feeds both the single-action and workflow grids from one field array
+  (`overlayDecisionSurfaceFields`), so they currently share one span value until split into two arrays.
+  Also documented a FE gotcha: a **PARTIAL** decision-surface seed (summary `2026-07-21a` seeded but
+  action `2026-07-21b` not) flips `isDecisionSurfaceEnabled` true with empty action bundles →
+  `buildActionChrome` crash (`charAt`/`label` of undefined); a total miss falls back cleanly to JSON.
+  (apeterson)
 - 2026-08-05 — **Built/Fixed** staged approval-chain value resolution on the record-modal
   **approval-details** card. Ported the decision adapter's staged resolver (`resolvePathInsensitive`
   + `makePreferredStageResolver`) into `surfaceBundleToTenantFields.ts`: a surface `config.preferredStage`

package/package.json

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