toga-ai 1.0.712 → 1.0.714

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

@@ -37,7 +37,7 @@
 | [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 denial reason (`ApprovalDecisions.note`) — capture, the denial-details card, and the read-only workflow mode](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, toga25-supply/src/layout/RecordApprovalModal/RecordApprovalModalLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx, toga25-supply/src/utils/formatDateTime.ts, dbchanges2/Core/2026-08-31a - SalesOrderDenialDetailsSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-31a - SalesOrderDenialDetailsReadOnlyRules.sql, 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 |

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

@@ -1,19 +1,30 @@
 ---
-title: Sales-order denial reason (`ApprovalDecisions.note`) — captured everywhere, displayed nowhere
+title: Sales-order denial reason (`ApprovalDecisions.note`) — capture, the denial-details card, and the read-only workflow mode
 framework: "2.0"
 repo: _underscore
 project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
-owners: [apeterson]
+updated: 2026-08-31
+owners: [apeterson, tcox]
 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
+  - toga25-supply/src/layout/RecordApprovalModal/RecordApprovalModalLayout.tsx
+  - toga25-supply/src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts
+  - toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx
+  - toga25-supply/src/utils/formatDateTime.ts
+  - dbchanges2/Core/2026-08-31a - SalesOrderDenialDetailsSurfaceSeed.sql
+  - dbchanges2/Client_Compass/2026-08-31a - SalesOrderDenialDetailsReadOnlyRules.sql
   - toga2-commerce/src/pages/OrderDetails/api/OrderDetailsApi.ts
 related:
   - ../../../clients/compass-usa/features/approval-decision-flow.md
@@ -28,11 +39,17 @@ related:
 
 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.
+where it is read, and what displays it.
 
-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.
+**Every tenant already captures it**, so a "show the denial reason" ticket is a pure
+**read/display** feature — no data-capture, no API and no schema work.
+
+**Status (2026-08-31).** In **production the rejection email is still the only consumer.** The
+display feature — a **denial banner** on the SO record modal plus a read-only **approval timeline**
+in the workflow modal — is built, committed and **confirmed rendering on `client-sandbox`**, but not
+released: `toga25-supply` branch **`TRUE-80850`** (`ca6678f`, pushed, **no PR**) and `dbchanges2`
+branch **`TRUE-80850`** (`38ef9ff`, **not merged to `_main`**). Seeds have run on `client-sandbox`
+only. See [Built](#built-2026-08-31--denial-banner--read-only-approval-timeline).
 
 ## Where the value lives
 
@@ -77,7 +94,9 @@ Both consumers read `$payload->note` and fall back to
   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.
+**No other reader exists in any deployed environment.** `toga2-commerce` still renders nothing; the
+`toga25-supply` banner + timeline exist only on the unmerged `TRUE-80850` branches (+ the
+`client-sandbox` seeds).
 
 ### toga2-commerce already fetches it and throws it away
 
@@ -122,19 +141,73 @@ feature.
 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.
+## Built (2026-08-31) — denial banner + read-only approval timeline
+
+The mockup arrived mid-build and **changed the design**: there is **no denial-details card**. The
+denial reason is not surfaced on the record modal at all — it lives one click away, in the workflow
+modal's read-only timeline.
+
+**1. Denial banner** (`SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx`) — full
+width at the **top of the modal body**, rendered by `SalesOrderView`, not by the summary grid. Two
+lines plus a **"View approval workflow"** pill (a native `button`; blox `BaseButton` styling
+conflicted):
+
+> This order was denied at {stage label} · step {N} of {M}
+> {decider} ({role}) denied the order on {MM/DD/YYYY, h:mm A}.
+
+**The reason is deliberately NOT in the banner.** The pill opens the workflow modal, which is
+read-only on a canceled order.
+
+**2. Read-only approval timeline** (`src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx`)
+— in read-only mode `RecordApprovalModalLayout` renders the timeline **instead of**
+`ApprovalFlowForm`: per-stage colored disc (green check approved / red x denied / gray step number
+pending) on a connector rail, a status line "Approved by {name} · {role} · {datetime}", and note
+boxes — gray **"Note"** for approvals, pink **"Reason for denial"** for denials. **No footer**; the
+header X closes. Dialog variant `.approvalDialogReadOnly` (780px, auto height).
+
+The read-only **summary** above the timeline drops `preferredStage`-bound fields (Assigned Manager —
+"who acts next" is meaningless on a decided order) and strips trailing label colons.
+
+**3. Surface 47 is still the gate — it just drives a banner instead of a card.** The
+`salesOrderDenialDetails` section is **excluded from `getVisibleSections`** outright (never a
+summary-grid card); `isDenialDetailsActive(tenantFields, order)` decides the banner: section visible
+**AND** its Tier-1 layout rule passes **AND** `hasDenialDetails(order)` (the ~1% emptiness guard,
+decision 3 below).
+
+**4. Deleted as dead code:** `DenialDetailsCard.tsx`, its `denialDetails` renderer in
+`sectionRenderers.tsx`, and the disabled-form read-only plumbing (`isReadOnly` on
+`ApprovalFlowForm` / `ApprovalStageCard` / `ApprovalFlowDetailInputs`). **The timeline is the only
+read-only path** — do not re-add a "disable the form" branch.
+
+**5. Adapter** (`surfaceBundleToTenantFields.ts`): `config.role` carried onto fields;
+`config.valueType` used **only when the enum column is NULL**; exports `isDenialDetailsActive`,
+`getDeniedStages`, `hasDenialDetails`, `resolvePathInsensitive`, `DENIAL_DETAILS_KEY`,
+`ApprovalStageRecord`. `SalesOrder` type gained `stages` / `currentStage`.
+
+**6. Seeds** (`dbchanges2` branch `TRUE-80850`, `38ef9ff`):
+`Core/2026-08-31a - SalesOrderDenialDetailsSurfaceSeed.sql` (surface **47**, elements **170–176**,
+Messages **227–232**, plus the `readOnlyRule` marker on surface 41) and
+`Client_Compass/2026-08-31a - SalesOrderDenialDetailsReadOnlyRules.sql` (two-stage widening +
+the Admin **`ENABLED_RULE`** as well as `VISIBILITY_RULE` on element 19). Reserved literal ids, plain
+`INSERT`s, verify-the-block SQL in the header. This feature **kept** 47 / 170–176 / 227–232; the
+transfer-order seeds that had reserved the same snapshot were **renumbered** to 53–57 / 190–206 /
+261–284 on 2026-08-31 — see
+[surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md).
+
+Verified on `client-sandbox` 2026-08-31: banner + read-only timeline render for Compass. Test orders
+SA136508, SA136480, SA136473, and **SA134872 (denial with a NULL note — placeholders render)**.
+Tests: 5 vitest files (`ApprovalTimelineView`, `DenialBanner`, adapter, `getVisibleSections`,
+decision-fields), tsc + eslint clean.
+
+## Design decisions (2026-08-28 plan, confirmed and extended by the 2026-08-31 build)
 
 ### 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
+Confirmed as built: `Core.Surfaces` **47** `sales-order-denial-details`, `SurfaceElements`
+**170–176**, `Messages` **227–232** — with **reserved literal ids**, not `AUTO_INCREMENT`, so client
+override files hardcode them and ship prod-ready. Re-verify the block is free before every run; see
 the verify-the-block-is-free rule in
-[surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md).)
+[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
@@ -157,19 +230,23 @@ language) with **no order-status axis**. `VISIBILITY_RULE` and `ENABLED_RULE` ar
 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.
+**Home for the marker (built):** element **176** on surface **41**
+(`sales-order-decision-summary`) — the only surface all three modal modes (approve / deny /
+approvalWorkflow) already fetch. Core default rule: `_status nin ["pendingApproval"]`.
+
+**Role markers are the convention for this whole family** — `sectionLayoutRule`, `titleSuffix`,
+`readOnlyRule`, and the new **`denialReason`** on the note element. A marker is a `config.role`
+string the FE looks for; it is **never** a magic `valueType`.
 
-**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.
+**Use the real `valueType` ENUM member whenever one exists** (`DATETIME` for `dtDecision`). The
+`config.valueType` bypass is reserved for genuinely-missing members, and the FE adapter now falls
+back to it **only when the enum column is NULL**.
 
-### 3. Gate the card with a plain Tier-1 rule + a component emptiness guard
+### 3. Gate it 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.
+don't-render-anything-empty guard in the component (now `isDenialDetailsActive` → `hasDenialDetails`).
+**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
@@ -187,6 +264,71 @@ The frozen rule grammar was confirmed identical on both sides: `eq`/`ne`/`in`/`n
 `lte` — `RULE_OPS` at `_underscore/Model/Core/Surface.php:233` and `FROZEN_OPS` in
 `toga25-supply/src/surface/evaluateSurfaceRule.ts`.
 
+### 4. Decision dates display ABSOLUTE (2026-08-31)
+
+New `src/utils/formatDateTime.ts` (dayjs, `MM/DD/YYYY, h:mm A`). Chosen over the existing
+`formatTimestamp`, which is **relative** ("3 hours ago") and useless on a months-old denial, and over
+native `Date` parsing — MySQL's `YYYY-MM-DD HH:mm:ss` is `Invalid Date` in Safari.
+
+### 5. A read-only widening must target the SAME override scope tier as the existing rows (2026-08-31)
+
+Compass needed the read-only rule widened to two stages
+(`nin ["pendingApproval","pendingInitialApproval"]`). For **element 19** (`approvalWorkflow`) the
+widening had to be written as an **Admin role-scoped** override, not client-wide: a client-wide
+(`roleId NULL`) row is **shadowed** by the pre-existing Admin role-scoped rows under the resolver
+cascade (base < client-wide < persona < role). Element 19 also carries an Admin **`ENABLED_RULE`**
+limited to pending statuses, so widening only `VISIBILITY_RULE` leaves the button visible-but-disabled
+and the modal still cannot open — **both attributes** need widening. Caught by sql-reviewer plus a
+sandbox check of the live override rows. Authoring detail:
+[surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md).
+
+### 6. Stage DISPLAY labels come from client config, not the DB (2026-08-31)
+
+The banner and every timeline row resolve the stage label from the per-client
+`approvalViewFields.recordActionFields.approvalWorkflow.stages[]` entry matching the **step**
+("Admin Review" / "Manager Review"), falling back to `ApprovalTemplateStages.name`. Compass's DB
+names are **status-flavored** ("Pending Initial Approval" / "Pending Approval") and read wrong in
+past tense. **Do not rename the DB stages** — those names feed `_status` and the approval emails;
+display naming belongs in config.
+
+### 7. Step totals come from the MAX step NUMBER, not `stages.length` (2026-08-31)
+
+The per-stage meta fan-out makes `order.stages[]` **transiently partial**, so array length rendered
+"step 2 of **1**" mid-load. Total = `Math.max(...steps)`.
+
+### 8. The stages fetch is gated on the APPROVALS SURFACE toggle (2026-08-31)
+
+`useApprovalModalViewModel` now gates its stages fetch on `sales-order-record-approvals`
+(`isApprovalsSurfaceEnabled`) — the same authoritative per-client gate the record-modal and
+row-state view models use — **not** on `approvalActionStatuses`. The status list excludes canceled,
+so a canceled order fetched no stages and the timeline had nothing to draw; the surface toggle also
+keeps approvals-disabled clients from fetching at all.
+
+### 9. Read-only FAILS CLOSED on a fetch error (2026-08-31)
+
+If the decision-surface fetch **errors**, the rule is unknown → the modal opens **read-only**; a
+**successful** response with no marker (unseeded client) stays **editable**. A transient surface
+outage must never unlock edit + submit on a decided order.
+
+### 10. Copy is config-first with FE fallbacks (2026-08-31)
+
+`modalFields.timelineLabel` / `noteLabel` / `denialReasonLabel` and
+`approvalWorkflow.viewWorkflowButton.label`. **Composed sentences** (the two banner lines, the
+"Approved by … · … · …" status line) remain **FE English** — Compass Canada localization is an open
+follow-up, not an oversight.
+
+## Open items (2026-08-31)
+
+- **Nothing is merged.** `toga25-supply` `TRUE-80850` (`ca6678f`) is pushed but **not PR'd**;
+  `dbchanges2` `TRUE-80850` (`38ef9ff`) is **not merged to `_main`**.
+- **Re-verify the id block immediately before any prod run** — a reservation is a snapshot, not a
+  lock (see [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md)).
+- **Compass Canada**: override file (same two-stage, role-scoped widening) **and** localization of
+  the FE-composed banner/timeline sentences.
+- **Quad** needs an `IS_VISIBLE` opt-in on element 19 first — it cannot open the workflow modal at
+  all today.
+- jcardinal still owes the `2.0/standards/framework-rules.md` reserved-id-exemption review.
+
 ## Gotchas
 
 - **Quad is not a Compass tenant on this path.** `_Model_Quad_ApprovalDecision` implements its own
@@ -203,6 +345,28 @@ The frozen rule grammar was confirmed identical on both sides: `eq`/`ne`/`in`/`n
   Anything keyed on `_status in ["canceled"]` must tolerate a missing decision/note.
 
 ## Change history
+- 2026-08-31 — **Built the display feature planned on 2026-08-28** (resumed apeterson's
+  `denial-reason-surface-plan` session), then **redesigned it mid-build when the mockup arrived**.
+  Final shape: a **denial banner** at the top of the record-modal body (stage label · step N of M,
+  decider + role + absolute datetime, and a "View approval workflow" pill) with the **reason
+  deliberately not in the banner**, plus a read-only **approval timeline**
+  (`ApprovalTimelineView.tsx`) that **replaces** the form in the workflow modal — per-stage discs on a
+  rail, gray "Note" / pink "Reason for denial" boxes, no footer. The planned `DenialDetailsCard` and
+  the disabled-form read-only plumbing were **deleted as dead code**; surface **47** now gates the
+  banner (`isDenialDetailsActive`) and is excluded from `getVisibleSections` entirely. Mode still
+  comes from the `config.role:'readOnlyRule'` marker (el **176** on surface 41), with the
+  decision-surfaces `isLoading` OR'd into `isApprovalLoading` (no editable→read-only flicker) and
+  **fail-closed on fetch error**. Other decisions: stage **display labels** come from client config
+  (Compass DB names are status-flavored — do not rename them); step totals from the **max step
+  number**, not `stages.length` (partial fan-out rendered "step 2 of 1"); the stages fetch is gated on
+  the **approvals surface toggle**, not `approvalActionStatuses` (canceled orders were fetching
+  nothing); `denialReason` is a **role marker, not a magic valueType**; the enum `valueType` wins over
+  `config.valueType`; dates are **absolute** (`formatDateTime`, `MM/DD/YYYY, h:mm A`); and the
+  element-19 widening must be **Admin role-scoped** covering **`ENABLED_RULE` as well as
+  `VISIBILITY_RULE`**. Seeds renamed `2026-08-28a` → **`2026-08-31a`** and committed
+  (`dbchanges2@TRUE-80850` `38ef9ff`); FE committed + pushed (`toga25-supply@TRUE-80850` `ca6678f`,
+  no PR). Verified rendering on `client-sandbox` (SA136508 / SA136480 / SA136473 / SA134872
+  null-note). Open: nothing merged, Compass Canada override + localization, Quad el-19 opt-in. (tcox)
 - 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

package/knowledge/2.0/apps/api2/features/environment-variable-drives-underscore-branch.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
-owners: ["bala", "mhammontree", "apeterson", "jcardinal"]
+updated: 2026-08-31
+owners: ["bala", "mhammontree", "apeterson", "jcardinal", "tcox"]
 files:
   - api2/.ebextensions/git.php
   - api2/.platform/hooks/prebuild/git.sh
@@ -185,6 +185,19 @@ the tier trades a stale-code bug for a total outage. Full procedure:
   method/class that isn't on the box and fatal. Landing `_underscore` first is **safe on its own**:
   the old api2 controller simply doesn't use the new framework code yet. Order: merge `_underscore`
   → (verify it's on the branch) → deploy api2.
+  - **🚨 Worked instance — `client-sandbox` was 100% DOWN on this exact violation (2026-08-31,
+    since fixed by matching the branches and redeploying).** Every request returned 500 `Call to
+    undefined method
+    _Model_Core_AclFieldPermission::resolveFieldPermissions()`. `api2@_sandbox-client`
+    (`Component/Api/V2/V2.php:6198`, commit `0cc37fe` "Delegate ACL field perms to shared resolver",
+    jcardinal 2026-08-14) delegates to a resolver whose `_underscore` half (`a5e79448` "Surface field
+    binding and ACL field resolver", same author/date) exists **only on `_qa-alpha` and
+    `toga25-desk`** — it was never merged to **`_underscore@_sandbox-client`**. Resolved the same day
+    by the team (branches matched + redeployed). **Why a half-shipped ACL refactor is a TOTAL outage,
+    not a partial one:** field-ACL
+    resolution runs on essentially every authenticated GET, so there is no degraded mode — the whole
+    tier 500s and every unrelated feature under test looks broken. When a whole sandbox goes dark,
+    check the two-repo pairing before debugging your own feature.
 - **⚠ A "Could not find required file for `_Model_...`" fatal on prod can be a STALE-BUILD
   artifact, not a missing file.** `Logs.Issue #476`
   ("Could not find required file for '_Model_Client_ItemFulfillments_InventoryAdjustment'") fired
@@ -257,6 +270,16 @@ the tier trades a stale-code bug for a total outage. Full procedure:
 
 ## Change history
 
+- 2026-08-31 — Recorded a **worked instance** of the cross-repo ordering rule: **`client-sandbox`
+  went entirely down** — every request 500'd with `Call to undefined method
+  _Model_Core_AclFieldPermission::resolveFieldPermissions()`. `api2@_sandbox-client` (`V2.php:6198`,
+  `0cc37fe`, 2026-08-14) delegates ACL field permissions to an `_underscore` resolver (`a5e79448`)
+  that lived only on `_qa-alpha` / `toga25-desk` and was never merged to
+  `_underscore@_sandbox-client`; fixed the same day by matching the branches and redeploying.
+  Durable point: a
+  half-shipped **ACL** refactor has no degraded mode — field-ACL resolution runs on nearly every
+  authenticated GET, so the tier is totally dark and unrelated features look broken. Found while
+  testing an unrelated toga25-supply feature. (tcox)
 - 2026-08-28 — Recorded two build-time-clone consequences: (1) **cross-repo deploy ordering** — api2
   clones `_underscore` (`_<ENVIRONMENT>`) at build via `.platform/hooks/prebuild/git.sh`, so for a
   change spanning both repos, `_underscore` must land on the deploy branch **before** api2 is

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

@@ -3,11 +3,12 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [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 migrations (uuid4 in SQL, INSERT guards, the DISTINCT trap, conditional ALTERs)](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 | 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-28b - TransferOrderListActionsSurfaceSeed.sql, 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 |
+| [Re-runnable additive migrations (uuid4 in SQL, INSERT guards, the DISTINCT trap, conditional ALTERs)](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/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-31a - SalesOrderDenialDetailsSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-31a - SalesOrderDenialDetailsReadOnlyRules.sql, 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-28b - TransferOrderListActionsSurfaceSeed.sql, 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 |
 | [Local vs prod MySQL config parity — why “it passed locally” is not evidence](workflows/local-vs-prod-mysql-config-parity.md) | Several migration failures that look like "prod-only bugs" are actually **per-machine MySQL server-configuration differences**. |  |
 | [Repairing non-prod metadata drift (works in prod, broken in beta/dev-sandbox)](workflows/nonprod-metadata-drift-repair.md) | Almost all 2.0 platform behavior is **metadata** — `Core.Records`/`RecordFields`, `Core.RecordScripts`, `Core.ApiPayloadInterceptors`, and per-client `Acl*` row | dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql, dbchanges2/Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Aig/_modules.txt, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, api2/Config/beta.ini, api2/Config/sandbox-dev.ini, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql |
+| [Targeting the right database (tenant restores, and running a change file against the wrong DB)](workflows/targeting-the-right-database.md) | Two ways to point at the wrong database — a dump taken from the wrong host, and a change file piped into the wrong schema. | api2/Config/production.ini, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql |
 | [Verifying whether a dbchanges2 migration actually ran in an environment](workflows/verifying-a-migration-ran.md) | dbchanges2 has no execution ledger you can query — "did this file run here?" has to be answered from the **rows the file would have produced**. | Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, Client/2026-08-13 - UnitsForItemsPO_SalesOrderItemsJoin.sql |

package/knowledge/2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md

@@ -6,11 +6,10 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
-owners: [bala, kyalamarthi]
+updated: 2026-08-31
+owners: [bala, kyalamarthi, apeterson]
 files:
   - 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
 related:
   - ../architecture.md

package/knowledge/2.0/apps/dbchanges2/features/surface-layer-schema.md

@@ -6,9 +6,11 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
-owners: [jcardinal, apeterson]
+updated: 2026-08-31
+owners: [jcardinal, apeterson, tcox]
 files:
+  - dbchanges2/Core/2026-08-31a - SalesOrderDenialDetailsSurfaceSeed.sql
+  - dbchanges2/Client_Compass/2026-08-31a - SalesOrderDenialDetailsReadOnlyRules.sql
   - toga25-supply/db-migrations/PLAYBOOK.md
   - toga25-supply/db-migrations/SURFACE-FEATURE-RUNBOOK.md
   - dbchanges2/Client_Compass/
@@ -563,7 +565,10 @@ All four gated buttons (17/18/19/21) carry the **Core** rule `order._status in [
 so on a **canceled** order the approval-workflow button is **hidden**.
 
 **Next free Core ids in PROD, 2026-08-28:** `Surfaces` **47**, `SurfaceElements` **170**, `Messages`
-**227**, `Actions` **17**. (Re-verify per the 🚨 rule below before writing a seed — "next free" vs
+**227**, `Actions` **17**. **Superseded — on 2026-08-31 (sandbox-client, freshly reset from prod) the
+MAX ids were `Surfaces` 52 / `SurfaceElements` 189 / `Messages` 260, and `Core/2026-08-28a`+`b` then
+claimed `Surfaces` 53–57 / `SurfaceElements` 190–206 / `Messages` 261–284.** (Re-verify per the 🚨
+rule below before writing a seed — "next free" vs
 "highest used" is exactly what caused the 2026-08-24 collision.)
 
 **Per-tenant overrides, as they actually exist in prod:**
@@ -605,6 +610,50 @@ the LIST surface + 4 record-modal SECTION surfaces + the `transfer-order-stage`
 verified free on **local AND production** before authoring. See
 [Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
 
+#### ⚠ Those blocks were RENUMBERED on 2026-08-31 — a reservation expires when someone else ships
+
+The 2026-08-28 blocks above were reserved from a **2026-08-28 snapshot** of production, and were
+**claimed by another feature before the transfer-order files shipped**: `sales-order-denial-details`
+took `Surfaces` **47**, `SurfaceElements` **170–176** and `Messages` **227–232**. Re-verified against
+sandbox-client (freshly reset from production) on 2026-08-31, where MAX ids were `Surfaces` **52** /
+`SurfaceElements` **189** / `Messages` **260**, the two transfer-order files were renumbered to a
+contiguous block above MAX:
+
+| | Reserved 2026-08-28 (stale) | **Live, as committed 2026-08-31** |
+|---|---|---|
+| `Core.Messages` | 227–260 | **261–284** |
+| `Core.Surfaces` | 47–52 | **53–57** |
+| `Core.SurfaceElements` | 170–189 | **190–206** |
+
+`Surfaces` 48–51, `SurfaceElements` 177–186 and `Messages` 233–250 are deliberately left as **unused
+gaps** rather than back-filled — a contiguous block above MAX is trivially verifiable and trivially
+reversible; hunting free holes is neither.
+
+Two durable rules:
+
+1. **A reserved block is a snapshot, not a lock.** Nothing in Core enforces it. **Re-verify the block
+   is still free immediately before the file runs**, not just when it is written, and say so in the
+   file header. The longer a seed sits unmerged, the more likely its block is gone.
+2. **Renumbering is cheap; colliding is not.** Because these seeds use literal ids with plain
+   `INSERT`, a stale block fails loudly on the primary key — which is the designed behavior and the
+   reason `INSERT IGNORE` is banned here (see the 2026-08-24 incident below). Bump to a fresh block
+   above MAX rather than trying to reuse the gap.
+3. **`SELECT MAX(id)` cannot see a block reserved by a seed that has not RUN.** A DB check only
+   reflects applied migrations, so a same-day sibling sitting unmerged in another developer's tree is
+   invisible to it. Verifying a block means querying the target Core **and** checking the in-flight
+   `Core/*SurfaceSeed.sql` files (this doc's block list is the shared record of them).
+
+**The filename suffix is a separate check from the id block.** The denial-details pair was authored
+as `2026-08-28a` and renamed to **`2026-08-31a`** because a committed
+`Core/2026-08-28a - API 2.0 Stability Monitor Cron.sql` already held that date+letter. A free
+date+letter says nothing about a free id block, and vice versa — check both.
+
+> These explicit ids are **correct and required**, not a portability bug. `Core.Surfaces` /
+> `Core.SurfaceElements` / `Core.Messages` are reserved-literal tables precisely so a `Client_*`
+> override file can inline them without a cross-cluster `Core.*` read. Do not "fix" a surface seed
+> into a `messageKey`-resolving `INSERT … SELECT`: the client-side references have no way to resolve
+> a Core id at runtime.
+
 **⚠ The reserved blocks are not an inventory of every surface id — pre-2026-08-21 surfaces sit
 outside them.** The reserved-id discipline begins at the reseed, so surfaces seeded before it took
 plain `AUTO_INCREMENT` ids: the **`navigation`** TAB_STRIP is `Core.SurfaceElements` **109–114**
@@ -692,6 +741,26 @@ Quad disabled-tooltip statement now does this). Relevant to `Client_Quad/2026-08
 SalesOrderDecisionSummaryOverride.sql`, whose header wrongly implies a pre-existing row is
 necessarily the correct row.
 
+### 🚨 A client-wide override is SHADOWED by an existing role-scoped row — widen at the SAME tier (2026-08-31)
+
+The resolver cascade is **base < client-wide < persona < role** (last write wins — see
+[surface-resolver](../../_underscore/features/surface-resolver.md)). So a `roleId NULL` (client-wide)
+row **does nothing** for any user whose role already has a row for that `(element, attribute)`: the
+role-scoped row is applied after it and wins. Writing the widening client-wide "for everyone" is the
+natural authoring instinct and it is **inert for exactly the users who need it**.
+
+Concrete: widening element **19** (`approvalWorkflow`) so Compass admins can open a canceled order
+read-only had to be an **Admin role-scoped** `UPDATE`-then-`INSERT` (role resolved at runtime by
+`Roles.name = 'Admin'`, guarded `IS NOT NULL`), because `Client_Compass` already holds Admin
+role-scoped rows on that element (sandbox: id 3 `IS_VISIBLE`, id 10 `VISIBILITY_RULE`, id 20
+`ENABLED_RULE`). Caught by sql-reviewer before the run.
+
+**And widen every attribute that gates the control, not just visibility.** Element 19 also carries an
+Admin **`ENABLED_RULE`** limited to pending statuses, so widening `VISIBILITY_RULE` alone leaves the
+button visible-but-**disabled** and the modal still cannot open. Before authoring a rule widening,
+`SELECT` the element's existing override rows and read **every** row's scope *and* attribute — the
+answer is in the data, not in the base seed.
+
 ## Migration maintenance — fold-back (⚠ the local-only window has CLOSED)
 
 > **Superseded 2026-08-21/24.** The Surface layer **has been pushed to production** (a hand-picked
@@ -978,6 +1047,28 @@ hits `Duplicate entry '251' for key 'messages.PRIMARY'`. The resolution that kee
   `config.valueKey` when it lives in the page.
 
 ## Change history
+- 2026-08-31 — Added the **denial-details** seed pair (`Core/2026-08-31a -
+  SalesOrderDenialDetailsSurfaceSeed.sql` — Surface **47**, elements **170–176**, Messages
+  **227–232**, plus a `readOnlyRule` marker on surface 41; and `Client_Compass/2026-08-31a -
+  SalesOrderDenialDetailsReadOnlyRules.sql`). Committed on branch **`TRUE-80850`** (`38ef9ff`), **not
+  merged to `_main`**; run on **`client-sandbox` only** and confirmed rendering there. (This is the
+  feature that claimed 47/170–176/227–232 and forced the transfer-order renumber above.) Two
+  authoring rules: **a client-wide (`roleId NULL`) override is shadowed by an existing role-scoped
+  row**, so the Compass read-only widening on element 19 had to be an Admin **role-scoped**
+  `UPDATE`-then-`INSERT` — and it had to widen the Admin **`ENABLED_RULE`** as well as
+  `VISIBILITY_RULE`, or the button stays visible-but-disabled; and **`SELECT MAX(id)` cannot see a
+  block reserved by a seed that has not run**, so a block check must also sweep in-flight seed files.
+  Also noted the filename date+letter is an independent check from the id block (this pair was
+  renamed off `2026-08-28a`, already taken by a committed Core file). (tcox)
+- 2026-08-31 — **Renumbered the transfer-order reserved blocks** to `Messages` **261–284**,
+  `Surfaces` **53–57**, `SurfaceElements` **190–206**: the 2026-08-28 blocks were reserved from a
+  snapshot and `sales-order-denial-details` claimed `Surfaces` 47 / `SurfaceElements` 170–176 /
+  `Messages` 227–232 first. New rule — **a reserved block is a snapshot, not a lock; re-verify it is
+  free immediately before the file RUNS, not just when it is written**, and bump to a contiguous
+  block above MAX (leaving gaps) rather than back-filling. Also recorded explicitly that literal
+  Core ids in a surface seed are **required, not a portability bug**, so nobody "fixes" one into a
+  `messageKey`-resolving `INSERT … SELECT`. From `Core/2026-08-28a`/`b`, committed in `dbchanges2`
+  `1c3fe2e`. (apeterson)
 - 2026-08-28 — **Extended the transfer-order reserved blocks** to `Messages` **227–260**, `Surfaces`
   **47–52**, `SurfaceElements` **170–189** (`Core/2026-08-28b`, the `transfer-orders-list-actions`
   BUTTON_BAR; all ids verified free on local **and** production first). Three authoring rules added: