toga-ai 1.0.399 → 1.0.400

package/knowledge/2.0/apps/_underscore/features/assortment-name-translation.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-26
+updated: 2026-07-21
 owners: ["bala"]
 files:
   - _underscore/Model/Client/AssortmentTranslation.php
@@ -25,9 +25,15 @@ Serves Assortment (product-grouping) **names** in multiple languages by adding a
 English stays in `Assortments.name`; the sidecar holds only non-English overlays. Because the
 translation layer is fully metadata-driven (see
 [Language Translation Layer](../../api2/features/language-translation-layer.md)), wiring this up
-required **no api2 code change** — only a new table, model, Core record registration, ACL grant,
-and a single field link. Compass Canada's French (fr-CA) assortment names are seeded as the first
-consumer.
+required only a new table, model, Core record registration, ACL grant, and a single field link.
+Compass Canada's French (fr-CA) assortment names are seeded as the first consumer.
+
+> **Correction (2026-07-21):** the original "no api2 code change needed" claim was only true for the
+> **FK/top-level** read paths. Assortment names are surfaced on the storefront **category browse** via a
+> `join=` request (`Assortments.name`), and the joined-select-fields read path did **not** consult the
+> sidecar — it copied the raw SQL column straight into the response, so the seeded French names stayed
+> English there. That required a real api2 change (the 5th serialization site) — see the
+> [Language Translation Layer](../../api2/features/language-translation-layer.md) 2026-07-21 change history.
 
 ## Key files / entry points
 
@@ -51,8 +57,10 @@ The mechanism itself is the data-driven translation layer documented in
 4. **The field link (what makes it translate automatically).** The translatable `Assortments.name`
    RecordField gets its `Core.RecordFields.translationRecordFieldId` set to the sidecar's `name`
    RecordField. The api2 V2 layer reads `translationRecordFieldId` for every field and automatically
-   returns the sidecar value for the caller's resolved language (falling back to English when absent) —
-   so assortment names now translate **without any api2 code change**.
+   returns the sidecar value for the caller's resolved language (falling back to English when absent).
+   This works with no api2 code change for FK/top-level reads; the storefront's `join=` (joined-select)
+   read path additionally required the 5th-serialization-site fix landed 2026-07-21 (see the correction
+   note above and the Language Translation Layer doc).
 5. **ACL.** A full ACL chain grants the **Base** role read/write on the new record. Because the
    record's `aclDatabase = 'CLIENT'`, the grant lives in each client DB — see
    [ACL Permission Chain](./acl-permission-chain.md).
@@ -75,6 +83,11 @@ The mechanism itself is the data-driven translation layer documented in
 
 ## Change history
 
+- 2026-07-21 — Correction: the "no api2 code change needed" claim held only for FK/top-level reads. The
+  storefront category browse surfaces `Assortments.name` via a `join=` request, and the joined-select read
+  path in api2 did not consult the sidecar (raw column copied through), so seeded fr-CA names stayed English
+  there. Fixed by the 5th-serialization-site change in the Language Translation Layer (V2.php); no change to
+  this sidecar/model/metadata was required. (bala)
 - 2026-06-26 — Initial build: `AssortmentTranslations` sidecar table + `_Model_Client_AssortmentTranslation`
   model + `Core.Records` 332 registration + `translationRecordFieldId` link on `Assortments.name` + Base-role
   ACL chain. Reuses the existing metadata-driven translation layer, so no api2 code change was needed.

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-14
+updated: 2026-07-21
 owners: ["jcardinal", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -110,8 +110,11 @@ 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
+serialization site `getTranslatedFieldValue($record, $field, $sourceModel, $defaultValue)` is called.
+There are now **five** serialization sites, all of which must route through the helper: (1) top-level
+full-model fields, (2) custom-field options, (3) foreign-key child objects, (4) inherent-child arrays
+(both the specific-fields and the all-fields/expand-everything branches), and (5) **joined-select
+fields** (fields requested from a `join=` table, e.g. `Assortments.name`). 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 fallback warning. The warning now carries the
@@ -119,6 +122,21 @@ missing record's `uuid` in its `identifiers` and dedupes per-field-**and**-per-r
 (key `recordFieldId:uuid`) rather than once-per-field — so every record lacking a translation for a
 field is reported individually.
 
+**Joined-select fields (site 5) — how the source row is reached.** A `join=` field's value arrives as
+a flat SQL column (`$row->{Alias_field}`), so the helper needs the joined row's identity to load its
+sidecar. In the LIST/GET branch of `processRoutePairs` (joined-select SQL build ~L3700-3800,
+serialization ~L4038-4060): when `shouldTranslate()` is true and a selected joined field is translatable
+(`lookupRecordFieldByRecordIdAndField` + `lookupTranslatableFieldByRecordFieldId`), the SQL build also
+SELECTs that joined table's primary key (`` `Alias`.`id` AS `Alias_id` ``), tracked in
+`$joinedTableRecordsByAlias` and `$joinedTablePrimaryKeyAliasByAlias`; the hidden PK column is only
+appended when not already requested (`in_array` guard). At serialization the joined source model is
+instantiated by that PK (`new $joinedSourceModelName((int)$row->$alias)`) and each joined value routes
+through `getTranslatedFieldValue()`. English and API-credential/public traffic is byte-identical (all
+new logic gated behind `shouldTranslate()`, which is false for en / API / public — no extra SQL column,
+no extra model load, output unchanged). This is why a metadata-only sidecar (e.g. `AssortmentTranslations`)
+still needed an api2 code change to translate on the `join=` read path even though FK/top-level reads
+worked with no code change.
+
 **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.
@@ -191,6 +209,25 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
   (matching `ItemTranslations`) while the source fields are `utf8mb4_0900_ai_ci`. Ad-hoc queries that
   compare a sidecar string against a source string must add `COLLATE utf8mb4_bin` or MySQL throws a
   collation-mismatch error.
+- **GROUP BY gotcha on translatable joined fields (site 5).** The sibling joined-field code pushes each
+  selected joined field into `$groupBy` under aggregates; the hidden PK column added for translation must
+  **also** be pushed to `$groupBy` when `!empty($aggregateFunctionFields)`, or a non-English list request
+  combining a translatable `join=` with an aggregate/`group=` throws MySQL 1055 under `ONLY_FULL_GROUP_BY`.
+  Mirror the sibling `$groupBy[]` push for the PK column.
+- **DISTINCT granularity (site 5).** The list path always runs `SELECT DISTINCT`, so adding the hidden PK
+  to the SELECT can in theory change DISTINCT granularity. Only reachable with distinct + join + a
+  translatable joined field whose rows share values but differ by PK; verified harmless for the real
+  storefront query (a `WHERE` pinning one assortment yields the same 4 rows). Worth checking if a
+  translatable join is added to a query that relies on DISTINCT collapsing duplicate rows.
+- **Per-row cost on translatable-join lists (site 5).** `getTranslatedFieldValue` dereferences the source
+  model key via `_Model __get`, forcing a full row load, so ~2 queries per row (source + sidecar) for
+  non-English translatable-join lists — consistent with the feature's per-row-load tradeoff. Candidate
+  future optimization: let the helper accept a known id instead of a live `_Model`.
+- **Pre-existing (not introduced by site 5): `join=`/`ojoin=` identifiers are unvalidated.** Table/alias/
+  ON-clause identifiers flow from the query string into SQL with no validation/escaping (`V2.php` ~L3416-3463,
+  `parseOptionsJoin` ~L7874-7920). The new PK-select line reuses the same already-tainted `$tableAlias` as the
+  adjacent pre-existing lines, so it adds no new injection class — but the underlying tainted-identifier path
+  is a standing concern flagged for separate follow-up.
 - Reading a possibly-absent magic field off a generic `_Model` needs `array_key_exists(...)` +
   `__get` — `isset()`/`?? null` always read false/null. See
   [_Model magic-field access](../../_underscore/features/model-magic-field-access.md); this was the
@@ -202,6 +239,20 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
 
 ## Change history
 
+- 2026-07-21 — Wired translation into the **joined-select-fields** path (the 5th and final read-path
+  serialization site) in `V2.php` `processRoutePairs` (joined-select SQL build ~L3700-3800, serialization
+  ~L4038-4060). `join=` fields (e.g. `Assortments.name`) previously copied the raw SQL column straight into
+  the response and never consulted the sidecar, so Compass Canada's already-seeded French assortment/category
+  names stayed English on the storefront category browse. Fix (gated behind `shouldTranslate()`, so en/API/
+  public output is byte-identical): SELECT the joined table's PK as a hidden `` `Alias`.`id` AS `Alias_id` ``
+  (tracked in `$joinedTableRecordsByAlias`/`$joinedTablePrimaryKeyAliasByAlias`, `in_array`-guarded), then at
+  serialization instantiate the joined source model by that PK and route the value through
+  `getTranslatedFieldValue()`. Also fixed a GROUP BY 1055 bug (the hidden PK must be pushed to `$groupBy` when
+  aggregates are present). Noted the DISTINCT-granularity edge, the ~2-queries-per-row cost, and that the
+  pre-existing unvalidated `join=` identifier path is unchanged (no new injection class). No toga2-commerce or
+  DB/metadata change needed — sidecar rows, the `Assortments.name` `translationRecordFieldId` link, and the
+  fr-CA storefront request all already existed. cso: SAFE TO SHIP; php-reviewer: safe after the GROUP BY fix
+  (applied), remaining items non-blocking follow-ups. (bala)
 - 2026-07-13 — Extended the translation layer to item **feature** text: three new sidecar tables
   (`FeatureTranslations`, `ItemCategoryFeatureGroupTranslations`, `ItemFeatureTranslations`; Records
   343/344/345, RecordFields 2442–2457) with `translationRecordFieldId` wired to the source fields,

package/package.json

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