toga-ai 1.0.494 → 1.0.495

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.495",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",