toga-ai 1.0.608 → 1.0.609

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

@@ -39,6 +39,7 @@
 | [_String helpers — ASCII-safe HTML entity encoding (and the parseBetween trap)](features/string-html-entity-helpers.md) | `_String` is the 2.0 framework's static string utility class. | _underscore/String.php |
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Client_Compass/2026-07-15f - SalesOrderRecordActionsRemoveDeadConfigRuleOverrides.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php, api2/Component/Api/V2/V2.php |
 | [Table-View Hyperlink Columns (meta → ACL → computed URL → render)](features/tableview-hyperlink-columns.md) | Any 2.0 table-view column can render its value as a clickable link instead of plain text. | _underscore/Model/Client/TableView.php, _underscore/Model/Client/TrackingNumber.php, api2/Component/Api/V2/V2.php, toga2-supply/src/api/toga.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/convertData.tsx, toga2-supply/src/components/ui/Tables/hooks/useDataTableState.tsx, dbchanges2/Client/2026-07-20 - TrackingNumberHyperlinkAndFieldPermission.sql |
+| [TableView joins (TableViewJoins → SQL) — aliasing, chained multi-hop joins, ACL](features/tableview-joins.md) | `Client_*.TableViewJoins` rows are what let a table view show a column from a table other than its base record. | _underscore/Model/Client/TableView.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql, dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql |
 | [TogaIQ Gateway Client (_Component_Api_Togaiq) — AI generate/translate from 2.0](features/togaiq-gateway-client.md) | `_Component_Api_Togaiq` is the 2.0 framework's client for the **TogaIQ** (Talos) AI gateway. | _underscore/Component/Api/Togaiq/Togaiq.php, _underscore/ApiRequest.php |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Elite/2026-08-17 - FulfillmentTableViews.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView | _underscore/Model/Client/ServiceRequest.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql |

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

@@ -0,0 +1,171 @@
+---
+title: TableView joins (TableViewJoins → SQL) — aliasing, chained multi-hop joins, ACL
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-08-18
+owners: [bala]
+files:
+  - _underscore/Model/Client/TableView.php
+  - dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql
+  - dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql
+  - dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql
+related:
+  - ../../api2/features/tableview-field-metadata.md
+  - ./page-meta-context-field-settings.md
+  - ./tableview-hyperlink-columns.md
+  - ../../api2/features/tableview-apiwhereclause-row-filtering.md
+---
+
+## Summary
+
+`Client_*.TableViewJoins` rows are what let a table view show a column from a table other than its
+base record. `_Model_Client_TableView::meta()` (`_underscore/Model/Client/TableView.php`) turns each
+row into one entry of `table.joins` (`table`, `alias`, `type`, `onA`, `onB`). Two things about that
+translation are load-bearing and non-obvious:
+
+- **`onB` is emitted with the RAW TABLE NAME of the parent field's record, never with an alias.**
+- **`joinOnTableViewJoinId` does not affect the emitted ON clause at all.**
+
+Together those mean a **two-hop (chained) join works only because the first join of a table is
+aliased to the plain table name**. Get the order or the duplication wrong and the view emits SQL
+referencing a table that was never joined.
+
+## How it works
+
+The joins for a view are read with (paraphrased, ~line 55-73):
+
+```sql
+SELECT TableViewJoins.id, joinRecordId, joinOnRecordFieldId, joinOnTableViewJoinId,
+       parentRecordFieldId, parentCustomRecordFieldId, `type`
+FROM TableViewJoins
+INNER JOIN AclRecordPermissions ON AclRecordPermissions.recordId = TableViewJoins.joinRecordId
+WHERE TableViewJoins.tableViewId = <id> AND AclRecordPermissions.roleId IN (<user roles>)
+ORDER BY TableViewJoins.sortOrder ASC, TableViewJoins.id ASC
+```
+
+Then, per join:
+
+- **Alias.** A counter (`$tableViewAliasOrds`) starts at `65` (`A`) and is seeded with the view's
+  **base** table. The first join of a given table gets `ord == 65`, which means its alias is the
+  **plain table name**. Any later join of that same table becomes `<Table>_<letter>`.
+- **ON clause.**
+  - `onA` = `` `<this join's alias>`.`<joinOnRecordField.field>` ``
+  - `onB` = `` `<($parentRecord->model)::TABLE>`.`<parentRecordField.field>` `` — the **raw table
+    name** of the record that owns `parentRecordFieldId`.
+- `joinOnTableViewJoinId` is used for exactly one thing: setting `joinOnTableAlias` on the join
+  object. The current code **never emits `joinOnTableAlias` into `onA`/`onB`**. Treat it as
+  documentation of the chain, not the mechanism.
+
+## Chained (multi-hop) joins
+
+Example shipped 2026-08-18 on the `inventory_units` view (base record **Units**, 31): to show
+`Manufacturers.name` you need **Units → Items → Manufacturers**.
+
+- Hop 1: join **Items** (record 21) `ON Items.id (105) = Units.itemId (238)`
+- Hop 2: join **Manufacturers** (record 20) `ON Manufacturers.id (104) = Items.manufacturerId (107)`
+
+Hop 2's `onB` renders as `` `Items`.`manufacturerId` ``. That resolves **only** because hop 1 is the
+first Items join on the view and therefore aliased `Items`. So:
+
+- **The parent hop must sort first.** Joins are ordered `sortOrder ASC, id ASC`, so give the parent
+  hop the lower `sortOrder` or the SQL references a table that has not been joined yet.
+- **A chain breaks if its parent table is joined more than once on the same view.** The extra join
+  gets a suffixed alias while `onB` still says the bare table name, so the chain silently binds to
+  the first join — or fails outright if the bare-name join is not the one you meant.
+- Before this change there were **zero** rows with a non-null `joinOnTableViewJoinId` anywhere in
+  `Client_Elite`, so chained joins were previously unused in these schemas.
+
+## Look for an existing unused join before adding one
+
+The `inventory_units` view already carried a Units → Items join
+(`TableViewJoins.uuid = '7894941a-d00b-49db-af5f-63835c29b1a4'`, joinRecordId 21, joinOnRecordFieldId
+105 `Items.id`, parentRecordFieldId 238 `Units.itemId`, `OUTER`, `sortOrder 0`) in **both** clients
+and in **both** prod and client-sandbox — referenced by **zero** `TableViewFields`. It came in with
+the all-clients template `dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql`.
+Only the second hop had to be created. Always check for a usable join first; a duplicate Items join
+would also have broken the chain above.
+
+## The joined record needs an AclRecordPermissions row
+
+The joins query **INNER JOINs `AclRecordPermissions` on `joinRecordId`**. With no row for the
+caller's role, the join is silently dropped from the result set, and any `TableViewFields` row
+pointing at it then throws:
+
+```
+There is no AclRecordPermissions record permitting access to TableViewJoins.id = N for this user
+```
+
+So a new joined table (here `Manufacturers`, record 20) needs its `AclRecordPermissions` grant in the
+same migration.
+
+## Context RecordFieldSettings are OPTIONAL for a joined column to render
+
+`meta()` looks up `contextRecordFieldId`-scoped settings (`DefaultRecordFieldSettings` plus the
+Client / Persona / User / Language `RecordFieldSettings` tables) only to decide **which settings row
+supplies the column label**. When no context row exists for `(recordFieldId, contextRecordFieldId)`,
+it nulls `contextTable` / `contextField` and falls back to the field's own settings. A new joined
+column therefore does **not** require adding `RecordFieldSettings` rows just to appear — those rows
+are only needed to control the **header text** (see
+[page-meta-context-field-settings](./page-meta-context-field-settings.md), which is also where the
+"header renders as a camelCase slug" fallback is explained).
+
+## Authoring the migration (house style used here)
+
+The 2026-08-18 change added Part Number (`Items.partNumber` 108), Manufacturer
+(`Manufacturers.name` 103) and Item Description (`Items.description` 109) to `inventory_units`
+(`TableViews.uuid 86b3f376-2a15-4a46-ac0a-9b25146e40ac`), positioned directly after Asset Tag,
+mirroring how `inventory_items` surfaces the same three fields. Applied to **prod and
+client-sandbox for both Elite and NYCHH** as one file per client with identical content.
+
+- **Key everything off `uuid`, never off `id`.** `TableViews.id` happened to be 21 in both clients,
+  but the pre-existing `TableViewJoins.id` differed (Elite 142, NYCHH 165). Resolve ids with
+  `(SELECT id FROM TableViewJoins WHERE uuid = ...)`.
+- **One idempotent file beats an insert file plus a follow-up reorder file.** The insert had already
+  run in all four targets when the reposition was requested; rather than ship a second migration, the
+  same file was rewritten as `INSERT ... ON DUPLICATE KEY UPDATE` keyed on `uuid` for the join and the
+  three fields, followed by an unconditional renumber. On an already-applied schema the net effect is
+  just the reorder — no duplicate rows, no row-id churn.
+- **`@` session variables mean the file must run in ONE connection.** Splitting the statements across
+  connections (or across two client-tool tabs) silently loses the variables and the renumber writes
+  garbage.
+- Reordering columns has its own hazard — `TableViewFields` has `UNIQUE (tableViewId, index)`, so a
+  naive `index = index + N` can collide mid-statement. The safe park-shift-pull pattern is documented
+  in [tableview-field-metadata](../../api2/features/tableview-field-metadata.md).
+
+Core-level reference ids used (identical across all clients and environments): **Records** — Units
+31, Items 21, Manufacturers 20. **RecordFields** — `Units.itemId` 238, `Items.id` 105,
+`Items.partNumber` 108, `Items.description` 109, `Items.manufacturerId` 107, `Manufacturers.id` 104,
+`Manufacturers.name` 103.
+
+## Gotchas
+
+- **`onB` never uses an alias.** Any chain depends on the parent hop owning the bare table name.
+- **`joinOnTableViewJoinId` is inert in the emitted SQL** — setting it does not make a chain work,
+  and omitting it does not break one. It is metadata for humans until the ON-clause builder starts
+  using `joinOnTableAlias`.
+- **Alias suffixes are not `_B` for the first duplicate.** The counter is incremented both inside the
+  `isset` branch and again at the end of the loop, so the second join of a non-base table lands on
+  `chr(67)` → `<Table>_C`; `<Table>_B` only appears when the view joins its own **base** table. Do
+  not hand-write an alias from memory — check the counter logic before relying on one.
+- **A missing `AclRecordPermissions` row for the joined record drops the join, not just the column** —
+  and the resulting error names a `TableViewJoins.id`, which is why it reads like config corruption
+  rather than an ACL gap.
+- **An unused join can already exist.** Confirm before inserting; a duplicate join of the same table
+  is what breaks chained joins.
+
+## Change history
+
+- 2026-08-18 — Documented how `TableViewJoins` compile into SQL after adding a chained
+  **Units → Items → Manufacturers** join for the Part Number / Manufacturer / Item Description columns
+  on `inventory_units` (Elite + NYCHH): `onB` is emitted with the **raw table name** (so a chain only
+  works off the first, unaliased join of a table), `joinOnTableViewJoinId` feeds only
+  `joinOnTableAlias` and is **not** in the ON clause, joins are ordered `sortOrder ASC, id ASC`, the
+  joins query INNER JOINs `AclRecordPermissions` on `joinRecordId` (missing grant = dropped join plus
+  the "no AclRecordPermissions record permitting access to TableViewJoins.id" error), and context
+  `RecordFieldSettings` are optional for rendering (label-only). Also recorded the pre-existing unused
+  Units→Items join `7894941a-...` present in both clients, and the uuid-keyed idempotent single-file
+  migration style. (bala)

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, dbchanges2/Core/2026-08-17a - ItemFulfillmentQuantityFieldTypeNumber.sql, dbchanges2/Client/2026-08-17a - ItemFulfillmentColumnsCopyable.sql, dbchanges2/Client_Quad/2026-08-18c - SalesOrderListingSortByDateOrderDesc.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, dbchanges2/Client_Quad/2026-08-18c - SalesOrderListingSortByDateOrderDesc.sql, dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.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/tableview-field-metadata.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-20
-owners: [apeterson]
+updated: 2026-08-18
+owners: [apeterson, bala]
 files:
   - _underscore/Model/Client/TableView.php
   - api2/Component/Api/V2/V2.php
@@ -15,9 +15,12 @@ files:
   - dbchanges2/Core/2026-08-17a - ItemFulfillmentQuantityFieldTypeNumber.sql
   - dbchanges2/Client/2026-08-17a - ItemFulfillmentColumnsCopyable.sql
   - dbchanges2/Client_Quad/2026-08-18c - SalesOrderListingSortByDateOrderDesc.sql
+  - dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql
+  - dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql
 related:
   - tableview-apiwhereclause-row-filtering.md
   - ../../toga25-supply/features/meta-driven-table-data.md
+  - ../../_underscore/features/tableview-joins.md
 ---
 
 ## Summary
@@ -52,6 +55,8 @@ it. (Reference: `Core.RecordFields` id 369 = `ItemFulfillmentItems.quantity` set
 `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)).
+  How a join row becomes SQL — aliasing, chained multi-hop joins, and the ACL row the joined record
+  needs — is in [tableview-joins](../../_underscore/features/tableview-joins.md).
 
 ### `recordFieldId` is a cross-DB reference into shared `Core.RecordFields`
 
@@ -65,6 +70,32 @@ Reference ids observed for the `Items` record: **`Core.Records` id 21 = Items**,
 **`Core.RecordFields` id 106 = `Items.uuid`**. (Look these up per field before writing a migration —
 do not assume ids across environments.)
 
+## Column order (`index`) — the UNIQUE keys make reordering non-trivial
+
+`TableViewFields` carries **`UNIQUE (tableViewId, index)`** and **`UNIQUE (tableViewId, slug)`**.
+Columns are emitted `ORDER BY TableViewFields.index ASC`, so repositioning a column means rewriting
+other rows' `index` — and a plain `UPDATE ... SET index = index + N` can hit the unique key
+**mid-statement**, because MySQL checks per row, not at statement end.
+
+The safe pattern (used to slot Part Number / Manufacturer / Item Description in right after Asset
+Tag on `inventory_units`, 2026-08-18) is **park → shift → pull → drop**, so that every target slot is
+empty at the moment it is written:
+
+1. Park the moving rows in a high band (`200+`).
+2. Shift the rows that must move down into a second band (`100+`).
+3. Pull those back down into the freed low slots.
+4. Drop the parked rows into their final positions.
+
+Notes that matter when writing it:
+
+- **`index` is `TINYINT UNSIGNED`** — the parking band must stay under 256.
+- **Gaps in `index` are harmless** (it is display order only), but finishing with a contiguous
+  renumber makes the script **re-runnable to the same final state**.
+- Do the whole thing **uuid-keyed** and unconditional at the end, so an already-applied migration
+  can simply be re-run instead of shipping a separate "reorder" file — see the authoring notes in
+  [tableview-joins](../../_underscore/features/tableview-joins.md). If the script uses `@` session
+  variables, all statements must run in **one connection**.
+
 ## Hidden (projected-but-not-rendered) columns
 
 A `TableViewFields` row with `isVisible=0` is still selected into the row's data projection but
@@ -148,6 +179,14 @@ SalesOrderListingSortByDateOrderDesc.sql`).
   `meta.table.sort=[{slug,dir}]`; and the JOIN-`TableViewFields`-on-slug UPDATE recipe that
   avoids MySQL error 1093 (a self-subquery on `TableViews` is rejected). Applied to Quad's
   sales-orders listing (default `dateOrder DESC`). (apeterson)
+- 2026-08-18 — Recorded that `TableViewFields` has **UNIQUE (tableViewId, `index`)** and
+  **UNIQUE (tableViewId, slug)**, so a column reorder cannot be a plain `index = index + N` (the
+  unique key is checked per row, mid-statement); documented the park → shift → pull → drop pattern,
+  the `TINYINT UNSIGNED` ceiling on the parking band, and that a closing contiguous renumber is what
+  makes such a migration re-runnable. Found while inserting Part Number / Manufacturer / Item
+  Description after Asset Tag on the `inventory_units` view for Elite + NYCHH. Cross-linked the new
+  [tableview-joins](../../_underscore/features/tableview-joins.md) doc for how a join row becomes
+  SQL. (bala)
 - 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

package/knowledge/INDEX.md

@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 58 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 59 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 51 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 24 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 8 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/elite/INDEX.md

@@ -5,7 +5,7 @@
 | [Elite — NetSuite → TOGa Supply inbound sync (TRUE-80499 onboarding)](features/netsuite-togasupply-sync.md) | 1.0 | Elite is the 18th client on the shared NetSuite → TOGa Supply importer ([engine](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)). | worker/crons/toga2/netsuite/sync_togasupply_elite.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/schedules/cron.worker.sync.json, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/PurchaseOrder.php, _underscore/Model/Elite/ItemReceipt.php, dbchanges2/Client_Elite/_modules.txt, test/@srija/Elite Testing/Service Requests/test_sync_togasupply_elite_section.php, test/@srija/Elite Testing/Service Requests/test_diagnose_togasupply_elite.php |
 | [Elite SalesOrder → NetSuite Push (postPost/postPut interceptors → worker2)](features/salesorder-netsuite-push.md) | 2.0 | Elite orders created in Toga are pushed into NetSuite **event-driven**, not on a cron. | _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/ServiceRequest.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Core/2026-08-06a - Service request and sales order payload interceptors.sql |
 | [Elite — Sales Order stage change posts a reply on the TOGa Desk (1.0) ticket](features/salesorder-status-togadesk-reply.md) | 2.0 | When an Elite sales order's **stage** changes, a reply is posted on the originating **TOGa Desk (1.0)** ticket so the requester sees progress where they raised | worker2/Worker/Sync/SalesOrderStatus.php, _underscore/Model/Elite/SalesOrderStatus.php, _underscore/Model/Elite/SalesOrder.php |
-| [Elite — supply2 frontend scope (Inventory + Service Requests, both built)](features/supply2-scope.md) | 2.0 | Scope for onboarding Elite to the `toga2-supply` frontend (host `ELITE`). | toga2-supply/ELITE-CLIENT-TASK-NOTES.md, toga2-supply/src/pages/Orders/view/OrderView/viewModel/FIELDS/ELITE/BASEFIELDS.json, toga2-supply/src/pages/Orders/viewModel/FIELDS/ELITE/BASE.json, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/hooks/useFetchData.tsx, toga2-supply/src/components/ui/Toaster.tsx, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/pages/Inventory/viewModel/FIELDS/INVENTORYPAGEFIELDS.ts, toga2-supply/src/pages/Inventory/viewModel/index.ts, toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx, toga2-supply/src/pages/Inventory/listing/InventoryRouter.tsx, toga2-supply/src/pages/Inventory/listing/InventorySubTablePage.tsx, toga2-supply/src/utils/resolveClientHostName.ts, toga2-supply/src/utils/formatCustomerName.tsx, toga2-supply/src/utils/convertConstructorColumnTitles.ts, toga2-supply/src/pages/Orders/OrdersPage.tsx, toga2-supply/src/pages/Orders/viewModel/FIELDS/ELITE/BASE.json, toga2-supply/src/pages/Orders/viewModel/useOrdersPageViewModel.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/pages/Orders/view/OrderView/viewModel/useOrderDetailsViewModel.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/renderModalContent.tsx, toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx, toga2-supply/package.json |
+| [Elite — supply2 frontend scope (Inventory + Service Requests, both built)](features/supply2-scope.md) | 2.0 | Scope for onboarding Elite to the `toga2-supply` frontend (host `ELITE`). | toga2-supply/ELITE-CLIENT-TASK-NOTES.md, toga2-supply/src/pages/Orders/view/OrderView/viewModel/FIELDS/ELITE/BASEFIELDS.json, toga2-supply/src/pages/Orders/viewModel/FIELDS/ELITE/BASE.json, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/hooks/useFetchData.tsx, toga2-supply/src/components/ui/Toaster.tsx, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/pages/Inventory/viewModel/FIELDS/INVENTORYPAGEFIELDS.ts, toga2-supply/src/pages/Inventory/viewModel/index.ts, toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx, toga2-supply/src/pages/Inventory/listing/InventoryRouter.tsx, toga2-supply/src/pages/Inventory/listing/InventorySubTablePage.tsx, toga2-supply/src/utils/resolveClientHostName.ts, toga2-supply/src/utils/formatCustomerName.tsx, toga2-supply/src/utils/convertConstructorColumnTitles.ts, toga2-supply/src/pages/Orders/OrdersPage.tsx, toga2-supply/src/pages/Orders/viewModel/FIELDS/ELITE/BASE.json, toga2-supply/src/pages/Orders/viewModel/useOrdersPageViewModel.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/pages/Orders/view/OrderView/viewModel/useOrderDetailsViewModel.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/renderModalContent.tsx, toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx, toga2-supply/package.json, dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql |
 | [Elite — stale TableView config (11 dead Core.RecordFields across 9 views; 2 now fixed)](features/supply2-tableview-config-drift.md) | 2.0 | `Client_Elite`'s `TableViewJoins` predate **two** platform bridge-table migrations and still reference **11 deleted `Core.RecordFields` ids (211, 321, 932, 358, | dbchanges2/Client_Elite/, dbchanges2/Client_Elite/2026-08-07 - ServiceRequests TableView.sql, dbchanges2/Client_Elite/2026-08-17 - FulfillmentTableViews.sql, dbchanges2/Core/2026-08-07 - ServiceRequests TableView.sql, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
 | [Elite — raising a Service Request from a TOGa Desk ticket (App_Api_ServiceRequest)](features/togadesk-service-request-intake.md) | 1.0 | An Elite agent raises a **Service Request** from a TOGa Desk (1.0) ticket via a modal. | library/app/api/servicerequest.php, library/app/model/togadesk/ticket.php, togadesk/desk/includes/classes/class.ticket.php, togadesk/desk/template/modals/tickets/serviceRequest.php, togadesk/desk/includes/controllers/modals/tickets/serviceRequest.php, togadesk/desk/includes/controllers/actions/tickets/serviceRequest.php, dbchanges2/Client_Elite/2026-08-11a - EliteServiceRequestTicketUnique.sql, test/@srija/Elite Testing/Service Requests/test_elite_desk_service_request.php |
 | [Elite](profile.md) | 2.0 | Elite is a managed-services client that uses **Freshservice** as their helpdesk platform. | worker2/Worker/Elite.php, worker2/Worker/Sync/ServiceRequest.php, library/app/api/toga2.php, library/app/api/servicerequest.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/ServiceRequest.php, togadesk/desk/includes/classes/class.ticket.php, worker/crons/toga2/netsuite/sync_togasupply_elite.php |

package/knowledge/clients/elite/features/supply2-scope.md

@@ -32,11 +32,13 @@ files:
   - toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/renderModalContent.tsx
   - toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx
   - toga2-supply/package.json
+  - dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql
 related:
   - ../../../2.0/apps/toga2-supply/workflows/client-host-scoping.md
   - ../../../2.0/apps/toga2-supply/features/order-detail-field-config-and-customer-name.md
   - ./supply2-tableview-config-drift.md
   - ../profile.md
+  - ../../../2.0/apps/_underscore/features/tableview-joins.md
 ---
 
 ## Summary
@@ -73,6 +75,15 @@ One host-scoped group-by view only: **"Units By Items"**, no group-by modal.
 - Local run: `npm run elite` (`vite --host elite.togasupply`) plus a
   `127.0.0.1 elite.togasupply` hosts-file entry.
 
+**The nested `inventory_units` view now shows what the hardware actually is (2026-08-18).** Unit rows
+previously carried only serial / asset tag, so a user could not identify the item without opening it.
+Part Number, Manufacturer and Item Description were added directly after Asset Tag, mirroring
+`inventory_items`, via `dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql` (an
+identical file was applied for NYCHH). Manufacturer needs a **chained** Units → Items → Manufacturers
+join — mechanism, ACL requirement and the column-reorder hazard are in
+[tableview-joins](../../../2.0/apps/_underscore/features/tableview-joins.md). Purely backend metadata;
+no frontend change.
+
 **Hardening from the CodeRabbit review (2026-08-10)** — guardrail-preserving variants, not the
 reviewer's literal diffs:
 
@@ -200,6 +211,12 @@ byte-identical in behavior** — that is the bar for editing shared UI here (see
   2026-08-07 prod→beta refresh that wiped the hand-built `service-requests` view.
 
 ## Change history
+- 2026-08-18 — Added **Part Number / Manufacturer / Item Description** to the `inventory_units` table
+  view directly after Asset Tag (`dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql`,
+  same file content shipped for NYCHH; prod + client-sandbox), so unit rows identify the hardware
+  instead of showing serial/asset tag alone. Manufacturer comes through the first chained
+  Units → Items → Manufacturers join in `Client_Elite`; backend metadata only, no frontend change.
+  (bala)
 - 2026-08-18 - Added `ELITE: "Elite"` to `formatCustomerName.tsx`'s `CUSTOMER_MAP` so the
   order-details **Customer** row shows a name instead of a dash. Recorded that this row is
   **hardcoded in the frontend for every host** - the shared `valueKey`

package/knowledge/clients/nychh/INDEX.md

@@ -2,4 +2,4 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. |  |
+| [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. | dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql |

package/knowledge/clients/nychh/profile.md

@@ -15,11 +15,13 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-08-17
+updated: 2026-08-18
 owners: ["jcardinal", "apeterson", "bala"]
-files: []
+files:
+  - dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql
 related:
   - ../../2.0/apps/_underscore/features/tracking-number-bridges.md
+  - ../../2.0/apps/_underscore/features/tableview-joins.md
 ---
 
 ## Summary
@@ -34,6 +36,11 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   run the NetSuite→TOGa Supply sync and the asset-tag verification/backfill diagnostics.
 
 ## Key features (this client)
+- **`inventory_units` table view carries item detail as of 2026-08-18** — Part Number, Manufacturer
+  and Item Description sit directly after Asset Tag, reached through a **chained** Units → Items →
+  Manufacturers join (`dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql`, identical
+  to Elite's file; applied in prod and client-sandbox). Mechanism and the reorder hazard:
+  [tableview-joins](../../2.0/apps/_underscore/features/tableview-joins.md).
 - Item-fulfillment table views (`item-fulfillments-for-sales-orders`,
   `item-fulfillments-for-sales-order-items`) rebuilt 2026-06-19 to mirror the Compass fix —
   re-rooted at `ItemFulfillmentItems` with item-level (record 318) tracking. See

package/package.json

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