toga-ai 1.0.61 → 1.0.63

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

@@ -4,4 +4,5 @@
 |-----|---------|-------|
 | [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. | library/_.php, library/app/, library/browser/ |
 | [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 |
+| [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 |
 | [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 |

package/knowledge/1.0/apps/library/features/netsuite-suiteql-api-reference.md

@@ -0,0 +1,321 @@
+---
+title: NetSuite SuiteQL/REST API Reference
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-06-11
+owners: ["dfranks"]
+files:
+  - library/app/api/netsuite/rest.php
+  - library/ssl/netsuite_ec_key.pem
+related:
+  - netsuite-suiteql-rest-shim.md
+  - ../architecture.md
+  - ../../worker/features/forecast2-netsuite-reconciliation.md
+---
+
+## Summary
+
+General working reference for the Agilant NetSuite integration: how to authenticate, how
+SuiteQL behaves, and the confirmed schema of the tables/columns/codes we query. The client class
+is `App_Api_Netsuite_Rest` (`library/app/api/netsuite/rest.php`), split out of the old
+`netsuite.php` ~2026-05-15. SOAP is deprecated — **production code must use REST/SuiteQL**; SOAP
+is acceptable only for ad-hoc troubleshooting.
+
+This doc is the **broad map** (mechanics, schemas, codes, performance). For the deep field
+*semantics* that silently corrupt totals (sign conventions, `tl.id`==line, ShipItem NULL cost,
+`iscogs` COGS lines, `createdFrom` non-determinism), see the companion
+`netsuite-suiteql-rest-shim.md`.
+
+## Authentication
+
+- **REST OAuth 2.0 / JWT client-credentials.** The client assertion is signed with an EC private
+  key at `library/ssl/netsuite_ec_key.pem`. Token lifetime is **3600s**; the adapter auto-refreshes
+  ~60s before expiry (`TOKEN_EXPIRATION_SAFETY_SECONDS`).
+- The `certificateId` (the JWT `kid`) comes from the NetSuite integration record. The **worker**
+  config (`worker/config.*.ini` `[netsuite]` section) holds the real value; `worker2/Config/` ships
+  a placeholder `CERTIFICATE_ID_HERE` that `initialize()` explicitly rejects.
+- `readConfig()` supports two framework contexts: 1.0 via `App_Registry::get('config')['netsuite']`,
+  and 2.0 via `_Config::netsuite()`.
+
+## Bootstrapping the client from a standalone script
+
+To use the client outside a normal app entry point (e.g. a `test/@dave` CLI):
+
+```php
+$_SERVER['SCRIPT_FILENAME'] = realpath(__DIR__ . '/../../worker') . DIRECTORY_SEPARATOR . '_approot_anchor.php';
+chdir(__DIR__ . '/../../worker');   // REQUIRED — OAuth cert / certificateId resolves relative to worker/
+require_once('_.php');
+App_Framework_Worker::initialize();
+App_Api_Netsuite_Rest::authenticate();   // acquire OAuth2 token once
+```
+
+- **`chdir` into `worker/` is mandatory** — without it the OAuth `certificateId`/cert path won't
+  resolve and `authenticate()` throws.
+- In our usage the client is effectively **read-only**: only `GET` (record fetch) and `POST`
+  (SuiteQL) are exercised. `send()` accepts any verb (incl. PATCH/PUT) but we don't write through it.
+
+### The `send()` logging trap (dev laptop)
+
+`App_Api_Netsuite_Rest::send()` auto-authenticates but does **not** call `setLogging(false)`. From a
+dev laptop the API-log DB write then fails and the framework error handler reports a **misleading
+"Could not connect to database 'Vision'"** that masks the real result. Workaround: `authenticate()`
+once, then issue your own `App_ApiTransaction` with logging off:
+
+```php
+$url = rtrim(App_Api_Netsuite_Rest::$endpoint, '/') . App_Api_Netsuite_Rest::API_BASE_PATH
+     . '/query/v1/suiteql?limit=1000&offset=0';
+$req = new App_ApiTransaction('POST', $url, ['q' => $sql], App_ApiTransaction::ENCODE_JSON);
+$req->setLogging(false);
+$req->addHeader('Authorization', 'Bearer ' . App_Api_Netsuite_Rest::$accessToken);
+$req->addHeader('Accept', 'application/json');
+$req->addHeader('Content-Type', 'application/json');
+$req->addHeader('Prefer', 'transient');     // required for SuiteQL
+$resp = $req->execute(false);
+```
+
+In production (worker/EB) `send()` is fine — the Logs DB is reachable there.
+
+## SuiteQL
+
+- **Endpoint:** `POST {base}/query/v1/suiteql?limit=1000&offset=N`, body `{"q": "<sql>"}`.
+- **`Prefer: transient` header is required** (avoids server-side cursor overhead / errors).
+- **Pagination:** max `limit=1000`; the response carries `items[]` and a boolean **`hasMore`**. Loop
+  `offset += 1000` until `hasMore` is false. The private `suiteqlListAll()` helper in `rest.php` does
+  exactly this.
+- **Session timezone is `America/New_York`** — `CURRENT_DATE`/`CURRENT_TIMESTAMP`, `TO_TIMESTAMP()`,
+  and `lastmodifieddate` all resolve in ET (−04:00/−05:00), distinct from the account's "Pacific"
+  setting. Confirmed empirically: `SYSDATE` is −07:00 but the date columns are ET. **Build window
+  bounds in ET.**
+- **Date vs timestamp filters:** `trandate` is a **DATE** column — use
+  `TO_DATE('YYYY-MM-DD', 'YYYY-MM-DD')`. `lastmodifieddate` is a **TIMESTAMP** — use
+  `TO_TIMESTAMP('YYYY-MM-DD HH:MM:SS', 'YYYY-MM-DD HH24:MI:SS')`. `TO_DATE` rejects impossible
+  calendar dates (e.g. `2026-06-31`) with an opaque HTTP 400 — validate dates before building SQL.
+- **Oracle-flavored functions work:** `TO_DATE`, `TO_TIMESTAMP`, `TO_CHAR(trandate,'YYYY')` /
+  `'YYYY-MM'` for bucketing, `NVL(...)`, and `BUILTIN.DF(field)` for a reference field's display
+  value (e.g. `BUILTIN.DF(entity)` → customer name, `BUILTIN.DF(status)` → "Pending Fulfillment") —
+  a cheap alternative to per-id GETs for display strings.
+- **`ORDER BY` inside a `GROUP BY` query is rejected** with `Invalid or unsupported search`. Sort in
+  PHP after fetching all pages.
+- **Correlated subqueries are supported** (used in `listSales()` for `orderLine` — see the
+  `previousTransactionLineLink` section).
+
+### Debugging: the framework swallows errors as an HTML page
+
+A failing query (or any PHP error) often renders the framework's HTML "Oops" error page with a
+Sentry Error ID instead of a usable message. To see the real cause from a CLI script:
+
+- check `$req->responseCode` and print the raw body on a non-2xx, and/or
+- register a shutdown handler: `register_shutdown_function(function () { print_r(error_get_last()); });`
+
+`execute()` may return an already-decoded object **or** a string — normalize with
+`json_decode(json_encode($resp), true)` and always check `responseCode` is 2xx first.
+
+## `transaction` table
+
+### Type codes (`transaction.type`)
+
+| Code | Meaning |
+|------|---------|
+| `SalesOrd` | Sales Order |
+| `CustInvc` | Invoice |
+| `CashSale` | Cash Sale |
+| `CashRfnd` | Cash Refund |
+| `CustCred` | Credit Memo |
+| `Opprtnty` | Opportunity |
+| `PurchOrd` | Purchase Order |
+| `ItemRcpt` | Item Receipt |
+| `ItemShip` | Item Fulfillment |
+| `InvAdjst` | Inventory Adjustment |
+
+### Status codes (`transaction.status` letter)
+
+**Sales Orders:** `A` Pending Approval · `B` Pending Fulfillment · `C` Cancelled ·
+`D` Partially Fulfilled · `E` Pending Billing/Partially Fulfilled · `F` Pending Billing ·
+`G` Billed · `H` Closed. **"Open" sales orders = `B`, `D`, `E`, `F`.** Note `listSalesOrders()`
+returns **all** statuses for a window (no server-side status filter) — callers must filter.
+
+**Invoices:** `A` Open · `B` Paid In Full.
+**Credit Memos:** `A` Open · `B` Fully Applied.
+**Cash Sales:** `A` Unapproved Payment · `C` Deposited.
+**Cash Refunds:** `Y` (the only status; empty string in SOAP).
+
+### Header columns present (✓ confirmed in SuiteQL)
+
+`id`, `tranid`, `trandate`, `lastmodifieddate`, `type`, `status`, `entity`, `employee`,
+`leadsource`, `terms`, `memo`, `otherrefnum`, `foreigntotal`/`total` (both return the same value),
+`foreignamountunpaid` (AR balance — invoices only; NULL for SO/credit memo/cash sale), `duedate`,
+`shipmethod`, `opportunity`, `shippingaddress` (numeric id → join `transactionShippingAddress`),
+and custom fields (`CUSTBODY_END_CUSTOMER`, `CUSTBODY_STOCKING_ORDER`, …).
+
+### Header fields NOT in SuiteQL (✗ — require a per-id REST GET)
+
+`shippingCost`, `taxTotal`, `subTotal`, `createdFrom` (also derivable from
+`previousTransactionLineLink`, but non-deterministically — see shim doc), `trackingNumbers`,
+`linkedTrackingNumbers`, and the **structured** `shippingAddress` object (SuiteQL gives only the id).
+
+## `transactionline` table
+
+### Key columns (confirmed present)
+
+`transaction`, `linesequencenumber`, `uniquekey`, `id`, `item`, `itemtype`, `mainline`, `quantity`,
+`foreignamount`, `rate`, `costestimate`, `class`, `memo`, `quantitybilled`, `quantitycommitted`,
+`quantitypicked`, `quantityshiprecv`, `createdfrom`, `entity` (line-level customer), `location`,
+`subsidiary`.
+
+- **`mainline = 'F'`** selects detail (non-summary) lines; `mainline = 'T'` is the header row.
+- **`tl.orderline` does NOT exist** — HTTP 400 `Field 'orderline' for record 'transactionLine' was
+  not found.` The originating SO line lives in `previousTransactionLineLink`.
+- **Synthetic-line sentinels:** `tl.item` returns **negative ids** for synthetic rows (e.g. `-8` =
+  TaxGroup "-Not Taxable-"). Filter `tl.item > 0`, and exclude `itemtype NOT IN ('ShipItem',
+  'TaxItem','TaxGroup','Discount','EndGroup','BeginGroup','Subtotal','Description','Markup',
+  'Payment')`.
+- Sign conventions and the `tl.id`==`line` rule are detailed in `netsuite-suiteql-rest-shim.md`.
+
+### Line filtering for revenue queries
+
+- `tl.mainline = 'F'` and `tl.item > 0` plus the itemtype denylist above.
+- For a **product vs shipping** split, also exclude `'ShipItem'`/`'Discount'` from product and sum
+  `ShipItem` separately.
+- **Open-order (in-flight) product revenue:** `((-tl.quantity) - NVL(tl.quantitybilled,0)) * tl.rate`;
+  shipping term `SUM(-tl.foreignamount)` over `tl.itemtype = 'ShipItem'`.
+
+## `previousTransactionLineLink` table
+
+The bridge between a child line (e.g. invoice) and its originating parent line (e.g. SO).
+
+| Column | Meaning |
+|--------|---------|
+| `nextdoc` / `nextline` / `nexttype` | Child transaction id / its `linesequencenumber` / type (e.g. `CustInvc`) |
+| `previousdoc` / `previousline` / `previoustype` | Parent id / its `linesequencenumber` (= SOAP `orderLine`) / type (e.g. `SalesOrd`) |
+| `linktype` | e.g. `OrdBill`, `OrdRvCom`, `OppClose` |
+
+**SOAP `orderLine` for an invoice line:**
+
+```sql
+SELECT MIN(potl.previousline)
+FROM previoustransactionlinelink potl
+WHERE potl.nextdoc = <invoice_id>
+  AND potl.nextline = <linesequencenumber>
+  AND potl.previoustype = 'SalesOrd'
+```
+
+Filter `previoustype = 'SalesOrd'` to exclude the `OppClose` → Opportunity link; `MIN()` collapses
+the multiple link types (`OrdBill`, `OrdRvCom`) that reference the same line. For `createdFrom`, the
+REST record GET is authoritative — the mainline link is ambiguous (see shim doc).
+
+## `transactionShippingAddress` table
+
+`transaction.shippingaddress` is a numeric id → join here **on `nkey`** (`WHERE id = ...` does NOT
+work; the pk is `nkey`). Columns: `addr1`, `addr2`, `addressee`, `attention`, `city`, `state`
+(two-letter), `country` (two-letter), `zip`, `addrtext` (formatted full-address blob).
+
+## `item` table
+
+`itemtype` (+ `subtype` / `isserialitem`) → REST shim `_recordType` / SOAP class:
+
+| `itemtype` + qualifier | `_recordType` |
+|------------------------|---------------|
+| `InvtPart` + `isserialitem=T` | `serializedInventoryItem` |
+| `InvtPart` + `isserialitem=F` | `inventoryItem` |
+| `NonInvtPart` + `Sale` / `Resale` / `Purchase` | `nonInventorySaleItem` / `nonInventoryResaleItem` / `nonInventoryPurchaseItem` |
+| `OthCharge` + `Sale` / `Resale` | `otherChargeSaleItem` / `otherChargeResaleItem` |
+| `Service` + `Sale` / `Resale` | `serviceSaleItem` / `serviceResaleItem` |
+| `Discount` / `Kit` / `Group` / `Description` | `discountItem` / `kitItem` / `itemGroup` / `descriptionItem` |
+| `Expense` | **skip** — internal; no SOAP equivalent |
+
+`item.description` = SOAP `salesDescription`; `item.purchasedescription` = SOAP
+`purchaseDescription`. There is **no** SuiteQL `salesdescription` column.
+
+## `customer` table
+
+- `BUILTIN.DF(custentity10)` = display name of the **Consolidated Customer** custom field (CF id
+  4968, script id `custentity10`); SOAP `customFieldList` CF internalId 4968 maps to this.
+- `entityid` and `companyname` are split in SuiteQL; SOAP concatenated them as
+  `"<entityid> <companyname>"`. When they're equal, return the value once (don't duplicate).
+
+## Custom fields
+
+| NS internalId | Script id | Description |
+|---------------|-----------|-------------|
+| 3149 | `CUSTBODY_END_CUSTOMER` | End Customer (on transaction) |
+| 7097 | `CUSTBODY_STOCKING_ORDER` | Stocking Order flag |
+| 4968 | `custentity10` | Consolidated Customer (on customer record) |
+| 6840 | `custbody_forecast_category` | Forecast Category (on opportunity) |
+| 6841 | `custbody_sales_stage` | Sales Stage (on opportunity) |
+| 3942 | `custbody_ctc_account` (`CF_ACCOUNT`) | Account |
+| 6579 | `custbody_ctc_business_unit` (`CF_BUSINESS_UNIT`) | Business Unit |
+
+## REST per-id record GET
+
+Used for fields SuiteQL doesn't expose on `transaction`: `shippingCost`, `taxTotal`, `subTotal`,
+`amountRemaining` (SuiteQL `foreignamountunpaid` is the equivalent), `trackingNumbers` /
+`linkedTrackingNumbers`, the structured `shippingAddress`, the `createdFrom` reference, and the
+**stable `line` number** on the record sublist (`line` ↔ `lineUniqueKey`).
+
+- **Stable line numbers — the critical one.** The REST record's `item.items[*].line` (via
+  `lineUniqueKey`) is the **authoritative** source for `Forecast.Sales.lineNumber`. SuiteQL
+  `linesequencenumber` can diverge from REST `line` for SOAP-era records (confirmed empirically),
+  so keying on `linesequencenumber` risks duplicate Sales rows that can't be matched or deleted.
+  **`listSales()` keeps the per-id GET for this reason — do not eliminate it.**
+
+## `list*()` helpers — behavior & cost
+
+`listSales()`, `listSalesOrders()`, `listOpportunities()` all:
+
+1. **Filter on `lastmodifieddate`, NOT `trandate`.** A record dated long ago but edited recently IS
+   returned; a recently-dated but unmodified record is NOT. (Trips up any local lookup that windows
+   on transaction date.)
+2. Fetch headers via paginated SuiteQL, then — for sales / sales-orders — do a **per-id REST GET per
+   header** for the GET-only fields above, then fetch lines in `id` chunks of 500.
+
+**Cost implication:** runtime scales with the number of records *modified* in the window (open +
+closed) because of the per-id GET, not with the number you care about — a wide window is expensive.
+`listOpportunities()` has no per-id GET, so it runs in minutes regardless of window.
+
+### Measured volumes / latency (Agilant account, 2024–2026)
+
+| Metric | Value |
+|--------|-------|
+| Heaviest month (Aug 2024) | 14,795 transactions / 69,802 item lines |
+| Typical heavy month | ~4,000–6,000 transactions |
+| SuiteQL header page (1000 rows) | ~1.5s |
+| SuiteQL line chunk (500 txns, 1000 rows) | ~1.4s |
+| SuiteQL link chunk (500 txns, 1000 rows) | ~0.5s |
+| Per-id REST GET (one record) | ~100–150ms |
+| `listSales()` — typical month (5k txns) | ~1.5–2h (GET-bound) |
+| `listSales()` — Aug 2024 (14.8k txns) | ~4–6h (GET-bound) |
+| `listOpportunities()` — same window | minutes (no GET) |
+
+SalesOrd per-id GET counts by `lastmodifieddate` window: ~16,600 (90d) / ~61,900 (365d) / ~145,700
+(3yr) — vs only ~13,500 currently-open SOs, i.e. a 3-year window does ~10× the work of the target
+set. Fields that *could* move to the header query (eliminating most GETs): `total`,
+`foreignamountunpaid`, `dueDate`, `terms`, `shipMethod`, `opportunity`, `shippingAddress`. Fields
+that **cannot**: `shippingCost`, `taxTotal`, `subTotal`, `trackingNumbers`, and the stable `line`
+numbers. Budget hours for multi-year runs and launch them under `nohup`/`tmux`.
+
+## Gotchas / known issues
+
+- **PHP 7.2 prod constraint.** `library`/`worker` run PHP 7.2 (Amazon Linux 1 EB). Banned syntax:
+  arrow functions (`fn() =>`), typed properties (`public int $x`), `??=`, `match()`, numeric
+  separators (`1_000`). Lint with `C:\xampp7\php\php.exe -l` before deploying — `C:\xampp8\php`
+  (PHP 8.0) is for running probes on the laptop only, **not** for compat checking.
+- Field/relationship availability varies by NetSuite account **and** record type — probe the live
+  account before assuming a column exists.
+
+## Change history
+
+- 2026-06-11 — Initial reference captured from live-probe notes (TRUE-79183): SuiteQL mechanics,
+  ET session timezone, transaction/transactionline/previousTransactionLineLink/shippingAddress/item
+  schemas, type & status codes, custom-field map, REST GET-only fields, `list*()` cost model and
+  measured volumes. (dfranks)
+
+## Related docs
+
+- `netsuite-suiteql-rest-shim.md` — deep field semantics (signs, `tl.id`==line, `iscogs`, ShipItem
+  cost, `createdFrom`) that sit on top of these mechanics.
+- `../../worker/features/forecast2-netsuite-reconciliation.md` — the audit/trueup tooling that
+  consumes this API.

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

@@ -11,6 +11,7 @@ owners: [dfranks]
 files:
   - library/app/api/netsuite/rest.php
 related:
+  - netsuite-suiteql-api-reference.md
   - ../architecture.md
   - ../../worker/features/forecast2-netsuite-reconciliation.md
 ---
@@ -113,5 +114,7 @@ None — uniform across clients (NetSuite is a single shared account).
 
 ## Related docs
 
+- `netsuite-suiteql-api-reference.md` — the broad API reference (auth, SuiteQL mechanics, table
+  schemas, type/status codes, custom-field map, performance) these semantics sit on top of.
 - `../architecture.md` — Library core architecture.
 - `../../worker/features/forecast2-netsuite-reconciliation.md` — the tooling that applies these.

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

@@ -3,4 +3,4 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Worker (1.0 Framework) Architecture](architecture.md) | `worker` is the legacy (**1.0** `App_` framework) **background-job tier**. | worker/index.php, worker/_/app/framework.php, worker/crons/, worker/schedules/, worker/ebs/cron.worker.php, worker/.ebextensions/035_cron.worker.config |
-| [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/reconcile_netsuite_totals.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
+| [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/reconcile_netsuite_totals.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |

package/knowledge/1.0/apps/worker/features/forecast2-netsuite-reconciliation.md

@@ -13,10 +13,13 @@ files:
   - test/@dave/analyze_netsuite_forecast_diff.php
   - test/@dave/trueup_sales.php
   - test/@dave/trueup_open_orders.php
+  - test/@dave/trueup_opportunities.php
+  - test/@dave/probe_sales_gap_direct.php
   - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
 related:
   - ../architecture.md
   - ../../library/features/netsuite-suiteql-rest-shim.md
+  - ../../library/features/netsuite-suiteql-api-reference.md
 ---
 
 ## Summary
@@ -38,6 +41,11 @@ by reconciling a chosen tranDate range directly against NetSuite.
   match NetSuite for a tranDate range (insert/update/delete per line).
 - `trueup_open_orders.php --from= --to= [--prod] [--dry-run] [--verbose]` — same for
   `Forecast.OpenOrderItems` (currently-open SOs whose tranDate falls in range).
+- `trueup_opportunities.php --from --to [--prod] [--dry-run]` — same for `Forecast.Opportunities`
+  by tranDate range. Pure SuiteQL (no per-id GET), so it's fast: a 2026-YTD prod run reconciled
+  ~4,000 opps in ~13s to a $0 delta.
+- `probe_sales_gap_direct.php` / `probe_open_orders_gap.php` — read-only NS-vs-FC2 revenue
+  breakdowns by type+month using **direct prod mysqli** (demonstrate the sandbox-dev bypass below).
 
 ## How it works
 
@@ -92,11 +100,36 @@ None — Forecast2 is a single shared dataset.
 - **Always dry-run prod first** and confirm the change counts are real drift, not artifacts —
   e.g. 2023-01-03 showed 240 "updates" that were entirely createdFrom backfill + profit float-dust
   (zero real drift); after the fixes it correctly reports `unchanged=240`.
+- **`App_Database` routes *reads* to sandbox-dev on dev laptops.** On the laptop,
+  `App_Database::query('db_forecast2')` resolves (via `config.dev-*.ini`) to the **sandbox-dev**
+  database, not prod — so any probe using the framework DB layer shows zero rows for
+  `Forecast.Sales` even though prod has data. Read probes must bypass the ini and connect directly
+  to the **core2 reader** (`reader1.core.database.togahub.com`, creds in `CLAUDE.md` /
+  `worker/config.worker.ini`). `reconcile_netsuite_totals.php` and `probe_sales_gap_direct.php`
+  already do this. (This is the read-side mirror of the `--prod` write override above.)
+- **`reconcile`'s Open Orders figure is a live snapshot**, not a tranDate-bounded query: it sums
+  **all currently-open SOs** regardless of date. Comparing that against the full `OpenOrderItems`
+  table shows a large apparent gap driven by records that will never sync, **not** by drift:
+  - **Future-dated SOs** (trandate 2027–2029) — NetSuite data-entry errors (wrong year). The
+    backfill window doesn't extend into the future, so they never sync. Flag to whoever owns
+    NetSuite data; not a code bug.
+  - **Pre-2024 legacy open SOs** — ordered before the sync window.
+  When a user asks about a date range (e.g. 2026 YTD), **filter the open-orders comparison to that
+  trandate window manually** — within the normal window (2024→present) the delta is rounding-only.
+- **Legacy credit-memo wrong-sign rows.** Some `Forecast.Sales` credit-memo/cash-refund rows were
+  stored with **flipped signs** by a prior sync version (positive instead of negative), inflating
+  revenue. `trueup_sales.php` repairs them: it compares against NS by trandate, detects the sign
+  mismatch, and delete+re-inserts with the correct sign. See the shim/reference docs for why a
+  uniform `-foreignamount` is correct and an extra per-type `$factor` double-negates.
 - These tools live in `test/@dave/` (developer tooling), but `trueup_open_orders` has been run
   against production. The `Defaults`/checkpoint mechanics of the scheduled sync are separate.
 
 ## Change history
 
+- 2026-06-11 — Documented the `App_Database` sandbox-dev read pitfall (bypass with direct core2
+  mysqli), `reconcile`'s open-orders live-snapshot semantics (future-dated + pre-2024 legacy SOs
+  explain apparent gaps), the legacy credit-memo wrong-sign repair, and added `trueup_opportunities`
+  + the gap-probe tools. (dfranks)
 - 2026-06-11 — `trueup_sales` rewritten to bulk SuiteQL (`fetchSalesBulk`, ~300× faster);
   `amountDue` + `createdFrom` dropped; float-dust fixed; `--prod` flag added. `reconcile`/`analyze`
   profit queries `NVL(costestimate,0)` — established the $663K gap was an audit artifact and the

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)_ — 3 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 4 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 3 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 
 ## 2.0 framework

package/knowledge/clients/compass-usa/features/mits-po-to-so-item-linking.md

@@ -71,7 +71,28 @@ USA and Canada share the parent handler unchanged.
   number onto the line). Example seen on SA132739: UPS `1Z8696XA0193326215` actually shipped
   `C40QYUC-1` (SO line 4) but was attached to SO line 1 (`1000555`).
 
+- **Over-fulfillment (fulfilled qty > ordered) is the other visible symptom of the same
+  scramble.** When a spuriously-linked PO item ships, its ASN/PO-driven ItemFulfillment walks
+  the bad bridge link and creates a **phantom `ItemFulfillmentItem` on the wrong SO line**, so
+  that line shows more fulfilled than ordered (the same shipment is also fulfilled correctly on
+  its real line). Cleanup per order:
+  - **Spurious bridge rows:** delete where the SO item's part ≠ the PO item's part, scoped to
+    the one `salesOrderId` (`soi.itemId <> vi.itemId` via `VendorItems`). Idempotent.
+  - **Phantom IFI:** the duplicate on the over-fulfilled line is the IFI with **no
+    `ItemFulfillmentItemUnits`, no `ItemFulfillmentItems_TrackingNumbers`, and nothing
+    mirroring it** (`upstreamItemFulfillmentItemId`). The legitimate line fulfillment is the
+    sibling IFI that has a real `Unit` and/or a downstream mirror (often in an auto-numbered
+    `F#####` IF rather than the SO-named IF). Delete the phantom guarded by
+    `id + salesOrderItemId + itemFulfillmentId + quantity`.
+  - These are pre-fix orders only (POs created before the 2026-06-11 guard). Cleanup is
+    one-time data, written as a dated `dbchanges2/Client_Compass/` file per order.
+  - ⚠ Not every over-fulfilled Compass line is this bug — high multipliers (5×–20×) seen on
+    other orders (e.g. SA114091 25→125) do not fit the split-PO 2× pattern and are a separate,
+    uninvestigated cause.
+
 ## Change history
+- 2026-06-11 — Documented the over-fulfillment symptom and the phantom-IFI cleanup predicate;
+  remediated SA132657 and SA132641 (one dated dbchanges2 file each). (jcardinal)
 - 2026-06-11 — Guarded `postPost` SO↔PO item linking to MR orders only; SA links come solely
   from `prePost`'s `createdFromSalesOrderItem` remap. Fixes spurious cross-part links. (jcardinal)
 

package/package.json

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