toga-ai 1.0.295 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.295",
+  "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",