toga-ai 1.0.375 → 1.0.377

package/knowledge/1.0/apps/library/INDEX.md

@@ -9,6 +9,7 @@
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |
 | [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t | library/app/framework.php, library/app/frameworkindex.php, library/app/mvc.php, library/app/database.php, library/app/model.php, library/app/config.php |
+| [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite `isfulfillable` flag during item sync and stamping it onto the **Agilant | library/app/netsuite.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php |
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem, test/@dave/Junk Drawer/nsq.php |
 | [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. | library/app/api/netsuite/rest.php |
 | [NetSuite Sync Alert Monitor (App_SystemMonitor_NetSuiteIntegration)](features/netsuite-sync-alert-monitor.md) | `App_SystemMonitor_NetSuiteIntegration` (`library/app/systemmonitor/netsuiteintegration.php`, title **"NetSuite Sync Alert"**) is a 1.0 system monitor that watc | library/app/systemmonitor/netsuiteintegration.php, worker/crons/infrastructure/system_monitors.php |

package/knowledge/1.0/apps/library/features/netsuite-item-isfulfillable-sync.md

@@ -0,0 +1,102 @@
+---
+title: isFulfillable from NetSuite during Item Sync (Phase 1)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-07-20
+owners: [bala]
+files:
+  - library/app/netsuite.php
+  - library/app/api/toga2.php
+  - worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php
+related:
+  - toga2-api-client-and-bridge.md
+  - ../../worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md
+---
+
+## Summary
+This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite
+`isfulfillable` flag during item sync and stamping it onto the **Agilant-catalog (source/supplier)
+item** in the 2.0 platform. The client-facing copy is reached separately by the
+[2.0 propagation engine](../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md),
+which walks the supply chain up from the source item. Only the source item is stamped here.
+
+## Key files / entry points
+- `library/app/netsuite.php` — `App_NetSuite::getItemIsFulfillable($itemInternalId): bool|null`.
+  A SOAP `ItemSearchBasic` by internal id; returns the boolean (or `null` when unknown). Mirrors
+  the existing `getItemIsSerialized` exactly — the only prior item flag the sync read.
+- `library/app/api/toga2.php` — `getCreateItem` (~line 4364). During item create/update the sync
+  now reads `$isFulfillableItem = App_NetSuite::getItemIsFulfillable($nsItemInternalId)` and, when
+  **non-null**, stamps `$payload['isFulfillable']` on the create/update PUT|POST to api2. The
+  NetSuite internal id is resolved from the order line or from the part number
+  (`getItemInternalIdFromPartNumber` / `getItemGroupInternalIdFromPartNumber`). Stores
+  `c_netsuiteInternalItemId` on the item.
+- `worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php` — one-time backfill (see below).
+
+## How it works
+1. Item sync resolves the NetSuite internal id for the item (order line, else part-number lookup).
+2. `getItemIsFulfillable` SOAP-searches the item and returns the flag.
+3. If non-null, `getCreateItem` adds `isFulfillable` to the item PUT/POST payload to api2. api2's
+   Items interceptor then propagates it up-chain (Phase 2).
+4. Going forward the **daily sync** handles new items automatically; existing items are caught up
+   by the one-time backfill.
+
+### One-time backfill (July 5+ orders)
+`backfill_isfulfillable_jul5.php` catches up Agilant items on SalesOrders since **2026-07-05**:
+- It **PUTs each source item to `/items`** via `App_Api_Toga2::send` — the *same* call the sync
+  makes — so **api2's interceptor performs the recursion**. It deliberately does **NOT** write the
+  DB directly and does **NOT** walk the chain itself. (Design choice: reuse the one propagation
+  path so backfill and steady-state behave identically.)
+- Reads the value from NetSuite **by part number**, fulfillable-if-any (`max` across matching
+  internal ids).
+- Env-agnostic: `App_Registry::get('config')` with `DB_HOST_PREFERENCE` = `localhost` (local) /
+  `writer.client` (prod); `DRY_RUN` flips true→false. Compass credentials are the same source as
+  `sync_togasupply_compass_usa.php`.
+
+## Key gotcha — what NetSuite `isfulfillable` actually means
+NetSuite `isfulfillable` (SuiteQL `SELECT isfulfillable FROM item`) is **`T` for InvtPart AND
+NonInvtPart (services)**; it is `F` **only** for Group/bundle headers. It does **NOT** distinguish
+physical goods from services — `itemtype` would, but the sync has never used `itemtype` (only
+`isSerialized`), so this feature intentionally reflects NetSuite's flag **as-is**. **Net effect:
+nearly everything resolves to `fulfillable = 1`.**
+
+- **Open product decision (caveat):** because services come back fulfillable, the storefront makes
+  everything clickable. Whether that is intended vs. needing `itemtype` to hide services is
+  **pending product confirmation**.
+
+## Verification performed
+- **Prod read-only dry-run:** 20 reachable Compass items; chain walk correct
+  (Agilant `1989 B4NY9UC#ABA` → Compass `1986 B4NY9UC-2`); ~91% of July-5+ order lines reach a
+  Compass item, all landing on the correct Compass copy.
+- **Local live backfill:** 85 Agilant PUTs → interceptor → 20 distinct Compass items set (all `=1`),
+  each verified to trace through an Agilant source.
+
+## Gotchas / known issues
+- **Value stamped only on the Agilant source item here** — the client-facing copy is set by the 2.0
+  interceptor. If the interceptor rows aren't deployed in the target env, api2 **403s the whole item
+  write** on the unknown `isFulfillable` field (see the Phase-2 doc's deploy gotchas).
+- **Backfill fires the api2 path, not direct SQL.** It relies on the Phase-2 interceptor being live
+  in the env it targets; running it against an env without the interceptor rows will 403 every PUT.
+- **🔐 Credentials:** the backfill's Compass client/api uuids come from config; the API secret lives
+  in `Client_Compass.Apis` (name `Agilant`) — never reproduce the secret value.
+
+## Change history
+- 2026-07-20 — Added `App_NetSuite::getItemIsFulfillable` (SOAP `ItemSearchBasic`, mirrors
+  `getItemIsSerialized`) and wired `getCreateItem` to stamp `isFulfillable` on the item PUT/POST to
+  api2 when non-null (internal id from order line or part-number lookup; stores
+  `c_netsuiteInternalItemId`). Added the one-time `backfill_isfulfillable_jul5.php` cron, which
+  re-PUTs Agilant source items so the api2 interceptor does the recursion (no direct DB writes).
+  Documented the NetSuite `isfulfillable` semantics gotcha (T for InvtPart + services, F only for
+  group headers — does not distinguish service vs physical) and the resulting open product decision.
+  (bala)
+
+## Related docs
+- [App_Api_Toga2 — API Client & 1.0↔2.0 Bridge](toga2-api-client-and-bridge.md) — the transport
+  `getCreateItem`/the backfill use to reach api2.
+- [NetSuite → TOGa Supply Per-Client Sync](../../worker/features/netsuite-togasupply-per-client-sync.md)
+  — the sync engine this item flag rides in.
+- [Phase 2 — isFulfillable propagation up the SO↔PO chain (2.0)](../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md).

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -198,6 +198,12 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 
 ## Change history
 
+- 2026-07-20 — Fixed a pre-existing **missing `try`-close / brace bug** in
+  `common_sync_togasupply.php` (the inventory-adjustments and item-fulfillments blocks lacked a
+  `try` close, a parse error that broke the Compass sync run). Same failure class as the 2026-07-09
+  tier-wide `rest.php` outage — a dropped token in this shared engine crashes the run before records
+  process. (Fixed incidentally while shipping the `isFulfillable` item-sync feature; see the
+  [library Phase-1 doc](../../library/features/netsuite-item-isfulfillable-sync.md).) (bala)
 - 2026-07-10 — Added **Quad + Growrk** to the NetSuite Sync Alert monitor's
   `CLIENT_CONFIGURATIONS` (previously unmonitored); **AIG deliberately left off** (held
   account, checkpoints frozen at the 2026-04-28 seed). Recorded a real, ongoing IF/InvAdj

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

@@ -16,6 +16,7 @@
 | [Error Reporting — Issue/Event Aggregation (agreed POST-to-receiver design)](features/error-reporting-issue-event.md) | Platform-wide error-reporting infrastructure for TOGA 2.0, built around a two-table **Issue / Event** aggregation model in the shared **Core Logs DB**. | _underscore/Error.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, dbchanges2/Logs/2026-07-06 - Issue and Event tables.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 |
 | [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 |
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
 | [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.php |

package/knowledge/2.0/apps/_underscore/features/fulfillable-item-propagation.md

@@ -0,0 +1,126 @@
+---
+title: isFulfillable Propagation Up the SO↔PO Chain
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-20
+owners: [bala]
+files:
+  - _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
+related:
+  - recursive-item-fulfillments.md
+  - ../../../1.0/apps/library/features/netsuite-item-isfulfillable-sync.md
+  - ../../../clients/compass-usa/profile.md
+---
+
+## Summary
+`Items.isFulfillable` is a boolean that gates whether a storefront line's **Qty Fulfilled**
+cell is actionable. The value is **born on the Agilant-catalog (source/supplier) item** during
+the 1.0 NetSuite item sync (see the [Phase 1 doc](../../../1.0/apps/library/features/netsuite-item-isfulfillable-sync.md)),
+but the toga2-supply storefront shows the **client's own catalog row** — a *different* `Items`
+row linked to the source item only through the multi-tier supply chain. This feature is the
+**2.0 (Phase 2)** half: an api2 interceptor that, whenever an item write carries `isFulfillable`,
+walks the `SalesOrderItem`↔`PurchaseOrderItem` chain **upward** and stamps the same value onto
+every client-facing item it reaches. Value flows source → client copy so the storefront gate is
+correct on the row the customer actually sees.
+
+This is a sibling of the [Recursive Item Fulfillments](recursive-item-fulfillments.md) engine —
+same bridge topology, walked for a different payload (a scalar flag rather than fulfillment rows).
+
+## Key files / entry points
+- `_underscore/Model/Client/Item.php`
+  - `propagateFulfillableAcrossChain(string $itemUuid)` (~lines 497–565) — the engine.
+  - `propagateFulfillableWhenPayloadCarriesTheFlag($api)` — the interceptor body, registered on
+    `postPost` and `postPut` for Items. **Gated:** `if (!isset($api->httpPayload->isFulfillable)) return;`
+    so an ordinary item edit that doesn't touch the flag never triggers a chain walk.
+- `_underscore/Model/Compass/Item.php` — Compass's Item subclass **must call
+  `parent::postPost` / `parent::postPut`** so the base propagation isn't shadowed by the Compass
+  price-override override. (Same empty-pass-through pattern the recursive-IF engine relies on.)
+
+## How it works
+1. **Interceptor gate.** `postPost`/`postPut` call `propagateFulfillableWhenPayloadCarriesTheFlag`,
+   which returns immediately unless the payload carried `isFulfillable`. Only the sync (and the
+   one-time backfill) send that field, so day-to-day item edits skip the walk entirely.
+2. **Load the source item** by uuid → `id` + `isFulfillable`. If the value is **NULL**, return
+   (nothing authoritative to propagate).
+3. **Walk the chain UP** with a `WITH RECURSIVE ChainSalesOrderItems` CTE:
+   - **Anchor:** `SalesOrderItems WHERE itemId = <sourceItemId>`.
+   - **Recursive step:** join `PurchaseOrderItems_SalesOrderItems` (PSO) then
+     `SalesOrderItems_PurchaseOrderItems` (SPO) to climb one tier
+     (Agilant SOI → PSO → POI → SPO → next SOI). `UNION` (not `UNION ALL`) stops loops.
+   - **Result:** `SELECT DISTINCT LinkedSalesOrderItems.itemId WHERE itemId <> sourceItemId` —
+     every client-facing item id reachable above the source.
+4. **Diff-only update:**
+   `UPDATE Items SET isFulfillable = <value> WHERE id IN (...) AND (isFulfillable <> <value> OR isFulfillable IS NULL)`.
+   Re-runs are no-ops, so repeated syncs / a re-run backfill are safe.
+
+## Chain topology (VERIFIED in prod)
+- **Agilant items sit on the `PSO.salesOrderItemId` side; Compass (client-facing) items sit on
+  the `SPO.salesOrderItemId` side.** The value born on the Agilant *source* item therefore flows
+  **up** to the Compass item the storefront renders.
+- Same four bridge tables as the recursive-IF engine (`PurchaseOrders_SalesOrders`,
+  `SalesOrders_PurchaseOrders`, `PurchaseOrderItems_SalesOrderItems`,
+  `SalesOrderItems_PurchaseOrderItems`), so a **broken/missing SOI↔POI bridge row breaks this walk
+  too** — the same integrity class as the Compass off-by-one bridge bugs (see
+  [MITS PO → SO Item Linking](../../../clients/compass-usa/features/mits-po-to-so-item-linking.md)).
+
+## Data model / schema (deploy)
+Three `dbchanges2` migrations register the field + hooks; **all must be present in the target
+env or the flag write is rejected:**
+1. **Core RecordField** (`Core/2026-07-17 - Items isFulfillable RecordField.sql`) — recordId **21**
+   (Items), field `isFulfillable`, BOOLEAN.
+2. **Core `ApiPayloadInterceptors`** (`Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql`)
+   — rows for recordId 21, **POST/POST** and **POST/PUT**, global (clientId/apiId null).
+3. **Client column + ACL** (`Client/2026-07-17 - ItemsisFulfillable.sql`) — `Items.isFulfillable`
+   column + ACL rows.
+
+## Conflict rule
+Multi-source kits (an item reachable from more than one source) use **LAST-WRITER-WINS**. A
+deterministic `MIN`/`MAX` aggregate was **deliberately deferred** — harmless while values are
+uniformly `1` (see the Phase-1 gotcha: NetSuite flags nearly everything fulfillable).
+
+## Client variations
+- **Compass** (USA/Canada, DB `Client_Compass`) is the built/verified client. Its `_Model_Compass_Item`
+  overrides `postPost`/`postPut` for a price override, so it **must** `parent::` up to the base or
+  propagation silently never fires.
+- Engine itself is shared `_Model_Client_Item` logic; any client with the schema present gets it.
+
+## Gotchas / known issues
+- **⚠ Interceptors are DB-driven.** The `postPost`/`postPut` PHP does nothing without the
+  `ApiPayloadInterceptors` rows in the **target env's Core DB**. Missing rows → the hook never
+  fires **and** api2 EV-8's the unknown `isFulfillable` field, **403-ing the whole request** (not
+  just dropping the field). This is the same interceptor-row requirement as the recursive-IF engine.
+- **⚠ Cross-cluster Core/client on prod.** On prod, Core and client DBs are on **separate
+  clusters**, so the client ACL migration's cross-DB `Core.RecordFields` uuid lookup must be
+  **resolved/substituted at deploy** — it cannot join across clusters at runtime.
+- **⚠ Compass subclass shadowing.** If a future client subclass overrides Items `postPost`/`postPut`
+  without calling `parent::`, propagation silently stops for that client.
+- **Product decision unresolved (caveat, not a bug).** Because NetSuite's `isfulfillable` is `T`
+  for services as well as physical goods (see Phase-1 doc), propagation makes **everything**
+  clickable on the storefront. Whether "reflect NetSuite's flag as-is" is the intended behavior —
+  vs. using `itemtype` to hide services — is **pending product confirmation**.
+
+## Change history
+- 2026-07-20 — Built the isFulfillable up-chain propagation engine:
+  `propagateFulfillableAcrossChain` + the payload-gated `postPost`/`postPut` interceptor on Items
+  (recursive SOI↔POI CTE, diff-only `UPDATE`), plus the Compass `parent::` fix so the price-override
+  subclass doesn't shadow it. Registered the field + interceptors via three `dbchanges2` migrations
+  (Core RecordField 21, Core POST/POST + POST/PUT interceptor rows, Client column + ACL). Verified
+  in prod (Agilant `1989 B4NY9UC#ABA` → Compass `1986 B4NY9UC-2`; 20 reachable Compass items) and via
+  a local live backfill (85 Agilant PUTs → 20 distinct Compass items set). Last-writer conflict rule
+  for multi-source kits (MIN/MAX aggregate deferred). (bala)
+
+## Related docs
+- [Phase 1 — isFulfillable from NetSuite during item sync (1.0)](../../../1.0/apps/library/features/netsuite-item-isfulfillable-sync.md)
+  — where the value is sourced + the one-time backfill.
+- [Recursive Item Fulfillments](recursive-item-fulfillments.md) — the sibling engine over the same
+  bridge topology.
+- [Compass MITS PO → SO Item Linking](../../../clients/compass-usa/features/mits-po-to-so-item-linking.md)
+  — how the SOI↔POI bridges get built (and the integrity bugs that break this walk).

package/knowledge/2.0/apps/_underscore/features/recursive-item-fulfillments.md

@@ -143,6 +143,9 @@ inheritance. Verified against prod `Client_Compass` chains (≥3 levels deep).
 - 2026-06-08 — Documented the Recursive Item Fulfillments engine (interceptor-driven upstream fulfillment mirroring, bundle scaling, reconcile loop). (jcardinal)
 
 ## Related docs
+- [isFulfillable Propagation Up the SO↔PO Chain](fulfillable-item-propagation.md) — a sibling
+  engine that walks the **same** bridge topology to propagate a scalar item flag (rather than
+  fulfillment rows) from the source item up to the client-facing copy.
 - GroWrk transfer order flow plan: `clients/growrk/features/transfer-order-flow.md`.
 - `_underscore` architecture (interceptors, `internalApiRequest`, `_Model` layer).
 - `api2` architecture (V2 metadata engine that fires these interceptors; the

package/knowledge/2.0/apps/toga25-supply/INDEX.md

@@ -4,6 +4,7 @@
 |-----|---------|-------|
 | [TOGa 2.5 Supply — Architecture](architecture.md) | `toga25-supply` ("TOGa 2.5 Supply") is the **React/TypeScript frontend** for the 2.0 Supply application — an iteration and improvement of `toga2-supply`. | toga25-supply/src/main.tsx, toga25-supply/src/App.tsx, toga25-supply/src/routes.tsx, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/layout/, toga25-supply/src/pages/, toga25-supply/src/hooks/useTableCellInteractions.ts |
 | [Action-Button Rule Engine (Flag / Rule grammar)](features/action-button-rule-engine.md) | A declarative, fully config-driven rule engine that resolves the boolean-ish flags (`isEnabled`, `isVisible`, `isComplete`) on SalesOrder action-button options. | toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
+| [Client API-Fetch Fields (useClientApiFields / apiFields.json)](features/client-api-fetch-fields.md) | The mechanism that resolves a client's **API-fetch projection** — which `fields` / `ojoin` / `join` / `where` to request from the TOGa API for a given page — fr | toga25-supply/src/fieldsConfig/resolveApiConfig.ts, toga25-supply/src/fieldsConfig/useClientApiFields.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx |
 | [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/layout/VendorItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/ |
 | [Column Visibility (URL-driven show/hide columns)](features/column-visibility.md) | A "Columns" header button that opens a modal listing every column from the table meta, lets the user show/hide columns, adjusts the table live, and persists the | toga25-supply/src/components/ColumnVisibilityModal/, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |

package/knowledge/2.0/apps/toga25-supply/features/client-api-fetch-fields.md

@@ -0,0 +1,136 @@
+---
+title: Client API-Fetch Fields (useClientApiFields / apiFields.json)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-07-20
+owners: [apeterson]
+files:
+  - toga25-supply/src/fieldsConfig/resolveApiConfig.ts
+  - toga25-supply/src/fieldsConfig/useClientApiFields.ts
+  - toga25-supply/src/fieldsConfig/index.ts
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
+  - toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/apiFields.json
+  - toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx
+related:
+  - client-configurable-fields.md
+  - surface-frontend.md
+---
+
+## What it is
+
+The mechanism that resolves a client's **API-fetch projection** — which `fields` / `ojoin` /
+`join` / `where` to request from the TOGa API for a given page — from **one colocated
+`apiFields.json` file per page**, keyed by client slug. It is the fetch-projection sibling of
+[client-configurable-fields](client-configurable-fields.md) (`useClientFields`): that hook
+resolves **presentation** config (now largely moving to the DB-backed
+[Surface layer](surface-frontend.md)); this hook resolves **what data to fetch**.
+
+The split exists because presentation config migrated to Surface, leaving the API-fetch wiring
+coupled to a now-legacy `orderViewFields`/`*RecordViewFields` blob (formerly the
+`salesOrderDetailsConfig` / `itemRecordDetailsConfig` keys). This mechanism extracts the fetch
+projection into its own scalable per-page file + a shared resolver, keeping the central
+`fieldsConfig/index.ts` registry lean — **each page owns its own `apiFields.json`** rather than
+folding every page's fetch config into `fieldsConfig/index.ts`.
+
+## How it works
+
+Two new files in `src/fieldsConfig/`, re-exported from `fieldsConfig/index.ts`:
+
+1. **`apiFields.json` (per page, colocated in the page's `viewModel/FIELDS/`).** A map keyed by
+   client slug (uppercase — `DEFAULT`, `COMPASS`, `COMPASSCANADA`, `NYCHH`, …). The `DEFAULT`
+   block is the **full base**. Each per-client block is one of two shapes:
+   - **Delta** — `{ "extends": "DEFAULT", ...only the differences }`, merged over its parent.
+     Use for the common 1–3 field tweak; adding a field to `DEFAULT` then reaches every client.
+   - **Full override** — a complete config with **no `extends`**, returned verbatim. Use when a
+     client diverges substantially (many fields / different joins / different `where` clauses).
+
+2. **`resolveApiConfig(map, clientSlug)`** — a pure, recursive deep-merge resolver:
+   - **Array fields** (`fields`, `ojoin`, `join`) support `add<Field>` / `remove<Field>` sugar
+     (`addFields`, `removeFields`, `addOjoin`, …) to tweak the parent's array, **or** you restate
+     the array literally to replace it wholesale (a literal wins over add/remove).
+   - **Nested objects** merge recursively; **scalars / new keys** replace the parent value.
+   - **Array element identity** for dedupe/removal: strings by value, join objects by their
+     **first object key** (e.g. `{ "Items": {...} }` → `Items`), else by JSON form. Results are
+     deduped.
+   - Supports **chained `extends`** (a client can extend another client) with a **cycle guard**
+     (a re-visited slug returns its own delta un-merged). An **unknown client falls back to
+     `DEFAULT`**; a missing `DEFAULT` yields `{}`.
+
+3. **`useClientApiFields(map)`** — reads the client slug via
+   `useHostnameStore.getState().getHostname()` (the **same** slug source as `useClientFields`),
+   then `useMemo`s `resolveApiConfig(map, slug)` so consumers get a **stable object reference**
+   and the react-query fetch cache key does not churn every render. API-fetch fields are
+   **client-only** — there is no role dimension (they describe *what to fetch*, not a per-role
+   view).
+
+The view model consumes it directly:
+
+```ts
+const salesOrderDetailsConfig = useClientApiFields(apiFields) as Parameters<
+  typeof useFetchSalesOrderRecord
+>[1];
+```
+
+## Hybrid dedup model (decision)
+
+The per-client shape is deliberately a **hybrid**: `DEFAULT` base + per-client delta, with a
+full-override escape hatch. Chosen over full-copy-per-client because differences are usually
+1–3 fields (the delta case, kept DRY so a field added to `DEFAULT` reaches every client) but can
+be 5+ fields plus different joins/where clauses (the full-override case). Full-copy-per-client
+drifts too fast across 6+ clients. The resolver location is likewise a decision: a **generic
+colocated hook** (per-page `apiFields.json` + one shared hook), **not** folding every page's
+fetch config into the central `fieldsConfig/index.ts`.
+
+## Adopting the pattern on a page
+
+1. Add `viewModel/FIELDS/apiFields.json`: a `DEFAULT` full base, plus a block per client that
+   diverges (`extends: "DEFAULT"` + `add<Field>`/`remove<Field>` deltas, or a no-`extends` full
+   override). A client whose config is byte-identical to `DEFAULT` can be **omitted** — the
+   resolver's DEFAULT fallback covers it.
+2. Wire the view model to `useClientApiFields(apiFields)`, casting to the fetch hook's param type
+   (`Parameters<typeof useFetch...>[1]`).
+3. Delete the now-dead fetch block from the legacy presentation JSON (single source of truth).
+
+**Adopted so far:**
+- **SalesOrder record modal** — `SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json`
+  (DEFAULT full base; COMPASS / COMPASSCANADA as `extends: DEFAULT` + `addFields` deltas, e.g.
+  `_totalLease`, `c_erpEntityId`). The view model's `salesOrderDetailsConfig` now comes from
+  `useClientApiFields(apiFields)` instead of `tenantFields.salesOrderDetailsConfig`; the dead
+  `salesOrderDetailsConfig` block was removed from `FIELDS/DEFAULT/orderViewFields.json`.
+- **Item record modal** — `ItemRecordModalLayout/viewModel/FIELDS/apiFields.json` (DEFAULT full
+  base of 31 fields; COMPASS + COMPASSCANADA as `extends: DEFAULT` + a 6-field `addFields` delta:
+  `_leasePrice`, `_leasePrice12Months`, 4× `personaItems.*`; **NYCHH omitted** — byte-identical to
+  DEFAULT). The view model consumes `useClientApiFields(apiFields)` (dropping its own
+  `useClientFields`; view sections still read `useClientFields` in the view components). The dead
+  `itemRecordDetailsConfig` block was removed from all four client
+  `itemRecordViewFields.json` files, which now hold only presentation keys
+  (`header`/`sections`/`editItem`).
+
+## Gotchas
+
+- **Field order in a `fields` projection array is irrelevant to the TOGa API fetch.** The API
+  returns requested fields regardless of order, and the reshape/view logic reads by key — so
+  append-style delta merges (added fields land at the end) are **safe** and do not change
+  behavior. This is why `add<Field>` sugar can append without needing positional control.
+- **Omit a client that matches `DEFAULT`.** Don't author a byte-identical client block — the
+  resolver falls back to `DEFAULT` for any unknown/absent client, so an identical block is pure
+  drift risk (NYCHH on the Item modal is deliberately absent).
+- **Same slug source as presentation.** The slug comes from `useHostnameStore.getHostname()` (the
+  same source as `useClientFields`); don't introduce a second slug resolution path.
+
+## Change history
+- 2026-07-20 — Built the client-based API-fetch fields mechanism: `resolveApiConfig` (pure
+  recursive deep-merge with `add`/`remove` array sugar, literal-replace, chained `extends` +
+  cycle guard, DEFAULT fallback) + `useClientApiFields` (client-only, slug via `useHostnameStore`,
+  memoized for stable fetch cache keys), each page owning a colocated `apiFields.json`. Adopted on
+  the SalesOrder and Item record modals; removed the dead `salesOrderDetailsConfig` /
+  `itemRecordDetailsConfig` fetch blocks from the legacy presentation JSON. Decision: hybrid
+  DEFAULT-base + per-client-delta with a full-override escape hatch (over full-copy-per-client).
+  Discovered: `fields`-array order is irrelevant to the API fetch. (apeterson)
+</content>
+</invoke>

package/knowledge/2.0/apps/toga25-supply/features/client-configurable-fields.md

@@ -22,6 +22,7 @@ related:
   - ../architecture.md
   - column-visibility.md
   - action-button-rule-engine.md
+  - client-api-fetch-fields.md
 ---
 
 ## What it is
@@ -31,6 +32,14 @@ filter buttons, group-by options, column pickers, layout toggles — without har
 the view model or rebuilding per client. All such config resolves through `src/fieldsConfig`
 and the `useClientFields()` hook.
 
+> **Scope — presentation, not fetch.** This doc covers **presentation/UI** config. A client's
+> **API-fetch projection** (which `fields`/`ojoin`/`join`/`where` to request) now lives in a
+> separate per-page `apiFields.json` resolved by `useClientApiFields` — see
+> [client-api-fetch-fields](client-api-fetch-fields.md). The old fetch keys
+> (`salesOrderDetailsConfig` in `orderViewFields`, `itemRecordDetailsConfig` in
+> `itemRecordViewFields`) were **extracted out** of these presentation JSON files; those files
+> now hold presentation keys only.
+
 ## How it works
 
 1. **Per-client JSON lives next to the consuming page _or layout_**, under `FIELDS/<CLIENT>/`
@@ -159,6 +168,11 @@ modal's chrome from the same per-client JSON, not from the component:
   `vendorItemRecordViewFields` are record-modal-layout examples living under `src/layout/.../viewModel/FIELDS/`.
 
 ## Change history
+- 2026-07-20 — Extracted the **API-fetch projection** out of these presentation JSON blobs into a
+  new per-page `apiFields.json` + `useClientApiFields` mechanism (see
+  [client-api-fetch-fields](client-api-fetch-fields.md)). The `salesOrderDetailsConfig` block was
+  removed from `FIELDS/DEFAULT/orderViewFields.json` and the `itemRecordDetailsConfig` block from
+  all four `itemRecordViewFields.json` files; those files now hold presentation keys only. (apeterson)
 - 2026-07-01 — De-roled `orderViewFields` from client×role to **client-only**: COMPASS/COMPASSCANADA
   now read a flat client JSON via `mergeOrderView(...)` in `fieldsConfig/index.ts` (COMPASSCANADA's
   JSON flattened from byte-identical `{ADMIN,MANAGER}`). Fixed a latent bug where COMPASS's

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 12 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 13 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 15 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 9 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 34 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 35 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 30 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 12 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
@@ -29,7 +29,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 7 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 9 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 9 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 10 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)
 

package/knowledge/clients/compass-usa/profile.md

@@ -11,6 +11,7 @@ apps:
   - worker1.5
   - worker2
   - dbchanges2
+  - library
 project: _Underscore
 client: compass-usa
 type: profile
@@ -88,4 +89,10 @@ separate, related client (see its own profile).
   order. Contrast Quad, which gets the full picked/packed machine. See
   [IF stage lifecycle & order status](../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md).
 - Built on the shared 2.0 Recursive Item Fulfillments engine (upstream mirroring).
+- **`Items.isFulfillable` gates the storefront Qty Fulfilled cell (2026-07).** Sourced from
+  NetSuite onto the Agilant source item during the 1.0 item sync
+  ([Phase 1](../../1.0/apps/library/features/netsuite-item-isfulfillable-sync.md)) and propagated
+  up the SO↔PO chain to the client-facing Compass item by an api2 interceptor
+  ([Phase 2](../../2.0/apps/_underscore/features/fulfillable-item-propagation.md)). Verified on prod
+  Compass chains; a one-time July-5+ backfill re-PUTs source items through the same path.
 - This profile is a starting point; expand as more Compass-specific behavior is captured.

package/package.json

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