toga-ai 1.0.251 → 1.0.253

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

@@ -8,5 +8,5 @@
 | [Column Visibility (URL-driven show/hide columns)](features/column-visibility.md) | A "Columns" header button that opens a modal listing every column from the table meta, lets the user show/hide columns, adjusts the table live, and persists the | toga25-supply/src/components/ColumnVisibilityModal/, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/, toga25-supply/src/hooks/useTableCellInteractions.ts |
-| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
+| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

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

@@ -11,7 +11,11 @@ owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
   - toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts
+  - toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts
   - toga25-supply/src/surface/evaluateSurfaceRule.ts
   - toga25-supply/src/surface/actionRegistry.ts
@@ -56,15 +60,18 @@ feature flag — see below). Backend: [surface-resolver](../../_underscore/featu
   **structural fingerprint**: `looksLikeBundle` now requires **both** an `elements` array **and** a
   `surface` descriptor object (not the `elements` array alone — see the decoy gotcha below).
   `extractBundle(raw, slug)` then **prefers** the bundle whose `surface.slug === slug`, falling back to
-  first-found, so a stray sibling bundle can't win. `looksLikeGroup` requires the documented `group`
-  discriminator key so a single-bundle envelope is not mistaken for a group. On a malformed payload it
+  first-found, so a stray sibling bundle can't win. On a malformed payload it
   falls back to a safe empty bundle (empty `elements` + empty `messages`/`theme`/`vocabularies` maps)
   so the page never crashes.
 - **`useFetchSurfaceMetaGroup(slugs[])`** — the grouped sibling of `useFetchSurfaceMeta`, for a screen
   needing many section surfaces at once. **Order-insensitive** (the slug list is normalized so cache
   hits don't depend on argument order), `staleTime: Infinity`, hits the grouped endpoint
-  `GET /v2/surfaces/meta-group?slugs=...`, and extracts the `{surfaces}` map via `extractGroup()` /
-  `looksLikeGroup()` (the same structural-fingerprint approach as `extractBundle`). Returns `{}` for
+  `GET /v2/surfaces/meta-group?slugs=...`, and extracts the SLUG-keyed `{surfaces}` map via the
+  recursive **`findSurfaceMap(raw, depth=5)`** — which walks the envelope tree and returns the
+  `surfaces` map whose **values look like bundles** (or an empty/null map), uniquely identifying the
+  inner slug-keyed map regardless of nesting or `data` wrapping. (`extractGroup`'s old
+  `data`/`data.<key>` probe and the `looksLikeGroup` `group`-discriminator check were both removed —
+  see the group-nesting gotcha below for why.) Returns `{}` for
   unmigrated screens (`enabled:false`), so a non-roster client does no fetch.
 - **`componentRegistry`** (`src/surface/componentRegistry.tsx`) — the **presentation sibling** of
   `actionRegistry`, both keyed by the surface meta's `action.key`. `actionRegistry` maps key→behavior
@@ -154,6 +161,17 @@ three bespoke renderers `detailSection`/`locationCard`/`totalsCard` are untouche
   `getDetailSections` are untouched — **only the SOURCE of section config moves JSON → Surface.**
   Business logic stays in code: the recurring-lease `_totalLease` gate in the grid and approval
   gating are **not** moved. (Registered-renderer seam: *config describes, code decides.*)
+- **Full adapter-seam data path (verified this session, no direct `<SurfaceSection>`):**
+  `useFetchSurfaceMetaGroup(SALES_ORDER_SURFACE_SLUGS)` → `surfaceBundleToTenantFields(surfaces)` →
+  merged into `tenantFields` (roster clients only; `clientSlug` is the **uppercased** `getHostname()`
+  result matched against the roster) → **`buildPatchedTenantFields`** (which only overrides
+  `recordActionFields`, so it **preserves all surface section keys**) → `SalesOrderView` →
+  **`SalesOrderSummaryGrid`** (renders by `section.type` / `cardType`:
+  `detailSection`/`locationCard`/`totalsCard`, where `cardType` comes from `surface.config.cardType`)
+  + **`getDetailSections`** (reads `section.isVisible` for the `displayToggle` sections, which carry a
+  `sectionVisibility` marker element). **Decision (confirmed by the developer this session): KEEP the
+  adapter approach — do NOT replace it with a direct `<SurfaceSection>` swap.** The bespoke grid
+  renderers and the `TenantFields` seam are the deliberate integration point.
 - **Roster gate — `SALES_ORDER_SURFACE_MIGRATED_CLIENTS = [COMPASS, COMPASSCANADA, QUAD]`** (an
   in-code roster in `surfaceBundleToTenantFields.ts`; the view-model
   `useSalesOrderRecordModalLayoutModel.tsx` consults it). The view-model resolves sections from
@@ -182,6 +200,27 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   bundle → the action bar renders nothing. Fix: `looksLikeBundle` must require **both** `elements` AND
   a `surface` descriptor; use recursive `findBundle` + slug-preferring `extractBundle` (see How it
   works). The durable backend follow-up is to confirm/stabilize the single-meta envelope contract.
+- **The GROUPED meta envelope double-nests the slug-keyed `surfaces` map under an OUTER route-keyed
+  `surfaces` slot — match by value shape, never grab the first `surfaces`.** The meta-group V2 envelope
+  mirrors single-meta's bundle nesting: the real SLUG-keyed map sits one level deeper under a ROUTE-keyed
+  outer slot — `{ surfaces: { "meta-group": { group, surfaces: { "order-details": bundle, … } } },
+  elements: [] }`. The old `extractGroup` grabbed the **first** `surfaces` it saw (the outer route-keyed
+  one, whose values are *group* objects, not bundles), so `surfaces["order-details"]` was `undefined`
+  and `surfaceBundleToTenantFields` produced `{}` — every migrated-client SalesOrders section vanished.
+  Fix: recursive **`findSurfaceMap(raw, depth=5)`** returns the `surfaces` map whose **values look like
+  bundles** (or null/empty), uniquely identifying the inner slug-keyed map regardless of nesting or
+  `data` wrapping. Verified by trace across 6 envelope shapes (double-nested, resolver-return-at-top,
+  simple, data-wrapped, null-child, empty). **Note:** an earlier attempt that required a top-level
+  `group` discriminator on the probed level (`looksLikeGroup`) broke the fetch (returned `{}`) because
+  the V2 envelope carries no top-level `group` at that level — `looksLikeGroup` was removed entirely.
+- **For migrated clients, a dropped (`surface: null`) display section silently vanishes — there is no
+  JSON fallback left.** Once a client's JSON section blocks are deleted (roster migration), a section
+  whose surface resolves to `surface: null` (a seed/ACL gap, e.g. `additional-order-details` /
+  `admin-notes` / `notes`) is dropped by `surfaceBundleToTenantFields` and the section disappears with
+  no fallback. That is a backend seed/ACL gap, **not** an FE bug. Separately, two sections are
+  intentionally gated in `getDetailSections`: `shipments` is **permanently hidden** (the view-model
+  hardcodes `shipmentsData: []` and `useShipments` is commented out; the section gates on
+  `shipmentsData.length > 0`), and `invoices` is data-gated on `invoiceData.length > 0`.
 - **The surface `record` shape must match the rule field namespace — wrap as `{ order }`.** Seeded
   Tier-1 rules namespace their field as `order._status`, so `getByPath(record, "order._status")` only
   resolves if the host passes `record={{ order }}`. Passing the bare order object resolves to
@@ -210,6 +249,19 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-06-30 — Follow-up: fixed the GROUPED meta fetch returning `{}` (every migrated-client
+  SalesOrders section had vanished). The meta-group envelope double-nests the slug-keyed `surfaces`
+  map under an outer ROUTE-keyed `surfaces` slot; the old `extractGroup` grabbed the first (outer,
+  group-valued) `surfaces`. Replaced it with recursive `findSurfaceMap(depth=5)` that returns the
+  `surfaces` map whose values are bundle-shaped (verified across 6 envelope shapes). **Reverted the
+  earlier same-session `group`-discriminator `looksLikeGroup` change** — requiring a top-level `group`
+  broke the fetch; `looksLikeGroup` removed entirely. Verified the SalesOrders section migration is
+  fully wired via the adapter seam (`useFetchSurfaceMetaGroup` → `surfaceBundleToTenantFields` →
+  `buildPatchedTenantFields` (overrides only `recordActionFields`) → `SalesOrderSummaryGrid` /
+  `getDetailSections`) and confirmed the decision to KEEP the adapter over a direct `<SurfaceSection>`.
+  Documented why some sections stay hidden (`shipments` hardcoded empty; `invoices` data-gated; and a
+  dropped `surface: null` display section vanishes with no JSON fallback for migrated clients — a
+  seed/ACL gap). (apeterson)
 - 2026-06-30 — Migrated the SalesOrders record-modal sections onto Surface for the roster clients
   [COMPASS, COMPASSCANADA, QUAD] via the registered-renderer seam: added `useFetchSurfaceMetaGroup`
   (order-insensitive grouped `/surfaces/meta-group` fetch) + `surfaceBundleToTenantFields()` (adapts
@@ -221,7 +273,7 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
 - 2026-06-30 — Debugged + extended the client-side action-bar renderer (no client-specific work).
   Fixed three rendering bugs: (1) the single-meta envelope's **decoy `elements: []`** masked the real
   nested bundle — `looksLikeBundle` now requires `elements` AND a `surface` descriptor, with recursive
-  `findBundle(depth=4)` + slug-preferring `extractBundle` + `group`-discriminator `looksLikeGroup` +
+  `findBundle(depth=4)` + slug-preferring `extractBundle` +
   safe empty `messages`/`theme`/`vocabularies` fallback (`useFetchSurfaceMeta.ts`); (2) Tier-1 rules
   always false because the host passed the bare order object instead of the `{ order }` envelope the
   `order.*` field namespace requires (`SalesOrderTopBar.tsx`); (3) every action icon rendered as

package/knowledge/sessions/2026-06-30-surface-section-migration-fe-apeterson.md

@@ -0,0 +1,69 @@
+---
+type: session
+slug: surface-section-migration-fe
+title: Surface action-bar + SalesOrders section migration — FE fixes
+author: apeterson
+repos: [toga25-supply]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-06-30
+updated: 2026-06-30
+---
+
+# Session: surface-section-migration-fe
+**Date:** 2026-06-30
+**Project/Repo:** toga25-supply (2.0)
+**Task:** Make the Surface presentation layer actually render in the SalesOrders record modal — fix the action-bar (BUTTON_BAR) rendering, the grouped section fetch/extraction, Tier-1 rule evaluation, icons, and add a meta-driven custom-component path — all in the toga25-supply React frontend (no backend/DB this session).
+
+---
+
+## What WORKED
+<!-- Include specific file paths and evidence -->
+- **`extractBundle` single-meta decoy fix** — `src/surface/useFetchSurfaceMeta.ts`. The single-meta envelope `{ surfaces: { meta: <bundle> }, elements: [] }` has a decoy empty top-level `elements: []`. Tightened `looksLikeBundle` to require BOTH an `elements` array AND a `surface` object; replaced hard-coded raw/data probing with recursive `findBundle(raw, predicate, depth=4)`; `extractBundle(raw, slug)` now PREFERS the bundle whose `surface.slug === slug`, falling back to first-found. Trace verified: action-bar payload → 5 elements (was 0); direct/`data`/`data.meta` shapes still resolve. Type-check clean.
+- **Grouped fetch `extractGroup` double-nesting fix** — `src/surface/useFetchSurfaceMeta.ts`. The meta-group envelope double-nests the slug-keyed `surfaces` map under an OUTER route-keyed `surfaces` slot: `{ surfaces: { "meta-group": { group, surfaces: { "order-details": bundle, ... } } } }`. Old `extractGroup` grabbed the outer (route-keyed) map → `surfaces["order-details"]` undefined → `surfaceBundleToTenantFields` returned `{}`. Replaced `looksLikeGroup` + the data-probe with recursive `findSurfaceMap(raw, depth=5)` that returns the `surfaces` map whose VALUES look like bundles (or null/empty). Trace verified across 6 shapes (double-nested, resolver-return-at-top, simple, data-wrapped, null-child, empty). Type-check clean.
+- **Tier-1 rule record envelope** — `src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx`. Rules use field `order._status`, but the component passed the bare order; `getByPath(order,"order._status")` → undefined → all gates false. Fixed by passing `record={order ? { order } : null}`. Trace: `{order:{_status:"pendingApproval"}}` → true; `fulfilled` → false. `evaluateSurfaceRule.ts` was NOT the bug.
+- **Icon resolution** — `src/surface/SurfaceActionBar.tsx`. `tokens.icon` is a literal FontAwesome name, not a theme-token slug; running it through `resolveThemeToken` (theme map has only color/bg keys) made every icon fall back to "check". Fixed to `element.tokens?.icon ?? "check"`; removed the now-unused `resolveThemeToken` import.
+- **Meta-driven component registry** — NEW `src/surface/componentRegistry.tsx` (presentation sibling of `actionRegistry`, keyed by `action.key`). `"salesOrder.viewLog"` → `<ViewLogButton label onOpenLog={onActivate} />`. `SurfaceActionBar.renderElement` calls `getSurfaceComponent(element.action?.key)` and renders it (keyed Fragment) before the default icon button. Type-check clean.
+- **Section migration verified end-to-end (adapter seam)** — data path: `useFetchSurfaceMetaGroup(SALES_ORDER_SURFACE_SLUGS)` → `surfaceBundleToTenantFields(surfaces)` → merged into `tenantFields` (migrated clients only) → `buildPatchedTenantFields` (only overrides `recordActionFields`, so it PRESERVES all surface section keys) → `SalesOrderView` → `SalesOrderSummaryGrid` (renders by `section.type` cardType) + `getDetailSections` (reads `section.isVisible`). Full project type-check: zero errors.
+- **Debug cleanup** — removed all debug `console.log`s from the viewModel (×3), `SalesOrderRecordModalLayout.tsx`, and `getDetailSections.tsx`. `grep` confirms none remain; type-check clean.
+- **Two `/capture` runs PUSHED** to team `_main`, updating `2.0/apps/toga25-supply/features/surface-frontend.md` (owners `[jcardinal, apeterson]`), including corrections of two stale notes from the first capture.
+
+## What did NOT work — DO NOT RETRY THESE
+<!-- Exact failure reasons — do not vague-ify -->
+- **Requiring a `group` discriminator key in `looksLikeGroup`** — added during the review pass to disambiguate single-vs-group. It RETURNED `{}` for the grouped fetch because the V2 envelope does not carry a top-level `group` at the probed level (the single-meta envelope has none either). Reverted, then `looksLikeGroup` removed entirely in favor of `findSurfaceMap`. DO NOT re-add a `group`-key requirement.
+- **Matching the bundle/group on `elements` array ALONE** — the original `looksLikeBundle`/`looksLikeGroup` fingerprint. An empty `elements: []` decoy (single) and the outer route-keyed `surfaces` (group) both satisfied it, returning the wrong node. Must additionally require a `surface` descriptor (bundle) / match by bundle-shaped values (group).
+- **Branching the custom component on `renderType === "BUTTON"`** — rejected by the user as "not driven by surface meta" — it hardcodes a component to a whole render category. Use the `action.key`-keyed `componentRegistry` instead (the chosen approach).
+
+## Not tried yet (candidates for next session)
+- **Seed/ACL fixes for the display-section surfaces** (`additional-order-details`, `admin-notes`, `notes`) — if still missing at runtime, their surface resolves `surface: null` and the adapter drops the key (no JSON fallback for migrated clients). This is the paused Track B (prod cross-cluster seed work), NOT an FE fix. See session `surface-layer` (jcardinal) for the prod cross-cluster blocker.
+- **Re-enable `shipments`** — currently permanently hidden: `useShipments` is commented out and the viewModel hardcodes `shipmentsData: []`; `getDetailSections` gates on `shipmentsData.length > 0`. Re-wire `useShipments` if shipments need to render.
+- **Runtime verification on a migrated client** — confirm on a `COMPASS`/`COMPASSCANADA`/`QUAD` hostname that the cards + detail sections render from Surface and the action bar shows all five buttons with correct icons.
+- **Backend: stabilize the single-meta / meta-group envelope contract** so the FE shape-probing (`findBundle`/`findSurfaceMap`) can eventually relax.
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| src/surface/useFetchSurfaceMeta.ts | modified | `findBundle` + slug-preferred `extractBundle`; `findSurfaceMap` + `extractGroup`; `looksLikeGroup` removed. Type-check clean. |
+| src/surface/SurfaceActionBar.tsx | modified | renames (element/surfaceMeta/recordSurfaceState); literal `tokens.icon`; `componentRegistry` branch; debug logs gone. |
+| src/surface/componentRegistry.tsx | created | NEW presentation registry keyed by `action.key`; `salesOrder.viewLog` → ViewLogButton. |
+| src/pages/.../view/sections/SalesOrderTopBar.tsx | modified | `record={order ? { order } : null}` envelope for Tier-1 rules. |
+| src/pages/.../viewModel/useSalesOrderRecordModalLayoutModel.tsx | modified | debug logs removed; surface→tenantFields merge intact (unchanged logic). |
+| src/pages/.../SalesOrderRecordModalLayout.tsx | modified | removed stray `console.log(error)`. |
+| src/pages/.../helpers/getDetailSections.tsx | modified | removed `console.log(tenantFields)`. |
+| src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx | modified | PRE-EXISTING change from session start — NOT touched this session; review separately. |
+| .claude/ | untracked | local harness mirror; not part of this work. |
+
+## Decisions made
+- **Keep the adapter seam for section migration; do NOT replace with direct `<SurfaceSection>`** (user-confirmed). Rationale: the adapter (`surfaceBundleToTenantFields` → `tenantFields` → existing renderers) is complete and keeps business logic (the `_totalLease` recurring gate, card styling) in code; a direct-`<SurfaceSection>` rewrite would re-home all that for no functional gain. Rejected: per-section `<SurfaceSection surfaceSlug record/>` like SurfaceActionBar.
+- **Custom components via an `action.key`-keyed `componentRegistry`** (sibling of `actionRegistry`), not a `renderType` branch. Rationale: fully meta-driven, same extensibility model as the existing registries; adding a custom button = one surface element + one registry entry.
+- **Shape-probe by value, not by key/path** — both `findBundle` and `findSurfaceMap` identify the target by structural shape (bundle = `surface` + `elements`; slug-keyed map = values are bundles) and walk the tree, rather than hard-coding the V2 envelope nesting. Rationale: robust across route/version envelope changes.
+
+## Blockers
+- **Display-section surfaces may not be seeded/granted** for the migrated clients — if `additional-order-details`/`admin-notes`/`notes` are still missing at runtime, that is a seed/ACL (Track B) gap, not FE. Track B (prod cross-cluster Client seed rewrite) remains user-paused pending prod Core ids (see session `surface-layer`).
+
+## Exact next step
+> On a migrated-client hostname (`clientSlug` === `COMPASS`/`COMPASSCANADA`/`QUAD`), open a sales order and inspect the network response for `GET /v2/surfaces/meta-group` plus the resolved `surfaces` object: confirm the slug-keyed bundles for `order-details`, `ship-to`, `bill-to`, `order-summary`, `order-recurring`, `invoices`, `notes`, `admin-notes`, `additional-order-details`. For any whose bundle is `surface: null`, that slug is a seed/ACL gap (Track B) — list them and hand off to the backend seed pass; everything that resolves should now render via the verified adapter path.
+
+---
+_Saved by /session-save on 2026-06-30_

package/package.json

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