toga-ai 1.0.321 → 1.0.322

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

@@ -2,6 +2,7 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
+| [Proposed — git-sourced base+overlay JSON authoring for the Surface layer](architecture/surface-authoring-proposal.md) | A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model move off hand-authored SQL against the `SurfaceOverrides` E | _underscore/Model/Core/Surface.php, _underscore/Model/Client/SurfaceOverride.php |
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql |
 | [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php |

package/knowledge/2.0/apps/_underscore/architecture/surface-authoring-proposal.md

@@ -0,0 +1,67 @@
+---
+title: Proposed — git-sourced base+overlay JSON authoring for the Surface layer
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: architecture
+status: draft
+updated: 2026-07-13
+owners: [apeterson]
+files:
+  - _underscore/Model/Core/Surface.php
+  - _underscore/Model/Client/SurfaceOverride.php
+related:
+  - ../features/surface-resolver.md
+---
+
+## Summary
+
+A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model
+move off hand-authored SQL against the `SurfaceOverrides` EAV table onto **git-sourced JSON**: a full
+neutral `_base/<surface>.json` per surface plus partial per-client overlay files holding only diffs,
+merged by the resolver at read time. The runtime resolver is kept for the dynamic parts (per-record
+Tier-2 evaluation + ACL element-drop). This doc records the motivation, the design, and interim
+guardrails so the lead dev can decide.
+
+**Critical rules:** This is a **proposal, status: draft — nothing here is implemented.** Do not treat
+any of it as the current system. The live authoring path is still hand-written SQL against
+`SurfaceOverrides`; if you stay on it, apply the interim guardrails below (unique index, strict SQL
+mode, autocommit on, idempotent migrations) or you will hit the silent EAV failure modes.
+
+## Problem
+
+Surface config is authored as hand-written SQL against the `SurfaceOverrides` EAV table. This has:
+- **No git diff / review / rollback** — config changes bypass code review and CI.
+- **No team-merge story** — concurrent work on a shared surface collides with no merge tooling.
+- **Silent DB failure modes** — ENUM coercion of unknown values to `''` (non-strict mode), a missing
+  unique constraint letting duplicate override rows pile up, and autocommit-off swallowing writes.
+
+Cost signal: 2 of ~17 surfaces took ~5 days.
+
+## Recommendation
+
+**Source of truth = git.** For each surface author a full neutral `_base/<surface>.json`, plus partial
+per-client overlay files holding **only diffs**, merged by the resolver at read time. Keep the
+resolver for the dynamic parts it must still compute (per-record Tier-2 evaluation + ACL
+element-drop — see [surface-resolver](../features/surface-resolver.md)).
+
+**Framing: "source of truth = git; read substrate = a choice."** Three read substrates, in order of
+preference:
+1. Read the JSON files directly at read time.
+2. Seed the JSON documents into a DB column at deploy (git still authors; DB is a materialized cache).
+3. (Avoid) DB-as-master authored by hand — the status quo.
+
+## Optional future — bounded live toggles
+
+An admin UI (a screen + a validating API endpoint + an `admin_flags` DB table) that writes a
+**bounded, whitelisted** set of per-client feature toggles, merged at **highest precedence**. This
+gives live no-deploy toggles without undermining git-as-truth, because the whitelist bounds what can
+be changed outside git.
+
+## Interim guardrails (if staying on SQL/EAV)
+
+- Unique index on `SurfaceOverrides(surfaceElementId, attribute, roleId, personaId, languageId)`.
+- Strict SQL mode (so unknown ENUM values error instead of coercing to `''`).
+- Autocommit on.
+- Idempotent, re-runnable migrations.

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-01
+updated: 2026-07-13
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Core/Surface.php
@@ -137,6 +137,70 @@ breaks logic.
   `_Model_<Client>_*` overrides + `Client_ApiPayloadInterceptor` hooks — the Surface layer does
   **not** absorb business logic.
 
+## Per-client override of the Tier-1 gating RULES (not just static flags)
+
+Originally only static flags (`isVisible`/`isEnabled`) and `config` were per-client overridable
+via `SurfaceOverrides`; the **Tier-1 gating rules** (`visibilityRule`/`enabledRule`) were frozen on
+the Core element. That meant two-stage-approval clients could not be expressed as data — they needed
+per-client PHP. Two new override attributes make the declarative rules per-client overridable so the
+two-stage behavior is **pure data**:
+
+- `_Model_Client_SurfaceOverride` now declares `ATTRIBUTE__VISIBILITY_RULE` and
+  `ATTRIBUTE__ENABLED_RULE` constants.
+- In `Surface.php` `_resolveElement`, the resolver decodes and applies both attributes: the locals
+  are seeded from the Core element's own `visibilityRule`/`enabledRule`, then overridden by any client
+  override row. `_castOverride` decodes them as JSON alongside `CONFIG`.
+
+> **⚠ LOCAL only (as of 2026-07-13).** The `_underscore` code change **and** the ENUM migration below
+> must ship together to beta/prod on promotion. php-reviewer pass + a PHPUnit regression test for the
+> rule-override path are still outstanding.
+
+**Mandatory ENUM migration (ships with the code).** Each client schema's
+`SurfaceOverrides.attribute` ENUM must be widened *before* any rule-override row is inserted:
+`ALTER TABLE Client_*.SurfaceOverrides MODIFY attribute ENUM(...,'VISIBILITY_RULE','ENABLED_RULE') NOT NULL`
+across all 32 `Client_*` schemas. In **non-strict SQL mode** an insert of an unknown ENUM value
+**silently coerces to `''`** — which makes the resolver ignore the rows and `NOT EXISTS` guards never
+match (duplicate rows pile up). Widen the ENUM first, always.
+
+### Override semantics: REPLACE, not deep-merge
+A `CONFIG` (and now `VISIBILITY_RULE`/`ENABLED_RULE`) override **replaces the whole decoded object**
+— it does **not** deep-merge (`Surface.php` ~line 818). So a `CONFIG` override value must carry the
+**full** config (e.g. `role` + `filterKey` + `additionalData`), not just the changed key.
+
+### Two separate gating mechanisms on the sales-order listing (do not conflate)
+- The **Approvals FILTER** on the sales-order listing is driven by `config.additionalData._status`.
+- The **per-button record actions** are gated by `visibilityRule`/`enabledRule`.
+These are separate mechanisms on separate surfaces; a filter change is a `CONFIG` override, a
+button-gating change is a rule override.
+
+## Core re-baselined to a neutral default + per-client diffs (decision, 2026-07-13)
+
+Core was effectively "Client Zero = Compass", not a neutral default, so every client inherited
+Compass's shape. Core was re-baselined as a true shared default so clients store **only diffs**:
+
+1. The approvals gate is governed by the **`navigation-approvals` ACL grant**, not per-tenant
+   `IS_VISIBLE` overrides.
+2. Default approvals filter = `pendingApproval` only (single-stage).
+3. No Tier-2 `config.tier2` caveat baked into Core.
+4. Edit-in-Commerce only for Compass / CompassCanada.
+5. Columns button hidden by default.
+
+Per-client diffs layered on top:
+- **Quad** — Approve + Deny only; filter narrowed to `pendingApproval`; filter button visible.
+- **Compass USA / Compass Canada** — two-stage approvals: record-action `visibilityRule`/`enabledRule`
+  = `in [pendingApproval, pendingInitialApproval]`. **Compass Canada** additionally gets a `CONFIG`
+  override on the approvals filter button (surface `sales-order-listing-actions`) to add
+  `pendingInitialApproval`.
+
+> ⚠ **Regression left open:** the Compass / CompassCanada **non-rule** overrides (Edit-in-Commerce
+> flags, role-8 Manager hides) were **wiped during the rebuilds and not re-added**. The two-stage rule
+> overrides are also LOCAL only (see above).
+
+### Operational gotcha — raw SQL bypasses the cache-bust
+Raw SQL against the surface tables bypasses the model-layer cache-bust, so the on-disk bundle cache
+at `~/toga/cache/surface_meta/*.json` **must be cleared manually** after any raw-SQL surface edit.
+(Cache confusion earlier was a local-setup artifact, not an inherent design issue.)
+
 ## How a surfaces scripted-API call is authorized (route-level gate)
 
 Authorizing a surfaces script (`meta`, `meta-group`, `debug`) is a **two-layer** check. Get the
@@ -234,6 +298,17 @@ 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-07-13 — Made the Tier-1 gating RULES per-client overridable: added
+  `ATTRIBUTE__VISIBILITY_RULE`/`ATTRIBUTE__ENABLED_RULE` to `_Model_Client_SurfaceOverride`;
+  `_resolveElement` seeds locals from the Core element's rules then applies overrides;
+  `_castOverride` decodes them as JSON — so two-stage approvals are pure data, not per-client PHP.
+  Requires widening `Client_*.SurfaceOverrides.attribute` ENUM (32 schemas) first (non-strict mode
+  silently coerces unknown ENUM → `''`). Documented override REPLACE-not-merge semantics, the
+  filter (`config.additionalData._status`) vs button-rule split, the raw-SQL cache-bust bypass
+  (`~/toga/cache/surface_meta/*.json`), and the Core neutral-default re-baseline (ACL-gated
+  approvals, single-stage default, per-client diffs: Quad = Approve+Deny, Compass/CC = two-stage).
+  ⚠ Code + ENUM migration are LOCAL only; non-rule Compass/CC overrides wiped in rebuild not yet
+  re-added; php-reviewer + regression test outstanding. (apeterson)
 - 2026-07-01 — Clarified vocabulary/label per-client relabeling (new section): Vocabulary `slug`
   and VocabularyTerm `value` are stable internal ids never shown to users; the displayed label
   always resolves from `Core.Messages`; clients relabel via a `SurfaceOverrides` `LABEL_MESSAGE`

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/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/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.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/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/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/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.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 |
 | [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,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
+updated: 2026-07-13
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
@@ -27,6 +27,7 @@ files:
   - 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
@@ -245,10 +246,24 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   (the path form 404s EV-6).
 - **Tier-1 only on the client.** Business-logic gates (Tier-2) arrive as resolved booleans from the
   backend (`meta.surface`); never re-encode business rules in the FE evaluator.
+- **A React portal overlay's click bubbles through the COMPONENT tree, not the DOM tree.** The
+  SalesOrders row-actions menu (`SurfaceRowActions.tsx`) renders its dismiss overlay via a portal;
+  an outside-click on that fixed overlay propagated up the React component tree to the row's
+  `handleRowClick` and **opened the record modal**. Fix: call `e.stopPropagation()` (plus close) in
+  the overlay's `onClick`. Portal DOM position does not stop React synthetic-event bubbling.
+- **The sticky row-actions column must be gated on the active filter.** In `SalesOrders.tsx` the
+  `actionColumns` array is only included when `activeFilterKey === APPROVALS_FILTER_KEY`
+  (`"approvals"`); otherwise the row-actions column showed unconditionally.
 - **`tsc` not yet run** this session (the private `@agilant/toga-blox` registry needs npm creds);
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-07-13 — Fixed two SalesOrders row-actions bugs: (1) the portal dismiss overlay in
+  `SurfaceRowActions.tsx` propagated an outside-click up the React component tree to the row handler
+  and opened the record modal — added `e.stopPropagation()` (+ close) on the overlay `onClick`;
+  (2) gated the sticky `actionColumns` array in `SalesOrders.tsx` on
+  `activeFilterKey === APPROVALS_FILTER_KEY` so the row-actions column only shows under the Approvals
+  filter. (apeterson)
 - 2026-06-30 — Follow-up: fixed the GROUPED meta fetch returning `{}` (every migrated-client
   SalesOrders section had vanished). The meta-group envelope double-nests the slug-keyed `surfaces`
   map under an outer ROUTE-keyed `surfaces` slot; the old `extractGroup` grabbed the first (outer,

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)_ — 28 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 29 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 27 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 10 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)

package/package.json

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