toga-ai 1.0.643 → 1.0.644

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

@@ -16,7 +16,7 @@
 | [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/common_sync_togasupply.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 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, library/app/netsuite.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 |
 | [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | `library/app/api/toga2.php` handles bidirectional ticket sync for PC Matic B2B between TOGaDesk 1.0 and TOGA 2.0. | library/app/api/toga2.php, library/app/api/startechticket.php, worker/crons/toga2/startech/common_import_supporting_records.php |
 | [App_Api_Toga2 — TOGa2 API Client & 1.0↔2.0 Sync Bridge](features/toga2-api-client-and-bridge.md) | `App_Api_Toga2` (`library/app/api/toga2.php`, ~8400 lines) is the **1.0-side client for the TOGa 2 (`_underscore`/api2) public API** *and* the home of the cross | library/app/api/toga2.php, worker/crons/toga2/aig/sync_togasupply_aig.php, worker/crons/toga2/wje/sync_togasupply_wje.php, test/@Mark/AIG/test_multi_email.php |

package/knowledge/1.0/apps/library/features/netsuite-suiteql-rest-shim.md

@@ -6,14 +6,16 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-06-11
-owners: [dfranks]
+updated: 2026-08-25
+owners: [dfranks, jcardinal]
 files:
   - library/app/api/netsuite/rest.php
+  - library/app/netsuite.php
 related:
   - netsuite-suiteql-api-reference.md
   - ../architecture.md
   - ../../worker/features/forecast2-netsuite-reconciliation.md
+  - ../../../2.0/apps/_underscore/features/netsuite-rest-client.md
 ---
 
 ## Summary
@@ -90,6 +92,35 @@ Forecast2 tables already store.
 - **TO_DATE rejects impossible dates** (e.g. `2026-06-31`) with an opaque HTTP 400 — validate
   calendar dates before building SuiteQL.
 
+## Transaction status sourcing (1.0) — and the 2026.2 REST `status.id` change
+
+1.0 reaches NetSuite over **two transports, and neither reads status off a REST record GET
+body**:
+
+- **REST adapter (`App_Api_Netsuite_Rest`, `rest.php`).** It *does* issue `/record/v1/...`
+  GETs, but it sources `status` from the **SuiteQL header row** (`$h->status`, from the
+  `SELECT ... status ... FROM ...` at ~L381/574/754 — already a letter) and maps that letter
+  to the SOAP-era text label via an internal **`$statusMap`** (~L471-472, L625-626,
+  L853-854/863). The REST GET body (`$rec`) is only read for shipMethod / opportunity / terms /
+  createdFrom / country — **never status**. Downstream forecast2 crons
+  (`worker/crons/toga2/forecast2/*`) compare `$nsRecord->status` to text, but that text is
+  *adapter-produced* (from the SuiteQL letter via `$statusMap`), not from the changing REST
+  field.
+- **SOAP (`App_NetSuite`, `library/app/netsuite.php`).** Always uses `new NetSuiteService()`
+  (SuiteTalk toolkit) and reads transaction status off the SOAP record as text (e.g.
+  `$items->status != 'Billed'/'Cancelled'/'Closed'` ~L1151/L1434; `$nsInvoice->status ==
+  'Paid In Full'` ~L2546). SOAP is a different API and is unaffected. (The many
+  `->status->isSuccess` / `statusDetail` reads elsewhere are the SOAP **response envelope**,
+  not the record's business status.)
+
+> **NetSuite 2026.2 impact: none for 1.0.** 2026.2 standardizes the `status.id` returned by
+> **REST record GETs** for transactions to single-letter codes across all types (some types
+> return it as text like `"Open"` today); `status.refName` and SuiteQL are unchanged, and
+> SOAP is a separate API. Since no 1.0 code reads `status.id` off a REST GET body, no patch is
+> needed. NetSuite SuiteAnswers ID **89313**. The 2.0 side of the same conclusion (shared REST
+> client + worker2 consumers) is in
+> [`netsuite-rest-client.md`](../../../2.0/apps/_underscore/features/netsuite-rest-client.md).
+
 ## Data model
 
 Reads NetSuite `transaction`, `transactionline`, `previoustransactionlinelink` via SuiteQL and
@@ -108,6 +139,12 @@ None — uniform across clients (NetSuite is a single shared account).
 
 ## Change history
 
+- 2026-08-25 — Documented **1.0 transaction-status sourcing across both transports** and the
+  conclusion that the **NetSuite 2026.2 REST `status.id` text→letter standardization does not
+  affect 1.0** (SuiteAnswers 89313). `App_Api_Netsuite_Rest` derives status from the SuiteQL
+  letter and maps it via an internal `$statusMap` — never from the REST GET body; forecast2
+  crons see that adapter-produced text, not the changing field; `library/app/netsuite.php` is
+  pure SOAP (a different API). Discovery/impact-analysis only — no code changed. (jcardinal)
 - 2026-06-11 — Documented bulk SuiteQL field semantics (tl.id==line, ShipItem NULL cost, iscogs
   COGS filter, createdFrom non-determinism, foreignamountunpaid, sign conventions) surfaced while
   moving the Forecast2 trueup tools off per-id REST GETs. (dfranks)

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

@@ -30,7 +30,7 @@
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php, _underscore/Model.php, _underscore/Model/Rate/Subscription.php |
 | [_Model::save() parent FK cascade — stored-SQL-field recompute deadlocks](features/model-save-parent-cascade-stored-field-deadlock.md) | `_Model::save()` runs a **generic parent foreign-key cascade**: inserting (or saving) a child row that carries an FK to a parent causes `_Model` to **re-load an | _underscore/Model.php, _underscore/Model/Client/PurchaseOrder.php, _underscore/Model/Client/AdvanceShippingNotice.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, _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 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, _underscore/Trait/Netsuite/SalesOrder.php, worker2/Worker/Netsuite/SalesOrder.php, worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Worker/Netsuite/Opportunity.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, _underscore/Model/Client/TableView.php, toga2-supply/src/components/ui/Tables/PrimaryTable/PrimaryTable.tsx |
 | [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/Model.php, _underscore/Query.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, api2/Controller/Index.php |

package/knowledge/2.0/apps/_underscore/features/netsuite-rest-client.md

@@ -6,14 +6,19 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-20
+updated: 2026-08-25
 owners: ["dfranks", "jcardinal", "bala"]
 files:
   - _underscore/Component/Api/Netsuite/Netsuite.php
+  - _underscore/Trait/Netsuite/SalesOrder.php
+  - worker2/Worker/Netsuite/SalesOrder.php
+  - worker2/Component/Forecast/SaleImport/SaleImport.php
+  - worker2/Worker/Netsuite/Opportunity.php
 related:
   - ../../worker2/features/netsuite-salesorder-open-orders-sync.md
   - ../../worker2/features/netsuite-salesorder-outbound-push.md
   - ../../worker2/features/netsuite-opportunity-sync.md
+  - ../../library/features/netsuite-suiteql-rest-shim.md
   - ../architecture.md
 ---
 
@@ -167,6 +172,40 @@ rather than a bad query. Confirmed live 2026-07-28.
 Surfaced building the NYCHH asset-tag backfill (see
 [nychh-asset-tag-backfill](../../worker2/features/nychh-asset-tag-backfill.md)).
 
+## NetSuite transaction status sourcing (2.0) — and the 2026.2 REST `status.id` change
+
+**`fetchRecord()` returns the REST record UNTOUCHED — there is no central status
+normalization in the shared client.** `fetchRecord()` (`Netsuite.php` ~L215-223) does
+`send('GET', route)`, json-decodes, and hands the raw record back; it never reads or maps
+`status`. So whether a 2.0 consumer is exposed to a change in the REST record's `status`
+field depends entirely on *that consumer*, not on the client. Audited 2026-08-25 — every 2.0
+consumer sources transaction status from a change-safe field:
+
+- **`worker2/Worker/Netsuite/SalesOrder.php`** reads `status->refName` (the human-readable
+  label) and compares it to `OPEN_STATUSES` text — never `status.id`.
+- **`worker2/Component/Forecast/SaleImport/SaleImport.php`** — `statusName()` (~L845-853) reads
+  `status->refName`, matched against `EXCLUDED_STATUSES` text. This is the shared engine that
+  Invoice / CashSale / CreditMemo / CashRefund import all delegate to.
+- **`worker2/Worker/Netsuite/Opportunity.php`** — `fetchStatus()` (~L431-444) gets transaction
+  status via **SuiteQL** (`SELECT status FROM transaction`), which already returns the letter
+  and maps `A`/`C`/`D`. (Its `entityStatus.id` at ~L197 is a *different* field — an opaque
+  lookup key, not the transaction status.)
+- **`_underscore/Trait/Netsuite/SalesOrder.php`** — the one text `switch ($nsOrder->status)`
+  (~L589-620) is driven by a **SOAP** `$service->get()` record, not REST.
+- **`api2`** makes no NetSuite calls of its own — it only registers the SDK at boot and writes
+  one hardcoded outbound status literal (`PENDING_FULFILLMENT`); its `->status` reads are its
+  own HTTP response envelope. Not a NetSuite status consumer.
+
+> **NetSuite 2026.2 impact: none for 2.0.** NetSuite 2026.2 standardizes the `status.id` field
+> returned by **REST record GETs** for transaction records to single-letter codes (A/B/D/E/V)
+> across all transaction types (today some types return `status.id` as text like `"Open"`);
+> `status.refName` and SuiteQL are unchanged, and SOAP/SuiteTalk is a different API. Because no
+> 2.0 code reads `status.id` off a REST GET body as text, no patch is needed. NetSuite
+> SuiteAnswers ID **89313**. (Not audited: other 2.0 apps that may consume this client —
+> `toga2-supply`, `toga25-supply`, `tools` — check them the same way if touched.) The 1.0 side
+> of the same conclusion is in
+> [`netsuite-suiteql-rest-shim.md`](../../library/features/netsuite-suiteql-rest-shim.md).
+
 ## Logging
 
 `send()` calls `setLogging(false)`, so **NetSuite REST request/response bodies are NOT written to
@@ -192,6 +231,14 @@ doc.)
 
 ## Change history
 
+- 2026-08-25 — Documented **2.0 NetSuite transaction-status sourcing** and the conclusion that
+  the **NetSuite 2026.2 REST `status.id` text→letter standardization does not affect 2.0**
+  (SuiteAnswers 89313). `fetchRecord()` returns the REST record raw (no central status
+  normalization), and every audited consumer reads status from `status.refName` or SuiteQL, or
+  over SOAP — none reads REST `status.id` as text: worker2 SalesOrder/SaleImport (`refName`),
+  worker2 Opportunity (`fetchStatus()` via SuiteQL), `_underscore` SalesOrder trait (SOAP),
+  api2 (no NetSuite calls). Discovery/impact-analysis only — no code changed. (jcardinal)
+
 - 2026-08-20 — Added **idempotent creates via `externalId`**: `createRecord()` has no idempotency, so
   stamp an `externalId` (NetSuite rejects a duplicate within the account) and read the record back
   with `GET /record/v1/<record>/eid:<externalId>` — the non-SuiteQL fallback, which matters because

package/package.json

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