toga-ai 1.0.144 → 1.0.146

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

@@ -6,8 +6,8 @@ project: Database Changes
 client: shared
 type: architecture
 status: active
-updated: 2026-06-12
-owners: [jcardinal]
+updated: 2026-06-19
+owners: [jcardinal, mhammontree]
 files:
   - Core/
   - Client/
@@ -141,6 +141,36 @@ file inside `HISTORIC` running; **never** add new changes there.
 5. Never edit or re-date an already-applied file — add a new dated file instead. Never put new
    work in a `HISTORIC` folder.
 
+## Bulk data loads — one statement, not many
+
+When a change inserts many rows (reference-data / code-table loads), write it as a **single
+bulk `INSERT`**, not one `INSERT` statement per row. The database is billed per query and the
+external executor runs each statement as its own round-trip, so N separate inserts cost N times
+the round-trips (and query cost) of one batched statement. This is a standing team preference.
+
+- Use one `INSERT ... VALUES (...),(...),...` or `INSERT ... SELECT` over a derived
+  (`UNION ALL`) row set.
+- To stay **idempotent** without a unique key to `INSERT IGNORE` against, anti-join the source
+  set to the target and insert only the misses:
+
+```sql
+INSERT INTO TargetTable (uuid, keyColumn, otherColumn)
+SELECT
+	src.uuid,
+	src.keyColumn,
+	src.otherColumn
+FROM (
+	SELECT '<uuid>' AS uuid, '<key>' AS keyColumn, '<value>' AS otherColumn
+	UNION ALL SELECT ...
+) AS src
+LEFT JOIN TargetTable existing ON existing.keyColumn = src.keyColumn
+WHERE
+	existing.id IS NULL;
+```
+
+- Keep the single statement well under `max_allowed_packet` (64 MB default) — a few thousand
+  rows is comfortably fine.
+
 ## Relationship to the rest of 2.0
 
 `dbchanges2` is registered as a **2.0 core repo** (`role: core` in `registry.json`) — it is

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-08
-owners: [jcardinal]
+updated: 2026-06-18
+owners: [jcardinal, dfranks]
 files:
   - worker2/Worker/
   - worker2/Controller/Index.php
@@ -126,6 +126,31 @@ curl -X POST https://worker.togahub.com/ \
 
 Use realistic placeholder values, not empty strings/nulls.
 
+## How exceptions & retries work
+
+The EB worker dispatcher (`Controller/Index.php::worker()`) wraps your action call in
+`try { } catch (\Throwable $e)`:
+- **Returns normally** → `WorkerJobs.isSuccess = 1`, `dtCompleted` set.
+- **Throws** (any `Throwable`, incl. `Error`) → `isSuccess = 0`, `failureReason` = message +
+  `file:line` + full stack trace. (Two earlier phases — DB-logs registration and `initialize()` —
+  fail the same way.)
+
+Crucially, the worker **always returns HTTP 200, even on a throw**, so SQS deletes the message
+immediately. **There is no DLQ and no automatic retry.** A throw makes the failure *visible* (a
+failed `WorkerJobs` row to alert on) — it does **not** re-run the job.
+
+So **do not design "throw so it retries" — it won't.** To actually retry / self-heal:
+- **Re-enqueue** with `_Worker::runTask('Category/Action/Method', [...])` — inserts a fresh
+  `WorkerJobs` row + SQS message, so it genuinely re-runs. Carry your own **attempt counter** in the
+  parameters to bound it.
+- Or **in-process retry** *within* the method (it's a background worker with a 3600s visibility
+  budget — a bounded sleep+retry loop is fine here, unlike a request handler).
+- Or **manual** `_Worker_Infrastructure_Worker::Retry($id)` / the reset-fields SQL, or a periodic
+  reconcile cron as a backstop.
+
+Rule of thumb: `throw` to surface a genuine failure; `runTask`/in-process loop when the work should
+be reattempted.
+
 ## Gotchas
 
 - Class must be **`abstract`** and methods **`public static`** or routing fails.
@@ -135,4 +160,8 @@ Use realistic placeholder values, not empty strings/nulls.
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-06-18 — Documented worker-action **exception/retry semantics**: dispatcher catches `Throwable` →
+  `isSuccess=0`+`failureReason`, **always HTTP 200, no DLQ, no auto-retry**; throwing surfaces a failure
+  but does not re-run — retry via `_Worker::runTask` re-enqueue (attempt-counter), in-process loop, or
+  manual `Retry()`. (dfranks)
 - 2026-06-08 — Documented the worker-action contract (path→class/method convention, parameter typing, webhook/cron templates); replaces the former `/worker2-action` skill. (jcardinal)

package/knowledge/2.0/apps/worker2/features/netsuite-opportunity-sync.md

@@ -147,6 +147,17 @@ Shared helpers: `buildCustomFields()` (the field array, used by both create and
   it on the payload; the new contract drops it).
 - Every ClickUp `_ApiRequest` calls `setLogging(self::CLICKUP_API_LOGGING_ENABLED=false)`, so ClickUp
   traffic is not written to the Logs DB.
+- **Two `_Component_Api_Netsuite` classes exist — edit the right one.** worker2 calls the **global**
+  `_Component_Api_Netsuite`, autoloaded from `_underscore/Component/Api/Netsuite/Netsuite.php`; `api2`
+  ships a *separate* `namespace api` copy (`\api\_Component_Api_Netsuite`) for its own use. Editing the
+  api2 copy has **no effect** on the worker2 webhook integration — change the `_underscore` one.
+- **NetSuite REST calls are NOT logged to `Logs.Api`.** `_Component_Api_Netsuite::send()` calls
+  `setLogging(false)`, so unlike platform traffic and ClickUp/Freshservice/Sentry (which land in the
+  logs-cluster `Logs.Api` with full request + `responsePayload`), NetSuite request/response bodies are
+  not captured — you can't pull a historical NetSuite response for debugging. That cost us the response
+  bodies when diagnosing the [open-orders read-after-write lag](./netsuite-salesorder-open-orders-sync.md);
+  removing that `setLogging(false)` is under review (handle the 20–50 KB payload volume the
+  prod-appropriate way — retention/sampling/summary — not by defaulting logging off).
 
 ## Data model
 
@@ -306,6 +317,11 @@ same **skip-if-unchanged** compare on the extracted values, and **actor-identity
 trigger a CU→NS write. The NS→CU change-detection above is the complementary backstop, not a substitute.
 
 ## Change history
+- 2026-06-18 — Documented two NetSuite-client gotchas: **two `_Component_Api_Netsuite` copies** (worker2
+  uses the global `_underscore` one; api2 has a separate `namespace api` copy — edit the right one), and
+  `send()`'s `setLogging(false)` means **NetSuite calls aren't logged to `Logs.Api`** (no historical
+  response bodies; removal under review). Also dropped the debunked dev-laptop rationale from the
+  ClickUp-logging note. (dfranks)
 - 2026-06-18 — **Diagnosed the live opportunity-import gap as a deployment misconfig + characterized the
   AMQ burst behavior.** The Opportunity `ue_amq_enqueue` deployment was `Released` but with an **empty
   audience** (~4:41–5:39 pm) so it enqueued nothing; missing opps had no queue row and no worker2 job

package/knowledge/INDEX.md

@@ -34,6 +34,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## Clients
 
+- **AIG (Staples Protection Plan)** (`aig`) → [clients/aig/INDEX.md](clients/aig/INDEX.md)
 - **Compass Canada** (`compass-canada`) → [clients/compass-canada/INDEX.md](clients/compass-canada/INDEX.md)
 - **Compass USA** (`compass-usa`) → [clients/compass-usa/INDEX.md](clients/compass-usa/INDEX.md)
 - **Elite** (`elite`) → [clients/elite/INDEX.md](clients/elite/INDEX.md)

package/knowledge/clients/aig/INDEX.md

@@ -0,0 +1,6 @@
+# Client: AIG (Staples Protection Plan) `aig`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [AIG Entitlement Intake & SaleItem Code Resolution](features/entitlement-intake.md) | 2.0 | AIG protection-plan entitlements arrive as `api2` V2 JSON POSTs. | _underscore/Model/Aig/Entitlement.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/entitlement-intake.md

@@ -0,0 +1,131 @@
+---
+title: AIG Entitlement Intake & SaleItem Code Resolution
+framework: "2.0"
+project: API
+client: aig
+type: client-feature
+status: active
+updated: 2026-06-19
+owners: ["mhammontree"]
+files:
+  - _underscore/Model/Aig/Entitlement.php
+  - dbchanges2/Client_Aig/2026-06-18a - TRUE-79534 AIG SaleItem codes.sql
+related:
+  - 2.0/apps/api2/architecture.md
+  - 2.0/apps/dbchanges2/architecture.md
+  - 2.0/apps/_underscore/architecture.md
+---
+
+## Summary
+
+AIG protection-plan entitlements arrive as `api2` V2 JSON POSTs. Before the entitlement is
+written, the `_Model_Aig_Entitlement::prePost` interceptor resolves the **sold warranty SKU**
+(`saleItem.partNumber`) against `Client_Aig.Items` to set the `Entitlement.saleItemId` foreign
+key and to attach fulfillment types/methods. If that part number has no matching `Items` row,
+the FK can't resolve and intake fails with **"Missing AIG item ID."** Keeping
+`Client_Aig.Items` populated with AIG's current sale-item catalog is what keeps intake working.
+
+## Key files / entry points
+
+- **`_underscore/Model/Aig/Entitlement.php`** — `prePost(&$api, &$payload)` is the PRE-POST
+  API payload interceptor (named by the `prePost*` convention) that runs on entitlement intake.
+- **`Client_Aig.Items`** — the catalog the interceptor looks up against (`partNumber` column).
+- **`dbchanges2/Client_Aig/…`** — where new code batches are loaded (see *Uploading new codes*).
+
+## How it works
+
+1. AIG POSTs an entitlement payload (vendor `STS_001`) to the `api2` V2 API.
+2. `_Model_Aig_Entitlement::prePost` runs and:
+   - cleans a duplicated-firstName-in-lastName quirk on `contact`;
+   - if `payload->item` (the covered **device/unit**) has a `description` but no `itemCategory`,
+     sets `itemCategory.name = item.description`;
+   - reads `partNumber = payload->saleItem->partNumber` and runs
+     `SELECT id FROM Items WHERE partNumber = '{partNumber}' LIMIT 1` to get `$itemId`;
+   - uses `$itemId` to load fulfillment **types** (`Items_EntitlementFulfillmentTypes`) and
+     **methods** (`Items_EntitlementFulfillmentMethods`) and injects them into the payload.
+3. The V2 engine resolves `Entitlement.saleItemId` (FK → `_Model_Client_Item`) from that same
+   `saleItem.partNumber`. **No matching `Items` row → unresolvable FK → "Missing AIG item ID".**
+4. `postPost` then emails the contact a Staples Protection Plan registration link
+   (`staplesprotection.togaview.com`).
+
+## Data model
+
+`Client_Aig.Items` is **dual-purpose** — it holds two different kinds of row, distinguished by
+whether `itemCategoryId` is set:
+
+| Row kind | Example `partNumber` | `description` | `itemCategoryId` |
+|---|---|---|---|
+| **Sale item** (warranty SKU) | `ASI-2YG2`, `SP-2D-TAB3` | price-band plan, e.g. `2YR Product under $500: ($30-$49.99)` | **NULL** |
+| **Unit/device item** | `157C`, `1159`, `5022` | device type, e.g. `Chromebook`, `Printer Inkjet` | set → `ItemCategories` |
+
+- `Client_Aig.ItemCategories` is a **device-classification** table (`Laptop`, `Printer`,
+  `Tablet`) — it classifies the physical hardware (unit items), **not** the warranty sale
+  items. Sale items correctly carry `itemCategoryId = NULL`; do not try to assign them a
+  category (the price-band plan descriptions don't map to a device type).
+- `ItemCategories.c_premiumTechSupportCategory` (enum `PC`/`Tablet`) is read by the AIG
+  ClosedClaims → NetSuite invoicing sync.
+
+### SaleItem code schemes
+
+AIG migrated their sale-item coding. The catalog spans:
+- **Legacy `SP-*`** — the original scheme (only a handful seeded historically).
+- **New `ASI-*` / `SM-*`** — current STS_001 (Staples) scheme; the bulk of the catalog.
+- **Numeric `SA` codes** (8-digit, e.g. `24664377`) — a separate program sheet in AIG's
+  spreadsheet, distinct part-number space (no collisions with the STS codes).
+
+## Uploading new codes (the recurring task)
+
+When AIG sends a new "Active SaleItemID" spreadsheet (columns `SaleItemID`, `Description`):
+
+1. Load it into `Client_Aig.Items` via a **`dbchanges2/Client_Aig/`** migration (dated
+   `YYYY-MM-DD<letter>` per the dbchanges2 contract).
+2. Insert minimally `uuid`, `partNumber`, `description` — everything else (`isActive`,
+   `isVisible`, `inventoryType=HYBRID`, timestamps) takes table defaults; **leave
+   `itemCategoryId` NULL** for sale items.
+3. Generate **fully-random UUIDs** (e.g. `uuid4`), never the time-based MySQL `UUID()` —
+   per the 2.0 standard. Bake literal UUIDs into the SQL since a migration can't call PHP's
+   `_String::generateUuid()`.
+4. Use a **single bulk `INSERT`** (see the dbchanges2 architecture rule), made idempotent with
+   an anti-join because `Items` has **no unique key on `partNumber`** (so `INSERT IGNORE`
+   can't help):
+   ```sql
+   INSERT INTO Items (uuid, partNumber, description)
+   SELECT src.uuid, src.partNumber, src.description
+   FROM ( SELECT '<uuid>' AS uuid, '<part>' AS partNumber, '<desc>' AS description
+          UNION ALL SELECT ... ) AS src
+   LEFT JOIN Items existing ON existing.partNumber = src.partNumber
+   WHERE existing.id IS NULL;
+   ```
+
+## Client variations
+
+This is AIG-specific behavior (the `_Model_Aig_Entitlement` override); other clients do not run
+this interceptor or use this dual-purpose Items pattern.
+
+## Gotchas / known issues
+
+- **"Missing AIG item ID" = the sale-item code isn't in `Client_Aig.Items`.** This is the
+  classic symptom of AIG shipping new codes before the catalog is loaded. Fix = load the codes.
+- **The `partNumber` lookup is raw-interpolated** (`WHERE partNumber = '{$partNumber}'`) — a
+  latent SQL-injection point in `_Model_Aig_Entitlement::prePost`. Payload data is partner-
+  supplied; should be escaped with `_Database::escape()` or parameterized. Not yet fixed
+  (TRUE-79534 was data-load only).
+- **The lookup is not vendor-scoped** (`LIMIT 1` on `partNumber` alone). It relies on
+  `partNumber` being globally unique within `Items`; safe today because the code spaces don't
+  collide, but a future collision would silently resolve to the wrong item.
+- **Unit/device item codes are a separate source.** The entitlement payload also carries
+  `entitlementUnits[].unit.item.partNumber` (e.g. `1167` "Tablet Accessories"); those device
+  codes are **not** in the SaleItemID spreadsheet and must be sourced separately if missing.
+- **No unique key on `Items.partNumber`** — use an anti-join for idempotent loads, not
+  `INSERT IGNORE`.
+
+## Change history
+
+- 2026-06-19 — Documented intake flow; loaded 2,200 new SaleItem codes (1,700 STS `ASI-*`/`SM-*`
+  + 500 unique numeric `SA`) into `Client_Aig.Items` via TRUE-79534, fixing "Missing AIG item ID"
+  on the new `ASI-*` scheme. Follow-up to TRUE-79441. (mhammontree)
+
+## Related docs
+
+- [api2 architecture](../../../2.0/apps/api2/architecture.md) — the V2 intake engine + payload interceptors.
+- [dbchanges2 architecture](../../../2.0/apps/dbchanges2/architecture.md) — migration naming + the bulk-insert rule.

package/knowledge/clients/aig/profile.md

@@ -0,0 +1,40 @@
+---
+title: "AIG (Staples Protection Plan)"
+framework: "2.0"
+apps:
+  - _underscore
+  - api2
+  - dbchanges2
+project: API
+client: aig
+type: profile
+status: active
+updated: 2026-06-19
+owners: ["mhammontree"]
+files: []
+related:
+  - clients/aig/features/entitlement-intake.md
+---
+
+## Summary
+
+AIG is the warranty underwriter behind the **Staples Protection Plan** retail program. In the
+2.0 platform AIG is a database-level tenant (`Client_Aig` schema) with its own `_Model_Aig_*`
+class overrides in `_underscore` (most pulling in NetSuite traits). Protection-plan
+**entitlements** are pushed to TOGa via the `api2` V2 JSON API; on intake an interceptor
+resolves the sold warranty SKU against `Client_Aig.Items`, and closed claims are invoiced
+back to AIG through NetSuite.
+
+The intake vendor on entitlement payloads is `STS_001` ("STS" = Staples); registration emails
+go out under the Staples Protection Plan brand and link to `staplesprotection.togaview.com`.
+
+## Integration touchpoints
+
+- **`api2`** — entitlement intake (`/v2` JSON), where the AIG payload is POSTed.
+- **`_underscore`** — `_Model_Aig_*` overrides (Entitlement intake interceptor, Contact sync,
+  NetSuite item/SO/invoice traits).
+- **`dbchanges2`** — `Client_Aig/` schema + reference-data migrations (e.g. the SaleItem code
+  catalog in `Client_Aig.Items`).
+
+See [entitlement-intake.md](features/entitlement-intake.md) for how a payload becomes an
+entitlement and how to load new sale-item codes.

package/package.json

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