toga-ai 1.0.605 → 1.0.607

package/knowledge/2.0/apps/_underscore/features/email-send-pipeline.md

@@ -7,11 +7,13 @@ client: shared
 type: feature
 status: active
 updated: 2026-08-13
-owners: ["bala", "tcox", "dfranks"]
+owners: ["bala", "tcox", "dfranks", "apeterson"]
 files:
   - _underscore/Email.php
   - _underscore/String.php
   - worker2/Worker/Infrastructure/Email/Send.php
+  - _underscore/Model/Client/Logs/Email.php
+  - _underscore/Model/Client/Logs/EmailAttachment.php
 related:
   - email-template-sending.md
   - string-html-entity-helpers.md
@@ -84,6 +86,19 @@ derive one from the other).
   reading the row, not by waiting for mail.
 - **~1-minute latency, not instant.** Anything that assumes an email is sent synchronously at the
   `send()` call is wrong — transmission happens on the next Send-worker tick.
+- **⚠ The `Logs_<Client>.Email` + `EmailAttachment` queue tables must be PROVISIONED, or every
+  send throws `Table 'logs_<client>.email' doesn't exist`.** The two tables the pipeline INSERTs
+  into (`Email`, `EmailAttachment`, accessed via the `DB_CLIENT_LOGS` alias) are backed only by the
+  models `_underscore/Model/Client/Logs/Email.php` + `EmailAttachment.php` — **no dbchanges2
+  migration ever created them**, so a client whose `Logs_<Client>` schema predates (or never ran)
+  the create is missing them, and the very first `_Email::send()` for that client 500s *after* the
+  calling code is otherwise correct. Symptom seen on `logs_quad`: `"Table 'logs_quad.email' doesn't
+  exist"` immediately after the Quad approval-email code fix. Interim fix = hand-authored
+  `CREATE TABLE` DDL matching the `Logs_<Client>` house style (`status` ENUM
+  `PENDING`/`SENT`/`FAILED`; `body`/`to`/`cc`/`bcc` as text; **no FKs**, per the logs-DB
+  convention). **Durable follow-up (pending): add the `Email`/`EmailAttachment` tables to the
+  `Logs_<Client>` blank-client template + a dated dbchanges2 migration so every environment/client
+  inherits them.**
 - **The Send worker forces HTML mode.** `sendEmail()` calls `$mailer->IsHTML(true)`
   **unconditionally**, ignoring the sender's `setIsHtml(false)`. A caller that queued a
   "plain-text" message is still transmitted HTML-mode. Author bodies accordingly.
@@ -160,6 +175,12 @@ derive one from the other).
     for a hotfix.
 
 ## Change history
+- 2026-08-18 — Recorded that the `Logs_<Client>.Email` + `EmailAttachment` queue tables are
+  **not created by any dbchanges2 migration** (only the models exist), so a client whose
+  `Logs_<Client>` schema lacks them 500s on the first `send()` with `"Table 'logs_<client>.email'
+  doesn't exist"` — hit on `logs_quad` right after the Quad approval-email fix. Interim = hand
+  DDL (status enum, text body/to/cc/bcc, no FKs); durable follow-up = add both tables to the
+  `Logs_<Client>` blank template + a dated migration. (apeterson)
 - 2026-08-13 — Documented that **`send()` resolves the `Logs_<Client>` database itself** from the
   client identifier (`Core.Clients` → `Databases` → `DatabaseHosts` for the environment + region) and
   **throws unless exactly one row matches** — so `setClientIdentifier()` takes a lookup key that must

package/knowledge/2.0/apps/_underscore/features/error-reporting-issue-event.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-08-12
-owners: ["dfranks", "jcardinal", "mhammontree", "ajean", "bala"]
+owners: ["dfranks", "jcardinal", "mhammontree", "ajean", "bala", "apeterson"]
 files:
   - _underscore/Error.php
   - _underscore/Database.php
@@ -485,6 +485,15 @@ gracefully — it silently deletes all observability for the whole tier. Any cha
 - **⚠ A missing `Logs.Issue` column silently disables ALL error capture on that environment** —
   see the open defect above. Symptom: `identifiers.captureFailure` in the API response and nothing
   anywhere else.
+- **⚠ The whole `Logs` cluster schema must be PROVISIONED on every environment, or capture
+  itself throws and swallows the real error.** The six singular `Logs` tables
+  (`Issue`/`Event`/`IssueFingerprint`/…) are created by the `dbchanges2/Logs/` migrations; an
+  environment whose `Logs` DB never ran them (or ran a partial subset) fails *inside*
+  `_Error::captureException()` with e.g. `"Table 'Logs.IssueFingerprint' doesn't exist"`. Because
+  this is the error-capture layer, the failure masks the **original** exception, so a real 500 on
+  that box may be under-logged or invisible. Seen on the client sandbox environment (`IssueFingerprint`
+  absent). Fix = run the `dbchanges2/Logs/` migrations on that environment's `Logs` DB. Diagnose a
+  suspiciously-empty capture by confirming the `Logs` tables exist before chasing the app code.
 - **Read-your-writes: reads go to the READ host and cannot see an uncommitted write.** A
   second `$issue->save()` re-reads the row via `_Model::initialize()`, and that SELECT goes to
   the read host — a separate connection that cannot see the still-uncommitted INSERT on the
@@ -652,6 +661,12 @@ clientUserId). **Neither was built.** As built instead:
 
 ## Change history
 
+- 2026-08-18 — Recorded the environment-provisioning gotcha: the `Logs` cluster tables
+  (`Issue`/`Event`/`IssueFingerprint`/…) come from the `dbchanges2/Logs/` migrations, and an
+  environment missing them fails inside `_Error::captureException()` (e.g. `"Table
+  'Logs.IssueFingerprint' doesn't exist"`), masking the original exception. Seen on the client
+  sandbox environment. (apeterson)
+
 - 2026-08-12 — **Corrected the 2026-08-06 open defect and marked it RESOLVED.** The sandbox-dev
   `Logs.Issue` drift was **seven** missing columns, not one: `clickupPriority` (`2026-08-03a`) **plus the
   whole `2026-08-05a` lifecycle migration** (`status`, `dtAutoResolved`, `baselineGapSeconds`,

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

@@ -18,7 +18,7 @@
 | [TOGa IQ Sprint Dashboard API (Record Scripts)](features/sprint-dashboard-api.md) | The internal **TOGa IQ sprint dashboard** is served in production by **six api2 Record Scripts** on `_Model_Team_Sprint` (`_underscore/Model/Team/Sprint.php`), | _underscore/Model/Team/Sprint.php, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-07-24a - SprintDashboardRecordScripts.sql, dbchanges2/Client_True/2026-07-24b - SprintDashboardScriptAcl.sql |
 | [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [TableView row-filtering via apiWhereClause (options.where grammar, end to end)](features/tableview-apiwhereclause-row-filtering.md) | `TableViews.apiWhereClause` (TEXT, nullable) is the sanctioned, code-free way to restrict or exclude rows from a 2.0 table view. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/TableView.php, toga2-supply/src/api/toga.ts |
-| [TableView field/column metadata (TableViewFields, hidden projected columns)](features/tableview-field-metadata.md) | The columns of a 2.0 table view are defined by DB metadata, not code. | _underscore/Model/Client/TableView.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql, dbchanges2/Core/2026-08-17a - ItemFulfillmentQuantityFieldTypeNumber.sql, dbchanges2/Client/2026-08-17a - ItemFulfillmentColumnsCopyable.sql |
+| [TableView field/column metadata (TableViewFields, hidden projected columns)](features/tableview-field-metadata.md) | The columns of a 2.0 table view are defined by DB metadata, not code. | _underscore/Model/Client/TableView.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql, dbchanges2/Core/2026-08-17a - ItemFulfillmentQuantityFieldTypeNumber.sql, dbchanges2/Client/2026-08-17a - ItemFulfillmentColumnsCopyable.sql, dbchanges2/Client_Quad/2026-08-18c - SalesOrderListingSortByDateOrderDesc.sql |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
 | [V2 API error/message codes (EV/EZ troubleshooting map)](features/v2-api-error-codes.md) | The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the response `error` field, grouped by family: `EN-*` authentication, `EZ-*` a | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, api2/Component/Api/V2/Response/Oauth/Oauth.php, api2/Controller/Index.php, toga2-supply/src/globalTypes.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/api/toga.ts, _underscore/Model/Client/TrackingNumber.php |
 | [V2 request deadlock-retry — route-scoped in-process replay](features/v2-deadlock-retry.md) | api2's front controller can **detect a MySQL deadlock (1213) / lock-wait timeout (1205) and replay the whole request in-process**, so a transient lock collision | api2/Controller/Index.php, _underscore/Database.php, _underscore/Query.php |

package/knowledge/2.0/apps/api2/features/tableview-field-metadata.md

@@ -14,6 +14,7 @@ files:
   - dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql
   - dbchanges2/Core/2026-08-17a - ItemFulfillmentQuantityFieldTypeNumber.sql
   - dbchanges2/Client/2026-08-17a - ItemFulfillmentColumnsCopyable.sql
+  - dbchanges2/Client_Quad/2026-08-18c - SalesOrderListingSortByDateOrderDesc.sql
 related:
   - tableview-apiwhereclause-row-filtering.md
   - ../../toga25-supply/features/meta-driven-table-data.md
@@ -93,8 +94,42 @@ per-client folder — the reference migration
 `dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql` adds the hidden
 `Items.uuid` column to the `items-for-purchase-orders` view and was verified against `Client_Nychh`.
 
+## Default sort is DB-driven (`TableViews.sortPrimary*`), emitted as `meta.table.sort`
+
+A view's **default sort** is not code — it lives on the `Client_*.TableViews` row:
+
+- **`sortPrimaryTableViewFieldId`** → FK to `TableViewFields.id` (the column to sort by), plus
+  **`sortPrimaryDirection`** (`'ASC'`/`'DESC'`).
+- **`sortSecondaryTableViewFieldId`** (+ its direction) for a tie-break sort.
+
+The API emits it as **`meta.table.sort = [{slug, dir}]`** (the `slug` is the referenced
+`TableViewFields.slug`), which the frontend applies as the initial ordering.
+
+**To change a listing's default sort per client, use a multi-table JOIN UPDATE — never a
+subquery on `TableViews`.** Because `sortPrimaryTableViewFieldId` points at a
+`TableViewFields` row of the *same* view, a `SET ... = (SELECT id FROM TableViewFields WHERE
+tableViewId = TableViews.id ...)` self-references `TableViews` and MySQL rejects it with
+**error 1093** ("can't specify target table for update in FROM clause"). Instead JOIN
+`TableViewFields` on its `slug` and set the id from the joined row:
+
+```sql
+UPDATE TableViews tv
+JOIN TableViewFields tvf
+  ON tvf.tableViewId = tv.id AND tvf.slug = 'dateOrder'
+SET tv.sortPrimaryTableViewFieldId = tvf.id,
+    tv.sortPrimaryDirection = 'DESC'
+WHERE tv.slug = '<listing-slug>';
+```
+
+This is the same shape as the `Client_Compass` item-fulfillment view's default-sort override.
+Applied for Quad: the sales-orders listing now defaults to `dateOrder DESC` (most recent
+first) instead of `number DESC` (`dbchanges2/Client_Quad/2026-08-18c -
+SalesOrderListingSortByDateOrderDesc.sql`).
+
 ## Gotchas / known issues
 
+- **Default-sort updates must JOIN `TableViewFields`, not subquery `TableViews`** — a subquery
+  on the same view triggers MySQL error 1093. See *Default sort* above.
 - **`recordFieldId` is cross-DB** — it indexes `Core.RecordFields`, not anything in the client DB.
   Resolve the id in `Core`, but insert the `TableViewFields` row in the client DB.
 - **Don't assume `Core.RecordFields`/`Core.Records` ids are stable across environments** — look them
@@ -108,6 +143,11 @@ per-client folder — the reference migration
 
 ## Change history
 
+- 2026-08-18 — Documented DB-driven **default sort**: `TableViews.sortPrimaryTableViewFieldId`
+  (+ `sortPrimaryDirection`, and the secondary pair) FK into `TableViewFields`, emitted as
+  `meta.table.sort=[{slug,dir}]`; and the JOIN-`TableViewFields`-on-slug UPDATE recipe that
+  avoids MySQL error 1093 (a self-subquery on `TableViews` is rejected). Applied to Quad's
+  sales-orders listing (default `dateOrder DESC`). (apeterson)
 - 2026-08-17 — Documented that a column's `type`/`precision` are canonical from `Core.RecordFields`
   (no per-view override — a change hits every view/client) while `isCopyable`/`isSortable`/
   `isFilterable`/`isVisible` are per-view `TableViewFields` flags. Confirmed setting

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-08-14
+updated: 2026-08-18
 owners: [jcardinal, apeterson]
 files:
   - dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql
@@ -641,6 +641,19 @@ rule resumes.
   messageKey; appId/recordId inherited from the `order-details` sibling by slug), Core→Core only
   (prod-safe). Per-client SurfaceOverride divergence not yet seeded — shared Core default + FE wiring
   only. (apeterson)
+- 2026-08-18 — Seeded the **"Enter PO Details" row-action `MENU_ITEM`** on the
+  `sales-order-listing-row-actions` surface (id 3): `Core/2026-08-18a` adds Message
+  `salesOrder.action.enterPo` + Action `salesOrder.enterPo` (`OPEN_MODAL`,
+  `config {kind:poNumber, valueKey:poNumber}`) + a `renderType='MENU_ITEM'` element, seeded Core
+  **neutral off** (`isVisible=0`/`isEnabled=0`). A row action needs a full Action+Message+element
+  triple (not a clone of the record-actions BUTTON — different FE dispatch seam, see
+  [surface-frontend](../../toga25-supply/features/surface-frontend.md)). Quad opts in via
+  `Client_Quad/2026-08-18b` (`IS_VISIBLE=1` client-wide, `IS_ENABLED=1` roles 7/8/9,
+  `VISIBILITY_RULE` `order._status in [pendingApproval]`). Separately, `Client_Quad/2026-08-18a`
+  gates the existing record-actions "Enter PO Details" **BUTTON** (surface
+  `sales-order-record-actions`, `config.valueKey=poNumber`) with a `VISIBILITY_RULE` limited to
+  `pendingApproval` — Quad is single-stage (only `pendingApproval`), whereas Compass/CompassCanada
+  widen the same gate to include `pendingInitialApproval`. (apeterson)
 - 2026-07-21 — Added the sales-order **Approve enable-gate** per-client overrides (`Client_*/2026-07-21a`):
   Compass/CC ADMIN `ENABLED_RULE` = `(pendingInitialApproval AND stepTwoAssigned) OR pendingApproval`
   on surface 8 el 17 + surface 3 el 29 (rule JSON in `c_longValue`; Compass UPDATEs its existing

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/PrimaryTableServerLayout/PrimaryTableServerLayout.tsx, toga25-supply/src/layout/PrimaryTableServerLayout/types.ts, 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, toga25-supply/src/layout/RecordApprovalModal/helpers/handleFormatApprovalWorkflowPayload.ts, toga25-supply/src/layout/RecordApprovalModal/api/approvalDecisionsApi.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/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/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.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/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.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/hooks/useSalesOrderVip.ts, 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,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-14
+updated: 2026-08-18
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/applyColSpan.ts
@@ -39,6 +39,7 @@ files:
   - 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/hooks/useSalesOrderVip.ts
   - 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
@@ -115,6 +116,24 @@ feature flag — see below). Backend: [surface-resolver](../../_underscore/featu
   change.
 - **`actionRegistry`** — string action key → existing app handler (the proven `MODAL_RENDERERS`
   pattern). The DB ships keys + payloads; the app supplies the actual handlers.
+
+### Row-menu `MENU_ITEM` dispatch is a DIFFERENT path than a record-actions `BUTTON` — you cannot clone one as the other
+The listing **row menu** (`SurfaceRowActions.tsx`) and the record-modal **action bar**
+(`SalesOrderTopBar` / `SurfaceActionBar`) dispatch through two distinct seams, so moving a
+control from one surface to the other is **not** a copy of the element:
+- **Row menu items** render as **`renderType='MENU_ITEM'`**, take their label from a
+  **`Core.Messages`** row, and dispatch **by `action.key` → `actionRegistry`**. So a new row
+  action needs a real **`Core.Action`** + a label **`Core.Message`** + an **`actionRegistry`
+  handler** keyed by that action.key.
+- **Record-actions controls** render as **`renderType='BUTTON'`** and dispatch **by
+  `config.valueKey`** through `SalesOrderTopBar` (not the action.key/registry path).
+- Therefore you **cannot** duplicate a record-actions BUTTON element onto a row-actions surface
+  and expect it to work — a row item must be authored as a MENU_ITEM with its own Action +
+  Message + registry handler. Concrete: "Enter PO Details" existed only as the record-actions
+  BUTTON; adding it to the `sales-order-listing-row-actions` surface required a new
+  `salesOrder.action.enterPo` Message + `salesOrder.enterPo` Action (`OPEN_MODAL`,
+  `config {kind:poNumber, valueKey:poNumber}`) + an `actionRegistry["salesOrder.enterPo"]`
+  entry (`forwardToDispatch("poNumber")` → `setApprovalModal({modalSelected:'poNumber'})`).
 - **theme/message resolvers** (`resolve.ts`) — token → CSS and ICU message rendering.
 - **`SurfaceActionBar`/`SurfaceActions` + `SurfaceSection`** — generic renderers.
 
@@ -512,6 +531,16 @@ developer asked for the **whole component**, not just badges. The old
 
 ## Gotchas
 
+- **The VIP `/contacts` API call is gated by an approval-details element's `labelSuffix.valueKey`,
+  NOT by the element's `isVisible`.** `useSalesOrderVip.ts` decides whether to call `/contacts`
+  (which reads `Users.c_isVip`) by scanning the approval-details surface for an element whose
+  `labelSuffix.valueKey` **ends in `isVip`**. So for a client that does not have the VIP chip
+  configured (e.g. Quad), that call 403s `EZ-2` on `Users.c_isVip` unless the VIP `labelSuffix` is
+  stripped from the surface. `Core/2026-08-10a` strips the VIP `labelSuffix` from the Core base
+  surface (`JSON_REMOVE config.$.labelSuffix`); Compass + Compass Canada re-add the gold VIP chip
+  via a `CONFIG` override. Applying the Core seed turns VIP off for Quad/all-non-Compass while
+  keeping it on for Compass/Compass Canada — **no FE change needed**. The gate is the
+  `labelSuffix.valueKey`, not the visibility flag.
 - **A named predicate that FAILS OPEN silently enables a button when its data isn't fetched.**
   `stepTwoAssigned` returns `true` when `order.currentStage` is `null` (a fail-OPEN default). So if the
   surface's approval-stage data is not plumbed in (e.g. `approvalsEnabled=false`, so
@@ -634,6 +663,14 @@ developer asked for the **whole component**, not just badges. The old
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-08-18 — Documented that a listing **row-menu `MENU_ITEM`** dispatches by
+  `action.key`→`actionRegistry` (label from `Core.Messages`), a **different seam** than a
+  record-actions **`BUTTON`** (dispatched by `config.valueKey` via `SalesOrderTopBar`) — so a
+  BUTTON element cannot be cloned onto a row-actions surface; a row action needs its own Action +
+  Message + registry handler (built "Enter PO Details" as `salesOrder.enterPo`). Also recorded that
+  `useSalesOrderVip` gates the `/contacts` (`Users.c_isVip`) call by an approval-details element's
+  `labelSuffix.valueKey` ending in `isVip` — stripping the VIP `labelSuffix` (Core/2026-08-10a)
+  turns the call off for non-Compass clients (Quad) with no FE change. (apeterson)
 - 2026-08-14 — Moved the whole Sales Order **Admin Notes** component into Surface (badge labels/colors,
   chrome labels, layout toggles — not just badges), retiring the hardcoded
   `addNotesFields.json → fieldsConfig → model → view` plumbing. New **`buildNotesComponent()`**

package/knowledge/INDEX.md

@@ -12,7 +12,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **togaview** (TOGa View) — 7 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
-- **test** (Test) — 14 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
+- **test** (Test) — 15 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 3 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
 - **tools** (Tools) — 15 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 

package/knowledge/clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md

@@ -5,10 +5,11 @@ project: _Underscore
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-08-04
+updated: 2026-08-18
 owners: ["jcardinal", "bala", "dfranks"]
 files: []
 related:
+  - 1.0/apps/test/features/compass-retrofix2-sql-generator.md
   - clients/compass-usa/profile.md
   - clients/compass-usa/features/asn-to-item-fulfillment.md
   - clients/compass-usa/features/mits-po-to-so-item-linking.md
@@ -71,6 +72,27 @@ back-link chain climbs **Agilant → ODP → Compass**. Item back-links use
 `ItemFulfillmentItems.upstreamItemFulfillmentItemId` the same direction and may be many-downstream →
 one-upstream for bundles.
 
+> **Mirror-gap root cause — a missing item bridge stalls the climb (verified 2026-08-18).** The
+> recursive IF mirror climbs Agilant → ODP → Compass through **BOTH** bridge tables. If the
+> `PurchaseOrderItems_SalesOrderItems` rung linking the Compass/MITS PO item → the ODP SO item is
+> **missing**, the mirror **cannot map past the ODP SO** and never creates the ODP/Compass mirror IFs
+> — the Compass SO shows "nothing fulfilled" even though the Agilant SO has an ItemFulfillment
+> (`c_netsuiteInternalItemFulfillmentId` set, created by NetSuite sync). Orders SA130530, SA130334,
+> SA130430 all had an intact header chain and every other item bridge, but were missing **only** that
+> one rung (confirmed against a healthy order that had it). When diagnosing a Flow-B order that
+> fulfilled upstream but shows empty on Compass, check that specific bridge first.
+
+### Asset tags arrive as separate CG "units" (Flow B)
+NetSuite delivers asset tags on **separate service-item lines** whose part number contains
+`ASSETTAG` (e.g. `ODP-COMPASS-ASSETTAG1`). Older Compass imports landed each asset tag as its **own
+`Units` row** whose `serialNumber` holds the CG value (e.g. `CG2000027730`), attached via
+`ItemFulfillmentItemUnits` alongside the real serialized unit on the **same** fulfillment. The
+forward fix (`library/app/api/toga2.php` ~lines 3688–3965) applies those asset tags to the serialized
+items **in order** and sets `Units.assetTag` on the real device. Retroactively this is Phase 0 of the
+[retrofix2 tool](../../../1.0/apps/test/features/compass-retrofix2-sql-generator.md); because units
+are **shared up the chain** (same `Units.id` at every level), the correction must land before the
+fulfillment mirror climbs.
+
 ## Expected raw-data invariants (for detect-and-repair)
 
 1. **Links:** every SOI that should be procured has exactly one PURE bridge to the matching POI on the
@@ -141,12 +163,18 @@ column is `ON UPDATE CURRENT_TIMESTAMP`), which can look like a fresh modificati
 `api2` cXML ShipNotice handler; the `_underscore` recursive item-fulfillment engine.
 
 ## Retrofix tooling
-A standalone repair script lives in the worker 1.0 test area (`test/@jeff/compass/retrofix.php`,
-machine-local path tracked in dev memory). It sweeps Compass SOs newest-first, detects deviations from
-the invariants above, and repairs via direct SQL on `db_prod2_compass`. Safety rules baked in: rehearsal
-mode (logs intended writes, rolls back), per-phase gating, a hard block on any write to the
-`TrackingNumbers` table, and the never-over-fulfill cap. It is a diagnostic/repair tool, not part of the
-runtime workflow.
+The current repair script is **`test/@jeff/compass/retrofix2.php`** (1.0 `App_`), which
+**supersedes** the older `retrofix.php` sibling in the same folder. Unlike the description below of the
+earlier tool, retrofix2 **emits review-first `.sql`** rather than writing the DB directly. It runs
+three phases newest-first per SO — **Phase 0** (CG-unit asset-tag merge; must run first because units
+are shared up the chain), **Phase 1** (header/link/bridge repairs, levels L1–L4, where L3 fixes the
+`PurchaseOrderItems_SalesOrderItems` rung the mirror needs), **Phase 2** (fulfillment mirror climb).
+Each level is wrapped in `runLevel()` so one level's exception (notably L1's unconditional NetSuite
+call failing) is logged as a skip and swallowed, letting the independent NetSuite-free repairs still
+emit. Write guards: `emit()` hard-blocks `Units` and `TrackingNumbers` writes; the Phase-0-only
+`emitUnit()` permits `Units` UPDATE/DELETE but still blocks `TrackingNumbers`. Full structure in the
+[retrofix2 feature doc](../../../1.0/apps/test/features/compass-retrofix2-sql-generator.md). It is a
+diagnostic/repair tool, not part of the runtime workflow.
 
 ## Edge cases & escalation
 - Incomplete orders (no PO/ASN/Agilant leg yet) are normal — repair only the layers that exist.
@@ -155,6 +183,12 @@ runtime workflow.
 - High-multiplier over-fulfillment (5×–20×) does not fit the split-PO spurious-link pattern — separate cause.
 
 ## Change history
+- 2026-08-18 — Recorded the **Flow-B mirror-gap root cause** (a missing `PurchaseOrderItems_SalesOrderItems`
+  rung stalls the recursive IF mirror past the ODP SO, so a fulfilled Agilant order shows empty on
+  Compass — orders SA130530/SA130334/SA130430), the **CG asset-tag "unit" data shape** (asset tags land
+  as their own CG-serial `Units` rows), and repointed the Retrofix tooling section to the new
+  **retrofix2.php** (review-first `.sql`; Phase 0/1/2; `runLevel()` level isolation; `emit()`/`emitUnit()`
+  write guards). (jcardinal)
 - 2026-08-04 — Added the **"empty shell" order signature** — the ODP importer writes the SO header
   and its items in two separate API requests, so a fatal on the second leaves a committed,
   zero-item order — plus the three orphan sweeps that detect it (zero-item SOs, zero-item POs, ODP

package/knowledge/clients/quad/profile.md

@@ -82,4 +82,13 @@ Client-specific DB change-sets live in `dbchanges2/Client_Quad/`.
 - Quad is one of only **two** clients (with Compass) whose fulfillment views are free of the
   dangling `joinRecordId` 41 / `parentRecordFieldId` 211+321 config, because both were migrated to
   base record 29. Ten other clients still carry it.
+- **Single-stage approval (2026-08-18).** Quad's approval flow has only the `pendingApproval`
+  stage (no `pendingInitialApproval`), so its PO-details visibility/enable gates on the
+  sales-order surfaces use `order._status in [pendingApproval]` — contrast Compass/Compass Canada,
+  which widen the same gate to include `pendingInitialApproval`. Quad opted into the "Enter PO
+  Details" **row-action** menu item (`sales-order-listing-row-actions`) client-wide, enabled for
+  roles 7/8/9. Seed side: [Surface Layer Schema](../../2.0/apps/dbchanges2/features/surface-layer-schema.md).
+- **Sales-orders listing default sort = `dateOrder DESC` (2026-08-18)** — most recent first
+  (was `number DESC`), set on Quad's `TableViews` row. See
+  [TableView field/column metadata](../../2.0/apps/api2/features/tableview-field-metadata.md).
 - This profile is a starting point; expand as more Quad-specific behavior is captured.

package/package.json

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