toga-ai 1.0.682 → 1.0.684

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

@@ -37,13 +37,14 @@
 | [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona **names** in multiple languages by adding a per-language **sidecar** table `PersonaTranslations`, reusing the platform's existing metadata-driven | _underscore/Model/Client/PersonaTranslation.php, dbchanges2/Client/2026-07-22b - PersonaTranslations.sql, dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql, dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql, dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql, toga2-commerce/src/pages/Account/view/MySettingsView.tsx |
 | [Record Change Audit Log (Logs_<Client>.Record / RecordField) — reading a field's history](features/record-change-audit-log.md) | Every 2.0 client schema has a sibling **logs** schema `Logs_<Tenant>` (e.g. | _underscore/Model/Client/Logs/Record.php, _underscore/Model/Client/Logs/RecordField.php, _underscore/Model/Client/Logs/CustomRecordField.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql, dbchanges2/Client_Compass/2026-08-18 - FixSA135471HeroItemHalfQuantityFulfillment.sql |
+| [Sales-order denial reason (`ApprovalDecisions.note`) — captured everywhere, displayed nowhere](features/sales-order-denial-reason.md) | The **denial reason** an approver types when rejecting a sales-order approval stage. | _underscore/Model/Client/ApprovalDecision.php, _underscore/Model/Compass/ApprovalDecision.php, _underscore/Model/Quad/ApprovalDecision.php, toga25-supply/src/layout/RecordApprovalModal/, toga25-supply/src/layout/RecordApprovalModal/api/approvalDecisionsApi.ts, toga2-commerce/src/pages/OrderDetails/api/OrderDetailsApi.ts |
 | [Sales-order \"PO Number\" sourcing — one surface element, `_purchaseOrders`, tenant SQL underneath](features/sales-order-po-number-sourcing.md) | The sales-order modal's **PO Number** field is **not** tenant-split at the display layer. | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Canada/SalesOrder.php, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, dbchanges2/Core/2026-08-25a - PoNumberDetailFieldPurchaseOrdersValueKey.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Client_Quad/2026-08-19a - PoDetailsButtonMostRecentPoSelection.sql |
 | [SO↔PO bridge tables are TWO tables in OPPOSITE directions (upstream vs downstream)](features/sales-order-purchase-order-bridge-direction.md) | There are **two** bridge tables linking sales orders and purchase orders, and they mean **opposite things**. | _underscore/Model/Client/PurchaseOrders/SalesOrder.php, _underscore/Model/Client/SalesOrders/PurchaseOrder.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/SalesOrder.php, _underscore/Trait/Netsuite/SalesOrder.php, library/app/api/toga2.php |
 | [Per-client sales-order status filter (Surface FILTER_SET → table meta `filterOptions`)](features/sales-order-status-filter-surface.md) | The status-filter dropdown on the sales-orders table is **per client**, driven by a Surface `FILTER_SET` rather than by the raw contents of the client's `SalesO | _underscore/Model/Client/TableView.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Prudential/SalesOrder.php, toga-blox/src/components/Table/hooks/useFetchTablePageMeta.ts, toga-blox/src/api/types.ts, dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql |
 | [_String helpers — ASCII-safe HTML entity encoding (and the parseBetween trap)](features/string-html-entity-helpers.md) | `_String` is the 2.0 framework's static string utility class. | _underscore/String.php |
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Client/Language.php, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, toga25-supply/src/App.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/contexts/AuthContext.tsx, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Core/2026-08-21a - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_Compass/2026-08-04a - ApprovalDetailsAssignedManagerPreferredStage.sql, _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Client_Compass/2026-07-15f - SalesOrderRecordActionsRemoveDeadConfigRuleOverrides.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-12a - NavigationSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-12a - NavigationRoleGrants.sql, toga25-supply/surface-layer-guide.md |
 | [Table-View Hyperlink Columns (meta → ACL → computed URL → render)](features/tableview-hyperlink-columns.md) | Any 2.0 table-view column can render its value as a clickable link instead of plain text. | _underscore/Model/Client/TableView.php, _underscore/Model/Client/TrackingNumber.php, api2/Component/Api/V2/V2.php, toga2-supply/src/api/toga.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/convertData.tsx, toga2-supply/src/components/ui/Tables/hooks/useDataTableState.tsx, dbchanges2/Client/2026-07-20 - TrackingNumberHyperlinkAndFieldPermission.sql |
-| [TableView joins (TableViewJoins → SQL) — aliasing, chained multi-hop joins, ACL](features/tableview-joins.md) | `Client_*.TableViewJoins` rows are what let a table view show a column from a table other than its base record. | _underscore/Model/Client/TableView.php, _underscore/Model.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql, dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_CompassCanada/2026-08-27a - ItemFulfillmentTableViewsRebuild.sql |
+| [TableView joins (TableViewJoins → SQL) — aliasing, chained multi-hop joins, ACL](features/tableview-joins.md) | `Client_*.TableViewJoins` rows are what let a table view show a column from a table other than its base record. | _underscore/Model/Client/TableView.php, _underscore/Model.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql, dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_CompassCanada/2026-08-27a - ItemFulfillmentTableViewsRebuild.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql |
 | [TogaIQ Gateway Client (_Component_Api_Togaiq) — AI generate/translate from 2.0](features/togaiq-gateway-client.md) | `_Component_Api_Togaiq` is the 2.0 framework's client for the **TogaIQ** (Talos) AI gateway. | _underscore/Component/Api/Togaiq/Togaiq.php, _underscore/ApiRequest.php |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Elite/2026-08-17 - FulfillmentTableViews.sql, dbchanges2/Client_Quad/2026-08-26a - BackfillQuadUnitLevelTrackingSingleTn.sql, dbchanges2/Client_Quad/2026-08-26b - BackfillQuadItemLevelTrackingSingleTn.sql, dbchanges2/Client_CompassCanada/2026-08-27a - ItemFulfillmentTableViewsRebuild.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView | _underscore/Model/Client/ServiceRequest.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql |

package/knowledge/2.0/apps/_underscore/features/sales-order-denial-reason.md

@@ -0,0 +1,222 @@
+---
+title: Sales-order denial reason (`ApprovalDecisions.note`) — captured everywhere, displayed nowhere
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-08-28
+owners: [apeterson]
+files:
+  - _underscore/Model/Client/ApprovalDecision.php
+  - _underscore/Model/Compass/ApprovalDecision.php
+  - _underscore/Model/Quad/ApprovalDecision.php
+  - toga25-supply/src/layout/RecordApprovalModal/
+  - toga25-supply/src/layout/RecordApprovalModal/api/approvalDecisionsApi.ts
+  - toga2-commerce/src/pages/OrderDetails/api/OrderDetailsApi.ts
+related:
+  - ../../../clients/compass-usa/features/approval-decision-flow.md
+  - ../../../clients/compass-usa/features/mr-ma-order-approval-and-status.md
+  - acl-permission-chain.md
+  - surface-resolver.md
+  - ../../dbchanges2/features/surface-layer-schema.md
+  - ../../toga25-supply/features/surface-frontend.md
+---
+
+## What it is
+
+The **denial reason** an approver types when rejecting a sales-order approval stage. It is a single
+free-text field — **`ApprovalDecisions.note`** — and this doc is the map of where it is written,
+where it is read, and (as of 2026-08-28) where it is **not** read.
+
+The headline: **every tenant already captures it, and no frontend anywhere displays it.** Its one
+and only consumer today is the rejection email. So a "show the denial reason" ticket is a
+**read/display** feature — there is no data-capture, no API and no schema work in it.
+
+## Where the value lives
+
+| Thing | Value |
+|---|---|
+| Column | `Client_<Tenant>.ApprovalDecisions.note` |
+| Model | `_Model_Client_ApprovalDecision`, `FIELD_CHAR` |
+| Core `Records` id | **179** (`aclDatabase = CLIENT`) |
+| Core `RecordFields` id for `note` | **1551** |
+
+`ApprovalDecisions` holds **at most one row per stage per approval** (see
+[approval-decision-flow](../../../clients/compass-usa/features/approval-decision-flow.md)), so a
+denial reason is per-stage, not per-order — an order can in principle carry a note on stage 1 and
+another on stage 2.
+
+## The write side already exists — all three tenants
+
+In `toga25-supply` the approval modal already captures the note for Compass USA, Compass Canada and
+Quad:
+
+- `RecordApprovalModal/view/ApprovalFlowDetailInputs.tsx` renders the reason input.
+- It is **config-driven** by the per-client `approvalActionFields.json`
+  (`deniedLabel` / `deniedRequired` / `approvedLabel` / `approvedRequired`) — deny is required,
+  approve optional, per the Core decision-action surfaces (see
+  [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md)).
+- `RecordApprovalModal/api/approvalDecisionsApi.ts` POSTs it.
+
+Nothing on the write path needs changing.
+
+## Who reads it today — the rejection email, and only the rejection email
+
+Both consumers read `$payload->note` and fall back to
+`SELECT note FROM ApprovalDecisions WHERE uuid = …` when the payload does not carry it.
+
+- **Compass USA + Compass Canada** — `_Model_Compass_ApprovalDecision::sendRejectionEmailToUser()`
+  → `buildRejectionNoteHtml()` (~L493, ~L904, ~L934). Canada machine-translates EN↔FR through
+  TogaIQ; **US passes the note through verbatim** because the client gate fails closed (see the
+  "Compass US is deliberately excluded from the rejection-note translation" gotcha in
+  [approval-decision-flow](../../../clients/compass-usa/features/approval-decision-flow.md)).
+- **Quad** — `_Model_Quad_ApprovalDecision::handleApprovalDecision()` sends
+  `TEMPLATE_REQUEST_DENIED` with a `{note}` token. **Quad does not extend the Compass parent** —
+  it is a separate implementation, so a change to the Compass rejection-note path does not reach
+  Quad and vice versa.
+
+**No other reader exists.** Neither `toga25-supply` nor `toga2-commerce` renders it.
+
+### toga2-commerce already fetches it and throws it away
+
+`toga2-commerce/src/pages/OrderDetails/api/OrderDetailsApi.ts` (~L225) already lists
+`"ApprovalDecisions.note"` in the `fields` of `getCurrentApprovalStage()`. It is dropped on the
+floor downstream: the `ApprovalDecision` type in `globalTypes.ts` is only `{currentStage, stages}`,
+and the OrderDetails view renders `salesOrderNotes` — a **different table**, not the denial reason.
+
+So the commerce half of a display feature is **type + formatting + render + per-tenant copy**
+(including French for Canada) with **no API work**. Do not add the field to the request; it is
+already there.
+
+## ACL — `RecordFields` 1551 (prod, 2026-08-28)
+
+Point-in-time grant state on `AclFieldPermissions` for the `note` field:
+
+| Tenant | Roles holding a grant |
+|---|---|
+| Compass USA | 3 (API), 4 (Admin), 7 (Compass Base), 8 (Manager) |
+| Compass Canada | 1 (Base), 8 (Compass Base), 9 (Manager), 10 (Agilant-Administrators) |
+| Quad | **1 (Base) and 3 (API) only** |
+
+**Quad's Supply roles 7 (Global Admin) / 8 (IT-Shopper) / 9 (Buyer) have no direct grant** — but
+this is **not a blocker today**, because every one of those users also holds role 1 and ACL
+**unions** across a user's roles (see
+[acl-permission-chain](acl-permission-chain.md)). No ACL migration is needed to ship a display
+feature.
+
+**Latent risk worth knowing:** a future Quad user granted role 7 *without* role 1 would fail the
+**entire** request with `EZ-2`, not merely lose the field — one unreadable field named in `fields=`
+403s the whole GET. That turns a missing grant on an obscure field into a blank page.
+
+## How much denial data actually exists (prod, 2026-08-28)
+
+| Tenant | Denied decisions | With a note |
+|---|---|---|
+| Compass USA | 2,579 (across 2,570 orders) | 2,357 (**91%**) |
+| Compass Canada | 34 | 9 (26%) |
+| Quad | 3 | 3 |
+
+**Recorded recommendation:** ship **Compass USA first**. Canada and Quad get the surface rows for
+consistency, but no per-tenant polish is justified by 34 and 3 rows. All figures are point-in-time
+measurements, not standing facts.
+
+## Planned display design (decided 2026-08-28 — nothing built yet)
+
+Three decisions were taken during the investigation. They are recorded here so the build does not
+re-litigate them.
+
+### 1. The denial-details block gets its OWN surface
+
+**Planned:** `Core.Surfaces` **47** `sales-order-denial-details`, `SurfaceElements` **170–174**, plus
+a **175** marker — with **reserved literal ids**, not `AUTO_INCREMENT`, so client override files can
+hardcode them and ship prod-ready. (Next free prod ids as of 2026-08-28: Surfaces **47**,
+SurfaceElements **170**, Messages **227**, Actions **17** — re-verify before writing the seed; see
+the verify-the-block-is-free rule in
+[surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md).)
+
+Rejected: adding it to `sales-order-record-header` (surface 11). That surface is **top-bar chrome
+only** — modal tag / order date / status badge / title, consumed by `SalesOrderTopBar.tsx`. Both
+comparable read-only cards already have their own surface (`sales-order-decision-summary` 41,
+`sales-order-approval-details` 38, each inheriting `appId`/`recordId` from the `order-details`
+sibling), a conditional section needs its own layout-rule marker, and mixing it into an always-on
+surface complicates every header override.
+
+### 2. "View only" mode is a MARKER ELEMENT carrying a rule — never per-element `IS_ENABLED`
+
+The approval-workflow modal's read-only mode is expressed as a **hidden marker element whose
+resolved rule the FE reads as a MODE**. Precedent is already live in prod: element **108** on
+surface 38, `config.role = 'sectionLayoutRule'`, `renderType TEXT`, `isVisible = 0` — it never
+renders; the FE evaluates its resolved `visibilityRule` against the record to choose a layout. Both
+Compass DBs override it client-wide with `VISIBILITY_RULE`. Same family as element 24
+(`approvalsGate`) on surface 10.
+
+**Why not `IS_ENABLED`:** that attribute is a **static boolean** per (element, role, persona,
+language) with **no order-status axis**. `VISIBILITY_RULE` and `ENABLED_RULE` are the *only*
+status-aware attributes in the `SurfaceOverrides` ENUM. Separately, the workflow **button must stay
+clickable** so the modal can open at all — read-only cannot be expressed by disabling the button.
+
+**Planned home for the marker:** surface **41** (`sales-order-decision-summary`) — the only surface
+all three modal modes (approve / deny / approvalWorkflow) already fetch.
+
+**Half the rendering already exists.** `ApprovalFlowDetailInputs.tsx` computes
+`areInputsDisabled = !isPreApproved && stageHasApprovalDecision`, and `StageHasDecisionView.tsx`
+already renders a decided stage's decision label plus the note in a disabled/readOnly textarea.
+Remaining gaps: stages with **no** decision still render editable; `ApprovalStageCard`'s
+approve/deny radios are not status-gated; the submit path is not gated.
+
+### 3. Gate the card with a plain Tier-1 rule + a component emptiness guard
+
+**Decision:** `{"all":[{"field":"order._status","op":"in","value":["canceled"]}]}` plus a
+don't-render-an-empty-card guard in the component. **Not** a new Tier-2 named predicate.
+
+This **reverses** the initial recommendation. Compass `_status` reaches `canceled` two ways — an
+explicit `salesOrderStageId` (stage 8, Canceled) *or* any denied `ApprovalDecision` (see
+[mr-ma-order-approval-and-status](../../../clients/compass-usa/features/mr-ma-order-approval-and-status.md))
+— so a Tier-1 rule also fires on administratively-canceled orders with no denial behind them. A
+`hasDeniedDecision` predicate was proposed to close that hole, then dropped once the hole was
+**measured**: prod 2026-08-28, **1,592** Compass orders sit on stage 8, **1,569** of them also have
+a denied decision, so only **23** — **0.9%** of ~2,593 — would render an empty card. That does not
+justify growing `SURFACE_NAMED_RULES`, which the codebase itself calls an *"INTENTIONAL DEVIATION"*
+from the frozen grammar (see
+[surface-frontend](../../toga25-supply/features/surface-frontend.md)). Comment the guard with why it
+exists, and revisit if admin/NetSuite cancellation volume rises.
+
+The frozen rule grammar was confirmed identical on both sides: `eq`/`ne`/`in`/`nin`/`gt`/`gte`/`lt`/
+`lte` — `RULE_OPS` at `_underscore/Model/Core/Surface.php:233` and `FROZEN_OPS` in
+`toga25-supply/src/surface/evaluateSurfaceRule.ts`.
+
+## Gotchas
+
+- **Quad is not a Compass tenant on this path.** `_Model_Quad_ApprovalDecision` implements its own
+  denial email (`TEMPLATE_REQUEST_DENIED` + `{note}`) and does **not** extend
+  `_Model_Compass_ApprovalDecision`. Any "fix the denial note for everyone" change is two edits.
+- **Quad cannot open the approval-workflow modal at all today.** Quad has **no `SurfaceOverride` on
+  element 19 (`approvalWorkflow`) or 21 (`editOrder`)** — its roles 7/8/9 are opted into approve +
+  deny only. An `IS_VISIBLE` opt-in for element 19 is a **prerequisite** for any Quad work on the
+  workflow modal, and it is easy to miss because Compass/Compass Canada both have it.
+- **`salesOrderNotes` is not the denial reason.** The commerce OrderDetails view renders
+  `salesOrderNotes` (request/shipping/delegate note types on a different table). Reading that code
+  and concluding "the note is already displayed" is the trap.
+- **"Canceled" does not mean "denied."** ~1% of Compass canceled orders have no denial behind them.
+  Anything keyed on `_status in ["canceled"]` must tolerate a missing decision/note.
+
+## Change history
+- 2026-08-28 — Documented the denial reason end-to-end for the forthcoming display feature
+  (investigation only; **no code written, no migration run**; all prod figures read-only). Findings:
+  the value is `ApprovalDecisions.note` (Core record **179**, RecordField **1551**); the **write
+  side already exists for all three tenants** in `toga25-supply`; its **only** consumer is the
+  rejection email (Compass parent for USA/Canada, a **separate** Quad implementation); and
+  `toga2-commerce` **already requests the field** in `getCurrentApprovalStage()` but drops it (narrow
+  type + the view renders the unrelated `salesOrderNotes`). Recorded prod ACL for field 1551 (Quad's
+  Supply roles 7/8/9 pass only because they also hold role 1 and ACL unions — latent whole-request
+  `EZ-2` if that ever stops being true), prod denial volumes (Compass USA 2,579 denied / 91% with a
+  note; Canada 34/9; Quad 3/3 → ship Compass USA first), and three design decisions: an **own
+  surface** (planned 47 / elements 170–175, reserved literal ids) rather than an addition to the
+  header surface; **view-only expressed as a rule-carrying marker element** (precedent el 108
+  `sectionLayoutRule`) because `IS_ENABLED` has no status axis and the button must stay clickable;
+  and a **plain Tier-1 `canceled` rule + component emptiness guard** instead of a new Tier-2 named
+  predicate — the initial Tier-2 recommendation was reversed after measuring the gap at 23 orders
+  (0.9%). Also flagged that **Quad has no override on element 19**, so it cannot open the approval
+  workflow modal at all today. (apeterson)

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

@@ -59,6 +59,7 @@ files:
   - toga25-supply/surface-layer-guide.md
 related:
   - ../../dbchanges2/features/surface-layer-schema.md
+  - sales-order-denial-reason.md
   - ../../api2/features/surface-meta-option.md
   - acl-permission-chain.md
   - sales-order-status-filter-surface.md
@@ -246,6 +247,32 @@ cluster-isolation rule.
   exact ids to a *different* element. See the NYCHH ship-together constraint in
   [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md).
 
+### 🚨 …but the REPO still does not describe prod. Read production. (2026-08-28)
+
+The reserved-literal house style fixes **new** files. It did **not** retroactively fix the ~51
+existing `Client_Compass`/`Client_CompassCanada`/`Client_Quad` override files, which still carry
+cross-cluster `FROM Core.SurfaceElements JOIN Core.Surfaces` reads and are **physically unrunnable
+in prod** (verified empirically 2026-08-28: the Core reader exposes only
+Core/Forecast/Forecast_Archive/Team, the client reader only `Client_*`). Prod's rows were **hand-written
+by an operator** — id resolution on prod-core, then literal INSERTs against prod-client, per
+`toga25-supply/db-migrations/SURFACE-FEATURE-RUNBOOK.md` — and never written back to the repo.
+
+**Standing rule (developer ruling, 2026-08-28): establish surface state by READING PRODUCTION, never
+by reading `dbchanges2`. The stale files are NOT to be back-ported, reconciled, re-run or modified.**
+Full detail, the prod element/override sweep, and the next-free prod ids live in
+[surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md).
+
+### Only `VISIBILITY_RULE` / `ENABLED_RULE` are status-aware — everything else is a static boolean
+
+Worth stating outright because it decides how a per-status behavior gets modeled: `IS_VISIBLE` and
+`IS_ENABLED` are static booleans per **(element, role, persona, language)** — there is **no
+order-status axis** anywhere in the `SurfaceOverrides` attribute ENUM except the two rule attributes.
+Any "behave differently when the order is in state X" requirement is therefore a **rule**, and if the
+target is a whole section/mode rather than one control it belongs on a **hidden marker element whose
+rule the FE reads as a MODE** (el 108 `sectionLayoutRule`; el 24 `approvalsGate`) — see the marker
+flavors in [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md) and the applied
+design in [sales-order-denial-reason](sales-order-denial-reason.md).
+
 ### Prior (2026-08-21) framing — kept for context, now historical
 
 The per-client surface **override** files could not run in production under the dbchanges2
@@ -698,6 +725,16 @@ full stop. See
   match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-08-28 — Recorded that the reserved-literal house style fixed **new** authoring only: the ~51
+  existing `Client_Compass`/`Client_CompassCanada`/`Client_Quad` override files still carry
+  cross-cluster `Core.*` joins and are **unrunnable in prod** (verified empirically — the Core and
+  client readers expose disjoint schema sets), while prod's rows were **hand-written by an operator**
+  per `SURFACE-FEATURE-RUNBOOK.md` and never written back. **Developer ruling: read PRODUCTION for
+  surface state; the stale files are not to be back-ported, reconciled, re-run or modified.** Also
+  stated the attribute axis plainly — `IS_VISIBLE`/`IS_ENABLED` are static booleans per
+  (element, role, persona, language) with **no status axis**, so `VISIBILITY_RULE`/`ENABLED_RULE` are
+  the only status-aware attributes, and a status-aware *mode* belongs on a hidden rule-carrying marker
+  element (el 108 `sectionLayoutRule`, el 24 `approvalsGate`). (apeterson)
 - 2026-08-28 — **Corrected the route-level gate's role-id space.** The dispatch check is keyed on
   the role space that `Core.Records.aclDatabase` selects, not always `id.client.roles`: `surfaces`
   is a **CORE** record, so `V2.php` (~L3090) takes `$roleIds` from **`id.core.roles`** and

package/knowledge/2.0/apps/_underscore/features/tableview-joins.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-08-28
-owners: [bala]
+owners: [bala, apeterson]
 files:
   - _underscore/Model/Client/TableView.php
   - _underscore/Model.php
@@ -16,6 +16,7 @@ files:
   - dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql
   - dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql
   - dbchanges2/Client_CompassCanada/2026-08-27a - ItemFulfillmentTableViewsRebuild.sql
+  - dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql
 related:
   - ../../api2/features/tableview-field-metadata.md
   - ./page-meta-context-field-settings.md
@@ -23,6 +24,8 @@ related:
   - ../../api2/features/tableview-apiwhereclause-row-filtering.md
   - ../../api2/features/request-logging.md
   - ../../../../clients/compass-canada/features/item-fulfillment-tableviews.md
+  - ./acl-permission-chain.md
+  - ../../toga25-supply/features/transfer-orders-page.md
 ---
 
 ## Summary
@@ -84,6 +87,27 @@ first Items join on the view and therefore aliased `Items`. So:
 - Before this change there were **zero** rows with a non-null `joinOnTableViewJoinId` anywhere in
   `Client_Elite`, so chained joins were previously unused in these schemas.
 
+### Joining the same table twice is SAFE — until something chains off it
+
+The hazard is often stated as "never join a table twice." That is stricter than the mechanism. The
+alias counter starts at `65` (`A`) **already seeded with the base table**, so the **first** join of a
+table gets the **bare table name** and the **second** becomes `<Table>_C` (not `_B` — see the
+gotcha). Since `onB` always renders the raw table name, the precise rule is:
+
+> **Duplicating a table is harmless while no join's `onB` names that table.** It breaks only when the
+> duplicated table is the **parent** of a chained join, because the chain silently binds to whichever
+> copy took the bare name.
+
+Worked example — the `transfer-orders` view (2026-08-28) joins **`Locations` twice**, for the origin
+and destination location, plus `TransferOrderStages`. That is safe because **all three ON clauses
+reference the base table `TransferOrders`**, so nothing hangs off the `Locations` alias at all.
+
+The corollary shapes design decisions well beyond the view: because a second `Locations` hop *would*
+be unsafe, the transfer-order record modal reads its **addresses out of the record fetch** (FK
+expansion + `calcDepth`), not out of a third `TableViewJoins` row. When a column needs data two hops
+past an already-duplicated table, the answer is usually the record fetch, not another join. See
+[Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
+
 ## Look for an existing unused join before adding one
 
 The `inventory_units` view already carried a Units → Items join
@@ -156,6 +180,19 @@ for fatals lives on [request-logging](../../api2/features/request-logging.md).
 Contrast mode (b), which surfaces a readable message naming a `TableViewJoins.id` — which is exactly
 why it reads like config corruption rather than an ACL gap.
 
+**The drop happens first; whether you get an error depends on the field path.** The join disappearing
+from the result set is the primary effect — a view whose column resolves through the missing join can
+therefore simply **render without that column** rather than throwing. Do not treat "no error" as
+evidence the grant exists. Either way the grant is mandatory: seed it with the view.
+
+**A grant is the whole 4-table chain, not one row.** `AclRecordPermissions` →`AclLogicGroups` →
+`AclLogicGroupExpressions` → `AclRecordExpressions` (see
+[acl-permission-chain](./acl-permission-chain.md)); an `AclRecordPermissions` row with no logic group
+is the failure mode already recorded for the NYCHH tracking bridges. Newer records can have **zero**
+grants of any kind — `Records` **351** (`transfer-order-stages`) had none before
+`Client_Nychh/2026-08-28a`, so the Status column of a brand-new view would have vanished silently.
+Check the joined record's grants before assuming an existing record is grant-covered.
+
 ## Context RecordFieldSettings are OPTIONAL for a joined column to render
 
 `meta()` looks up `contextRecordFieldId`-scoped settings (`DefaultRecordFieldSettings` plus the
@@ -229,6 +266,16 @@ Core-level reference ids used (identical across all clients and environments): *
   writes its transaction log. Canada's fix:
   [Compass Canada item-fulfillment TableViews](../../../../clients/compass-canada/features/item-fulfillment-tableviews.md).
   (bala)
+- 2026-08-28 — Sharpened the duplicate-join rule from "never join a table twice" to **"duplication is
+  harmless unless the duplicated table is a chained join's parent"** (the alias counter seeds `A` with
+  the base table, so the first join takes the bare name that `onB` always emits). Worked example: the
+  new `transfer-orders` view joins `Locations` twice safely because all three ON clauses reference the
+  base table — and the corollary that data two hops past a duplicated table belongs in the record
+  fetch (FK expansion + `calcDepth`), which is why the transfer-order modal's addresses are not a
+  third join. Also refined the ACL note: the missing grant **drops the join first**, so a column can
+  silently disappear with **no** error (no error ≠ grant exists), the grant means the full 4-table
+  chain, and a new record can have **zero** grants — `Records` 351 (`transfer-order-stages`) had none.
+  (apeterson)
 - 2026-08-18 — Documented how `TableViewJoins` compile into SQL after adding a chained
   **Units → Items → Manufacturers** join for the Part Number / Manufacturer / Item Description columns
   on `inventory_units` (Elite + NYCHH): `onB` is emitted with the **raw table name** (so a chain only

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

@@ -58,6 +58,12 @@ it.
 > `TINYINT UNSIGNED NULL … AFTER isFilterable` (matching its sibling flags); the real fan-out
 > migration is still outstanding. Background:
 > [framework branch ahead of schema](../../dbchanges2/workflows/framework-branch-ahead-of-schema.md).
+>
+> **Where the column exists, verified 2026-08-28:** present on **local** and **sandbox-client**
+> (both hand-applied), **absent on production and beta**. Operational consequence for authors: a
+> `TableViewFields` INSERT that **names `isGroupable`** runs fine locally and **fails on prod**. Omit
+> the column from new TableView migrations until the fan-out migration lands — the
+> `Client_Nychh/2026-08-28a` transfer-orders view does exactly that.
 
 ### A column's `type` / `precision` are NOT per-view — they come from `Core.RecordFields`
 
@@ -249,6 +255,10 @@ SalesOrderListingSortByDateOrderDesc.sql`).
   *and* that query — and a grep for the property alone under-reports what a missing column breaks.
 
 ## Change history
+- 2026-08-28 — Pinned **where `isGroupable` actually exists**: present on local and sandbox-client
+  (both hand-applied), **absent on production and beta**. So a `TableViewFields` INSERT naming the
+  column passes locally and fails on prod — omit it from new TableView migrations until the fan-out
+  migration lands (`Client_Nychh/2026-08-28a - TransferOrdersTableView.sql` does). (apeterson)
 - 2026-08-28 — Recorded that **`DESCRIBE` / `information_schema.COLUMNS` hides a composite unique
   key's second column** (`COLUMN_KEY = ''` for `TableViewFields.index`), so `index` looks free right
   up until `Duplicate entry '13-2' for key 'tableviewfields.tableViewId_index'` — read

package/knowledge/2.0/apps/api2/features/v2-rest-query-contract.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-27
+updated: 2026-08-28
 owners: [tcox, bala, apeterson]
 files:
   - api2/Component/Api/V2/V2.php
@@ -16,6 +16,8 @@ related:
   - v2-api-error-codes.md
   - tableview-apiwhereclause-row-filtering.md
   - nested-fk-acl-embedding.md
+  - ../../_underscore/features/calculated-sql-fields.md
+  - ../../toga25-supply/features/transfer-orders-page.md
 ---
 
 ## Summary
@@ -90,6 +92,43 @@ response that walks that collection can 500. Two defences, both cheap:
 The fragility itself is **unfixed** — any depth ≥ 2 response is exposed. Lowering depth removes
 *your* exposure, not the defect.
 
+### ⚠ `calcDepth` defaults to **1** — a calculated field one FK hop out comes back NULL, silently
+
+`calcDepth` bounds how deep `FIELD_SQL` **calculated** fields are evaluated, independently of
+`depth`. At the default of **1** only the requested record's own calculated fields resolve; a
+calculated field on a record reached through an FK returns **`null` with no message** — no `EV-8`,
+no warning, a 200 that merely looks like empty data.
+
+Worked example: `_Model_Client_Location` exposes
+`_addressLine1/_addressLine2/_addressCity/_addressState/_addressZip` as `FIELD_SQL`. Requested from
+a record that only *points at* a Location (`GET /v2/transfer-orders/{uuid}` with the location
+expanded), they need **`calcDepth: 2`**. Rule of thumb: **raise `calcDepth` by one for every FK hop
+between the requested record and the calculated field's model**, and suspect it first whenever a
+calculated field is null on a nested object but correct when that object is fetched directly.
+Definition of the fields themselves:
+[FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
+
+### What nests by default is `InherentRecordChildren` — everything else needs the nested ROUTE
+
+A record's one-to-many children arrive inside the record response **only** if `Core.
+InherentRecordChildren` declares them. `sales-orders` (record 14) has **seven**; plenty of records
+have **none** — `transfer-orders` (312) had **zero** as of 2026-08-28, so `transferOrderItems` never
+appears in the record payload no matter what `fields`/`depth` ask for. The client must call the
+**nested route** instead:
+
+```
+GET /v2/transfer-orders/{uuid}/transfer-order-items
+```
+
+- **The JSON key of an inherent child is the camelCase of the child ROUTE**, not of the table or the
+  model (`V2.php` ~L6310, via `_String::CASE_KEBAB` → `CASE_CAMEL`). `transfer-order-items` →
+  `transferOrderItems`.
+- **Adding an `InherentRecordChildren` row is a breaking-shape change, not a feature flag.** It
+  alters the default response for **every** existing caller of that route — including 1.0 importers
+  and NetSuite sync — so the blast radius has to be surveyed first. The transfer-order build
+  deliberately declined to add one and named the child route in the consuming surface's config
+  instead. See [Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
+
 ### ⚠ `join` / `ojoin` drive the WHERE/filter — NOT the response shape
 
 **`join` and `ojoin` change which rows come back, not what the JSON looks like.** The response
@@ -234,6 +273,14 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
   invisible; re-request with `fields=` to force `EZ-2` and see the denied list.
 
 ## Change history
+- 2026-08-28 — Documented two response-shape facts hit while building the Transfer Orders modal.
+  **`calcDepth` defaults to 1**, so a `FIELD_SQL` calculated field on a record one FK hop out returns
+  `null` with **no** message (Location's `_address*` fields needed `calcDepth: 2`) — raise it one per
+  FK hop. And **what nests by default is `InherentRecordChildren`**: `transfer-orders` (312) has
+  **zero** rows, so `transferOrderItems` never appears in the record payload at any `depth` and the
+  client must call the nested route; the inherent-child JSON key is the **camelCase of the child
+  ROUTE** (`V2.php` ~L6310). Adding an `InherentRecordChildren` row changes the default shape for
+  every existing caller of that route, so it is a breaking change, not a flag. (apeterson)
 - 2026-08-27 — Pinned the **mechanism** behind the silently-ignored uuid-READ `where` to exact code:
   a uuid'd route is classified `ACTION__READ` (`V2.php:3022-3026`) and that branch
   (`V2.php:4399` → ~`5478`) has **no `where` handling at all**; `where` is applied only in

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

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
 | [Re-runnable additive INSERTs (uuid4 in SQL, guards, and the DISTINCT trap)](features/rerunnable-additive-inserts.md) | Most `dbchanges2` files are **additive data grants** run by hand against production, often more than once (once per environment, or twice because someone was no | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql, dbchanges2/Client_Compass/2026-08-28 - GrantViewOrdersRoleSalesOrdersNavigation.sql, dbchanges2/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql |
-| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Quad/2026-07-21b - ApproveDisabledTooltipPoNumber.sql, dbchanges2/Client_Quad/2026-08-21 - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Core/2026-07-29a - SalesOrderApprovalDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-05b - ApprovalDetailsShippingMethodConcatCharge.sql, dbchanges2/Core/2026-08-14a - NoteBadgesVocabularySurface.sql, dbchanges2/Client/2026-08-14a - NoteBadgeThemeTokens.sql, dbchanges2/Client/2026-08-14b - NoteBadgeUserColorFix.sql, dbchanges2/Client_Compass/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Client_CompassCanada/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Core/2026-08-26a - ServiceRequestRecordHeaderSurfaceSeed.sql, dbchanges2/Core/2026-08-26b - ServiceRequestDetailsSurfaceSeed.sql |
+| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | toga25-supply/db-migrations/PLAYBOOK.md, toga25-supply/db-migrations/SURFACE-FEATURE-RUNBOOK.md, dbchanges2/Client_Compass/, dbchanges2/Client_CompassCanada/, dbchanges2/Client_Quad/, dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Quad/2026-07-21b - ApproveDisabledTooltipPoNumber.sql, dbchanges2/Client_Quad/2026-08-21 - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Core/2026-07-29a - SalesOrderApprovalDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-05b - ApprovalDetailsShippingMethodConcatCharge.sql, dbchanges2/Core/2026-08-14a - NoteBadgesVocabularySurface.sql, dbchanges2/Client/2026-08-14a - NoteBadgeThemeTokens.sql, dbchanges2/Client/2026-08-14b - NoteBadgeUserColorFix.sql, dbchanges2/Client_Compass/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Client_CompassCanada/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Core/2026-08-26a - ServiceRequestRecordHeaderSurfaceSeed.sql, dbchanges2/Core/2026-08-26b - ServiceRequestDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | > **A local browser wizard now automates this.** Steps 2–9 below (create DBs, generate Core/API > inserts, append to `Clients_Db.txt`) — plus the dbchanges2 bla | Client/, Client_<Tenant>/, Core/, Logs_Client/ |
 | [Auditing a client DB that drifted from its models (partially applied module migration)](workflows/client-schema-drift-audit.md) | A recurring 2.0 failure mode: **one client's database drifts from what the PHP models declare**, usually because a `_modules/<module>/` migration was applied to | dbchanges2/Client_Growrk/2026-05-28.sql, dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/_modules.txt |
 | [Framework branch running AHEAD of schema — environment-wide 1054/EO-1 after a deploy](workflows/framework-branch-ahead-of-schema.md) | A **third** kind of 2.0 schema drift, distinct from the two already documented: nobody's database went backwards — **the code went forwards**. | _underscore/Model/Core/RecordField.php, _underscore/Model/Client/TableViewField.php, _underscore/Model/Client/TableView.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/Urgency.php, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-14c - RecordFieldsValidationMetadata.sql, dbchanges2/Client/2026-08-14a - RecordFieldSettingsClientTable.sql, dbchanges2/Client/2026-08-13a - UserNavPreferencesClientTable.sql, dbchanges2/Client/2026-08-13c - PersonaNavVisibilityClientTable.sql |