toga-ai 1.0.556 → 1.0.557

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

@@ -20,6 +20,7 @@
 | [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 |
 | [Error Reporting — Issue/Event Capture, Fingerprinting & Aggregation](features/error-reporting-issue-event.md) | Platform-wide error reporting for TOGA 2.0, built on an **Issue / Event** aggregation model in the **shared Core Logs DB**. | _underscore/Error.php, _underscore/Database.php, _underscore/Exception/Business.php, api2/Controller/Index.php, worker2/Controller/Index.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, _underscore/Model/Core/Logs/IssueFingerprint.php, _underscore/Model/Core/Logs/IssueClickupTask.php, _underscore/Model/Core/Logs/IssueEmailAddress.php, _underscore/Model/Core/Logs/IssueAreaOwner.php, dbchanges2/Logs/2026-07-30a - Error reporting Issues and Events.sql, dbchanges2/Logs/2026-08-01a - Rename tables to singular.sql, dbchanges2/Logs_Client/2026-08-01a - Drop Error table.sql, dbchanges2/Core/2026-07-30a - Error escalation cron job.sql |
 | [Record-Changed Event Publishing (_Event::publish to SQS)](features/event-publish-sqs.md) | `_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event pipeline. | _underscore/Event.php |
+| [FIELD_STORAGE fields — per-row lazy hydration and the platform-wide missing-column 500](features/field-storage-row-hydration.md) | `FIELD_STORAGE` is the 2.0 field type for blob-backed columns (S3 or local folder). | _underscore/Model.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/Invoice.php, dbchanges2/Core/HISTORIC/2024/2024-11b - item-fulfillments.sql |
 | [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). | worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/probe_je_shape.php, test/@dave/fixer.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [isFulfillable Propagation Up the SO↔PO Chain](features/fulfillable-item-propagation.md) | `Items.isFulfillable` is a boolean that gates whether a storefront line's **Qty Fulfilled** cell is actionable. | _underscore/Model/Client/Item.php, _underscore/Model/Compass/Item.php, dbchanges2/Core/2026-07-17 - Items isFulfillable RecordField.sql, dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql, dbchanges2/Client/2026-07-17 - ItemsisFulfillable.sql |
 | [Item-Fulfillment Stage Lifecycle (picked/packed/shipped) & Order Status](features/item-fulfillment-stage-lifecycle-and-order-status.md) | Every ItemFulfillment (IF) now carries an explicit **stage** — picked → packed → shipped — resolved through `ItemFulfillmentStages → ItemFulfillmentStatuses` (m | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Client/SalesOrderItem.php, _underscore/Model/Client/Item.php, _underscore/Model/Client/PurchaseOrderItem.php, library/app/api/toga2.php, dbchanges2/Client/2026-06-30a - BackfillNullStageItemFulfillmentsToShipped.sql, dbchanges2/Client/2026-06-30b - SalesOrderStatusesPickedPacked.sql, dbchanges2/Client/2026-06-30c - ItemFulfillmentStageIdNotNull.sql, dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql |
@@ -28,7 +29,7 @@
 | [_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, _underscore/Model/Rate/Subscription.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 |
 | [NetSuite Sales Order sync — ship-to address, phone, and PO reference sourcing](features/netsuite-salesorder-address-phone-sync.md) | `_Trait_Netsuite_SalesOrder` is the **shared** sales-order importer composed into **22 client models** (every client on the dbchanges2 `netsuite` module). | _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Model.php, dbchanges2/_modules/netsuite/2026-08-10a - AddressPhoneNumberApiRoleAcl.sql |
-| [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | `_Model_Core_Page::meta()` is the **legacy** page-meta resolver behind `GET /pages/meta?slug=<slug>` — still the live path for `toga2-supply` and other pre-Surf | _underscore/Model/Core/Page.php |
+| [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | `_Model_Core_Page::meta()` is the **legacy** page-meta resolver behind `GET /pages/meta?slug=<slug>` — still the live path for `toga2-supply` and other pre-Surf | _underscore/Model/Core/Page.php, _underscore/Model/Client/TableView.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/Query.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 |

package/knowledge/2.0/apps/_underscore/features/carrier-shipping-labels.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-08-11
-owners: [mhammontree]
+owners: [mhammontree, tcox]
 files:
   - test/@Mark/true-80824-fedex-inflate-test.php
   - dbchanges2/Client_Growrk/2026-08-10e - GrowrkUpsServiceMethodCodes.sql
@@ -27,6 +27,7 @@ files:
   - _underscore/Cloud.php
 related:
   - ../architecture.md
+  - field-storage-row-hydration.md
   - recursive-item-fulfillments.md
   - ../../toga2-supply/features/fulfill-and-ship.md
   - ../../api2/features/record-scripts.md
@@ -276,6 +277,12 @@ review. **The UPS client has the same latent gap.**
 
 ## `FIELD_STORAGE` mechanics (reference)
 
+> **⚠ `TrackingNumbers.labelPdfFile` has NO physical column in any `Client_*` schema in any
+> environment** (verified 2026-08-11) — the 2024 change registered the Core `RecordField` but never
+> wrote an `ALTER TABLE`. Because storage fields hydrate **lazily per returned row**, `GET
+> /tracking-numbers` 500s (`EO-1` / MySQL 1054) the moment a query matches rows. Full write-up +
+> fix: [FIELD_STORAGE row hydration](field-storage-row-hydration.md).
+
 `Model.php` handles storage fields separately from regular columns (write loop ~line
 393; read ~line 730). Config keys in `[_underscore]`: `model_storage_folder` → local
 folder mode (if set, S3 is never used); `model_storage_s3_bucket` +
@@ -416,6 +423,11 @@ still discards the unsaved in-memory value.
   bill) — expect a hard error rather than a silently-wrong bill in those cases.
 
 ## Change history
+- 2026-08-11 — Flagged that `TrackingNumbers.labelPdfFile` has **no physical column in any
+  `Client_*` schema in any environment** (only the Core `RecordFields` metadata was ever inserted),
+  so `GET /tracking-numbers` 500s once a query returns rows — storage fields hydrate lazily per row,
+  which is why it stayed dormant. Details in the new
+  [FIELD_STORAGE row hydration](field-storage-row-hydration.md) doc. (tcox)
 - 2026-08-11 — TRUE-80824: **made FedEx carrier rejection reasons readable.** FedEx returned a
   **gzip-encoded HTTP 400** and `_ApiRequest` sets no `CURLOPT_ENCODING`, so `json_decode` saw
   compressed bytes and `describeShipmentError()` printed `\x1f\x8b…`; with `setLogging(false)` on the

package/knowledge/2.0/apps/_underscore/features/field-storage-row-hydration.md

@@ -0,0 +1,105 @@
+---
+title: "FIELD_STORAGE fields — per-row lazy hydration and the platform-wide missing-column 500"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-08-11
+owners: [tcox]
+files:
+  - _underscore/Model.php
+  - _underscore/Model/Client/TrackingNumber.php
+  - _underscore/Model/Client/Invoice.php
+  - dbchanges2/Core/HISTORIC/2024/2024-11b - item-fulfillments.sql
+related:
+  - carrier-shipping-labels.md
+  - ../../api2/features/v2-api-error-codes.md
+  - ../../dbchanges2/workflows/client-schema-drift-audit.md
+---
+
+## Summary
+
+`FIELD_STORAGE` is the 2.0 field type for blob-backed columns (S3 or local folder). Unlike every
+other declared field it is **excluded from the model's main SELECT** (`Model.php` ~L664) and
+**hydrated lazily, per returned row**, when the V2 engine walks the result set. That single
+difference changes the failure mode of schema drift completely:
+
+> **A `FIELD_STORAGE` field whose column does not exist cannot fail on an empty result set.**
+> The request only 500s once a query actually **returns rows** — so the defect sits dormant for
+> months and then appears the day a client's data starts matching.
+
+**Live platform defect (found 2026-08-11, unfixed):** `TrackingNumbers.labelPdfFile` and
+`Invoices.invoicePdfFile` are declared `FIELD_STORAGE` on the models but the columns exist in
+**no `Client_*` schema in any environment** — verified against `information_schema` on both
+dev-sandbox and production. `GET /tracking-numbers` and `GET /invoices` 500 for **every client**
+as soon as a row matches.
+
+## How storage fields differ from normal fields
+
+| | Normal / `c_` field | `FIELD_STORAGE` field |
+|---|---|---|
+| In the model's SELECT | **Yes** — `_Model` builds the SELECT from every declared property, ignoring the caller's `fields=` | **No** — skipped at `Model.php` ~L664 |
+| When the value is read | With the row | **Lazily, per row**, at depth 1 of hydration (`Model.php` ~L730) |
+| Missing column, 0 rows returned | **500** (`EO-1` / MySQL 1054) — the SELECT itself is invalid | **200** — nothing is hydrated, nothing fails |
+| Missing column, ≥1 row returned | 500 | **500** (`EO-1` / MySQL 1054 "Unknown column") |
+
+The consequence for diagnosis: the usual
+[client schema-drift audit](../../dbchanges2/workflows/client-schema-drift-audit.md) reasoning
+("a missing column fails **any** load of the record, on **any** route") is **not** true for storage
+fields. An endpoint that returns 200 on an empty/filtered query is **not** evidence its schema is
+sound. Re-drive the request with a filter you know matches rows before clearing it.
+
+Storage path, config keys and the two 2026-07 `Model.php` write/read bugs are documented in
+[carrier shipping labels → `FIELD_STORAGE` mechanics](carrier-shipping-labels.md).
+
+## The current defect — `labelPdfFile` / `invoicePdfFile` were never migrated
+
+- `_Model_Client_TrackingNumber::$labelPdfFile = self::FIELD_STORAGE` was added on **2024-10-16**
+  (`ffe72b61`, "Adding the fedex shipment api call").
+- `_Model_Client_Invoice::$invoicePdfFile = self::FIELD_STORAGE` is declared the same way.
+- `dbchanges2/Core/HISTORIC/2024/2024-11b - item-fulfillments.sql` inserted only the **Core
+  `RecordFields` metadata** for them. **No `ALTER TABLE` was ever written**, so the physical
+  columns were never created in any tenant schema.
+- Confirmed absent from **every** `Client_*` schema on **both** dev-sandbox and production.
+
+Dormant for ~10 months because the frontend fulfillment → tracking path was broken in other ways
+and never returned tracking rows. **Elite was the first client to return rows and hit it.**
+
+**Backend fix (correct):** a `dbchanges2` migration adding both columns to all `Client_*` schemas —
+or, if the feature is dead, remove the properties from the models. Do not "fix" it per client; the
+declaration is in the shared base model, so every tenant is affected identically.
+
+**Sandbox demo unblock only** (hand-applied, not a substitute for the migration):
+
+```sql
+ALTER TABLE TrackingNumbers ADD COLUMN labelPdfFile LONGBLOB NULL;
+ALTER TABLE Invoices ADD COLUMN invoicePdfFile LONGBLOB NULL;
+```
+
+## Gotchas / known issues
+
+- **"It returns 200" proves nothing about a storage field.** Empty result sets never hydrate.
+  Reproduce with rows.
+- **The 500 is per-row, so it looks data-dependent.** The same route works for one filter and
+  fails for another — which reads like a bad row rather than a missing column.
+- **Metadata without DDL is a real migration state.** A `Core.RecordFields` row can exist for a
+  column that was never created; the field registration is what makes the API *offer* it, not what
+  makes it *exist*. When auditing drift, check `information_schema` for storage fields too — the
+  model-vs-schema diff described in the drift audit will otherwise not flag them as urgent because
+  nothing is failing yet.
+- **Blast radius is the platform, not a tenant.** Unlike the usual one-client drift, a field
+  declared on a shared `_Model_Client_*` class with no migration anywhere means **all** clients are
+  broken at once.
+
+## Change history
+- 2026-08-11 — First capture: documented that `FIELD_STORAGE` fields are excluded from the model's
+  main SELECT and hydrated **lazily per returned row**, so a missing storage column 500s only when
+  a query actually returns rows (empty sets stay 200). Recorded the live platform defect —
+  `TrackingNumbers.labelPdfFile` (declared 2024-10-16, `ffe72b61`) and `Invoices.invoicePdfFile`
+  exist in **no `Client_*` schema in any environment**, because the 2024-11b item-fulfillments
+  change inserted only the Core `RecordFields` metadata and no `ALTER TABLE`; `GET /tracking-numbers`
+  and `GET /invoices` 500 for every client once rows match. Found via Elite, the first client to
+  return tracking rows. Fix = a dbchanges2 migration across all `Client_*` schemas (or drop the
+  model fields). (tcox)

package/knowledge/2.0/apps/_underscore/features/page-meta-context-field-settings.md

@@ -6,12 +6,14 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-11
 owners: [tcox]
 files:
   - _underscore/Model/Core/Page.php
+  - _underscore/Model/Client/TableView.php
 related:
   - surface-resolver.md
+  - ../../api2/features/tableview-field-metadata.md
   - error-reporting-issue-event.md
   - ../../../clients/elite/features/supply2-tableview-config-drift.md
 ---
@@ -33,6 +35,42 @@ bug that takes down *unrelated* pages for any client that uses the feature.
 Example (Elite): row id 1 relabels field **58** to **"Total"** in the context of field **190**
 (`ServiceRequests.id`) — authored for the `service-requests` view.
 
+## Why this matters: table-view **column headers** for joined columns need context rows
+
+This is the mechanism behind "why is my column header a camelCase slug?" — and the answer is
+counter-intuitive enough that it has cost more than one session.
+
+A table view's column header is resolved by the frontend (`PrimaryTable` in `toga2-supply`) out of
+the **page meta**, by two *different* paths depending on where the column's field comes from:
+
+| Column's field | Lookup path in `pageMeta.settings.fields` |
+|---|---|
+| on the view's **base record** | `[record][field][label-singular]` — a flat, context-free row |
+| reached through a **join** | `[record][field][contextRecord][contextField][label-singular]` |
+
+So for a **joined** column, a `ClientRecordFieldSettings` row with a null `contextRecordFieldId`
+lands in the flat path the frontend never reads for that column, and the label silently does
+nothing. The row must carry **`contextRecordFieldId` = the table-view join's
+`parentRecordFieldId`** (`Model/Client/TableView.php` sets `settings.contextTable` /
+`settings.contextField` for every joined column from exactly that value).
+
+**When nothing resolves, the header falls back to the raw `TableViewFields.slug`** — which is why
+unlabeled joined columns render as camelCase identifiers rather than as blanks.
+
+### The `Core.PageRecords` gate
+
+`Page.php` assembles `settings.fields` from an **INNER JOIN** on `Core.RecordFields` (~L652) that is
+gated by **`Core.PageRecords`**: only fields of records *attached to the page* are emitted at all.
+A perfectly correct settings row therefore does nothing until **both** the labelled field's record
+**and** the context record are attached to the page. Sequencing for any such change:
+
+1. **The `isset()` guard in `Page.php` (below) goes first.** Until it ships, adding context rows is
+   actively dangerous — a context row fatals **every** page that contains the labelled field's
+   record but not the context record.
+2. Then the `Core.PageRecords` attachments.
+3. Then the `ClientRecordFieldSettings` rows, as a `dbchanges2` migration (hand-inserts on beta do
+   not survive a tenant refresh).
+
 ## The bug — "Undefined array key \<contextRecordFieldId\>" 500
 
 > **Status: reported to the backend, unfixed as of 2026-08-10.**
@@ -68,6 +106,17 @@ data change, is what makes it fatal.
   customization. The guard belongs in the framework.
 
 ## Change history
+- 2026-08-11 — Documented what context-scoped settings are actually **for**: table-view **column
+  header labels**. A base-record column resolves as `settings.fields[record][field][label-singular]`
+  but a **joined** column resolves the context-nested
+  `settings.fields[record][field][contextRecord][contextField][label-singular]`, so a label row for a
+  joined column must carry `contextRecordFieldId` = the join's `parentRecordFieldId`
+  (`Model/Client/TableView.php` emits `settings.contextTable`/`contextField` from it) — a
+  context-free row lands in a path the frontend never reads. Unresolved headers fall back to the raw
+  `TableViewFields.slug` (the camelCase headers). Also recorded the **`Core.PageRecords` gate**
+  (`Page.php` ~L652 INNER JOINs `Core.RecordFields` only for records attached to the page) and the
+  mandatory ordering: `isset()` guard → PageRecords attachments → settings rows as a migration.
+  (tcox)
 - 2026-08-10 — First capture: documented context-scoped `ClientRecordFieldSettings` and the
   `Page.php:824` *"Undefined array key \<contextRecordFieldId\>"* fatal (context field not on the
   requested page), which the 2026-08-07 strict Sentry handler turned from a warning into a 500 on

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

@@ -19,7 +19,7 @@
 | [TableView row-filtering via apiWhereClause (options.where grammar, end to end)](features/tableview-apiwhereclause-row-filtering.md) | `TableViews.apiWhereClause` (TEXT, nullable) is the sanctioned, code-free way to restrict or exclude rows from a 2.0 table view. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/TableView.php, toga2-supply/src/api/toga.ts |
 | [TableView field/column metadata (TableViewFields, hidden projected columns)](features/tableview-field-metadata.md) | The columns of a 2.0 table view are defined by DB metadata, not code. | _underscore/Model/Client/TableView.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
-| [V2 API error/message codes (EV/EZ troubleshooting map)](features/v2-api-error-codes.md) | The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the response `error` field, grouped by family: `EN-*` authentication, `EZ-*` a | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, api2/Component/Api/V2/Response/Oauth/Oauth.php, api2/Controller/Index.php, toga2-supply/src/globalTypes.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, _underscore/Model/Client/TrackingNumber.php |
+| [V2 API error/message codes (EV/EZ troubleshooting map)](features/v2-api-error-codes.md) | The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the response `error` field, grouped by family: `EN-*` authentication, `EZ-*` a | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, api2/Component/Api/V2/Response/Oauth/Oauth.php, api2/Controller/Index.php, toga2-supply/src/globalTypes.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/api/toga.ts, _underscore/Model/Client/TrackingNumber.php |
 | [V2 REST query contract (params, where grammar, encoding, ACL behavior)](features/v2-rest-query-contract.md) | What an **HTTP client** has to get right to query the Toga v2 REST API: which query params are recognized, the exact `where` grammar, how the query string is (n | api2/Component/Api/V2/V2.php |
 | [V2 reverse hasMany collections must be named in the fetch fields whitelist](features/v2-reverse-hasmany-fields-whitelist.md) | In the V2 JSON engine, a **reverse hasMany** relationship — the collection of child records that foreign-key back to a parent (e.g. | api2/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**. | api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php, api2/.platform/hooks/prebuild/git.sh, api2/.ebextensions/git.php, api2/.ebextensions/git.sandbox-dev.json |

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-11
 owners: [mhammontree, tcox, jcardinal, ajean, bala]
 files:
   - api2/Component/Api/V2/V2.php
@@ -15,8 +15,10 @@ files:
   - api2/Controller/Index.php
   - toga2-supply/src/globalTypes.ts
   - toga2-supply/src/pages/Orders/api/OrdersApi.ts
+  - toga2-supply/src/api/toga.ts
   - _underscore/Model/Client/TrackingNumber.php
 related:
+  - ../../_underscore/features/field-storage-row-hydration.md
   - ../../_underscore/features/error-reporting-issue-event.md
   - ../../_underscore/features/acl-permission-chain.md
   - ../../dbchanges2/workflows/client-schema-drift-audit.md
@@ -46,6 +48,7 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
 | **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) |
 | **EO-1** | Operation failed — MySQL **1054 "Unknown column 'X' in 'field list'"** | The **exact reverse** of the row above: the generated model (or a **trait** it `use`s) *declares* the field but the client table has **no such column**. `_Model` builds its SELECT from **every declared property**, so this fires on **any** load of that record on **any** route — including when the caller never asked for that field. Usual cause: a client DB whose module migration only **partially** applied | Add the missing column to that client DB — plus its `CustomRecordFields` row and `AclCustomFieldPermissions` grant if it is a `c_` field. Audit the rest of the drift first: [client schema-drift audit](../../dbchanges2/workflows/client-schema-drift-audit.md) |
+| **EO-2** | *"invalid configuration / A required database could not be reached while initializing the request"* — **almost always a lie** | The `catch (Throwable $dbBootstrapError)` in `api2/Controller/Index.php` (~L364) wraps the **entire request dispatch**, not just the DB bootstrap, so **any** Throwable that escapes query processing is relabelled EO-2. Real causes seen: MySQL 1054 on a missing column, a promoted PHP warning, a model fatal | **Ignore the message text.** Get the real exception from Sentry (`captureException`) or, on newer builds, from `identifiers.message` in the envelope; then resolve `error.id` per diagnosis note 9 |
 | **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). **This applies to the `id` field too:** fetching a record by its numeric `id` (`GET /v2/<record>?fields=id,...`) 403s `EZ-2` if `id` has no read grant — the `id` field is ACL-gated like any other, not implicitly readable | 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 |
@@ -158,6 +161,21 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
     **missing DB column**. And several near-identical 500s sharing **one `transactionId`** are
     apiproxy's cross-region retry, not repeated user impact.
 
+13. **`EO-2` is a catch-all mislabel — and an ABSENT log row is itself a signal.** Three facts that
+    together cost a full session of misdirected DB-connectivity debugging:
+    - The controller's bootstrap `catch (Throwable …)` spans the whole dispatch, so a query-time
+      fatal is reported as *"A required database could not be reached."* **The database was fine.**
+      Treat EO-2 as "an unclassified Throwable escaped", nothing more.
+    - **5xx responses are NOT written to `Logs_<Client>.Api`** — response logging is skipped on a
+      fatal. So a request you watched 500 in DevTools with **no matching `Logs_<Client>.Api` row**
+      is *confirmation* of a server-side fatal, not a sign you queried the wrong client/timestamp.
+      (Pair with note 12: `Logs.Api.transactionId` stores a timestamp, so you cannot look the
+      request up by the envelope's `transactionId` either.)
+    - **The frontend swallows it.** `togaApiRequest` (`toga2-supply/src/api/toga.ts`) returns
+      **`null`** for any response `>= 500` (axios `validateStatus` under 500 throws), so callers see
+      a null payload, not an error — every consumer must null-guard, and "the page rendered empty"
+      is a plausible symptom of a 500 you never saw.
+
 ## BREAKING (2026-07-30): `error` is now an object, not a bare string
 
 The V2 envelope's `error` changed from a bare string (`"EO-1"`) to an **object**:
@@ -243,6 +261,16 @@ Full mechanics:
 
 ## Change history
 
+- 2026-08-11 — Added **`EO-2`** to the map as a **catch-all mislabel**: `Controller/Index.php`'s
+  `catch (Throwable $dbBootstrapError)` (~L364) wraps the entire dispatch, so any escaped Throwable
+  is reported as *"A required database could not be reached while initializing the request"* — the
+  text is usually wrong (the observed case was MySQL 1054 on a `FIELD_STORAGE` column that exists in
+  no client schema). Added diagnosis note 13: the real exception is in Sentry / `identifiers.message`;
+  **5xx responses are never written to `Logs_<Client>.Api`**, so a missing log row for a request that
+  visibly 500'd confirms a server fatal; and `togaApiRequest` in toga2-supply returns **`null`** on
+  any `>= 500`, so the frontend shows an empty page rather than an error. Linked the new
+  [FIELD_STORAGE row hydration](../../_underscore/features/field-storage-row-hydration.md) doc, whose
+  lazy per-row hydration is why that 1054 only fires when a query returns rows. (tcox)
 - 2026-08-10 — Added a **third `EO-1` case — MySQL 1054 "Unknown column"**: the reverse of the
   known model-declaration gap. When the model (or a **trait** it `use`s) declares a field the client
   table lacks, `_Model` still SELECTs it — it builds its SELECT from **every declared property**,

package/knowledge/2.0/apps/toga2-supply/workflows/client-host-scoping.md

@@ -6,7 +6,7 @@ project: TOGa Supply
 client: shared
 type: workflow
 status: active
-updated: 2026-08-10
+updated: 2026-08-11
 owners: [apeterson, tcox]
 files:
   - toga2-supply/src/stores/useHostNameStore.ts
@@ -132,7 +132,14 @@ before wiring the modal. The fix pattern:
   the host**, so other hosts never issue the extra request;
 - expect **columns the other record does not have** — see the `isQuote` gotcha below;
 - expect the join to be **optional**: an unmatched row resolves to `null` and the modal opens empty.
-  Decide the empty-state treatment with product; do not silently ship a blank modal.
+  Decide the empty-state treatment with product; do not silently ship a blank modal. Elite settled
+  on an explicit empty state driven off the resolver query's `isFetched`/`isError` → `null`
+  details ("No order details are available for this service request") — copy that shape rather than
+  leaving a blank panel.
+- **expect the join to be 1:N, and sort.** Elite's ServiceRequests → SalesOrders was assumed 1:1 and
+  is not (one SR had two orders), so the resolver returned an arbitrary row and the modal showed a
+  different order run to run. **Fetch an ordering key alongside the uuid** (Elite: `number`) and pick
+  deterministically. Verify the cardinality in the data — do not take it from the view definition.
 
 ## Getting a login for a new host (auth + test user)
 
@@ -197,7 +204,10 @@ actually talks to.
 - **Selection is uuid-driven and non-null-asserted.** Selection resolves from the URL param
   `<tableSlug>:group=<uuid>` with fallback `groupOptions.find(o=>o.isDefault) || groupOptions[0]`;
   `InventoryPage.tsx` non-null-asserts the uuid find and **throws** if the uuid is missing for a
-  host. Every host must have a valid default. **There is a third `find(...)!` consumer**:
+  host. Every host must have a valid default. (**Fixed 2026-08-11 in `InventoryPage.tsx`**: a URL
+  uuid absent from the resolved host's options now falls back to `defaultOption` instead of
+  crashing — a shared link from another host no longer white-screens the page.) **There is a third
+  `find(...)!` consumer**:
   `InventorySubTablePage.tsx` (~L139) does the same non-null assert, so a host whose array is
   missing the selected uuid crashes on the **nested** table too, not just the primary one.
 - **Shared localStorage is order-dependent and persists across host switches** in one browser
@@ -221,12 +231,26 @@ actually talks to.
   (callers already fall back to the field name). Reusing another page's `listingSlug` is therefore
   survivable, but remember it only affects **ACL and search labels** — column headers come from the
   **table-view** meta, not the page meta.
+- **Fixing a SHARED component for one host: make the condition provably a no-op for the others.**
+  The bar is *byte-identical rendering* for every host that does not meet the new condition, and you
+  should be able to state why. Worked examples (2026-08-11): `Toaster.tsx` centers a **message-only**
+  toaster (`flex-1` + `text-center`) — every other call site passes an action, so the branch is never
+  taken; `OrdersPage.tsx` re-syncs `pageTitle`/`tableDisplayData` **after the host store hydrates**,
+  which only changes first-render behavior where `fields` was `undefined`. A host conditional is the
+  escape hatch; a *condition on the data the component already has* is better and safer.
 - **A record swap costs you columns.** Elite's `service-requests` view is built on ServiceRequests,
   which has **no `isQuote` column**, so Orders' unconditional `isQuote: false` filter 500'd with
   `1054 Unknown column`. Filters that assume the SalesOrders shape must be made conditional on a
   FIELDS flag (`hasQuoteFilter`), not assumed. Backend confirmed this is an FE-side fix.
 
 ## Change history
+- 2026-08-11 — Added the rule for **fixing shared components on one host's behalf** (the condition
+  must be a provable no-op for every other host — Toaster message-only centering, OrdersPage state
+  re-sync after host-store hydration), recorded that a cross-record resolver join can be **1:N** and
+  must sort deterministically on a fetched key (Elite's ServiceRequests → SalesOrders was assumed
+  1:1 and is not), noted the empty-state shape for an unmatched resolver row, and that
+  `InventoryPage.tsx` now falls back to `defaultOption` for a URL group uuid the host does not have
+  instead of crashing on `find(...)!`. (tcox)
 - 2026-08-10 — Added **reference implementation 2 — retitling a shared page** (per-host
   `FIELDS/<HOST>/BASE.json` supplying `pageTitle`/`tableSlug`/`listingSlug`, explicit host entry in
   the view model, slug literals threaded through `fields?.` with literal fallbacks, feature removal

package/knowledge/INDEX.md

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

package/knowledge/clients/elite/INDEX.md

@@ -3,6 +3,6 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [Elite SalesOrder → NetSuite Push (postPost/postPut interceptors → worker2)](features/salesorder-netsuite-push.md) | 2.0 | Elite orders created in Toga are pushed into NetSuite **event-driven**, not on a cron. | _underscore/Model/Elite/SalesOrder.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Client_Elite/2026-08-10 - SalesOrderNetsuiteInterceptors.sql |
-| [Elite — supply2 frontend scope (Inventory + Service Requests, both built)](features/supply2-scope.md) | 2.0 | Scope for onboarding Elite to the `toga2-supply` frontend (host `ELITE`). | toga2-supply/ELITE-CLIENT-TASK-NOTES.md, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/pages/Inventory/viewModel/FIELDS/INVENTORYPAGEFIELDS.ts, toga2-supply/src/pages/Inventory/viewModel/index.ts, toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx, toga2-supply/src/pages/Inventory/listing/InventoryRouter.tsx, toga2-supply/src/pages/Inventory/listing/InventorySubTablePage.tsx, toga2-supply/src/utils/resolveClientHostName.ts, toga2-supply/src/utils/convertConstructorColumnTitles.ts, toga2-supply/src/pages/Orders/OrdersPage.tsx, toga2-supply/src/pages/Orders/viewModel/FIELDS/ELITE/BASE.json, toga2-supply/src/pages/Orders/viewModel/useOrdersPageViewModel.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/pages/Orders/view/OrderView/viewModel/useOrderDetailsViewModel.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/renderModalContent.tsx, toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx, toga2-supply/package.json |
+| [Elite — supply2 frontend scope (Inventory + Service Requests, both built)](features/supply2-scope.md) | 2.0 | Scope for onboarding Elite to the `toga2-supply` frontend (host `ELITE`). | toga2-supply/ELITE-CLIENT-TASK-NOTES.md, toga2-supply/src/pages/Orders/view/OrderView/viewModel/FIELDS/ELITE/BASEFIELDS.json, toga2-supply/src/pages/Orders/viewModel/FIELDS/ELITE/BASE.json, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/hooks/useFetchData.tsx, toga2-supply/src/components/ui/Toaster.tsx, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/pages/Inventory/viewModel/FIELDS/INVENTORYPAGEFIELDS.ts, toga2-supply/src/pages/Inventory/viewModel/index.ts, toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx, toga2-supply/src/pages/Inventory/listing/InventoryRouter.tsx, toga2-supply/src/pages/Inventory/listing/InventorySubTablePage.tsx, toga2-supply/src/utils/resolveClientHostName.ts, toga2-supply/src/utils/convertConstructorColumnTitles.ts, toga2-supply/src/pages/Orders/OrdersPage.tsx, toga2-supply/src/pages/Orders/viewModel/FIELDS/ELITE/BASE.json, toga2-supply/src/pages/Orders/viewModel/useOrdersPageViewModel.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/pages/Orders/view/OrderView/viewModel/useOrderDetailsViewModel.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/renderModalContent.tsx, toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx, toga2-supply/package.json |
 | [Elite — stale TableView config (11 dead Core.RecordFields across 9 views)](features/supply2-tableview-config-drift.md) | 2.0 | `Client_Elite`'s `TableViewJoins` predate **two** platform bridge-table migrations and still reference **11 deleted `Core.RecordFields` ids (211, 321, 932, 358, | dbchanges2/Client_Elite/, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
 | [Elite](profile.md) | 2.0 | Elite is a managed-services client that uses **Freshservice** as their helpdesk platform. | worker2/Worker/Elite.php, library/app/api/toga2.php, _underscore/Model/Elite/SalesOrder.php |

package/knowledge/clients/elite/features/supply2-scope.md

@@ -6,10 +6,15 @@ project: TOGa Supply
 client: elite
 type: client-feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-11
 owners: [apeterson, tcox]
 files:
   - toga2-supply/ELITE-CLIENT-TASK-NOTES.md
+  - toga2-supply/src/pages/Orders/view/OrderView/viewModel/FIELDS/ELITE/BASEFIELDS.json
+  - toga2-supply/src/pages/Orders/viewModel/FIELDS/ELITE/BASE.json
+  - toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts
+  - toga2-supply/src/hooks/useFetchData.tsx
+  - toga2-supply/src/components/ui/Toaster.tsx
   - toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts
   - toga2-supply/src/pages/Inventory/viewModel/FIELDS/INVENTORYPAGEFIELDS.ts
   - toga2-supply/src/pages/Inventory/viewModel/index.ts
@@ -108,14 +113,22 @@ is literal-identical to before.
 
 The backend table view (slug supplied by the backend dev) is built on the **ServiceRequests RECORD**
 — joining Tickets / Customers / ServiceRequestTypes / SalesOrders, where
-`SalesOrders.serviceRequestId = ServiceRequests.id` (1:1). It is **not** a renamed SalesOrders view.
+`SalesOrders.serviceRequestId = ServiceRequests.id`. It is **not** a renamed SalesOrders view.
 Three consequences drove the rest of the work:
 
+> **⚠ CORRECTION (2026-08-11): the ServiceRequests ↔ SalesOrders relationship is 1:N, not 1:1.**
+> This doc previously said 1:1; that is wrong. **SR100001 links to two sales orders (SA100000 and
+> SA100003).** Any resolver that assumes a single match will pick an arbitrary row and the modal
+> will show a *different* order run to run.
+
 1. **Row uuids are ServiceRequests uuids, but every detail-modal route is a `/sales-orders` record
    route.** Fixed with `getSalesOrderUuidForServiceRequest()` in `src/pages/Orders/api/OrdersApi.ts`
    (`GET /sales-orders` + a ServiceRequests join, `where ServiceRequests.uuid = …`), whose resolved
    `detailsUuid` is threaded through `useOrderDetailsViewModel.ts` via react-query. The query is
    **enabled only for `hostName === "ELITE"`**, so every other host bypasses it entirely.
+   Because the join is **1:N**, the resolver fetches `uuid` **and** `number` and **sorts
+   client-side, taking the lowest number** — a deterministic pick, so the modal opens the same order
+   every time.
 2. **ServiceRequests has no `isQuote` column.** `OrdersPage`'s unconditional `isQuote: false` filter
    500'd with `1054 unknown column`; the backend confirmed the fix belongs on the FE, hence
    `hasQuoteFilter`.
@@ -126,18 +139,45 @@ Three consequences drove the rest of the work:
 Verified working end-to-end on the one Elite service request that has a linked sales order
 (ticket INC-13982).
 
-## Open question — orphan ServiceRequests (needs backend/product input)
+## Part 3 — order-details modal & polish (2026-08-11)
+
+The details modal is now per-host configured through
+`src/pages/Orders/view/OrderView/viewModel/FIELDS/ELITE/BASEFIELDS.json`:
+
+- a **Type** row sourced from `salesOrderType.name`;
+- `settings.currencyCharacter` `"$"`;
+- Elite-worded copy for the no-details state;
+- section visibility flags for the sections Elite does not show.
+
+`FIELDS/ELITE/BASE.json` also **disables the export button** for Elite.
+
+**Orphan service requests are a DESIGNED EMPTY STATE, not a bug** (this closes the open question
+this doc previously carried). `useOrderDetailsViewModel.ts` reads the resolver's `isFetched` /
+`isError` and yields **`null` `orderDetails`**, which renders
+*"No order details are available for this service request."* Most Elite service requests on
+dev-sandbox have no linked sales order, so this is the common path — do not "fix" the blank modal.
+
+**Elite skips the ASN tracking query.** `OrdersApi.ts` short-circuits the
+`AdvanceShippingNoticeUnits` lookup for `ELITE` — **that table does not exist in `Client_Elite`**,
+so issuing it 500s the details fetch.
+
+**Inventory nested view renamed to the backend's slug.** `DUMMYGROUPOPTIONS.ts` now uses
+`inventory_units` (the backend's slug) with `nestedPrimaryRecordSlug` `Items`, and
+`useFetchData.tsx`'s primary-fetch filter guard was extended to cover `"Items"`.
 
-**5 of 6** Elite service requests on dev-sandbox have **no linked SalesOrder**, so the details modal
-opens empty — the resolver correctly yields `null` and there is nothing to render. Undecided:
+### Shared-component fixes made along the way (guardrail-safe)
 
-- an explicit "no order linked" empty state, or
-- a ServiceRequest-level detail view (not just an order modal), or
-- making order-less rows non-clickable.
+Each of these touches a component every host renders, so each was written so that **other hosts are
+byte-identical in behavior** — that is the bar for editing shared UI here (see the
+[host-scoping playbook](../../../2.0/apps/toga2-supply/workflows/client-host-scoping.md)):
 
-The prerequisite answer is a data question: **is an order-less service request a legitimate
-lifecycle state**, or is the dev-sandbox data simply incomplete? Do not pick a UI treatment before
-that is answered.
+- `components/ui/Toaster.tsx` — a **message-only** toaster now centers (conditional `flex-1` +
+  `text-center`); the previous `justify-between` stranded the text at the right edge. The condition
+  provably no-ops every other call site (they all pass an action).
+- `pages/Orders/OrdersPage.tsx` — `pageTitle` / `tableDisplayData` state is **re-synced after the
+  host store hydrates**; on a first visit those rendered with `fields` still `undefined`.
+- `pages/Inventory/listing/InventoryPage.tsx` — a URL group uuid that is not in the resolved host's
+  options now falls back to `defaultOption` instead of crashing on the non-null-asserted `find(...)!`.
 
 ## Known limitations / notes
 
@@ -148,6 +188,19 @@ that is answered.
   2026-08-07 prod→beta refresh that wiped the hand-built `service-requests` view.
 
 ## Change history
+- 2026-08-11 — Order-details modal + service-requests polish: per-host
+  `FIELDS/ELITE/BASEFIELDS.json` (Type row from `salesOrderType.name`, `$` currency character,
+  Elite-worded no-details copy, section flags), export button disabled in `FIELDS/ELITE/BASE.json`,
+  inventory nested view renamed to the backend's `inventory_units` slug
+  (`nestedPrimaryRecordSlug: Items`) with `useFetchData.tsx`'s filter guard extended to `"Items"`,
+  and the ELITE skip of the ASN tracking query (`AdvanceShippingNoticeUnits` does not exist in
+  `Client_Elite`). **CORRECTED: ServiceRequests ↔ SalesOrders is 1:N, not 1:1** (SR100001 →
+  SA100000 + SA100003), so the resolver now fetches `uuid`+`number` and picks the lowest number
+  deterministically. **Closed the orphan-SR open question** — an order-less SR is a *designed empty
+  state* ("No order details are available for this service request") driven by the resolver's
+  `isFetched`/`isError` yielding null `orderDetails`. Also landed three guardrail-safe shared-component
+  fixes (Toaster message-only centering, OrdersPage state re-sync after host-store hydration,
+  InventoryPage URL-uuid fallback to `defaultOption`). (tcox)
 - 2026-08-10 — **Service Requests shipped and verified** (INC-13982): implemented as the Orders page
   host-configured, not a new route — new `FIELDS/ELITE/BASE.json` (pageTitle/tableSlug/listingSlug/
   `hasQuoteFilter`/no `approvalActionOptions`), explicit `ELITE` entry in `useOrdersPageViewModel`,

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-08-10
+updated: 2026-08-11
 owners: [tcox]
 files:
   - dbchanges2/Client_Elite/
@@ -112,6 +112,33 @@ note, script, or diff that identifies a join by **row id** is worthless after a
 by **(`tableViewId`, `joinRecordId`, `joinOnRecordFieldId`)** instead — the id columns in the table
 above are a snapshot for orientation, not a key.
 
+## Service-requests column headers — the context-row mapping (authored, BLOCKED)
+
+Elite's `service-requests` view renders several headers as raw camelCase slugs because its columns
+are reached through joins and Elite has no context-scoped label rows for them. The mechanism (why a
+joined column needs `contextRecordFieldId`, and the `Core.PageRecords` gate) is in
+[legacy page meta](../../../2.0/apps/_underscore/features/page-meta-context-field-settings.md).
+
+Mapping derived for the view (target `Core.RecordFields` id → **context** `Core.RecordFields` id):
+
+| Target field id(s) | Context field id | Context field |
+|---|---|---|
+| 566, 574 | 1595 | `ServiceRequests.ticketId` |
+| 679 | 2087 | `customerId` |
+| 203 | 192 | `serviceRequestTypeId` |
+| 48, 175, 58 | 190 | `ServiceRequests.id` |
+| 28 | 43 | `SalesOrders.locationId` |
+| 2766 | — | flat row (base record — **no** context) |
+
+**Blocked on the backend, in this order — do not skip ahead:**
+
+1. The `Page.php` `isset()` guard (~L822–829). Until it ships, inserting these rows fatals every
+   page that carries the labelled field's record but not the context record.
+2. `Core.PageRecords` additions on **`sales-orders-listing`** (Elite reuses it): **Tickets** and
+   **Service request types**. Without them the fields are not emitted into the meta at all.
+3. The `ClientRecordFieldSettings` rows themselves, shipped as a `dbchanges2/Client_Elite/`
+   migration — a hand-insert on beta will not survive the next tenant refresh (see above).
+
 ## Gotchas / known issues
 
 - **A `Client_*` DB that predates a platform migration fails silently until a user opens the
@@ -123,6 +150,12 @@ above are a snapshot for orientation, not a key.
   [error-reporting-issue-event](../../../2.0/apps/_underscore/features/error-reporting-issue-event.md).
 
 ## Change history
+- 2026-08-11 — Added the authored **context-row mapping for the `service-requests` column headers**
+  (target → context `Core.RecordFields` ids; 2766 is flat/base-record) and the mandatory backend
+  ordering it is blocked behind: `Page.php` `isset()` guard → `Core.PageRecords` additions on
+  `sales-orders-listing` (Tickets + Service request types) → the settings rows as a
+  `dbchanges2/Client_Elite/` migration. Unlabelled joined columns currently fall back to the raw
+  `TableViewFields.slug`, which is the camelCase headers on that view. (tcox)
 - 2026-08-10 — Recorded the **2026-08-07 prod→beta rebuild of `Client_Elite`** and its four
   breakages (wiped hand-built `service-requests` view, empty-password `devteam` user, the `isQuote`
   `1054`, and the `/pages/meta` 500), plus the rule that **`TableViewJoins` row ids shift on

package/knowledge/clients/elite/profile.md

@@ -12,7 +12,7 @@ project: Worker
 client: elite
 type: profile
 status: active
-updated: 2026-08-10
+updated: 2026-08-11
 owners: [snaredla, apeterson, tcox, bala]
 files:
   - worker2/Worker/Elite.php
@@ -42,9 +42,11 @@ dbchanges2 **PR #454** (TRUE-80499, snaredla24, 2026-08-05) added the **netsuite
 
 Elite's service-request data model: `ServiceRequests` is the record the `service-requests` table
 view is built on (joining Tickets / Customers / ServiceRequestTypes / SalesOrders, with
-`SalesOrders.serviceRequestId = ServiceRequests.id`, 1:1). **Most Elite service requests on
-dev-sandbox have no linked sales order** — whether that is a legitimate lifecycle state is an open
-question for backend/product (see supply2-scope).
+`SalesOrders.serviceRequestId = ServiceRequests.id`). **That relationship is 1:N, not 1:1**
+(corrected 2026-08-11 — SR100001 links to both SA100000 and SA100003), so anything resolving an SR
+to "its" sales order must pick deterministically. **Most Elite service requests on dev-sandbox have
+no linked sales order at all**, and that is now treated as a legitimate state: the details modal
+renders a designed "no order details" empty state (see supply2-scope).
 
 **Elite orders are pushed to NetSuite event-driven (2026-08).** `_Model_Elite_SalesOrder`'s
 `postPost`/`postPut` interceptors queue the shared worker2 push. Elite's

package/package.json

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