toga-ai 1.0.713 → 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

@@ -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 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 | 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 |
+| [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 |

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

@@ -7,8 +7,10 @@ client: shared
 type: feature
 status: active
 updated: 2026-08-31
-owners: [jcardinal, apeterson]
+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/
@@ -636,6 +638,15 @@ Two durable rules:
    `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_*`
@@ -730,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
@@ -1016,6 +1047,19 @@ 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 /

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

@@ -12,7 +12,7 @@
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/layout/PrimaryTableServerLayout/PrimaryTableServerLayout.tsx, toga25-supply/src/layout/PrimaryTableServerLayout/types.ts, toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/GenericNestedTables.tsx, toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/hooks/useTableCellInteractions.ts, toga25-supply/src/hooks/useServerTableUrlState.ts, toga25-supply/src/layout/RecordApprovalModal/helpers/handleFormatApprovalWorkflowPayload.ts, toga25-supply/src/layout/RecordApprovalModal/api/approvalDecisionsApi.ts |
 | [Side navigation & default route — an empty nav renders a BLANK PAGE and gets reported as "cannot log in"](features/side-navigation-and-default-route.md) | The 2.5 side nav is **100% backend-driven** by the `navigation` surface bundle, and the same list also decides **which routes exist** and **where `/` lands**. | toga25-supply/src/routes.tsx, toga25-supply/src/layout/AppLayout/viewModel/useAppLayoutViewModel.ts, api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [SSO redirect & public-vs-user session gating (useAuthenticationFlow)](features/sso-redirect-and-session-gating.md) | How 2.5 Supply decides, on every navigation, whether an anonymous visitor should be bounced to their client's SSO IdP instead of the local `/login` form. | toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/src/routes.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/api/api.ts |
-| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/App.tsx, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/layout/RecordApprovalModal/, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/useServiceRequestRecordModalLayoutModel.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
+| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/App.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/SalesOrderRecordModal.module.css, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/SalesOrderApprovalModalsLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/RecordApprovalModalLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css, toga25-supply/src/utils/formatDateTime.ts, toga25-supply/src/utils/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/layout/RecordApprovalModal/, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/useServiceRequestRecordModalLayoutModel.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [Talos Integration (AppLayout host + adapter wiring)](features/talos-integration.md) | toga25-supply is the first host of the shared blox [Talos assistant](../../toga-blox/features/talos-assistant.md). | toga25-supply/src/layout/AppLayout/AppLayout.tsx, toga25-supply/src/components/Header/Header.tsx, toga25-supply/src/components/Header/Header.module.css, toga25-supply/src/index.css, toga25-supply/src/assets/talos-owl.png |
 | [Transfer Orders page (TableView → Core surfaces → React page + record modal)](features/transfer-orders-page.md) | The Transfer Orders screen — list + read-only record modal — built end to end on 2026-08-28 from a Claude Design prototype. | toga25-supply/src/pages/TransferOrders/TransferOrders.tsx, toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts, toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrdersTableLayout/TransferOrdersTableLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/hooks/useTransferOrderRecord.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/viewModel/useTransferOrderRecordModalLayoutModel.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/view/TransferOrderRecordView.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/CreateTransferOrderModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/index.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferableItemRows.ts, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/routes.tsx, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json, toga25-supply/.env.development |

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

@@ -6,10 +6,18 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
-owners: [jcardinal, apeterson]
+updated: 2026-08-31
+owners: [jcardinal, apeterson, tcox]
 files:
   - toga25-supply/src/App.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/SalesOrderRecordModal.module.css
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/SalesOrderApprovalModalsLayout.tsx
+  - toga25-supply/src/layout/RecordApprovalModal/RecordApprovalModalLayout.tsx
+  - toga25-supply/src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx
+  - toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css
+  - toga25-supply/src/utils/formatDateTime.ts
+  - toga25-supply/src/utils/index.ts
   - toga25-supply/src/surface/evaluateSurfaceRule.ts
   - toga25-supply/src/layout/RecordApprovalModal/
   - toga25-supply/src/contexts/AuthContext.tsx
@@ -397,6 +405,91 @@ element (surface-owned binding); the FE owns the *resolution mechanics*.
   semantics). Quad overrides field sort/visibility on the same card. Core seeds the shared content
   (shipping-method + currency-charge concat, Order-For inline email path).
 
+## A surface section can drive a BANNER instead of a grid card (2026-08-31)
+
+`sales-order-denial-details` (surface 47) is the first section surface whose resolved config renders
+**outside the summary grid**: `getVisibleSections` **excludes** `DENIAL_DETAILS_KEY` unconditionally,
+and `SalesOrderView` renders `<DenialBanner>` at the top of the modal body when
+**`isDenialDetailsActive(tenantFields, order)`** — section visible **AND** its Tier-1 layout rule
+passes **AND** `hasDenialDetails(order)`. Same three-part gate shape as `isApprovalDetailsActive`.
+
+The takeaway: **a surface section is a config unit, not a placement contract.** Where it renders is
+an FE decision (the layout/geometry boundary below); the surface only says whether it applies and
+what is in it.
+
+- **Stage-relative valueKeys.** The section's element valueKeys resolve against `order.stages[]`
+  (`DecidedBy._name`, `ApprovalDecisions.note`, `dtDecision`) via `resolvePathInsensitive` — not the
+  order root, and not via `config.preferredStage` (which pins *one* stage). A third valueKey
+  namespace alongside `order.`-prefixed header keys and bare section keys.
+- **Emptiness guard in the component, not in the rule.** The Tier-1 `order._status in ["canceled"]`
+  rule also fires on administratively-canceled orders (~1%) — see "measure the gap" below.
+- **Step totals: use the MAX step NUMBER, never `stages.length`.** The per-stage meta fan-out leaves
+  `order.stages[]` transiently partial, which rendered "step 2 of **1**" mid-load.
+- **Stage display labels come from client config** — the `approvalWorkflow.stages[]` entry matching
+  the step, falling back to `ApprovalTemplateStages.name` (Compass's DB names are status-flavored:
+  "Pending Initial Approval").
+
+**Adapter changes** (`surfaceBundleToTenantFields.ts`): `config.role` is carried **onto the field**;
+`config.valueType` is used **only when the element's `valueType` enum column is NULL** — the enum
+wins. New exports: `isDenialDetailsActive`, `getDeniedStages`, `hasDenialDetails`,
+`resolvePathInsensitive`, `DENIAL_DETAILS_KEY`, `ApprovalStageRecord`.
+
+**Dates are ABSOLUTE.** New `src/utils/formatDateTime.ts` (dayjs, `MM/DD/YYYY, h:mm A`). The
+pre-existing `formatTimestamp` is **relative** ("3 hours ago") and wrong for a months-old decision,
+and native `new Date(...)` on the API's MySQL `YYYY-MM-DD HH:mm:ss` string is **`Invalid Date` in
+Safari** — always parse these with dayjs.
+
+**Design note:** the banner's "View approval workflow" pill is a **native `button`** — blox
+`BaseButton` variants fought the pill styling.
+
+Seed side + the Compass override: [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md);
+subject doc: [sales-order-denial-reason](../../_underscore/features/sales-order-denial-reason.md).
+
+## `readOnlyRule` — a marker rule that puts the approval-workflow modal in view-only mode (2026-08-31)
+
+The second live use of "a marker's rule selects a MODE" (below). A hidden
+`config.role: 'readOnlyRule'` element (**el 176**) was added to the **existing**
+`sales-order-decision-summary` surface (41) — the only surface all three modal modes fetch — and the
+FE reads its resolved `visibilityRule` as a mode flag, not as visibility.
+
+Chain: `surfaceBundlesToDecisionFields` exposes **`workflowReadOnlyRule`** →
+`useApprovalModalViewModel` computes **`isWorkflowReadOnly`** → `RecordApprovalModalLayout`
+`isReadOnly`.
+
+**Read-only SWAPS THE VIEW — it does not disable the form.** `RecordApprovalModalLayout` renders
+**`ApprovalTimelineView`** in place of `ApprovalFlowForm`: per-stage colored disc (green check /
+red x / gray step number) on a connector rail, a "Approved by {name} · {role} · {datetime}" status
+line, and note boxes (gray "Note", pink "Reason for denial"). No footer — the header X closes;
+dialog variant `.approvalDialogReadOnly` (780px, auto height). The first implementation *did* thread
+`isReadOnly` through `ApprovalFlowForm` / `ApprovalStageCard` / `ApprovalFlowDetailInputs` to disable
+controls; when the mockup arrived that plumbing was **deleted as dead code**. **Do not re-add a
+"disable the form" branch** — a read-only view of a form is a different component, not the same
+component with everything greyed out, and keeping both means every future form change must be
+correct twice.
+
+The read-only summary above the timeline also **drops `preferredStage`-bound fields** (Assigned
+Manager = "who acts next", meaningless once decided) and strips trailing label colons.
+
+Rules this establishes:
+
+- **No marker seeded → behaves exactly as before.** A mode marker must default to the old behavior,
+  so an unseeded client is untouched.
+- **⚠ FAIL CLOSED on a fetch error.** `isWorkflowReadOnly` returns `true` when the decision-surface
+  fetch **errors** (the rule is unknown); only a *successful* empty response means editable. A
+  transient surface outage must not unlock edit + submit on a decided order.
+- **⚠ Gate the modal's skeleton on the mode fetch.** The decision-surfaces `isLoading` is **OR'd
+  into `isApprovalLoading`**, so the skeleton stays up until the mode is known. Without that the
+  modal renders **editable and then flips read-only** — a visible flicker on a control that decides
+  whether a user can act.
+- **Gate dependent fetches on the SURFACE TOGGLE, not on a status list.** The view model's
+  approval-stages fetch now keys off `sales-order-record-approvals`
+  (`isApprovalsSurfaceEnabled`) — the same authoritative gate the record-modal and row-state view
+  models use — instead of `approvalActionStatuses`, which excludes `canceled` and so starved the
+  timeline of stages on exactly the orders it exists for.
+- **Copy is config-first with FE fallbacks** (`modalFields.timelineLabel` / `noteLabel` /
+  `denialReasonLabel`, `approvalWorkflow.viewWorkflowButton.label`). Composed sentences stay FE
+  English — localization for Compass Canada is an open follow-up.
+
 ## Two FE rule engines (surface Tier-1 vs legacy named-rule) — do not conflate
 
 There are **two** rule evaluators in this app. As of 2026-07-21 the surface evaluator now has a
@@ -454,12 +547,10 @@ family. Reach for this whenever the variation is **status-aware**, because `isVi
 static booleans with no status axis, and whenever the control must stay interactive (a modal's
 "view only" mode cannot be expressed by disabling the button that opens it).
 
-**Read-only approval-workflow modal — what already exists (2026-08-28).** Roughly half the rendering
-is already in place: `ApprovalFlowDetailInputs.tsx` computes
-`areInputsDisabled = !isPreApproved && stageHasApprovalDecision`, and `StageHasDecisionView.tsx`
-already renders a decided stage's decision label plus its note in a disabled/readOnly textarea. The
-gaps are specific: stages with **no** decision still render editable, `ApprovalStageCard`'s
-approve/deny radios are not status-gated, and the submit path is not gated.
+**Known role markers:** `sectionVisibility` (section on/off), `sectionLayoutRule` (el 108, layout),
+`approvalsGate` (el 24), `titleSuffix`, `readOnlyRule` (el 176, modal mode — built 2026-08-31, see
+above), `denialReason` (identifies the note field on the denial-details card). A new one is a
+`config.role` string plus the FE that looks for it — **never** a magic `valueType`.
 
 ### `resolveElementState` — the flag composition
 `resolveElementState.ts` computes an element's `isEnabled` as **`staticFlag AND enabledRule AND
@@ -594,6 +685,11 @@ here is a cross-screen change. Re-check Sales Orders, Items and Vendor Items aft
 
 ## Gotchas
 
+- **A vitest file that reaches `@agilant/toga-blox` must stub the whole package:
+  `vi.mock("@agilant/toga-blox", () => ({}))`.** blox's `dist` entry imports `global.css`, which
+  node's ESM loader rejects, so **any** import chain that transitively pulls blox in fails to load
+  the test file (not the assertion — the file). Every surface adapter/component test needs the stub;
+  it is the reason a new test can fail before a single expectation runs.
 - **The VIP `/contacts` API call is gated by an approval-details element's `labelSuffix.valueKey`,
   NOT by the element's `isVisible`.** `useSalesOrderVip.ts` decides whether to call `/contacts`
   (which reads `Users.c_isVip`) by scanning the approval-details surface for an element whose
@@ -796,6 +892,28 @@ button except **View Log** renders and does nothing on click. Whether the SR mod
 actions surface is **still an open decision**, not an oversight.
 
 ## Change history
+- 2026-08-31 — **Built** the sales-order **denial banner** + read-only **approval timeline**
+  (`toga25-supply@TRUE-80850` `ca6678f`, pushed, no PR; verified rendering on `client-sandbox`).
+  Two durable FE patterns. (1) **A surface section can drive a BANNER, not a grid card**:
+  `DENIAL_DETAILS_KEY` is excluded from `getVisibleSections` outright and `SalesOrderView` renders
+  `DenialBanner` when `isDenialDetailsActive` (visible AND Tier-1 rule AND `hasDenialDetails` — the
+  ~1% empty-cancel guard); a surface section is a **config unit, not a placement contract**. Its
+  valueKeys are **stage-relative** (`order.stages[]` via `resolvePathInsensitive`, a third namespace
+  distinct from `config.preferredStage`); step totals must come from the **max step number** because
+  the per-stage fan-out leaves `stages[]` transiently partial ("step 2 of 1"); stage **display
+  labels** come from client config, not the status-flavored DB names. (2) **Read-only SWAPS THE
+  VIEW**: `RecordApprovalModalLayout` renders `ApprovalTimelineView` instead of `ApprovalFlowForm`
+  (discs + rail, gray Note / pink Reason-for-denial boxes, no footer, `.approvalDialogReadOnly`), and
+  the earlier `isReadOnly`-disables-the-form plumbing in
+  `ApprovalFlowForm`/`ApprovalStageCard`/`ApprovalFlowDetailInputs` was **deleted as dead code** —
+  do not re-add it. Mode still comes from the `readOnlyRule` marker (el 176, surface 41) and now
+  **fails closed on fetch error**; the skeleton is gated on the mode fetch (no editable→read-only
+  flicker); the stages fetch moved onto the **approvals surface toggle** (`approvalActionStatuses`
+  excludes `canceled`, starving the timeline). Adapter carries `config.role` onto fields and uses
+  `config.valueType` **only when the enum column is NULL**; new absolute `formatDateTime`
+  (`MM/DD/YYYY, h:mm A`; `formatTimestamp` is relative and native `Date` parsing of MySQL datetimes
+  is `Invalid Date` in Safari). Added the vitest `vi.mock("@agilant/toga-blox")` requirement (blox
+  `dist` imports `global.css`). 5 test files, tsc + eslint clean. (tcox)
 - 2026-08-28 — **`SurfaceActionBar` labeled mode now honours `element.variant`** (shared infra):
   `renderMode="labeled"` had hardcoded `variant="secondaryAction"` for every button, so a `PRIMARY`
   seed could never render as primary. Added an `element.variant` → `BaseButton` variant map with a

package/package.json

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