toga-ai 1.0.463 → 1.0.465

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,8 +6,8 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
-owners: [jcardinal]
+updated: 2026-07-28
+owners: [jcardinal, mhammontree]
 files:
   - library/app/api/toga2.php
   - worker/crons/toga2/aig/sync_togasupply_aig.php
@@ -90,6 +90,17 @@ bool $enabled2to1, bool $enabled1to2)`. When `enabled2to1`:
 - Pages 2.0 **`/contacts`** (for AIG, only those with `c_togaCustomerId IS NULL`) and upserts each
   into the 1.0 client DB `Customers`/`Addresses` via `syncContactToToga1Customer`, then **writes
   the new 1.0 id back** to the 2.0 contact's `c_togaCustomerId` (PUT `/contacts/{uuid}`).
+- **Email storage (`syncContactToToga1Customer`, TRUE-79401):** the 1.0 `Customers.emailAddress`
+  column stores the contact's **full** list of 2.0 email addresses joined by the class constant
+  `CUSTOMER_EMAIL_DELIMITER = '; '`, not just the primary. The list is built from
+  `array_column((array)($togaContact->contactEmailAddresses ?? []), 'emailAddress')` →
+  trim / `array_filter` / `array_unique` → `implode` → `App_Database::sqlEscape` (escape **after**
+  imploding); an empty collection falls back to the single primary email (no regression). A
+  separately-escaped `$primaryEmailAddress` is retained **only** for the customer-dedupe lookup
+  (`WHERE Customers.emailAddress LIKE '$primaryEmailAddress'`) so storing a list doesn't break
+  record matching — dedupe is authoritatively keyed on **`c_togaCustomerId`**, with the primary-email
+  `LIKE` as a legacy fallback. Consuming the `contactEmailAddresses.emailAddress` collection required
+  adding it to the `/contacts` fetch `fields` whitelist (see gotcha).
 - Pages 2.0 **`/entitlements`** without a `c_togaServiceRequestId` and inserts 1.0
   `ServiceRequests` (+ a `Contacts` row if needed) via `syncEntitlementToToga1ServiceRequest`.
 - The 1→2 direction (`enabled1to2`) is a stub (not yet implemented).
@@ -154,11 +165,37 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
   the `App_Model` layer; follow the surrounding escaping discipline when modifying.
 - **Per-record error isolation** in the TOGaDesk sync is via `try/catch` → `\Sentry\captureException`;
   a thrown exception elsewhere (transport, checkpoint read) still aborts the whole run.
+- **A reverse hasMany collection is only returned if you add it to the fetch `fields` whitelist.**
+  The `/contacts` fetch requests an **explicit** `fields` list from the 2.0 metadata API; a reverse
+  hasMany collection (e.g. `contactEmailAddresses.emailAddress`) is **not** returned unless it is
+  added to that list — so consuming a related collection means editing **both** the fetch field list
+  **and** the consuming code. (The general 2.0-side metadata behavior — reverse relations resolved via
+  the child model's `FOREIGNKEY_MODEL` and named as the camelCase plural of the child model — is a
+  framework-level fact captured separately.)
+- **`TOGA_AIG.Customers.emailAddress` is `varchar(255)`** (V1 legacy, latin1_swedish_ci) — wide
+  enough to hold several `'; '`-joined emails, so TRUE-79401 needed **no** schema/dbchanges migration
+  (the earlier fear that it was ~VARCHAR(55) was wrong). `TOGA_AIG` is the 1.0 legacy DB;
+  `Client_Aig` is the 2.0 prod tenant.
+- **The multi-email path is not yet exercised (open, TRUE-79401).** As of 2026-07-28 all 20
+  `Client_Aig.ContactEmailAddresses` rows are one-per-contact, and **no** api2/`_underscore` code
+  references `UserDefined3`/`UserDefined4` or creates `ContactEmailAddresses` rows. Whether an api2
+  intake mapping is still needed depends on how Staples / SA.com sends the extra emails: if they POST
+  nested `contactEmailAddresses` records to the V2 API the library change is complete; if they send
+  flat `UserDefined3`/`UserDefined4` fields expecting us to map them into email rows, an api2 intake
+  mapping must be built. Open question owned by **Paulina**.
 - **PHP 7.2** target (prod worker/library) — no arrow functions, typed properties, `??=`, `match`.
   Lint with `C:\xampp7\php\php.exe -l`.
 
 ## Change history
 
+- 2026-07-28 — TRUE-79401: `syncContactToToga1Customer` now stores a contact's **full** email list in
+  1.0 `TOGA_AIG.Customers.emailAddress` as a `CUSTOMER_EMAIL_DELIMITER` (`'; '`)-joined, deduped,
+  escaped string (was primary-only) for AIG/Staples support lookup. Added
+  `contactEmailAddresses.emailAddress` to the `/contacts` fetch `fields` whitelist; kept a separate
+  escaped primary email for the dedupe `LIKE` (dedupe stays keyed on `c_togaCustomerId`); empty list
+  falls back to primary. No migration needed (`Customers.emailAddress` is `varchar(255)`). Scope stayed
+  library-only. Multi-email path not yet exercised — payload shape (nested `contactEmailAddresses` vs
+  flat `UserDefined3/4`) is open, owner Paulina. (mhammontree)
 - 2026-06-23 — Initial documentation of the `App_Api_Toga2` transport (auth/token caching, options
   DSL) and the 1.0↔2.0 bridge routines `syncWithToga` (Contacts/Entitlements → Customers/ServiceRequests)
   and `syncWithTogadesk` (bi-directional ticket/repair-order/people/asset sync with dual checkpoint

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

@@ -18,5 +18,6 @@
 | [TableView field/column metadata (TableViewFields, hidden projected columns)](features/tableview-field-metadata.md) | The columns of a 2.0 table view are defined by DB metadata, not code. | _underscore/Model/Client/TableView.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
 | [V2 API error/message codes (EV/EZ troubleshooting map)](features/v2-api-error-codes.md) | The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the response `error` field, grouped by family: `EN-*` authentication, `EZ-*` a | api2/Component/Api/V2/V2.php, _underscore/Model/Client/TrackingNumber.php |
+| [V2 reverse hasMany collections must be named in the fetch fields whitelist](features/v2-reverse-hasmany-fields-whitelist.md) | In the V2 JSON engine, a **reverse hasMany** relationship — the collection of child records that foreign-key back to a parent (e.g. | api2/Component/Api/V2/V2.php |
 | [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. | api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php |
 | [New Environment Configuration & Provisioning (api2)](workflows/environment-configuration-and-provisioning.md) | What it takes for a 2.0 API environment (e.g. | api2/Config/<environment>.ini, api2/Controller/Index.php, dbchanges2/Core/2026-06-16a - DatabaseHosts for new QA QC stage demo environments.sql, dbchanges2/Logs/, _underscore/Route.php |

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

@@ -239,6 +239,18 @@ they are the known sharp edges. Do not re-discover these from scratch.
    [worker2 does](../worker2/features/alb-target-group-auto-registration.md). The same script's
    IMDSv2 handling (token on the `curl` command line, silent IMDSv1 fallback) must be fixed with it.
    See the Security note above.
+10. **Cross-client page-number paging is O(page), and the deepen chunk size is an untuned
+    performance dial.** Serving a deep page of a
+    [cross-client listing](features/cross-client-data-retrieval.md) requires materializing every
+    preceding row into the Cache cluster — page 4430 means 110,747 rows. Adaptive chunking
+    (`DEEPEN_CHUNK_MAX_RECORDS = 500`) makes it cheaper, not cheap. The durable fix is exposing
+    **keyset cursors to the caller** so cost is independent of depth; V2 already supports
+    `seekValues` + `seekUuid` correctly, so the mechanism exists but the caller-facing contract is
+    **unbuilt and not yet scoped**. Related dial: chunk size trades round trips against
+    sub-response size — a narrowed `fields` request stays small at any chunk, but an unrestricted
+    listing expands every row through `getFullModelData()` at the requested depth, which is the case
+    where 500 may need lowering. Watch it against `CURL_TIMEOUT_SECONDS = 30`. Do not raise the
+    chunk constant without checking sub-response size for wide, deep listings.
 
 ## When making changes here
 
@@ -254,8 +266,13 @@ they are the known sharp edges. Do not re-discover these from scratch.
   the duplicate check.
 - Preserve the commit-logs / rollback-data-on-failure invariant when editing the controller
   or `execute()`.
+- **A code path with exactly one caller gets zero incidental coverage.** V2's keyset-pagination
+  branch emitted syntactically invalid SQL for an entire development cycle because only the
+  cross-client deepen path ever sets `$isKeysetMode`. In a ~2,000-line untested monolith, treat
+  single-caller branches in `V2.php` as unverified until exercised directly.
 
 ## Change history
+- 2026-07-28 — Added Known issue #10: cross-client page-number paging is inherently O(page) (deep pages materialize every preceding row into the Cache cluster), with caller-facing keyset cursors identified as the durable fix but left unbuilt/unscoped, plus the `DEEPEN_CHUNK_MAX_RECORDS = 500` tuning tradeoff against `getFullModelData()` expansion and `CURL_TIMEOUT_SECONDS = 30`. Added a change-guidance bullet that single-caller branches in the untested `V2.php` monolith get zero incidental coverage (the keyset `LIMIT` syntax error shipped invisibly for a full cycle). (jcardinal)
 - 2026-07-28 — Documented the previously unrecorded `060_register_instance_to_shared_application_load_balancer` postdeploy hook pair in the Deployment section (non-prod self-registration into the same-named ALB target group; production skipped), and recorded a **committed IAM access key** in `ebs/register_instance_to_shared_application_load_balancer.php` as a security note + Known issue #9 — location, line range, commit subject, and remediation only (rotate, audit CloudTrail, move to the instance profile; history rewrite is a separate sign-off). Flagged api2's copy as the unhardened original vs. the new worker2 reference implementation. (jcardinal)
 - 2026-07-28 — Added a consolidated **Known issues / accepted risks** section (8 items), absorbing the previously free-floating deferred raw-exception-disclosure follow-up as item 1, so the tier's sharp edges (unrotated committed secrets, pre-execute phase still outside the main guard, local Logs DB name mismatch, permissive CORS, unpinned `_underscore` build clone, untested `V2.php` monolith, JWT rotation overlap window) are in one place instead of scattered. Recorded that `DB_CACHE` is resolved by name (`Databases.name = 'Cache'`), never by a hardcoded id, which differs per Core instance. (jcardinal)
 - 2026-07-28 — Added gotcha: the request-logger's auto-generated `Api.transactionId` (millisecond timestamp `Y-m-d H:i:s.v`, UNIQUE) collides under concurrent same-millisecond nested writes → MySQL 1062 → HTTP 500; platform-wide, observed on the Compass/Veyer ASN feed (`sourceIp 34.232.23.158`). Distinct from the client-supplied `transactionId`/EV-5 uniqueness contract. Fix direction: uuid the logged id or retry-on-1062. (bala)

package/knowledge/2.0/apps/api2/features/cross-client-data-retrieval.md

@@ -42,10 +42,11 @@ is a **scatter-gather** engine: it fans out to each entitled client's own V2 API
 streams with a watermark, and caches the merged result per-user/per-query on a dedicated Cache
 cluster.
 
-> **Status: working end to end on local dev** (multi-client fan-out, ACL-filtered `client` object,
-> typed multi-column sort, keyset paging, narrowed `fields`, per-query cache isolation).
-> **Not yet deployed** — next stop is external testing. See
-> [api2 architecture](../architecture.md) for the accepted risks carried into that test.
+> **Status: working end to end on local dev AND on a real deployed environment** — first
+> deployed test 2026-07-28 on the **dev sandbox** (`api.beta.togahub.com`, dev-sandbox cluster).
+> That test exposed a page-2-and-beyond failure whose root cause and four follow-on defects are
+> now fixed and verified (see *Deep paging*, *Gotchas* and the change history). See
+> [api2 architecture](../architecture.md) for the accepted risks carried alongside it.
 
 ## How it works
 
@@ -107,6 +108,73 @@ deepening and returned empty pages.
 the watermark cannot make any row safe, so querying it is a wasted round trip. At 1000 clients that
 is ~1 sub-request per pass instead of 1000 — the single biggest efficiency property of the design.
 
+**Worked example (the canonical shape to reason about).** Sorting `-dateOrder` DESC across Compass
++ NYCHH: Compass has 170 rows sharing `dateOrder = 2026-07-27` while NYCHH's *newest* row is
+`2026-06-18`. Compass therefore holds the watermark for many consecutive pages, and NYCHH must
+**not** be re-queried until Compass's cursor passes `2026-06-18`. Verified against live data: after
+the 25-row page-1 cursor, 145 of the 170 same-date rows remain (25 + 145 = 170), i.e. the
+multi-column seek predicate is correct across a large tie block.
+
+### The merge never serves past the watermark (`isDepthUnproven`)
+
+`servePage()` used to do a blind `OFFSET`/`LIMIT` over the result table. When deepening **could not**
+cover the requested page — a client failed, a cursor stalled, or `MAX_DEEPEN_ITERATIONS` ran out —
+it still served a full page of rows that a lagging client may legitimately displace, i.e. it
+presented a mis-ordered page as authoritative. One failed sub-request was enough to return 25 wrong
+rows.
+
+The page is now **clamped to `Tables.safeRecordCount`**, and any shortfall raises the new public
+`$isDepthUnproven`, which V2 turns into a **WARNING** message telling the caller to retry to
+continue deepening. Two new meta fields: `meta.crossClient.safeRecordCount` and
+`meta.crossClient.isDepthUnproven`. `needsDeepening()` and the flag are deduped onto one new
+`hasUnexhaustedClients()` helper.
+
+**Subtlety — the flag is only raised while `hasUnexhaustedClients()` is true.** Once every client is
+exhausted, `safeRecordCount` *is* the true end of the result set, so a short final page is correct
+and must **not** warn.
+
+### Adaptive deepen chunking (sub-request page size ≠ caller's page size)
+
+Because only the watermark client is deepened per pass, and each pass used to fetch the **caller's**
+`recordsPerPage`, reaching page N cost ~N sequential sub-requests — and `MAX_DEEPEN_ITERATIONS = 50`
+capped one HTTP request at ~1250 new rows. Requesting page 254 returned an *empty* page plus the
+new warning.
+
+The internal fetch size is now decoupled from the caller's:
+
+```
+chunkSize = min(DEEPEN_CHUNK_MAX_RECORDS /* 500 */,
+                max(callerRecordsPerPage, target - safeRowCount()))
+```
+
+Page 1 of 25 still fetches exactly 25; page 254 fetches 500 per pass — ~13 round trips instead of
+254. `fanOut()` takes `chunkSize` instead of `recordsPerPage`.
+
+The caller's `recordsPerPage` still governs `servePage()`'s `LIMIT`, `needsDeepening()`'s target,
+`reportedCounts()`, and the **cache identity** (`Tables.recordsPerPage` + query hash). Only the
+internal fetch size changed — **no schema change**.
+
+**Chunk-size tuning.** Chunk size trades round trips against sub-response size. A narrowed `fields`
+request stays small at any chunk; an *unrestricted* listing expands every row through
+`getFullModelData()` at the requested depth, and that is the case where 500 may need lowering.
+Watch it against `CURL_TIMEOUT_SECONDS = 30`.
+
+### Only a cursor-less sub-response may set a client's total
+
+Once the seek predicate is in the `WHERE` clause, V2's found-rows count is the **remainder after the
+cursor**, not the client's total. `collectRows()` therefore tracks an `$isFirstFetch` map and only a
+usable, cursor-less (offset-mode) sub-response establishes `totalRecordCount`; later deepen passes
+leave the recorded total standing. Without this guard, fixing the keyset `LIMIT` bug would have made
+reported totals silently **shrink** on every deepen pass.
+
+### Diagnosing a fan-out failure from the client logs
+
+In `Logs_<Client>.Api`, a sub-request that logged its `POST /v2/auth/encrypted-user-uuid` (201) but
+has **no corresponding GET row** proves the data sub-request died **before** the logging step (a
+fatal) — which is what distinguishes it from a clean 0-row response. That single observation
+isolated the keyset `LIMIT` root cause. Cross-check the *other* client's log too: the **absence** of
+any row there confirms watermark-only deepening queried only the intended client.
+
 ### Per-row `client` object (ACL-filtered)
 
 Every returned row carries a `client` object filtered by the caller's **CORE** roles
@@ -157,12 +225,45 @@ cron.
   in client queries — because the PHP-side watermark merge compares bytes. Any linguistic collation
   would order differently and the merge could certify rows complete that MySQL then re-orders.
 - **Never use the raw stored row count** to decide paging depth; only `safeRecordCount`.
+- **Never serve rows past `safeRecordCount`.** A short page + `isDepthUnproven` + a WARNING is
+  correct; a full page of possibly-displaceable rows is not.
+- **A failed client is UNKNOWN, never exhausted.** Only a client that provably ran out of rows may
+  be marked `exhausted` — the watermark math treats exhausted clients as having no remainder.
+- **Only a cursor-less sub-response may set a client's `totalRecordCount`** — a seek-filtered
+  response counts the remainder, not the total.
+- **Anything compared against a sub-request's page size must compare against `chunkSize`**, not the
+  caller's `recordsPerPage`, now that the two differ.
 - **Every outbound sub-request needs its own globally-unique `transactionId`.**
 - **Forward the caller's original query string verbatim** — parsed `$httpOptions` do not round-trip
   (see the url-decode gotcha below). `MAX_CONCURRENT_CLIENT_FETCHES = 25` bounds fan-out.
 
 ## Gotchas
 
+- **V2's keyset `LIMIT` had no leading newline — every seek sub-request was a SQL syntax error.**
+  In `processRoutePairs()` (`V2.php`, keyset branch, ~line 4113) the keyset path did
+  `$sql .= ('LIMIT ' . $recordsPerPage)` while the OFFSET path had a leading newline. The `ORDER BY`
+  immediately above ends in a bare `ASC`, so the generated SQL read
+  `` CAST(`uuid` AS BINARY) ASCLIMIT 25 ``. It hid for a whole development cycle because **only the
+  cross-client deepen path ever sets `$isKeysetMode`** — page 1 uses OFFSET and nothing else in api2
+  exercises keyset mode. This was the root cause of the entire "page 2+ returns wrong results" report.
+  *Lesson: a code path with exactly one caller gets zero incidental coverage.*
+- **`emptyClientResult()` returning `exhausted => true` turned a transient error into a permanently
+  wrong cached answer.** `safeRowCount()` skips exhausted clients when computing the watermark, so a
+  failed client dropped out of the watermark → every already-cached row looked provably safe →
+  `safeRecordCount` was committed too high → `needsDeepening()` returned false for the **life of the
+  cache entry**, permanently excluding that client from every future deepen pass. It is now `false`
+  (unknown remainder). No runaway risk: the existing `$newRowCount === 0` stall guard still breaks
+  the loop.
+- **`persistCursors()` erased the reported totals of every client it did not fetch this pass.** It
+  `DELETE`s all `Tables_Clients` rows then re-`INSERT`s with `$counts[$clientId] ?? null`, but a
+  deepen pass only populates `$counts` for the single watermark-holding client. Every other client's
+  `totalRecordCount`/`prohibitedRecordCount` became NULL → `meta.totalRecordCount` and
+  `totalPageCount` went to 0 → and because `nextPage` derives from `totalPageCount`, `nextPage`
+  became `null`, dead-ending any caller that pages by following `nextPage`. Fix: `SELECT` the
+  existing counts before the `DELETE` and carry them forward **per field**.
+- **The exhaustion test had to move to `chunkSize` in the same commit as adaptive chunking.**
+  Comparing a full 500-row block against a caller page size of 25 declares the client "exhausted" and
+  silently reintroduces the `emptyClientResult` class of bug above.
 - **V2 NEVER url-decodes its query string.** It splits `QUERY_STRING` on `&` and `=` and consumes
   the raw values. Anything containing `,`, `[`, `"`, `%`, `+` or a space arrives mangled — this bit
   the feature twice (the JSON `seekValues` array, and a comma-separated `fields` list corrupted into
@@ -200,7 +301,35 @@ cron.
 - **`curl_multi` busy-spin guard** — both multi loops `usleep(100)` when
   `curl_multi_select() === -1`.
 
+## Known limitation — deep page-number paging is inherently O(page)
+
+Serving page 4430 means materializing all 110,747 preceding rows into the cache. Adaptive chunking
+makes that cheaper, not cheap: cost still grows with depth, because a page **number** cannot be
+resolved without knowing everything before it.
+
+The durable answer is **exposing keyset cursors to the caller** so cost is independent of depth — the
+mechanism already exists (V2 now supports `seekValues` + `seekUuid` correctly). This was raised with
+the developer on 2026-07-28 and **deliberately left unbuilt / not yet scoped**: record it as a known
+limitation and a candidate direction, not as pending work.
+
 ## Change history
+- 2026-07-28 — **First test on a real deployed environment** (dev sandbox,
+  `api.beta.togahub.com`), which reported wrong results on page 2+. Root cause: V2's keyset `LIMIT`
+  was concatenated without a leading newline, so **every** seek sub-request was a SQL syntax error —
+  invisible until now because only the cross-client deepen path sets `$isKeysetMode`. Fixed, plus the
+  four defects it masked: `emptyClientResult()` marking a *failed* client `exhausted` (which
+  permanently over-committed `safeRecordCount` and excluded that client from all future deepening);
+  `persistCursors()` NULL-ing the totals of every client not fetched in the pass (killing
+  `totalRecordCount`/`totalPageCount`/`nextPage`); totals being taken from cursor-filtered
+  sub-responses (now only a cursor-less first fetch sets a client's total); and `servePage()` serving
+  blind `OFFSET`/`LIMIT` past the watermark (now clamped to `safeRecordCount`, with a new public
+  `$isDepthUnproven` → V2 WARNING, `hasUnexhaustedClients()` helper, and new
+  `meta.crossClient.safeRecordCount` / `isDepthUnproven`). Added **adaptive deepen chunking**
+  (`DEEPEN_CHUNK_MAX_RECORDS = 500`; per-pass `chunkSize`, `fanOut()` and the exhaustion test both
+  switched to it) so deep pages cost ~page/500 round trips instead of ~page — no schema change, cache
+  identity unchanged. Recorded the Compass/NYCHH tie-block worked example, the log-based fan-out
+  failure diagnostic, and deep page-number paging being O(page) as a known limitation (caller-facing
+  keyset cursors left unbuilt). Verified working on dev sandbox. (jcardinal)
 - 2026-07-28 — Took the feature from never-executed to working end to end. Row identity moved from
   the numeric id to `rowUuid`/`seekUuid` (a V2 LIST never returns `id`); per-query
   `TableResults_<id>` tables with typed, direction-indexed sort columns; multi-column `seekValues`

package/knowledge/2.0/apps/api2/features/v2-reverse-hasmany-fields-whitelist.md

@@ -0,0 +1,77 @@
+---
+title: V2 reverse hasMany collections must be named in the fetch fields whitelist
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-28
+owners: [mhammontree]
+files:
+  - api2/Component/Api/V2/V2.php
+related:
+  - nested-fk-acl-embedding.md
+  - ../../../../1.0/apps/library/features/toga2-api-client-and-bridge.md
+---
+
+## What it is
+
+In the V2 JSON engine, a **reverse hasMany** relationship — the collection of child records that
+foreign-key back to a parent (e.g. a Contact's many `ContactEmailAddresses`) — is **not** included
+in a response by default. It is only serialized when the caller **explicitly names it in the fetch
+`fields` list**. A parent GET that does not list the reverse collection comes back with that key
+absent — no error, no warning `message`, still HTTP 200 / `isSuccess: true`. This is a framework-level
+fact about how the 2.0 metadata layer resolves and names reverse relations; it is the general form of
+the AIG-specific `contactEmailAddresses.emailAddress` gotcha in the 1.0 `App_Api_Toga2` bridge.
+
+## How it works
+
+- **Reverse relations are metadata-resolved, not implicit.** The V2 engine builds the set of
+  embeddable relations for a model from the model metadata. A **forward** FK (parent points at one
+  child) resolves from the parent model's own FK field. A **reverse** hasMany (many children point
+  back at this parent) is resolved by scanning **child** models for a `FOREIGNKEY_MODEL` constant that
+  targets this model — the engine walks the child side to discover "who points at me".
+- **Naming convention — camelCase plural of the child model.** A discovered reverse collection is
+  exposed under the **camelCase plural of the child model name**. So children modeled as
+  `ContactEmailAddress` (with `FOREIGNKEY_MODEL` → `Contact`) surface on the parent as
+  `contactEmailAddresses`; a nested field of that collection is dotted, e.g.
+  `contactEmailAddresses.emailAddress`. Get the pluralization/casing exactly right — a mismatched name
+  is treated as an unknown field and simply yields nothing rather than an error.
+- **Whitelist-gated serialization.** The engine only serializes a reverse collection that appears in
+  the requested `fields` list (for the library options DSL, the nested-array form
+  `['contactEmailAddresses' => ['emailAddress']]`). Omit it and the collection is silently skipped —
+  it is opt-in, not opt-out. There is no default depth that pulls reverse hasMany collections in for
+  you.
+- **Consuming a reverse collection is therefore a two-part change.** Any code that wants to read a
+  related collection off a parent must (1) add the collection (and the specific child fields) to the
+  **fetch `fields` whitelist**, and (2) add the **consuming code** that reads it. Adding only the
+  consumer leaves the key absent at runtime; adding only the field silently fetches data nobody uses.
+
+## Relationship to ACL embedding
+
+This whitelist gate is **orthogonal to** the child-record ACL gate documented in
+[nested-fk-acl-embedding.md](nested-fk-acl-embedding.md). Naming a reverse collection in `fields` is
+necessary but not sufficient: each embedded child record is still re-checked against its own
+`AclRecordPermissions`, and an ungranted child is silently dropped. A missing nested collection can be
+caused by **either** an omitted `fields` entry **or** a missing child-record ACL grant — check both.
+
+## Gotchas
+
+- **Silent, not erroring.** An unlisted (or misspelled) reverse collection produces no `messages[]`
+  entry — the symptom is purely a missing key in `data`. Confirm the exact camelCase-plural name from
+  the child model before assuming a data problem.
+- **The 1.0 bridge hit this concretely.** TRUE-79401 needed
+  `contactEmailAddresses.emailAddress` added to the `/contacts` fetch `fields` list in
+  `App_Api_Toga2` before the 1.0 sync could read a contact's full email list — see
+  [App_Api_Toga2 — TOGa2 API Client & bridge](../../../../1.0/apps/library/features/toga2-api-client-and-bridge.md).
+
+## Change history
+
+- 2026-07-28 — Captured the framework-level rule (split out of the TRUE-79401 library gotcha): V2
+  reverse hasMany collections are resolved via the child model's `FOREIGNKEY_MODEL`, exposed under the
+  camelCase plural of the child model, and are **only** serialized when explicitly named in the fetch
+  `fields` whitelist — otherwise the key is silently absent (200 / `isSuccess:true`, no message).
+  Orthogonal to, and stacks with, the child-record ACL embedding gate. (mhammontree)
+</content>
+</invoke>

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 40 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 34 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 18 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 19 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/knowledge/clients/aig/profile.md

@@ -5,11 +5,12 @@ apps:
   - _underscore
   - api2
   - dbchanges2
+  - library
 project: API
 client: aig
 type: profile
 status: active
-updated: 2026-06-19
+updated: 2026-07-28
 owners: ["mhammontree"]
 files: []
 related:
@@ -35,6 +36,10 @@ go out under the Staples Protection Plan brand and link to `staplesprotection.to
   NetSuite item/SO/invoice traits).
 - **`dbchanges2`** — `Client_Aig/` schema + reference-data migrations (e.g. the SaleItem code
   catalog in `Client_Aig.Items`).
+- **`library` (1.0)** — the `App_Api_Toga2` bridge syncs 2.0 AIG contacts/entitlements down into the
+  legacy 1.0 `TOGA_AIG` DB (`Customers`/`ServiceRequests`), run by a worker cron every ~10 min. Note
+  the two AIG databases: **`TOGA_AIG`** = V1 legacy sync target; **`Client_Aig`** = V2 prod tenant. See
+  [App_Api_Toga2 bridge](../../1.0/apps/library/features/toga2-api-client-and-bridge.md).
 
 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.463",
+  "version": "1.0.465",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",