toga-ai 1.0.145 → 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/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.145",
+  "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",