toga-ai 1.0.591 → 1.0.593

package/knowledge/1.0/apps/library/features/error-capture-1-0.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
+updated: 2026-08-17
 owners: ["jcardinal", "mhammontree"]
 files:
   - library/app/error/capture.php
@@ -177,6 +177,15 @@ exists in `api2`/`worker2`. So 1.0 reads the AL1 container config at
 
 ## Gotchas / known issues
 
+- **⚠ A grouped `Logs.Issue` row can show a STALE error id — read the live api2 transaction log for
+  the current error.** Two facts combine to mislead: (1) `Event.errorMessage` is **`varchar(255)`**,
+  so a long API response is **truncated** — often before the trailing error id; and (2)
+  `Logs.Issue.subject` / `Issue.errorMessage` hold the **first-occurrence** text, so a long-lived
+  issue keeps showing the error id from whenever it was first seen even after the per-call error has
+  changed. Observed 2026-08-17: issue `3H` still displayed `EO-1` / `3G-6` (the original
+  undefined-method fatal) while the current per-call failure was actually `EV-11` (an FK 1451 on a
+  DELETE). **To see what is failing *now*, read the live api2 transaction log
+  (`Logs_<client>.Api.responsePayload`) for the specific call — not the grouped `Issue` row.**
 - **Any PHP warning inside capture code would kill the request.** 1.0's
   `App_Error::handleError()` routes **every** PHP warning into `handleException()`, which renders
   the red box and calls `exit()` — so a single warning raised while capturing (an unreachable IMDS
@@ -220,6 +229,12 @@ exists in `api2`/`worker2`. So 1.0 reads the AL1 container config at
 
 ## Change history
 
+- 2026-08-17 — Recorded a diagnostic trap: a grouped `Logs.Issue` row can show a **stale error id**
+  because `Event.errorMessage` is `varchar(255)` (truncates a long API response, often before the
+  error id) and `Issue.subject`/`errorMessage` keep the **first-occurrence** text — observed issue
+  `3H` still showing `EO-1`/`3G-6` while the live per-call error was `EV-11` (FK 1451). Read the live
+  `Logs_<client>.Api.responsePayload` for the actual current error. Surfaced diagnosing the Compass
+  USA NetSuite SO sync freeze. (jcardinal)
 - 2026-08-05 — Recorded the legacy `DELETE_DOA_PRE-SENTRY_error.php` handler leaking the full
   config array (prod DB / SES / NetSuite / Payeezy / SSL Store credentials + ticket PII) on a
   live towfoundation.togaview.com error page, meaning that host evaluates as dev mode in

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-17
 owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
@@ -328,6 +328,16 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
   **and** the consuming code. (The general 2.0-side metadata behavior — reverse relations resolved via
   the child model's `FOREIGNKEY_MODEL` and named as the camelCase plural of the child model — is a
   framework-level fact captured separately.)
+- **⚠ Depth alone does NOT return every reverse-hasMany collection — `GET /sales-orders` at depth 4
+  omits `itemFulfillmentItems` and `invoiceItems`.** Verified 2026-08-17 against prod
+  `Logs_Compass.Api` responses (no fields whitelist): a depth-4 sales-order GET returns
+  `salesOrderItems` and the **PO-link bridge** collections
+  (`salesOrderItemPurchaseOrderItems`, `purchaseOrderItemSalesOrderItems`) but **not**
+  `itemFulfillmentItems` or `invoiceItems`. So any importer code that guards on
+  `$salesOrderItem->itemFulfillmentItems` / `->invoiceItems` from that GET is a **silent no-op** —
+  same reverse-hasMany trap as above, now with a concrete consequence: the NetSuite SO renumber fix
+  keys off a recorded "could-not-delete" set instead of trusting those collections (see
+  [NetSuite → TOGa Supply per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md)).
 - **`TOGA_AIG.Customers.emailAddress` is `varchar(255)`** (V1 legacy, latin1_swedish_ci) — wide
   enough to hold several `'; '`-joined emails, so TRUE-79401 needed **no** schema/dbchanges migration
   (the earlier fear that it was ~VARCHAR(55) was wrong) — but **it is a real ceiling: ~6–7
@@ -386,6 +396,13 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-08-17 — Recorded that **depth-4 `GET /sales-orders` omits the `itemFulfillmentItems` and
+  `invoiceItems` reverse-hasMany collections** (it does return `salesOrderItems` and the PO-link
+  bridges), verified against prod `Logs_Compass.Api` — so code guarding on those collections from
+  that GET is a silent no-op, reinforcing the reverse-hasMany-fields trap. Surfaced fixing the
+  NetSuite SO renumber freeze (Compass USA), which now keys off a recorded "could-not-delete" set;
+  see [NetSuite → TOGa Supply per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md).
+  (jcardinal)
 - 2026-08-12 — Recorded the **`send()` return contract**: it always returns a response carrying
   `isSuccess` (early-returns on true, falls through to `return $response` on false, throws when the
   property is absent), so `empty($response->isSuccess)` is a safe failure check on anything it

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-12
+updated: 2026-08-17
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -87,13 +87,28 @@ its IDLE write. **There is no timeout, memory cap, or resource limit anywhere in
 never *tune the window size down*. (Corollary: a window that has grown back to the cap is positive
 evidence the section is completing.)
 
-### ⚠ A per-record API failure does NOT stop the cursor — the record is skipped forever
-
-The cursor write (`LAST_SYNC_DATETIME_*`) and `finishModeIteration()` both run **unconditionally
-after** the record loop. A record that throws mid-loop is captured to Sentry and **stepped over**,
-while the section still reports success and advances the cursor past its window. So
-**"section IDLE + cursor advancing" is not proof of a complete import** — it only proves the run
-didn't die.
+### ⚠ Per-record isolation is SECTION-SPECIFIC — and SALES_ORDERS has NONE (corrected 2026-08-17)
+
+Whether a bad record is "stepped over" or freezes the section depends entirely on whether **that
+section's** record loop wraps the `sync*FromNetsuite()` call in a per-record `try/catch`. It is not
+uniform across the six sections, and the earlier blanket claim here ("a per-record failure does not
+stop the cursor — the record is skipped forever") is **false for the SALES_ORDERS section**.
+
+- **Where a section DOES isolate per record:** the cursor write (`LAST_SYNC_DATETIME_*`) and
+  `finishModeIteration()` run after the loop, so a caught record is skipped and the section still
+  reports IDLE and advances. There, **"section IDLE + cursor advancing" is not proof of a complete
+  import** — it only proves the run didn't die (recovery = rewind the cursor; re-import is
+  idempotent).
+- **⚠ SALES_ORDERS has NO per-record `try/catch`.** The `SALES_ORDERS` foreach in
+  `common_sync_togasupply.php` (~L637-673) calls `App_Api_Toga2::syncSalesOrderFromNetsuite()`
+  **bare**. `send()` throws on any non-success by default, so **one poison order throws, propagates,
+  and aborts the whole section BEFORE** the cursor PUT + `finishModeIteration()`. The mode stays
+  `1-RUNNING`, the watermark freezes, the window shrinks ÷3 each run, and the **same** order is
+  re-tried and re-throws every 5 minutes — a permanent freeze, not a skip. So a stuck
+  `SALES_ORDERS` at `1-RUNNING` with a days-frozen watermark means **it is throwing on a specific
+  order** (go read the live api2 transaction log for that client — see the poison-order gotcha
+  below). The "shrinking window is a bug signal" rule still holds; the "record is stepped over"
+  corollary does **not** for this section.
 
 Proven concretely on Elite: sales order **169441** (NetSuite internal id 4624062, trandate
 2024-04-15, customer PO `BEGGS/04152024/…`) was simply absent from `Client_Elite.SalesOrders`
@@ -361,9 +376,46 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   a new line is actually created. Full root cause, the prod cleanup migration, and the
   deploy-fix-before-cleanup sequencing live in the
   [Compass ODP Duplicate PO-Line Cleanup](../../../clients/compass-usa/workflows/odp-duplicate-po-line-cleanup.md).
+- **⚠ A single un-deletable renumbered line could freeze the entire SALES_ORDERS section (fixed
+  2026-08-17).** When NetSuite renumbers a line, `syncSalesOrderFromNetsuite` renumbers by
+  **DELETE `/sales-order-items/{uuid}` then re-create in the per-item loop**. Its "pinned row" guard
+  only skipped rows carrying `itemFulfillmentItems` / `salesOrderItemPurchaseOrderItems` /
+  `purchaseOrderItemSalesOrderItems`; an **INVOICED** line
+  (`InvoiceItems.salesOrderItemId`, `ON DELETE RESTRICT`) was **not** guarded, so the DELETE failed
+  with MySQL **1451** → api2 **EV-11** 400, and — because the SALES_ORDERS loop has no per-record
+  `try/catch` (see the corrected gotcha above) — the throw aborted the section, freezing Compass USA
+  for ~5 days (`NETSUITE_EXECUTION_MODE_SALES_ORDERS='1-RUNNING'`, watermark stuck at
+  `2026-08-12 06:13:26`) while it re-tried the same poison order every run (SO **7447** /
+  `SalesOrderItem` 47828, invoiced by `InvoiceItem` 25515). **Fix (library-only, PHP 7.2-safe, no
+  signature changes)** in `syncSalesOrderFromNetsuite`: (1) the renumber-DELETE now passes
+  `$throwExceptionOnApiError=false`, checks `empty($resp->isSuccess)`, and records any row it cannot
+  delete in a new `$pinnedRenumberLineUniqueKeys` set (keyed by `c_netsuiteLineUniqueKey`); (2) the
+  per-item PUT loop treats a row in that set as **pinned** — it keeps its current `lineNumber` (no
+  `UNIQUE(salesOrderId,lineNumber)` collision) and its PUT is made non-throwing + `error_log` **for
+  pinned rows only** (normal rows keep throw-on-error so real failures still surface); (3) the
+  trailing "remove dropped items" DELETE now skips `invoiceItems` and checks `isSuccess`. Net: **no
+  single order can freeze the section again regardless of which `RESTRICT` child blocks a delete**;
+  the invoiced line simply stays at its existing `lineNumber` (a documented unresolvable
+  NetSuite-vs-invoiced case). Deploy `library` only — no SQL, no other repos — then the section
+  completes, mode flips IDLE, and the backlog backfills idempotently. Note the collection guard added
+  for `invoiceItems` is **best-effort only**: depth-4 `GET /sales-orders` does **not** return the
+  `itemFulfillmentItems` or `invoiceItems` reverse-hasMany collections (only the PO-link bridges), so
+  the fix keys off the recorded "could-not-delete" set rather than trusting those collections — see
+  [App_Api_Toga2 client & bridge](../../library/features/toga2-api-client-and-bridge.md).
 
 ## Change history
 
+- 2026-08-17 — Fixed a Compass USA ~5-day SALES_ORDERS freeze: an **invoiced** line that NetSuite
+  renumbered could not be DELETEd (FK `InvoiceItems.salesOrderItemId` `RESTRICT` → MySQL 1451 →
+  api2 EV-11), and because the SALES_ORDERS loop has **no per-record `try/catch`** the throw aborted
+  the whole section (mode stuck `1-RUNNING`, watermark frozen, poison order SO 7447 re-tried every
+  run). `syncSalesOrderFromNetsuite` now makes the renumber-DELETE non-throwing, records
+  un-deletable rows in a `$pinnedRenumberLineUniqueKeys` set, and keeps a pinned row at its existing
+  `lineNumber` with a non-throwing PUT (normal rows still throw on error); the trailing dropped-item
+  DELETE now skips `invoiceItems` and checks `isSuccess`. **Corrected** the prior gotcha that claimed
+  a per-record failure never stops the cursor — that is **section-specific and false for
+  SALES_ORDERS**, which has no per-record isolation. Library-only deploy; no SQL/other repos.
+  Diagnosis touched worker/api2/_underscore (read-only). (jcardinal)
 - 2026-08-12 — TRUE-80499 (Elite onboarding, shared-engine work). **Fixed** the sparse-client
   `TypeError`: the two per-client item lookups are now initialised at
   `common_sync_togasupply.php:74-75` instead of only inside the items loop, so a client whose items

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

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

package/knowledge/2.0/apps/api2/features/api-payload-interceptors.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-14
-owners: ["mhammontree", "dfranks", "bala", "snaredla"]
+updated: 2026-08-17
+owners: ["mhammontree", "dfranks", "bala", "snaredla", "jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
   - api2/Controller/Index.php
@@ -448,6 +448,13 @@ and the failing environment**. It is a small table, and the drift is usually exa
 
 ## Change history
 
+- 2026-08-17 — Corroborated that the unguarded-dispatch fatal is **systemic, not client-specific**:
+  the prod "undefined method" issue bucket (`Logs.Issue` ref 3G / id 59) grouped **both**
+  `_Model_Compass_Usa_SalesOrderItem::postPost()` **and** `_Model_Elite_SalesOrder::postPut()` — two
+  different tenants, one shared fragility. (This was the original Compass USA failure on 2026-08-12,
+  before it was mitigated on the 2.0 side and the client's NetSuite sync progressed to an unrelated
+  FK failure downstream.) Reinforces the standing fix direction: guard all four `V2.php` call sites
+  with `method_exists()`. Investigation only, no code change. (jcardinal)
 - 2026-08-14 — TRUE-80489, from building the Compass inactive-standalone-item order guard.
   (1) **A PRE interceptor on a PARENT record fires on the nested child POST, with the CHILD as the
   payload.** `POST /sales-orders/{uuid}/sales-order-items` resolves `SalesOrders` as the

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

@@ -12,6 +12,8 @@ files:
   - _underscore/Model/Client/TableView.php
   - api2/Component/Api/V2/V2.php
   - dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql
+  - dbchanges2/Core/2026-08-17a - ItemFulfillmentQuantityFieldTypeNumber.sql
+  - dbchanges2/Client/2026-08-17a - ItemFulfillmentColumnsCopyable.sql
 related:
   - tableview-apiwhereclause-row-filtering.md
   - ../../toga25-supply/features/meta-driven-table-data.md
@@ -33,7 +35,20 @@ it.
 - **`Client_*.TableViews`** — one row per view (per client DB, e.g. `Client_Nychh`).
 - **`Client_*.TableViewFields`** — one row per **column** of a view. Key columns: `recordFieldId`
   (which field this column shows), `tableViewJoinId` (which join in the view the field is reached
-  through), `slug` (the frontend/tanstack column id), `isVisible` (0 = projected-but-hidden).
+  through), `slug` (the frontend/tanstack column id), `isVisible` (0 = projected-but-hidden),
+  and the per-view **presentation flags** `isCopyable` / `isSortable` / `isFilterable`. These
+  four flags **are** per-view — the same underlying field can be copyable in one view and not in
+  another.
+
+### A column's `type` / `precision` are NOT per-view — they come from `Core.RecordFields`
+
+A field's rendered **type and precision are canonical**, read from the shared
+`Core.RecordFields.type` / `Core.RecordFields.precision` — there is **no per-view type/precision
+override** on `TableViewFields`. Changing `Core.RecordFields.type`/`precision` therefore changes
+the column's type/format **everywhere that field appears, for every client**. That is the
+intended canonical behavior — if you only want the change in one view, this mechanism cannot do
+it. (Reference: `Core.RecordFields` id 369 = `ItemFulfillmentItems.quantity` set to
+`type=NUMBER`, `precision=0`, which normalizes that column across all fulfillment views/clients.)
 - **`Client_*.TableViewJoins`** — the view's joins; also drive `options.join`/`ojoin` on the data
   request (see [tableview-apiwhereclause-row-filtering](tableview-apiwhereclause-row-filtering.md)).
 
@@ -87,9 +102,17 @@ per-client folder — the reference migration
 - **Make column migrations idempotent** (`NOT EXISTS` guard) — they run per client DB.
 - **`isVisible=0` still costs a fetch** — the field is selected into the projection; only the render
   is suppressed.
+- **`type`/`precision` are canonical (Core-wide), not per-view.** Editing `Core.RecordFields`
+  changes every view/client that shows the field; there is no per-view type override. `isCopyable`,
+  `isSortable`, `isFilterable`, `isVisible` are the per-view knobs (on `TableViewFields`).
 
 ## Change history
 
+- 2026-08-17 — Documented that a column's `type`/`precision` are canonical from `Core.RecordFields`
+  (no per-view override — a change hits every view/client) while `isCopyable`/`isSortable`/
+  `isFilterable`/`isVisible` are per-view `TableViewFields` flags. Confirmed setting
+  `Core.RecordFields` id 369 (`ItemFulfillmentItems.quantity`) to `type=NUMBER precision=0` and
+  toggling `isCopyable` per-view on the shared item-fulfillment table views. (apeterson)
 - 2026-07-20 — Documented the backend TableView column-metadata model (per-client
   `TableViews`/`TableViewFields`/`TableViewJoins`, `recordFieldId` → shared `Core.RecordFields`
   cross-DB ref, `isVisible=0` projected-but-hidden columns) and the dbchanges2 recipe for adding a

package/knowledge/2.0/apps/toga-blox/features/primary-table-templates.md

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
+updated: 2026-08-17
 owners: [apeterson]
 files:
   - toga-blox/src/templates/PrimaryTable/PrimaryTable.tsx
@@ -80,7 +80,13 @@ Sticky columns use a `--sticky-offset` CSS variable summed from neighboring colu
 - Frozen widths measure only **mounted** rows; virtualized tables size from the first paint set.
 - `headerSpan` adds a separate top row (`colSpan`); only the leaf header row maps to colgroup.
 - Resize is non-persistent (local state, resets when columns change).
+- **A visible column can look "missing" under `shrinkColumns`.** `shrinkColumns` (modal tables)
+  freezes each column to its measured header+body content width, so a column whose content is
+  minimal collapses to a sliver and appears absent even though it built. If a column seems gone,
+  confirm `isVisible=1` first (that is the only real gate), then look at its shrink/freeze width —
+  not the column set.
 
 ## Change history
+- 2026-08-17 — Noted that under `shrinkColumns` a genuinely visible column can render at a sliver width and look "missing" — check `isVisible` and the measured/frozen width, not the column set (apeterson).
 - 2026-06-23 — Documented the three Primary Table entry points, measure-and-freeze sizing, virtualization, and sticky columns (apeterson).
 - 2026-06-22 — Added `shrinkColumns` / `minColumnWidth` shrink-to-fit for modal tables; freeze logic uses natural content width (apeterson).

package/knowledge/2.0/apps/toga-blox/features/table.md

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
+updated: 2026-08-17
 owners: [apeterson]
 files:
   - toga-blox/src/components/Table/index.ts
@@ -134,8 +134,31 @@ Per-column header controls, each a popover trigger with `data-active` / `data-op
 - The filter `includes` mode treats comma-separated values as OR.
 - `EditableCell` currency formats **on blur**, phone formats **on keystroke**.
 - Cell type config (`columnTypeConfig` prop) overrides the hardcoded `COLUMN_TYPE_CONFIG`.
+- **Field `type`/`precision` come from the backend `Core.RecordFields`, not from the table-view
+  field.** `resolveCellType` keys off `tableViewField.type` but that value is populated upstream
+  from the shared Core RecordField — there is no per-view type override. Changing a column's type
+  or precision is a `Core.RecordFields` DB change (see
+  [api2 tableview-field-metadata](../../api2/features/tableview-field-metadata.md)), not a blox
+  change. `isCopyable`/`isVisible`/`isSortable`/`isFilterable` *are* per-view flags.
+- **The only column-visibility gate is `field.isVisible`.** `buildTanstackColumns` builds a column
+  for every visible field. The `accessorFn` walks the `tableViewField` dot-path
+  (`SalesOrderItems.lineNumber` → `row.SalesOrderItems.lineNumber`), so a joined/context field is
+  blank unless `tableViewMeta.joins` actually provides the join. `settings.contextTable`/
+  `contextField` are used **only** to resolve the column *label* (`useAssignTableFieldLabels`),
+  never for data fetching. A visible column can still *look* missing when `shrinkColumns` freezes
+  it to a tiny width because its measured header+body content is minimal (see
+  [primary-table-templates](primary-table-templates.md)).
+- **Table/surface meta is cached with `Infinity` staleTime/gcTime** (`useFetchTablePageMeta`), so
+  after a DB metadata change (`TableViewFields`, `Core.RecordFields`) a **hard reload** is required
+  to see it. And the app consumes toga-blox's built **`dist/`**, not `src/` — editing blox source
+  requires `npm run build` before it takes effect at runtime.
 
 ## Change history
+- 2026-08-17 — Added gotchas on meta→column mapping: field `type`/`precision` come from
+  `Core.RecordFields` (not per-view) while `isCopyable`/`isVisible`/`isSortable`/`isFilterable` are
+  per-view; `isVisible` is the only column gate; `accessorFn` dot-walks and needs the join;
+  `contextTable`/`contextField` drive labels only; meta is cached `Infinity` (hard reload after DB
+  meta change) and the app runs `dist/` (rebuild required). (apeterson)
 - 2026-06-23 — Documented the Table component layers, cell types, filters/sorts, hooks, and theming (apeterson).
 - 2026-06-23 — `HeaderFilterSearch`: search icon hidden on input focus; `data-active` added to the icon span; clear button no longer widens the input (fixed-width menu); mode dropdown excludes the selected mode (apeterson).
 - 2026-06-22 — Column sizing reworked to measure-and-freeze using natural content width; `MIN_COLUMN_WIDTH` floor (120px) applies only when no explicit width is set (apeterson).

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

@@ -9,7 +9,7 @@
 | [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 |
 | [Force Logout on Deployment (useDeploymentGuard)](features/force-logout-on-deployment.md) | On large deployments the backend bumps the Core parameter `META_LAST_REFRESH_DATETIME`. | toga25-supply/src/hooks/useDeploymentGuard.tsx, toga25-supply/src/App.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
-| [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/GenericNestedTables.tsx, toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json, toga25-supply/src/hooks/useTableCellInteractions.ts, toga25-supply/src/hooks/useServerTableUrlState.ts, toga25-supply/src/layout/RecordApprovalModal/helpers/handleFormatApprovalWorkflowPayload.ts, toga25-supply/src/layout/RecordApprovalModal/api/approvalDecisionsApi.ts |
+| [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/PrimaryTableServerLayout/PrimaryTableServerLayout.tsx, toga25-supply/src/layout/PrimaryTableServerLayout/types.ts, toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/GenericNestedTables.tsx, toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json, toga25-supply/src/hooks/useTableCellInteractions.ts, toga25-supply/src/hooks/useServerTableUrlState.ts, toga25-supply/src/layout/RecordApprovalModal/helpers/handleFormatApprovalWorkflowPayload.ts, toga25-supply/src/layout/RecordApprovalModal/api/approvalDecisionsApi.ts |
 | [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

package/knowledge/2.0/apps/toga25-supply/features/record-modals-and-nested-tables.md

@@ -6,9 +6,11 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-14
+updated: 2026-08-17
 owners: [apeterson]
 files:
+  - 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/
@@ -92,6 +94,13 @@ caches the unfiltered first render (uuid null) and never refetches. Guard with `
 when uuid is null, `additionalData` returns `{}`. Typically `isPaginationEnabled: false` +
 `isInfiniteScrollingEnabled: true` (but see [meta-driven-table-data](meta-driven-table-data.md)).
 
+**Read-only (non-clickable) modal tables — `disableRowClick`.** `PrimaryTableServerLayout` takes
+an optional `disableRowClick?: boolean` (its `types.ts`); when set it passes `onRowClick={undefined}`
+to `PrimaryTableServerTemplate` so rows render non-interactive (no cursor/hover affordance, no
+navigation). `ItemFulfillmentModal` sets it because the fulfillment table is read-only. It is
+scoped so all other `PrimaryTableServerLayout` consumers keep normal row-click behavior — pass it
+only for genuinely read-only tables.
+
 ## Pattern 5 — `GenericNestedTables` (config-driven multi-level / swap tables)
 
 A config-driven renderer: declare an array of `TableLevel` objects instead of hand-wiring each
@@ -204,6 +213,9 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
   calling `apiDelete(route)`.
 
 ## Change history
+- 2026-08-17 — Added `disableRowClick?: boolean` to `PrimaryTableServerLayout` (passes
+  `onRowClick={undefined}` to the template) for read-only modal tables; `ItemFulfillmentModal` uses
+  it. Scoped so other consumers keep normal row-click behavior. (apeterson)
 - 2026-08-14 — Fixed unassigning an approval-workflow stage: clearing the assignee now emits a
   DELETE `/approval-decisions/{uuid}` (the assignment lives on the `ApprovalDecisions` record)
   instead of silently dropping the field. Gated to fire only for a still-undecided stage

package/knowledge/clients/compass-canada/profile.md

@@ -6,6 +6,7 @@ apps:
   - api2
   - toga2-supply
   - toga25-supply
+  - toga-blox
   - toga2-commerce
   - worker
   - worker2
@@ -15,7 +16,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-08-12
+updated: 2026-08-17
 owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:

package/knowledge/clients/compass-usa/profile.md

@@ -6,6 +6,7 @@ apps:
   - api2
   - toga2-supply
   - toga25-supply
+  - toga-blox
   - toga2-commerce
   - worker
   - worker1.5
@@ -17,7 +18,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-08-13
+updated: 2026-08-17
 owners: [jcardinal, bala, tcox, apeterson, dfranks]
 files: []
 related:

package/knowledge/clients/nychh/profile.md

@@ -6,6 +6,7 @@ apps:
   - api2
   - toga2-supply
   - toga25-supply
+  - toga-blox
   - dbchanges2
   - worker2
   - worker
@@ -14,7 +15,7 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-08-05
+updated: 2026-08-17
 owners: ["jcardinal", "apeterson", "bala"]
 files: []
 related:

package/package.json

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