toga-ai 1.0.500 → 1.0.501

package/knowledge/2.0/apps/api2/features/api-payload-interceptors.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-08-03
-owners: ["mhammontree"]
+owners: ["mhammontree", "dfranks"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Client/ItemFulfillment.php
@@ -46,6 +46,42 @@ interceptor mechanism: the symptom looks exactly like a code bug.
 Because the registration is a **data** row, it is per-environment: the code ships with a deploy, the
 hook only becomes live when the migration lands.
 
+## Registration is also **per-API** — the scoping is DB config, not code
+
+The interceptor row carries an **`apiId`** (plus `isActive`) alongside `recordId`,
+`prePostProcessing` and `httpMethod`, and both a **`Core.ApiPayloadInterceptors`** and a
+**`Client_<X>.ApiPayloadInterceptors`** table are consulted. So a hook runs only for the APIs that
+have a row.
+
+**Consequence worth internalising: a guard you place in an interceptor is implicitly scoped to
+whichever APIs have interceptor rows, and that scoping lives in data, not in the PHP.** Reading
+the model tells you nothing about who it applies to, and **adding a row for another API silently
+widens the blast radius** of every check in that hook. Worked example: Compass `recordId 17`
+(`purchase-orders`) has exactly two rows, both `apiId = 2` (MITS Service Hub), identical in local
+and prod — so a validation added to `_Model_Compass_PurchaseOrder::prePost` cannot fire for the
+tenant's other APIs at all. See
+[Compass MITS PO → SO Item Linking](../../../clients/compass-usa/features/mits-po-to-so-item-linking.md).
+
+## The interceptor sees payload keys **verbatim** (no `c_` stripping, no rename)
+
+**Verified empirically** by a live HTTP probe against local dev
+(`test/@dave/Junk Drawer/probe_c_prefix_payload_mapping.php`):
+
+- `$payload` carries the keys **exactly as the client sent them**. Sending `mitsSalesOrder` yields
+  `$payload->mitsSalesOrder`; sending `c_mitsSalesOrder` yields `$payload->c_mitsSalesOrder`.
+  **Column mapping happens AFTER the interceptor runs.**
+- The rename in **`Client_<X>.Apis_CustomRecordFields.overrideFieldName`** governs only which
+  field names the API **accepts on input**. Without a rename row the renamed name is rejected with
+  *"a field specified in your request does not exist"*; the **raw model field name is always
+  accepted**. Rename rows are themselves `apiId`-scoped, so two APIs writing the same record can
+  legitimately use different names for one field.
+
+> **⚠ Do not re-derive this from the source.** Static reading of `api2/Component/Api/V2/V2.php`
+> around **L7384** — where `$modelVarsToSet` is cast to an object after a `$flippedRenamedFields`
+> flip — *looks* like the interceptor receives MODEL-level field names. It does not. The probe
+> result above is authoritative; the code path is misleading. Anyone tempted to reason it out
+> from V2.php will reach the wrong answer.
+
 ## Worked example — the EV-10 that was not a code bug
 
 `_Model_Client_ItemFulfillment::prePost()` defaults `itemFulfillmentStageId` to the shipped stage on
@@ -78,6 +114,13 @@ and the failing environment**. It is a small table, and the drift is usually exa
 
 ## Change history
 
+- 2026-08-03 — Added two verified behaviours from a live dev probe: (1) interceptor registration
+  is **per-API** (`apiId` on the row, in both the Core and `Client_<X>` tables), so a guard in a
+  hook is scoped by **DB config rather than code** and a new row widens its blast radius; (2) the
+  interceptor receives payload keys **verbatim** — no `c_` stripping, no rename — with
+  `Apis_CustomRecordFields.overrideFieldName` governing only which names the API *accepts* on
+  input, and column mapping happening after the hook. Flagged the misleading `V2.php` ~L7384
+  `$flippedRenamedFields` path that suggests the opposite. (dfranks)
 - 2026-08-03 — TRUE-80494: documented the mechanism after an `EV-10`
   (`itemFulfillmentStageId cannot be null`) in dev-sandbox turned out to be a **missing
   `ApiPayloadInterceptors` `(28, PRE, POST)` row**, not a code fault — `prePost` is dispatched only

package/knowledge/clients/compass-usa/features/mits-po-to-so-item-linking.md

@@ -31,35 +31,53 @@ production data-integrity bug.
 
 ## Who actually calls `POST /v2/purchase-orders` (MITS is NOT the only caller)
 
-`/v2/purchase-orders` for Compass is a **shared endpoint with two unrelated inbound channels**,
-distinguished in `Core.ClientApiIdentities` (clientId 2). **The channels are told apart by the
-FIELD NAME, not by whether a MITS SO is present at all:**
+`/v2/purchase-orders` for Compass is a **shared endpoint with two inbound callers**. Identify the
+caller from `Logs_<Client>.Api.apiId`, which is a FK to **`_Model_Client_Api` →
+`Client_<X>.Apis`** — *not* to `Core.ClientApiIdentities` (`_underscore/Model/Client/Logs/Api.php:17`
+declares `FIELDOPT_FOREIGNKEY_MODEL => '\_Model_Client_Api'`, and `_Model_Client_Api::TABLE =
+'Apis'`). `Client_Compass.Apis` is: **1 = Agilant** (internal), **2 = MITS Service Hub**,
+3 = Compass Group, 4 = Office Depot (Cxml).
 
-| Identity | Channel | SO field sent | Values | `purchaseOrderItems` |
+**The two callers are told apart by the FIELD NAME, not by whether a MITS SO is present at all:**
+
+| `apiId` | Caller | SO field sent | Values | `purchaseOrderItems` |
 |---|---|---|---|---|
-| `153531108` | MITS | **`mitsSalesOrder`** (unprefixed) | only `SA…` or `MR…` | always present |
-| `COMPASS-CXML` | cXML / EDI | **`c_mitsSalesOrder`** (`c_`-prefixed) | numeric, e.g. `472981379001` | present |
-| `COMPASS-CXML` | cXML / EDI | **neither field** | — | often **absent entirely** |
+| 2 | **MITS Service Hub** | **`mitsSalesOrder`** (unprefixed) | only `SA…` or `MR…` | always present |
+| 1 | **Agilant** (internal) | **`c_mitsSalesOrder`** (`c_`-prefixed) | numeric, e.g. `472981379001` | present |
+| 1 | **Agilant** (internal) | **neither field** | — | **absent entirely** |
 
 Measured over 60 days of inbound `POST /v2/purchase-orders` (`Logs_Compass.Api`):
-- **MITS — 4,547 posts, 100% carry the unprefixed `mitsSalesOrder`**; `SA` 2,928, `MR` 1,619.
-  Never `MA`, never any other prefix. **No `SA` value has ever been sent by a non-MITS caller.**
-- **COMPASS-CXML — 2,697 posts**: 2,455 carry `c_mitsSalesOrder`, and **242 carry neither field**.
-  In a 30-day slice: 1,508 `c_mitsSalesOrder` posts all had items; **136 posts had neither field
-  and no `purchaseOrderItems` key** — the legitimate header-first EDI POs.
-- Compass **Canada** posts under a **separate identity (`409531`)**, so never hardcode an
-  identity id.
+- **MITS (apiId 2) — 4,547 posts, 100% carry the unprefixed `mitsSalesOrder`**; `SA` 2,928,
+  `MR` 1,619. Never `MA`, never any other prefix. **No `SA` value has ever been sent by any other
+  api.**
+- **Agilant (apiId 1) — 2,697 posts**: 2,455 carry `c_mitsSalesOrder`, and **242 carry neither
+  field**. In a 30-day slice: 1,508 `c_mitsSalesOrder` posts all had items; **136 posts had
+  neither field and no `purchaseOrderItems` key**. What upstream process creates those item-less
+  header-first POs is **not established** — we know only which api posts them.
+- Compass **Canada** is a separate tenant with its own `Client_CompassCanada.Apis` ids — resolve
+  the caller per tenant; never hardcode one.
+
+**Why the two field names exist:** `Client_Compass.Apis_CustomRecordFields` holds exactly **one**
+row for `c_mitsSalesOrder` — recordId 17 → `overrideFieldName` `mitsSalesOrder`, scoped to
+**apiId 2 only**. So MITS is *permitted* to send the unprefixed name and every other api must use
+the raw model field name. `Client_CompassCanada` is configured identically. See
+[API Payload Interceptors](../../../2.0/apps/api2/features/api-payload-interceptors.md) for how
+per-api renames and interceptor scoping interact.
 
 **Consequences for any validation added to this endpoint:**
-- **The unprefixed `mitsSalesOrder` is the MITS marker** — not the identity id, and not the
+- **The unprefixed `mitsSalesOrder` is the MITS marker** — not an identity string, and not the
   `SA`/`MR` prefix. Supporting evidence: `prePost` reads `$payload->mitsSalesOrder`; the only
   `c_mitsSalesOrder` occurrence in the codebase is the model field declaration at
-  `_underscore/Model/Compass/PurchaseOrder.php:18`; and `Core.ApiPayloadInterceptors` has **no
-  rows for `recordId = 17`** (the `purchase-orders` record), so nothing rewrites field names in
-  flight.
+  `_underscore/Model/Compass/PurchaseOrder.php:18`; and an interceptor receives payload keys
+  **verbatim** — there is no `c_` stripping and no rename applied to `$payload` (verified by live
+  probe; see the interceptor doc).
+- **The interceptor itself is api-scoped by DB config.** `Client_Compass.ApiPayloadInterceptors`
+  has exactly two rows for recordId 17 (`purchase-orders`), **both `apiId = 2`**, identical in
+  local and prod. So `prePost`/`postPost` — and therefore any guard placed in them — **never
+  execute for apiId 1 at all**. Adding a row for another api silently widens the blast radius.
 - A "reject purchase orders with zero line items" rule keyed on the **unprefixed** field cannot
-  touch the 136 item-less EDI posts — they carry neither field. Gating on **item count alone**
-  would reject all of them.
+  touch the 136 item-less posts: they carry neither field *and* their api has no interceptor row.
+  Gating on **item count alone** at a shared layer would reject all of them.
 - **`MA` orders never arrive from MITS.** Compass creates them manually; they go to ODP, reach us
   over EDI, and land on an exception report for manual NetSuite entry. (An earlier belief that MA
   is a third MITS prefix to filter on is wrong.)
@@ -67,17 +85,16 @@ Measured over 60 days of inbound `POST /v2/purchase-orders` (`Logs_Compass.Api`)
 > **⚠ Querying trap — a substring match on `mitsSalesOrder` conflates the two callers**, because
 > `c_mitsSalesOrder` *contains* it. Anyone characterising this traffic from `Logs_Compass.Api`
 > must match the **exact key**; a pattern like `"mitsSalesOrder":"` also silently misses the
-> prefixed form, which is how this session first reached the wrong conclusion that cXML never
-> sends an SO reference. Second trap: payloads appear **both minified**
+> prefixed form, which is how this session first reached the wrong conclusion that the second
+> caller never sends an SO reference. Second trap: payloads appear **both minified**
 > (`"mitsSalesOrder":"MR…"`) **and pretty-printed** (`"mitsSalesOrder": "MR…"`, space after the
-> colon), so a naive pattern under-counts a second way.
+> colon), so a naive pattern under-counts a second way. Third trap: `Logs_<Client>.Api.apiId`
+> resolves against **`Client_<X>.Apis`**, not `Core.ClientApiIdentities` — reading it in the wrong
+> id space mislabels every caller.
 
-> **OPEN / UNVERIFIED:** it is **not** confirmed whether the 2.0 framework strips the `c_` prefix
-> when populating `$payload` for an interceptor. If it does, cXML requests carrying
-> `c_mitsSalesOrder` would also enter a guard keyed on `$payload->mitsSalesOrder`. Harmless while
-> those posts all carry items, but a future item-less cXML post carrying `c_mitsSalesOrder` would
-> then be wrongly rejected. This **cannot be settled from logs** — it needs a dev-environment
-> check.
+> **RESOLVED (was open):** the framework does **not** strip the `c_` prefix when populating
+> `$payload` for an interceptor — keys arrive verbatim. A guard keyed on `$payload->mitsSalesOrder`
+> therefore cannot be entered by a request that sent `c_mitsSalesOrder`.
 
 ## How it works
 - **SA orders (normal):** each inbound PO item carries `createdFromSalesOrderItem.lineNumber`
@@ -207,6 +224,15 @@ USA and Canada share the parent handler unchanged.
   need item backfill from the sibling ODP SO first).
 
 ## Change history
+- 2026-08-03 — **Corrected the caller identification** recorded earlier the same day:
+  `Logs_<Client>.Api.apiId` is a FK to `Client_<X>.Apis`, **not** `Core.ClientApiIdentities`, so
+  the second caller is **Agilant (apiId 1, internal)** — not a cXML/EDI channel. Traffic counts
+  are unchanged; what creates the item-less header-first POs is **not** established. Added the
+  `Apis_CustomRecordFields` per-api rename (recordId 17 `c_mitsSalesOrder` → `mitsSalesOrder`,
+  apiId 2 only; Canada identical) as the reason two field names exist, and the fact that the
+  recordId-17 interceptor rows are **both apiId 2**, so a guard in `prePost` never runs for
+  apiId 1. **Resolved** the open `c_`-prefix question: payload keys reach an interceptor verbatim.
+  (dfranks)
 - 2026-08-03 — Documented that `/v2/purchase-orders` has **two** Compass inbound channels (MITS
   `153531108` vs `COMPASS-CXML`; Canada is a third identity `409531`), told apart by **field
   name**: unprefixed `mitsSalesOrder` = MITS, `c_mitsSalesOrder` = cXML, neither = the item-less

package/package.json

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