toga-ai 1.0.294 → 1.0.296

package/knowledge/2.0/apps/api2/features/language-translation-layer.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-06-25
-owners: ["jcardinal"]
+updated: 2026-07-09
+owners: ["jcardinal", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
   - api2/Component/Api/V2/Response/Response.php
@@ -54,8 +54,27 @@ PersonaApp, UserGlobal, UserApp — each overriding the previous when set. A Cli
 `isOverridable = 0` **locks** the value against all later layers. For the persona layers, the **first
 persona** (in the user's persona order) that sets it wins. The resolved code is validated against
 `Languages.code` (fallback `en`), embedded in the JWT `id.language` claim, and echoed on every
-response as `audience.language`. API-credential auth gets no language. Token refresh copies the claim,
-so a language change requires re-authentication.
+response as `audience.language`. API-credential auth gets no language.
+
+**Language re-resolution on token refresh (user tokens only).** `/auth/refresh` now re-resolves the
+user's language and embeds it in the newly minted tokens, so a language switch takes effect on the
+next hourly refresh **without a full re-login** (previously the refresh path copied the decoded JWT
+payload verbatim and only reset `exp`/`iat`, so a language change was invisible until re-auth). The
+re-resolution runs **only** for user tokens — it reads `id.client.user.uuid` off the token and skips
+entirely for API-credential and public tokens (no language claim). It rebuilds the resolution context
+from the existing token — loads `_Model_Client_User` by `uuid` (→ `userId`), `_Model_Core_App` by
+`id.app.uuid` (→ `appId`), and takes `personaIds` from `id.client.personas` — then calls the **same**
+private `resolveSettingValue(slug: _Model_Core_Setting::SLUG_LANGUAGE, context: {appId, personaIds,
+userId})` helper the login path uses (same 8-layer cascade; the client DB is already registered at this
+point). The resolved code is validated against `_Model_Client_Language` (load by `code`):
+- **Valid** → sets `$this->jwtPayload->id->language` to the resolved code.
+- **Unset/empty** → defaults to `'en'`.
+- **Invalid** (non-empty but absent from `Languages`) → **keeps the token's current language** and adds
+  a `WZ-4` warning (see below). It deliberately does **not** fail the refresh — a bad setting must not
+  log an active user out on their hourly refresh (contrast the login path, which hard-fails with EV-16).
+
+Placement is load-bearing: the `id.language` mutation happens **after** client-DB registration and
+**before** both the access and refresh tokens are signed, so both new tokens carry the updated language.
 
 **Invalid-language hard failure (auth time).** The resolved code is validated against the client's
 `Languages` table. An **unset/empty** setting defaults to `en` (no error). But a **non-empty** code
@@ -64,6 +83,14 @@ that does **not** exist in `Languages` now **fails authentication** with HTTP 40
 with the offending `language` code in the message `identifiers` — instead of silently falling back to
 `en`. A misconfigured language must surface loudly, not silently degrade.
 
+**Invalid-language soft warning (refresh time).** On the refresh path an invalid code is handled with a
+distinct, non-fatal WARNING instead of EV-16: `WZ-4 DEFINED_MESSAGE_WARNING_INVALID_LANGUAGE_SETTING`
+(type WARNING, group VALIDATION, `{language}` identifier placeholder; defined in `Response.php`, added
+via `addDefinedMessage(...)` so the warning has a stable catalogued code). Because it is a WARNING it
+carries no `status` key and does not change the response status — the refresh succeeds and the token
+keeps its current language. This is deliberately softer than EV-16 (status 400), which would fail the
+refresh and log the user out.
+
 **Auth-mint status finalization (subtle).** The auth success path sets `status = 201` and attaches the
 tokens. EV-16 is signalled by a local flag `$invalidLanguageSetting` set at the resolution site; the
 finalization branches `if (empty($invalidLanguageSetting))` → `201` + tokens, else
@@ -134,6 +161,9 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
   `__get` — `isset()`/`?? null` always read false/null. See
   [_Model magic-field access](../../_underscore/features/model-magic-field-access.md); this was the
   cause of the uuid not appearing in the fallback warning.
+- **Refresh re-resolution is user-token-only.** If you extend the JWT with new audience-shaped claims,
+  remember the refresh path rebuilds context from the *existing* token (uuid/app-uuid/personas) — it
+  does not re-read anything the token doesn't carry.
 - Migrations not yet executed at time of writing; needs live verification.
 
 ## Change history
@@ -149,6 +179,14 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
   record `uuid` and dedupes per-record (`recordFieldId:uuid`). Documented the `isOverridable = 0`
   client-global lock as a config gotcha. Discovered the `_Model` `__isset` gap behind the missing-uuid
   bug (see linked _underscore doc). Live-tested on the local Compass DB. (jcardinal)
+- 2026-07-09 — `/auth/refresh` now re-resolves the user's language (same `resolveSettingValue` cascade as
+  login) and embeds it in the newly minted access + refresh tokens, so a language switch applies on the
+  next refresh with no re-login (previously refresh copied the JWT payload verbatim, resetting only
+  `exp`/`iat`). User-tokens only (skips API-credential/public — no language claim); mutates `id.language`
+  after client-DB registration and before signing both tokens. Invalid code on refresh is a **soft**
+  non-fatal `WZ-4 WARNING_INVALID_LANGUAGE_SETTING` (new constant in `Response.php`) that keeps the
+  token's current language — vs. login's hard EV-16 400 — so a bad setting can't log an active user out.
+  (TRUE-80064, bala)
 
 ## Related docs
 

package/knowledge/2.0/apps/api2/features/nested-relationship-writes.md

@@ -6,12 +6,13 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-07
-owners: ["bala"]
+updated: 2026-07-09
+owners: ["bala", "mhammontree"]
 files:
   - api2/Component/Api/V2/V2.php
 related:
   - ../architecture.md
+  - ../../../clients/aig/features/entitlement-intake.md
 ---
 
 ## Summary
@@ -57,6 +58,37 @@ rows on every write.
 If you need to link by a business key (like an employee XID), **resolve that key to a uuid in your
 caller first** (e.g. build a `key → uuid` map), then send `{uuid}`.
 
+## Per-API overrides (`Apis_RecordFields`)
+
+The base identifier flags above (`Core.RecordFields.isIdentifier`) can be **overridden per API**
+via rows in a tenant's `Apis_RecordFields` table, read by the V2 resolver's override block
+(`V2.php` ~6926–6936; child policy in `getChildPolicy()` ~8019–8041; loader ~8526–8538). Two
+columns matter:
+
+- **`overrideIsIdentifier`** — overrides whether the field is a searchable identifier for that API.
+- **`overrideChildPolicy`** — overrides link-vs-create for the nested record (e.g. `MATCH_CREATE`
+  = match an existing child by identifier, else create it).
+
+> **Trap: a `NULL` `overrideIsIdentifier` is read as "not an identifier", not "no opinion".**
+> The override block evaluates `!$row->overrideIsIdentifier`, so a `NULL` **unsets** the field
+> from the API's searchable identifiers even when the base `Core.RecordFields` row has
+> `isIdentifier=1`. Any `Apis_RecordFields` row created **only** to set a child policy
+> (leaving `overrideIsIdentifier` NULL) will silently strip that field as an identifier. The
+> nested object then has no searchable identifier and the write fails **EV-12 VALIDATION**
+> (`V2.php:7094`) — the `MATCH_CREATE` that should have saved it never runs on that path.
+> Correct the data with an explicit `overrideIsIdentifier = 1`, or (systemic fix, not yet done)
+> change the code so only an explicit `0` removes an identifier and `NULL` means "no override".
+
+**Build divergence warning.** The `Apis_RecordFields` override feature (reading
+`overrideIsIdentifier`/`overrideChildPolicy`) was introduced 2026-03-20 (api2 commit `624146d`
+"Cache custom fields and API override lookups"). Environments on **older** builds ignore the
+override and keep the base identifier, so a tenant with identical Core metadata + override rows +
+data can behave differently across environments purely by build version. A NULL-`overrideIsIdentifier`
+override row that works on prod (older build) will start throwing EV-12 once prod gets the newer
+build — audit such rows before/with the deploy. First seen in AIG (TRUE-79978): prod resolved,
+beta/QA threw EV-12 on the injected `entitlementFulfillmentType` — see
+[AIG entitlement intake](../../../clients/aig/features/entitlement-intake.md).
+
 ## Gotcha
 
 - **Nested write with only a non-identifier field silently creates duplicates.** This is a
@@ -68,6 +100,11 @@ caller first** (e.g. build a `key → uuid` map), then send `{uuid}`.
 
 ## Change history
 
+- 2026-07-09 — Documented the per-API `Apis_RecordFields` override layer (`overrideIsIdentifier`,
+  `overrideChildPolicy`) and the trap that a `NULL` `overrideIsIdentifier` is read as "not an
+  identifier" (`!$row->overrideIsIdentifier`) — an override row set only for a child policy
+  silently strips the field as an identifier → EV-12 at `V2.php:7094`. Added the build-divergence
+  warning (override feature added 2026-03-20, commit `624146d`). Surfaced by AIG TRUE-79978. (mhammontree)
 - 2026-07-07 — Documented that api2 nested-relationship writes match an existing child **only** by
   identifier (`uuid`); a non-unique custom field is not a match key and forces a new-record insert.
   Correct pattern is `contact: {uuid}` (resolve business keys to uuid in the caller). Surfaced by
@@ -78,3 +115,5 @@ caller first** (e.g. build a `key → uuid` map), then send `{uuid}`.
 - [api2 architecture](../architecture.md) — the V2 CRUD engine (`processRoutePairs`).
 - [Prudential device import + contact linking](../../../clients/prudential/features/device-information-import-and-contact-linking.md)
   — the production incident that exposed this behavior.
+- [AIG entitlement intake](../../../clients/aig/features/entitlement-intake.md) — the TRUE-79978
+  EV-12 that exposed the `Apis_RecordFields` NULL-`overrideIsIdentifier` trap + build divergence.

package/knowledge/clients/aig/features/entitlement-intake.md

@@ -5,12 +5,13 @@ project: API
 client: aig
 type: client-feature
 status: active
-updated: 2026-06-19
+updated: 2026-07-09
 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/features/nested-relationship-writes.md
   - 2.0/apps/api2/architecture.md
   - 2.0/apps/dbchanges2/architecture.md
   - 2.0/apps/_underscore/architecture.md
@@ -42,7 +43,9 @@ the FK can't resolve and intake fails with **"Missing AIG item ID."** Keeping
    - 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.
+     **methods** (`Items_EntitlementFulfillmentMethods`) and injects them into the payload as
+     **name-only** related objects (e.g. `entitlementFulfillmentType: {name: "Repair"}`). AIG
+     never sends `entitlementFulfillmentType`; it is populated entirely by this interceptor.
 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
@@ -118,9 +121,28 @@ this interceptor or use this dual-purpose Items pattern.
   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`.
+- **An `entitlementFulfillmentType` EV-12 VALIDATION error is NOT a bad client payload —
+  it's this interceptor's injected field failing to resolve.** AIG never sends that field;
+  the interceptor injects it as `{name: "Repair"}`. The error means the V2 resolver could not
+  find a searchable identifier for the injected object. Root cause (TRUE-79978) was an
+  `Apis_RecordFields` override row that stripped `name` as an identifier — see
+  [api2 nested-relationship writes → Per-API overrides](../../../2.0/apps/api2/features/nested-relationship-writes.md).
+- **Empty `saleItem.partNumber` silently resolves to the wrong item.** The lookup is
+  `WHERE partNumber = '{$partNumber}' LIMIT 1`; when `partNumber` is `""`, it matches item
+  `id=10` ("2YR Tablet") — the first row with an empty part number — which carries a "Repair"
+  fulfillment type. So a blank part number does not fail loudly; it injects a spurious
+  name-only fulfillment type. The interceptor should guard an empty/failed lookup before
+  injecting (not yet fixed).
 
 ## Change history
 
+- 2026-07-09 — TRUE-79978: root-caused an `entitlementFulfillmentType` EV-12 on beta/QA. The
+  field is injected (name-only) by `prePost`; the beta `Client_Aig.Apis_RecordFields` override
+  row (apiId=2, recordFieldId=1202) had `overrideIsIdentifier=NULL` + `overrideChildPolicy=MATCH_CREATE`,
+  which the newer V2 build reads as "not an identifier", stripping `name` → no searchable id →
+  EV-12. Unblocked with a manual one-row beta data fix (`SET overrideIsIdentifier=1`); prod runs
+  an older build without the override feature so it still resolves. See the api2 feature doc for
+  the shared resolver behavior. (mhammontree)
 - 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)

package/package.json

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