toga-ai 1.0.195 → 1.0.196

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

@@ -7,6 +7,7 @@
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php |
+| [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |

package/knowledge/2.0/apps/_underscore/features/model-magic-field-access.md

@@ -0,0 +1,57 @@
+---
+title: _Model magic-field access (__get without __isset)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: ["jcardinal"]
+files:
+  - _underscore/Model/Core/Model.php
+related:
+  - ../../api2/features/language-translation-layer.md
+---
+
+## Summary
+
+`_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`.
+Because PHP does not route `isset()` / null-coalescing through `__get()`, any `isset($model->field)` or
+`$model->field ?? null` on a magic (DB) field is **always** `false` / `null` — even when the column
+exists and has a value. And a bare `$model->field` read for a column that is **not** on the model
+**throws**. This bites any code that probes for an optional/conditional field on a generic model.
+
+## How it works
+
+- `_Model::__get($name)` resolves a configured DB field and returns its value; for an unconfigured
+  field it throws (not a silent null).
+- There is **no** `_Model::__isset()`, so PHP's `isset()`/`empty()`/`??` short-circuit to "not set"
+  for every magic field before `__get` is ever consulted. This is a PHP language rule, not a bug in
+  the value.
+
+**Safe pattern for a possibly-absent field on a generic model:**
+
+```php
+if (array_key_exists('uuid', $model->getFieldConfig())) {
+    $uuid = $model->uuid; // safe: __get won't throw, field is known to exist
+}
+```
+
+Check `array_key_exists('field', $model->getFieldConfig())` first, then read via `__get`. Do **not**
+gate on `isset($model->field)` or `$model->field ?? $default` — both silently misbehave.
+
+## Gotchas / known issues
+
+- `isset($model->magicField)` / `$model->magicField ?? null` are **always** false/null for DB-backed
+  magic fields. Use `getFieldConfig()` + `array_key_exists` to test presence.
+- A bare `__get` on an unconfigured field **throws** — never read a maybe-absent field without the
+  `getFieldConfig()` guard.
+- This surfaced as a missing `uuid` in the API translation-layer fallback warning — see
+  [Language Translation Layer](../../api2/features/language-translation-layer.md).
+
+## Change history
+
+- 2026-06-25 — Documented the `__get`-without-`__isset` gap and the `getFieldConfig()` +
+  `array_key_exists` safe-read pattern, discovered while debugging a missing `uuid` in the API2
+  translation fallback warning. (jcardinal)

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

@@ -3,7 +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 |
+| [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, api2/Component/Api/V2/Response/Response.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

@@ -6,10 +6,11 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
+updated: 2026-06-25
 owners: ["jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
+  - api2/Component/Api/V2/Response/Response.php
   - _underscore/Model/Core/Setting.php
   - _underscore/Model/Core/RecordField.php
   - _underscore/Model/Core/DefaultGlobalSetting.php
@@ -20,6 +21,7 @@ files:
   - dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql
 related:
   - ./acl-permission-chain.md
+  - ../../_underscore/features/model-magic-field-access.md
 ---
 
 ## Summary
@@ -55,6 +57,19 @@ persona** (in the user's persona order) that sets it wins. The resolved code is
 response as `audience.language`. API-credential auth gets no language. Token refresh copies the claim,
 so a language change requires re-authentication.
 
+**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
+that does **not** exist in `Languages` now **fails authentication** with HTTP 400
+`EV-16 DEFINED_MESSAGE_ERROR_INVALID_LANGUAGE_SETTING` (validation group, defined in `Response.php`),
+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.
+
+**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
+`addDefinedMessage(EV-16)` + `data = null`. See Gotchas — do **not** convert this to an
+`is_null($this->response->status)` guard.
+
 **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
@@ -65,7 +80,10 @@ serialization site (top-level full-model, custom-fields, FK child, both inherent
 `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.
+otherwise it returns the English default and queues a fallback warning. The warning now carries the
+missing record's `uuid` in its `identifiers` and dedupes per-field-**and**-per-record
+(key `recordFieldId:uuid`) rather than once-per-field — so every record lacking a translation for a
+field is reported individually.
 
 **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
@@ -96,6 +114,26 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
   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.
+- **"Why isn't my language setting applying?"** A `ClientGlobalSettings` row with `isOverridable = 0`
+  **locks** the value against all downstream persona/user layers — a `UserGlobalSettings` (or persona)
+  override never wins while the client-global layer is locked. This is by design (the 8-layer cascade
+  with `isOverridable` locking). To let user/persona overrides apply, the locking layer must be
+  `isOverridable = 1` (or its value cleared). The cascade itself is correct — this is a data-config
+  gotcha, not a code bug.
+- **Namespace gotcha in `V2.php` (`namespace api;`).** The api-namespaced classes
+  (`_Component_Api_V2_Response`, `_Component_Api_V2_Response_Message`) must be referenced **unqualified**
+  (resolves to `api\…`) or with the full `\api\_Component_Api_V2_Response_Message`. A bare leading
+  backslash (`\_Component_Api_V2_Response_Message`) forces the global namespace and throws
+  `EO-1 "Could not find required file"` via the autoloader. The translation fallback-warning code hit this.
+- **Do NOT guard the auth-mint finalization with `is_null($this->response->status)`.** The auth response
+  auto-adds client `name` + user `firstName`/`lastName` and runs `processRoutePairs()`, which sets
+  `$this->response->status` to `200` **before** finalization. An `is_null` guard there suppresses the
+  `201` + tokens and yields a broken `200`/`data:null` login. Branch on the explicit
+  `$invalidLanguageSetting` flag instead.
+- 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
+  cause of the uuid not appearing in the fallback warning.
 - Migrations not yet executed at time of writing; needs live verification.
 
 ## Change history
@@ -103,6 +141,14 @@ None — uniform across all clients. The sidecar table + ACL ship via `dbchanges
 - 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)
+- 2026-06-25 — Added defined error `EV-16 INVALID_LANGUAGE_SETTING` (HTTP 400, in `Response.php`): a
+  non-empty language code absent from `Languages` now fails auth instead of silently falling back to
+  `en` (empty still defaults to `en`). Documented the auth-mint `201` finalization (branch on the
+  `$invalidLanguageSetting` flag, never an `is_null(status)` guard). Fixed the fallback-warning
+  namespace bug (no bare leading backslash on api-namespaced classes). Fallback warning now includes the
+  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)
 
 ## Related docs
 

package/knowledge/INDEX.md

@@ -15,7 +15,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 13 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 14 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 14 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/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)

package/package.json

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