toga-ai 1.0.809 → 1.0.811

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-14
+updated: 2026-09-15
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -1270,6 +1270,50 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
   Note `SalesOrderItems.lineNumber` is a **`smallint`**, so the parked base must stay within smallint
   range for the client's line counts (headroom 1000 is safe at observed volumes).
 
+- **⚠ A NetSuite-removed line that still holds an UPSTREAM customer-PO link blocked the renumber and
+  re-froze Compass SALES_ORDERS (fixed 2026-09-15, `library` only, Compass-gated).** Compass USA's
+  SALES_ORDERS was stuck at `1-RUNNING` (`Logs.Issue` 749, clientId 2) throwing *"unresolvable
+  NetSuite<->DB lineNumber conflict … reconcile the orphaned/undeletable row"* whenever a
+  NetSuite-removed line sat on a `lineNumber` a surviving line had to move onto. Root cause: the
+  **existing** stale-line prune (`toga2.php` ~L1582) runs **AFTER** the renumber **and** skips any
+  line carrying a PO link (it cannot delete a PO-linked line), so those removed-but-PO-linked lines
+  survived and occupied a needed target number — and the renumber threw first anyway.
+  - **Fix — a Compass-gated prune BEFORE the renumber** in `syncSalesOrderFromNetsuite`. For each SO
+    line whose `c_netsuiteLineUniqueKey` is **non-empty** and **absent** from the current NetSuite
+    line set (a line NetSuite removed) that was **never fulfilled and never invoiced**: delete its
+    Agilant-side SO↔PO **bridge LINK** rows in **both** directions (routes
+    `/purchase-order-item-sales-order-items/{uuid}` and `/sales-order-item-purchase-order-items/{uuid}`),
+    then DELETE the `SalesOrderItem` (`/sales-order-items/{uuid}`), then drop it from the in-memory
+    `$salesOrderItemsInToga`. It **NEVER** deletes/modifies the `PurchaseOrder`/`PurchaseOrderItem`
+    itself (the Compass **customer** order is off-limits) and never touches another order record.
+  - **Guardrails (owner decision 2026-09-15; cto AGREE; php-reviewer clean; cso SAFE TO SHIP):**
+    (a) non-empty key **absent from NetSuite** only — an empty key was never matched to NetSuite, so
+    treating it as "removed" is a false positive; (b) never a shipped/invoiced line (checked against
+    the fulfillment/invoice maps built ~L990-1032); (c) **Compass-gated** (`CLIENT_UUID_COMPASS`);
+    (d) **re-check that one line's fulfillment/invoice status immediately before the deletes** to
+    close a TOCTOU gap (the maps are a start-of-run snapshot); (e) the final `SalesOrderItem` DELETE
+    stays **throwing** (fail-loud) if any unhandled attachment remains — mirrors the PO-line cleanup
+    in `syncPurchaseOrderFromNetsuite` (~L2793-2806) and the mirror-NetSuite decision (2026-09-02).
+  - **Every FK child of `Client_Compass.SalesOrderItems` blocks a delete.** All are `NO ACTION` or
+    `RESTRICT`, and InnoDB treats `NO ACTION` as `RESTRICT`: `ItemFulfillmentItems`, `InvoiceItems`,
+    `PurchaseOrderItems_SalesOrderItems`, `SalesOrderItems_PurchaseOrderItems`,
+    `SalesOrderItems_CommittedUnits`, `SalesOrderItems_Tags`, `SalesOrderItems`
+    (`parentSalesOrderItemId` kit children), `SalesOrderItems_TransferOrderItems`,
+    `TransferOrderItems_SalesOrderItems`. This is why the prune must clear the bridge links first and
+    only ever touches never-fulfilled/never-invoiced lines.
+  - **Proven (evidence):** NetSuite sales order 271929 (internal id 6926956), customer "6096 ODP
+    Veyer (B2B)"; NetSuite reorganized it to 9 lines and removed 6 kitting lines (lineUniqueKeys
+    20024694/695/696/702/703/704) that never shipped and were never invoiced but each still held an
+    upstream customer-PO link — those 6 blocked the renumber.
+  - **⚠ OPEN, NOT FIXED — a DUPLICATE `SalesOrders` record on one NetSuite internal id.** `SalesOrders`
+    number **467435086001** shares NetSuite internal id **6926956** with order 271929 (two TOGa
+    records for one NetSuite sales order; 467435086001 has 12 keyless lines with downstream vendor-PO
+    links, none shipped). The main SO lookup in `syncSalesOrderFromNetsuite` (~L946-974) filters
+    Compass by `locationId 615286` / `customerId 3`, which currently narrows to 271929, so the prune
+    only ever touches 271929 — but **two records on one NetSuite id is an anomaly that could make the
+    lookup bind to the wrong record on other orders.** Needs its own ticket. Deploy: `library` only;
+    the worker redeploys to pick it up (worker clones library on deploy).
+
 - **⚠ Canon + Endeavor Health ITEM_RECEIPTS froze because `fetchPurchaseOrderById` never populated the
   PO vendor (deployed/verified 2026-08-29).** The PO shim's `->entity` was always null (its SuiteQL
   SELECT omitted `entity`, unlike `listPurchaseOrders`), so the fail-loud missing-entity guard in
@@ -1581,6 +1625,21 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
 
 ## Change history
 
+- 2026-09-15 — **Compass SALES_ORDERS unfrozen: a Compass-gated prune runs BEFORE the renumber.**
+  `syncSalesOrderFromNetsuite` was throwing *"unresolvable NetSuite<->DB lineNumber conflict"*
+  (`Logs.Issue` 749, clientId 2) because a NetSuite-removed line that still held an upstream
+  customer-PO link survived the existing stale-line prune (which runs after the renumber and skips
+  PO-linked lines) and occupied a `lineNumber` a surviving line needed. Added a prune BEFORE the
+  renumber that, for each never-fulfilled/never-invoiced line whose non-empty `c_netsuiteLineUniqueKey`
+  is absent from NetSuite, deletes its SO↔PO bridge links in both directions then the `SalesOrderItem`
+  — never touching the `PurchaseOrder`/`PurchaseOrderItem` (Compass customer order). Guardrails:
+  absent-from-NetSuite + non-empty key only, never shipped/invoiced, Compass-gated, immediate
+  TOCTOU re-check, final DELETE stays fail-loud. Recorded that every FK child of
+  `Client_Compass.SalesOrderItems` is `NO ACTION`/`RESTRICT` (all block a delete), and an OPEN
+  duplicate-`SalesOrders`-record anomaly (467435086001 shares NetSuite internal id 6926956 with
+  271929). Proven on NetSuite SO 271929 (6 removed kitting lines blocked the renumber). `library`
+  only, no SQL; worker redeploys to pick it up. cto AGREE; php-reviewer clean; cso SAFE TO SHIP.
+  (jcardinal)
 - 2026-09-13 — **ITEM_FULFILLMENTS unfrozen for NYCHH: five stacked fulfillment-reconcile bugs fixed
   (library, deployed + verified in prod).** (1) **Unit duplication from a truncated nested GET** — the
   existing-units dedup map was built from the nested `itemFulfillmentItemUnits` of one

package/knowledge/2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-26
-owners: [apeterson, bala]
+updated: 2026-09-15
+owners: [apeterson, bala, jcardinal]
 files:
   - _underscore/Model/Client/PurchaseOrders/SalesOrder.php
   - _underscore/Model/Client/SalesOrders/PurchaseOrder.php
@@ -40,6 +40,18 @@ one returns `200` with an empty array, which reads like a permission or data bug
 Read the name as **"`<source>`\_`<thing created from it>`"**. The *first* table name is the
 origin; the second is what was generated from it.
 
+**The line-item bridges follow the same rule (same name order, same directions):**
+
+| Table | Direction | Meaning | API route |
+|---|---|---|---|
+| `PurchaseOrderItems_SalesOrderItems` | **UPSTREAM** | an SO line created **FROM** a customer PO line | `purchase-order-item-sales-order-items` |
+| `SalesOrderItems_PurchaseOrderItems` | **DOWNSTREAM** | a vendor PO line created **FROM** an SO line | `sales-order-item-purchase-order-items` |
+
+The 1.0 Compass NetSuite sync deletes these **item-level** link rows in **both** directions when it
+prunes a NetSuite-removed SO line — see
+[NetSuite → TOGa Supply per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)
+(2026-09-15).
+
 ## How it works
 
 - Both `Records` rows are `aclDatabase = CLIENT`, `childPolicy = MATCH_UPSERT`, so both are
@@ -122,6 +134,11 @@ everywhere. Present is not populated.
   collapses many POs without multiplying rows.
 
 ## Change history
+- 2026-09-15 — Added the **line-item** bridge parallel: `PurchaseOrderItems_SalesOrderItems`
+  (upstream, route `purchase-order-item-sales-order-items`) and `SalesOrderItems_PurchaseOrderItems`
+  (downstream, route `sales-order-item-purchase-order-items`) follow the same name-order rule as the
+  header bridges. Confirmed while building the Compass 1.0 sync's pre-renumber prune, which deletes
+  both item-level link directions for a NetSuite-removed SO line. (jcardinal)
 - 2026-08-26 — Added the **write** side: the two directions are populated by two different
   pipelines (2.0 `_Trait_Netsuite_SalesOrder` writes **upstream** customer POs from `otherRefNum`;
   the 1.0 `syncPurchaseOrderFromNetsuite` cron writes **downstream** vendor POs), and the api2 child

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/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/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/package.json

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