toga-ai 1.0.422 → 1.0.424

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

@@ -21,7 +21,7 @@
 | [_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 |
 | [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.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 |
+| [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, api2/Controller/Index.php |
 | [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona **names** in multiple languages by adding a per-language **sidecar** table `PersonaTranslations`, reusing the platform's existing metadata-driven | _underscore/Model/Client/PersonaTranslation.php, dbchanges2/Client/2026-07-22b - PersonaTranslations.sql, dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql, dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql, dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql, toga2-commerce/src/pages/Account/view/MySettingsView.tsx |
 | [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, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Client_Compass/2026-07-15f - SalesOrderRecordActionsRemoveDeadConfigRuleOverrides.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php, api2/Component/Api/V2/V2.php |

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-07-16
+updated: 2026-07-23
 owners: ["jcardinal", "rgirish", "mhammontree"]
 files:
   - _underscore/_underscore.php
@@ -344,21 +344,28 @@ multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentNa
 - **`_Database::register()` auto-starts a lazy transaction (since Apr 2 2026, commit `fa7835ed`).** Any code that calls `register()` and then writes to that DB must call `_Database::transactionCommit()` before the request ends — otherwise MySQL silently rolls back all writes when the connection closes. Lazy transactions only materialise on the first write, so read-only callers are unaffected. See `_underscore/Database.php:48`. First discovered when Rate SAML user provisioning silently discarded all new user INSERTs (Jun 2026).
 - **PHP "Unclosed '{'" parse errors report a MISLEADING line number.** When a `.php` file loaded by the autoloader (`Loader.php`) has a dropped/unbalanced brace, PHP reports `Unclosed '{' on line N` where N is the **outermost `class X {` line** and fails at EOF — NOT at the true location of the missing `}`. Worse, because the file loads lazily via the SPL autoloader, the runtime trace points at the **caller** that triggered the autoload (e.g. a `new _Email()` call site), not the broken file. **Triage rule:** for an "Unclosed '{'" error, the real culprit is a missing `}` somewhere between the reported line and EOF of the file that failed to load — run `php -l <file>` (it reports the EOF line) and scan the whole file. **Merge-conflict resolutions are a common source of a single dropped brace** — review the entire merge, not just the one file the error appears to name. (First hit: production 500 EO-1, Jul 2026 — a `}` dropped from `_Email::send()` during merge `685e4a14` surfaced as a trace pointing at the `new _Email()` caller.)
 
-- **A controller exception is silently swallowed by `Route.php`, then masked as a view error.** In
-  dispatch, `_underscore/Route.php` (~lines 462–468) wraps the controller call in
+- **A controller exception used to be silently swallowed by `Route.php`, then masked as a view error
+  (FIXED 2026-07-23).** In dispatch, `_underscore/Route.php` previously wrapped the controller call in
   `catch (Exception $e) { _Database::transactionRollback(); }` — **no log, no rethrow, no debug
-  bypass.** The controller response is left null, so Route.php falls through to its generic throw at
-  line 525: `Failed to determine how to render view for route '<route>' ... './View/Index/<method>.html'`.
-  **Therefore this "Failed to determine how to render view" fatal is very often a MASK for a real
-  exception thrown inside the controller method** (commonly `_Controller_Index::api()`), not a genuine
-  routing/view misconfiguration. A frequent culprit is a DB connect / "Unknown database" failure in
-  `api()`'s **unguarded pre-execute block** (it registers `DB_LOGS` and queries `Logs.Api` for the
-  transactionId-uniqueness check *before/outside* the only try/catch, which wraps just
-  `$api->execute()` at ~line 205). When diagnosing the line-525 error, look for a thrown exception in
-  the controller — not the view layer. (Note: an *unmatched host* does NOT trigger this; `api()`
-  returns a response object that gets JSON-encoded — only a thrown exception hits the line-525 path.)
-  See `2.0/apps/api2/workflows/environment-configuration-and-provisioning.md`. Fix candidate: have
-  Route.php log/rethrow the swallowed exception (or expose it under debug) instead of discarding it.
+  bypass.** The controller response was left null, so Route.php fell through to its generic throw:
+  `Failed to determine how to render view for route '<route>' ... './View/Index/<method>.html'`.
+  That "Failed to determine how to render view" fatal was therefore very often a MASK for a real
+  exception thrown inside the controller method (commonly `_Controller_Index::api()`), not a genuine
+  routing/view misconfiguration. **Fixed 2026-07-23:** the catch now logs the swallowed exception
+  (via `error_log`, message + trace) **and rethrows**, and it catches `\Throwable` (not just
+  `Exception`) so `Error`s (type errors, fatals) surface too — the rollback is still performed before
+  rethrow. The real exception now propagates instead of being reshaped into the misleading line-525
+  view error. When diagnosing, you now see the true controller exception directly. (Note: an
+  *unmatched host* does NOT trigger this; `api()` returns a response object that gets JSON-encoded —
+  only a thrown exception hits this path.) A frequent underlying culprit was a DB connect / "Unknown
+  database" failure in `api()`'s pre-execute block — now separately guarded in api2 (see the api2
+  architecture doc's front-controller section). See
+  `2.0/apps/api2/workflows/environment-configuration-and-provisioning.md`.
+- **Follow-up (deferred, separate ticket): production info-leak from unconditional `display_errors`.**
+  Now that Route.php rethrows, whatever global error handling renders the exception can leak the raw
+  message/trace to the client if `display_errors` is on unconditionally. Confirm `display_errors` is
+  disabled in production and that the framework's error surface returns a sanitized envelope (not a raw
+  stack trace) to API consumers. Not yet done — tracked as a follow-up.
 
 ## Change history
 - 2026-06-11 — Documented lazy transaction gotcha in `_Database::register()` (rgirish)
@@ -367,3 +374,4 @@ multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentNa
 - 2026-07-02 — Fixed framework-wide `FIELD_STORAGE` write-drop and folder-read bugs in `Model.php`; noted the remaining unconditional-refetch dirty-read follow-up. (mhammontree)
 - 2026-07-07 — Documented `_Query` writes-only async mode (`isAsync` → Worker `Infrastructure/Database/Query`) in the database-architecture section, linked `features/async-query-execution.md`, and noted the SQS-first `_Worker::runTask()` enqueue departure (caller does no MySQL; worker tier creates the row on pickup). (jcardinal)
 - 2026-07-16 — Documented the misleading "Unclosed '{'" parse-error gotcha (autoloader reports the outermost `class {` line / caller trace, not the true dropped-brace location; merge conflicts a common cause). First hit production 500 EO-1 via a dropped `_Email::send()` brace. (jcardinal)
+- 2026-07-23 — Fixed the Route.php swallow→mask gotcha: the controller-call catch now log+rethrows and catches `\Throwable` (not just `Exception`), so the true controller exception surfaces instead of the misleading line-525 "Failed to determine how to render view" fatal. Noted the deferred production `display_errors` info-leak follow-up. (jcardinal)

package/knowledge/2.0/apps/_underscore/features/per-client-database-connections.md

@@ -6,12 +6,13 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-09
+updated: 2026-07-23
 owners: ["dfranks", "jcardinal", "mhammontree", "apeterson"]
 files:
   - _underscore/Database.php
   - _underscore/ApiRequest.php
   - _underscore/Model/Client/Logs/Api.php
+  - api2/Controller/Index.php
 related:
   - ../architecture.md
   - ../workflows/local-db-refresh-from-beta.md
@@ -89,12 +90,29 @@ registration is region-aware in `api2/Controller/Index.php`; the alias const is
   set from beta — see [Refreshing a local dev DB from beta](../workflows/local-db-refresh-from-beta.md).
   This is a **local-environment** gap, not a code bug — do not "fix" it by disabling logging in
   shared code.
+- **The shared Core Logs DB (`DB_LOGS`) has the same trap — and its name is resolved dynamically,
+  so "I have all the databases installed" can still fail.** api2's `Controller/Index.php::api()`
+  bootstrap registers `DB_LOGS` using a schema name read from a **`Core.Database` row**
+  (`id = CORE_LOGS_DATABASE_ID`), not a fixed literal. A Logs DB you created locally whose *name*
+  doesn't match that Core row still reads as **missing** → `mysqli_connect` `Unknown database`. Match
+  the local schema name to the `Core.Database` row (or fix the row), don't just "create a logs DB."
+- **This Core Logs bootstrap runs OUTSIDE the try/catch that wraps `$api->execute()`** (the env
+  lookup, region/host `search()`, `_Model_Core_Database` instantiation, and `_Database::register()`
+  for `DB_CORE`/`DB_LOGS` all run before the guarded block at ~line 202 of `Controller/Index.php`).
+  A connect failure here threw past `api()` and got masked by `Route.php` as the misleading line-525
+  "Failed to determine how to render view" error — see the Route.php swallow→mask gotcha in
+  [_underscore architecture](../architecture.md#gotchas--known-issues).
 - Related 1.0 analogue: the legacy `App_` worker has the same hazard writing to `Logs.API`
   (`db_logs`) — the laptop trap there is documented separately in the worker NetSuite bootstrap
   notes.
 
 ## Change history
 
+- 2026-07-23 — Documented the shared **Core Logs** (`DB_LOGS`) analogue of the logs trap: its schema
+  name is resolved from a `Core.Database` row (`id = CORE_LOGS_DATABASE_ID`) in
+  `api2/Controller/Index.php::api()`, so a name-mismatched local Logs DB still reads as missing; and
+  this bootstrap runs outside `api()`'s guarded block, so a connect failure was masked by Route.php's
+  line-525 view error. (jcardinal)
 - 2026-07-09 — Linked the new [Running a 2.0 app locally](../workflows/running-a-2.0-app-locally.md) runbook, which frames these three connections as one requirement of a full local browser run. (mhammontree)
 - 2026-07-09 — Linked the new [local-DB-refresh-from-beta workflow](../workflows/local-db-refresh-from-beta.md)
   from the logs-trap fix (refreshing all local schemas from beta covers the missing `Logs_<Id>`). (apeterson)

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: architecture
 status: active
-updated: 2026-07-07
+updated: 2026-07-23
 owners: [jcardinal, bala]
 files:
   - api2/Controller/Index.php
@@ -65,8 +65,21 @@ lands in `api()`.
 - **CORS:** permissive `Access-Control-Allow-*`; returns 200 for `OPTIONS` preflight.
 - **`/health`:** 200 + empty object (EB/LB probe — keep it working).
 - **Sentry:** initialized per request; EC2 instance metadata attached.
-- **Core DB:** registers `Core` (`DB_CORE`), preferring a region-local read host
-  (`CORE_READHOST`). **Core Logs DB** (`DatabaseHost` id 11) registered region-aware as `DB_LOGS`.
+- **Core DB bootstrap (now guarded, 2026-07-23):** registers `Core` (`DB_CORE`), preferring a
+  region-local read host (`CORE_READHOST`), then registers the **Core Logs DB** region-aware as
+  `DB_LOGS`. This whole block runs in a **pre-execute phase that executes *before* the `execute()`
+  try/catch**, so a failure here historically escaped that guard and became a fatal. Two traps:
+  (1) the Core Logs **schema name is resolved from a `Core.Database` row** (`id =
+  CORE_LOGS_DATABASE_ID`), so a **name-mismatched local Logs DB** (one whose actual schema name
+  differs from the Core-recorded name) reads as **missing** and `mysqli_connect` throws `Unknown
+  database` — a common local-dev breakage, not a code bug. (2) That connect failure used to be a
+  fatal. **Fixed 2026-07-23:** the pre-execute Core/Logs bootstrap is wrapped in a
+  `try/catch (\Throwable)` that, on failure, returns the standard **`INVALID_CONFIGURATION`**
+  error envelope and reports to **Sentry** instead of dying with an unguarded fatal. Note the
+  rollback in that catch is a **guarded no-op** — with no transaction started yet,
+  `_Database::transactionRollback()` short-circuits safely (`Database.php:219–226`). See
+  [_underscore architecture — Route.php log+rethrow gotcha](../_underscore/architecture.md) for the
+  upstream masking behavior this pairs with, and the per-client-database-connections feature doc.
 - **Host dispatch:** lowercase `HTTP_HOST`, strip trailing domain, switch on the remainder.
 - **Transaction/logging invariant (JSON path):** wraps the call in transactions; on
   **success** commit logs then data; on **failure** commit logs but **roll back data**; on
@@ -153,6 +166,12 @@ Core/Client/Logs DB passwords, **AWS access key id + secret**, and third-party A
 carries a **GitHub PAT**. These should be rotated and moved to SSM Parameter Store / EB env
 properties. **Flag this if you touch config or deploy.**
 
+**Follow-up (deferred, separate ticket): raw exception disclosure to clients.** The error paths that
+surface a caught `\Throwable` (now that Route.php rethrows and the bootstrap guard reports failures)
+must not return raw `getMessage()`/`getTrace()` output in the client-facing envelope — that leaks
+internal paths, schema names, and stack frames to API consumers. Sanitize the client envelope
+(generic message + code; full detail to Sentry/logs only). Not yet done.
+
 ## When making changes here
 
 - **Adding/altering an endpoint is usually a data change, not code** — define `Records` +
@@ -167,3 +186,6 @@ properties. **Flag this if you touch config or deploy.**
   the duplicate check.
 - Preserve the commit-logs / rollback-data-on-failure invariant when editing the controller
   or `execute()`.
+
+## Change history
+- 2026-07-23 — Documented the now-guarded Core/Logs DB bootstrap in the front controller: the pre-execute block runs before the `execute()` try/catch, the Core Logs schema name is resolved from a `Core.Database` row (`id = CORE_LOGS_DATABASE_ID`) so a name-mismatched local Logs DB reads as missing, and the failure is now wrapped in `try/catch (\Throwable)` returning `INVALID_CONFIGURATION` + Sentry instead of a fatal (guarded no-op rollback, `Database.php:219–226`). Added the deferred raw-getMessage/getTrace client-disclosure follow-up to the Security note. (jcardinal)

package/knowledge/2.0/apps/toga-blox/workflows/dynamic-publish-pipeline.md

@@ -6,8 +6,8 @@ project: TOGa Blox
 client: shared
 type: workflow
 status: active
-updated: 2026-07-21
-owners: [jcardinal]
+updated: 2026-07-23
+owners: [jcardinal, apeterson]
 files:
   - toga-blox/.github/workflows/publish.yml
   - toga-blox/src/utils/getFontAwesomeIcon.tsx
@@ -35,6 +35,26 @@ resolve in a consuming app's build, or touching `publish.yml`.
 - **Every** branch (including `_production`) publishes a **prerelease** version
   `X.Y.Z-<mode>.<run>` under dist-tag `<mode>`. There is no longer a production special case.
   Verified live: `production:1.0.315-production.96`, `sandbox-client:1.0.315-sandbox-client.97`.
+  Observed 2026-07-23: `sandbox-client:1.0.317-sandbox-client.101`, `sandbox-dev:1.0.316-sandbox-dev.102`.
+
+### Version derivation (CI owns the suffix; dev owns only the base)
+
+- CI reads `version` from `package.json`, **strips any `-<suffix>`**, does **`patch + 1`**, then
+  appends `-<mode>.<GITHUB_RUN_NUMBER>`. So base `1.0.317` on `_sandbox-client` run 104 publishes
+  `1.0.318-sandbox-client.104` under dist-tag `sandbox-client`.
+- **The developer controls only the BASE version** committed in `package.json` on the feature
+  branch. **Never hand-write the `-<mode>.N` prerelease suffix** — CI generates it. There is no
+  manual `npm publish`; CI is the only publisher.
+
+### Deploy procedure (e.g. `_sandbox-client`)
+
+1. Ensure a clean tree; optionally bump the base version in `package.json` on the feature branch.
+2. Merge the feature branch into `_sandbox-client`, then push (this triggers the CI publish).
+3. Monitor with `gh run watch`; verify with `npm dist-tag ls @agilant/toga-blox`.
+4. Consuming apps (e.g. `toga25-supply` on `_sandbox-client`) install from the `sandbox-client`
+   dist-tag or a pinned `1.0.x-sandbox-client.N` version and must **re-install** to pick up a new
+   build. The `deploy-sandbox-client` project skill (`.claude/skills/` in this repo) drives this
+   procedure end-to-end.
 
 ### What was removed (and why it's safe)
 
@@ -66,6 +86,12 @@ environment needs its own maintained `_<mode>` branch in `toga-blox-npm`.
 - **Publish before build.** `npm install @agilant/toga-blox@<mode>` fails `ETARGET No matching
   version` in the app build until this repo has published that channel. GitHub Actions runs the
   workflow version *on the pushed branch*, so the branch must carry the current `publish.yml`.
+- **`publish.yml` has diverged across branches (2026-07-23).** The dynamic `_*` wildcard trigger
+  lives on `_sandbox-client`, but older/feature branches (e.g. `feature-new-table`) still carry the
+  *old* `publish.yml` that triggers only on `_production/_gamma/_beta`. Because Actions runs the
+  copy on the pushed branch, a new `_<mode>` channel will **not** publish unless the branch you push
+  carries the wildcard-trigger version. When standing up a new channel, merge from a branch that has
+  the dynamic `publish.yml` (or update it first).
 - **FontAwesome v7 `style`-prop TS2322** (fixed 2026-07-21 in `getFontAwesomeIcon.tsx`, and a
   reusable pattern for any consumer). FA v7 types the `FontAwesomeIcon` `style` prop as
   `CSSProperties & CSSVariables`, where `CSSVariables` requires a `--fa-*` custom-property index
@@ -78,6 +104,11 @@ environment needs its own maintained `_<mode>` branch in `toga-blox-npm`.
   the pattern the consuming apps should follow (see the commerce workflow's secret-hygiene note).
 
 ## Change history
+- 2026-07-23 — Documented CI version derivation (strip suffix → patch+1 → append `-<mode>.<run>`;
+  dev owns only the base version, never the suffix) and the `_sandbox-client` deploy procedure now
+  driven by the `deploy-sandbox-client` project skill. Recorded that `publish.yml` has diverged
+  across branches: the dynamic `_*` trigger is on `_sandbox-client` while older/feature branches
+  still trigger only on `_production/_gamma/_beta`. (apeterson)
 - 2026-07-21 — Made `publish.yml` fully dynamic: trigger `_*`, branch→dist-tag by stripping the
   leading underscore (mode == channel 1:1), every branch (incl. `_production`) publishes a
   `X.Y.Z-<mode>.<run>` prerelease; removed the `_production`→`latest` special case (workflow no

package/package.json

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