toga-ai 1.0.912 → 1.0.914

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

@@ -44,6 +44,7 @@
 | [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | Legacy `Page::meta()` page-meta resolver + context-scoped `ClientRecordFieldSettings`; open when a grid column header is wrong/camelCase, or a `/pages/meta` pag |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | `_underscore` opens three per-client DB connections (data/logs/archive) per request; open when a local or prod request 500s with `Unknown database`, when resolv |
 | [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona names in multiple languages via a `PersonaTranslations` sidecar (copy of the assortment-translation pattern); open when adding/running persona tr |
+| [Persona nav-visibility gate + user nav pins (keyed by Core.SurfaceElements uuid)](features/persona-nav-visibility-gate.md) | Sidebar-nav persona gate in `_Model_Core_Surface` (`Client.PersonaNavVisibility`) and user nav pins (`Client.UserNavPreferences`), both keyed by Core `SurfaceEl |
 | [Record Change Audit Log (Logs_<Client>.Record / RecordField) — reading a field's history](features/record-change-audit-log.md) | Field-level change audit trail per tenant; open to answer "who changed this field, to what, when" or to tell a direct SQL edit from an in-app change. |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | Engine that mirrors a downstream ItemFulfillment up the SO→PO→SO chain onto every customer-facing SO; open when touching IF creation, bundle scaling, or upstrea |
 | [Sales-order denial reason (`ApprovalDecisions.note`) — capture, the denial-details card, and the read-only workflow mode](features/sales-order-denial-reason.md) | Map of the SO approval denial reason (`ApprovalDecisions.note`) — where it is written, read, and displayed; open when building any denial-reason display, banner |
@@ -53,6 +54,7 @@
 | [Shipping Carriers & Carrier Account Numbers (records, matching, duplication, deletion)](features/shipping-carriers-and-accounts.md) | Per-client `ShippingCarriers` / `ShippingCarrierAccountNumbers` model, how the syncs match/create carrier rows, and the duplication + blank-carrier + pagination |
 | [_String helpers — ASCII-safe HTML entity encoding (and the parseBetween trap)](features/string-html-entity-helpers.md) | `_String` static string utilities: use `encodeToAsciiHtmlEntities` for any dynamic text going into a 2.0 email; open when escaping email text or parsing substri |
 | [Surface FIELD ↔ RecordField binding (maxLength / validationType / isWritable fold-in)](features/surface-field-recordfield-binding.md) | Resolver capability that folds `Core.RecordFields` input-contract metadata (maxLength/validationType/isWritable) onto a surface FIELD element; open when a 2.5 s |
+| [DEFERRED — re-key Client.SurfaceOverrides from numeric Core ids to uuids](features/surface-overrides-uuid-rekey.md) | Deferred: `Client.SurfaceOverrides.surfaceId`/`surfaceElementId` still point at Core rows by numeric id; open before a client's first override rows on an env wh |
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | Runtime for the platform Surface UI layer (`_Model_Core_Surface::resolve`/`metaGroup`, replaces `Page::meta`); open for surface resolution, the override cascade |
 | [Table-View Hyperlink Columns (meta → ACL → computed URL → render)](features/tableview-hyperlink-columns.md) | How a 2.0 table-view column renders its value as a clickable link (`hyperlinkRecordFieldId` → ACL field-read → computed URL → render); open when a configured hy |
 | [TableView joins (TableViewJoins → SQL) — aliasing, chained multi-hop joins, ACL](features/tableview-joins.md) | How `TableViewJoins` rows become a view's join SQL — aliasing, chained multi-hop joins, ACL gating, and the three ways a view breaks; open before adding/rebasin |

package/knowledge/2.0/apps/_underscore/features/persona-nav-visibility-gate.md

@@ -0,0 +1,51 @@
+---
+title: "Persona nav-visibility gate + user nav pins (keyed by Core.SurfaceElements uuid)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-09-29
+owners: [jcardinal]
+files:
+  - _underscore/Model/Core/Surface.php
+  - _underscore/Model/Client/PersonaNavVisibility.php
+  - _underscore/Model/Client/UserNavPreference.php
+  - dbchanges2/Client/2026-09-29a - NavItemSurfaceElementUuidColumns.sql
+  - dbchanges2/Client/2026-09-29b - DropNavItemSurfaceElementIdColumns.sql
+  - dbchanges2/Core/2026-09-29a - UserNavPreferencesNavItemUuidRecordField.sql
+related:
+  - surface-resolver.md
+  - surface-overrides-uuid-rekey.md
+  - ../../dbchanges2/features/surface-layer-schema.md
+---
+
+Sidebar-nav persona gate in `_Model_Core_Surface` (`Client.PersonaNavVisibility`) and user nav pins (`Client.UserNavPreferences`), both keyed by Core `SurfaceElements.uuid`; open before touching nav visibility, pins, or any Client row that points at a Core Surface element.
+
+## Summary
+
+- Gate runs only when the surface `config.renderAs === 'nav'`. Default-deny: a nav element survives only if one of the caller's personas has a `PersonaNavVisibility` grant for it in the request app.
+- Grants and pins store `navItemSurfaceElementUuid` (CHAR(36), lowercase) = `Core.SurfaceElements.uuid`. The numeric `navItemSurfaceElementId` column was dropped 2026-09-29.
+- Rule: never key a Client row to a Core Surface/SurfaceElement by numeric id. Core ids shift when Core is rebuilt or copied to another env; seeded uuids are the same everywhere.
+
+## How it works
+
+1. `_buildBundle` step 5b: `$isNavGated` = `config.renderAs === 'nav'`. False → nothing runs, no element dropped (user menu uses `renderAs='menu'`). Do not widen this check.
+2. App id = `$api->app->id`, else `Surfaces.appId`.
+3. `_grantedNavItemSurfaceElementUuids($personaIds, $appId)`: one query on the client DB (`personaId IN (...) AND appId = ... AND navItemSurfaceElementUuid IS NOT NULL`) → set keyed by lowercase uuid. No personas or no app → empty set → all nav elements hidden.
+4. Per element: drop if `strtolower($element->uuid)` is not in the set.
+5. Cluster-safe: grant uuids are read on the client connection and matched in PHP against the Core elements. No cross-database SQL.
+
+**Pins (`Client.UserNavPreferences`, Core.Records 349):** RecordField 2645 = `navItemSurfaceElementUuid` (2487 = old id field, retired). `prePost` interceptor stamps `userId` from the JWT and `appId` (`$api->app->id`, fallback 34), checks uuid format, lowercases it.
+
+## Gotchas
+
+- Model field is `FIELD_CHAR`, not `FIELD_CHAR_UUID`. `FIELD_CHAR_UUID` auto-generates a value, which would overwrite the FK.
+- Symptom of id drift: sidebar-nav returns only the theme (all elements dropped). Seen on qa-alpha 2026-09-29: Core rebuilt from prod, grants pointed at ids 114-134, local elements were 241-261 (+127).
+- `Client/2026-09-29b` deletes old id-only grants only for a persona+app that already has uuid grants, then sets the uuid NOT NULL. A client never re-keyed fails loud (`Invalid use of NULL`) instead of losing its whole sidebar. Fix: write that client's uuid grant seed (pattern: `Client_True/2026-09-29a`), then re-run.
+- Run order: `Client/2026-09-29a` + client grant seeds → code live → `Client/2026-09-29b` → `Core/2026-09-29b` (removes RecordField 2487).
+- `Client.SurfaceOverrides` still uses numeric Core ids — same risk, deferred: [surface-overrides-uuid-rekey](surface-overrides-uuid-rekey.md).
+
+## Change history
+- 2026-09-29 — Grants + pins re-keyed from numeric SurfaceElements id to uuid; `_grantedNavItemSurfaceElementIds` renamed `_grantedNavItemSurfaceElementUuids` (_underscore `8e299b1b`, dbchanges2 `66ba056`) (jcardinal)

package/knowledge/2.0/apps/_underscore/features/surface-overrides-uuid-rekey.md

@@ -0,0 +1,37 @@
+---
+title: "DEFERRED — re-key Client.SurfaceOverrides from numeric Core ids to uuids"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: deferred
+updated: 2026-09-29
+owners: [jcardinal]
+files:
+  - _underscore/Model/Core/Surface.php
+  - _underscore/Model/Client/SurfaceOverride.php
+related:
+  - persona-nav-visibility-gate.md
+  - surface-resolver.md
+---
+
+Deferred: `Client.SurfaceOverrides.surfaceId`/`surfaceElementId` still point at Core rows by numeric id; open before a client's first override rows on an env whose Core can be rebuilt.
+
+## Summary
+
+Not built. `_Model_Core_Surface::_loadOverrides` matches `SurfaceOverrides.surfaceId` / `surfaceElementId` to Core numeric ids. Same failure as the nav gate before 2026-09-29 ([persona-nav-visibility-gate](persona-nav-visibility-gate.md)): once a client has override rows and Core is rebuilt/copied with different AUTO_INCREMENT ids, overrides silently miss or land on the wrong element.
+
+## How it works
+
+Planned fix (do before first client use on such an env):
+1. Add `surfaceUuid` / `surfaceElementUuid` CHAR(36) to `Client.SurfaceOverrides` (`FIELD_CHAR`, not `FIELD_CHAR_UUID`).
+2. `_loadOverrides`: match by uuid on the client connection, join to Core elements in PHP (no cross-database SQL).
+3. Forward-only re-key seeds per client, then drop the id columns with a fail-loud NOT NULL step (same shape as `Client/2026-09-29b`).
+
+## Gotchas
+
+- Elements seeded with reserved id literals are stable across envs; the risk is elements that took AUTO_INCREMENT ids (e.g. the `navigation` surface's elements). The framework-rules "Bounded exemption — the Surface tables" stays as-is until this is built.
+
+## Change history
+- 2026-09-29 — Recorded as deferred after the nav-gate uuid fix exposed the same numeric-id risk (jcardinal)

package/knowledge/2.0/apps/_underscore/features/surface-resolver.md

@@ -36,6 +36,8 @@ related:
   - sales-order-status-filter-surface.md
   - surface-field-recordfield-binding.md
   - ../../toga25-supply/features/side-navigation-and-default-route.md
+  - persona-nav-visibility-gate.md
+  - surface-overrides-uuid-rekey.md
 ---
 
 Runtime for the platform Surface UI layer (`_Model_Core_Surface::resolve`/`metaGroup`, replaces `Page::meta`); open for surface resolution, the override cascade, vocab/theme/message resolution, client seeding, caching, and 403/empty-bundle debugging.

package/knowledge/2.0/apps/api2/features/health-check-endpoint.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-09-29
 owners: [jcardinal]
 files:
   - api2/health
@@ -32,6 +32,7 @@ The EB/ALB liveness probe (`/health`) is served two ways, and the **load-bearing
 - **`api2/health`** — a one-line static file (`OK`). Apache serves it directly.
 - **`api2/.platform/httpd/conf.d/health_probe.conf`** — comment-only documentation of why the probe is static (no directives; explains the decision at the Apache layer).
 - **Why it works without a rewrite fight:** `api2/.htaccess` only rewrites to `index.php` when the request target is **not a real file** (`RewriteCond %{REQUEST_FILENAME} !-f`). Because `health` is a real file, the rewrite is skipped and Apache serves it straight.
+- **`api2/.ebextensions/health-check.config`** (2026-09-29) — pins the EB default process health check: `aws:elasticbeanstalk:environment:process:default` → `HealthCheckPath: /health`, `MatcherHTTPCode: 200`. Without it EB checks `/`, which returns 405 → env Red/Severe, `Target.ResponseCodeMismatch`. Applies on the next deploy of each env.
 - **Why `enforce_https` doesn't redirect it:** EB health checks arrive on **HTTP:80 with no `X-Forwarded-Proto`**, and `enforce_https.conf` only redirects requests carrying the forwarded-proto marker — so the probe is not bounced to HTTPS.
 
 **PHP short-circuit (for `/v2/health` and direct hits).** At the top of `Index.php::api()`, before host dispatch and before the Core/Logs DB bootstrap. Matches against a class constant:
@@ -56,7 +57,14 @@ So **all** these probe variants return 200 and never touch routing or the DB: `/
 - **Do not** move `/health` back into a PHP-served route or rename/remove `api2/health` — that re-couples EB liveness to PHP-FPM worker availability, the exact failure this fixed (see [api2 architecture — EB "Degraded" health](../architecture.md)).
 - Health probes must degrade to a 200 short-circuit, not enter routing. Add new probe paths to `HEALTH_CHECK_ROUTES` in normalized form, never as a new exact-string branch.
 
+- Env Red/Severe with `Target.ResponseCodeMismatch` → check the target group health-check path is `/health`, not `/`. The `.ebextensions` file sets it; an env not yet redeployed still has the old path.
+- Git Bash path-converts AWS CLI args (`/health` → `C:/Program Files/Git/health`). Prefix the command with `MSYS_NO_PATHCONV=1`.
+
 ## Related
 
 - [api2 architecture — EB "Degraded" health](../architecture.md)
 - [V2 API error codes](v2-api-error-codes.md)
+
+## Change history
+- 2026-09-29 — Added `.ebextensions/health-check.config` (HealthCheckPath `/health`, matcher 200); api-qa-alpha was Red on `/` 405 (api2 `885d114`) (jcardinal)
+- 2026-08-28 — `/health` moved to a static Apache file, off PHP-FPM (jcardinal)

package/knowledge/2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-17
+updated: 2026-09-29
 owners: ["bala", "rgirish"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -17,6 +17,7 @@ related:
   - ../../../clients/compass-usa/features/item-catalogs-and-duplicate-items.md
   - ../../../clients/elite/features/supply2-tableview-config-drift.md
   - tableview-field-metadata.md
+  - ../../_underscore/features/calculated-sql-fields.md
 ---
 
 ## Summary
@@ -167,8 +168,40 @@ None — engine behavior. A specific client's view may carry its own `apiWhereCl
 - **Operator allowlist.** `parseOptionsWhere` whitelists the operators above and rejects unknown
   ones (e.g. `regexp` returns a 500) — see the Compass cost-centers doc. Numeric/regex filtering
   that the grammar can't express must be done client-side or by adding an operator to api2.
+- **⚠ The FIELD name is never validated — an unknown one is a bare 500 with an EMPTY body.**
+  `parseOptionsWhere` maps only the operator token; the field slot passes straight into the SQL.
+  A name no model declares reaches MySQL as `Unknown column '<x>' in 'where clause'`, nothing
+  catches it, and the request dies as a 500 with **no message at all** (the 1.0 monitor then reports
+  its fallback literal *"No message found in response payload"* — see
+  [v2-api-error-codes](v2-api-error-codes.md) note 13). Live case: a `_isServiceClass` condition
+  stored on Elite's `inventory_items` clause 500'd `GET /v2/items` **91 times in 5 minutes across
+  7 prod api2 instances** (2026-09-17). **Open gap:** api2 has no guard that rejects an unknown
+  `_`-prefixed field with a 400 before it reaches MySQL.
+- **⚠ Deploy order: the `_underscore` model field ships BEFORE the migration that references it.**
+  An `_`-prefixed name in a clause only resolves if the model declares it `FIELD_SQL` with a
+  matching same-name static (e.g. `_qtyOnHand` on `_Model_Client_Item`) — see
+  [calculated SQL fields](../../_underscore/features/calculated-sql-fields.md). A clause is **data**,
+  so it goes live the instant the `dbchanges2` file runs, with no deploy gate; applying it first
+  takes the listing endpoint down for that tenant. Check the client's own model too — a
+  `_Model_<Client>_Item` inherits from `_Model_Client_Item` and may declare neither.
+- **An unexplained field in a `where=` lives in the DB, not the frontend.** Filters reaching api2
+  are stored in `Client_<Tenant>.TableViews.apiWhereClause`, not written in app code. When a field
+  name appears in **no** repo and **no** git history, query `TableViews` across the client DBs —
+  that is where it is.
 
 ## Change history
+- 2026-09-29 — **Recorded that an unvalidated field name in a stored clause is a production
+  outage class, not a typo.** `parseOptionsWhere` maps only the operator and passes the field slot
+  straight to MySQL, so an undeclared `_`-prefixed name becomes `Unknown column` → an uncaught
+  500 with an **empty body**. Live case: a draft `_isServiceClass` condition on Elite's
+  `inventory_items` view 500'd `GET /v2/items` 91 times in 5 minutes across 7 prod api2 instances
+  (2026-09-17); `_isServiceClass` was declared on no model and existed in no repo or git history.
+  Added the deploy-ordering rule (the `_underscore` `FIELD_SQL` field must be deployed **before**
+  the `dbchanges2` file that references it, because a clause is data and needs no deploy), the
+  debugging path (an unexplained `where=` field lives in `TableViews.apiWhereClause`, not the
+  frontend repo), and the open gap that api2 rejects unknown operators but not unknown fields.
+  Diagnosis only, no code changed. Prod re-verified 2026-09-29: zero `TableViews` rows across all
+  37 `Client_*` databases reference the field. (bala)
 
 - 2026-09-17 — **Recorded that subqueries ARE possible in a stored `apiWhereClause`**: the parser
   splits on literal spaces, so writing `/**/` in place of every space (MySQL reads it as

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 90 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 92 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 80 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 26 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 22 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/elite/features/supply2-tableview-config-drift.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: elite
 type: client-feature
 status: active
-updated: 2026-09-17
+updated: 2026-09-29
 owners: [tcox, bala, rgirish]
 files:
   - dbchanges2/Client_Elite/
@@ -297,6 +297,17 @@ for the technique and the parser mechanics.
 required a `_isServiceClass` model field on `_Model_Elite_Item`; **that field does not exist and is
 not needed** — do not add one.
 
+**⚠ That earlier draft reached PRODUCTION and took `/v2/items` down.** Before the rewrite, the
+stored clause was `(Items.partNumber:excludes:SVC-,_isServiceClass:eq:0)`. `_isServiceClass` is
+declared on neither `_Model_Client_Item` nor `_Model_Elite_Item`, so the raw name went into the SQL
+and MySQL threw `Unknown column '_isServiceClass' in 'where clause'` — **91 empty-body 500s on
+`GET /v2/items` in 5 minutes across 7 prod api2 instances (2026-09-17)**. A stored clause needs no
+deploy, so it went live the moment the migration ran. Closed: `2026-09-15a` reverted the clause and
+the current one uses only `_qtyOnHand` / `_qtyAvailable`, which **are** declared `FIELD_SQL`.
+Re-verified 2026-09-29 — zero `TableViews` rows in any of the 37 prod `Client_*` databases mention
+`ServiceClass`. The general rule and the debugging path are in
+[apiWhereClause row filtering](../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md#gotchas--known-issues).
+
 ### Why the class check replaced the `SVC-` prefix
 
 The `SVC-` prefix was an unreliable signal. Verified on **prod `Client_Elite`** (2026-09-15):
@@ -388,6 +399,15 @@ the old `SVC-` prefix check back into the clause.
   [error-reporting-issue-event](../../../2.0/apps/_underscore/features/error-reporting-issue-event.md).
 
 ## Change history
+- 2026-09-29 — **Recorded that the abandoned `_isServiceClass` draft clause actually shipped to
+  production and caused an outage**, which this doc previously reported only as "does not exist and
+  is not needed". The stored clause `(Items.partNumber:excludes:SVC-,_isServiceClass:eq:0)` put an
+  undeclared field into the SQL, giving `Unknown column '_isServiceClass' in 'where clause'` and 91
+  empty-body 500s on `GET /v2/items` in 5 minutes across 7 prod api2 instances (2026-09-17).
+  Incident is closed — `2026-09-15a` reverted the clause, the live one uses only the declared
+  `FIELD_SQL` fields `_qtyOnHand` / `_qtyAvailable`, and a 2026-09-29 sweep of all 37 prod
+  `Client_*` databases found no `TableViews` row mentioning `ServiceClass`. Diagnosis only, no code
+  changed. (bala)
 - 2026-09-17 — **Replaced the `SVC-` partNumber prefix filter with an ItemClass-hierarchy check**
   on the `inventory_items` view (`2026-09-15a - InventoryHideServiceClassItems.sql`): the clause
   now walks the `ItemClasses` parent chain and excludes items whose ROOT class id is 1, 22 or 40,

package/package.json

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