toga-ai 1.0.540 → 1.0.541

package/knowledge/2.0/apps/api2/features/request-logging.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
+updated: 2026-08-10
 owners: ["mhammontree", "dfranks"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -106,6 +106,28 @@ fact AIG **does** post live entitlements — the writes were **failing (HTTP 500
 core `Logs`**, not `Logs_Aig`. See
 [AIG entitlement intake → Intake is a live API feed](../../../../clients/aig/features/entitlement-intake.md).
 
+## Querying prod `Logs.Api` without timing out (narrow first, fetch payloads last)
+
+Prod `Logs.Api` is large enough that **any `LIKE` over `requestPayload` / `responsePayload`
+(both `mediumtext`) times out the `toga_query` MCP call at 300 s — even scoped to a single day.**
+There is no usable index on those columns. Do not start from a payload search.
+
+The working pattern, in order:
+
+1. **Narrow with indexed / non-text columns only** — a `dtStamp` range plus `route`,
+   `method`, `responseCode`, `hostname`. A
+   `GROUP BY hostname, route, method, responseCode` over one day is cheap and is the fastest way
+   to spot a failing route (this is what surfaced the AIG entitlement 500s).
+2. **Collect the `id`s** from that narrowed set.
+3. **Then fetch payloads by `id`**, a few rows at a time, using `LEFT(...)` / `SUBSTRING(...)`
+   rather than selecting the whole `mediumtext`.
+
+Volume reference for sizing a query: **~8,151 rows in `Logs.Api` for a single day** (2026-05-27).
+
+Note this is in tension with the payload-based techniques in the next section — the
+`JSON_EXTRACT` dedupe/vendor-split works because it runs over an **already-narrowed** row set
+(one route, one response code, one date range), not over the raw table.
+
 ## Recovering an intake backlog from logged payloads
 
 Because the core/writer `Logs.Api` stores **every** inbound request — including failed writes —
@@ -134,6 +156,11 @@ re-send.
 
 ## Change history
 
+- 2026-08-10 — Added **Querying prod `Logs.Api` without timing out**: any `LIKE` over the
+  `mediumtext` `requestPayload`/`responsePayload` times out the `toga_query` MCP call at 300 s even
+  for one day. Narrow first on indexed/non-text columns (`dtStamp` + `route` + `responseCode`, or a
+  `GROUP BY hostname, route, method, responseCode` to spot the failing route), collect `id`s, then
+  fetch payloads by `id` with `LEFT()`/`SUBSTRING()`. Volume reference ~8,151 rows/day. (mhammontree)
 - 2026-08-04 — Added the limit of the commit-logs contract: an **uncaught PHP fatal** (a
   `Call to undefined method` from an interceptor dispatch) produced **zero rows in
   `Logs_Compass.Api`** — no 5xx row for the whole day and no row for the failing request — while

package/knowledge/clients/aig/INDEX.md

@@ -3,5 +3,5 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [AIG Contract Reconciliation & Dealer Programs (STS_001 / SA_001)](features/contract-reconciliation.md) | 2.0 | How to reconcile an **AIG contract sales sheet** against the `Client_Aig` tenant, and the durable finding that the **Staples Advantage.com (`SA_001`) program do | _underscore/Model/Client/Entitlement.php, _underscore/Model/Aig/Entitlement.php, _underscore/Model/Client/Contact.php, _underscore/Model/Aig/Contact.php |
-| [AIG Entitlement Intake & SaleItem Code Resolution](features/entitlement-intake.md) | 2.0 | The `_Model_Aig_Entitlement::prePost` interceptor below is the code path for AIG protection-plan entitlements arriving as `api2` V2 JSON POSTs — and that path * | _underscore/Model/Aig/Entitlement.php, dbchanges2/Client_Aig/2026-06-18a - TRUE-79534 AIG SaleItem codes.sql |
+| [AIG Entitlement Intake & SaleItem Code Resolution](features/entitlement-intake.md) | 2.0 | The `_Model_Aig_Entitlement::prePost` interceptor below is the code path for AIG protection-plan entitlements arriving as `api2` V2 JSON POSTs — and that path * | _underscore/Model/Aig/Entitlement.php, api2/Component/Api/V2/V2.php, dbchanges2/Client_Aig/2026-06-18a - TRUE-79534 AIG SaleItem codes.sql |
 | [AIG (Staples Protection Plan)](profile.md) | 2.0 | AIG is the warranty underwriter behind the **Staples Protection Plan** retail program. |  |

package/knowledge/clients/aig/features/contract-reconciliation.md

@@ -5,7 +5,7 @@ project: API
 client: aig
 type: client-feature
 status: active
-updated: 2026-07-29
+updated: 2026-08-10
 owners: ["mhammontree"]
 files:
   - _underscore/Model/Client/Entitlement.php
@@ -27,7 +27,7 @@ durable finding that the **Staples Advantage.com (`SA_001`) program does not rou
 | DealerId | Program | Status |
 |---|---|---|
 | `STS_001` | **Staples Technology Solutions** | live api2 feed; intake gap **RESOLVED 2026-07-29** (self-healed) |
-| `SA_001` | **Staples Advantage.com** | **never reaches api2** — separate feed; scope decision is the one open item |
+| `SA_001` | **Staples Advantage.com** | **never reaches api2** — SA.com is not sending them; **AIG owns and is working it**, not a TOGa defect (2026-08-10) |
 
 `STS_001` arrives as a **live API feed**; its 156-contract gap from the now-fixed intake bug
 **self-healed** (the feed re-sent and all 156 succeeded — see below). `SA_001` never reaches our
@@ -106,6 +106,28 @@ because their `SA_001` contract was never ingested.
 into `Client_Aig`, and if so via what feed/integration? That is a scope/integration decision for
 AIG / the team — not a back-fill of a dropped load. Until decided, `SA_001` stays out-of-pipeline.
 
+#### CLOSED (2026-08-10): missing `SA_001` entitlements are AIG's issue, not a TOGa defect
+
+**SA.com is not sending the new entitlements to us. AIG owns this and is working it.** Stop
+working "missing SA_001 entitlement" escalations as a TOGa bug — the correct response is to route
+them to AIG.
+
+Confirmed on a concrete case from AIG's own Warranty Administration Portal: contract
+**CN 1000046237886 / CCN 7680760752-2** (Staples Advantage.com program, plan *"2YR Printer Onsite
+Next Day: ($500-$999.99)"*, purchased 2026-05-27) exists in AIG's portal and is **completely absent
+on our side**:
+
+- zero rows in `Client_Aig.Entitlements` — searched by `number`, `vendorEntitlementNumber`,
+  `datePurchase`, **and** contract-holder name;
+- zero rows in `Client_Aig.Contacts`;
+- **zero trace in `Logs_Aig.Api` or the core/writer `Logs.Api`.**
+
+No log row anywhere means the contract was **never delivered** — nothing was rejected, nothing was
+partially created, and there is no dropped payload to replay. That is the distinguishing signal:
+a TOGa-side intake defect always leaves a failed-write row in the core `Logs` (see
+[request logging](../../../2.0/apps/api2/features/request-logging.md)); **total absence points
+upstream.**
+
 ## How to load a missing program / sheet (back-fill)
 
 If `SA_001` is ever confirmed in-scope for `Client_Aig` and AIG cannot route it through api2, it
@@ -118,6 +140,13 @@ feed re-send over a manual load whenever the contracts do reach api2.
 
 ## Change history
 
+- 2026-08-10 — Read-only prod investigation. **Closed the `SA_001` question as NOT a TOGa defect:**
+  SA.com is not sending the entitlements; **AIG owns and is working it.** Evidenced by portal
+  contract CN 1000046237886 / CCN 7680760752-2 (purchased 2026-05-27) being absent from
+  `Client_Aig.Entitlements` *and* `Contacts` *and* from both `Logs_Aig.Api` and core `Logs.Api` —
+  never delivered, so nothing was rejected or partially created. Recorded the general
+  discriminator: an intake defect leaves a failed-write row in core `Logs`; **total log absence
+  points upstream.** Future "missing SA_001 entitlement" escalations route to AIG. (mhammontree)
 - 2026-07-29 — TRUE-80179 / TRUE-79534: **156 active `STS_001` RESOLVED (self-healed).** The next
   scheduled batch re-sent all 156 outstanding contracts and every one succeeded (201 × 156, zero
   failures; `Client_Aig.Entitlements` +156) — no manual back-fill needed, because the feed re-sends

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

@@ -5,10 +5,11 @@ project: API
 client: aig
 type: client-feature
 status: active
-updated: 2026-08-03
+updated: 2026-08-10
 owners: ["mhammontree"]
 files:
   - _underscore/Model/Aig/Entitlement.php
+  - api2/Component/Api/V2/V2.php
   - dbchanges2/Client_Aig/2026-06-18a - TRUE-79534 AIG SaleItem codes.sql
 related:
   - clients/aig/features/contract-reconciliation.md
@@ -122,6 +123,32 @@ 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)).
 
+## Verified prod state (2026-08-10) — the catalog IS loaded; do NOT re-diagnose as "missing item ID"
+
+Re-verified read-only against prod. **The TRUE-79534 catalog load did run and is present**, so a
+1064/500 seen from here on is **not** the missing-catalog problem:
+
+- **`Client_Aig.Items` = 2,212 rows** — 1,110 `ASI-*`, 558 `SM-*`, 37 legacy `SP-*`.
+- The exact part number in the historically-failing payloads, **`ASI-2YG2`, IS present.**
+- **`Client_Aig.Entitlements` = 621 rows**, latest `dtCreated` **2026-08-04**, latest
+  `datePurchase` **2026-07-31** — entitlements are still being created.
+
+So the remaining exposure at `Entitlement.php:48` is the **input-empty** variant (an *empty*
+`itemId` interpolated), not an unknown-code variant. Anyone re-opening this should read the actual
+interpolated value before assuming a missing AIG item ID — the earlier ticket already ruled that
+out.
+
+**Open question (not answered this session):** the historical failure window in the core/writer
+`Logs.Api` shows **exactly 1,200 `POST /v2/entitlements` requests per day, all HTTP 500, zero
+successes on that route**, every day from at least **2026-05-20 through 2026-07-28**, with the
+*same* stale batch replayed daily — log id 996641 (05-27) and id 1877726 (07-28) carry
+**byte-identical** payloads (`number: 1000045980287`), as do ids 998804 / 1881349
+(`number: 1000045972141`). No entitlement POSTs are logged in core `Logs` after 07-28. Because
+**successful** writes log to `Logs_Aig`, not core `Logs`, the most likely reading is that the route
+recovered on 07-29 exactly as the resolution above describes. But the creating path for the newest
+rows (through 2026-08-04) was **not positively identified** — confirm it in `Logs_Aig.Api` before
+asserting either "intake is entirely down" or "intake is healthy."
+
 ## Business Unit (`UserDefined2`) — answered and DROPPED (nothing to build)
 
 AIG (Alissa, 2026-05-04) confirmed the **Business Unit / Value** field needs **nothing returned to
@@ -294,7 +321,17 @@ this interceptor or use this dual-purpose Items pattern.
   `Apis_RecordFields` override row that stripped `name` as an identifier — see
   [api2 nested-relationship writes → Per-API overrides](../../../2.0/apps/api2/features/nested-relationship-writes.md).
 - **A lookup miss yields an empty `$itemId` that crashes the next query (confirmed in prod,
-  TRUE-79534).** When `saleItem.partNumber` is **valid but absent** from `Client_Aig.Items`, the
+  TRUE-79534).** The unguarded line is **`_underscore/Model/Aig/Entitlement.php:48`** in `prePost`,
+  reached from **`api2/Component/Api/V2/V2.php:2601`**. The malformed statement it emits is:
+  ```sql
+  SELECT EntitlementFulfillmentTypes.name
+  FROM Items_EntitlementFulfillmentTypes
+  INNER JOIN EntitlementFulfillmentTypes ON ...
+  WHERE Items_EntitlementFulfillmentTypes.itemId =      -- nothing after the '='
+  ```
+  → MySQL **ERROR 1064** → HTTP 500. The fix is a **guard clause / early return** on an
+  empty-or-failed lookup *before* this query runs. When `saleItem.partNumber` is
+  **valid but absent** from `Client_Aig.Items`, the
   `SELECT id … WHERE partNumber = '{$partNumber}' LIMIT 1` returns nothing → `$itemId` is empty →
   the **fulfillment query interpolates it unquoted** → `WHERE …itemId = ` → **ERROR 1064** → HTTP
   500 (the mechanism behind the whole intake outage). A separate **input-empty** variant also
@@ -320,6 +357,16 @@ this interceptor or use this dual-purpose Items pattern.
 
 ## Change history
 
+- 2026-08-10 — Read-only prod investigation (no code/SQL changed). Added **Verified prod state**:
+  the TRUE-79534 catalog **is** loaded (`Client_Aig.Items` = 2,212 rows — 1,110 `ASI-*` / 558
+  `SM-*` / 37 `SP-*`; `ASI-2YG2` present), so a future 1064 here is the **empty-input** variant,
+  **not** a missing AIG item ID — do not re-diagnose it as TRUE-79534. Pinned the unguarded lookup
+  to **`_underscore/Model/Aig/Entitlement.php:48`** (from `api2/Component/Api/V2/V2.php:2601`) and
+  recorded the exact malformed fulfillment query, so the fix is a plain guard clause. Quantified
+  the historical outage from core `Logs.Api` (**1,200 × HTTP 500/day, zero successes on the route,
+  2026-05-20 → 2026-07-28**, the same batch replayed byte-identically — corroborates the
+  scheduled-re-send model). Flagged the **open question**: 621 entitlements exist with `dtCreated`
+  up to 2026-08-04 and the creating path was not positively identified. (mhammontree)
 - 2026-08-03 (later pass) — **Two corrections.** (1) The `ERROR 1267` temp-table collation trap is a
   **per-machine server-config property, not a "prod-only" / version difference**: measured prod Core
   8.0.39 with the MySQL 8 default `utf8mb4_0900_ai_ci` vs local Core_2 8.0.44 with an explicit

package/package.json

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