toga-ai 1.0.494 → 1.0.496

package/knowledge/1.0/apps/worker/INDEX.md

@@ -10,5 +10,6 @@
 | [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql, library/app/api/netsuite/rest.php, library/app/systemmonitor/netsuiteintegration.php |
 | [OneUptime external uptime monitoring for 1.0 workers](features/oneuptime-worker-uptime-monitoring.md) | Every 1.0 worker box self-reports its liveness to an external OneUptime monitor once per minute by curl-POSTing to a per-worker "Incoming Request" heartbeat URL | library/app/worker.php, worker/crons/worker/worker_heartbeat.php |
 | [Prudential: Send Shipments for the Day report (daily cron)](features/send-shipments-for-the-day.md) | Daily cron (9:00 PM) that emails Prudential and Dell stakeholders an Excel report of all devices shipped that day, including tracking number, serial number, emp | worker/crons/notifications/reports/send_shipments_for_the_day.php |
+| [Diagnosing frozen 1.0 worker cron check-ins (Sentry "missed" flood)](workflows/diagnosing-frozen-cron-checkins.md) | When 1.0 worker cron timestamps freeze and Sentry project `worker1` fills with **`missed`** check-ins, the intuitive diagnosis — a wedged `App_Framework::isProc | worker/.ebextensions/cron.config, library/app/worker.php |
 | [isFulfillable Multi-Client Backfill (all togasupply clients)](workflows/isfulfillable-multi-client-backfill.md) | One-time backfill that catches up `Items.isFulfillable` on **existing** items across **all 17 togasupply clients** (AIG, Broward Sheriff, Canon, Endeavor Health | worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php, library/app/api/toga2.php |
 | [Onboarding a Client to the NetSuite TOGa Supply Sync](workflows/onboarding-client-to-netsuite-togasupply-sync.md) | How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer (`worker/crons/toga2/netsuite/`). | worker/crons/toga2/netsuite/sync_togasupply.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |

package/knowledge/1.0/apps/worker/workflows/diagnosing-frozen-cron-checkins.md

@@ -0,0 +1,103 @@
+---
+title: Diagnosing frozen 1.0 worker cron check-ins (Sentry "missed" flood)
+framework: "1.0"
+repo: worker
+project: Worker
+client: shared
+type: workflow
+status: active
+updated: 2026-08-03
+owners: ["dfranks"]
+files:
+  - worker/.ebextensions/cron.config
+  - library/app/worker.php
+related:
+  - ../architecture.md
+  - ../features/oneuptime-worker-uptime-monitoring.md
+  - ../../library/features/cron-execution-monitoring.md
+---
+
+## Summary
+
+When 1.0 worker cron timestamps freeze and Sentry project `worker1` fills with **`missed`**
+check-ins, the intuitive diagnosis — a wedged `App_Framework::isProcessRunning()` lock — is
+usually **wrong**. The common cause is **Elastic Beanstalk deployment churn replacing the EC2
+instances underneath the crons**. This workflow is the ordered path that distinguishes the two
+and the interpretation traps along the way.
+
+## Where to look (name mapping)
+
+Sentry project **`worker1`** is the 1.0 worker tier running in the Elastic Beanstalk
+environment **`agilant-worker`** (application "Agilant", `us-west-2`, account
+`502614707982`, reachable with the `default` SSO profile). It is a multi-instance autoscaled
+fleet. **There is no EB environment literally named `worker1`** — the Sentry project name and
+the EB environment name do not match, and looking for the wrong one costs real time.
+
+## The failure mode
+
+An EB deploy that aborts — events read like `Failed to deploy application`,
+`Unsuccessful command execution on instance id(s) ...`,
+`Cannot complete command execution ... no longer running` — causes EB to **replace
+instances**. In-flight cron processes die with their host, and each Sentry monitor's
+`lastCheckIn` freezes at whatever its now-terminated instance last reported. Nothing is
+stuck; nothing needs clearing.
+
+Two consequences worth knowing:
+
+- **Check-ins resume on their own**, typically within ~1 minute of the deploy completing.
+  No manual intervention, no lock to clear, no instance to restart.
+- EB may warn that an aborted deploy left instances on **mixed application versions**. That
+  does need a re-deploy of the intended version — the recovery of the crons does not imply
+  the fleet is on the version you meant to ship.
+
+## Diagnostic path
+
+1. **List the project's monitors and find the stall boundary.**
+   `GET https://sentry.io/api/0/organizations/<org>/monitors/?project=worker1` — read each
+   monitor's `environments[].lastCheckIn`. The cluster of timestamps that all stop at roughly
+   the same moment is the boundary.
+2. **Pull per-monitor check-in history.**
+   `GET .../monitors/<slug>/checkins/` — a `missed` entry **with no `duration`** means the run
+   never started or never reported. A run that started and then hung looks different (it has a
+   start and no clean check-out). This is the first signal separating "process never launched"
+   from "process wedged".
+3. **KEY DISCRIMINATOR — are non-monitored crons on the same host still throwing ordinary
+   exceptions in the same Sentry project's issue stream?** If other crons are still erroring
+   *after* the stall boundary, then PHP runs and Sentry connectivity both work and the host is
+   alive. That rules out "host down / Sentry unreachable" and points at instance replacement
+   or a per-cron blockage.
+4. **Confirm against Elastic Beanstalk.**
+   ```
+   aws elasticbeanstalk describe-events --environment-name agilant-worker --start-time <ISO>
+   aws elasticbeanstalk describe-environment-health --environment-name agilant-worker --attribute-names All
+   ```
+   Correlate deploy / abort / instance-add / instance-remove timestamps against the stall
+   boundary. A deploy window that brackets the boundary is the answer.
+
+## Interpretation caveats
+
+- **Timezones.** Sentry returns **UTC**; the developer reporting the symptom is usually
+  quoting local **CDT (UTC-5)**. Convert before concluding the windows "don't line up" — they
+  usually do.
+- **Establish each monitor's baseline before calling a stale timestamp new.** The `worker1`
+  monitor list chronically contains monitors that have been silently dead for weeks or months
+  for reasons unrelated to any current incident. During an incident these are noise and must
+  not be read as "failed to recover." (Deliberately not listing which ones — that goes stale.
+  Check each monitor's own history.)
+- **Separate high-frequency from low-frequency monitors.** A 5-minute monitor should recover
+  within minutes; an hourly or daily one will not move until its next scheduled slot, and its
+  silence proves nothing.
+- **Alerting-hygiene gap.** Chronically dead cron monitors mean nobody is being alerted on
+  those jobs at all. Worth a separate follow-up whenever you notice one.
+
+## After recovery
+
+A multi-minute cron outage on this tier means missed windows for order processing, email
+sending, and inbound order imports. These are catch-up-on-next-run designs and generally
+self-drain — but **eyeball queue depth / backlog after recovery rather than assuming clean**.
+
+## Change history
+
+- 2026-08-03 — Documented from a production diagnostic session: frozen cron timestamps +
+  `missed` check-in flood on `worker1` traced to EB deployment churn on `agilant-worker`, not
+  a wedged `isProcessRunning()` lock. (dfranks)

package/knowledge/2.0/apps/_underscore/features/email-send-pipeline.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-07-29
-owners: ["bala", tcox]
+owners: ["bala", "tcox", "dfranks"]
 files:
   - _underscore/Email.php
   - worker2/Worker/Infrastructure/Email/Send.php
@@ -71,11 +71,47 @@ SMTP** using PHPMailer, then flips each row to `SENT` or `FAILED`. So a 2.0 emai
   `DevTeam@goagilant.com` is a known-good verified sender identity in worker2 config. See
   [ai-bdr web-funnel-app.md](../../ai-bdr/features/web-funnel-app.md).
 
+- **⚠ READ-AFTER-WRITE ON THE READER REPLICA LOSES `send()`'S OWN LOG ROW (deterministic).**
+  `_Email::send()` INSERTs the `PENDING` `Logs_[Client].Email` row, then reads `$emailLog->id`
+  back. On a `_Model`, `save()` sets the PK in memory from `getInsertId()` but does **not** clear
+  `_model_needsToBeInitialized`, so the next `->id` access triggers `__get` → `initialize()`,
+  which issues a fresh `SELECT ... WHERE id=<new id>`. `DB_CLIENT_LOGS` is registered with a
+  **separate `readHost`**, so that SELECT is routed to the **reader replica** — but the INSERT is
+  still inside an **uncommitted** lazy transaction, so it has produced no binlog event and the
+  replica **can never** see it during this request. The read returns 0 rows and `initialize()`
+  throws `"exactly 1 row expected, 0"`. This is **100% deterministic, not a lag race** — an
+  uncommitted write cannot replicate. A connection *can* see its own uncommitted writes
+  (read-your-own-writes), so forcing the read onto the writer is the fix.
+  - **Why only some emails hit it:** approval/order-placed emails send from inside the **api2
+    CRUD POST path** (and worker2), which call `_Database::setIsReadHostEnabled(false)`
+    (`V2.php` create loop; worker2 `Controller/Index.php`) — their identical read-back hits the
+    **writer** and succeeds. The scripted-API path (`/email-templates/sendEmail`) never suppresses
+    the read host, so it throws every time. This was the root cause of the Compass In-Transit
+    email outage — see
+    [`compass-partial-in-transit-delivered-emails.md`](../../../1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md).
+  - **Fix direction (smallest blast radius):** wrap the log-row `save()` + id read (+ attachment
+    loop) in `_Email::send()` with `_Database::setIsReadHostEnabled(false)`, restoring the prior
+    value in a `finally` (get/set at `Database.php`). Fixes all scripted-API emails and hardens the
+    interceptor path.
+  - **Rejected alternatives:** (a) `commit` right after `save()` before the read — recreates the
+    failure as an *intermittent* replication-lag race AND breaks the request's one-transaction
+    boundary (orphans the row on a later throw, prematurely commits everything else buffered on the
+    connection, strands attachment/API-log writes on a closed lazy transaction). (b) Clear
+    `_model_needsToBeInitialized` after INSERT in `_Model::save()` so `->id` reads from memory
+    (zero queries) — conceptually the *correct* fix but changes every model in the ORM, too broad
+    for a hotfix.
+
 ## Change history
 - 2026-07-29 — Noted that the SES SMTP credentials/settings now have a **non-PHP consumer**: the
   BDR funnel sends via nodemailer against the same SES host (us-west-2, port 587, TLS) using
   `TOGA_SMTP_*` env vars, so a rotation must be coordinated with BDR's `.env.local` + Amplify
   vars or BDR's summary email goes dark. (tcox)
+- 2026-07-29 — Documented the **deterministic read-after-write failure** in `_Email::send()`:
+  reading `$emailLog->id` after INSERT triggers `_Model::__get`→`initialize()`→ a reader-replica
+  SELECT for an uncommitted row → `"exactly 1 row expected, 0"` throw. Only the scripted-API send
+  path fails (CRUD/worker paths suppress the read host via `setIsReadHostEnabled(false)`); this was
+  the root cause of the Compass In-Transit outage. Fix direction = suppress the read host around the
+  log-row save+read in `send()`. (dfranks)
 - 2026-07-28 — Created: documented that `_Email::send()` **queues** (writes a `PENDING`
   `Logs_[Client].Email` row + attachment BLOBs) rather than transmitting, and that the worker2
   `Infrastructure/Email/Send` cron (`Core.CronJobs` `* * * * *`) does the actual SES SMTP send

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

@@ -11,7 +11,7 @@
 | [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, _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 |
+| [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, api2/Controller/Index.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 |
 | [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |

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

@@ -7,9 +7,10 @@ client: shared
 type: feature
 status: active
 updated: 2026-07-29
-owners: ["mhammontree"]
+owners: ["mhammontree", "dfranks"]
 files:
   - api2/Component/Api/V2/V2.php
+  - api2/Controller/Index.php
   - _underscore/Model/Client/Logs/Api.php
   - _underscore/Model/Core/Logs/Api.php
 related:

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 14 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 17 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 18 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 10 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)

package/knowledge/sessions/2026-08-03-true-79401-multi-email-resolution-mhammontree.md

@@ -0,0 +1,82 @@
+---
+type: session
+slug: true-79401-multi-email-resolution
+title: TRUE-79401 — closed the multi-email payload-shape question (no api2 work needed)
+author: mhammontree
+repos: [library, api2, _underscore, worker2]
+framework: "both"
+client: aig
+status: active
+created: 2026-08-03
+updated: 2026-08-03
+---
+
+# Session: true-79401-multi-email-resolution
+**Date:** 2026-08-03
+**Project/Repo:** library (1.0 core) — with 2.0 findings in api2 / _underscore / worker2
+**Task:** Review the one open question left on TRUE-79401 (multiple email addresses for AIG in the 1.0 `library` bridge) — namely "do we need an api2 intake mapping?" — and determine whether it was already answered in prior sessions or meetings.
+
+---
+
+## What WORKED
+
+- **Found the prior session's record immediately** via the knowledge base, not by code archaeology. `knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md` held the full TRUE-79401 history from the 2026-07-28 capture, including the open question and the "owner Paulina" note.
+- **Confirmed the library implementation is present in the working tree** — grep for `CUSTOMER_EMAIL_DELIMITER|contactEmailAddresses` in `C:\WWW\library` returned `toga2.php:112` (the `'; '` constant), `:8424` (the `/contacts` fetch `fields` whitelist entry), and `:8499–8505` (the `array_column` → trim/filter/unique → implode → `sqlEscape` chain).
+- **Proved `UserDefined3` is not a real field anywhere.** Grep across all of `C:\WWW` returned exactly two hits: the comment at `library/app/api/toga2.php:8424` and the knowledge doc itself. Zero hits in `api2` or `_underscore`. This was the key evidence that the flat-field branch was never implemented and never intended.
+- **Proved `c_businessUnit` was never built.** Grep for `businessUnit|c_businessUnit` (case-insensitive) across `C:\WWW` returned only unrelated `BusinessUnits` table hits in the `forecast` repo — nothing in `_underscore`, `api2`, or `dbchanges2`. So there is no dead custom field to clean up.
+- **Extracted the Teams transcript from the .docx successfully** after two failures (see below). Working method: `[System.IO.Compression.ZipFile]::ExtractToDirectory()` on the `.docx`, then on `word/document.xml` replace `</w:p>` → newline and `<w:br/>` → newline, strip `<[^>]+>`, and hand-replace the five XML entities. Produced 21,829 chars / 199 lines of readable transcript at `<scratchpad>/aig-transcript/transcript.txt`.
+- **The transcript answered the question**, plus three things nobody asked: purpose is verification-only, the ~15-client-DB column approach was rejected, and the origin of the "VARCHAR(55)" fear.
+- **AIG's mapping spreadsheet (shared as an image by Paulina) closed it definitively** — both `UserDefined3` and `UserDefined4` map to `Entitlements.contact.contactEmailAddresses[].emailAddress`, and the `UserDefined2` (Business Unit) target column is conspicuously **empty**, corroborating that it was dropped.
+- **`/capture` published 4 doc UPDATEs and pushed** — validate OK (305 docs / 30 repos), mirrored to `C:\WWW\.claude\knowledge`, PUSHED.
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **Searching the production logs for a multi-email payload.** This was my suggestion and it is a **dead end by construction**: AIG currently sends only one email address and will not enable the extra fields until we tell them the feature is live. Therefore every payload in `Logs_Aig.Api` and in the core/writer `Logs` contains exactly one `primaryContactEmailAddress` and nothing else. There is no multi-email payload to find. **Do not propose a log audit to determine the future payload shape** — the shape is a *specification* question, not a discovery question.
+- **Searching our own transcript store for the 2026-05-01 meeting.** `Team/Transcripts/Export` first ran successfully in production on **2026-06-12** (PR #78) and runs off an incremental watermark with a bounded `lookbackDays`; no multi-week backfill appears in its change history. A May 1 meeting is **not** in `Team.TranscriptExports`, `Team.TranscriptProcessing`, or the `togaiq` KBs despite having been recorded. Recover pre-June meetings from Microsoft Graph or a manual export instead.
+- **Reading the `.docx` with the `Read` tool.** Failed with: `This tool cannot read binary files. The file appears to be a binary .docx file.` Must unzip and strip XML (method above).
+- **`[System.Web.HttpUtility]::HtmlDecode($t)` in the extraction script.** Failed with: `Unable to find type [System.Web.HttpUtility].` — Windows PowerShell 5.1 does not load `System.Web` by default. Either `Add-Type -AssemblyName System.Web` first, or (what I did) hand-replace `&amp; &lt; &gt; &quot; &apos;`. Note the failure was non-terminating, so the script *appeared* to continue and wrote a partially-processed file — the first extraction produced only 6 lines and looked plausible.
+- **Assuming the delimited string was the payload format.** The comma/semicolon discussion in the 2026-05-01 meeting is about **1.0 storage** (`TOGA_AIG.Customers.emailAddress`, a legacy `varchar(255)` that can only hold a string), *not* the inbound payload. The payload is an array of objects. Three layers: nested records inbound → one row per address in `Client_Aig.ContactEmailAddresses` → `'; '`-joined string in 1.0. Easy conflation because the same meeting covers both within minutes.
+
+## Not tried yet (candidates for next session)
+
+- **The beta nested-write test.** POST a synthetic AIG entitlement to beta/QA with two nested `contactEmailAddresses` entries and **assert the actual `Client_Aig.ContactEmailAddresses` row count** — not the HTTP status. Must cover **both** a brand-new contact (CREATE) and a **second entitlement for an existing contact** (UPDATE). The UPDATE path is the suspect one: per `2.0/apps/api2/features/nested-relationship-writes.md` (2026-07-20), the reverse back-reference injection at `V2.php:4985–4996` breaks single-key forced-MATCH and explicitly names `primaryContactEmailAddress` as likely affected.
+- **Verifying the library change is merged and deployed to the prod worker.** Git/deploy state of `C:\WWW\library` was **never checked** this session. The code is confirmed present in the working tree only.
+- **The note to Paulina / AIG** — two confirmations (did the mapping document actually reach AIG after the 2026-05-04 email; has their dev acknowledged the `contactEmailAddresses[]` mapping) plus the concrete JSON example.
+- **Hardening the dedupe lookup** — `LIKE '%$primaryEmailAddress%'` instead of the current wildcard-less `LIKE`, or dropping the email fallback in favour of `c_togaCustomerId` alone.
+- **Guarding the unrelated-but-open `prePost` empty-`$itemId` defect** in `_Model_Aig_Entitlement` (a missing sale-item code still 500s instead of returning a clean "Missing AIG item ID"). Pre-existing, documented, out of TRUE-79401 scope.
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `library/app/api/toga2.php` | **Unchanged this session** | TRUE-79401 code from 2026-07-28 confirmed present at `:112`, `:8424`, `:8499–8505`. No edits made. |
+| `_underscore/Model/Aig/Entitlement.php` | Unchanged (read only) | `postPost` single-recipient email confirmed **correct by design**, not a gap. |
+| `_underscore/Model/Client/ContactEmailAddress.php` | Unchanged (read only) | Confirms the collection is one row per address; FK `contactId` → `_Model_Client_Contact`. |
+| `knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md` | **Updated + pushed** | "Payload shape OPEN" gotcha **replaced** with a RESOLVED section; new Open items section; 4 new gotchas. |
+| `knowledge/clients/aig/features/entitlement-intake.md` | **Updated + pushed** | New "Business Unit (UserDefined2) — answered and DROPPED" section + 2 gotchas. |
+| `knowledge/2.0/apps/api2/features/nested-relationship-writes.md` | **Updated + pushed** | New framework-level section: a wrong-shaped nested collection returns 201 and silently drops data. |
+| `knowledge/2.0/apps/worker2/features/teams-transcript-export.md` | **Updated + pushed** | New gotcha: no transcript coverage before ~2026-06-12. |
+| `<scratchpad>/aig-transcript/transcript.txt` | Created (temp) | Extracted 2026-05-01 meeting transcript, 199 lines. Scratchpad — not committed. |
+
+**No source code was written or changed this session.** It was review + resolution + knowledge capture.
+
+## Decisions made
+
+- **No api2 intake mapping will be built.** Rationale: AIG's own field-mapping document maps both `UserDefined3` and `UserDefined4` to `Entitlements.contact.contactEmailAddresses[].emailAddress`, so AIG restructures on their side and the V2 metadata-driven engine writes the collection generically. *Rejected alternative:* an AIG `prePost` interceptor converting flat `c_secondaryEmailAddress`/`c_tertiaryEmailAddress` custom fields into `ContactEmailAddresses` rows — rejected because it caps the address count, requires custom-field definitions plus a release, and the mapping document already specifies the nested form.
+- **Keep the separately-escaped `$primaryEmailAddress` for the dedupe lookup**, despite the 2026-05-01 meeting saying to "get rid of the primary contact email address" entirely. Rationale: the primary-email `LIKE` is the legacy fallback for matching pre-existing 1.0 customers that have no `c_togaCustomerId`; removing it would break that matching outright. Accepted consequence: a stored `'; '`-joined list can no longer satisfy the wildcard-less `LIKE`, which could duplicate a customer if the `c_togaCustomerId` write-back ever fails after the insert.
+- **Multi-recipient notification stays out of scope.** Rationale: the meeting explicitly framed this as verification/lookup for support agents ("it's just for visual, this is for verification, it's a string") and specifically rejected CC/BCC-ing all addresses onto TogaDesk tickets. *Rejected alternative:* widening `postPost`'s registration email to all addresses.
+- **Change 4 (201-with-silent-drop) was recorded on the existing api2 `nested-relationship-writes` feature doc rather than promoted to a `standard`.** Rationale: it is the behavior of one already-documented capability, not a new cross-cutting rule — and it avoided an ELEVATED approval gate.
+- **`worker2` was NOT added to the `aig` client app-scope.** Rationale: the transcript-coverage finding is a shared/internal worker2 fact, not AIG-specific.
+
+## Blockers
+
+- **Communication deadlock with AIG, not a code blocker.** AIG will not enable the secondary/tertiary email fields until we tell them the feature is live; we have not told them, and our last message (2026-05-04) asked them to send the email fields "only if they are necessary for the process" — ambiguous phrasing delivered in the same breath as dropping Business Unit, which may have read as a de-scope. **There is no AIG reply to that message.** Both sides are waiting on each other.
+- **Unknown whether the mapping document actually reached AIG.** In the 2026-05-01 meeting Paulina was holding the whole document back until the Business Unit / invoice-file question was answered. That question *was* answered on 2026-05-04, but nothing confirms the document went out afterward.
+- **Deploy state of the library change is unverified** — cannot honestly tell AIG "it's live" until confirmed.
+
+## Exact next step
+
+> Draft the note to Paulina for AIG's dev team. It must (1) retract the "only if necessary" ambiguity and state plainly that the secondary/tertiary addresses **are** wanted — unlike Business Unit; (2) include the concrete JSON example, not just the `contactEmailAddresses[].emailAddress` path expression, because a bare-string array `["email2@domain.com"]` returns HTTP 201 and silently drops the addresses (`array_column($list, 'emailAddress')` yields empty); (3) ask the two confirmations — did the mapping document reach AIG after the 2026-05-04 email, and has their dev acknowledged the `contactEmailAddresses[]` mapping. The exact payload fragment to paste is in `knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md` → the `TRUE-79401 payload shape — RESOLVED` section. Immediately after: check the git/deploy state of `C:\WWW\library` for the TRUE-79401 commit before signalling "live".
+
+---
+_Saved by /session-save on 2026-08-03_

package/package.json

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