toga-ai 1.0.177 → 1.0.178

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

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
+| [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, expanding later) in multiple languages without forking the schema or breaking English consume | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql |
 | [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 |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | 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**. |  |

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

@@ -0,0 +1,110 @@
+---
+title: Language Translation Layer (audience.language + sidecar tables)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: ["jcardinal"]
+files:
+  - api2/Component/Api/V2/V2.php
+  - _underscore/Model/Core/Setting.php
+  - _underscore/Model/Core/RecordField.php
+  - _underscore/Model/Core/DefaultGlobalSetting.php
+  - _underscore/Model/Client/ItemTranslation.php
+  - dbchanges2/Client/2026-06-23a - ItemTranslations.sql
+  - dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql
+  - dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql
+  - dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql
+related:
+  - ./acl-permission-chain.md
+---
+
+## Summary
+
+Serves the same TOGa data (Item title/description/longDescription, expanding later) in multiple
+languages without forking the schema or breaking English consumers. English stays in the source
+table; per-language overlays live in per-table **sidecar** tables (`ItemTranslations` first).
+The caller's language is resolved once at authentication, surfaced on every response's
+`audience.language`, and embedded in the JWT; reads/writes are redirected to the sidecar in the
+**API layer** (`V2.php`) — the `_Model` ORM is untouched, so workers/crons/cXML keep returning
+base English. Missing translations fall back to English with a warning in `messages[]` (still 200).
+
+## Key files / entry points
+
+- `_underscore/Model/Core/Setting.php` — `SLUG_LANGUAGE` const + `valueIsSet()` helper (the cascade
+  resolver itself lives in V2.php, since it is a language/API concern).
+- `api2/Component/Api/V2/V2.php`:
+  - `resolveSettingValue($slug, $context)` — the 8-layer Settings-cascade resolver (private).
+  - `resolveValidLanguageCode()` — validates the resolved code against `Languages.code`, default `en`.
+  - `getTranslatedFieldValue()` / `loadTranslationSidecar()` / `shouldTranslate()` / `addTranslationFallbackWarning()` — read path.
+  - `extractTranslationWrites()` / `saveTranslationWrites()` — write path.
+  - `lookupTranslatableFieldByRecordFieldId` built in the RecordFields load (~line 200).
+- `_underscore/Model/Client/ItemTranslation.php` — the first sidecar model.
+
+## How it works
+
+**Language resolution (auth time, user auth only).** `resolveSettingValue('language', …)` walks the
+Settings Matrix in order — DefaultGlobal, DefaultApp, ClientGlobal, ClientApp, PersonaGlobal,
+PersonaApp, UserGlobal, UserApp — each overriding the previous when set. A Client/Persona layer with
+`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.
+
+**Which fields are translatable (metadata-driven).** `Core.RecordFields.translationRecordFieldId`
+(new column, positioned after `recordId`) points a source field's RecordField at the sidecar field's
+RecordField. `buildLookups`/RecordFields-load resolves this into
+`lookupTranslatableFieldByRecordFieldId[sourceRecordFieldId] => {sidecarRecordId, sidecarField}`.
+
+**Read path (PHP `_Model::load()`, NOT a SQL JOIN — deliberate choice).** At every response
+serialization site (top-level full-model, custom-fields, FK child, both inherent-child paths)
+`getTranslatedFieldValue($record, $field, $sourceModel, $defaultValue)` is called. When a non-base
+language is active and the field is translatable, it loads the sidecar row for that source row +
+`languageId` (cached per row so multiple fields = one load) and returns the sidecar value if non-null;
+otherwise it returns the English default and queues a deduped `W*` warning.
+
+**Write path.** On create and update, `extractTranslationWrites()` pulls translatable fields out of
+the write set for a non-base language (so the English source is never overwritten), and after the
+source row saves, `saveTranslationWrites()` upserts them into the sidecar for the current language.
+Nested-child translatable writes are NOT auto-redirected — use the dedicated `/v2/item-translations`
+endpoint for those.
+
+## Data model
+
+- `Client.ItemTranslations` — `id, uuid, dtCreated, dtUpdated, itemId (FK Items, RESTRICT),
+  languageId (FK Languages, RESTRICT), title, description, longDescription`; `UNIQUE(itemId, languageId)`.
+  English stays in `Items`; sidecar holds only non-English overlays (null → English fallback).
+- `Core.RecordFields.translationRecordFieldId` — new nullable self-FK (after `recordId`).
+- `Core.Records` 331 = `item-translations` (`aclDatabase='CLIENT'`); `Core.RecordFields` 2233–2239
+  (its fields), 2240 (the self-describing `translationRecordFieldId` field).
+- `item-translations` ACL chain lives in each client DB targeting the Base role — see
+  [acl-permission-chain.md](./acl-permission-chain.md).
+
+## Client variations
+
+None — uniform across all clients. The sidecar table + ACL ship via `dbchanges2/Client/` (all client DBs).
+
+## Gotchas / known issues
+
+- The resolver/read/write deliberately use `_Model::load()` per row, not a SQL JOIN/COALESCE — less
+  SQL-efficient but the team's chosen approach; the sidecar is cached per row to avoid N-per-field loads.
+- `audience.language` reflects the *requested* language even if a given field lacks a translation; the
+  per-field fallback warning signals the English fallback.
+- The base language is `en`; when the resolved language is `en` (or API auth) all translation logic is
+  skipped and responses are byte-identical to pre-feature.
+- Migrations not yet executed at time of writing; needs live verification.
+
+## Change history
+
+- 2026-06-23 — Initial build: audience.language + JWT embedding, ItemTranslations sidecar + metadata +
+  full ACL chain, and translation-aware read/write at the API layer. Also fixed a latent autoload bug
+  by renaming `DefaultFlobalSetting.php` → `DefaultGlobalSetting.php`. (jcardinal)
+
+## Related docs
+
+- [ACL Permission Chain](./acl-permission-chain.md)
+- [api2 Architecture](../architecture.md)

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 11 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 12 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 5 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 6 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 2 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) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/package.json

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