toga-ai 1.0.206 → 1.0.208

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

@@ -7,7 +7,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 |
-| [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 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 |
 | [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 |
 | [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 |

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

@@ -103,3 +103,13 @@ packages: `phpoffice/phpspreadsheet ^1.6`, `smalot/pdfparser ^0.14.0`.
 - **Timezone** is always `America/Chicago` (set in `_.php`).
 - **`__APPROOT__`** is resolved by locating an ancestor folder named `_`; each app must
   have that `_` folder at its root.
+
+## App_String cross-framework crypto (`encryptWithKey` / `decryptWithKey`)
+
+`App_String::encryptWithKey($data, $key)` and `decryptWithKey($data, $key)` (public static) do
+**AES-256-CBC**: random IV via `random_bytes`, returning `base64(iv . ciphertext)` with openssl
+flag `0`. They are **deliberately byte-for-byte interoperable** with the 2.0
+`_String::encryptWithKey` / `decryptWithKey`, so a SAML handoff token encrypted by the 2.0
+gateway decrypts in any 1.0 app (round-trip verified). Net-new methods — no existing method
+changed, no behavior change for existing apps. First consumer: the Tools app's `App_Auth`
+(`1.0/apps/tools/features/saml-sso-auth.md`).

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

@@ -6,11 +6,12 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-06-11
+updated: 2026-06-25
 owners: ["dfranks"]
 files:
   - library/app/api/netsuite/rest.php
   - library/ssl/netsuite_ec_key.pem
+  - test/@dave/Junk Drawer/nsq.php
 related:
   - netsuite-suiteql-rest-shim.md
   - ../architecture.md
@@ -183,6 +184,30 @@ and custom fields (`CUSTBODY_END_CUSTOMER`, `CUSTBODY_STOCKING_ORDER`, …).
 - **Open-order (in-flight) product revenue:** `((-tl.quantity) - NVL(tl.quantitybilled,0)) * tl.rate`;
   shipping term `SUM(-tl.foreignamount)` over `tl.itemtype = 'ShipItem'`.
 
+### Journal Entry lines — the `mainline` rule INVERTS
+
+Journal Entries break the `mainline='F' = detail / mainline='T' = header` rule above — **all JE
+`transactionline` rows have `mainline='T'`** (there is no header/`mainline='F'` split). A revenue
+query that filters `mainline='F'` over a JE returns **empty**. When querying JE lines, do **not**
+filter `mainline='F'`. Confirmed by probing accrual JE #6962 (internalId 7128398), reclass JE #6967
+(7128548), and 15 recent revenue JEs.
+
+Other JE line facts (same probes):
+- **`tl.salesrep` does NOT exist** on `transactionline` — selecting it is an HTTP 500. (There is no
+  line-level sales-rep dimension on a JE.)
+- **`tl.item` is NEVER populated on JE revenue/cost lines** (`COUNT(item) = 0` across every sampled
+  JE) — JEs post to accounts, not items.
+- The only line-level dimensions present on a JE are **`class`** and **`entity`** (customer), and
+  only when the preparer fills them in.
+- Revenue line = `accttype IN ('Income','OthIncome')`; cost line = `accttype = 'COGS'`.
+- An auto-created **reversing JE** (`isreversal='T'`) fires **NO webhook** — if a sync consumes JEs it
+  must synthesize the reversal locally.
+
+> **Deferral decision (2026-06-25):** adding Journal Entries as a 5th `Forecast.Sales` transaction
+> type is **DEFERRED**. The intended `(salesRep, item)` grouping is **impossible** on JE lines until a
+> NetSuite custom field supplying those dimensions is created and populated (no `salesrep` column, no
+> `item`). Re-evaluate only once that custom field exists — don't re-probe this from scratch.
+
 ## `previousTransactionLineLink` table
 
 The bridge between a child line (e.g. invoice) and its originating parent line (e.g. SO).
@@ -308,6 +333,15 @@ numbers. Budget hours for multi-year runs and launch them under `nohup`/`tmux`.
 
 ## Change history
 
+- 2026-06-25 — **Documented Journal Entry line structure + the JE→Forecast.Sales deferral.** JEs
+  invert the `mainline` rule — **all** JE `transactionline` rows are `mainline='T'` (no `'F'` detail
+  split), so a `mainline='F'` revenue query over a JE returns empty. Also: `tl.salesrep` does not
+  exist (HTTP 500), `tl.item` is never populated on JE lines (post to accounts, not items), the only
+  line dims are `class`/`entity` (when filled), revenue = `accttype IN ('Income','OthIncome')` / cost
+  = `'COGS'`, and an auto-reversing JE (`isreversal='T'`) fires no webhook. Recorded the decision to
+  **defer** adding JEs as a 5th `Forecast.Sales` type — the intended `(salesRep, item)` grouping is
+  impossible until a NetSuite custom field supplies those dims. Probed via `test/@dave/Junk
+  Drawer/nsq.php` against accrual JE #6962, reclass #6967, and 15 recent revenue JEs. (dfranks)
 - 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

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

@@ -0,0 +1,8 @@
+# tools (Tools) — 1.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md |
+| [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | The first two tools shipped in the Tools app, both under the **Developers** folder and gated to personas **Development Team** / **TOGa Technology**. | tools/mvc/developers/uuid/get.php, tools/mvc/developers/password/get.php |
+| [Tools Persona-Gated Navigation (App_Nav)](features/persona-gated-navigation.md) | `App_Nav` is the Tools app's two-level, **persona-gated** navigation. | tools/_/app/nav.php |
+| [Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)](features/saml-sso-auth.md) | `App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=` handoff (see the 2.0 SAML downstream integration contract), establishe | tools/_/app/auth.php, tools/mvc/sso/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/get.php |

package/knowledge/1.0/apps/tools/architecture.md

@@ -0,0 +1,81 @@
+---
+title: Tools (1.0 Internal-Tools App) Architecture
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: architecture
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - tools/index.php
+  - tools/_/app/framework.php
+  - tools/_/app/frameworkindex.php
+  - tools/_/app/auth.php
+  - tools/_/app/nav.php
+  - tools/common/header.php
+  - tools/common/footer.php
+  - tools/mvc/get.php
+  - tools/mvc/_TEMPLATE/get.php
+  - tools/docs/ADDING_A_TOOL.md
+related:
+  - ./features/saml-sso-auth.md
+  - ./features/persona-gated-navigation.md
+  - ./features/developer-tools.md
+  - ../library/architecture.md
+  - ../library/features/mvc-page-pattern-and-app-skeleton.md
+---
+
+## Summary
+
+**Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind
+simple interfaces, gated by Client_True staff persona. It is modeled on `togaview` and depends on
+the `library` core. Auth comes via the SAML gateway `?saml=` handoff; the app owns its own
+session and reads `Client_True` **read-only**. Adding a tool = create `mvc/<route>/get.php`
+(copy `mvc/_TEMPLATE`) + add one `App_Nav::definition()` entry + `App_Auth::requireAuth([...])`.
+
+**Critical rules:** Do NOT use bare `<header>` elements in this app — they inherit the legacy
+dashboard stylesheet's `header{position:fixed;width:100vw}` rule and cause horizontal scroll
+(the top header bar was removed for exactly this reason). A nav action's `route` maps **1:1** to
+`mvc/<route>/get.php`. Auth fails **closed** and never auto-creates users; the dev bypass is
+double-gated (`[internal] dev_mode` AND `App_Registry::inDevMode()`). `config.*.ini`
+(incl. `config.prod.ini`) is committed with plaintext production secrets — a known, team-accepted
+risk (see Known issues); never add more secrets and treat these as compromised if leaked.
+
+## Boot & structure
+
+Standard 3-line `index.php`: `require '_.php'; App_Framework_Tools::initialize();
+App_Framework_Tools::renderIndex();`. App-specific framework subclasses
+`App_Framework_Tools` / `App_FrameworkIndex_Tools` live in `_/app/`. The 1.0 folder-based MVC
+page pattern is unchanged from the library skeleton (see the library feature doc).
+
+`App_Framework_Tools::initialize()` sets the session cookie HttpOnly + SameSite=Lax before
+calling the parent initialize.
+
+## Layout (single-style app)
+
+No per-host `stylePath` subfolder — one `assets/css/style.css`. Uses TOGA Technology logos in
+`assets/img` (`toga-brandmark-white.png` in the dark sidebar; `toga-horizontal-colored.png` on
+login/welcome). A fixed left two-column shell: dark left sidebar (`.app-nav`) with brand at top,
+persona-filtered nav in the middle, pinned footer with the user's name + a ghost "Log out"
+button; content area on the right. **No top header bar** (see Critical rules).
+
+## Home route
+
+`/` (`mvc/get.php`) renders a persona-filtered dashboard of available tools (tiles grouped by
+folder) when logged in, via `App_Nav::visibleGroups()`, or a welcome/sign-in card when not.
+
+## Adding a tool
+
+Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one entry to
+`App_Nav::definition()`, and put `App_Auth::requireAuth([...personas])` at the top. Documented in
+`docs/ADDING_A_TOOL.md`. See the App_Nav and App_Auth feature docs.
+
+## Known issues / security
+
+- **Plaintext secrets committed to git.** `config.*.ini` (incl. `config.prod.ini`) contains
+  plaintext production secrets (RDS master password, SMTP, Payeezy, NetSuite). The team has
+  **accepted this for now** (developer decision, 2026-06-25). Future remediation: git-ignore the
+  config files and rotate all exposed credentials. (Location only — no values recorded here.)
+- **SSO initiation + replay defense are open items** — see `features/saml-sso-auth.md`.

package/knowledge/1.0/apps/tools/features/developer-tools.md

@@ -0,0 +1,37 @@
+---
+title: Tools — Developers Folder (UUID & Password Generators)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - tools/mvc/developers/uuid/get.php
+  - tools/mvc/developers/password/get.php
+related:
+  - ../architecture.md
+  - ./persona-gated-navigation.md
+---
+
+## Summary
+
+The first two tools shipped in the Tools app, both under the **Developers** folder and gated to
+personas **Development Team** / **TOGa Technology**. They are the reference example of the
+"one small tool = one `mvc/<route>/get.php`" pattern.
+
+## How it works
+
+### Generate UUID (`mvc/developers/uuid/get.php`)
+- Server generates an RFC 4122 **v4** UUID via `random_bytes(16)` with version/variant bits set.
+- UI is click-to-copy, then instant **client-side** regenerate using `crypto.getRandomValues`.
+
+### Generate Password (`mvc/developers/password/get.php`)
+- Reproduces the standalone `test/team/generate_password.php` script.
+- `App_String::generateSupportCode(8)` produces the password; `App_String::passwordHash()`
+  produces the bcrypt hash. The page shows **both** the password and the hash, each copyable.
+
+## Change history
+- 2026-06-25 — Built the first two Developers tools: RFC 4122 v4 UUID generator and a password+bcrypt-hash generator (ported from test/team/generate_password.php), both gated to Development Team / TOGa Technology personas (jcardinal)

package/knowledge/1.0/apps/tools/features/persona-gated-navigation.md

@@ -0,0 +1,44 @@
+---
+title: Tools Persona-Gated Navigation (App_Nav)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - tools/_/app/nav.php
+related:
+  - ../architecture.md
+  - ./saml-sso-auth.md
+---
+
+## Summary
+
+`App_Nav` is the Tools app's two-level, **persona-gated** navigation. The structure is a single
+**hard-coded `definition()` array** (NOT in the DB), so developers/Claude edit it directly. It
+drives both the left-rail nav and the home dashboard, and is the single source of truth for which
+personas may reach a given route.
+
+## How it works
+
+### Structure
+- Two levels: **folders** (grouping) → **actions** (each loads a page).
+- Each folder and each action carries a `personas` list. An item is visible iff
+  `App_Auth::hasAnyPersona()` matches — folder gate plus an optional per-action gate.
+
+### Render surfaces
+- `render()` — emits the filtered left-rail nav with active-route highlighting.
+- `visibleGroups()` — returns the filtered structure as data for the home dashboard tiles.
+- `personasForRoute()` — returns the union of folder+action personas so a page can self-guard
+  with `App_Auth::requireAuth(...)` using the same data the nav used.
+
+### Route convention
+An action's `route` (e.g. `/developers/uuid`) maps **1:1** to `mvc/<route>/get.php`. Adding a
+tool means creating that file and adding one entry to `definition()` — see
+`docs/ADDING_A_TOOL.md` and the architecture doc.
+
+## Change history
+- 2026-06-25 — Built App_Nav: hard-coded two-level persona-gated navigation; render() for the left rail, visibleGroups() for the dashboard, personasForRoute() for page self-guarding; route maps 1:1 to mvc/<route>/get.php (jcardinal)

package/knowledge/1.0/apps/tools/features/saml-sso-auth.md

@@ -0,0 +1,76 @@
+---
+title: Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [jcardinal]
+files:
+  - tools/_/app/auth.php
+  - tools/mvc/sso/get.php
+  - tools/mvc/login/get.php
+  - tools/mvc/login/post.php
+  - tools/mvc/logout/get.php
+related:
+  - ../architecture.md
+  - ../../../2.0/apps/saml/features/downstream-integration-contract.md
+  - ../../../clients/true/features/users-personas-data-model.md
+---
+
+## Summary
+
+`App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=`
+handoff (see the 2.0 SAML downstream integration contract), establishes its own session, and
+gates every page by **Client_True persona**. The gateway holds no session — session ownership
+is entirely this app's. Auth fails **closed** to a self-contained 401 page; users are **never**
+auto-created.
+
+## How it works
+
+### Consuming the `?saml=` handoff (`mvc/sso/get.php` → `App_Auth`)
+1. Length-guard `$_GET['saml']`, then base64-decode → `json_decode` → read `payload.client`
+   and `payload.user`.
+2. Decrypt each with `App_String::decryptWithKey()` using config `[saml] api_secret_access_token`,
+   with a **dual-key retry** against `api_secret_access_token_previous` (supports gateway key
+   rotation). This interoperates byte-for-byte with the 2.0 `_String::encryptWithKey()` that
+   produced the token (see the library `App_String` crypto methods).
+3. Validate the decrypted **client uuid == configured `true_client_uuid`** via `hash_equals`,
+   and that both decrypted values match a UUID regex.
+4. Load the active Client_True user: `WHERE uuid = ? AND isActive = 1`. No match → fail closed.
+
+### Session establishment (`establishSession()`)
+- Calls `session_regenerate_id(true)`, then caches the user and **persona names** in `$_SESSION`.
+- Persona lookup (read-only `db_true`):
+  `SELECT p.name FROM Users u JOIN Users_Personas up ON up.userId=u.id JOIN Personas p ON p.id=up.personaId WHERE u.uuid = <escaped>`.
+- The session cookie is set **HttpOnly + SameSite=Lax** in `App_Framework_Tools::initialize()`
+  before the parent initialize runs.
+
+### Page guarding
+- `requireAuth([personas])` at the top of each page; `hasAnyPersona()` is `array_intersect`
+  against the cached session personas. App_Nav uses the same cached data to filter the nav.
+
+### Dev bypass (double-gated, fails closed in prod)
+`mvc/login/post.php` permits **email-only** login **only** when config `[internal] dev_mode`
+is truthy **and** `App_Registry::inDevMode()` — both must hold. When used it writes a `SECURITY`
+line to `error_log`.
+
+## Gotchas / known issues
+
+- **SSO initiation is not implemented in this 1.0 app.** Building the signed AuthnRequest lives
+  in 2.0 `_underscore` (`singleSignOnServiceUrl()`); login here points at a configurable
+  `[saml] initiation_url` **placeholder**. Open item: needs a gateway initiation entry point or
+  a ported builder.
+- **No app-side replay defense.** The handoff token carries no nonce/timestamp the app verifies.
+  Recommend the gateway embed `iat` + `jti`.
+
+## Config keys
+
+`[database_true]` (read-only Client_True); `[saml]` `api_secret_access_token` /
+`api_secret_access_token_previous`, `initiation_url`, `client_authentication_uuid`,
+`domain_uuid`, `true_client_uuid`; `[internal]` `dev_mode`.
+
+## Change history
+- 2026-06-25 — Built App_Auth: SAML `?saml=` handoff consumer with dual-key decrypt, hash_equals client-uuid check, fail-closed 401, persona-cached session (HttpOnly+SameSite=Lax), and a double-gated dev bypass. Initiation + replay defense left as open items (jcardinal)

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

@@ -5,7 +5,7 @@
 | [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 |
 | [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%` sales orders whose corresponding Office Depot (ODP) sales order has | worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php |
 | [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.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/loop_trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_profit_invoices.php, test/@dave/probe_profit_gap.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/schedules/cron.worker.infrastructure.json |
+| [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/fixer.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, test/@dave/loop_trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_profit_invoices.php, test/@dave/probe_profit_gap.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/schedules/cron.worker.infrastructure.json |
 | [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |
 | [Prudential: Send Shipments for the Day report (daily cron)](features/send-shipments-for-the-day.md) | Daily cron (9:00 PM) that emails Prudential and Dell stakeholders an Excel report of all devices shipped that day, including tracking number, serial number, emp | worker/crons/notifications/reports/send_shipments_for_the_day.php |
 | [Onboarding a Client to the NetSuite TOGa Supply Sync](workflows/onboarding-client-to-netsuite-togasupply-sync.md) | How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer (`worker/crons/toga2/netsuite/`). | worker/crons/toga2/netsuite/sync_togasupply.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |

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

@@ -10,6 +10,7 @@ updated: 2026-06-25
 owners: [dfranks]
 files:
   - test/@dave/reconcile_netsuite_totals.php
+  - test/@dave/fixer.php
   - test/@dave/analyze_netsuite_forecast_diff.php
   - test/@dave/trueup_sales.php
   - test/@dave/trueup_open_orders.php
@@ -49,6 +50,15 @@ by reconciling a chosen tranDate range directly against NetSuite.
   bucket. The diffs are **gated** because they materialize every transaction/order in the window
   into PHP arrays and OOM on multi-year windows — default is summary-only; positional `[from] [to]`
   work alongside the flag.
+- `fixer.php [--commit --prod]` — **self-contained** all-in-one delta finder + corrector across
+  **Sales + OpenOrderItems + Opportunities** in one tool (bootstraps the 1.0 framework; no shelling
+  out to the per-table trueups). **FIND** phase aggregates per-id diffs of all three categories,
+  NetSuite (SuiteQL) vs the prod `Forecast` reader, over a **fixed window** (current date back
+  through 2025-01-01); paginated `GROUP BY` made stable with `ORDER BY t.id`. **FIX** phase
+  (`fixSales`/`fixOpenOrders`/`fixOpportunities`) emulates the existing trueup logic **scoped to
+  only the discrepant ids**. **Default dry-run**; `--commit` requires `--prod` (both must be passed
+  to write). See the two baked-in gotchas (lazy self-reconnecting `fcReader()`; `buildDoubleFieldArray`
+  by-ref) and the **NS-deleted-invoice stale Sales row** failure mode below.
 - `analyze_netsuite_forecast_diff.php [from] [to]` — decomposes the delta **per transaction** into
   NS_ONLY (missing from FC), FC_ONLY (stale/extra), DRIFT (value differs). Read-only.
 - `trueup_sales.php --from --to [--chunk-days N] [--prod] [--dry-run]` — makes `Forecast.Sales`
@@ -143,6 +153,22 @@ None — Forecast2 is a single shared dataset.
 
 ## Gotchas / known issues
 
+- **An NS-DELETED invoice leaves STALE cost-only `Forecast.Sales` rows the add/update-only import can
+  never remove.** The 5-min `import_sales.php` cron is **add/update-only — it has no delete path** (only
+  the nightly discrepancy-fix deletes). So when an invoice is **deleted in NetSuite**, its already-imported
+  `Forecast.Sales` lines survive as orphans — and they survive in a telltale shape: **`revenue = 0`,
+  `profit = -cost`** (the revenue side is gone but the cost line lingers), inflating a **profit-only**
+  delta with no matching revenue delta. `fixer.php` detects and **deletes** them. Real example: closed a
+  **$12,838.84 profit delta** on 2026-06-18 — 5 NS-deleted invoices, 33 stale lines. When a profit-only
+  gap localizes to invoices that **no longer exist in NetSuite**, this is the cause; deletion (not trueup
+  re-insert) is the fix.
+- **`fixer.php` baked-in gotchas (apply to any long NS-bulk + Forecast-read tool):**
+  - **The Forecast reader connection idles out mid-run (Aurora idle-drop) during long NetSuite bulk
+    fetches.** Don't hold one long-lived handle across the NS calls — use a **lazy self-reconnecting
+    `fcReader()`** (ping-or-reconnect) called **immediately before each FC query**, not once up front.
+  - **`App_Database::buildDoubleFieldArray(App_Database::query(...))` throws "Only variables should be
+    passed by reference."** `buildDoubleFieldArray` takes its argument by reference, so a function-call
+    result can't be passed inline — **assign `query(...)` to a temp variable first**, then pass the temp.
 - **An audit must apply the sync's own inclusion rules or it manufactures phantom deltas.**
   `reconcile`'s NetSuite Sales SUM/diff originally had **no transaction-status filter**, but the
   sync (`trueup_sales` / `common_import_sales_from_netsuite.php`) deliberately **excludes** Invoice

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-24
+updated: 2026-06-25
 owners: ["dfranks"]
 files:
   - _underscore/Component/Api/Netsuite/Netsuite.php
@@ -48,10 +48,20 @@ through `_ApiRequest` directly (mirroring `send()`'s auth/endpoint/header setup)
 - `_ApiRequest` exposes **`responseCode` + `responseHeaders`** (a raw header string — there is **no
   `getHeader()`** accessor). `_Component_Api_Netsuite::send()` does **not** surface either.
 - Robust parse: `preg_match_all('/^Location:\s*(\S+)/im', $responseHeaders, ...)` and take the
-  **LAST** match (skips any 100-Continue / redirect block), then `#/(\d+)(?:[?#]|$)#` to pull the
-  trailing numeric id tolerating a query string or fragment.
+  **LAST** match (skips any 100-Continue / redirect block), then a trailing-id regex to pull the
+  numeric id tolerating a query string or fragment.
 - Throws on non-2xx, on no `Location` header, and on no id parsed.
 
+> **⚠ BUG (live, not yet fixed):** the trailing-id regex was written as `'#/(\d+)(?:[?#]|$)#'`,
+> which uses `#` as the PCRE **delimiter** *and* puts `#` inside the `[?#]` character class — so PHP
+> reads the class-`#` as a premature closing delimiter and the whole pattern **always throws
+> `preg_match(): Unknown modifier ']'`**. This fires *after* the record is already created, so the
+> create succeeds in NetSuite but `createRecord()` raises and the caller never gets the new id —
+> it breaks the entire outbound create/push path. **Fix direction:** change the delimiter so `#`
+> isn't both delimiter and class member, e.g. `~/(\d+)(?:[?#]|$)~`. Interim workaround used in
+> probes: recover the new id by regex-parsing the thrown exception message (the `Location` value
+> is in it). Confirmed live 2026-06-25.
+
 ### Update — reuse `send('PATCH', $route, $body)`
 
 Updates do **not** need a new helper. A NetSuite record PATCH returns 204 with no body, and
@@ -85,9 +95,17 @@ doc.)
 - **204-with-empty-body is success, not failure.** Both create (204 + `Location`) and update (204,
   no body) return no payload; treat a 2xx with empty body as success and key off the status, not the
   body.
+- **`createRecord()`'s trailing-id regex is a live `#`-delimiter bug** (`'#/(\d+)(?:[?#]|$)#'` →
+  always `Unknown modifier ']'`), thrown *after* the record is created — see the ⚠ note under
+  *Create* for the cause and the `~…~`-delimiter fix.
 
 ## Change history
 
+- 2026-06-25 — **Recorded a live bug in `createRecord()`'s trailing-id regex.** The pattern
+  `'#/(\d+)(?:[?#]|$)#'` uses `#` as both the PCRE delimiter and a class member, so it always throws
+  `Unknown modifier ']'` — *after* the record is created, breaking the outbound create/push path.
+  Fix direction: re-delimit (e.g. `~/(\d+)(?:[?#]|$)~`); interim workaround is to parse the new id
+  out of the thrown exception message. (dfranks)
 - 2026-06-24 — **Added `createRecord()` — the first REST write method in the framework.** Posts
   through `_ApiRequest` directly (since `send()` hides headers) and parses the new internalId from
   the 204 `Location` header (last match, trailing-id regex). Update path documented as reuse of

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

@@ -9,7 +9,7 @@
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Notification/Email.php, dbchanges2/Core/2026-05-21 - Monitors.sql |
-| [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
+| [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, test/@dave/test_model_load_behavior.php, dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |

package/knowledge/2.0/apps/worker2/features/netsuite-opportunity-sync.md

@@ -21,6 +21,8 @@ files:
   - test/@dave/clickup/backfill_opportunity_numbers.php
   - test/@dave/clickup/probe_opportunity_fields.php
   - test/@dave/probe_clickup_desc_match.php
+  - test/@dave/test_model_load_behavior.php
+  - "dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql"
   - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
 related:
   - ./netsuite-salesorder-open-orders-sync.md
@@ -163,7 +165,15 @@ Shared helpers: `buildCustomFields()` (the field array, used by both create and
 
 Writes `Forecast.Opportunities` (header) + `Forecast.OpportunityItems` (children), faithful to
 the legacy cron's OPPORTUNITIES section:
-- Upsert header by `netsuiteOpportunityInternalId`; items insert/update/delete by `line`; no
+- Upsert header by `netsuiteOpportunityInternalId` via a **business-key resolve**, NOT
+  `_Model::load()` — `SELECT id FROM Opportunities WHERE netsuiteOpportunityInternalId=? ORDER BY
+  id`, take the first row (or new), save, then **delete any extra duplicate rows** (and their
+  `OpportunityItems` children) inline so the handler is **self-healing** against pre-existing
+  duplicates (see the `load()` gotcha below for why `load()` cannot be used here).
+- A **UNIQUE index on `Opportunities.netsuiteOpportunityInternalId`** (migration
+  `dbchanges2/Forecast/2026-06-25a …`) is the only race-proof guard against concurrent/redelivered
+  webhooks creating a duplicate. The table was confirmed duplicate-free before the index was added.
+- items insert/update/delete by `line`; no
   header delete; children deleted before the header on DELETE.
 - Lookups: `customerId`/`salesRepEmployeeId` → null on miss; `forecastCategoryId`/`salesStageId`/
   `percentToCloseStatusId` → **create-on-miss** (+name update); unknown line item → **throws**
@@ -182,6 +192,19 @@ None — platform-wide Forecast sync.
 
 ## Gotchas / known issues
 
+- **`_Model::load()` returns TRUE only on an EXACTLY-ONE match — a duplicate-row self-amplifier in
+  any load-then-upsert handler.** `_Model::load()` (`_underscore/Model.php:788–808`) returns FALSE
+  for **both** 0 rows **and** 2+ rows — it succeeds only when the lookup matches exactly one row.
+  The old inbound opportunity handler used `load()` to find the existing header before its upsert, so
+  the instant an `netsuiteOpportunityInternalId` had **two** rows (from any earlier race/redelivery),
+  `load()` could never re-find it and **every subsequent webhook INSERTed yet another row** — a
+  self-amplifying duplicate (opp 7192265 reached **4 rows**, a $1,275 reconcile delta). This is a
+  **platform-wide footgun**: any `load()`-by-business-key-then-upsert pattern silently flips to
+  insert-only once a duplicate exists. **Fix:** resolve the id with a plain
+  `SELECT id … ORDER BY id` (take the first) instead of `load()`, and have the handler delete the
+  extra rows so it self-heals; back it with a UNIQUE index so duplicates can't form. The exactly-1
+  semantics is proven empirically by `test/@dave/test_model_load_behavior.php` (seeds 2 sentinel
+  rows, asserts `load()` → FALSE; self-cleaning local fixture).
 - **A User Event can't trigger another User Event → the immediate trigger lives in the enqueuer.**
   The enqueuer (a UE) creating the queue row does NOT fire any UE on the queue record (only the
   *scheduled* drainer's `submitFields` does). So a drain-UE on the queue record never runs for
@@ -364,6 +387,16 @@ same **skip-if-unchanged** compare on the extracted values, and **actor-identity
 trigger a CU→NS write. The NS→CU change-detection above is the complementary backstop, not a substitute.
 
 ## Change history
+- 2026-06-25 — **Fixed the Opportunity duplicate-row amplification + added a unique-index guard.**
+  Root cause: `_Model::load()` returns TRUE only on an **exactly-one** match (FALSE for 0 *and* 2+),
+  so once an nsId had 2 rows the `load()`-then-upsert handler could never re-find it and every
+  webhook INSERTed another row (opp 7192265 hit 4 rows / $1,275 delta). Replaced `load()` with a
+  business-key `SELECT id … ORDER BY id` resolve + inline delete of extra duplicate rows and their
+  `OpportunityItems` children (self-healing), and added a **UNIQUE index on
+  `Opportunities.netsuiteOpportunityInternalId`** (`dbchanges2/Forecast/2026-06-25a …`; table
+  confirmed duplicate-free first) as the race-proof guard. Recorded the `load()` exactly-1 semantics
+  as a platform-wide footgun for any load-then-upsert handler; proven by
+  `test/@dave/test_model_load_behavior.php`. (dfranks)
 - 2026-06-25 — **Characterized the AMQ enqueuer scope + a live drainer TypeError.** The enqueuer is
   generic over all record types via `RECORD_TYPE_MAP` (no context filter, prod `DEV_OVERRIDE.enabled=false`)
   but probe-confirmed `Released` on **only Opportunity (`customdeploy1`) + Sales Order (`customdeploy2`)** —

package/knowledge/INDEX.md

@@ -12,6 +12,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 11 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
+- **tools** (Tools) — 4 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 
@@ -27,7 +28,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) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 6 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 6 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 7 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)
 
 ## standalone framework

package/knowledge/clients/true/profile.md

@@ -3,6 +3,7 @@ title: "TOGA Technology"
 framework: "2.0"
 apps:
   - _underscore
+  - tools
 project: _Underscore
 client: true
 type: profile
@@ -24,3 +25,6 @@ by staff role (e.g. the planned Toolbox app) reads its `Users` / `Personas` mode
 - **Client DB:** `Client_True`
 - **Client identifier:** `True`
 - **SSO mapper:** `_Model_True_ClientAuthentication` (base; matches by email from NameID)
+
+The new **Tools** app (1.0; repo `tools`) reads the `Client_True` DB **read-only** to gate its
+internal tooling by staff persona (see `1.0/apps/tools/`).

package/knowledge/registry.json

@@ -182,5 +182,14 @@
     "framework": "2.0",
     "role": "app",
     "dependsOn": []
+  },
+  {
+    "repo": "tools",
+    "project": "Tools",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": [
+      "library"
+    ]
   }
 ]

package/package.json

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