toga-ai 1.0.429 → 1.0.431

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

@@ -5,7 +5,9 @@
 | [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/ |
 | [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | A single authenticated V2 GET listing can return records across **many** clients (designed for 1000+) that the caller is entitled to, honoring **each target cli | api2/Component/Api/CrossClient/CrossClient.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, api2/_.php, _underscore/Model/Cache/Table.php, _underscore/Model/Cache/Tables/Client.php, dbchanges2/Core/2026-06-30b - CacheClusterRegistrationAndRecordTtl.sql, dbchanges2/Cache/2026-06-30a - MultiClientCacheTables.sql |
 | [Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)](features/encrypted-user-uuid-auth-handoff.md) | `POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**: given an encrypted `{client, user}` UUID pair, it mints a fr | api2/Component/Api/CrossClient/CrossClient.php |
+| [Health-check endpoint (/health liveness short-circuit)](features/health-check-endpoint.md) | `_Controller_Index::api()` short-circuits **liveness/health-probe** requests to an HTTP 200 **before** any routing, DB bootstrap, or V2 engine work runs. | api2/Controller/Index.php |
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, plus item **feature** text — `Features.name`, `ItemCategoryFeatureGroups.name`, `ItemFeatures | 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, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql |
+| [Nested FK object embedding is gated by the CHILD record's own ACL](features/nested-fk-acl-embedding.md) | When the V2 JSON engine serializes a foreign-key field into a **nested object** (in `getFullModelData()`, ~V2.php L6016-6060), it re-checks the **child** record | api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql |
 | [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php |
 | [Record Scripts (computed/aggregate /v2 endpoints — the authoring contract)](features/record-scripts.md) | In api2 you almost never write a controller. | api2/Component/Api/V2/V2.php, _underscore/Model/Team/Sprint.php |
 | [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 |

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

@@ -0,0 +1,64 @@
+---
+title: "Health-check endpoint (/health liveness short-circuit)"
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-24
+owners: [jcardinal]
+files:
+  - api2/Controller/Index.php
+related:
+  - ../architecture.md
+  - v2-api-error-codes.md
+---
+
+## Summary
+
+`_Controller_Index::api()` short-circuits **liveness/health-probe** requests to an HTTP 200
+**before** any routing, DB bootstrap, or V2 engine work runs. EB/LB (Elastic Beanstalk /
+load balancer) probes depend on this always returning 200 cheaply — the architecture doc's
+critical rule is literally "Don't break `/health`". This doc records the **matching contract**
+so a teammate doesn't reintroduce a brittle exact-string check.
+
+## How it works
+
+The short-circuit lives at the top of `Index.php::api()`, before host dispatch and before the
+Core/Logs DB bootstrap. It matches against a class constant:
+
+```php
+const HEALTH_CHECK_ROUTES = ['/health', '/v2/health'];
+```
+
+The incoming path is **normalized** before comparison — lowercased, query string stripped,
+trailing slash removed — then matched strictly:
+
+```php
+$path = strtolower(rtrim(strtok($_SERVER['REQUEST_URI'] ?? '', '?'), '/'));
+if (in_array($path, self::HEALTH_CHECK_ROUTES, true)) { /* return 200 */ }
+```
+
+This means **all** of these probe variants return 200 and never touch routing or the DB:
+`/health`, `/v2/health`, `/health/` (trailing slash), `/health?x=1` (query string), and any
+case variant. On match it returns 200 with an empty object.
+
+## Why the normalization matters (the bug this fixed)
+
+The original check was an exact match `$_SERVER['REQUEST_URI'] == '/health'`, so any variant
+(`/v2/health`, trailing slash, query string) **fell through into the V2 routing engine**
+instead of short-circuiting. There it hit auth/DB work and could surface as an **HTTP 500
+(`EO-1`)** — a failing liveness probe. Health probes must degrade to a 200 short-circuit, not
+enter routing. When adding a new probe path, add it to `HEALTH_CHECK_ROUTES` (already
+normalized form: lowercase, no trailing slash, no query) rather than re-adding an exact-string
+branch.
+
+## Change history
+- 2026-07-24 — Replaced the brittle exact-string `REQUEST_URI == '/health'` check with a
+  `HEALTH_CHECK_ROUTES` constant + normalized (lowercase / strip query / strip trailing slash)
+  strict `in_array` match, so `/v2/health`, `/health/`, and `/health?x` all short-circuit to 200
+  before routing/DB work instead of falling through to the V2 engine and returning 500 (EO-1).
+  Verified via live curl on all variants. (jcardinal)
+</content>
+</invoke>

package/knowledge/2.0/apps/api2/features/nested-fk-acl-embedding.md

@@ -0,0 +1,79 @@
+---
+title: Nested FK object embedding is gated by the CHILD record's own ACL
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-23
+owners: [apeterson]
+files:
+  - api2/Component/Api/V2/V2.php
+  - dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql
+related:
+  - cross-client-data-retrieval.md
+  - tableview-apiwhereclause-row-filtering.md
+---
+
+## What it is
+
+When the V2 JSON engine serializes a foreign-key field into a **nested object** (in
+`getFullModelData()`, ~V2.php L6016-6060), it re-checks the **child** record's own
+`AclRecordPermissions` against the caller's roles before embedding it. If no grant exists, the
+engine records a debug `"No ACL Record Permissions records exist"` and **silently drops the nested
+object** — still HTTP 200, `isSuccess: true`, no error or warning `message`. This is why a linked
+object can silently disappear from an API payload for one client but embed fine for another.
+
+## How it works
+
+- The gate needs only an `AclRecordPermissions` **row** for the child record on one of the caller's
+  roles. Unlike a direct top-level GET of that record, the embedding path does **not** call
+  `buildSqlExpression` — an ACL row alone (no logic-group expression) is sufficient to embed.
+- Which roles are checked depends on the child `Records.aclDatabase`. A **CLIENT**-acl record checks
+  only the caller's **client** roles; a CORE-acl record checks CORE roles (mirrors the dispatch/record
+  rules in [surface-meta-option](surface-meta-option.md)).
+- The drop is **silent by design**: absence of a grant is treated as "not authorized to see this
+  linked object", collapsed to omission rather than an error. There is no `messages[]` entry, so the
+  symptom presents purely as a missing key in `data`.
+
+## The role-3-vs-role-1 mis-seed pattern (the durable gotcha)
+
+The most common cause of a silently-missing nested object is an ACL **mis-seed on the wrong role**:
+a child record granted to a service role no human carries (e.g. role **3 "API"**) instead of the
+base role every user carries (role **1 "Base"**). Because a CLIENT-acl record checks only the
+caller's client roles, a human user authenticated with role 1 gets no grant → the child is dropped;
+a machine/API caller on role 3 sees it fine.
+
+- **Confirmed instances:** the sales-order↔purchase-order join. On **Compass** the `purchase-orders`
+  record (Core Record 17, `_Model_Client_PurchaseOrder`, `aclDatabase=CLIENT`) was granted in
+  `Client_Compass` only to role 3, so the nested `purchaseOrder` dropped from the
+  sales-order-purchase-orders join response; **Quad** had it on role 1 (perm + logic group → `all`
+  expression) and embedded fine. The **same** mis-seed was previously found on **CompassCanada**
+  (record 275). It is **not** a single-client quirk — audit every client when a nested object is
+  reported missing for some tenants only.
+- **The fix mirrors the working tenant:** add a role-1 `AclRecordPermissions` (full CRUD,
+  app-agnostic) + `AclLogicGroups` (AND) + `AclLogicGroupExpressions` reusing the existing `all`
+  record expression on the child record. Field-read perms on role 1 usually already exist (no
+  `AclFieldPermissions` insert needed). Author it **id-agnostically** (natural keys, not hardcoded
+  ids), `NOT EXISTS`-guarded, wrapping any self-referencing subquery in a derived table to avoid MySQL
+  error 1093. See `dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql`.
+
+## Diagnostic tell
+
+A top-level GET of the child record **works** but the **nested embed of the same record under a
+parent is missing**, with a 200/`isSuccess:true` response and no `messages[]`. Chase the child
+record's `AclRecordPermissions` for the caller's role — not the parent's grant, and not field
+permissions.
+
+## Change history
+- 2026-07-23 — Documented that V2 nested-FK embedding (`getFullModelData`) re-checks the CHILD
+  record's own `AclRecordPermissions` and SILENTLY drops the nested object (200, isSuccess true, no
+  message) when no grant exists — needing only an ACL row, not a logic-group expression. Fixed the
+  Compass sales-order↔PO join: `purchase-orders` (record 17, CLIENT-acl) was granted only to role 3
+  ("API") not role 1 ("Base"), so humans lost the nested `purchaseOrder` while Quad (role-1 grant)
+  embedded fine; mirrored Quad's role-1 grant (`Client_Compass/2026-07-23b`). Confirmed this is the
+  SAME role-3-vs-role-1 mis-seed pattern already seen on CompassCanada (record 275) — not
+  CompassCanada-only. (apeterson)
+</content>
+</invoke>

package/knowledge/2.0/apps/api2/features/v2-api-error-codes.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
-owners: [mhammontree, tcox]
+updated: 2026-07-24
+owners: [mhammontree, tcox, jcardinal]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Client/TrackingNumber.php
@@ -35,6 +35,7 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
 | **EV-8** | Request field does not exist | A field sent in the payload isn't registered as a **`Core.RecordFields`** row for that record | Register the field in `Core.RecordFields` (see the "add a field to a V2 record" recipe in the ACL doc) |
 | **EV-9** | No permission to write field | The field exists but the caller's role has no **`AclFieldPermissions`** grant (`isWritable=1`) in the CLIENT DB | Add the `AclFieldPermissions` row for the role (clone a writable sibling field's grant) |
 | **EO-1** | Operation failed — identifier "There is no field called 'X' in the '_Model_Client_Y' model" | The DB column **and** `Core.RecordFields` exist, but the **generated model class** `_underscore/Model/Client/<Name>.php` doesn't declare the field. This is the **4th** requirement beyond the 3-file migration — and most often it's a **cross-repo git branch mismatch** (`_underscore` on a branch whose generated model lacks a field the DB/RecordFields already carry) | Declare the field in the generated model class (`public $field = self::FIELD_*`) and put all related repos (`_underscore`, `api2`, `dbchanges2`, `toga2-supply`) on the **same** feature branch — see the ACL doc's writable-field recipe |
+| **EO-1** | Operation failed — **surfaced from a PHP warning/notice, not a real op error** (e.g. "Attempt to read property 'id' on bool", undefined variable) | A latent PHP warning escalates to a 500 because **Sentry's `ErrorHandler` in api2 promotes warnings/notices into thrown exceptions** (see diagnosis note 5). The known instance: in `V2.php::processRoutePairs()` an **unresolved route** leaves the local `$record = false`, and the post-processing payload interceptor layer then dereferenced `$record->id` → warning → 500 | Guard before dereferencing an unresolved record. The fix added a guard clause `if (!$record) return [$rawRequestedRouteName => $outData];` **before** the interceptor/logging layer (so a bad route returns a clean envelope, not a fatal), and initializes `$record = false;` at the top of the `foreach ($lookupByRouteNames ...)` loop so the invalid-HTTP-method / null-`$action` branch can't leave `$record` undefined (an undefined-variable warning would itself escalate to a 500) |
 | **EZ-1** | Unauthorized record/script dispatch | Missing **`AclRecordScripts`** (scripted APIs) or the **`AclRecordPermissions`** four-table chain (records) for the caller's role | Grant `AclRecordScripts` (scripts) or complete the record-CRUD chain |
 | **EZ-2** | Field-level authorization denied (READ) | The field is registered (`Core.RecordFields` present → no `EV-8`) but the caller's role has no **`AclFieldPermissions`** grant to **read** it. The read-side counterpart of `EV-9` (write) | Add the `AclFieldPermissions` row for the role (`isWritable=0` if the field is server-written). For a **custom** `c_` field use `AclCustomFieldPermissions` instead — see the ACL doc's standard-vs-custom table |
 | **EV-5** | Duplicate `transactionId` | The globally-unique `transactionId` was reused | Send a fresh unique `transactionId` per request |
@@ -54,6 +55,15 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
 3. **EV-6 vs EZ-1** are the two halves of exposing a scripted API: EV-6 = no `Core.RecordScripts`
    route (the segment falls through to record lookup); EZ-1 = the route exists but there's no
    `AclRecordScripts` dispatch grant for the caller's role.
+5. **EO-1 can be a masked PHP warning, not an operation error.** Sentry's `ErrorHandler` in
+   api2 **escalates PHP warnings/notices into thrown exceptions**, so a latent "read property on
+   bool" or "undefined variable" surfaces to the client as an **HTTP 500 (EO-1)** rather than a
+   log line. Practical consequence: in `V2.php` you must guard against warnings as if they were
+   fatals — an unresolved route (or a parent FK-field path) leaves `$record = false`, and any
+   later `$record->id` deref becomes a 500. Return a clean envelope for unresolved records
+   **before** the interceptor/logging layer, and initialize loop-locals so no branch leaves a
+   variable undefined.
+
 4. **EO-1 ("no field called 'X' in the model") is NOT a DB problem.** EV-8 means the Core
    `RecordFields` registration is missing; EO-1 means the DB column and RecordFields are both
    present but the **generated PHP model class** lacks the field. Before touching migrations,
@@ -71,6 +81,12 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
 
 ## Change history
 
+- 2026-07-24 — Added a second **`EO-1`** case: a latent PHP **warning** (unresolved route →
+  `$record->id` on `bool` in `V2.php::processRoutePairs()`, or an undefined loop variable)
+  escalates to an HTTP 500 because api2's Sentry `ErrorHandler` promotes warnings/notices into
+  exceptions. Fix = guard clause returning a clean envelope for unresolved records before the
+  post-processing interceptor layer + initialize `$record = false` at the loop top. Added
+  diagnosis note 5 (warnings surface as EO-1 500s). (jcardinal)
 - 2026-07-23 — TRUE-79533: added **`EZ-2`** (field-level READ authorization denied) — the read-side
   counterpart of `EV-9`; a registered field (no `EV-8`) with no `AclFieldPermissions` read grant.
   Clarified EV-8/EV-9/EZ-2 as three states of one field and the standard-vs-custom grant-table

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

@@ -3,5 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
-| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.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, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql |
+| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.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, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | > **A local browser wizard now automates this.** Steps 2–9 below (create DBs, generate Core/API > inserts, append to `Clients_Db.txt`) — plus the dbchanges2 bla | Client/, Client_<Tenant>/, Core/, Logs_Client/ |

package/knowledge/2.0/apps/dbchanges2/features/surface-layer-schema.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
+updated: 2026-07-23
 owners: [jcardinal, apeterson]
 files:
   - dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql
@@ -65,6 +65,7 @@ files:
   - dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql
   - dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql
   - dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql
+  - dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql
 related:
   - ../../_underscore/features/surface-resolver.md
 ---
@@ -499,6 +500,14 @@ rule resumes.
   override is added). **Open follow-up.**
 
 ## Change history
+- 2026-07-23 — Repointed the Order Details **"PO Number"** detail field (all clients, Core seed).
+  `Core/2026-07-23a - PoNumberDetailFieldValueKey.sql` updates the `SurfaceElements` row (uuid
+  `d45c51d8-8211-11f1-bfa7-a30f63c3a801`, label `salesOrder.field.poNumber`) `config` from
+  `{"valueKey":"_purchaseOrders","isPersonaValue":true}` to
+  `{"valueKey":"purchaseOrderDetails.purchaseOrder.number"}`. The FE DetailSection resolves a field
+  value by plain dot-path against the order object, and the real PO number lives at
+  `purchaseOrderDetails.purchaseOrder.number`; `isPersonaValue` was dropped (it applies only to
+  persona arrays, not scalars). Keyed by stable uuid. (apeterson)
 - 2026-07-21 — Seeded the **per-client decision-summary overrides** off the shared
   `sales-order-decision-summary` surface (all `2026-07-21c`, client-level — `roleId`/`personaId`/
   `languageId` NULL): **Quad** hides three summary rows (`assignedTo._name`, `c_erpEntityId`,

package/knowledge/2.0/apps/toga25-supply/features/surface-frontend.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
+updated: 2026-07-23
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
@@ -165,11 +165,37 @@ modal copy, visibility/enable) to Surface; **leave data-fetch wiring (fetch slug
 nested-table topology) in JSON/code.** Not every screen reduces to a generic `SurfaceSection` swap —
 see SalesOrders below.
 
-## SalesOrders record-modal sections — migrated via the registered-renderer seam (roster-gated)
-
-The SalesOrders detail sections are now migrated onto Surface for the **seeded roster clients only**,
-via the registered-renderer approach (not a generic `SurfaceSection` swap — `SalesOrderSummaryGrid`'s
-three bespoke renderers `detailSection`/`locationCard`/`totalsCard` are untouched).
+## Surface on/off is 100% BACKEND-driven — no FE roster (2026-07-23)
+
+**A client turns Surface on purely by backend state — never a hardcoded FE allowlist.** The
+SalesOrders record modal previously gated surface resolution on an in-code roster
+(`SALES_ORDER_SURFACE_MIGRATED_CLIENTS = ["COMPASS","COMPASSCANADA","QUAD"]`): it fetched the surface
+group only for rostered clients, and everyone else fell back to JSON. That roster was the **last FE
+gate** blocking BE-driven resolution — and it blocked NYCHH from ever receiving a corrected surface
+field even though its API returned the data. **It has been removed entirely.**
+
+- The SO modal now **ALWAYS** fetches the surface group and spreads
+  `surfaceBundleToTenantFields(surfaces)` **unconditionally** (view-model
+  `useSalesOrderRecordModalLayoutModel.tsx`; roster constant deleted from
+  `surfaceBundleToTenantFields.ts` and `helpers/index.ts`).
+- Fetch is **failure-isolated** (`retry:false`, errors → `isError`, `surfaces` defaults to `{}`), and
+  `surfaceBundleToTenantFields` returns `{}` for an empty/unauthorized bundle — so a client the backend
+  does **not** serve stays JSON-driven with no roster. Merge remains **JSON-base + Surface-wins**.
+- A client now "turns on" Surface by two backend facts only: (1) being granted the `surfaces`/`meta-group`
+  script ACL (`AclRecordScripts` — see [surface-meta-option](../../api2/features/surface-meta-option.md)),
+  **and** (2) having its surfaces seeded/overridden server-side. No FE change is ever needed to onboard a
+  client onto Surface.
+- **Audit outcome:** every other `useFetchSurfaceMeta`/`useFetchSurfaceMetaGroup` call site (item-record
+  modal, approval-decision modal, Items/VendorItems/Inventory/Login) was already BE-driven — the SO modal
+  roster was the ONLY offending gate. The `clientSlug` conditionals in `src/fieldsConfig/` (`resolveRole`,
+  `FIELDS[clientSlug]`) are the **legacy JSON fallback layer, NOT surface gating**, and are correctly left
+  in place (they serve clients the backend doesn't yet drive via Surface).
+
+## SalesOrders record-modal sections — migrated via the registered-renderer seam
+
+The SalesOrders detail sections are migrated onto Surface via the registered-renderer approach (not a
+generic `SurfaceSection` swap — `SalesOrderSummaryGrid`'s three bespoke renderers
+`detailSection`/`locationCard`/`totalsCard` are untouched).
 
 - **`surfaceBundleToTenantFields()`** (`SalesOrders/helpers/`) adapts the grouped Surface bundle into
   the existing **`TenantFields`** shape, so the existing `SalesOrderSummaryGrid` renderers and
@@ -178,8 +204,9 @@ three bespoke renderers `detailSection`/`locationCard`/`totalsCard` are untouche
   gating are **not** moved. (Registered-renderer seam: *config describes, code decides.*)
 - **Full adapter-seam data path (verified this session, no direct `<SurfaceSection>`):**
   `useFetchSurfaceMetaGroup(SALES_ORDER_SURFACE_SLUGS)` → `surfaceBundleToTenantFields(surfaces)` →
-  merged into `tenantFields` (roster clients only; `clientSlug` is the **uppercased** `getHostname()`
-  result matched against the roster) → **`buildPatchedTenantFields`** (which only overrides
+  merged into `tenantFields` (**unconditionally, for every client**; an empty/unauthorized bundle
+  adapts to `{}` so unseeded clients stay JSON-driven) → **`buildPatchedTenantFields`** (which only
+  overrides
   `recordActionFields`, so it **preserves all surface section keys**) → `SalesOrderView` →
   **`SalesOrderSummaryGrid`** (renders by `section.type` / `cardType`:
   `detailSection`/`locationCard`/`totalsCard`, where `cardType` comes from `surface.config.cardType`)
@@ -212,15 +239,14 @@ from "≥1 field visible", and bind an array-derived value via element `config`
 resolved on the FE. This is the presentation counterpart of the schema's field-driven pattern and the
 third section pattern alongside card sections (`cardType` → grid renderer) and marker toggles.
 
-- **Roster gate — `SALES_ORDER_SURFACE_MIGRATED_CLIENTS = [COMPASS, COMPASSCANADA, QUAD]`** (an
-  in-code roster in `surfaceBundleToTenantFields.ts`; the view-model
-  `useSalesOrderRecordModalLayoutModel.tsx` consults it). The view-model resolves sections from
-  Surface **only** for roster clients; every other client (incl. never-migrated
-  NYCHH/Prudential/SPGlobal) skips the fetch and stays fully JSON-driven. Merge is **JSON-base +
-  Surface-wins.** ⚠ **Why a roster, not a flag:** the Core SECTION surfaces are **shared** and seeded
-  from Compass's shape — without the gate every client would inherit Compass's base and regress. A
-  **code** roster (not an env flag) is deliberate: a client is removed from the roster only once its
-  own seeds are verified.
+- **No roster (as of 2026-07-23).** The former
+  `SALES_ORDER_SURFACE_MIGRATED_CLIENTS = [COMPASS, COMPASSCANADA, QUAD]` in-code gate was **removed**;
+  the view-model now resolves sections from Surface for every client, and an empty/unauthorized bundle
+  adapts to `{}` so unseeded clients stay JSON-driven. Merge is still **JSON-base + Surface-wins**. The
+  guardrail that used to justify the roster (shared Core SECTION surfaces seeded from Compass's shape)
+  is now enforced backend-side by the **Core-neutral-default → per-client opt-in** seeding rule (see
+  [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md)) — Core no longer ships
+  Compass's shape as a live default, so removing the roster does not regress unseeded clients.
 - **JSON cleanup:** the migrated section blocks (orderDetails/shipTo/billTo/orderSummary/
   orderRecurring + the 5 display sections) were **deleted** from the COMPASS / COMPASSCANADA / QUAD
   `orderViewFields.json` files. Data-wiring (`salesOrderDetailsConfig`/`itemFulfillmentClickRule`/
@@ -471,6 +497,19 @@ now carry it (2026-07-21):
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-07-23 — **DECISION + FIX: surface on/off per client is now 100% backend-driven — removed the FE
+  roster entirely.** Deleted `SALES_ORDER_SURFACE_MIGRATED_CLIENTS = [COMPASS,COMPASSCANADA,QUAD]` from
+  `surfaceBundleToTenantFields.ts` + `helpers/index.ts`; `useSalesOrderRecordModalLayoutModel.tsx` now
+  ALWAYS fetches the surface group and spreads `surfaceBundleToTenantFields(surfaces)` unconditionally.
+  The fetch is failure-isolated (`retry:false` → `surfaces` defaults to `{}`) and the adapter returns
+  `{}` for an empty/unauthorized bundle, so a client the BE doesn't serve stays JSON-driven with no
+  roster. A client "turns on" Surface purely via backend state: the `surfaces`/`meta-group`
+  `AclRecordScripts` grant + seeded/overridden surfaces. This unblocked NYCHH (was blocked by the roster
+  from receiving the corrected PO-number field). Swept every other `useFetchSurfaceMeta(Group)` call
+  site (item-record modal, approval-decision modal, Items/VendorItems/Inventory/Login) — all already
+  BE-driven; the SO modal roster was the only FE gate. Confirmed the `src/fieldsConfig/` `clientSlug`
+  conditionals are the legacy JSON fallback layer (not surface gating) and left them in place.
+  (apeterson)
 - 2026-07-21 — Extended `surfaceBundlesToDecisionFields.ts` to emit **`isConcatenated`** on
   decision-summary rows: new exported `DecisionSummaryConcat` type (string shorthand | descriptor
   `{valueKey, prefix?, suffix?, valueType?, layout?, label?}`, mirroring blox `BaseDetailField`); optional

package/package.json

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