toga-ai 1.0.427 → 1.0.429

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-21
+updated: 2026-07-23
 owners: ["jcardinal", "mhammontree", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -56,6 +56,13 @@ writable). Without it the field is rejected on write **and** is unreadable:
 - **`AclFieldPermissions` is `UNIQUE (recordFieldId, roleId)`** (Client blank DDL) — guard inserts
   with `NOT EXISTS`. For a **read-only, server-written** field (one populated by a `postPost`
   interceptor rather than the API caller), grant `isWritable = 0`.
+- **A read-only field only needs a grant on the role(s) that actually READ it — find that role by
+  mirroring a sibling field of the same kind the readers already consume**, rather than blanket-granting
+  every role. E.g. the standard FK `serviceAddressId` mirrored its sibling FK `saleItemId`, whose sole
+  reader in `Client_Rate` is **role 1** (the toga2-view service cards) — so a single role-1 read grant
+  sufficed, NOT a 1/2/4 fan-out (a cross-role probe had shown roles 1/2/4 all lacked the grant, but only
+  role 1 actually reads the field). Grant `isWritable = 0` for a server-written field; resolve the role
+  by name/subselect (ids differ per client DB). Beta-proven on Rate `Client_Rate` 2026-07-23.
 
 ### Standard field vs. custom (`c_`) field — TWO different permission tables
 
@@ -199,6 +206,11 @@ the field.
 
 ## Change history
 
+- **2026-07-23** — TRUE-79533: noted that a **read-only field only needs a grant on the role(s) that
+  actually read it** — mirror a sibling field of the same kind the readers already consume rather than
+  granting every role. The standard FK `serviceAddressId` mirrored `saleItemId`'s reader, **role 1** in
+  `Client_Rate` (the toga2-view service cards), so a single role-1 read grant sufficed (not a 1/2/4
+  fan-out). (tcox)
 - **2026-07-23** — TRUE-79533: documented the **READ side** of `AclFieldPermissions` — a registered
   field with no grant returns **`EZ-2`** on read (the counterpart of the write code `EV-9`), and
   the **standard vs. custom** split: standard fields use `AclFieldPermissions` (keyed by

package/knowledge/2.0/apps/toga2-view/features/query-string-builder.md

@@ -60,5 +60,3 @@ easy to misread as an API problem.
   values to `String` before `urlEncode` — a numeric value (first hit via `fetchAddressesByIds`)
   threw `input.replace is not a function` and silently aborted the request client-side. Added
   regression tests. (tcox)
-</content>
-</invoke>

package/knowledge/2.0/apps/toga2-view/features/zip-validation-contact-phone.md

@@ -46,4 +46,3 @@ the store when it changed.
   field (a different covered property can have a different contact number). Previously the field
   was disabled once the store held a phone, and the post-purchase save made the first purchase lock
   it for every later visit. `save-if-different` retained. (tcox)
-</content>

package/knowledge/clients/nycdoe/features/servicenow-integration.md

@@ -6,7 +6,7 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-07-09
+updated: 2026-07-23
 owners: [mhammontree, sking]
 files:
   - worker/crons/sync/nycdoe/import_asn.php
@@ -248,6 +248,45 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
   164785 (internalId 6971859 → `38S0500` synced, 15 ROs) and PO 165751 (`50M7280` + `A3L980`
   NOT synced). PRs: library#831 (merge first) then worker#1670.
 
+- **⚠ REGRESSION of the 2026-07-09 multi-PO fix — a cross-wired SO/PO stamp silently drops
+  install tickets (diagnosed 2026-07-23; deferred to a one-off backfill, cron NOT changed).**
+  The 2026-07-09 fix (library#831 + worker#1670) made Stage 5 resolve item receipts **only**
+  Sales-Order-wide via `App_NetSuite::listItemReceiptsCreatedFromSalesOrder($soId)` (which fans
+  across the POs from `listPurchaseOrdersCreatedFromSalesOrder($soId)`). It **replaced** —
+  rather than augmented — the old by-stamped-PO lookup (`listItemReceiptsCreateFromPurchaseOrder`).
+  So when an ASN item's stamped `netSuiteInternalPurchaseOrderId` is **not a child of** its
+  stamped `netSuiteInternalSalesOrderId`, the SO-wide fan-out never inspects the stamped PO,
+  finds zero receipts, and the cron **silently creates no repair order and raises no error** —
+  the same "serials never sync, no error" symptom as the bug it replaced, in a distinct case.
+  - **Fingerprint:** an item stamped an SO whose only child PO has no receipt, while the stamped
+    PO (often an internalId *lower* than the SO's, i.e. created earlier) carries the real receipt
+    with the matching serials.
+  - **Root cause of the cross-wired stamp (SME Skyler King confirmed) = a warehouse
+    manual-entry error, not automation.** Confirmed case ASN **26215** (customer PO
+    `S202641365`): original SO `6901611` processed only `DOE-30HSS1BB00` (qty 1), PO `6901612`,
+    item receipt `6910404` (ticketed fine, RO 811791). Two monitors `DOE-62C5GAR1US` (serial
+    `VKWD9092`) and `DOE-64B6MAR1UZ` (serial `V600F9M6`) were **manually** added to SO `6901611`
+    with a **manually** created PO `6910401`, received on item receipt `6910410`. Separately,
+    when the real ASN arrived, the automation created a **duplicate** SO `6996287` (auto-PO
+    `6996288`, never used to receive — the serials were already on `6910410`). Net: ASN items
+    53905/53914 ended stamped SO=`6996287` (the duplicate) but PO=`6910401` (the manual PO under
+    the *original* SO), so SO-wide resolution finds nothing.
+  - **SME-confirmed correct end-state:** the units belong to the **original** SO (`6901611`);
+    the automation-created duplicate SO `6996287` / PO `6996288` is a NetSuite cleanup item
+    (cancel). The owed installs (one repair order per received unit) are **independent** of the
+    NetSuite duplicate and are created **TOGa Desk-side only**. Warehouse process has since been
+    corrected by training.
+  - **Recovery (chosen fix — one-off, not a cron change):** a run-once backfill reuses
+    `doeCreateInstallationRepairOrder` verbatim from Stage 5 (`3_create_installation_ticket.php`)
+    but scoped to a single ASN (id via CLI arg), resolving receipts from the **UNION** of the
+    SO's child POs *and* the item's stamped PO. It is idempotent (only units with
+    `togadeskRepairOrderId IS NULL`), guards double dispatch (skips a serial that already has a
+    `repair_order` in `db_togadesk`), never adds new `AdvanceShippingNoticeUnits`, is
+    serialized-only, and makes no NetSuite/ServiceNow writes. Confirmed on ASN 26215 (created the
+    two owed ROs). A **permanent union fix in the cron** (resolve receipts from SO child POs plus
+    the stamped PO) was considered but **deferred** — the team chose the one-off because the
+    warehouse process error is now prevented by training.
+
 ## Debugging & DB topology (DOE 1.0 sync)
 
 Reference for future DOE investigations — the 1.0 worker cannot run on a dev/Windows box;
@@ -265,6 +304,14 @@ use the toga DB MCP + `Logs.API` instead of running prod code locally.
   6971859 returned `totalRecords=1`, only `38S0500`.)
 - **`Bridge_NetSuite`** (legacy) has `SalesOrders` / `SalesOrderItems` / `SerialNumbers` but
   **no `PurchaseOrders` table** — POs are pulled live from the NetSuite API.
+- **Stuck-vs-received check, per ASN item:** compare
+  `listItemReceiptsCreatedFromSalesOrder($stampedSO)` against
+  `listItemReceiptsCreateFromPurchaseOrder($stampedPO)`, dumping each receipt line's `itemName`
+  plus its `inventoryAssignment` serials. If the SO-wide call returns 0 but the stamped PO
+  returns the receipt with the matching serials, it is the cross-wired-stamp regression above.
+- **`App_Model_Core_AdvanceShippingNotice` does NOT map `dtCreatedInstallationTicket`** — its
+  `__get` throws "No field or quick query defined for key …". Read that column via **raw SQL**,
+  not the model.
 
 ## Operating rules when changing this integration
 
@@ -278,6 +325,17 @@ use the toga DB MCP + `Logs.API` instead of running prod code locally.
    of the consumer query; `php -l` every touched file.
 
 ## Change history
+- 2026-07-23 — Diagnosed a regression of the 2026-07-09 multi-PO fix: Stage 5's SO-wide receipt
+  resolution *replaced* the by-stamped-PO lookup, so a cross-wired stamp (an item's stamped PO
+  not a child of its stamped SO) silently drops install tickets with no error. Root cause of the
+  cross-wire = a warehouse manual-entry error (a duplicate SO was auto-created while the real
+  receipt sat under a manually-created PO on the original SO); SME Skyler King confirmed the
+  correct end-state (units on the original SO, duplicate SO cancelled, owed installs are TOGa
+  Desk-side only). Recovered stuck ASN 26215 with a one-off union-receipt backfill (union of SO
+  child POs + the stamped PO; idempotent; no NetSuite/ServiceNow writes) that created the two
+  owed ROs; a permanent union fix in the cron was considered but deferred (warehouse process now
+  corrected by training). Added a regression gotcha + two debugging notes. No production code
+  changed. (mhammontree; SME sking)
 - 2026-07-09 — Fixed silent install-ticket drop when a NetSuite SO is fulfilled across
   multiple POs: Stage 5 now resolves item receipts Sales-Order-wide via new helper
   `App_NetSuite::listItemReceiptsCreatedFromSalesOrder` (fans across all POs from the SO,

package/knowledge/clients/rate/features/aig-contract-creation.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: rate
 type: client-feature
 status: active
-updated: 2026-06-29
-owners: [mhammontree]
+updated: 2026-07-23
+owners: [mhammontree, tcox]
 files:
   - _underscore/Model/Rate/Entitlement.php
   - _underscore/ApiRequest.php
@@ -96,9 +96,21 @@ creation vs. cancellation. This is an accepted, documented limitation — not an
   address, so an entitlement with no address never even attempts contract creation (and
   never logs a `/contract` call).
 - **Auth-induced failures are blind to the monitor** — see the detection limitation above.
+- **The AIG-success branch REASSIGNS `$payload->uuid`** (`$payload->uuid = _String::generateUuid()`,
+  repurposed as the AIG contract number) — and it does so **in the same `postPost`** that pins the WH
+  service address. On the pre-redesign build the pin step ran **after** this reassignment and keyed
+  off `$payload->uuid`, so **every successful AIG contract silently broke the WH address pin** (the
+  pin lookup matched no row). Preserve the ordering fix — snapshot the entitlement uuid **before**
+  this branch. See the
+  [WH per-address purchase guard](whole-home-warranty-purchase-guard.md) "AIG-success clobbers the
+  pin" gotcha (`_underscore` `_beta` `9c2e4b1c`).
 
 ## Change history
 
+- 2026-07-23 — Documented that the **AIG-success branch reassigns `$payload->uuid`** (as the contract
+  number) inside the shared `postPost`, which silently broke the WH service-address pin on the
+  pre-redesign build (pin keyed off the now-reassigned uuid). Fixed by snapshotting the entitlement
+  uuid before the AIG branch (`_underscore` `_beta` `9c2e4b1c`). Cross-linked the WH guard doc. (tcox)
 - 2026-07-07 — `postPost` now also persists the validated service address
   (`Entitlements.c_serviceAddressId`, `Addresses.isValidated=1`), wrapped so it never blocks the
   AIG-contract/email flow; a new WH `prePost` guard carrier-normalizes the address onto the

package/knowledge/clients/rate/features/whole-home-warranty-purchase-guard.md

@@ -106,6 +106,10 @@ Ticket: TRUE-79533. Business rule owner: PM Paulina.
    `Addresses.isValidated = 1` and writes `Entitlements.serviceAddressId`. This block is
    wrapped so a failure never interrupts the AIG-contract creation or the confirmation email
    (see the [AIG contract creation doc](aig-contract-creation.md) — the same `postPost`).
+   **The entitlement UUID is snapshotted up front** (`$entitlementUuid = $payload->uuid`) at the
+   top of `postPost`, **before** the AIG branch runs — because the AIG-success branch reassigns
+   `$payload->uuid` (see the "AIG-success clobbers the pin" gotcha). The pin lookup must use the
+   snapshot, not `$payload->uuid`.
 6. All SQL uses `_Database::escape()` / int-casts — `_Query` has **no bind API** in this path.
 
 ## Field & model: `serviceAddressId` is now a STANDARD field (reviewer Jeff)
@@ -280,6 +284,22 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
 - **`ApiPayloadInterceptors` (Client_Rate) has no `phpMethod` column.** The interceptor method
   is resolved **by convention** from `(prePostProcessing, httpMethod)`: `PRE+POST → prePost`,
   `POST+POST → postPost` (matches the framework `[pre|post][HttpMethod]` convention).
+- **ROOT CAUSE of NULL pins on the pre-redesign build: the pin silently fails whenever the AIG
+  contract is created SUCCESSFULLY.** The old `postPost` pinned the entitlement by `$payload->uuid`,
+  but the **AIG-success branch reassigns `$payload->uuid = _String::generateUuid()`** (reusing it as
+  the AIG contract number) **before** the pin step. So on an AIG success the pin lookup by
+  `$payload->uuid` matches **no row**, logs `"TRUE-79533: could not resolve service address"`, and
+  gives up — leaving `Entitlements.serviceAddressId` (and, pre-redesign, `c_serviceAddressId`) NULL
+  and the purchase's `Addresses.isValidated` NULL (that pair is the fingerprint of a lost pin).
+  Pinning is therefore **intermittent — it works only when AIG auth FAILS** (the branch that
+  clobbers the uuid never runs). Proven on beta `Client_Rate` 2026-07-23: entitlement 68 pinned,
+  69/70/71 unpinned despite an intact Contact→`primaryContactAddressId`→ContactAddresses chain.
+  **Fixed in `_underscore` `_beta` commit `9c2e4b1c`**: `postPost` snapshots
+  `$entitlementUuid = $payload->uuid` up front, before the AIG branch, and pins by the snapshot.
+  **DEPLOY DEPENDENCY:** any environment still running a **pre-redesign** `api2`/`_underscore` build
+  loses the address pin every time AIG succeeds; the fix only takes effect on **EB redeploy**
+  (api2 pulls `_underscore` at deploy). This is the mechanism behind the COALESCE fallback and the
+  dangling-pin gotcha below — the fallback is what keeps the dedup correct while pins are missing.
 - **Dedup is defeated by a DANGLING pin (not just a NULL one).** The COALESCE fallback covers a
   **NULL** `serviceAddressId`, but if `serviceAddressId` points at a **deleted `Addresses` row**,
   the join drops that entitlement and it becomes **invisible to the guard** — a duplicate WH slips
@@ -324,6 +344,17 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
   (verified in `api2/Component/Api/V2/V2.php` `getAclFieldPermissions()` ~line 5731), which is why
   a custom→standard promotion must re-create the read grant as an `AclFieldPermissions` row.
   (mhammontree)
+- 2026-07-23 — **Root cause of intermittent NULL pins + guard hardening confirmed** (tcox). (1) The
+  `postPost` service-address pin **silently fails whenever the AIG contract creation SUCCEEDS**,
+  because the AIG-success branch reassigns `$payload->uuid` before the pin step, so pinning by
+  `$payload->uuid` matches no row (fingerprint: `serviceAddressId` + `Addresses.isValidated` both
+  NULL). Proven on beta (entitlement 68 pinned, 69/70/71 not). Fixed in `_underscore` `_beta`
+  `9c2e4b1c` (snapshot `$entitlementUuid` up front). Deploy-dependency: pins are lost on AIG success
+  on any pre-redesign build until EB redeploy. (2) The dedup blind spot (unpinned entitlements
+  invisible to `hasActiveWarrantyAtAddress` — demonstrated live: two active WH at "STE 250" slipped
+  through on the old build) is **CLOSED in `_beta` `a9f408bc`** — the dedup joins Addresses via
+  `COALESCE(serviceAddressId, ContactAddresses.addressId)`, disables the query cache for the read,
+  and documents an accepted TOCTOU. (tcox)
 - 2026-07-23 — **LAUNCH BLOCKER found: the standard `serviceAddressId` field has NO read ACL grant**
   (tcox). Probe-verified on beta: `GET /v2/entitlements?fields=serviceAddressId` → 403 `EZ-2` for
   roles 1/2/4 (`aclDatabase=CLIENT`). Standard fields are authorized via **`AclFieldPermissions`**

package/knowledge/clients/rate/profile.md

@@ -3,6 +3,7 @@ title: "Rate"
 framework: "2.0"
 apps:
   - _underscore
+  - api2
   - saml
   - toga2-view
   - worker
@@ -12,8 +13,8 @@ project: SAML SSO Gateway
 client: rate
 type: profile
 status: active
-updated: 2026-06-30
-owners: ["rgirish", "bala", "mhammontree"]
+updated: 2026-07-23
+owners: ["rgirish", "bala", "mhammontree", "tcox"]
 files: []
 related:
   - clients/rate/features/saml-sso.md

package/package.json

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