toga-ai 1.0.810 → 1.0.811

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.810",
+  "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",