toga-ai 1.0.810 → 1.0.812

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

@@ -17,6 +17,7 @@
 | [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 |
 | [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. |
 | [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 |
+| [NetSuite classification → ItemClasses sync (opt-in per client)](features/netsuite-item-class-sync.md) | `App_Api_Toga2::getCreateItemClass()` mirrors NetSuite's **classification tree** into the client's `ItemClasses` table and stamps `Items.itemClassId`. |
 | [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 |
 | [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 |
 | [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. |

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

@@ -0,0 +1,150 @@
+---
+title: NetSuite classification → ItemClasses sync (opt-in per client)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-09-15
+owners: [rgirish]
+files:
+  - library/app/api/toga2.php
+  - worker/crons/toga2/netsuite/sync_togasupply_elite.php
+  - dbchanges2/_modules/netsuite/2026-09-11a - ItemClassesNetsuiteHierarchy.sql
+  - dbchanges2/_modules/netsuite/2026-09-11b - ItemClassApiWritePermission.sql
+  - dbchanges2/_modules/netsuite/2026-09-11c - ItemClassRecordPermission.sql
+related:
+  - netsuite-item-assettype-sync.md
+  - netsuite-item-isfulfillable-sync.md
+  - toga2-api-client-and-bridge.md
+  - ../../worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../../2.0/apps/_underscore/features/item-classification-itemclasses.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md
+  - ../../../clients/elite/features/netsuite-togasupply-sync.md
+---
+
+## Summary
+
+`App_Api_Toga2::getCreateItemClass()` mirrors NetSuite's **classification tree** into the client's
+`ItemClasses` table and stamps `Items.itemClassId`. It is **opt-in per client** via
+`IS_ENABLED_NETSUITE_ITEM_CLASSIFICATIONS`, and today **only Elite** has it on.
+
+It is the third flag stamped by the item importer, alongside
+[assetType](netsuite-item-assettype-sync.md) and [isFulfillable](netsuite-item-isfulfillable-sync.md).
+Unlike those two it **creates rows** rather than linking to a hand-curated lookup, so it needs a
+schema migration and a full ACL chain before it can run.
+
+**Do not repurpose `ItemClasses` without reading
+[who already uses it](../../../2.0/apps/_underscore/features/item-classification-itemclasses.md)** —
+Northwell (27 rows, ServiceNow categories) and Prudential (7 rows, device tiers) already hold
+unrelated data in that table.
+
+## Key files / entry points
+
+- **`library/app/api/toga2.php` → `getCreateItemClass()`** — the whole feature. Returns an
+  `ItemClasses.uuid` or `null`.
+- **`App_Api_Netsuite_Rest::listClassifications()`** — pulls the full NetSuite tree (311 rows as of
+  2026-09-11).
+- **`worker/crons/toga2/netsuite/sync_togasupply_elite.php:65`** — the only launcher that turns it on.
+
+## How it works
+
+1. **Gated first.** If `IS_ENABLED_NETSUITE_ITEM_CLASSIFICATIONS` is undefined or false it returns
+   `null` immediately, so the `itemClass` key never reaches the item payload.
+2. **Caches the NetSuite tree once per run** into a `static` map keyed by `internalId`.
+3. **Caches the client's existing rows once per run** via paged `GET /item-classes`, keyed by
+   `c_netsuiteInternalClassId`.
+4. **Climbs to the root** collecting the ancestor chain, then **creates from the root down** so each
+   parent exists before its child's `parentItemClass` references it.
+5. Each `POST /item-classes` sends `name` + `c_netsuiteInternalClassId` (+ `parentItemClass.uuid`).
+
+**Matching is on the NetSuite internal id, never on name.** NetSuite classification names repeat
+across branches ("Shipping" appears 3x), which is why
+`2026-09-11a - ItemClassesNetsuiteHierarchy.sql` **drops the `name` UNIQUE index** and adds a UNIQUE
+on `c_netsuiteInternalClassId` instead.
+
+### Two cache guards worth keeping
+
+- **A loaded-flag, not `empty()`.** `ItemClasses` starts empty on every client, so an `empty()` check
+  would re-fetch the whole list on every item until the first class exists.
+- **`recordsPerPage => 1000` is explicit on purpose.** An unpaginated V2 list GET **silently
+  truncates at 25 rows** — with the default the lookup would miss existing classes and try to
+  re-create them.
+
+## ⚠ The field name is `c_netsuiteInternalClassId` — no `Item` in the middle
+
+The single trap in this feature, and it broke the whole thing on first deploy.
+
+The migration and the live DB column are **`c_netsuiteInternalClassId`**. The code shipped in
+`37b55595` used **`c_netsuiteInternalItemClassId`** in all 5 places. Symptoms:
+
+- Every `POST /item-classes` failed with **`EV-9`** — api2 rejects the *entire* record when one field
+  is not writable, and an unregistered field is not writable.
+- The lookup `GET` asked for a field that does not exist, so `$lookupItemClassUuid` never populated.
+- Net effect: `Client_Elite.ItemClasses` held **0 rows** — the feature never worked at all since
+  deploy, with no error surfaced to the cron.
+
+**The migration file is the authority on a custom-field name; code follows the DB.** The column is
+already live in ~22 client databases, so renaming the column to match the code was never an option.
+Fixed in `70f1129f` (merged PR #883, in `_production`).
+
+**Generalise this:** before shipping any `c_` field, grep the `dbchanges2` migration for the exact
+string and diff it against the PHP. A mismatch here is invisible — no 500, no log line, just an empty
+table.
+
+## Required schema + ACL (all three layers)
+
+`ItemClasses` is `Core.Records` id **105**, `aclDatabase = CLIENT` — so **every grant lives in the
+client database, not Core**. Records 15, 18, 21 and 105 are all CLIENT.
+
+| Layer | Table | What it grants | Migration |
+|---|---|---|---|
+| Record | `AclRecordPermissions` + paired `AclLogicGroups` | roleId 3 create/read/update on record 105 | `2026-09-11c` |
+| Base field | `AclFieldPermissions` | roleId 3 writable on RecordFields 601-605, 2596 | `2026-09-11b` |
+| Custom field | `AclCustomFieldPermissions` | roleId 3 writable on `c_netsuiteInternalClassId` | `2026-09-11a` |
+
+RecordFields worth knowing: **605** = `Items.itemClassId`, **2596** =
+`ItemClasses.parentItemClassId`, **2594/2595** = `SalesOrderItems.fulfillmentType` /
+`PurchaseOrderItems.fulfillmentType`.
+
+**The record-level layer is the one that gets missed** — field grants alone are not enough, and
+without `AclRecordPermissions` the API role cannot `POST /item-classes` at all. Full mechanics:
+[ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md).
+
+## Gotchas
+
+- **⚠ `2026-09-11c` has no duplicate guard.** It is a plain `INSERT` into `AclRecordPermissions`, so
+  every re-run inserts another row. Production shows **three** rows for recordId 105 / roleId 3 on
+  every client checked (Elite: ids 346, 347, 348), and only the first (346) has a paired
+  `AclLogicGroups` — Elite has 3 logic groups hanging off it instead of 1. Harmless today (all rows
+  grant the same access) but it is noise, and the file should get a `NOT EXISTS` guard on
+  `(recordId, roleId)` per
+  [re-runnable additive migrations](../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md).
+  Those migrations also use `UUID()`, which the team standard forbids.
+- **The opt-in constants are the safety net for other clients.** `getCreateItemClass()` and the
+  `fulfillmentType` path both return early without their flag, so the keys are omitted entirely and
+  no un-provisioned client can hit `EV-9`. Confirmed by grep across all 19
+  `sync_togasupply_*.php` launchers — only Elite defines either constant.
+- **Before another client opts in it needs three things**, not just the shared module: (a) the
+  `_modules/netsuite` 2026-09-11 grants — already applied broadly (Canon, Quad, Nychh, Adyen,
+  Prudential all have record 105 + fields 601-605, 2596); (b) an Elite-`2026-09-11a`-equivalent
+  setting `allowUpdate = 1` on records **21** (Items) and **18** (Purchase order items) — Canon,
+  Nychh and Adyen are currently `0` there; (c) the Elite-`2026-09-11b`-equivalent grants on fields
+  **2594/2595**.
+- **Existing items are not backfilled.** Like assetType stamping, `getCreateItem()` only runs when a
+  transaction line references the item, so already-imported items keep `itemClassId = NULL` until the
+  sync re-walks transactions that reference them. That needs a
+  [cursor rewind](../../worker/features/netsuite-togasupply-per-client-sync.md).
+
+## Change history
+- 2026-09-15 — Documented the feature from an audit of the deployed code (library `37b55595`, worker
+  `6637ae75`). **Found and fixed a field-name mismatch that made the feature a complete no-op since
+  deploy:** the PHP sent `c_netsuiteInternalItemClassId` in 5 places while the live column and
+  `CustomRecordFields` row (recordId 105) are `c_netsuiteInternalClassId`, so every `POST
+  /item-classes` failed `EV-9` and `Client_Elite.ItemClasses` had 0 rows. Fixed in `70f1129f`.
+  Verified all three ACL layers are correctly granted for Elite in production, and recorded that the
+  two opt-in constants are Elite-only so no other client is exposed. Also recorded that
+  `2026-09-11c` is unguarded and has produced 3 duplicate `AclRecordPermissions` rows per client.
+  (rgirish)

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

@@ -32,6 +32,7 @@ related:
   - ../../library/features/toga2-api-client-and-bridge.md
   - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
   - ../../../clients/elite/features/netsuite-togasupply-sync.md
+  - ../../library/features/netsuite-item-class-sync.md
   - ../../../clients/compass-usa/features/sales-order-line-renumbering.md
 ---
 
@@ -68,7 +69,7 @@ Each section (sales orders, POs, invoices, item receipts, item fulfillments, inv
 adjustments) uses **adaptive time-windowing** via `startModeIteration()`/`finishModeIteration()`:
 a window stored as `<seconds>-<STATE>` in the client's `Parameters` table shrinks ÷3 when the
 prior run was left `RUNNING` (didn't finish) and grows ×3 (capped at
-`MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS`, default 432000s = 5 days) when it
+`MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS`, default **864000s = 10 days**) when it
 finished `IDLE`. The window state is written `RUNNING` at the **start** of each section, so a
 crash leaves it visibly RUNNING and the next run backs off. `LAST_SYNC_DATETIME_*` advances to
 the window's upper bound after each successful section.
@@ -76,12 +77,15 @@ the window's upper bound after each successful section.
 ### The window cap is per-client overridable (2026-08-12)
 
 `common_sync_togasupply.php:3` is
-`defined('MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS') || define(…, 432000)` — **not** a
+`defined('MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS') || define(…, 864000)` — **not** a
 `const` — so a wrapper may `const MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS = …;`
-*before* its `require_once` to widen its own catch-up window. Only Elite does (2592000 = 30 days,
-while backfilling from 2024); the other 17 wrappers inherit the 5-day default. Use this only for a
-deep backfill and put the reason in a comment next to it — at 5-day windows on a 5-minute cron,
-~858 days of history takes days of wall-clock to catch up; at 30 days it took ~90 minutes.
+*before* its `require_once` to widen its own catch-up window.
+
+**⚠ Re-verified 2026-09-15: the shared default is now `864000` (10 days), and NO wrapper overrides
+it — including Elite.** Elite's 30-day (2592000) backfill override was removed after its 2024
+backfill finished, exactly as the note here said it should be. So today every client runs the same
+10-day cap, and a deep rewind advances at most 10 days per run (see the resync recipe below). Use an
+override only for a deep backfill, and put the reason in a comment next to it.
 
 ### ⚠ A shrinking window is a BUG SIGNAL, not a load signal
 
@@ -125,8 +129,9 @@ mis-set during the 2026-09-08 Elite incident:
 - **The cap is `864000` (10 days), not `86400` (1 day).** One zero short is a silent 10× smaller
   window, not an error.
 
-(`MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS` is per-client overridable — Elite's wrapper sets
-2592000. Reset to the client's own cap, not blindly to 864000.)
+(`MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS` is per-client overridable, but as of 2026-09-15
+**no wrapper overrides it** — Elite's old 2592000 is gone. So `864000` is the right value for every
+client today; re-check the wrapper before assuming it, not the other way round.)
 
 ### Per-record resume cursor — checkpoint after EACH record, not window-end (LIVE 2026-09-02)
 
@@ -514,6 +519,30 @@ stage 5: 289135 was closed at **10:50** and the cursor had already passed **15:2
 WARNING: **`NETSUITE_LAST_SYNC_CURSOR_ITEM_RECEIPTS` on NYCHH is stale at 2024-08-06**, so re-enabling
 that feed replays roughly **two years** of receipts. Rewind it forward *before* flipping the toggle.
 
+#### Full resync recipe — and the 10-day ceiling that makes it a loop (2026-09-15)
+
+Rewinding to backfill a newly-stamped field (assetType, itemClass, a `c_` field) is the same
+mechanic, but at depth three details decide whether it works. The six keys, all in the **client**
+database's `Parameters` table:
+
+`NETSUITE_LAST_SYNC_CURSOR_` + `SALES_ORDERS` · `PURCHASE_ORDERS` · `INVOICES` · `ITEM_RECEIPTS` ·
+`ITEM_FULFILLMENTS` · `INVENTORY_ADJUSTMENTS`.
+
+1. **The id half must be `0` on a rewind.** The value is `<datetime>|<netsuiteInternalId>` and it is a
+   *seek* key — a non-zero id makes the run skip every record at that same datetime whose internal id
+   sorts below it. Always write `'2026-01-01 00:00:00|0'`, never carry the old id back.
+2. **The datetime is on the Eastern clock** (`America/New_York`), not UTC and not the server's. See
+   the wrong-clock bugs above — this is the same clock they settled on.
+3. **Reset the paired execution-mode key at the same time.** `NETSUITE_EXECUTION_MODE_<SECTION>`
+   holds `<seconds>-<STATE>`; a prior crash leaves it `RUNNING`, and the next run then **shrinks**
+   the window ÷3 instead of using the full cap. Observed live 2026-09-15: Elite's
+   `NETSUITE_EXECUTION_MODE_SALES_ORDERS` was stuck at `864000-RUNNING`. Set it to
+   `<the client's own cap>-IDLE` — see the manual-reset section above for both halves.
+4. **One run only advances `MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS`** — 864000s (10 days) by
+   default, and **Elite does not override this one**. So a rewind to 1 Jan 2026 needs **~26 runs** to
+   catch up. On the 5-minute cron that is fine; on a daily cron it would take ~26 days. **Run the
+   wrapper by hand in a loop** rather than waiting for the schedule.
+
 ### Sections are NOT order-dependent — one cursor can be rewound alone
 
 Each section's `startModeIteration()` reads only **its own** `Parameters` key, and the PO section
@@ -1624,6 +1653,15 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
   [NetSuite Sync Alert Monitor](../../library/features/netsuite-sync-alert-monitor.md).
 
 ## Change history
+- 2026-09-15 — Added the **full resync recipe** for a deep cursor rewind (the procedure for
+  backfilling a newly-stamped item field): the six `NETSUITE_LAST_SYNC_CURSOR_<SECTION>` keys live in
+  the **client** DB, the id half **must be `0`** or the seek skips records at the same datetime, the
+  datetime is on the **Eastern** clock, and the paired `NETSUITE_EXECUTION_MODE_<SECTION>` must be
+  reset to `<cap>-IDLE` in the same pass — Elite's `..._SALES_ORDERS` was found stuck at
+  `864000-RUNNING`, which shrinks the next window ÷3. Recorded the **10-day ceiling per run** (Elite
+  does *not* override this one), so a rewind to Jan 2026 needs ~26 runs and should be looped by hand
+  rather than left to the schedule. Found auditing the itemClass/fulfillmentType deploy — see
+  [NetSuite item-class sync](../../library/features/netsuite-item-class-sync.md). (rgirish)
 
 - 2026-09-15 — **Compass SALES_ORDERS unfrozen: a Compass-gated prune runs BEFORE the renumber.**
   `syncSalesOrderFromNetsuite` was throwing *"unresolvable NetSuite<->DB lineNumber conflict"*

package/knowledge/2.0/apps/_underscore/features/item-classification-itemclasses.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-11
+updated: 2026-09-15
 owners: ["rgirish"]
 files:
   - _underscore/Model/Client/ItemClass.php
@@ -18,6 +18,7 @@ related:
   - ./record-change-audit-log.md
   - ../../../../clients/prudential/features/itemclasses-device-tier-data.md
   - ../../dbchanges2/workflows/client-schema-drift-audit.md
+  - ../../../../1.0/apps/library/features/netsuite-item-class-sync.md
 ---
 
 ## Summary
@@ -78,7 +79,13 @@ LIMIT 1
 That cron is **disabled** — see the
 [Prudential ItemClasses data doc](../../../../clients/prudential/features/itemclasses-device-tier-data.md).
 
-**Nothing writes `itemClassId`.** No writer exists in `api2`, `worker2`, or `_underscore`.
+**~~Nothing writes `itemClassId`.~~ There is now ONE writer (2026-09-15).** The audit below was
+correct on 2026-09-11; four days later the 1.0 NetSuite importer became the first writer —
+`App_Api_Toga2::getCreateItemClass()` creates `ItemClasses` rows from the NetSuite classification
+tree and stamps `Items.itemClassId`. It is **opt-in per client and only Elite has it on**, so the
+"0 rows for 34 clients" picture below still holds everywhere else. See
+[NetSuite item-class sync](../../../../1.0/apps/library/features/netsuite-item-class-sync.md).
+No writer exists in `api2`, `worker2`, or `_underscore`.
 
 ### Frontend: one real reference, and a grep trap
 
@@ -101,9 +108,12 @@ Queried live via SuiteQL (2026-09-11): **311 classifications**, columns
 
 ## Gotchas
 
-- **⚠ `ItemClasses.name` has a UNIQUE index (index literally named `name`).** NetSuite
-  classification names repeat, so **any attempt to load NetSuite classes into this table fails
-  until that UNIQUE is dropped.** This is the first blocker on any NetSuite-classification work.
+- **~~⚠ `ItemClasses.name` has a UNIQUE index~~ — DROPPED 2026-09-11.** It was the first blocker on
+  NetSuite-classification work exactly as predicted here; `_modules/netsuite/2026-09-11a -
+  ItemClassesNetsuiteHierarchy.sql` drops it and adds a UNIQUE on the new
+  `c_netsuiteInternalClassId` instead, so matching is by NetSuite internal id and repeated leaf
+  names ("Shipping" x3) are fine. That migration also adds the self-referencing
+  `parentItemClassId` FK for the tree.
 - **A hierarchy path column must be `TEXT`, not `varchar(512)`.** NetSuite `fullname` values are
   long, and the 2.0 standard caps varchar at 255.
 - **The table is already `utf8mb4_0900_ai_ci`**, so new columns need no explicit `COLLATE`.
@@ -117,6 +127,13 @@ Queried live via SuiteQL (2026-09-11): **311 classifications**, columns
   would break Northwell's 245 tagged items, which hold ServiceNow service categories.
 
 ## Change history
+- 2026-09-15 — **Two facts from this audit are now superseded by the shipped NetSuite item-class
+  sync.** (1) "Nothing writes `itemClassId`" — `App_Api_Toga2::getCreateItemClass()` is now the
+  first writer, opt-in per client, Elite only. (2) The `ItemClasses.name` UNIQUE index — called out
+  here as the first blocker — was **dropped** by `_modules/netsuite/2026-09-11a`, which also added
+  `parentItemClassId` (self-FK) and a UNIQUE `c_netsuiteInternalClassId`. The Northwell (27 rows)
+  and Prudential (7 rows) warning is unaffected and still governs any reuse of this table.
+  (rgirish)
 - 2026-09-11 — Documented from a full usage audit of `ItemClasses` across every TOGA codebase and
   all 36 prod client schemas: the table ships blank to all clients but **only Northwell (27 rows,
   ServiceNow service categories) and Prudential (7 rows, Dell device tiers) have data**, for two

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-08
+updated: 2026-09-15
 owners: ["bala", "mhammontree", "tcox", "apeterson", "rgirish"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -234,6 +234,16 @@ production `Core.RecordFields` for `Items`:
 |---|---|---|---|
 | **107** | `Items.manufacturerId` | `MATCH_UPSERT` | **creates** the manufacturer — get-or-create by name works |
 | **269** | `Items.assetTypeId` | `MATCH` | **fails the entire item write** |
+| **914** | `Items.catalogId` | `MATCH` | **matches** the existing catalog — and can never create one |
+
+Row 914 is the benign shape of `MATCH`, and it is worth knowing why it is benign: the match set is
+built from **`isIdentifier`**, and the `catalogs` record carries `isIdentifier = 1` on **`id`,
+`uuid` AND `name`** (verified on production `Core.RecordFields`, 2026-09-15). So
+`catalog: {name: 'Compass'}` resolves to the existing `Catalogs` row by name and **cannot mint a
+new catalog** — which is what makes a name-keyed catalog safe to seed as a per-tenant default
+(see [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md)). The identifier set
+is per-record data, not a code constant: check `isIdentifier` before assuming a business key is
+matchable.
 
 The 1.0 NetSuite importer's `getCreateItem()` contains **both** calls. `getCreateManufacturer()`
 sends `manufacturer: {name}` and has always worked; copying that shape for `assetType: {name}`
@@ -442,6 +452,11 @@ only one tenant's copy has the wrong flag.
 
 ## Change history
 
+- 2026-09-15 — Added **`Items.catalogId` (recordFieldId 914, `MATCH`)** to the childPolicy table as
+  the *benign* `MATCH` case, and recorded why: the `catalogs` record has `isIdentifier = 1` on
+  **`id`, `uuid` and `name`** (prod `Core.RecordFields`), so `catalog: {name: '<catalog>'}` always
+  links the existing row and can never create a catalog. That is what lets a tenant ship a
+  name-keyed catalog as an item-create default. (bala)
 - 2026-09-08 — ⚠ Recorded the **third EV-12 flavor: the field is declared in PHP but
   `isIdentifier = 0` in the tenant's `CustomRecordFields`.** `V2.php` (~L7471-7530) builds
   `$recordIdentifiers` purely from DB metadata (`Core.RecordFields` + `Client_<X>.CustomRecordFields`

package/knowledge/2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md

@@ -6,13 +6,14 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-09-09
-owners: [bala, kyalamarthi, apeterson, ajean, jcardinal]
+updated: 2026-09-15
+owners: [bala, kyalamarthi, apeterson, ajean, jcardinal, rgirish]
 files:
   - 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
   - dbchanges2/Core/2026-09-08e - Insert QcBatch CronJob.sql
+  - dbchanges2/_modules/netsuite/2026-09-11c - ItemClassRecordPermission.sql
 related:
   - ../architecture.md
   - ../../worker2/features/netsuite-salesorder-open-orders-sync.md
@@ -284,6 +285,20 @@ concluding a migration is production-safe.
 
 ## Gotchas
 
+- **⚠ An unguarded ACL grant migration duplicates silently — `AclRecordPermissions` has no unique key
+  that stops it (found in prod 2026-09-15).** `_modules/netsuite/2026-09-11c - ItemClassRecordPermission.sql`
+  is a plain `INSERT … VALUES` for `(recordId 105, roleId 3)` with **no `NOT EXISTS` guard**. Every
+  client checked in production carries **three** identical rows (Elite: ids 346, 347, 348), and its
+  paired `AclLogicGroups` insert uses `LIMIT 1` with no guard either — so Elite ended up with **3
+  logic groups on permission 346** and **zero** on 347/348. Nothing errored, and access is still
+  correct (every row grants the same thing), which is precisely why it went unnoticed across a whole
+  module rollout. Two rules this file breaks and the next one should not:
+    - Guard on the real identity, `NOT EXISTS (… WHERE recordId = 105 AND roleId = 3)` — the
+      declared unique key is `(appId, recordId, roleId, indirectRecordId)`, and `appId`/
+      `indirectRecordId` being NULL means MySQL does **not** enforce it.
+    - It uses `UUID()`, which the team standard forbids everywhere (see the UUID4 section above).
+  Cleanup is safe but must keep **one** permission row *and* its logic group together — delete the
+  childless duplicates (347, 348), not the one that owns the group.
 - **A "re-run safe" file is usually only re-run safe *per phase*.** If Phase 1 creates the parent row
   with no `NOT EXISTS` guard, re-running the *whole file* creates a **second parent** and then hangs
   a full set of children off it. Re-run safety of the child phases does not make the file idempotent.
@@ -318,6 +333,12 @@ concluding a migration is production-safe.
   [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
 ## Change history
+- 2026-09-15 — Added a worked production example of the unguarded-insert trap on an **ACL grant**
+  migration: `_modules/netsuite/2026-09-11c` inserts `AclRecordPermissions (105, 3)` with no
+  `NOT EXISTS` guard, so every client now has **three** duplicate rows (Elite 346/347/348) and a
+  lopsided `AclLogicGroups` fan-out (3 groups on 346, none on 347/348). The declared unique key
+  `(appId, recordId, roleId, indirectRecordId)` does **not** protect it because `appId` and
+  `indirectRecordId` are NULL. Also flagged the file's use of `UUID()`. (rgirish)
 - 2026-09-09 — Added the rule that **every hardcoded uuid literal must be generated independently at
   random** — never bump a digit / copy-and-tweak / pattern them (guessable, defeats uniqueness); the
   fan-out same-literal reuse is the one intended exception. Restated **never `UUID()`, single-row or

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

@@ -6,9 +6,12 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-09-04
-owners: [jcardinal, apeterson, tcox]
+updated: 2026-09-15
+owners: [jcardinal, apeterson, tcox, bala]
 files:
+  - dbchanges2/Core/2026-09-15a - ItemCreateDefaultsSurfaceSeed.sql
+  - dbchanges2/Client_Compass/2026-09-15a - ItemCreateCatalogDefault.sql
+  - dbchanges2/Client_CompassCanada/2026-09-15a - ItemCreateCatalogDefault.sql
   - dbchanges2/Client_Compass/2026-09-04a - ItemRecordRestrictToPersonaVisible.sql
   - dbchanges2/Client_CompassCanada/2026-09-04a - ItemRecordRestrictToPersonaVisible.sql
   - dbchanges2/Core/2026-09-02a - TalosAssistantSurfaceSeed.sql
@@ -1372,7 +1375,100 @@ environment and take the **highest** `MAX(id)+1`, never the one in front of you,
 `Core.SurfaceElements.id` = **233**, next `Core.Messages.id` = **299**. Both consuming files were
 still unrun at the time, so this is a reservation, not a deployed state.
 
+## A marker element can carry per-tenant WRITE defaults, not just visibility (`item-record-create-defaults`, Core 61, 2026-09-15)
+
+The marker-element pattern (a hidden element whose `config` is the payload) had so far only carried
+**visibility / mode** flags. `Core/2026-09-15a - ItemCreateDefaultsSurfaceSeed.sql` uses it to carry
+**default field VALUES for a create form**: surface **`item-record-create-defaults`** (type
+`SECTION`, `config.cardType = 'createDefaults'`) with one element, `isVisible = 0`, whose config is
+
+```json
+{"role":"createDefaults","values":{}}
+```
+
+Core seeds `values` **empty** — the true-neutral default — and each tenant opts in with a single
+`SurfaceOverrides` **`CONFIG`** row. The consuming app spreads `values` into its `POST` body before
+the form fields, so a default never beats real user input. FE side:
+[surface-frontend](../../toga25-supply/features/surface-frontend.md). This shipped to fix items
+created in toga25-supply being written with `Items.catalogId = NULL` (28 rows in prod
+`Client_Compass`, 6 in `Client_CompassCanada`).
+
+**Why `name` and not `uuid` in the seeded value.** `Items.catalogId` is `Core.RecordFields` **914**
+with `childPolicy = MATCH`, and the `catalogs` record has `isIdentifier = 1` on `id`, `uuid` **and**
+`name` — so a name matches the existing row and **can never create a catalog**
+([nested-relationship writes](../../api2/features/nested-relationship-writes.md)). A name also keeps
+the seed readable and tenant-portable, where a uuid would not be.
+
+**The two tenants spell the catalog differently, and the seeds use the STORED spelling:**
+
+| Tenant | Seeded value | `Catalogs` reality |
+|---|---|---|
+| `Client_Compass` | `{"catalog":{"name":"Compass"}}` | id 1 **`Compass`** (also id 2 `Agilant`, id 3 `Office Depot`) |
+| `Client_CompassCanada` | `{"catalog":{"name":"compass"}}` | id 1 **`compass`** — the only row |
+
+Both `name` columns are case-insensitive (`utf8mb4_unicode_ci` on Compass,
+`utf8mb4_0900_ai_ci` on Canada), so either spelling would in fact match; matching the stored
+spelling is a readability rule, not a correctness one. Catalog background:
+[Compass item catalogs](../../../clients/compass-usa/features/item-catalogs-and-duplicate-items.md).
+
+### Both client files restate `role` — the CONFIG-replaces-wholesale rule, hit again
+
+A `CONFIG` override **replaces the element's config object entirely** (`Surface.php:839`, see
+[the load-bearing rule](#-a-config-override-replaces-config-wholesale--this-is-the-load-bearing-rule-of-the-whole-design)),
+so each client row must ship **`role` AND `values`**:
+
+```json
+{"role":"createDefaults","values":{"catalog":{"name":"Compass"}}}
+```
+
+Send only `values` and the element loses its `role`, the adapter stops finding the marker, and the
+default silently disappears with no error anywhere. This is now the **second** feature to hit it
+(after the Talos suggestion chips) — treat "restate every key the FE matches on" as the default
+authoring step for any CONFIG override, not a special case.
+
+### The client files hardcode the Core ids — and the 2026-07-20d precedent is NOT copyable
+
+`Client_Compass/2026-09-15a` and `Client_CompassCanada/2026-09-15a` inline the Core `surfaceId` /
+`surfaceElementId` read from Core **after** the Core file was run, and guard re-runs with
+`SELECT … FROM DUAL WHERE NOT EXISTS (…)` against the **client table only** — no `Core.*` read at
+all.
+
+**Confirmed again by a real failure this session:** querying `Client_Compass` with a join to `Core`
+returns `OperationalError (1049, "Unknown database 'Core'")` on the `prod-client` cluster. The
+nearest existing example, `Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql`, resolves
+its element id with `FROM Core.SurfaceElements JOIN Core.Surfaces` — **do not copy it.** It is one of
+the ~51 stale cross-cluster files described above; it landed in prod by hand transposition, not by
+running as written.
+
+### Ids consumed — and beta must be RE-READ, not reused
+
+`Surfaces`/`SurfaceElements` ids differ sharply per environment: before this work prod Core was at
+`Surfaces` **60** / `SurfaceElements` **233**, while dev-sandbox (beta) was at **23** / **65**. The
+developer ran the Core file **on PROD**, taking **surface 61** and **element 234**, and the two
+client files hardcode those prod ids.
+
+> ⚠ **Beta has not had the Core file run.** Running the client files on beta as written would point
+> the overrides at ids that mean something else (or nothing) there. Re-read the beta ids after
+> running the Core file and swap them in before running the client files.
+
+**Handoff published (verify before your own run):** next prod `Core.Surfaces.id` = **62**, next prod
+`Core.SurfaceElements.id` = **235**.
+
 ## Change history
+- 2026-09-15 — Added the **`item-record-create-defaults`** seed trio (`Core/2026-09-15a` +
+  `Client_Compass` / `Client_CompassCanada` `2026-09-15a - ItemCreateCatalogDefault.sql`), which
+  extends the marker-element pattern from visibility flags to **per-tenant create-form default
+  VALUES** (`config {"role":"createDefaults","values":{}}`, Core seeds `values` empty, each tenant
+  overrides). Shipped to stop toga25-supply writing `Items.catalogId = NULL`. Recorded: the value is
+  seeded by catalog **name** because `RecordFields` 914 is `MATCH` over a record with
+  `isIdentifier` on `name` (so it can never mint a catalog); the two tenants store the name with
+  different case (`Compass` vs `compass`, both CI collations); both client files must restate
+  **`role`** because a CONFIG override replaces the config wholesale (second feature to hit that);
+  and the client files hardcode Core ids with a client-only `NOT EXISTS` guard — re-confirmed by a
+  live `1049 Unknown database 'Core'` on `prod-client`, which also makes the older
+  `2026-07-20d - ItemRecordVendorItemsEnable.sql` a NON-copyable precedent. Prod consumed
+  **Surface 61 / SurfaceElement 234** (beta is at 23 / 65 and has NOT run the Core file — re-read
+  its ids first); next prod ids = **62** / **235**. (bala)
 - 2026-09-04 — Added the **restrict-to-persona opt-in pair** (`Client_Compass/2026-09-04a` +
   `Client_CompassCanada/2026-09-04a - ItemRecordRestrictToPersonaVisible.sql`): client-wide
   `IS_VISIBLE`+`IS_ENABLED` overrides on `surfaceId` **19** / `surfaceElementId` **57**, literal Core

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

@@ -6,8 +6,8 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-04
-owners: [jcardinal, apeterson, tcox, rgirish]
+updated: 2026-09-15
+owners: [jcardinal, apeterson, tcox, rgirish, bala]
 files:
   - toga25-supply/src/layout/RecordApprovalModal/helpers/stackedCurrencyJoiner.ts
   - toga25-supply/src/layout/RecordApprovalModal/helpers/stackedCurrencyJoiner.test.ts
@@ -71,6 +71,7 @@ files:
   - 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/hooks/useItemCreateForm.tsx
   - toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts
   - toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx
   - toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx
@@ -402,6 +403,64 @@ a `computeValueKey`, grep the consuming view's registry for that literal string
 > makes the field visible and therefore **crashes the modal**; the FE alone changes nothing visible.
 > Same shape as the approvals-gate ship-together dependency.
 
+## Item CREATE defaults also come from Surface — and a missing default wrote NULL `catalogId` (2026-09-15)
+
+The item modal's **create** payload now takes its per-tenant defaults from the Surface layer instead
+of a client branch in code. This started as a data bug: `useItemCreateForm` built the `POST /items`
+body with **no catalog at all**, so every item created in this app was saved with
+`Items.catalogId = NULL`. The old `toga2-supply` `CreateItemModal.tsx` had always sent
+`catalog: { name: "Compass" }` — which is why only the 2.5 app produced NULL rows, and why nobody
+saw it in the older app. **Measured on prod 2026-09-15:** `Client_Compass.Items` held **28** rows
+with a NULL `catalogId` (newest 2026-09-14) against 1,509 on catalog 1, and
+`Client_CompassCanada.Items` **6** NULL against 221. A NULL-catalog item **never reaches the
+storefront** — see
+[Compass item catalogs](../../../clients/compass-usa/features/item-catalogs-and-duplicate-items.md).
+
+**How it works now** — the same marker-element shape as `item-record-vendor-items`, read by a new
+adapter:
+
+- New Core surface **`item-record-create-defaults`** (type `SECTION`, `surface.config.cardType =
+  'createDefaults'`) carrying **one non-rendered marker element** with
+  `config = {"role":"createDefaults","values":{}}` and `isVisible = 0`.
+- The slug was added to **`ITEM_RECORD_SURFACE_SLUGS`**, so it rides the group fetch the record
+  modal already makes — no new request.
+- **`surfaceBundleToItemCreateDefaults()`** (`helpers/surfaceBundleToItemFields.ts`, exported via
+  `helpers/index.ts`) finds the marker by `config.role === 'createDefaults'` and returns its
+  `config.values` object.
+- `useItemCreateForm` **spreads the defaults FIRST** into the `POST /items` body, so a real form
+  field always wins over a default. Order is the whole contract here.
+- A tenant opts in with one `SurfaceOverrides` CONFIG row. Compass seeds
+  `{"catalog":{"name":"Compass"}}`; Compass Canada seeds `{"catalog":{"name":"compass"}}` — the
+  spelling differs per tenant, see
+  [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md).
+
+**Why this is the right seam:** a tenant default is presentation/tenant config, so it belongs in the
+surface layer, not in a hostname or client-slug switch in the create form. Adding the next default
+(vendor, inventory type, anything) is now a `values` key plus a seed row — zero FE change.
+
+### Adding a slug to a group fetch is SAFE on unseeded clients and environments
+
+`_buildBundle` returns `{ surface: null, elements: [] }` when `$surface->load()` fails, so a slug
+that has not been seeded in a tenant (or a whole environment where the Core file has not run) simply
+resolves to an empty bundle. The adapter then returns `{}` and the create payload is byte-identical
+to before. Verified against `Model/Core/Surface.php` — see
+[surface-resolver](../../_underscore/features/surface-resolver.md). **So the FE can ship before the
+SQL runs anywhere** — the reverse of the restrict-to-persona deploy-order rule above, because this
+element renders nothing.
+
+### Sending `catalog` by NAME does not trip the Compass POST interceptor
+
+`_Model_Compass_Item::postPost` throws *"Could not load catalog uuid"* when it receives a catalog
+with no uuid, which looks like a reason to send a uuid instead of a name. It is not. api2 invokes the
+POST payload interceptor with **`$outData` — the created record, not the submitted body**
+(`V2.php:6019`), and the created record always carries the resolved catalog uuid. Compass has an
+active POST/POST interceptor on `recordId 21` (Items); Compass Canada has one too, but there is no
+`_Model_CompassCanada_Item`, so it falls back to `_Model_Client_Item::postPost`, which returns early
+unless `isFulfillable` was sent. Background:
+[API payload interceptors](../../api2/features/api-payload-interceptors.md). The name→row match
+itself is safe because `Items.catalogId` is a `MATCH` field over a record whose `name` is an
+identifier — [nested-relationship writes](../../api2/features/nested-relationship-writes.md).
+
 ## SalesOrders approval-decision modal (approve + deny) — migrated via an OVERLAY adapter seam
 
 The SalesOrder approve/deny decision modal's config now sources its display fields from Surface,
@@ -1100,6 +1159,17 @@ claim is about the `navigation-*` **flags** being inert — still true — not a
 unused).
 
 ## Change history
+- 2026-09-15 — **Item create defaults moved to the Surface layer, fixing NULL `catalogId` on every
+  item created in this app.** `useItemCreateForm` sent no catalog at all (prod: 28 NULL-catalog rows
+  in `Client_Compass`, 6 in `Client_CompassCanada`; the older `toga2-supply` modal had always sent
+  `catalog: {name:"Compass"}`), and a NULL-catalog item never reaches the storefront. New Core
+  surface `item-record-create-defaults` carries a hidden `config.role='createDefaults'` marker whose
+  `config.values` each tenant overrides; the slug rides the existing `ITEM_RECORD_SURFACE_SLUGS`
+  group fetch, `surfaceBundleToItemCreateDefaults()` adapts it, and the create form spreads it
+  **first** so form fields still win. Recorded two rules that make this cheap: an unseeded slug
+  resolves to an empty bundle (so FE can ship before the SQL, unlike the restrict-to-persona case),
+  and sending `catalog` by **name** cannot trip `_Model_Compass_Item::postPost` because api2 hands a
+  POST interceptor the created record, not the request body. (bala)
 - 2026-09-04 — Fixed the item modal's **More Info → "Restrict to Persona"** field missing in VIEW for
   Compass USA + Canada. Two causes, both now rules here: (1) the item modal's VIEW is Surface-driven
   while EDIT is still JSON, so a Core-default-OFF element with no client `SurfaceOverride` vanishes

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)_ — 25 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 26 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 35 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/compass-canada/profile.md

@@ -17,7 +17,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-09-10
+updated: 2026-09-15
 owners: [jcardinal, bala, tcox, apeterson, ajean]
 files: []
 related:
@@ -61,6 +61,13 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   resolution + client constants that all 8 Canada crons depend on. `library` is in `apps` for that
   reason.
 
+- **Catalogs: one row, lowercase.** `Client_CompassCanada.Catalogs` holds a **single** row, id 1
+  name **`compass`** (lowercase) — not the `Compass` / `Agilant` / `Office Depot` trio Compass USA
+  has ([item catalogs](../compass-usa/features/item-catalogs-and-duplicate-items.md)). The column
+  collation is case-insensitive, but write the stored spelling when seeding a value that references
+  it by name. Items created in `toga25-supply` were saved with a NULL `catalogId` until 2026-09-15
+  (6 rows here); the fix seeds the catalog as a Surface create-default per tenant.
+
 ## Vendors & integrations
 - **Grand & Toy (G&T)** — primary hardware vendor. SOs flow toga → MITS → PO to G&T; G&T sends
   back ASNs. ASN ingestion (email CSV + the auto-created ItemFulfillment chain + bilingual

package/knowledge/clients/compass-usa/features/item-catalogs-and-duplicate-items.md

@@ -6,7 +6,7 @@ project: Library
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-09-02
+updated: 2026-09-15
 owners: ["bala", "jcardinal"]
 files:
   - library/app/api/toga2.php
@@ -214,6 +214,15 @@ children" rule:
 - **⚠ A NULL `catalogId` is a real state** (27 items in prod, 22 ODP `VendorItems` point at such
   items). Anything joining through `Catalogs` **drops those rows silently** — an inner join to
   `Catalogs` is itself a filter.
+  **Where the newest NULL rows came from is now known, and it is fixed (2026-09-15):** the
+  `toga25-supply` item **create** form posted no catalog at all, so every item created in the 2.5 app
+  was born with `catalogId = NULL` — **28** such rows in `Client_Compass` (newest 2026-09-14) and
+  **6** in `Client_CompassCanada`, against 1,509 / 221 on catalog 1. A NULL-catalog item never
+  reaches the storefront. The create form now takes `catalog: {name: 'Compass'}` from a seeded
+  Surface default instead of hardcoding it (the older `toga2-supply` modal always sent it, which is
+  why the NULL rows are all from the new app) — see
+  [surface-frontend](../../../2.0/apps/toga25-supply/features/surface-frontend.md). The existing NULL
+  rows still need a data repair; the leak is closed, the backlog is not.
 - **⚠ `BundleItems.itemId` is a silent catalog-resolution consumer — the storefront never
   re-catalogs it.** The `toga2-commerce` storefront relays whatever item `GET /v2/bundles/{uuid}`
   returns; its `catalogId = 1` filter guards standalone item search only, never bundles. So a kit
@@ -241,6 +250,11 @@ children" rule:
   [catalog-fold reversal](../workflows/catalog-fold-reversal.md).
 
 ## Change history
+- 2026-09-15 — Identified the **source of the newest NULL-`catalogId` items**: the `toga25-supply`
+  create form sent no catalog, so every item created in the 2.5 app was born catalog-less (**28** rows
+  in `Client_Compass`, newest 2026-09-14; **6** in `Client_CompassCanada`), and such an item never
+  reaches the storefront. The leak is closed — the create payload now takes its catalog from a seeded
+  Surface default — but the existing NULL rows are still unrepaired. (bala)
 - 2026-09-02 — **Narrowed the same-day uniqueness resolution below.** `Client_Compass.Items` holds
   `MD7F4LL/A-S` **twice** — id 2760 (`title` set, `isActive = 0`, the row all referencing bundles
   use) and id 2784 (`title` NULL, `isActive = 1`, unused) — a pair from outside the fold population, so

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-08
+updated: 2026-09-15
 owners: ["snaredla", "jcardinal", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/sync_togasupply_elite.php
@@ -27,6 +27,7 @@ files:
 related:
   - ../profile.md
   - ../../../1.0/apps/library/features/netsuite-item-assettype-sync.md
+  - ../../../1.0/apps/library/features/netsuite-item-class-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
@@ -119,10 +120,11 @@ migration file.
 
 ### Elite-only wrapper deviations
 
-- **`MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS = 2592000` (30 days)**, vs. the 5-day default the
-  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.**
+- **~~`MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS = 2592000` (30 days)~~ — REMOVED, and the
+  backfill it existed for is done (verified 2026-09-15).** Elite's wrapper no longer overrides the
+  cap, so it now inherits the shared **864000 (10 days)**. Keep this in mind before planning a
+  rewind: one Elite run advances 10 days, not 30. (The engine still `define()`s rather than
+  `const`s the cap, so an override remains possible if another deep backfill is ever needed.)
 - **⚠ 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`
@@ -266,6 +268,37 @@ failure/in-progress flag (you want `IDLE`), and the cap is **864000** (10 days),
 takes many runs. **Only reset after the underlying error is fixed**, or it just fails and shrinks
 again.
 
+### Elite is also the ONLY client opted in to itemClass + line fulfillmentType (2026-09-15)
+
+Same shape as assetType above: two constants in Elite's wrapper, and nothing else turns them on.
+
+```php
+const IS_ENABLED_NETSUITE_LINE_FULFILLMENT_TYPE = true;   // :60
+const IS_ENABLED_NETSUITE_ITEM_CLASSIFICATIONS  = true;   // :65
+```
+
+Without them `toga2.php` omits the `fulfillmentType` and `itemClass` keys entirely, so **no other
+client can hit `EV-9` from this work.** Confirmed by grep across all 19 `sync_togasupply_*.php`
+launchers. Mechanics and the field-name trap live on the
+[NetSuite item-class sync doc](../../../1.0/apps/library/features/netsuite-item-class-sync.md).
+
+**Elite's ACL is fully provisioned — verified in production 2026-09-15.** All three layers are
+granted, so no further ACL work is owed for Elite:
+
+| Layer | Verified |
+|---|---|
+| `AclFieldPermissions` roleId 3 writable | RecordFields **601-605** + **2596** (605 = `Items.itemClassId`, 2596 = `ItemClasses.parentItemClassId`) and **2594/2595** (`SalesOrderItems`/`PurchaseOrderItems.fulfillmentType`) |
+| `AclRecordPermissions` roleId 3 | record **105** (Item classes) create/read/update = 1; `allowUpdate = 1` on records **21** (Items) and **18** (Purchase order items) |
+| `AclCustomFieldPermissions` | `c_netsuiteInternalClassId` (`CustomRecordFields` id 79, recordId 105) |
+| paired `AclLogicGroups` | present for the record-105 permission |
+
+Records **15, 18, 21, 105 are all `aclDatabase = CLIENT`**, so every one of these grants lives in
+`Client_Elite`, not `Core` — the usual place this goes wrong.
+
+**Elite has 3 duplicate `AclRecordPermissions` rows** for 105/roleId 3 (ids 346, 347, 348) and 3
+logic groups on id 346, from the unguarded `2026-09-11c` migration. Harmless, but see the
+[item-class doc](../../../1.0/apps/library/features/netsuite-item-class-sync.md) before cleaning.
+
 ## Gotchas / known issues
 
 - **⚠ OPEN, unrelated: `GET /v2/notes/{uuid}/files` returns 405 `EV-7`** ("method not allowed /
@@ -307,6 +340,17 @@ again.
 
 ## Change history
 
+- 2026-09-15 — **itemClass + line `fulfillmentType` are now on for Elite, and Elite alone.** Recorded
+  the two wrapper constants (`IS_ENABLED_NETSUITE_ITEM_CLASSIFICATIONS`,
+  `IS_ENABLED_NETSUITE_LINE_FULFILLMENT_TYPE`) that gate the whole feature — no other launcher
+  defines either, so no other client is exposed. **Verified all three ACL layers in production**
+  (fields 601-605/2596 + 2594/2595, record 105 create/read/update plus `allowUpdate` on records 21
+  and 18, and the `c_netsuiteInternalClassId` custom-field grant), all in `Client_Elite` because
+  records 15/18/21/105 are `aclDatabase = CLIENT`. Also noted Elite's 3 duplicate
+  `AclRecordPermissions` rows from the unguarded `2026-09-11c` migration. The feature itself was a
+  no-op until a field-name fix landed the same day — see
+  [NetSuite item-class sync](../../../1.0/apps/library/features/netsuite-item-class-sync.md).
+  (rgirish)
 - 2026-09-08 — **Elite sales-order sync was fully blocked for 4 days by a transfer-order 400 EV-12**,
   and the reported symptom ("transfer orders missing") hid the real blast radius: nothing after
   `2026-09-04 14:02:52` synced. Root cause was **metadata, not code** —

package/package.json

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