toga-ai 1.0.492 → 1.0.494

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,13 +6,15 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-07-28
+updated: 2026-08-03
 owners: [jcardinal, mhammontree]
 files:
   - library/app/api/toga2.php
   - worker/crons/toga2/aig/sync_togasupply_aig.php
   - worker/crons/toga2/wje/sync_togasupply_wje.php
 related:
+  - ../../../2.0/apps/api2/features/nested-relationship-writes.md
+  - ../../../clients/aig/features/entitlement-intake.md
   - netsuite-suiteql-api-reference.md
   - netsuite-suiteql-rest-shim.md
   - ../../worker/features/netsuite-togasupply-per-client-sync.md
@@ -106,6 +108,80 @@ bool $enabled2to1, bool $enabled1to2)`. When `enabled2to1`:
 - The 1→2 direction (`enabled1to2`) is a stub (not yet implemented).
 - DB target is selected with `App_Model_Client::changeDbLinkToClientDatabase(getClientDatabaseNames()[$togaClientId])`.
 
+### TRUE-79401 payload shape — RESOLVED 2026-08-03 (nested; NO api2 work needed)
+
+**The multi-email payload shape is settled, and the 2026-07-28 library change is the COMPLETE
+implementation — zero api2/`_underscore` work is required.** (This supersedes the previous "open
+question, owner Paulina".) Sources: AIG's post-entitlements API field-mapping spreadsheet, the
+2026-05-01 Teams meeting, and the 2026-05-04 AIG email exchange.
+
+AIG's mapping document maps **both** `UserDefined3` (secondary email) **and** `UserDefined4` (third
+email) to the **same** nested collection — `Entitlements.contact.contactEmailAddresses[].emailAddress`.
+In the meeting the team looked up our own record/field names specifically to write them into that
+document ("it is called contact email addresses and the field is called email address").
+
+> **`UserDefined3` / `UserDefined4` are AIG's SOURCE-SIDE column labels only.** They are not, and
+> never were, fields to implement on our side. Verified: `UserDefined3` appears **nowhere** in
+> `api2` or `_underscore` — its only occurrences in the tree are a comment in
+> `library/app/api/toga2.php` and this doc.
+
+Correct inbound shape:
+
+```json
+"contact": {
+  "primaryContactEmailAddress": { "emailAddress": "primary@example.com" },
+  "contactEmailAddresses": [
+    { "emailAddress": "primary@example.com" },
+    { "emailAddress": "second@example.com" }
+  ]
+}
+```
+
+The primary **may** be repeated inside the collection — `syncContactToToga1Customer` de-dupes with
+`array_unique`.
+
+**Three distinct layers — only the last one is delimited.** Conflating them is the easy mistake:
+
+| Layer | Shape |
+|---|---|
+| 1. AIG → us (V2 payload) | nested `contactEmailAddresses[]` **array of objects** |
+| 2. `Client_Aig.ContactEmailAddresses` (2.0) | one **ROW** per address |
+| 3. `TOGA_AIG.Customers.emailAddress` (1.0) | a single `'; '`-joined **STRING** |
+
+The 2026-05-01 meeting's comma-vs-semicolon debate was entirely about **layer 3** (a legacy
+`varchar(255)` can only hold a string) and says nothing about the inbound payload.
+
+**Structural trap:** `contactEmailAddresses` is a **direct child collection**, so it is a **flat**
+array of objects — *not* the double-wrapped bridge-table form used by its siblings in the very same
+AIG payload (`entitlementEntitlementCoverageTypes: [{ entitlementCoverageType: {…} }]`). And a
+wrong shape does **not** error: V2 returns **201** and drops the data — see
+[api2 nested-relationship writes](../../../2.0/apps/api2/features/nested-relationship-writes.md).
+
+**Purpose is verification/lookup ONLY.** Settled 2026-05-01: "it's just for visual, this is for
+verification, it's a string." The use case is a support agent looking up a caller by **any** of
+their addresses after pulling the contract number. Multi-recipient notification (CC/BCC on TogaDesk
+tickets) was **explicitly rejected** — see the gotcha about the single-recipient registration email.
+
+### Open items (TRUE-79401)
+
+1. Confirm the library change is **merged and deployed to the prod worker** (git/deploy state not
+   verified as of 2026-08-03).
+2. **Beta verification of the nested write is outstanding.** Assert real
+   `Client_Aig.ContactEmailAddresses` **row counts** (never the HTTP status), covering **both** a
+   brand-new contact (CREATE) **and** a second entitlement for an **existing** contact (UPDATE).
+   The UPDATE path is the suspect one: the reverse back-reference injection at `V2.php:4985–4996`
+   breaks single-key forced-MATCH and explicitly names `primaryContactEmailAddress` as likely
+   affected (see the api2 doc, 2026-07-20).
+3. Give AIG's dev team a **concrete JSON example** (above), not just the
+   `contactEmailAddresses[].emailAddress` path expression, so they don't emit an array of bare
+   strings.
+4. Confirm with **Paulina** that the mapping document actually reached AIG. Risk: our 2026-05-04
+   email told AIG to send the email fields "only if they are necessary for the process" — ambiguous
+   phrasing, sent in the same breath as dropping Business Unit, which may have read as a de-scope.
+   No AIG reply. Meanwhile AIG won't enable the extra fields until we tell them the feature is live
+   → **both sides are waiting on each other.** The feature has been functionally complete since
+   2026-07-28 and is gated on **communication + verification, not development.**
+
 ### `syncWithTogadesk()` — 2.0 ⇄ 1.0 (TOGaDesk)
 
 A large bi-directional sync gated by **two checkpoint parameters** stored in 2.0 via
@@ -176,18 +252,51 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
   enough to hold several `'; '`-joined emails, so TRUE-79401 needed **no** schema/dbchanges migration
   (the earlier fear that it was ~VARCHAR(55) was wrong). `TOGA_AIG` is the 1.0 legacy DB;
   `Client_Aig` is the 2.0 prod tenant.
-- **The multi-email path is not yet exercised (open, TRUE-79401).** As of 2026-07-28 all 20
-  `Client_Aig.ContactEmailAddresses` rows are one-per-contact, and **no** api2/`_underscore` code
-  references `UserDefined3`/`UserDefined4` or creates `ContactEmailAddresses` rows. Whether an api2
-  intake mapping is still needed depends on how Staples / SA.com sends the extra emails: if they POST
-  nested `contactEmailAddresses` records to the V2 API the library change is complete; if they send
-  flat `UserDefined3`/`UserDefined4` fields expecting us to map them into email rows, an api2 intake
-  mapping must be built. Open question owned by **Paulina**.
+- **The multi-email path is not yet exercised in prod data (TRUE-79401)** — as of 2026-07-28 all 20
+  `Client_Aig.ContactEmailAddresses` rows are one-per-contact. The *payload-shape* question that
+  used to sit here is **RESOLVED** — see *TRUE-79401 payload shape* above. Verification (real row
+  counts on beta, CREATE **and** UPDATE paths) is the remaining open item.
+- **Do not "fix" the single-recipient registration email.**
+  `_Model_Aig_Entitlement::postPost` sends the Staples Protection Plan registration email to
+  `addTo($payload->contact->primaryContactEmailAddress->emailAddress)` only. That is **correct by
+  design**: TRUE-79401's scope is *verification/lookup*, and the team explicitly rejected
+  CC/BCC-ing every address onto TogaDesk tickets. Multi-recipient notification is out of scope.
+- **The dedupe `LIKE` is an equality match a stored list can no longer satisfy (latent).**
+  `syncContactToToga1Customer`'s fallback lookup is
+  `WHERE Customers.emailAddress LIKE '$primaryEmailAddress'` — **no wildcards**, so it is an
+  equality match. Now that the column can hold a `'; '`-joined list, a 1.0 row that already holds a
+  list will **not** match a primary-only lookup. Shielded in practice because dedupe is
+  authoritatively keyed on `c_togaCustomerId` first and a successful sync writes that id back to
+  2.0, dropping the contact out of the `c_togaCustomerId IS NULL` query forever. It only bites if
+  the **write-back fails after the insert succeeds** — a retry then inserts a **duplicate**
+  customer instead of matching. Hardening if it ever fires: `LIKE '%$primaryEmailAddress%'`. Note
+  this is a consequence of a deliberate deviation: the 2026-05-01 meeting said to drop the primary
+  email entirely, but the implementation retained a separately-escaped primary for this lookup (the
+  right call — dropping it would have broken legacy record matching outright).
+- **No `emailAddress2`/`emailAddress3` columns — deliberate.** The 2026-05-01 meeting explicitly
+  rejected adding extra email columns across the ~15 Toga Classic client DBs and chose the
+  delimited single field instead. That is **why TRUE-79401 has no `dbchanges` migration** — an
+  intentional decision, not an oversight. (The doc's earlier "fear that `Customers.emailAddress`
+  was ~VARCHAR(55)" traces to a garbled transcript line — "needs to fifty-five… maybe we should
+  change it to a long"; the column is `varchar(255)`. Closed.)
 - **PHP 7.2** target (prod worker/library) — no arrow functions, typed properties, `??=`, `match`.
   Lint with `C:\xampp7\php\php.exe -l`.
 
 ## Change history
 
+- 2026-08-03 — TRUE-79401 **payload shape RESOLVED** (review/no-code session; sources: AIG's
+  field-mapping spreadsheet, the 2026-05-01 Teams meeting, the 2026-05-04 AIG email). Both
+  `UserDefined3` and `UserDefined4` map to the **same** nested
+  `contact.contactEmailAddresses[].emailAddress` collection; `UserDefined3/4` are **AIG's
+  source-side labels only** and exist nowhere in `api2`/`_underscore` — so **no api2 intake mapping
+  is needed** and the 2026-07-28 library change is the complete implementation. Replaced the
+  "open question, owner Paulina" gotcha with the resolved shape + a concrete JSON example. Also
+  recorded: purpose is **verification/lookup only** (multi-recipient notification explicitly
+  rejected, so `postPost`'s single-recipient email is correct by design); the three-layer
+  payload/row/delimited-string distinction; the extra-email-columns rejection that explains the
+  absent `dbchanges` migration; and the latent wildcard-less dedupe `LIKE` vs. a stored list.
+  Remaining: deploy confirmation, beta row-count verification (CREATE **and** UPDATE), sending AIG
+  a concrete JSON example, and confirming the mapping doc reached AIG. (mhammontree)
 - 2026-07-28 — TRUE-79401: `syncContactToToga1Customer` now stores a contact's **full** email list in
   1.0 `TOGA_AIG.Customers.emailAddress` as a `CUSTOMER_EMAIL_DELIMITER` (`'; '`)-joined, deduped,
   escaped string (was primary-only) for AIG/Staples support lookup. Added

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-27
+updated: 2026-08-03
 owners: ["jcardinal", "mhammontree", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -214,6 +214,23 @@ read fresh per request) — no Apache restart needed. Concrete case: `TrackingNu
 threw EO-1 purely because `_underscore` was on a branch whose generated `TrackingNumber.php` lacked
 the field.
 
+### ⚠ Verify the mirror sibling's grants EXIST in the target DB — or the clone inserts nothing
+
+A "clone a sibling's grants" migration reads the **target database's own** `AclFieldPermissions`
+rows, so on a client where the sibling itself has no grants the `INSERT … SELECT` matches zero rows
+and **succeeds with 0 inserted and no error**. Always confirm the sibling has rows in that DB first.
+
+**Reference siblings that are safe to mirror** (verified present + complete per client):
+`shippingMethodId` (338), `measures.slug` (723), `containsBattery` (962), `shipToAddressId` (991).
+**Do NOT mirror `needsReturnLabel`** — its grants are absent in some clients.
+
+Reconfirmed 2026-08-03 (TRUE-80494): `measures.measureType` had **zero** grant rows in dev-sandbox
+`Client_Growrk`, so it was omitted from `GET /v2/measures`; the frontend's strict
+`m.measureType === "LENGTH"` split then produced empty arrays and **both unit dropdowns rendered
+empty with no error anywhere**. The same audit found `lengthMeasureId`/`weightMeasureId` granted to
+**role 3 only, not role 1** — grant fan-out is per-client and must be verified per client, not
+assumed from one.
+
 ## Checklist (so the chain is never half-built)
 
 - [ ] `AclRecordPermissions` row for the role × record with the right CRUD flags.
@@ -227,6 +244,14 @@ the field.
 
 ## Change history
 
+- **2026-08-03** — TRUE-80494: reconfirmed the **silent-omission** read rule in a second environment
+  (`measures.measureType` ungranted in dev-sandbox `Client_Growrk` → absent from `GET /v2/measures` →
+  empty unit dropdowns, no error) and added the **verify-the-mirror-sibling** rule: a clone migration
+  reads the target DB's own rows, so a sibling with no grants there inserts **zero rows without
+  erroring**. Listed safe reference siblings (`shippingMethodId` 338, `measures.slug` 723,
+  `containsBattery` 962, `shipToAddressId` 991) and flagged `needsReturnLabel` as unsafe to mirror.
+  Also noted `lengthMeasureId`/`weightMeasureId` were granted to role 3 but not role 1 — verify the
+  role set per client. (mhammontree)
 - **2026-07-22** — TRUE-79191: documented that the V2 GET **OUTPUT** field list is itself built from
   `AclFieldPermissions` (`getAclFieldPermissions` + the output `foreach` loops in
   `api2/.../V2.php`), so an **ungranted field is SILENTLY OMITTED** from the response (200, no

package/knowledge/2.0/apps/_underscore/features/carrier-shipping-labels.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-14
+updated: 2026-08-03
 owners: [mhammontree]
 files:
   - _underscore/Model/Client/ItemFulfillment.php
@@ -27,6 +27,8 @@ related:
   - ../architecture.md
   - recursive-item-fulfillments.md
   - ../../toga2-supply/features/fulfill-and-ship.md
+  - ../../api2/features/record-scripts.md
+  - ../../dbchanges2/workflows/nonprod-metadata-drift-repair.md
 ---
 
 ## Summary
@@ -168,6 +170,65 @@ outbound label:
   falls back to Signature Required (`2`).** None Specified is **omitted** (UPS default, no
   confirmation).
 
+## Reference numbers printed on the label (Reference 1 / Reference 2 — implemented 2026-07-31)
+
+Two user-entered reference values now reach the carrier and **print on the shipping label**. They
+are **transient**: not sourced from NetSuite, not persisted anywhere, no DB columns, no
+`RecordFields`, **zero `dbchanges2` work**. They ride as **query-string params on the existing
+carrier RecordScript calls** — see
+[Record Scripts → named-argument binding](../../api2/features/record-scripts.md), including the
+**mandatory backend-before-frontend deploy order** that pattern imposes.
+
+- `Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php` gained **`$referenceString2`**
+  (alongside the existing `$referenceString`).
+- `upsShipmentApi` / `fedexShipmentApi` (`Model/Client/ItemFulfillment.php`) gained optional
+  **`$reference1` / `$reference2`** params, and the two **OUTBOUND** shipment builders now use them
+  **instead of `SalesOrders.customerPurchaseOrder`**.
+- Semantics (decided; the field-config placeholders were authoritative over the initial verbal
+  description, and confirmed in testing when `281144` = `SalesOrders.number` was entered into
+  Reference 1): **Reference 1 = NetSuite SALES order #, Reference 2 = NetSuite PURCHASE order #.**
+- Length is capped at **35 characters** (carrier limit), enforced in the form config
+  (`characterLimit: 35`).
+
+### ⚠ CRITICAL — UPS `TransactionReference.CustomerContext` NEVER prints on a label
+
+The code previously sent the reference into
+`ShipmentRequest.Request.TransactionReference.CustomerContext`. That field is UPS's **request/response
+correlation echo**: UPS accepts it, returns **HTTP 200**, and **prints nothing**. This is why a
+reference never appeared on a GroWrk label — with no error to point at it.
+
+> **A carrier accepting a value with a 200 is not evidence that it printed. Only the rendered label
+> is.** Verify every label-content change against the actual label image.
+
+**Real label references require PACKAGE-LEVEL `ReferenceNumber` entries** (`Code` + `Value`):
+
+- **Shipment-level `ReferenceNumber` is REJECTED by UPS on US/PR → US/PR domestic shipments** — which
+  is most GroWrk volume — so **package level is mandatory**, not merely preferred.
+- **UPS prints the code's MEANING next to the value**, so the code choice is user-visible. Verified
+  code table: **`PO`** = Purchase Order Number, **`TN`** = Transaction Reference Number, **`IK`** =
+  Invoice Number, **`ON`** = Dealer Order Number, **`RZ`** = Return Authorization, plus `AJ`, `AT`,
+  `BM`, `9V`, `DP`, `3Q`, `MK`, `MJ`, `PM`, `PC`, `RQ`, `SA`, `SE`, `ST`, `EI`, `TJ`, `SY`.
+  **UPS has NO sales-order code.**
+- **Limits:** max **2** reference numbers per shipment, **35 chars** each; only **one** can be
+  barcoded per shipment (barcoding additionally requires ≤14 alphanumeric / ≤24 numeric and **no
+  spaces**).
+
+**FedEx** (`requestedPackageLineItems[].customerReferences[]`) **does** print. Enum values:
+`CUSTOMER_REFERENCE`, `P_O_NUMBER`, `INVOICE_NUMBER`, `DEPARTMENT_NUMBER`, `BILL_OF_LADING`,
+`RMA_ASSOCIATION`, `STORE_NUMBER`, `ELECTRONIC_PRODUCT_CODE`, `SHIPMENT_INTEGRITY`,
+`INTRACOUNTRY_REGULATORY_REFERENCE`. Max **3 per package**, and FedEx **rejects two entries of the
+same type**.
+
+**Chosen mapping (kept identical across carriers so a label reads the same either way):**
+
+| Field | UPS code | FedEx type |
+|---|---|---|
+| Reference 1 (NetSuite Sales Order #) | `TN` (Transaction Reference Number) | `CUSTOMER_REFERENCE` |
+| Reference 2 (NetSuite Purchase Order #) | `PO` (Purchase Order Number) | `P_O_NUMBER` |
+
+`TN` was chosen over `ON` (Dealer Order Number) precisely **because UPS prints the code's meaning** —
+"Dealer Order Number" would be misleading next to a sales-order number.
+
 ## `FIELD_STORAGE` mechanics (reference)
 
 `Model.php` handles storage fields separately from regular columns (write loop ~line
@@ -204,6 +265,30 @@ still discards the unsaved in-memory value.
 
 ## Gotchas / known issues
 
+- **⚠ `[ups] label_format` must be set in EVERY environment's api2 config.** Without it **production
+  UPS returns ZPL**, while the Fulfill & Ship return-label path expects a **raster PNG** for FPDF.
+  `beta.ini` already carried `label_format = "PNG"` and `production.ini` did **not** — which is
+  exactly why the flow worked on beta and failed in production (api2 `851c227` added it). When a
+  label-format bug reproduces in only one environment, diff the `[ups]` config block first.
+- **⚠ NO carrier can be tested on ANY non-production environment.** Beta (`api.beta.togahub.com`,
+  which reads the **dev-sandbox** cluster) runs `debug_mode = 1` → UPS `wwwcie.ups.com` (CIE) and
+  FedEx `apis-sandbox.fedex.com`; production uses `apis.fedex.com`. But the carrier **account
+  numbers** in non-prod data are **copied from production**, and neither test environment accepts a
+  production account: UPS → **"Missing or invalid shipper number" (120100)**, FedEx → **HTTP 400**.
+  **Label generation is therefore verifiable only in production** until CIE/sandbox-valid test
+  accounts are seeded into non-prod `ShippingCarrierAccountNumbers` (the stated remedy — not done).
+  Also: **beta and production point at the SAME NetSuite account (1095849)**, so a beta fulfillment
+  writes to production NetSuite. See the
+  [non-prod metadata drift workflow](../../dbchanges2/workflows/nonprod-metadata-drift-repair.md).
+- ~~FedEx shipment failures collapse to a generic "temporarily unavailable" message.~~ **Fixed
+  2026-07-31.** `Fedex.php` did
+  `$errorData?->errors[0]?->message ?? 'Shipment service is temporarily unavailable (HTTP n)'`, so any
+  unexpected response shape lost the real cause — and because the ship call runs with
+  `setLogging(false)`, **that message is the only diagnostic there is**. A new private static
+  **`describeShipmentError()`** (with `MAX_ERROR_BODY_LENGTH = 300`) now reports **every** `errors[]`
+  entry as `"CODE: message"`, echoes a **truncated raw body** when the shape is unrecognized, and
+  distinguishes an **empty** body. General rule for this codebase: a `??` fallback string on an error
+  path destroys the only evidence — report the unexpected shape instead of masking it.
 - UPS **test** endpoint (`wwwcie.ups.com`, debug mode) returns a constant tracking
   number `1ZXXXXXXXXXXXXXXXX` + SAMPLE labels → `TrackingNumbers.number` UNIQUE
   collision and File Cabinet duplicate-filename failures on repeat tests (see the
@@ -282,6 +367,22 @@ still discards the unsaved in-memory value.
   bill) — expect a hard error rather than a silently-wrong bill in those cases.
 
 ## Change history
+- 2026-08-03 — TRUE-80494: **wired Reference 1 / Reference 2 through to the carrier so they PRINT on
+  the label** — `ShipmentRequest` gained `$referenceString2`, `upsShipmentApi`/`fedexShipmentApi`
+  gained optional `$reference1`/`$reference2` (transient query-string params, **zero dbchanges2
+  work**), and the outbound builders now use them instead of `SalesOrders.customerPurchaseOrder`.
+  **Critical carrier discovery:** UPS `TransactionReference.CustomerContext` is a correlation echo
+  that **never prints** (200, no error) — label references need **package-level `ReferenceNumber`**
+  (`Code`+`Value`), since shipment-level is **rejected** on US/PR→US/PR domestic; UPS prints the
+  code's *meaning*, max 2 refs × 35 chars, one barcodable; FedEx
+  `requestedPackageLineItems[].customerReferences[]` does print (max 3/package, no duplicate types).
+  Mapping: Ref1 (NS Sales Order) → UPS `TN` / FedEx `CUSTOMER_REFERENCE`; Ref2 (NS Purchase Order) →
+  UPS `PO` / FedEx `P_O_NUMBER`. Fixed **FedEx error swallowing** (`describeShipmentError()` reports
+  every `errors[]` entry + a truncated raw body; the ship call logs nothing, so that string was the
+  only diagnostic). Recorded that **no carrier is testable outside production** (non-prod holds
+  production account numbers → UPS 120100 / FedEx 400; beta shares prod NetSuite 1095849) and that
+  **`[ups] label_format = "PNG"` was missing from `production.ini`** (prod returned ZPL where FPDF
+  needs PNG — beta had it, which is why only prod failed). (mhammontree)
 - 2026-07-17 — TRUE-79191: applied **signature type** to outbound labels for the first time (carrier
   libs previously ignored it). Added a generic `$signatureType` on `ShipmentRequest`;
   `fedexShipmentApi`/`upsShipmentApi` now SELECT + pass `TrackingNumbers.signatureType`; FedEx maps to

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

@@ -3,13 +3,14 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
+| [API Payload Interceptors (metadata-registered prePost/postPut model hooks)](features/api-payload-interceptors.md) | A `_Model`'s `prePost()` / `postPost()` / `prePut()` / `postPut()` hooks are **not** called by the model. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/ItemFulfillment.php, dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql |
 | [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | A single authenticated V2 GET listing can return records across **many** clients (designed for 1000+) that the caller is entitled to, honoring **each target cli | api2/Component/Api/CrossClient/CrossClient.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, _underscore/Model/Cache/Table.php, _underscore/Model/Cache/Tables/Client.php, _underscore/Model/Core/Record.php, worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Cache/2026-06-30a - MultiClientCacheTables.sql, dbchanges2/Core/2026-06-30b - CacheClusterRegistrationAndRecordTtl.sql, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
 | [Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)](features/encrypted-user-uuid-auth-handoff.md) | `POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**: given an encrypted `{client, user}` UUID pair, it mints a fr | api2/Component/Api/CrossClient/CrossClient.php |
 | [Health-check endpoint (/health liveness short-circuit)](features/health-check-endpoint.md) | `_Controller_Index::api()` short-circuits **liveness/health-probe** requests to an HTTP 200 **before** any routing, DB bootstrap, or V2 engine work runs. | api2/Controller/Index.php |
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, plus item **feature** text — `Features.name`, `ItemCategoryFeatureGroups.name`, `ItemFeatures | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql |
 | [Nested FK object embedding is gated by the CHILD record's own ACL](features/nested-fk-acl-embedding.md) | When the V2 JSON engine serializes a foreign-key field into a **nested object** (in `getFullModelData()`, ~V2.php L6016-6060), it re-checks the **child** record | api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql |
-| [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php |
-| [Record Scripts (computed/aggregate /v2 endpoints — the authoring contract)](features/record-scripts.md) | In api2 you almost never write a controller. | api2/Component/Api/V2/V2.php, _underscore/Model/Team/Sprint.php, _underscore/Query.php |
+| [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/ContactEmailAddress.php |
+| [Record Scripts (computed/aggregate /v2 endpoints — the authoring contract)](features/record-scripts.md) | In api2 you almost never write a controller. | api2/Component/Api/V2/V2.php, _underscore/Model/Team/Sprint.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Query.php |
 | [V2 Request Logging & Where Requests Land (client vs core log DB)](features/request-logging.md) | The V2 engine logs **every inbound request** — success *and* failure, with response code and payload — and routes each log entry to the **client** log or the ** | api2/Component/Api/V2/V2.php, _underscore/Model/Client/Logs/Api.php, _underscore/Model/Core/Logs/Api.php |
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |
 | [TOGa IQ Sprint Dashboard API (Record Scripts)](features/sprint-dashboard-api.md) | The internal **TOGa IQ sprint dashboard** is served in production by **six api2 Record Scripts** on `_Model_Team_Sprint` (`_underscore/Model/Team/Sprint.php`), | _underscore/Model/Team/Sprint.php, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-07-24a - SprintDashboardRecordScripts.sql, dbchanges2/Client_True/2026-07-24b - SprintDashboardScriptAcl.sql |

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

@@ -0,0 +1,86 @@
+---
+title: API Payload Interceptors (metadata-registered prePost/postPut model hooks)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-08-03
+owners: ["mhammontree"]
+files:
+  - api2/Component/Api/V2/V2.php
+  - _underscore/Model/Client/ItemFulfillment.php
+  - dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql
+related:
+  - ./record-scripts.md
+  - ../architecture.md
+  - ../../_underscore/features/acl-permission-chain.md
+  - ../../_underscore/features/recursive-item-fulfillments.md
+---
+
+## Summary
+
+A `_Model`'s `prePost()` / `postPost()` / `prePut()` / `postPut()` hooks are **not** called by the
+model. They are dispatched by the api2 **/v2 engine**, and **only if a metadata row exists** in
+`Core.ApiPayloadInterceptors` (or the Client-level equivalent) for that record + processing phase +
+HTTP method. **A missing registration row means the hook silently never runs** — the code is
+present, correct, deployed, and dead. This is the single most misleading failure mode in the
+interceptor mechanism: the symptom looks exactly like a code bug.
+
+## How it works
+
+1. On a write, `_Component_Api_V2` (`api2/Component/Api/V2/V2.php`) looks up
+   `ApiPayloadInterceptors` by **`(recordId, prePostProcessing, httpMethod)`** — e.g.
+   `(28, 'PRE', 'POST')`.
+2. The PHP method name is **derived from those two enum values**, not stored:
+   `strtolower(prePostProcessing) . ucfirst(strtolower(httpMethod))`. So:
+   - `PRE` + `POST` → **`prePost`**
+   - `POST` + `POST` → **`postPost`**
+   - `POST` + `PUT` → **`postPut`**
+3. If a row matches, the engine calls that static/instance method on the resolved model (the
+   **client subclass** when one exists — `_Model_Growrk_ItemFulfillment` before
+   `_Model_Client_ItemFulfillment`). If no row matches, nothing is called and there is **no error,
+   no message, and no log line**.
+
+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.
+
+## Worked example — the EV-10 that was not a code bug
+
+`_Model_Client_ItemFulfillment::prePost()` defaults `itemFulfillmentStageId` to the shipped stage on
+a `POST /v2/item-fulfillments`. In **dev-sandbox** the `(recordId 28, PRE, POST)` row was missing, so
+`prePost` never ran, `itemFulfillmentStageId` stayed `NULL`, and the write failed with **`EV-10`
+"Column 'itemFulfillmentStageId' cannot be null"** — while the identical code worked in production.
+Fix was purely metadata: apply the existing
+`dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql`.
+
+**Diagnostic that works:** do a **full-table compare of `ApiPayloadInterceptors` between production
+and the failing environment**. It is a small table, and the drift is usually exactly one row.
+
+## Gotchas / known issues
+
+- **⚠ A hook that "isn't running" is a missing registration row before it is a code bug.** Check
+  `ApiPayloadInterceptors` for `(recordId, phase, method)` **first** — never start by re-reading the
+  PHP.
+- **The method name is derived, so a typo'd enum silently misses.** A row with
+  `prePostProcessing = 'PRE'`, `httpMethod = 'PUT'` resolves to `prePut`, not `prePost`; the engine
+  will simply find no method and move on.
+- **Registration is per-environment.** Like `RecordFields` / `RecordScripts` / ACL rows, this is
+  metadata — "works in prod, not in beta/dev-sandbox" is the signature of drift, not of a bad
+  deploy. See the
+  [non-prod metadata drift repair workflow](../../dbchanges2/workflows/nonprod-metadata-drift-repair.md).
+- **Never emit output from an interceptor.** A stray `echo`/`print_r` corrupts the `/v2`
+  `{isSuccess,…,data}` envelope (this really happened in `ItemFulfillment.php` — see the
+  carrier-shipping-labels doc).
+- **Interceptors are a client-behavior extension point.** Per api2's architecture doc, client
+  specifics belong in `_Model_<Slug>_X` overrides + interceptor hooks, **not** in `V2.php`.
+
+## Change history
+
+- 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
+  from that metadata, and the method name is derived as
+  `strtolower(phase) . ucfirst(strtolower(method))`. Added the prod-vs-env full-table compare as the
+  diagnostic. (mhammontree)

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

@@ -6,10 +6,11 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-20
+updated: 2026-08-03
 owners: ["bala", "mhammontree", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
+  - _underscore/Model/Client/ContactEmailAddress.php
 related:
   - ../architecture.md
   - ../../../clients/aig/features/entitlement-intake.md
@@ -124,6 +125,33 @@ build — audit such rows before/with the deploy. First seen in AIG (TRUE-79978)
 beta/QA threw EV-12 on the injected `entitlementFulfillmentType` — see
 [AIG entitlement intake](../../../clients/aig/features/entitlement-intake.md).
 
+## A wrong-shaped nested collection returns 201 and silently drops the data
+
+V2 **ignores payload keys it does not recognize** and does not validate the *element shape* of a
+nested collection. Two distinct failure modes both return **HTTP 201 Created** with no error
+anywhere — no `messages[]`, nothing in the client `Logs` or the core/writer `Logs`:
+
+1. **Unknown / flat key.** A partner sends a source-side column label (e.g. a literal
+   `UserDefined3`) instead of the nested collection. The key is dropped; no child row is created.
+2. **Array of bare strings instead of array of objects.** `"contactEmailAddresses":
+   ["email2@domain.com"]` instead of `[{"emailAddress": "email2@domain.com"}]`. Nothing is
+   created, and any consumer doing `array_column($list, 'emailAddress')` gets an **empty** list —
+   so a downstream sync silently falls back to the primary email and the extra addresses vanish
+   with no trace.
+
+**Operational rules that follow:**
+
+- **When verifying a nested-collection integration, assert actual child ROW COUNTS** (e.g.
+  `SELECT COUNT(*) FROM Client_Aig.ContactEmailAddresses …`). **Never** treat the HTTP status as
+  evidence — a 201 proves only that the parent was written.
+- **Never hand a partner a path expression as the spec.** `contactEmailAddresses[].emailAddress`
+  does not pin element structure and reads as "an array of emails" to many developers. Always give
+  a **concrete JSON example** of the collection, objects included.
+- **Know whether the collection is direct or bridged.** A direct child collection is a **flat
+  array of objects** (`contactEmailAddresses: [{emailAddress}]`); a bridge/join collection is
+  **double-wrapped** (`entitlementEntitlementCoverageTypes: [{entitlementCoverageType: {…}}]`).
+  Both shapes routinely appear in the *same* payload, so the sibling collections actively mislead.
+
 ## Gotcha
 
 - **Nested write with only a non-identifier field silently creates duplicates.** This is a
@@ -135,6 +163,13 @@ beta/QA threw EV-12 on the injected `entitlementFulfillmentType` — see
 
 ## Change history
 
+- 2026-08-03 — Documented that V2 **silently ignores unrecognized payload keys and does not
+  validate nested-collection element shape**: both a flat/unknown key and an array of bare strings
+  (instead of an array of objects) return **HTTP 201** with the data dropped and no error logged
+  anywhere. Added the verification rule (assert child row counts, never the HTTP status), the rule
+  to give partners a concrete JSON example rather than a `collection[].field` path expression, and
+  the direct-vs-bridged collection shape distinction. Surfaced while resolving the AIG TRUE-79401
+  multi-email payload shape (`Client_Aig.ContactEmailAddresses`); no code changed. (mhammontree)
 - 2026-07-20 — Root-caused the **UPDATE-path** failure of the single-key-uuid forced-MATCH: the
   update path injects a reverse back-reference (`contactId = parent id`) into nested child objects
   at `V2.php:4985–4996` (commit `91d803f`) when the child has a back-FK to the parent, turning the

package/knowledge/2.0/apps/api2/features/record-scripts.md

@@ -6,11 +6,12 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-24
-owners: ["kyalamarthi"]
+updated: 2026-08-03
+owners: ["kyalamarthi", "mhammontree"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Team/Sprint.php
+  - _underscore/Model/Client/ItemFulfillment.php
   - _underscore/Query.php
 related:
   - ./sprint-dashboard-api.md
@@ -67,6 +68,37 @@ Rules the engine enforces (see `getRecordScriptPhpMethod()` + the dispatch in
   method itself still returns the raw object/array — do not echo, and never build the
   success/error envelope yourself.
 - Invocation is effectively `$model::$phpMethod(...$args)`.
+
+### ⚠ Argument binding is PHP NAMED-ARGUMENT unpacking of the QUERY STRING — with two consequences
+
+Verified in `api2/Component/Api/V2/V2.php` (~L4202 and ~L4468): the engine does
+`parse_str($_SERVER['QUERY_STRING'], $args)`, **merges the JSON request body** into the same array
+(**the query string wins** on a key collision — body support exists so a large value can avoid an
+HTTP 414; see [scripted-api POST-body args](./scripted-api-post-body-args.md)), sets
+`$args['api'] = $this`, and then calls
+`$candidateClientModelName::$recordScriptPhpMethod(...$args)`. Because `$args` is a **string-keyed**
+array, that spread is **PHP named-argument unpacking**: each query-string key must match a
+**declared parameter name** on the method.
+
+1. **Free extension point — a transient value needs NO schema, RecordField, or ACL work.**
+   `Core.RecordScripts` has columns `recordId`, `method`, `route`, `phpMethod` and **no parameter
+   signature at all**, so adding a parameter to a script is a **pure code change** — no migration.
+   This is the sanctioned way to pass a per-request, **unpersisted** value through to an external
+   call (first use: TRUE-80494 passed the user-entered Reference 1 / Reference 2 through
+   `upsShipmentApi` / `fedexShipmentApi` to the carrier label — the values are never stored).
+   Declare the new params **optional** (`?string $reference1 = null`).
+2. **⚠ An unmatched query key THROWS — so backend MUST deploy before frontend.** A key with no
+   matching declared parameter raises `Unknown named parameter $x` and the call fails outright.
+   Two real hazards: (a) if several **sibling** scripts receive the same new query params, every
+   sibling must declare them — adding the param to only `upsShipmentApi` breaks
+   `fedexShipmentApi`; (b) a frontend deployed **ahead** of the backend sends a param the deployed
+   method doesn't declare and breaks **every** call to that script. Any change that adds a script
+   parameter therefore carries a **mandatory deploy order: `_underscore`/api2 first, frontend
+   second.**
+
+> **`_underscore/Route.php` is NOT involved in this.** `Route.php` binds **path segments**
+> (`explode('/', urldecode($route))`), not the query string. Don't go looking there when debugging
+> record-script arguments.
 - **No current-sprint (or any per-request context) middleware.** Unlike a hand-built app, the
   `/v2` engine has no middleware that pre-resolves a "current" entity for a script. Each Record
   Script must resolve its own context (e.g. the current sprint) inside the method.
@@ -225,6 +257,14 @@ an `AclRecordScripts` grant in each client DB.
 
 ## Change history
 
+- 2026-08-03 — TRUE-80494: documented that argument binding is **PHP named-argument unpacking of the
+  query string** (`parse_str` + merged JSON body, query wins, `$args['api']` last, then
+  `$model::$phpMethod(...$args)`; `V2.php` ~4202/~4468) and its two consequences: (a) a script
+  parameter is a **pure code change** — `Core.RecordScripts` stores no signature, so a transient,
+  unpersisted per-request value can be threaded to an external call with **no migration/ACL work**
+  (first use: Reference 1/2 → carrier label); (b) an **unmatched query key throws**, so every
+  sibling script must declare shared new params and the **backend must deploy before the frontend**.
+  Also noted `_underscore/Route.php` binds path segments, not query args. (mhammontree)
 - 2026-07-31 — TRUE-80487: added the **reusable client-side `CustomRecordScript` pattern** for a
   scripted API declared on a client model — `CustomRecordScripts` + `AclCustomRecordScripts` are
   **both** `DB_CLIENT`, so registration and grant land in **one** database and the grant resolves

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

@@ -5,3 +5,4 @@
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
 | [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | > **A local browser wizard now automates this.** Steps 2–9 below (create DBs, generate Core/API > inserts, append to `Clients_Db.txt`) — plus the dbchanges2 bla | Client/, Client_<Tenant>/, Core/, Logs_Client/ |
+| [Repairing non-prod metadata drift (works in prod, broken in beta/dev-sandbox)](workflows/nonprod-metadata-drift-repair.md) | Almost all 2.0 platform behavior is **metadata** — `Core.Records`/`RecordFields`, `Core.RecordScripts`, `Core.ApiPayloadInterceptors`, and per-client `Acl*` row | dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, api2/Config/beta.ini |

package/knowledge/2.0/apps/dbchanges2/workflows/nonprod-metadata-drift-repair.md

@@ -0,0 +1,153 @@
+---
+title: Repairing non-prod metadata drift (works in prod, broken in beta/dev-sandbox)
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: shared
+type: workflow
+status: active
+updated: 2026-08-03
+owners: ["mhammontree"]
+files:
+  - dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql
+  - dbchanges2/Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql
+  - dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql
+  - api2/Config/beta.ini
+related:
+  - ../architecture.md
+  - ../../api2/features/api-payload-interceptors.md
+  - ../../api2/workflows/environment-configuration-and-provisioning.md
+  - ../../_underscore/features/acl-permission-chain.md
+---
+
+## Summary
+
+Almost all 2.0 platform behavior is **metadata** — `Core.Records`/`RecordFields`,
+`Core.RecordScripts`, `Core.ApiPayloadInterceptors`, and per-client `Acl*` rows. Non-prod
+environments receive those rows by someone remembering to run a migration there, so they **drift**.
+
+> **Default assumption: when a feature works in production but not in beta / dev-sandbox, the
+> environment's metadata is behind — not the code.** Verify drift before touching PHP.
+
+This workflow is the repair procedure, written from bringing dev-sandbox up to date so beta could
+exercise TOGa Supply Fulfill & Ship (TRUE-80494).
+
+## Steps
+
+1. **Identify which cluster the environment actually reads.** `api.beta.togahub.com` reads the
+   **dev-sandbox** cluster (`api2/Config/beta.ini` `[database] hostname =
+   dev.sandbox.database.togahub.com`) — "beta" is not its own database. Fix the right DB.
+2. **Full-table compare the small metadata tables, prod vs. target.** `ApiPayloadInterceptors` in
+   particular is small enough to diff wholesale, and the drift is typically **exactly one row**
+   (dev-sandbox was missing `(recordId 28, PRE, POST)`, so `prePost` never defaulted
+   `itemFulfillmentStageId` → `EV-10 Column 'itemFulfillmentStageId' cannot be null`). Apply the
+   existing migration rather than writing a new one.
+3. **For a field that reads back empty/blank, check `AclFieldPermissions` before the selector.** An
+   ungranted field is **silently omitted** from the GET body (HTTP 200, no message). `Measures.measureType`
+   had zero grant rows in dev-sandbox `Client_Growrk` → omitted from `GET /v2/measures` → the frontend's
+   `measureType === "LENGTH"` split produced empty arrays → both unit dropdowns rendered empty with no
+   error anywhere. See the [ACL permission chain](../../_underscore/features/acl-permission-chain.md).
+4. **Before running a grant migration that clones a sibling, verify the sibling's own grants exist in
+   that DB.** The clone reads the target DB's own rows, so a sibling with no grants there inserts
+   **zero rows and does not error**. Safe reference siblings (present + complete per client):
+   `shippingMethodId` (338), `measures.slug` (723), `containsBattery` (962), `shipToAddressId` (991).
+   **Do NOT mirror `needsReturnLabel`** — its grants are absent in some clients.
+5. **Register any missing Core `RecordField` + client column.** In dev-sandbox
+   `tracking-numbers.signatureType` was unregistered; it was registered, the
+   `TrackingNumbers.signatureType VARCHAR(255)` utf8mb4 column added, and `containsBattery` (962)
+   mirrored for its grants. **⚠ `Core.RecordFields` ids are team-maintained constants — ask for the
+   next `id` per the [dbchanges2 architecture rule](../architecture.md) (2026-07-31, jcardinal).**
+   What was actually done here diverged from that rule; see *Open question for jcardinal* below
+   before copying it.
+6. **Re-test the feature end-to-end in that environment**, then record what is still missing so the
+   next person doesn't rediscover it.
+
+## Environment facts worth knowing before you test here
+
+- **NO carrier can be tested on ANY non-production environment.** Beta runs
+  `[_underscore] debug_mode = 1`, which routes UPS to `wwwcie.ups.com` (CIE/test), and its
+  `[fedex] oauth` points at `https://apis-sandbox.fedex.com` (production uses `https://apis.fedex.com`).
+  But the carrier **account numbers** in non-prod data are copied from production, and neither test
+  environment accepts a production account — UPS returns **"Missing or invalid shipper number"
+  (120100)** and FedEx returns **HTTP 400**. **Label generation can only be verified in production**
+  until CIE/sandbox-valid test accounts are seeded into non-prod
+  `ShippingCarrierAccountNumbers`. (Remedy = obtain those test accounts; documented as the fix, not done.)
+- **⚠ Beta and production point at the SAME NetSuite account (1095849).** Any beta fulfillment
+  writes to **production** NetSuite. Treat a beta fulfill run as a production side effect.
+- **In dev-sandbox, `Core` and `Client_*` share one cluster**, so a `Core.`-qualified reference in a
+  `Client/` migration resolves there and looks fine. **Production splits them** (prod-core /
+  prod-client) — a clean dev-sandbox run is never proof a migration is cluster-safe (see the
+  architecture doc's hard isolation rule).
+
+## Open question for jcardinal — observed `Core.RecordFields` id divergence
+
+> **This section records evidence only. It does NOT amend
+> [`2.0/apps/dbchanges2/architecture.md`](../architecture.md).** The 2026-07-31 rule there
+> (jcardinal, commit `0af489d`, enforced by the `dbchanges2-record-ids` hook) is **normative**:
+> `Core.Records`/`Core.RecordFields` ids are team-maintained constants **so that** a client-database
+> migration can hardcode a `recordFieldId` and never read `Core` — which is what makes the
+> *Database isolation* hard rule workable, since production splits `Core` and `Client_*` across
+> separate clusters. The observations below indicate the rule is being **violated in dev-sandbox**;
+> they are not evidence the rule is wrong. Escalated to jcardinal, unresolved.
+
+**1. Observed divergence** (verified 2026-08-03, read-only inspection):
+
+- `items.isFulfillable` = **2434** in production, **2615** in dev-sandbox — **pre-existing**, not
+  created by this session.
+- In dev-sandbox, ids **2480 / 2481 / 2482** belong to `vocabularies.id` / `vocabularies.uuid` /
+  `vocabularies.dtCreated`. In production the same ids are `item-fulfillments.returnAddressId`
+  (2480), `tracking-numbers.signatureType` (2481), `entitlements.serviceAddressId` (2482).
+- Consequence: the shipped `Core/2026-07-10a - ItemFulfillmentReturnAddressIdRecordField.sql` and
+  `Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql` **cannot be applied to dev-sandbox
+  as written** — they would fail on a duplicate primary key.
+
+**2. The hazard this creates for the new rule (the important part).** Because the rule directs that
+`recordFieldId` **should** be hardcoded in client-database migrations, a `Client/` file hardcoding
+**2481** (production's `tracking-numbers.signatureType`) and run against **dev-sandbox** resolves to
+**`vocabularies.uuid`** and would **silently grant permissions on the wrong field** — a silent
+wrong-field write, strictly **worse** than a no-op.
+
+**3. Question for jcardinal.** Should dev-sandbox `Core.RecordFields` be **reconciled to production**
+so the stable-id premise holds in every environment — and if so, how, given those rows are already
+referenced by client `AclFieldPermissions`? And **until** it is reconciled, what should a `Client/`
+migration do: hardcode the id (risking the wrong field in non-prod) or resolve by the **stable
+`uuid`**?
+
+**4. Workaround of record (not a precedent).** When registering `tracking-numbers.signatureType` in
+dev-sandbox during this session, `id` was **omitted** and `AUTO_INCREMENT` assigned **2764**. This is
+**contrary to the 2026-07-31 rule** and was done as a **one-off manual environment repair** to
+unblock testing. It is **not** a precedent for committed migrations — a committed `Core/` migration
+must still carry a team-assigned `id` literal.
+
+**5. Related observation, same escalation.** `Client/2026-07-22c -
+TrackingNumberMeasureIdsFieldPermission.sql` and `Client/2026-07-16b -
+TrackingNumberSignatureTypeFieldPermission.sql` resolve their `recordFieldId` via
+`SET @fieldId = (SELECT … Core.RecordFields …)` before each INSERT block, with later blocks' `SET`s
+positioned **after** earlier INSERTs. Two factual consequences observed: (a) reading
+`Core.RecordFields` from a `Client/` file is itself a **Database-isolation violation** per
+[architecture.md](../architecture.md); (b) when the file is run in chunks / per client selection, the
+later block's variables are unset, `WHERE sibling.recordFieldId = NULL` matches nothing, and **0 rows
+insert with no error** — this silently no-op'd the `measures.measureType` read grant **twice** (first
+in production, then again in dev-sandbox), each time presenting as "empty unit dropdowns". The
+architecture-consistent remedy is to **hardcode the `recordFieldId` literal**, which removes the
+`Core` lookup entirely and with it the half-execution failure mode — but that is exactly the practice
+blocked by the id-divergence hazard in item 2 above, which is why both go to jcardinal together.
+
+## Known remaining drift (dev-sandbox, as of 2026-08-03)
+
+- `item-fulfillments.returnAddressId` — the **column exists** but there is **no Core RecordField**.
+  Only needed for the return-label flow.
+
+## Change history
+
+- 2026-08-03 — TRUE-80494: created from repairing dev-sandbox so beta could exercise Fulfill & Ship —
+  completed `Client_Growrk` measure grants (2476/2477/2478, role 1), applied the missing
+  `ApiPayloadInterceptors` PRE/POST row for recordId 28, registered
+  `tracking-numbers.signatureType` (+ column, + mirrored `containsBattery` grants). Recorded the
+  diagnostic sequence (full-table interceptor compare; verify sibling grants exist before a clone, or
+  it inserts zero rows silently), the safe reference siblings, that **beta reads the dev-sandbox
+  cluster**, that **no carrier is testable outside production**, and that **beta shares production's
+  NetSuite account**. Also opened an **escalation to jcardinal** (evidence only — architecture.md
+  deliberately left unchanged) on observed `Core.RecordFields` id divergence between production and
+  dev-sandbox and the silent wrong-field hazard it creates for hardcoded `recordFieldId`s.
+  (mhammontree)

package/knowledge/2.0/apps/toga2-supply/features/fulfill-and-ship.md

@@ -6,7 +6,7 @@ project: TOGa Supply
 client: shared
 type: feature
 status: active
-updated: 2026-07-27
+updated: 2026-08-03
 owners: [mhammontree]
 files:
   - _underscore/Model/Client/Measure.php
@@ -184,14 +184,19 @@ bare string** — see the gotcha below before wiring a new select field.
   `renderEditShipmentFormInput` rendering it via `BaseDisabledInput` on an `isReadOnly` flag. **Not
   persisted to `IF.locationId`** for now — persisting would be a separate backend "set from SO"
   change plus a NetSuite-mapping check.
-- **Reference 1 / Reference 2 fields are placeholders (rendered, values NOT wired yet).**
-  Definitions are settled: **Reference 1 = NetSuite Sales Order #, Reference 2 = NetSuite Purchase
-  Order #** (Eric, authoritative — supersedes Skyler's earlier "Ref 1 = vendor account #, Ref 2 =
-  company name"). Value sourcing/persistence/carrier-wiring is intentionally deferred; when wiring,
-  verify: SO# = the document **ORDER #** (e.g. `281144`) vs the internal id (`7221433`, stored as
-  `c_netsuiteInternalSalesOrderId`); the PO# lives in NetSuite and may not be in the 2.0 DB (the
-  SO's `customerPurchaseOrder` field — already reused as the carrier `referenceString` — vs a
-  separate linked NetSuite PO document).
+- **Reference 1 / Reference 2 are WIRED (2026-07-31, TRUE-80494) — user-entered, NOT persisted.**
+  Definitions confirmed: **Reference 1 = NetSuite Sales Order #, Reference 2 = NetSuite Purchase
+  Order #** (the field-config placeholders were authoritative over the initial verbal description,
+  and testing confirmed it — `281144` = `SalesOrders.number` — entered into Reference 1). Per SME
+  (Skyler) the values are **user-entered, NOT prefilled from NetSuite, and NOT persisted**; their
+  **sole purpose is to reach the carrier and print on the label**. Implemented as **transient
+  query-string params** on the existing carrier RecordScript calls (`fulfillShipment` in
+  `UpdateShipmentApi.ts` → `upsShipmentApi`/`fedexShipmentApi`) — **no defaultValues, no save
+  payload, no DB columns, zero `dbchanges2` work**. Form enforces `characterLimit: 35` (carrier
+  limit). Carrier codes + the UPS "CustomerContext never prints" trap: see the
+  [carrier-shipping-labels doc](../../_underscore/features/carrier-shipping-labels.md). **⚠ Adding a
+  param to a RecordScript means the BACKEND MUST DEPLOY FIRST** — a frontend sending a param the
+  deployed PHP doesn't declare throws `Unknown named parameter` and breaks every call.
 - **Phone # is REQUIRED by design (verified, kept per Eric):** config `isRequired:true` +
   `showRequiredIndicator`, enforced by `validateFormOnSubmit`.
 - **Address block layout (Figma):** inline **left** labels (Addressee / Attention / Address 1 /
@@ -366,6 +371,42 @@ the call 403s and returns no label.
 
 ## Gotchas / known issues
 
+- **⚠⚠ A config-driven validator MUST skip DISPLAY-ONLY fields — this caused a TOTAL production
+  submit outage (2026-07-29 → 2026-07-31, all clients).** `DUMMYUPDATESHIPMENTFIELDS.json` contains a
+  **display-only section header** (id 31, "Address") with **`valueKey: ""` and `isRequired: true`**.
+  react-hook-form's `getValues("")` **always returns `undefined`** (its internal `get` helper
+  short-circuits on a falsy path), so `validateFormOnSubmit` **always** set a validation error keyed
+  on **`""`**. This was harmless for months because the submit guard filtered blank keys
+  (`Object.keys(errors).filter(key => key && key.trim() !== "")`). The CodeRabbit **batch 2** change
+  replaced that guard with the **fresh boolean** returned by `validateFormOnSubmit`, which does **not**
+  filter blank keys → `hasErrors` always `true` → **silent early return → NO network request at all**.
+  It was invisible because the error is keyed on `""` and that field renders through `BaseInput`'s
+  `case "none"` branch, which has **no `errorMessage` slot**. Blast radius: **every client**, and all
+  three actions (Fulfill & Ship, Save, Save & Create New Shipment) share `onFormSubmit`.
+  **Two durable rules:**
+  1. A config-driven validator must skip display-only fields —
+     `if (!field.valueKey || inputType === "none") continue;`
+  2. **"No network request at all" is the diagnostic signature of client-side validation blocking**,
+     not a backend fault. Check the Network tab for the *absence* of a call before debugging the API.
+
+  **Decision (2026-07-31):** the fix shipped as a **minimal revert of the CALLER guard only**,
+  deliberately **keeping** `validateFormOnSubmit`/`checkDimensions` returning booleans so CodeRabbit
+  **batch 3**'s `clearErrors` fix survives. Rationale: smallest, safest diff to end a total production
+  outage. **Accepted trade-off:** this restores the first-submit-slips-through behaviour CodeRabbit
+  flagged, and CodeRabbit will likely re-flag it. The durable alternative — skip
+  `!field.valueKey || inputType === "none"` **inside** the validator, keeping both behaviours — is
+  recorded as future work (see the TRUE-80494 deployment doc).
+- **⚠ `saveShipment` is NOT transactional, and the edit screen masks the fallout.** `saveShipment`
+  (`UpdateShipmentApi.ts`) performs **three sequential POSTs** — item-fulfillment → tracking-number →
+  bridge — with **no rollback**. When the tracking-number POST fails, the already-created
+  `ItemFulfillment` is **orphaned**; and because `prePost` defaults the stage to SHIPPED, that orphan
+  can appear in **Fulfilled Shipments as a real shipment with zero tracking numbers** (observed:
+  F100074, id 7180, dev-sandbox). The edit screen then hides it: `EditShipmentForm.tsx` (~line 287)
+  does `const tn = editShipment.itemFulfillmentTrackingNumbers?.[0]?.trackingNumber ?? {}`, turning
+  "no tracking number" into an **empty object** — so the page **loads looking fine** and only fails on
+  save with `PUT /tracking-numbers/undefined` → **EV-6 with `uuid: "undefined"`**. **Diagnostic rule: a
+  literal `"undefined"` in a request URL means a client-side value was never populated — look for a
+  masking `?? {}` fallback**, not a backend bug.
 - **⚠ The shared `GoogleMapsLink` mapped the RECIPIENT, not the address.** The shared
   `components/ui/GoogleMapsLink.tsx` built its query from `[addressee, line1, line2, city, zip]`,
   which had two bugs: (a) it included the **`addressee` (recipient name)**, so Google surfaced the
@@ -669,8 +710,14 @@ the call 403s and returns no label.
   50px); may explore stacking. Owners: David Mancol (design) + Alexandra Peterson (phase 2/3).
   **Partly landed 2026-07-14:** the flexible-gap part of the spec now ships as a CSS
   `clamp(2px,1vw,50px)` on the row gaps; column-count reduction and stacking are still open.
-- **Reference 1/2 value wiring** — fields render but values aren't sourced/persisted; see the form
-  section (SO# vs internal id, PO# in NetSuite) before wiring.
+- ~~Reference 1/2 value wiring~~ — **done 2026-07-31 (TRUE-80494)**: transient carrier params, not
+  persisted; see the form section + the carrier-shipping-labels doc.
+- **Harden the validator instead of the caller** — replace the reverted caller-side blank-key guard
+  with a `!field.valueKey || inputType === "none"` skip **inside** `validateFormOnSubmit`, restoring
+  CodeRabbit's first-submit fix without re-breaking submit. See the outage gotcha.
+- **Make `saveShipment` transactional (or clean up on failure)** — today a failed tracking-number POST
+  orphans an ItemFulfillment that shows as a fulfilled shipment; and drop the masking `?? {}` on the
+  edit rehydrate so a missing tracking number surfaces on load, not on save.
 - **Global-vs-per-SO Shipments list** — pending Eric's model decision; see the gotcha above.
 - **"Fulfill & Ship from an existing Item Fulfillment"** third entry mode — see Planned direction.
 
@@ -682,7 +729,12 @@ expected once QA/users start.
 The return-label feature (TRUE-79191) needs **four** things present in a given environment or it
 silently mis-behaves; treat these as the release checklist when promoting to a new env:
 1. **`ItemFulfillments.returnAddressId` column** (Client DB) — the persisted return address FK.
-2. **RecordField 2434** (Core) — the record field backing `returnAddressId`.
+2. **The Core `RecordField` backing `returnAddressId`** — **id 2480 in production** (corrected
+   2026-07-31; the migration previously said 2434, which in prod is `items.isFulfillable`). **Do not
+   verify a `RecordFields` id against the target environment before relying on it** — prod and
+   dev-sandbox have drifted (open escalation: see the
+   [non-prod metadata drift workflow](../../dbchanges2/workflows/nonprod-metadata-drift-repair.md));
+   in dev-sandbox this field is **not registered at all**.
 3. **`generateReturnLabel` RecordScript** (Client DB) — the scripted-API dispatch grant.
 4. **Bridge ACL logic groups for records 317–322** (Client DB) — or reads 403 EZ-1; see the
    tracking-number-bridges doc.
@@ -709,6 +761,21 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 2026-08-03 — TRUE-80494 (hotfix + feature follow-up to TRUE-79191): **ended a TOTAL production
+  Fulfill & Ship submit outage** (all clients, since the 2026-07-29 deploy) — the display-only
+  "Address" section header (`valueKey: ""`, `isRequired: true`) always produced a validation error
+  keyed on `""` (RHF `getValues("")` is always `undefined`), which was previously filtered by the
+  caller's blank-key guard and became fatal once the caller branched on the validator's fresh boolean
+  → silent early return, **no network request at all**, invisible because `BaseInput`'s `case "none"`
+  has no error slot. Fixed by a **minimal revert of the caller guard only** (keeping the boolean
+  returns so CodeRabbit batch 3's `clearErrors` fix survives); validator-side skip recorded as future
+  work. **Wired Reference 1 / Reference 2** end-to-end as **transient, unpersisted** carrier params
+  (user-entered per SME Skyler; Ref1 = NS Sales Order, Ref2 = NS Purchase Order; `characterLimit: 35`;
+  zero dbchanges2 work) — **backend must deploy before frontend** because an undeclared RecordScript
+  param throws. Documented that **`saveShipment` is not transactional** (three sequential POSTs, no
+  rollback → orphaned ItemFulfillment that shows as *fulfilled* with no tracking, e.g. F100074/7180)
+  and that the edit rehydrate's `?? {}` masks it into a `PUT /tracking-numbers/undefined` → EV-6.
+  (mhammontree)
 - 2026-07-22 — TRUE-79191 (commit `e91f7029d`, full-stack): **IMPLEMENTED package Units of Measure** —
   the package weight + dimensions now have real Pound/Inch unit selectors that persist on the
   `TrackingNumber` and rehydrate on reopen (verified end-to-end). ZERO new tables: reused the client

package/knowledge/2.0/apps/worker2/features/teams-transcript-export.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-09
-owners: ["ajean", "jcardinal"]
+updated: 2026-08-03
+owners: ["ajean", "jcardinal", "mhammontree"]
 files:
   - worker2/Worker/Team/Transcripts.php
   - worker2/Config/production.ini
@@ -140,6 +140,15 @@ process is identical for all.
   those files. Acceptable as a one-off — the ledger `s3Key` is updated to match — but if you
   ever need a minimal re-file, change the move test to compare only the `YYYY-MM-DD` folder
   segment and relocate while preserving the original filename.
+- **There is NO transcript coverage before ~2026-06-12 — pre-June meetings are not in our store.**
+  `Team/Transcripts/Export` first ran successfully in production on **2026-06-12** (PR #78), and it
+  works off an **incremental watermark** with a bounded `lookbackDays`; nothing in its history shows
+  a multi-week backfill ever running. So searching `Team.TranscriptExports` /
+  `Team.TranscriptProcessing` / the `togaiq` KBs for a meeting older than ~2026-06-12 comes back
+  **empty even though the meeting WAS recorded**. Do not conclude "it wasn't recorded."
+  **Recovery path for an older meeting: Microsoft Graph** (which still retains it) or a manually
+  exported `.docx`/`.vtt` — not our own store. Hit in practice on 2026-08-03: a 2026-05-01 meeting
+  had to be supplied as a downloaded `.docx`.
 - **Cron rows cannot be `DELETE`d once they have fired.** `Core.WorkerJobs.cronJobId` has a FK
   (`WorkerJobs_CronJobs_FK`) to `CronJobs.id`, so a schedule change must `UPDATE` an existing
   row (and set `isActive = 0` on the ones being retired), not delete-and-reinsert. The historical
@@ -181,6 +190,12 @@ Policy gap; a `400` only on a UPN means the id was never resolved to a GUID. (A
 
 ## Change history
 
+- 2026-08-03 — Documented the **pre-2026-06-12 coverage gap**: `Team/Transcripts/Export` first ran in prod on
+  2026-06-12 (PR #78) and is watermark-incremental with a bounded `lookbackDays`, with no backfill
+  ever run — so any meeting older than ~2026-06-12 is absent from `Team.TranscriptExports` /
+  `Team.TranscriptProcessing` / `togaiq` despite having been recorded. Recovery is via Microsoft
+  Graph or a manual `.docx`/`.vtt` export. Found while recovering a 2026-05-01 meeting. No code
+  changed. (mhammontree)
 - 2026-07-09 — **`Export` re-architected to GRAPH-DIRECT** (merged into the ingestion pipeline).
   The `toga-private` staging bucket is dropped: `Export` is now a thin poller that records a
   discovery row and enqueues one `Process` job per transcript; `Process` downloads the VTT

package/knowledge/INDEX.md

@@ -20,8 +20,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 42 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 38 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 20 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
-- **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
+- **api2** (API) — 21 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **dbchanges2** (Database Changes) _(framework core)_ — 4 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 7 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)

package/knowledge/clients/aig/features/entitlement-intake.md

@@ -5,13 +5,14 @@ project: API
 client: aig
 type: client-feature
 status: active
-updated: 2026-07-29
+updated: 2026-08-03
 owners: ["mhammontree"]
 files:
   - _underscore/Model/Aig/Entitlement.php
   - dbchanges2/Client_Aig/2026-06-18a - TRUE-79534 AIG SaleItem codes.sql
 related:
   - clients/aig/features/contract-reconciliation.md
+  - 1.0/apps/library/features/toga2-api-client-and-bridge.md
   - 2.0/apps/api2/features/request-logging.md
   - 2.0/apps/api2/features/nested-relationship-writes.md
   - 2.0/apps/api2/architecture.md
@@ -121,6 +122,23 @@ Loading the catalog fixed intake, and because the feed re-sends outstanding cont
 **backlog of dropped contracts self-healed on the next scheduled run** — no manual back-fill was
 needed (see [contract reconciliation](contract-reconciliation.md)).
 
+## Business Unit (`UserDefined2`) — answered and DROPPED (nothing to build)
+
+AIG (Alissa, 2026-05-04) confirmed the **Business Unit / Value** field needs **nothing returned to
+AIG**: they already store it from the sale, and it is used only for **sales invoicing**, which is a
+**different process from claims invoicing** (the one we participate in). We replied asking them to
+**omit it from the API call entirely**. **No invoice-file template was ever needed.**
+
+Verified there is no dead custom field to clean up: `c_businessUnit` exists **nowhere** in
+`_underscore`, `api2`, or `dbchanges2` (the only `BusinessUnits` hits in the tree are unrelated, in
+the `forecast` repo). Corroborated by AIG's field-mapping spreadsheet, where the `UserDefined2`
+row's target column is **empty** while every other row is mapped.
+
+**This — not the extra emails — was the item actually blocking Paulina from sending the mapping
+document.** The two were conflated previously. See
+[the library bridge doc](../../../1.0/apps/library/features/toga2-api-client-and-bridge.md) for the
+resolved email-payload shape.
+
 ## Key files / entry points
 
 - **`_underscore/Model/Aig/Entitlement.php`** — `prePost(&$api, &$payload)` is the PRE-POST
@@ -223,6 +241,19 @@ this interceptor or use this dual-purpose Items pattern.
 
 ## Gotchas / known issues
 
+- **`postPost`'s SINGLE-recipient registration email is correct by design — do not "fix" it.**
+  It sends the Staples Protection Plan registration email to
+  `addTo($payload->contact->primaryContactEmailAddress->emailAddress)` only. TRUE-79401's multi-email
+  work is for **verification/lookup only** (a support agent finding a caller by any of their
+  addresses); the team **explicitly rejected** CC/BCC-ing every address onto TogaDesk tickets, so
+  multi-recipient notification is out of scope. Settled in the 2026-05-01 meeting: "it's just for
+  visual, this is for verification, it's a string."
+- **A wrong-shaped nested collection on intake returns HTTP 201 and silently drops the data.**
+  Both a flat/unknown key (a literal `UserDefined3`) and an array of bare strings
+  (`"contactEmailAddresses": ["a@b.com"]` instead of `[{"emailAddress": "a@b.com"}]`) are accepted
+  with **no error anywhere**. When verifying AIG's multi-email feed, assert **actual
+  `Client_Aig.ContactEmailAddresses` row counts** — never the HTTP status. See
+  [api2 nested-relationship writes](../../../2.0/apps/api2/features/nested-relationship-writes.md).
 - **A sale-item code missing from `Client_Aig.Items` currently produces an HTTP 500, not a clean
   "Missing AIG item ID."** In prod (TRUE-79534) a valid-but-unknown code made `$itemId` empty and
   the downstream fulfillment query threw MySQL ERROR 1064 — so the request 500'd and the contract
@@ -275,6 +306,15 @@ this interceptor or use this dual-purpose Items pattern.
 
 ## Change history
 
+- 2026-08-03 — Review-only session (no code changed). **Business Unit (`UserDefined2`) is answered
+  and dropped**: AIG (2026-05-04) needs nothing returned — it is theirs, from the sale, for **sales**
+  invoicing (not claims invoicing); we asked them to omit it from the API call and **no invoice-file
+  template was needed**. Verified `c_businessUnit` exists nowhere in `_underscore`/`api2`/`dbchanges2`,
+  so there is no dead field to clean up; the mapping spreadsheet's `UserDefined2` target column is
+  empty. This — not the extra emails — was what blocked Paulina from sending the mapping document.
+  Also recorded that `postPost`'s **single-recipient** registration email is **correct by design**
+  (TRUE-79401 is verification/lookup only; multi-recipient CC/BCC was explicitly rejected), and the
+  201-with-dropped-data trap when verifying the nested `contactEmailAddresses` feed. (mhammontree)
 - 2026-07-29 — TRUE-80179 / TRUE-79534 (**RESOLVED + correction**): the `STS_001` intake gap is
   **closed and it self-healed.** After the catalog load + collation fix shipped, AIG's next
   scheduled batch delivered all **156** outstanding `STS_001` contracts and every one succeeded

package/package.json

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