toga-ai 1.0.781 → 1.0.783

package/knowledge/1.0/apps/library/INDEX.md

@@ -16,6 +16,7 @@
 | [HTTP 500 Error Monitor (App_SystemMonitor_500Error) — and why its \"Error Type\" is not a diagnosis](features/http-500-error-monitor.md) | `App_SystemMonitor_500Error` (`library/app/systemmonitor/500error.php`, title **"HTTP 500 Error Alert"**) is the 1.0 system monitor that watches **`Logs.Api` fo | library/app/systemmonitor/500error.php, worker/crons/infrastructure/system_monitors.php, api2/Controller/Index.php, _underscore/Error.php |
 | [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t | library/app/framework.php, library/app/frameworkindex.php, library/app/mvc.php, library/app/database.php, library/app/model.php, library/app/config.php |
 | [NetSuite File Cabinet Content Retrieval via RESTlet (fetchInvoiceFile)](features/netsuite-filecabinet-restlet.md) | How 1.0 pulls **File Cabinet binary content** (invoice PDFs) out of NetSuite over REST. | library/app/api/netsuite/rest.php, worker/crons/toga2/netsuite/netsuite_restlet_filecontent.js, worker/config.worker.ini |
+| [assetType from NetSuite itemtype during Item Sync (opt-in per client)](features/netsuite-item-assettype-sync.md) | `getCreateItem()` never sent `assetType`, so **every item the NetSuite importer created had `Items.assetTypeId = NULL`** — for every client, since the importer | library/app/api/toga2.php, library/app/api/netsuite/rest.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_elite.php |
 | [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite `isfulfillable` flag during item sync and stamping it onto the **Agilant | library/app/netsuite.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php |
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem, test/@dave/Junk Drawer/nsq.php |
 | [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. | library/app/api/netsuite/rest.php, library/app/netsuite.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |

package/knowledge/1.0/apps/library/features/netsuite-item-assettype-sync.md

@@ -0,0 +1,202 @@
+---
+title: assetType from NetSuite itemtype during Item Sync (opt-in per client)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-09-04
+owners: [rgirish]
+files:
+  - library/app/api/toga2.php
+  - library/app/api/netsuite/rest.php
+  - worker/crons/toga2/netsuite/common_sync_togasupply.php
+  - worker/crons/toga2/netsuite/sync_togasupply_elite.php
+related:
+  - netsuite-item-isfulfillable-sync.md
+  - netsuite-suiteql-rest-shim.md
+  - toga2-api-client-and-bridge.md
+  - ../../worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../../2.0/apps/api2/features/nested-relationship-writes.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ../../../clients/elite/features/netsuite-togasupply-sync.md
+---
+
+## Summary
+
+`getCreateItem()` never sent `assetType`, so **every item the NetSuite importer created had
+`Items.assetTypeId = NULL`** — for every client, since the importer began. The string `assetType`
+appeared nowhere in `library/app/api/toga2.php` nor in `worker/crons/toga2/netsuite/*`.
+
+Measured on production `Client_Elite.Items`: **113 rows, 110 with `assetTypeId = NULL`**. The only
+3 non-NULL rows (`Laptop`, `Test`, `Test 2`) have `c_netsuiteInternalItemId = NULL` and
+`inventoryType = HYBRID` — hand-made test rows, not imported ones.
+
+This doc covers the fix: NetSuite's `item.itemtype` is now mapped to an `AssetTypes.uuid` and
+stamped on the item. It is **opt-in per client** and deliberately narrow, because two platform
+facts (below) make the obvious implementation break item imports outright.
+
+Sibling doc: [isFulfillable](netsuite-item-isfulfillable-sync.md) — the other NetSuite flag stamped
+by the same function. **The two are not symmetric** and must not be implemented the same way; see
+[Why this is not modeled on isFulfillable](#why-this-is-not-modeled-on-isfulfillable).
+
+## ⚠⚠ TWO blockers — read before adding this for another client
+
+Both were found under CTO review of a first proposal that looked obviously correct. Either one
+turns "the asset type is not set" into **"the item create fails outright."**
+
+### 1. `Items.assetTypeId` is not writable by the API role in most tenants
+
+api2 **aborts the entire record write** when a payload names a field the authenticating role cannot
+write. The NetSuite sync authenticates as **roleId 3 (API)**. So simply adding `assetType` to the
+payload does not merely fail to set the asset type — it **fails the item create**.
+
+Verified on production `Client_Elite.AclFieldPermissions`:
+
+| recordFieldId | Field | Roles granted |
+|---|---|---|
+| **269** | `Items.assetTypeId` | roleId **1 (Base) only** |
+| 107 | `Items.manufacturerId` | roleId **1 and 3 (API)** |
+
+**A `dbchanges2/Client_<Tenant>/` grant must land BEFORE the code deploy.** Elite's is
+`dbchanges2/Client_Elite/2026-09-04a - EliteItemAssetTypeApiWritePermission.sql`. Mechanics:
+[ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md).
+
+### 2. `assetTypeId`'s childPolicy is `MATCH`, not `MATCH_UPSERT` — so get-or-create does NOT work
+
+`getCreateManufacturer()` sits in the **same function** and does a get-or-create by name. **That
+pattern does not transfer.** Manufacturers auto-create precisely because their field is
+`MATCH_UPSERT`; `assetTypeId` is plain `MATCH`.
+
+Verified on production `Core.RecordFields`: id **269** (`assetTypeId`) = `MATCH`; id **107**
+(`manufacturerId`) = `MATCH_UPSERT`.
+
+With `MATCH`, sending `assetType: {name: 'Services'}` for a name that has no row is a
+**field-reference error that fails the record** — it does not create the row. Correct approach:
+**resolve name → uuid up front (`GET /asset-types`) and send `{uuid}`.** Policy semantics:
+[nested-relationship writes](../../../2.0/apps/api2/features/nested-relationship-writes.md).
+
+> **General lesson:** never reason by analogy from a sibling nested write in the same function.
+> Check that field's own `Core.RecordFields.childPolicy` first. Two fields on the same record
+> routinely differ.
+
+## Key files / entry points
+
+- `library/app/api/netsuite/rest.php` — `fetchItemFlagsByIds()` now selects `itemtype` in its
+  SuiteQL and exposes it as `->itemType`. **Free**: that query already selected from `item` once
+  per 500-id batch, so no extra round-trip. Returns `null` for an empty itemtype.
+- `library/app/api/toga2.php`
+  - `getAssetTypeUuidForNetsuiteItemType()` (~6358) — new private helper. Resolves a NetSuite
+    itemtype to an `AssetTypes.uuid` through the launcher's opt-in map. Returns `null` when the
+    client has not opted in or the itemtype is unmapped; **throws** when a configured mapping names
+    an asset type the client does not have.
+  - `getCreateItem()` (~6474) — sends `assetType: {uuid}` on create, and **fills it on existing
+    items only when currently NULL**.
+- `worker/crons/toga2/netsuite/common_sync_togasupply.php` (~298) — the bulk `/items` GET now
+  requests `assetType => ['uuid']`. **Without this the fill-NULL-only check has nothing to read and
+  would re-PUT every item every run** (the same trap `isFulfillable` fell into — see its doc).
+- `worker/crons/toga2/netsuite/sync_togasupply_elite.php` — the only launcher that opts in today.
+
+## How it works
+
+1. `fetchItemFlagsByIds()` returns `->itemType` alongside the serialized / fulfillable flags, one
+   SuiteQL query per 500 items.
+2. `getCreateItem()` calls `getAssetTypeUuidForNetsuiteItemType($itemFlags->itemType, …)`.
+3. The helper reads the launcher constant `NETSUITE_ITEM_TYPE_TO_ASSET_TYPE_NAME`
+   (`itemtype => AssetTypes.name`). **If the constant is not defined, it returns `null`** and the
+   `assetType` key is **omitted from the payload entirely**.
+4. On first need it `GET /asset-types` once and builds a `strtoupper(name) => uuid` map, skipping
+   rows with a NULL/blank name. **The cache is keyed by client uuid** — one worker process can
+   handle several clients in a run.
+5. Name not found → **throw**, naming the itemtype, the mapped name, and the fix. Fail loud, per the
+   team rule for import/sync/cron code.
+6. Create → `assetType: {uuid}` in the POST. Existing item → set it **only if
+   `$existingItem->assetType` is NULL**.
+
+## Design rules (and why each one)
+
+| Rule | Why |
+|---|---|
+| **Opt-in via a launcher constant** | `getCreateItem()` is shared by ~20 client sync launchers. Undefined constant ⇒ the payload key is absent ⇒ the other ~19 clients are **byte-for-byte unaffected**. |
+| **Link by uuid, never by name** | `assetTypeId` is `MATCH` — a name for a missing row fails the whole record (blocker 2). |
+| **Never auto-create an `AssetTypes` row** | `AssetTypes` is free text with per-client `AUTO_INCREMENT` ids and **no slug or code**, so nothing marks a row as sync-made vs. operator-made. Verified: `Client_Elite.AssetTypes` has 2 rows (1=`Laptop`, 2=`Services`); `Client_Compass.AssetTypes` has **38 hand-curated rows** (`ACCESSORY`, `EQUIPMENT`, `FEE`, `CONSULTING`, `WARRANTY`, `HP LAPTOP ACCESSORIES`, … plus an **empty-name row at id 23**) and **no `Services` row at all**. Auto-creating would pollute that taxonomy. |
+| **Fail loudly on a missing asset type** | A silent skip leaves a client half-stamped with no signal. |
+| **Fill-NULL-only on existing items** | `assetTypeId` is shared, **hand-curated per-client** data — unlike `isFulfillable`, which is a boolean NetSuite owns. Also means a manual TOGa correction of a NetSuite-mis-typed item **survives later syncs**. |
+| **Cache keyed by client uuid** | One worker process can service several clients. |
+
+## Why this is not modeled on isFulfillable
+
+[isFulfillable](netsuite-item-isfulfillable-sync.md) **refreshes on every difference** — and that
+doc's own ⚠ CRITICAL section records the cost: the refresh **reverts any local override**, so a
+hand fix silently disappears within a day.
+
+`assetType` deliberately does the opposite (**fill-NULL-only**). NetSuite does not own this field;
+the client's operators do. Do not "make it consistent" with `isFulfillable` — the asymmetry is the
+design.
+
+## NetSuite `itemtype` does NOT cleanly identify services
+
+`item.itemtype` **is** populated (account-wide: InvtPart 51336, NonInvtPart 2652, Group 585,
+Service 472, Kit 50, OthCharge 24, Discount 17, Expense 6, Description 3). But **`NonInvtPart` is
+mixed** — it holds real services. For Elite (113 items: 65 InvtPart, 11 Service, 17 NonInvtPart),
+`itemtype = 'Service'` alone marks only **11 of ~28** real services; the rest sit in `NonInvtPart`
+(`SVC-FS-DEPLOY`, `SVC-FS-SHIPPING-*`, `SVC-CI-RETAINER-RS`, `SVC-TS-Removal`, `Project - Cabling`).
+
+So a usable mapping must include the non-inventory types, not just `Service`. Elite's map is in
+[Elite's sync doc](../../../clients/elite/features/netsuite-togasupply-sync.md).
+
+**Residual gap: NetSuite data hygiene, not a code problem.** Three Elite items are typed
+`InvtPart` in NetSuite though they are services (`SVC-TS-ELITE-HDONBOARDING`, `CONFIG/INSTALL`,
+`CONF-RM-INSTALL-SUPP`). **Decided: this is a client data-hygiene ask, NOT a code special case** —
+a part-number allowlist inside a 20-client shared import is unmaintainable. Fill-NULL-only means a
+manual TOGa correction sticks.
+
+## Gotchas / known issues
+
+- **⚠ Existing items stay NULL until a cursor reset.** `getCreateItem()` only runs when a
+  transaction line references an item, so already-imported items are **not** back-stamped by
+  turning this on. Elite's 110 NULL items stay NULL until a cursor rollback makes the sync re-walk
+  transactions that reference them. Cursors live in the **client** database `Parameters` table
+  (key `NETSUITE_LAST_SYNC_CURSOR_*`, value `"<lastmodifieddate>|<netsuiteInternalId>"`), read via
+  `GET /parameters`. See [per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md).
+- **⚠ Lumping `Discount` / `Expense` / `Description` into a "Services" asset type is semantically
+  loose.** Harmless while `assetTypeId` only hides rows on a page — a **latent bug if it ever drives
+  billing or reporting.** Revisit the map before wiring `assetTypeId` into either.
+- **An empty-name `AssetTypes` row exists in the wild** (`Client_Compass` id 23). The name→uuid
+  cache skips NULL/blank names so it can never be matched by accident.
+- **⚠ PRE-EXISTING BUG, deliberately NOT fixed — needs its own ticket.** The fulfillability refresh
+  (`toga2.php` ~6547) reads `$existingItem->isFulfillable`, but the bulk `GET /items` lookup in
+  `common_sync_togasupply.php` **never requested that field**. So `$currentFulfillable` is always
+  `null` and the sync almost certainly **PUTs `isFulfillable` on every item, every run, for every
+  client**. Left untouched on purpose: fixing it changes behavior for all ~20 clients and was out of
+  scope. This is the exact trap `assetType` avoids by requesting `assetType => ['uuid']` in the same
+  lookup.
+
+## Change history
+
+- 2026-09-04 — **Built assetType stamping from NetSuite `itemtype`.** Root-caused that
+  `getCreateItem()` never sent `assetType`, so every imported item had `assetTypeId = NULL` (prod
+  `Client_Elite`: 110 of 113). Added `itemtype` to `fetchItemFlagsByIds()`'s existing SuiteQL
+  (free), the `getAssetTypeUuidForNetsuiteItemType()` helper, `assetType => ['uuid']` to the bulk
+  `/items` GET, and the create/fill paths. Recorded the **two blockers** that break the naive
+  version — `Items.assetTypeId` (recordField 269) is granted to **roleId 1 only** while the sync
+  authenticates as roleId 3, and api2 fails the **whole** record write on a non-writable field; and
+  269's childPolicy is **`MATCH`**, not the `MATCH_UPSERT` that makes the sibling
+  `getCreateManufacturer()` get-or-create work, so a name-only nested object is a hard failure.
+  Design: opt-in per launcher, link by uuid, never auto-create an `AssetTypes` row, fail loud on a
+  missing one, **fill-NULL-only** (the deliberate opposite of `isFulfillable`'s revert-everything
+  refresh). Also collapsed the existing-item branch's **three separate PUTs to the same
+  `/items/<uuid>`** into one, and recorded the pre-existing `isFulfillable`-never-requested bug as a
+  separate ticket. (rgirish)
+
+## Related docs
+
+- [isFulfillable from NetSuite during Item Sync](netsuite-item-isfulfillable-sync.md) — the sibling
+  flag on the same function, with the opposite refresh policy.
+- [Nested-relationship writes](../../../2.0/apps/api2/features/nested-relationship-writes.md) —
+  `MATCH` vs `MATCH_UPSERT` and why link-by-uuid is the only safe form.
+- [ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md) — the
+  field-write grant this feature needs per tenant.
+- [Elite NetSuite → TOGa Supply sync](../../../clients/elite/features/netsuite-togasupply-sync.md)
+  — the only client opted in, and its itemtype map.

package/knowledge/1.0/apps/library/features/netsuite-item-isfulfillable-sync.md

@@ -6,14 +6,15 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-12
-owners: [bala]
+updated: 2026-09-04
+owners: [bala, rgirish]
 files:
   - library/app/netsuite.php
   - library/app/api/toga2.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php
 related:
+  - netsuite-item-assettype-sync.md
   - toga2-api-client-and-bridge.md
   - ../../worker/features/netsuite-togasupply-per-client-sync.md
   - ../../worker/workflows/isfulfillable-multi-client-backfill.md
@@ -116,6 +117,22 @@ sweep that started 13:45 and set every item to `1`.
   each verified to trace through an Agilant source.
 
 ## Gotchas / known issues
+- **⚠⚠ The refresh's diff is BROKEN — `isFulfillable` is never read back, so it is PUT on every
+  item, every run, for every client.** The refresh at `toga2.php` ~6547 compares NetSuite's value
+  against `$existingItem->isFulfillable`, but the bulk `GET /items` lookup in
+  `common_sync_togasupply.php` **never requested that field** — so `$currentFulfillable` is always
+  `null` and the diff can never match. The 2026-07-28 entry below claims the field was added to that
+  field list; **it is not there** (verified 2026-09-04). Net effect: the "diff-only PUT keeps
+  re-syncs no-op" guarantee does not hold. **Not fixed — needs its own ticket**, because a fix
+  changes write volume for all ~20 clients. The sibling
+  [assetType feature](netsuite-item-assettype-sync.md) avoids this by requesting
+  `assetType => ['uuid']` in the same lookup.
+- **The existing-item branch now sends ONE PUT, not three.** It previously issued up to three
+  separate PUTs to the same `/items/<uuid>` with identical options (`inventoryType`,
+  `isFulfillable`, and now `assetType`). One payload is collected and a single PUT is sent when
+  non-empty. Side effect worth knowing: `inventoryType` was previously never written back to the
+  in-run lookup, so a repeat line for the same part number re-PUT it — all three fields now update
+  the lookup.
 - **Value stamped only on the Agilant source item here** — the client-facing copy is set by the 2.0
   interceptor. If the interceptor rows aren't deployed in the target env, api2 **403s the whole item
   write** on the unknown `isFulfillable` field (see the Phase-2 doc's deploy gotchas).
@@ -125,6 +142,15 @@ sweep that started 13:45 and set every item to `1`.
   in `Client_Compass.Apis` (name `Agilant`) — never reproduce the secret value.
 
 ## Change history
+- 2026-09-04 — **Two corrections found while building the sibling
+  [assetType stamping](netsuite-item-assettype-sync.md) on the same function.** (1) The
+  existing-item **refresh diff never works**: the bulk `GET /items` field list in
+  `common_sync_togasupply.php` does **not** request `isFulfillable` (contrary to the 2026-07-28
+  entry below), so `$currentFulfillable` is always `null` and the flag is almost certainly PUT on
+  every item, every run, for every client. Recorded as a separate ticket — not fixed, because it
+  changes write volume for ~20 clients. (2) The existing-item branch's up-to-**three** PUTs to the
+  same `/items/<uuid>` were collapsed into a **single** PUT, and `inventoryType` is now written back
+  to the in-run lookup (it previously was not, so a repeat part number re-PUT it). (rgirish)
 - 2026-08-12 — Prod investigation (no code change): recorded that the **existing-item refresh
   reverts any local override** (NetSuite returns `T` for services; audit-log proof on Compass items
   2382/2384/2385, stamped NULL→1 on 2026-08-04), so an override must be enforced by a write-time

package/knowledge/2.0/apps/api2/features/nested-relationship-writes.md

@@ -7,13 +7,14 @@ client: shared
 type: feature
 status: active
 updated: 2026-09-04
-owners: ["bala", "mhammontree", "tcox", "apeterson"]
+owners: ["bala", "mhammontree", "tcox", "apeterson", "rgirish"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Client/ContactEmailAddress.php
   - _underscore/Model/Client/TransferOrderStage.php
 related:
   - ../architecture.md
+  - ../../../1.0/apps/library/features/netsuite-item-assettype-sync.md
   - ../../toga2-supply/features/currency-amount-lines-editor.md
   - cxml-shipnotice-gateway.md
   - ../../../clients/aig/features/entitlement-intake.md
@@ -215,6 +216,46 @@ business keys to uuids in the caller. (Also note `Units.itemId` is NOT NULL, so
 omitted; and the `Units` identifier set is `uuid`/`itemId`/`serialNumber`/`assetTag`/`vendorId`/
 `macAddress`, so item + serialNumber is what gives find-or-create on a device.)
 
+### Plain `MATCH` (no UPSERT) makes a name-only nested object a HARD FAILURE — and a sibling field is no guide
+
+`MATCH_UPSERT` creates the missing child. **Plain `MATCH` does not** — sending a nested object that
+matches nothing is a **field-reference error that fails the whole record write**. It does not
+"skip the field."
+
+This bites hardest when the same function already does a working get-or-create on a *sibling* field
+of the *same* record, because the pattern looks obviously reusable and is not. Measured on
+production `Core.RecordFields` for `Items`:
+
+| recordFieldId | Field | childPolicy | So a name-only nested object… |
+|---|---|---|---|
+| **107** | `Items.manufacturerId` | `MATCH_UPSERT` | **creates** the manufacturer — get-or-create by name works |
+| **269** | `Items.assetTypeId` | `MATCH` | **fails the entire item write** |
+
+The 1.0 NetSuite importer's `getCreateItem()` contains **both** calls. `getCreateManufacturer()`
+sends `manufacturer: {name}` and has always worked; copying that shape for `assetType: {name}`
+would have broken item creation outright.
+
+> **Rule: before writing a nested object, check that field's OWN
+> `Core.RecordFields.childPolicy`.** Never reason by analogy from a sibling field on the same
+> record — two fields on one record routinely differ (the ASN tracking bridges above are the same
+> lesson on three sibling bridges).
+>
+> **On a `MATCH` field, always resolve the business key to a `uuid` in the caller and send
+> `{uuid}`.** For `AssetTypes` that means a `GET /asset-types` name→uuid map up front.
+
+Worked case:
+[assetType from NetSuite itemtype](../../../1.0/apps/library/features/netsuite-item-assettype-sync.md).
+
+#### The other half of the same trap: a non-writable field fails the WHOLE record, not just the field
+
+Same write, different gate. api2 **aborts the entire record write** when the payload names a field
+the authenticating role cannot write — so an ACL gap on one nested FK reads as "creates stopped
+working," not "that field is empty." Verified on production `Client_Elite.AclFieldPermissions`:
+recordField **269** (`assetTypeId`) had **roleId 1 only**, while **107** (`manufacturerId`) had
+**1 and 3**; the NetSuite sync authenticates as roleId 3. **The `dbchanges2/Client_<Tenant>/` grant
+must land before the code that sends the field.** Chain details:
+[ACL permission chain](../../_underscore/features/acl-permission-chain.md).
+
 ### Fix it with a migration — a manual one-row data patch on non-prod DOES NOT SURVIVE
 
 The TRUE-79978 beta fix was applied by hand as a single `UPDATE` on 2026-07-09. The **identical
@@ -357,6 +398,16 @@ transferOrderStage: { id: 7 }
   request time from a stable natural key (name/slug), because ids differ per tenant DB. Distinguished
   this from the existing `searchableIdentifierFields: ["id"]` flavor, which is a missing
   `isIdentifier` on a `c_` field. Found building the transfer-order create POST. (apeterson)
+- 2026-09-04 — Recorded that **plain `MATCH` (without UPSERT) makes a name-only nested object a hard
+  failure of the whole record write**, not a skipped field — and that **a sibling field on the same
+  record is no guide**. Prod `Core.RecordFields` on `Items`: **107** (`manufacturerId`) is
+  `MATCH_UPSERT` so `getCreateManufacturer()`'s get-or-create-by-name works, while **269**
+  (`assetTypeId`) is `MATCH`, so copying that shape into the same function would have broken item
+  creation. Rule: check the field's own `childPolicy`, and on a `MATCH` field resolve the business
+  key to a `uuid` in the caller. Also recorded the paired ACL gate — api2 aborts the **entire**
+  record write on a non-writable field (269 was granted roleId 1 only; the NetSuite sync
+  authenticates as roleId 3), so the tenant grant migration must precede the code deploy. Surfaced
+  under CTO review of the 1.0 NetSuite assetType import. (rgirish)
 
 - 2026-08-26 — Added: **the UPDATE path sets status 200 unconditionally after its children loop**, so
   a nested `PUT` reports success even when a child write failed (unique-key rejection, ACL denial).

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

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
 | [Re-runnable additive migrations (uuid4 in SQL, INSERT guards, the DISTINCT trap, conditional ALTERs)](features/rerunnable-additive-inserts.md) | Most `dbchanges2` files are **additive data grants** run by hand against production, often more than once (once per environment, or twice because someone was no | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql, dbchanges2/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql |
-| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Client_Compass/2026-09-04a - ItemRecordRestrictToPersonaVisible.sql, dbchanges2/Client_CompassCanada/2026-09-04a - ItemRecordRestrictToPersonaVisible.sql, dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql, dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql, dbchanges2/Core/2026-08-31a - SalesOrderDenialDetailsSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-31a - SalesOrderDenialDetailsReadOnlyRules.sql, toga25-supply/db-migrations/PLAYBOOK.md, toga25-supply/db-migrations/SURFACE-FEATURE-RUNBOOK.md, dbchanges2/Client_Compass/, dbchanges2/Client_CompassCanada/, dbchanges2/Client_Quad/, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Quad/2026-07-21b - ApproveDisabledTooltipPoNumber.sql, dbchanges2/Client_Quad/2026-08-21 - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Core/2026-07-29a - SalesOrderApprovalDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-05b - ApprovalDetailsShippingMethodConcatCharge.sql, dbchanges2/Core/2026-08-14a - NoteBadgesVocabularySurface.sql, dbchanges2/Client/2026-08-14a - NoteBadgeThemeTokens.sql, dbchanges2/Client/2026-08-14b - NoteBadgeUserColorFix.sql, dbchanges2/Client_Compass/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Client_CompassCanada/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Core/2026-08-26a - ServiceRequestRecordHeaderSurfaceSeed.sql, dbchanges2/Core/2026-08-26b - ServiceRequestDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Core/2026-09-03c - ColumnsModalSurfaceSeed.sql, dbchanges2/Core/2026-09-03d - ColumnsModalRetireConfigModal.sql |
+| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Client_Compass/2026-09-04a - ItemRecordRestrictToPersonaVisible.sql, dbchanges2/Client_CompassCanada/2026-09-04a - ItemRecordRestrictToPersonaVisible.sql, dbchanges2/Core/2026-09-03a - TransferOrderStatusBadgeRecordFields.sql, dbchanges2/Core/2026-09-03b - InventoryCreateTransferOrderAction.sql, dbchanges2/Client_Nychh/2026-09-03a - TransferOrdersStatusBadge.sql, dbchanges2/Client_Nychh/2026-09-03b - InventoryCreateTransferOrderShow.sql, dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql, dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql, dbchanges2/Core/2026-08-31a - SalesOrderDenialDetailsSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-31a - SalesOrderDenialDetailsReadOnlyRules.sql, toga25-supply/db-migrations/PLAYBOOK.md, toga25-supply/db-migrations/SURFACE-FEATURE-RUNBOOK.md, dbchanges2/Client_Compass/, dbchanges2/Client_CompassCanada/, dbchanges2/Client_Quad/, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Quad/2026-07-21b - ApproveDisabledTooltipPoNumber.sql, dbchanges2/Client_Quad/2026-08-21 - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Core/2026-07-29a - SalesOrderApprovalDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-05b - ApprovalDetailsShippingMethodConcatCharge.sql, dbchanges2/Core/2026-08-14a - NoteBadgesVocabularySurface.sql, dbchanges2/Client/2026-08-14a - NoteBadgeThemeTokens.sql, dbchanges2/Client/2026-08-14b - NoteBadgeUserColorFix.sql, dbchanges2/Client_Compass/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Client_CompassCanada/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Core/2026-08-26a - ServiceRequestRecordHeaderSurfaceSeed.sql, dbchanges2/Core/2026-08-26b - ServiceRequestDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Core/2026-09-03c - ColumnsModalSurfaceSeed.sql, dbchanges2/Core/2026-09-03d - ColumnsModalRetireConfigModal.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | > **A local browser wizard now automates this.** Steps 2–9 below (create DBs, generate Core/API > inserts, append to `Clients_Db.txt`) — plus the dbchanges2 bla | Client/, Client_<Tenant>/, Core/, Logs_Client/ |
 | [Auditing a client DB that drifted from its models (partially applied module migration)](workflows/client-schema-drift-audit.md) | A recurring 2.0 failure mode: **one client's database drifts from what the PHP models declare**, usually because a `_modules/<module>/` migration was applied to | dbchanges2/Client_Growrk/2026-05-28.sql, dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/_modules.txt |
 | [Framework branch running AHEAD of schema — environment-wide 1054/EO-1 after a deploy](workflows/framework-branch-ahead-of-schema.md) | A **third** kind of 2.0 schema drift, distinct from the two already documented: nobody's database went backwards — **the code went forwards**. | _underscore/Model/Core/RecordField.php, _underscore/Model/Client/TableViewField.php, _underscore/Model/Client/TableView.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/Urgency.php, _underscore/Model/Client/RecordFieldSetting.php, _underscore/Model/Client/ClientRecordFieldSetting.php, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-14c - RecordFieldsValidationMetadata.sql, dbchanges2/Client/2026-08-14a - RecordFieldSettingsClientTable.sql, dbchanges2/Client/2026-08-13a - UserNavPreferencesClientTable.sql, dbchanges2/Client/2026-08-13c - PersonaNavVisibilityClientTable.sql |

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

@@ -11,6 +11,10 @@ owners: [jcardinal, apeterson, tcox]
 files:
   - dbchanges2/Client_Compass/2026-09-04a - ItemRecordRestrictToPersonaVisible.sql
   - dbchanges2/Client_CompassCanada/2026-09-04a - ItemRecordRestrictToPersonaVisible.sql
+  - dbchanges2/Core/2026-09-03a - TransferOrderStatusBadgeRecordFields.sql
+  - dbchanges2/Core/2026-09-03b - InventoryCreateTransferOrderAction.sql
+  - dbchanges2/Client_Nychh/2026-09-03a - TransferOrdersStatusBadge.sql
+  - dbchanges2/Client_Nychh/2026-09-03b - InventoryCreateTransferOrderShow.sql
   - dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql
   - dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql
   - dbchanges2/Core/2026-08-31a - SalesOrderDenialDetailsSurfaceSeed.sql
@@ -145,6 +149,25 @@ per-tenant deltas live in **Client** (mirrors `TableViews`/ACL/`ItemTranslations
 `value varchar(255)` + `c_longValue mediumtext`. Precedence **base < client < persona < role**
 with language as an orthogonal overlay; the resolver applies it most-specific-last in one pass.
 
+### Which family is this table in? — the cheat sheet a UI-layer migration actually needs
+
+Every `.sql` file for a UI-layer change has to be checked statement-by-statement against the
+**cluster-isolation hard rule** (see the [dbchanges2 architecture](../architecture.md)), and the
+tables that come up over and over split cleanly. **Verified placement:**
+
+| Family | Tables |
+|---|---|
+| **CORE** | `Records`, `RecordFields`, `Messages`, `Surfaces`, `SurfaceElements`, `Actions`, `Vocabularies`, `VocabularyTerms` |
+| **CLIENT** (per tenant) | `TableViews`, `TableViewJoins`, `TableViewFields`, `AclRecordPermissions` / `AclFieldPermissions` / the rest of `Acl*`, `SurfaceOverrides`, `MessageTranslations`, `ThemeTokens` |
+
+Proof for the TableView half, rather than assumption: `_underscore/Model/Client/TableView.php:74`
+declares `database: _underscore::DB_CLIENT`. The Core half is the `Model/Core/*` counterpart.
+
+**The practical consequence:** a badge, a button or a column almost always needs **two files** — a
+`Core/` one and a `Client_<Tenant>/` one — and **every Core id the client file needs must be inlined
+as a literal, never sub-selected**. A `SELECT … FROM Core.…` inside a `Client_*` file cannot resolve
+in production and the hook refuses the write.
+
 ## SurfaceElements — two orthogonal axes + edit-mode columns (one tree serves view + edit)
 
 A record modal is modeled as **ONE** set of `<record>-record-*` SECTION surfaces (a header +
@@ -872,6 +895,14 @@ rule resumes.
 
 ## Gotchas
 
+- **🚨 A reserved-id comment block is NOT evidence.** Repo comments claimed `SurfaceElements`
+  reserved through 218; prod's `MAX(id)` was 220 and sandbox-client's was 232 (2026-09-03). Seeds
+  using AUTO_INCREMENT + `NOT EXISTS` consume ids invisibly and land differently per environment.
+  **Measure `MAX(id)` in every environment before picking a literal.**
+- **`TableViews` / `TableViewJoins` / `TableViewFields` / `Acl*` are CLIENT tables**
+  (`_underscore/Model/Client/TableView.php:74` → `DB_CLIENT`); `Records` / `RecordFields` /
+  `Messages` / `Surfaces` / `SurfaceElements` are **CORE**. A UI-layer change therefore needs two
+  files, and the client file must inline every Core id as a literal.
 - **🚨 SHIP-TOGETHER: `Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql`
   MUST be in the SAME release as `Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql`.**
   `Client_Nychh/2026-08-13a` resolved its Core ids via a cross-DB join and **stored the authoring
@@ -1058,6 +1089,22 @@ exactly (`MAX(Surfaces.id)` 44, `MAX(SurfaceElements.id)` 160) — that was **ve
 Using literals is still correct: a collision then fails loudly on the primary key instead of silently
 mis-wiring (which is what `INSERT IGNORE` did in the 2026-08-24 incident above).
 
+#### 🚨 The reserved-id COMMENTS in this repo do not match reality — and they drift PER ENVIRONMENT
+
+The comment blocks at the top of the seed files are a record of what was **claimed**, not of what is
+**taken**. Verified 2026-09-03: the repo comments said `SurfaceElements` were reserved through
+**218**, while `SELECT MAX(id)` returned **220 on production** and **232 on sandbox-client**.
+
+**Cause:** several seeds insert `SurfaceElements` with **AUTO_INCREMENT behind a `NOT EXISTS`
+guard** (the purely-additive pattern documented below) rather than with a literal id. Those rows are
+real and consume ids, but they leave no literal anywhere for a later author to read — and because
+each environment runs them at a different time against a different ceiling, the ids they land on
+**differ per environment**.
+
+> **Rule: measure `MAX(id)` in EVERY environment before picking a literal id.** Never take the
+> number from a comment block, a change-history entry, or this doc. The two authoring patterns are
+> both legitimate, but mixing them means the repo can never be an id ledger.
+
 #### Ceiling snapshot, verified read-only 2026-08-28 (before reserving the transfer-order block)
 
 | Environment | `MAX(Surfaces.id)` | `MAX(SurfaceElements.id)` | `MAX(Messages.id)` |
@@ -1383,6 +1430,21 @@ still unrun at the time, so this is a reservation, not a deployed state.
   rendered empty. Also recorded the **FE-first ship order**: the override alone exposes an
   unformatted value and crashes the modal (React error #31). Run on **client-sandbox `Client_Compass`
   only**; prod and Canada pending. (tcox)
+- 2026-09-04 — 🚨 **The reserved-id comment blocks in this repo do NOT match reality, and drift per
+  environment.** Comments said `SurfaceElements` were reserved through **218**; `SELECT MAX(id)`
+  returned **220 on production** and **232 on sandbox-client**. Cause: several seeds insert
+  `SurfaceElements` with **AUTO_INCREMENT behind a `NOT EXISTS` guard** instead of a literal id, so
+  the rows consume ids invisibly and land on different numbers in each environment. Rule recorded:
+  **measure `MAX(id)` in every environment before picking a literal** — a comment records a claim,
+  not a reservation. Also added a **verified Core-vs-Client placement cheat sheet** for the tables a
+  UI-layer migration touches (`TableViews`/`TableViewJoins`/`TableViewFields`/`Acl*`/
+  `SurfaceOverrides`/`MessageTranslations`/`ThemeTokens` = **CLIENT**, proven at
+  `_underscore/Model/Client/TableView.php:74` → `DB_CLIENT`; `Records`/`RecordFields`/`Messages`/
+  `Surfaces`/`SurfaceElements`/`Actions`/`Vocabularies`/`VocabularyTerms` = **CORE**), because a
+  badge or button change is almost always a two-file change and every Core id in the client file
+  must be an inlined literal. Confirmed on the transfer-order status badge + Inventory
+  create-transfer-order button seeds (`Core/2026-09-03a`+`b`, `Client_Nychh/2026-09-03a`+`b`), which
+  again followed the Core-seeds-OFF / tenant-opts-in default. (apeterson)
 - 2026-09-03 — Recorded the rule that **a modal needing surface-driven copy becomes its own Surface**:
   the resolver reads messages only from `*MessageId` columns and never from `config`, so
   `Core/2026-08-28b`'s `config.modal` keys could never resolve and the Columns modal rendered raw

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

@@ -10,7 +10,7 @@
 | [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/TransferOrders/viewModel/useTransferOrdersPageViewModel.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 |
 | [Persisted React Query cache (localStorage `supply-chain-query-cache`)](features/persisted-query-cache.md) | `localStorage["supply-chain-query-cache"]` is **not a hand-written cache**. | toga25-supply/src/App.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/hooks/useDeploymentGuard.tsx, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/hooks/useCurrentUser.ts, toga25-supply/src/hooks/useStatusTypeValues.ts, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/vite.config.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/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/layout/PrimaryTableServerLayout/PrimaryTableServerLayout.tsx, toga25-supply/src/layout/PrimaryTableServerLayout/types.ts, toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/GenericNestedTables.tsx, toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/helpers/buildInventoryPurchaseOrderUrl.ts, 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, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css |
+| [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/layout/PrimaryTableServerLayout/PrimaryTableServerLayout.tsx, toga25-supply/src/layout/PrimaryTableServerLayout/types.ts, toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/ItemFulfillmentModal/useItemFulfillmentModalViewModel.tsx, toga25-supply/src/layout/GenericNestedTables/GenericNestedTables.tsx, toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/helpers/buildInventoryPurchaseOrderUrl.ts, 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, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css |
 | [Side navigation & default route — an empty nav renders a BLANK PAGE and gets reported as "cannot log in"](features/side-navigation-and-default-route.md) | The 2.5 side nav is **100% backend-driven** by the `navigation` surface bundle, and the same list also decides **which routes exist** and **where `/` lands**. | toga25-supply/src/routes.tsx, toga25-supply/src/layout/AppLayout/viewModel/useAppLayoutViewModel.ts, api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [SSO redirect & public-vs-user session gating (useAuthenticationFlow)](features/sso-redirect-and-session-gating.md) | How 2.5 Supply decides, on every navigation, whether an anonymous visitor should be bounced to their client's SSO IdP instead of the local `/login` form. | toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/src/routes.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/api/api.ts |
 | [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/layout/RecordApprovalModal/helpers/stackedCurrencyJoiner.ts, toga25-supply/src/layout/RecordApprovalModal/helpers/stackedCurrencyJoiner.test.ts, toga25-supply/src/App.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/SalesOrderRecordModal.module.css, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/SalesOrderApprovalModalsLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/RecordApprovalModalLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css, toga25-supply/src/utils/formatDateTime.ts, toga25-supply/src/utils/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/layout/RecordApprovalModal/, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Bundles/viewModel/useBundlesPageViewModel.tsx, toga25-supply/src/layout/ItemFulfillmentModal/useItemFulfillmentModalViewModel.tsx, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/useServiceRequestRecordModalLayoutModel.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |

package/knowledge/2.0/apps/toga25-supply/features/column-visibility.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-03
+updated: 2026-09-04
 owners: [apeterson]
 files:
   - toga25-supply/src/components/ColumnVisibilityModal/
@@ -187,6 +187,11 @@ leaves a clean URL, and a column added to the meta later still shows up for that
 
 ## Gotchas
 
+- **⚠ The six-page `useColumnState` migration cannot be reverted file-by-file.** The shared
+  `ColumnVisibilityModalLabels` type gained **required** fields (`shown`, `hidden`, `lockedTip`,
+  `pinnedTip`), so restoring an old call site no longer type-checks — the build breaks. Roll the
+  whole change back together or not at all. (The dead `columnsButton` return in the SalesOrders view
+  model was deleted in the same pass.)
 - **No hardcoded copy in the component** — every user-facing string (incl. Close `aria-label`) is a
   required `labels` prop. On the **legacy** path the fallbacks live in the view model's resolution
   (never in the component or default props); on the **surface** path there are **no fallbacks at
@@ -211,6 +216,11 @@ leaves a clean URL, and a column added to the meta later still shows up for that
   meta later won't appear for an old link until Reset (intended).
 
 ## Change history
+- 2026-09-04 — ⚠ Recorded that the six-page `useColumnState` migration is **not reversible
+  file-by-file**: the shared `ColumnVisibilityModalLabels` type gained required fields (`shown`,
+  `hidden`, `lockedTip`, `pinnedTip`), so an old call site no longer type-checks and a partial revert
+  breaks the build. Roll it back whole or not at all. The dead `columnsButton` return in the
+  SalesOrders view model was removed in the same pass. (apeterson)
 - 2026-09-03 — The modal became **its own MODAL Surface** (`columns-modal`, **Core 60**; Messages
   293–298, SurfaceElements 222–232, `Core/2026-09-03c`). The 08-28 approach was unworkable: the
   resolver only collects messages from `*MessageId` columns and **never scans `config`**, so the

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

@@ -19,6 +19,7 @@ files:
   - toga25-supply/src/layout/SalesOrderRecordModalLayout/
   - toga25-supply/src/layout/SalesOrderItemsTableLayout/
   - toga25-supply/src/layout/ItemFulfillmentModal/
+  - toga25-supply/src/layout/ItemFulfillmentModal/useItemFulfillmentModalViewModel.tsx
   - toga25-supply/src/layout/GenericNestedTables/GenericNestedTables.tsx
   - toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx
   - toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx
@@ -110,6 +111,29 @@ navigation). `ItemFulfillmentModal` sets it because the fulfillment table is rea
 scoped so all other `PrimaryTableServerLayout` consumers keep normal row-click behavior — pass it
 only for genuinely read-only tables.
 
+### ⚠ `ItemFulfillmentModal`'s `slug` prop IS a TableView slug — and it is still hardcoded to sales orders
+
+The shared "Qty Fulfilled" drill-down modal (`src/layout/ItemFulfillmentModal/`) reads as if `slug`
+were a component variant. It is not: **`slug` is a TableView slug**, and the whole modal is built
+from it — `useTablePageMeta({ slug })` supplies the columns and
+`useTableData({ slug, tableViewMeta })` supplies the rows
+(`useItemFulfillmentModalViewModel.tsx`).
+
+**No TableView row for that slug → the modal opens EMPTY.** No error, no failed request. Reusing this
+modal for a new record type is therefore a **migration** first, a front-end change second.
+
+**Two spots are still hardcoded to sales orders** (blocking reuse as of 2026-09-04):
+
+1. **line ~27** — the label fetch always asks for page meta `"item-fulfillments-for-sales-orders"`,
+   whatever slug was passed in.
+2. **lines ~55–60** — the record filter falls back to **`"SalesOrders.uuid"`** for any unrecognised
+   slug, so a non-sales-order slug filters on the wrong column and returns nothing.
+
+**Measured in `Client_Nychh`: only TableViews 12 (`item-fulfillments-for-sales-orders`) and 13
+(`item-fulfillments-for-sales-order-items`) exist, both on `recordId` 29.** There is no
+transfer-order equivalent in any environment — see
+[transfer-orders-page](./transfer-orders-page.md).
+
 ## Pattern 5 — `GenericNestedTables` (config-driven multi-level / swap tables)
 
 A config-driven renderer: declare an array of `TableLevel` objects instead of hand-wiring each
@@ -343,6 +367,14 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
   EDIT is still JSON**: a field visible only in edit mode means a missing client `SurfaceOverride`,
   not a data bug (found on Compass's "Restrict to Persona" field). Detail in
   [surface-frontend](surface-frontend.md). (tcox)
+- 2026-09-04 — ⚠ Recorded that **`ItemFulfillmentModal`'s `slug` prop is a TableView slug**, not a
+  component variant: `useTablePageMeta`/`useTableData` build the entire modal from it, so a missing
+  TableView row opens the modal **empty and silently**. Reusing it for a new record type is a
+  migration before it is a front-end change. Also flagged the **two spots still hardcoded to sales
+  orders** — the label fetch always requests `item-fulfillments-for-sales-orders` (line ~27) and the
+  record filter falls back to `SalesOrders.uuid` for any unrecognised slug (lines ~55–60), so a
+  transfer-order slug today filters the wrong column and returns nothing. `Client_Nychh` has only
+  TableViews 12/13, both on `recordId` 29; no transfer-order equivalent exists anywhere. (apeterson)
 - 2026-09-03 — Added the **deep-link-from-a-modal-into-a-nested-table** pattern (pin `grouping`;
   build the column-filter chip with the `useServerTableUrlState` serializer, keyed by the table-meta
   **column id**; set `<slug>=<uuid>` to pre-expand the row) and the rule that makes it work:

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

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-09-04
-owners: [jcardinal, apeterson, tcox]
+owners: [jcardinal, apeterson, tcox, rgirish]
 files:
   - toga25-supply/src/layout/RecordApprovalModal/helpers/stackedCurrencyJoiner.ts
   - toga25-supply/src/layout/RecordApprovalModal/helpers/stackedCurrencyJoiner.test.ts
@@ -242,6 +242,28 @@ field even though its API returned the data. **It has been removed entirely.**
   `FIELDS[clientSlug]`) are the **legacy JSON fallback layer, NOT surface gating**, and are correctly left
   in place (they serve clients the backend doesn't yet drive via Surface).
 
+### ⚠ Corollary — NEVER resolve which table view a client's page uses by grepping `src`
+
+Because surface is backend-driven, the repo's grouping JSON is only the **DEFAULT**. A client's
+`SurfaceOverrides` can repoint a level at a completely different `fetchSlug`, and **that slug may
+appear nowhere in `src`** — which reads to a developer as "that view is dead code." It is not.
+
+**Rule: query that client's `SurfaceOverrides` in the target environment. A `grep` of the frontend
+repo cannot answer "which view does this client's page read?"**
+
+Worked case (Elite Inventory, prod, 2026-09-04):
+`src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json` uses `inventory_items` and
+`units-for-items-for-purchase-orders`, and **`inventory_units` appears nowhere in `src`**. But
+`Client_Elite.SurfaceOverrides` element **120** CONFIG is
+`{"key":"units","levels":[{"fetchSlug":"inventory_units","role":"flat"}]}` and element **118**
+(`unitsByItems`) also points at `inventory_units`, with 116/117 `IS_VISIBLE 0`. So Elite's live
+Units view is `inventory_units` (`TableViews` id 21), **not** id 17 — and a row filter applied to
+view 17 would have had no visible effect. See
+[Elite tableview config drift](../../../clients/elite/features/supply2-tableview-config-drift.md).
+
+This pairs with the standing rule that **a committed migration records intent, not deployed
+state** — the frontend repo records the default, not this tenant's state.
+
 ## SalesOrders record-modal sections — migrated via the registered-renderer seam
 
 The SalesOrders detail sections are migrated onto Surface via the registered-renderer approach (not a
@@ -783,8 +805,45 @@ in an edit to the shared blox stylesheet.
 ⚠ This is **shared infra** — `SurfaceActionBar` renders every migrated screen's chrome, so a change
 here is a cross-screen change. Re-check Sales Orders, Items and Vendor Items after touching it.
 
+## Hidden elements ARRIVE in the bundle — every hand-rolled builder must filter on `isVisible`
+
+The resolver ships the **whole** element tree and marks state on it; it does **not** prune. So a
+component that maps `bundle.elements` to its own controls **renders elements the Core seed
+deliberately turned off** unless it checks `el.isVisible` itself. `SurfaceActionBar` does this for
+you — a page that builds its own header buttons does not.
+
+Found 2026-09-03 on the **Inventory** page: `useInventoryPageViewModel` built its header buttons
+without the filter. It had no symptom only because no hidden element existed on that bar yet; the
+moment `Core/2026-09-03b` seeded the Create Transfer Order button `isVisible = 0`, it would have
+appeared for **every tenant** — defeating the whole Core-neutral-default / tenant-opt-in model. See
+[transfer-orders-page](./transfer-orders-page.md).
+
+> **Check for this wherever a view model reads `elements` directly.** `isVisible = 0` is the platform's
+> off switch; ignoring it turns every neutral default into an accidental release.
+
+## `useStatusColors` is keyed by `{ route, keyField }` — vocabularies do NOT all key on slug
+
+The original hook mapped a vocabulary slug to an API **route** and assumed the term `value` was
+always the record's **slug**. That held for sales orders and breaks for transfer orders:
+`TransferOrderStages` has no slug column, so its `VocabularyTerms.value` holds the stage **NAME**.
+
+`src/surface/useStatusColors.ts` therefore keys each vocabulary to a **`{ route, keyField }` pair**,
+and matches the term value against that field of the fetched rows
+(`?fields=slug,name,colorHex`). Adding a third STATUS vocabulary means answering *"what does its
+`VocabularyTerms.value` actually hold?"* before wiring it — a wrong `keyField` produces a badge with
+the right label and no colour, and logs nothing.
+
+Full badge chain (`RecordFields.type='STATUS'` → `Records.statusRecordId` → route → typeValues →
+blox `StatusCell`, which is a plain `typeValues[value]` lookup):
+[transfer-orders-page](./transfer-orders-page.md).
+
 ## Gotchas
 
+- **⚠ Hidden elements are IN the bundle** — a hand-rolled control builder that ignores
+  `el.isVisible` ships every element the Core seed turned off (see the section above).
+- **⚠ A STATUS badge renders label-but-no-colour when the vocabulary's `keyField` is wrong** —
+  `StatusCell` is a plain map lookup on the cell value, so a name against a slug-keyed vocabulary
+  just misses, silently.
 - **A vitest file that reaches `@agilant/toga-blox` must stub the whole package:
   `vi.mock("@agilant/toga-blox", () => ({}))`.** blox's `dist` entry imports `global.css`, which
   node's ESM loader rejects, so **any** import chain that transitively pulls blox in fails to load
@@ -1055,6 +1114,22 @@ unused).
   "Unexpected Application Error!" because the app has no top-level `ErrorBoundary`.
   `formatPersonaItems` now accepts both value shapes and is registered under both keys. **Deploy the
   FE first or together — the SQL alone crashes the modal.** (tcox)
+- 2026-09-04 — Two shared-infra findings from the transfer-order status badge. (1) ⚠ **Hidden
+  elements arrive in the resolved bundle** — the resolver marks state, it never prunes — so any view
+  model that builds its own controls from `bundle.elements` must filter on `el.isVisible`. The
+  Inventory header-button builder did not; it was symptomless only until `Core/2026-09-03b` seeded a
+  deliberately-hidden button, which would then have shown for every tenant. (2) **`useStatusColors`
+  is now keyed by `{ route, keyField }`, not by route alone**: sales-order terms carry the status
+  **slug** but transfer-order terms carry the stage **NAME** (`TransferOrderStages` has no slug
+  column), and a wrong key field yields a correctly-labelled badge with no colour and no log line.
+  (apeterson)
+- 2026-09-04 — Added the diagnostic corollary to "surface is 100% backend-driven": **a client's
+  live `fetchSlug` may appear nowhere in `src`, so grepping the frontend repo cannot tell you which
+  table view a client's page reads — query that client's `SurfaceOverrides` in the target
+  environment.** Worked case: Elite's Inventory Units level resolves to `inventory_units`
+  (`TableViews` 21) via prod `SurfaceOverrides` elements 120/118, while the repo DEFAULT JSON names
+  `units-for-items-for-purchase-orders` (17) and `inventory_units` is absent from `src` entirely.
+  No code change. (rgirish)
 - 2026-09-03 — Recorded that the 2.5 app **still calls `GET /v2/pages/meta`** from five view
   models (SalesOrders — twice per load — VendorItems, Inventory, Bundles, ItemFulfillmentModal)
   even though nothing in `src/` reads a field off the result. Found by the new Cypress

package/knowledge/2.0/apps/toga25-supply/features/toolbar-button-chrome.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-03
+updated: 2026-09-04
 owners: [apeterson]
 files:
   - toga25-supply/src/components/ToolbarButton/ToolbarButton.tsx
@@ -64,6 +64,24 @@ than by luck with whatever font metrics resolve.
 **The "applied" signal never fills the button.** Instead the glyph moves into a small filled rounded
 square — Group by: 18×18, radius 4, `#3F5DCA`, white glyph.
 
+### The API — `shape` + `activeAppearance`, generalised from `ColumnsToolbarButton`
+
+`ToolbarButton` was **generalised out of the one-off `ColumnsToolbarButton`**, not written fresh, so
+the Columns button is the reference call site.
+
+- **`shape`** picks between the two design shapes above: **`pill`** for actions (Refresh, Reset),
+  **`chip`** for management controls (Columns, Group by). One component, two shapes — not two
+  components.
+- **`activeAppearance`** separates the **transient** active state (pressed / in-flight) from the
+  **persistent** one (a filter or grouping is currently applied). They look different by design and
+  had previously been conflated, so a button could look permanently "on" after a single click.
+
+### Toolbar spacing — `gap-x-2` (8px), not `gap-x-5` (20px)
+
+Three labeled-mode pages (Transfer Orders, Sales Orders, Inventory) shipped with `gap-x-5` = **20px**
+between toolbar buttons; the mockup is **8px**. Corrected to `gap-x-2` on all three. Worth stating
+explicitly because 20px looks deliberate rather than wrong until it is next to the design.
+
 **Buttons the design does not specify keep `BaseButton`:** PRIMARY create actions, and the Approvals
 filter button (SurfaceElement 22, `config.role = filterButton`), whose navy fill is a clearer "on"
 signal than a chip.
@@ -84,6 +102,13 @@ signal than a chip.
   `Columns (N)` label when the columns differ from default.
 
 ## Change history
+- 2026-09-04 — Recorded the component's actual API and the spacing fix: `ToolbarButton` was
+  **generalised out of `ColumnsToolbarButton`** and takes a **`shape`** prop (`pill` for actions,
+  `chip` for management controls) plus an **`activeAppearance`** prop that separates a **transient**
+  active state (pressed/in-flight) from a **persistent** one (a filter or grouping is applied) —
+  previously conflated, which left a button looking permanently on. Also corrected the toolbar gap
+  from `gap-x-5` (20px) to **`gap-x-2` (8px)** on the three labeled-mode pages (Transfer Orders,
+  Sales Orders, Inventory) to match the mockup. (apeterson)
 - 2026-09-03 — Created. A page toolbar rendered three buttons at three different heights; the cause is
   that blox `.secondaryBtnAction` hard-codes `height: 26px` with **no theme token**, while
   `.primaryBtn` sets no height at all. Rethemeing would hit every button in the app, so the toolbar

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 24 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 25 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 34 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)

package/knowledge/clients/elite/INDEX.md

@@ -2,10 +2,10 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [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 — 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, dbchanges2/Client_Elite/2026-09-04a - EliteItemAssetTypeApiWritePermission.sql, library/app/api/toga2.php, library/app/api/netsuite/rest.php, 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, 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 — 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/Client_Elite/2026-08-13a - InventoryGroupingsSurfaceOverrides.sql, dbchanges2/Client_Elite/2026-09-04b - EliteInventoryHideServiceItems.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/netsuite-togasupply-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: elite
 type: client-feature
 status: active
-updated: 2026-09-03
+updated: 2026-09-04
 owners: ["snaredla", "jcardinal", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/sync_togasupply_elite.php
@@ -16,10 +16,14 @@ files:
   - _underscore/Model/Elite/PurchaseOrder.php
   - _underscore/Model/Elite/ItemReceipt.php
   - dbchanges2/Client_Elite/_modules.txt
+  - dbchanges2/Client_Elite/2026-09-04a - EliteItemAssetTypeApiWritePermission.sql
+  - library/app/api/toga2.php
+  - library/app/api/netsuite/rest.php
   - test/@srija/Elite Testing/Service Requests/test_sync_togasupply_elite_section.php
   - test/@srija/Elite Testing/Service Requests/test_diagnose_togasupply_elite.php
 related:
   - ../profile.md
+  - ../../../1.0/apps/library/features/netsuite-item-assettype-sync.md
   - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
   - ../../../1.0/apps/worker/workflows/onboarding-client-to-netsuite-togasupply-sync.md
   - ./salesorder-netsuite-push.md
@@ -81,11 +85,16 @@ the trait declares must exist as a column, a `CustomRecordFields` row **and** an
   other 17 wrappers inherit — Elite is backfilling from 2024 and 5-day windows on a 5-minute cron were
   too slow. This is only possible because the shared engine now `define()`s the cap instead of
   `const`-ing it. **Reduce it to the default once the backfill is caught up.**
-- **`IS_ENABLED_INTEGRATION_INVOICES = false` — TEMPORARY.** The invoice section scans the whole
-  NetSuite transaction table per window, kept running out of time, and **starved the item-receipt and
-  item-fulfillment sections that follow it** — which are what `_qtyOnHand` derives from. Re-enable
-  once inventory has caught up. (Note the invoice section is also capped at `now − 86400s` by design,
-  so it always trails.)
+- **⚠ EVERY integration flag is now `true` (2026-09-04) — including invoices, and that carries a
+  live risk.** `_SALES_ORDERS`, `_INVOICES`, `_ITEM_RECEIPTS`, `_ITEM_FULFILLMENTS`,
+  `_INVENTORY_ADJUSTMENTS` and `_TRANSFER_ORDERS` were all flipped `false → true`
+  (`_PURCHASE_ORDERS` was already on); stale comments were removed, including one that still said
+  transfer orders were off. **Invoices was deliberately disabled** because its section scans the
+  whole NetSuite transaction table per window, kept running out of time, and **starved the
+  item-receipt and item-fulfillment sections that follow it** — the ones `_qtyOnHand` derives from.
+  It is back on **at the same time as a planned PO cursor backfill**, so the starvation risk is
+  live. **If item receipts stop advancing, invoices is the first suspect.** (The invoice section is
+  also capped at `now − 86400s` by design, so it always trails.)
 - **`MIN_DATETIME_TO_CHECK_FOR_NETSUITE_DATA = '2018-01-01'`**, with the real start controlled by the
   seeded `Parameters` cursors.
 - **`TRANSFER_ORDER_DETECTION_MODE` is pre-set but NOT in use (2026-09-03).** Elite's wrapper declares
@@ -96,6 +105,54 @@ the trait declares must exist as a column, a `CustomRecordFields` row **and** an
   transfer orders as $0 held sales orders; do not assume the pre-set mode is correct for them. Mode
   mechanics: [per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
 
+### Elite is the ONLY client opted in to assetType stamping
+
+Elite's wrapper defines `NETSUITE_ITEM_TYPE_TO_ASSET_TYPE_NAME`, which turns on
+[assetType stamping from NetSuite `itemtype`](../../../1.0/apps/library/features/netsuite-item-assettype-sync.md).
+No other launcher defines it, so the other ~19 clients send no `assetType` key at all.
+
+```
+'InvtPart' => 'Laptop',   'Kit' => 'Laptop',      'Group' => 'Laptop',
+'Service'  => 'Services', 'NonInvtPart' => 'Services', 'OthCharge' => 'Services',
+'Discount' => 'Services', 'Expense' => 'Services',     'Description' => 'Services'
+```
+
+`Client_Elite.AssetTypes` has exactly **2 rows: 1 = `Laptop`, 2 = `Services`.** The non-inventory
+types are in the map on purpose — `itemtype = 'Service'` alone marks only **11 of ~28** real Elite
+services, because `NonInvtPart` is mixed (`SVC-FS-DEPLOY`, `SVC-FS-SHIPPING-*`,
+`SVC-CI-RETAINER-RS`, `SVC-TS-Removal`, `Project - Cabling`). Elite's 113 items break down as
+65 InvtPart / 11 Service / 17 NonInvtPart.
+
+**Two deploy prerequisites, in this order:**
+
+1. **`dbchanges2/Client_Elite/2026-09-04a - EliteItemAssetTypeApiWritePermission.sql` must run
+   BEFORE the library/worker deploy.** It grants `AclFieldPermissions` write on recordFieldId
+   **269** (`Items.assetTypeId`) to **roleId 3 (API)**, which previously held roleId 1 only. api2
+   fails the **entire** item write on a non-writable field, so deploying the code first breaks item
+   creation for Elite. **Applied in production and re-verified** (269 now carries roleId 1 and 3).
+2. **A cursor rollback is required to stamp existing items.** `getCreateItem()` only runs when a
+   transaction line references an item, so Elite's **110 already-NULL items stay NULL** until the
+   sync re-walks transactions that reference them. Cursors are in `Client_Elite.Parameters`
+   (`NETSUITE_LAST_SYNC_CURSOR_*`, value `"<lastmodifieddate>|<netsuiteInternalId>"`).
+
+   Prod cursor state at the time of this work, `NETSUITE_EXECUTION_MODE_*` all `IDLE`:
+
+   | Section | Cursor |
+   |---|---|
+   | PURCHASE_ORDERS (the only section then enabled) | `2026-09-04 12:56:00\|0` |
+   | SALES_ORDERS | `2026-09-01 15:45:56\|0` |
+   | ITEM_RECEIPTS | `2026-09-01 16:04:00\|0` |
+   | ITEM_FULFILLMENTS | `2026-09-01 16:04:11\|0` |
+   | INVOICES | `2026-08-20 00:00:00\|0` |
+   | INVENTORY_ADJUSTMENTS | `2026-09-01 16:04:21\|0` |
+
+**3 Elite items are typed `InvtPart` in NetSuite but are really services** —
+`SVC-TS-ELITE-HDONBOARDING`, `CONFIG/INSTALL`, `CONF-RM-INSTALL-SUPP`. **Decided: a NetSuite
+data-hygiene ask for the client, not a code special case.** Stamping is fill-NULL-only, so a manual
+TOGa correction survives later syncs. The Inventory filter also keeps a `SVC-` part-number prefix
+rule that still catches these three — see
+[supply2-tableview-config-drift](./supply2-tableview-config-drift.md).
+
 ## Gotchas / known issues
 
 - **⚠ Two files named `sync_togasupply_elite.php`, both scheduled.**
@@ -132,6 +189,22 @@ the trait declares must exist as a column, a `CustomRecordFields` row **and** an
 
 ## Change history
 
+- 2026-09-04 — **Elite became the first (and only) client opted in to assetType stamping**, and
+  **all integration flags were switched on.** Added `NETSUITE_ITEM_TYPE_TO_ASSET_TYPE_NAME` to the
+  wrapper (InvtPart/Kit/Group → `Laptop`; Service/NonInvtPart/OthCharge/Discount/Expense/Description
+  → `Services`) — the non-inventory types are needed because `NonInvtPart` is mixed and
+  `itemtype = 'Service'` alone catches only 11 of ~28 real services. Shipped
+  `2026-09-04a - EliteItemAssetTypeApiWritePermission.sql` (recordField **269** write grant to
+  **roleId 3**; applied and re-verified in prod) which **must run before the library/worker
+  deploy**, since api2 fails the whole item write on a non-writable field. Elite's 110 NULL items
+  need a **PO cursor rollback** to be stamped — `getCreateItem()` only fires on a referenced
+  transaction line; prod cursor state recorded above. Flipped `_SALES_ORDERS`, `_INVOICES`,
+  `_ITEM_RECEIPTS`, `_ITEM_FULFILLMENTS`, `_INVENTORY_ADJUSTMENTS`, `_TRANSFER_ORDERS` to `true` and
+  removed stale comments — **note the invoices risk**: it was disabled for starving the
+  receipt/fulfillment sections, and it is back on alongside the cursor backfill. Engine mechanics
+  and the two platform blockers:
+  [assetType sync](../../../1.0/apps/library/features/netsuite-item-assettype-sync.md). (rgirish)
+
 - 2026-09-03 — Elite's wrapper now declares `TRANSFER_ORDER_DETECTION_MODE =
   App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__ZERO_DOLLAR_HOLD` as part of the shared
   transfer-order detection-mode refactor (the old `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`

package/knowledge/clients/elite/features/supply2-tableview-config-drift.md

@@ -6,17 +6,22 @@ project: Database Changes
 client: elite
 type: client-feature
 status: active
-updated: 2026-08-18
-owners: [tcox, bala]
+updated: 2026-09-04
+owners: [tcox, bala, rgirish]
 files:
   - dbchanges2/Client_Elite/
   - dbchanges2/Client_Elite/2026-08-07 - ServiceRequests TableView.sql
   - dbchanges2/Client_Elite/2026-08-17 - FulfillmentTableViews.sql
+  - dbchanges2/Client_Elite/2026-08-13a - InventoryGroupingsSurfaceOverrides.sql
+  - dbchanges2/Client_Elite/2026-09-04b - EliteInventoryHideServiceItems.sql
   - dbchanges2/Core/2026-08-07 - ServiceRequests TableView.sql
   - dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql
   - dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql
 related:
   - ./supply2-scope.md
+  - ./netsuite-togasupply-sync.md
+  - ../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md
+  - ../../../2.0/apps/toga25-supply/features/surface-frontend.md
   - ../../../2.0/apps/_underscore/features/tracking-number-bridges.md
   - ../../../2.0/apps/_underscore/features/units-for-items-for-purchase-orders.md
   - ../../../2.0/apps/_underscore/features/page-meta-context-field-settings.md
@@ -241,6 +246,61 @@ Do not revive this without first re-testing finding 2 above.
 
 </details>
 
+## ⚠⚠ Which table view Elite's Inventory page uses comes from `SurfaceOverrides` — NOT the repo JSON
+
+**Durable rule: never conclude which table view a client's page uses by grepping the frontend repo.
+Query that client's `SurfaceOverrides` in the target environment.** This corrected a wrong
+conclusion mid-session and is the most reusable finding here.
+
+Reading `toga25-supply/src` is actively misleading for Elite:
+
+- `src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json` uses `inventory_items` and
+  `units-for-items-for-purchase-orders`.
+- **`inventory_units` appears nowhere in `src`** — which reads as *"`inventory_units` is a dead
+  view."* **It is not.**
+
+Verified on production `Client_Elite.SurfaceOverrides`:
+
+| Element | CONFIG / setting |
+|---|---|
+| **120** | `{"key":"units","levels":[{"fetchSlug":"inventory_units","role":"flat"}]}` |
+| **118** | `unitsByItems` — also points at `inventory_units` |
+| 116 / 117 | `IS_VISIBLE 0` (hidden) |
+
+Surface config **overrides** the repo JSON (surface resolution is 100% backend-driven — see
+[surface-frontend](../../../2.0/apps/toga25-supply/features/surface-frontend.md)). So **for Elite
+the live Units view is `inventory_units` (`TableViews` id 21), not
+`units-for-items-for-purchase-orders` (id 17).** Elite's overrides were seeded by
+`2026-08-13a - InventoryGroupingsSurfaceOverrides.sql`.
+
+This pairs with the existing team rule that **a committed migration records intent, not deployed
+state** — the frontend repo records the *default*, not this client's state.
+
+## Hiding service lines from Inventory — `2026-09-04b`
+
+`2026-09-04b - EliteInventoryHideServiceItems.sql` sets `TableViews.apiWhereClause`:
+
+| View | Clause |
+|---|---|
+| `inventory_units` | `(IFNULL(Items.assetTypeId,0):ne:2)` |
+| `inventory_items` | `(Items.partNumber:excludes:SVC-,IFNULL(Items.assetTypeId,0):ne:2)` |
+
+`assetTypeId 2` = Elite's `Services` row. Notes for anyone porting this:
+
+- **The filter belongs in the database table view, not the frontend** — an explicit scope decision.
+- **`IFNULL(...,0):ne:2` is mandatory, not cosmetic.** A bare `:ne:2` drops every `NULL` row and
+  would hide **all unstamped items** — and 110 of Elite's 113 items are unstamped until the cursor
+  backfill runs. The shape is copied from Elite's existing `item-fulfillments-for-sales-orders`
+  view. Grammar and the NULL-drop rule:
+  [apiWhereClause row filtering](../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md).
+- **The `SVC-` prefix rule is kept on `inventory_items`** because it still catches the three items
+  NetSuite mis-types as `InvtPart` (`SVC-TS-ELITE-HDONBOARDING`, `CONFIG/INSTALL`,
+  `CONF-RM-INSTALL-SUPP`) — see
+  [netsuite-togasupply-sync](./netsuite-togasupply-sync.md).
+- **Both `UPDATE`s are guarded on the current value**, so a re-run is a no-op.
+- `inventory_units` was targeted **because of the `SurfaceOverrides` finding above** — filtering
+  view 17 would have had no visible effect for Elite.
+
 ## Gotchas / known issues
 
 - **A `Client_*` DB that predates a platform migration fails silently until a user opens the
@@ -252,6 +312,18 @@ Do not revive this without first re-testing finding 2 above.
   [error-reporting-issue-event](../../../2.0/apps/_underscore/features/error-reporting-issue-event.md).
 
 ## Change history
+- 2026-09-04 — **Corrected which table view Elite's Inventory page actually reads, then filtered
+  it.** `toga25-supply/src` shows the DEFAULT groupings using `inventory_items` +
+  `units-for-items-for-purchase-orders`, and `inventory_units` appears nowhere in `src` — reading as
+  a dead view. Production `Client_Elite.SurfaceOverrides` proves otherwise: element **120** CONFIG
+  points `units` at `inventory_units` and element **118** (`unitsByItems`) does too, with 116/117
+  hidden. **Durable rule recorded: never resolve a client's table view by grepping the frontend
+  repo — query that client's `SurfaceOverrides` in the target environment.** Shipped
+  `2026-09-04b - EliteInventoryHideServiceItems.sql` to hide service lines via `apiWhereClause` on
+  `inventory_units` and `inventory_items`, using the mandatory `IFNULL(Items.assetTypeId,0):ne:2`
+  shape (a bare `:ne:2` would hide all 110 unstamped items) and keeping the existing `SVC-` prefix
+  rule for the three NetSuite-mis-typed items. Both UPDATEs are guarded so a re-run is a no-op.
+  (rgirish)
 - 2026-08-18 - **The Elite table views shipped as migrations, and two of the planned approaches
   turned out to be wrong.** Built the `service-requests` view (record 35, 5 OUTER joins, 9 columns)
   and the all-clients `inventory_units` view (record 31, Items as spine, 15 joins, 13 columns);

package/knowledge/clients/elite/profile.md

@@ -16,8 +16,8 @@ project: Worker
 client: elite
 type: profile
 status: active
-updated: 2026-08-26
-owners: [snaredla, apeterson, tcox, bala]
+updated: 2026-09-04
+owners: [snaredla, apeterson, tcox, bala, rgirish]
 files:
   - worker2/Worker/Elite.php
   - worker2/Worker/Sync/ServiceRequest.php
@@ -55,6 +55,15 @@ remaining stale views are still an open production go-live risk** - see
 dbchanges2 **PR #454** (TRUE-80499, snaredla24, 2026-08-05) added the **netsuite** module to
 `Client_Elite/_modules.txt` — the supply-chain schema layer is arriving.
 
+**Elite is the only client opted in to NetSuite `itemtype` → `assetType` item stamping
+(2026-09-04),** which is how service lines are hidden from the Inventory page. It needed a
+`Client_Elite` API-role write grant on `Items.assetTypeId` **before** the code deploy, and its
+existing 110 NULL items need a PO cursor rollback to be stamped — see
+[netsuite-togasupply-sync](features/netsuite-togasupply-sync.md) and the
+[shared assetType feature](../../1.0/apps/library/features/netsuite-item-assettype-sync.md). **All
+of Elite's integration flags are now on, invoices included** — invoices had been disabled for
+starving the receipt/fulfillment sections, so that risk is live again.
+
 **Elite is live on the inbound NetSuite → TOGa Supply sync as of 2026-08-12 (TRUE-80499).** A
 `*/5` worker cron backfilled April 2024 → Aug 2026 in ~90 minutes (257 sales orders, 234 purchase
 orders, 201 item fulfillments, 153 items, 229 units) — this is what adds **`worker`** (1.0) to

package/package.json

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