toga-ai 1.0.234 → 1.0.236

package/knowledge/1.0/standards/framework-rules.md

@@ -99,6 +99,19 @@ Before creating a new class in a 1.0 repo:
 3. Follow the naming convention exactly, including the type segment.
 4. If you are adding a class to the `library` core repo, be aware it affects all 1.0 apps — review `knowledge/1.0/apps/library/architecture.md` first.
 
+## Schema migrations — always in `dbchanges`
+
+**Application repos (`worker`, `togadesk`, `togaview`, `tools`, and any other 1.0 app)
+contain no standalone `.sql` migration or schema files.** All schema changes for any
+1.0 database — table creation, `ALTER` statements, index changes, seed data — go in the
+**`dbchanges`** repo.
+
+This rule applies regardless of which application repo the feature lives in. Even if you
+are adding a column that only `worker` reads, the `.sql` file goes in `dbchanges`.
+
+Never create a `.sql` file inside a 1.0 application repo. The SQL that belongs in those
+repos is only query strings embedded in PHP code — not standalone migration files.
+
 ## Error handling in controllers
 
 Controllers must not let exceptions bubble up to the framework unhandled. Catch specific exceptions, log them, and return an appropriate response.

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

@@ -8,7 +8,7 @@
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [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). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/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/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
+| [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). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/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/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [_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 |
 | [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 |
 | [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/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |

package/knowledge/2.0/apps/_underscore/features/forecast-sale-import.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-26
+updated: 2026-06-29
 owners: [dfranks]
 files:
   - _underscore/Component/Forecast/SaleImport/SaleImport.php
@@ -28,6 +28,7 @@ files:
   - 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/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js
   - test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js
 related:
@@ -161,11 +162,27 @@ location, memo). Handler `_Worker_Netsuite_JournalEntry`: `post`/`put` → `sync
 item-line upsert/reconcile machinery (`syncLines`/`guardedInsert`/`deleteRows`).
 
 **Mapping model (durable design):**
-- A JE line carries **no native item and no salesRep** (confirmed against the live account:
-  0 JEs carry an item on a revenue/cost line). The fields the business rule needs **do not
-  exist in NetSuite yet** — they are stubbed behind constants `JE_LINE_ITEM_FIELD` /
-  `JE_LINE_SALESREP_FIELD` (currently **null**), so until the fields are added every kept
-  line groups under `(null, null)` into **one aggregate row**.
+- **Sales rep is now LIVE on JE lines** as the custom column **`custcol_sales_rep_line`**
+  (`JE_LINE_SALESREP_FIELD = 'custcol_sales_rep_line'`, wired 2026-06-29 after live Apr–May
+  2026 probing). The value is a NetSuite **employee REFERENCE object** `{links, id, refName}`;
+  `.id` is the employee internalId (a **string** in JSON). `journalLineLookup()` resolves it
+  via `lookupId('Employees','netsuiteInternalId', .id)` → local `salesRepEmployeeId`. The
+  per-run **account-number allowlist isolates exactly the lines that carry the rep** — offset/
+  balancing lines omit class/entity/`custcol_sales_rep_line`, so they group to null and are
+  dropped. No schema/migration (`salesRepEmployeeId` already on `Forecast.Sales`).
+- **JE lines carry NO item field at all — item ingestion from NetSuite is not possible.**
+  Confirmed across multiple Apr–May 2026 JEs: the full union of line keys is
+  `{account, class, cleared, debit, credit, custcol_sales_rep_line, entity, line, memo, location}`.
+  There is **no native `item` and no custom item column**. `JE_LINE_ITEM_FIELD` stays **null
+  by design**; kept lines now group **per-salesRep with a null item**. The dimension that
+  exists *instead of* item is **`entity`** (the customer ref). Probe tool:
+  `test/@dave/probe_je_shape.php` (dumps line column shapes + custom columns).
+- **No salesRep self-heal (unlike the item path).** `journalLineLookup()` for Employees has
+  **no `syncEmployee()` fallback** (the item path self-heals via
+  `_Worker_Netsuite_Item::syncItem()`). A rep missing from `Forecast.Employees` silently
+  resolves to **null** and re-aggregates under null. It relies on the **supporting-records
+  pull** keeping `Forecast.Employees` current. (Sample coverage was complete — rep IDs
+  482, 569, 685, 30954, 34877 all present in prod `Forecast.Employees`.)
 - Lines hitting a **revenue** or **cost** GL account are grouped by **(salesRep, item)**:
   `revenue = Σ(credit − debit)` over revenue lines, `cost = Σ(debit − credit)` over cost
   lines, `profit = revenue − cost`.
@@ -411,6 +428,21 @@ record is deleted in NetSuite.)
 - The cron's sign handling is not portable here — see Sign convention.
 
 ## Change history
+- 2026-06-29 — **Wired JE sales-rep ingestion live** (TRUE-79862): set
+  `JE_LINE_SALESREP_FIELD = 'custcol_sales_rep_line'` after live Apr–May 2026 probing
+  confirmed the rep is now present on JE lines as that custom column — a NetSuite employee
+  **reference** object `{links,id,refName}` whose `.id` (string) resolves via
+  `lookupId('Employees','netsuiteInternalId',.id)`. Kept lines now group per-salesRep with a
+  null item. One-line change, no schema/migration (`salesRepEmployeeId` already exists).
+  **Confirmed JE lines carry NO item field** (native or custom) — line key union is
+  `{account,class,cleared,debit,credit,custcol_sales_rep_line,entity,line,memo,location}`; the
+  dimension *instead of* item is `entity` (customer ref), so `JE_LINE_ITEM_FIELD` stays null
+  by design (item ingestion from NetSuite is not possible). **Gotcha: JE salesRep lookup has
+  no self-heal** (the item path does via `syncItem()`) — a rep missing from
+  `Forecast.Employees` resolves to null and aggregates under null; relies on the
+  supporting-records pull. Still dormant in prod (JE webhook fires only once the AMQ enqueuer
+  deploys on the Journal Entry record type). Probe tool: `test/@dave/probe_je_shape.php`.
+  (dfranks)
 - 2026-06-26 — **Changed JE revenue/cost classification from `accttype` buckets to an EXACT
   account-NUMBER allowlist** (sales-team-defined): `JE_REVENUE_ACCOUNT_NUMBERS =
   {41100,41300,41500}`, `JE_COST_ACCOUNT_NUMBERS = {51100,51200}`; everything else ignored.

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

@@ -39,6 +39,13 @@ processes background jobs. It's a `_underscore` 2.0 app (`index.php` is just
 | S3 `agilant-worker-fallback` | Failed webhook payloads (`webhook-fallback/{uuid}.json`, 7-day lifecycle). |
 | API Gateway `WorkerWebhookIngestion` | `webhook.togahub.com` → Lambda. Lambda Function URLs are blocked by an AWS Org SCP, so API Gateway is the only public entry point. |
 
+## Critical repo rule — no SQL migration files
+
+**This repo contains PHP and Python only. Never create `.sql` schema-migration files here.**
+All table creation, `ALTER` statements, index changes, and seed data — including for
+`Core.WorkerJobs` and `Core.CronJobs` — go in the `dbchanges2` repo using its
+`YYYY-MM-DD<letter> - <Description>.sql` naming convention.
+
 ## MySQL tables
 
 **`Core.WorkerJobs`** — unified execution record. Key columns: `uuid`,

package/knowledge/2.0/standards/backend-php.md

@@ -22,6 +22,14 @@ related:
 
 ## Database/SQL
 
+### Migration files belong in `dbchanges2`
+
+SQL query strings embedded in PHP code (SELECTs, INSERTs, UPDATEs) live in this repo as
+part of normal PHP files. **Standalone `.sql` migration files do not.** Any schema change
+— CREATE TABLE, ALTER TABLE, new index, seed rows — must be placed in the `dbchanges2`
+repo, not here. See `2.0/standards/framework-rules.md` § Schema migrations for naming
+conventions.
+
 ### Table Design
 
 #### **Order of Fields**

package/knowledge/2.0/standards/framework-rules.md

@@ -86,6 +86,22 @@ return [
 ];
 ```
 
+## Schema migrations — always in `dbchanges2`
+
+**Application repos (`worker2`, `api2`, `_underscore`) contain no standalone `.sql`
+migration or schema files.** All schema changes for any 2.0 database — table creation,
+`ALTER` statements, index changes, seed data — go in the **`dbchanges2`** repo.
+
+File naming in `dbchanges2`: `YYYY-MM-DD<letter> - <Description>.sql`
+(e.g. `2026-06-30a - Add WorkerJobs failureCode column.sql`).
+
+This rule applies regardless of which application repo the feature lives in. Even if you
+are adding a column that only `worker2` reads, the `.sql` file goes in `dbchanges2`.
+
+Never create a `.sql` file inside `worker2`, `api2`, `_underscore`, or any other 2.0
+application repo. The SQL that belongs in those repos is only query strings embedded in
+PHP code — not standalone migration files.
+
 ## Checking dependencies before touching shared code
 
 `dependsOn` in `knowledge/registry.json` means a repo extends or depends on another repo's classes. Before modifying a class in a dependency repo (e.g. `_underscore` core):

package/knowledge/INDEX.md

@@ -16,7 +16,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 18 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 19 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 22 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 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)

package/package.json

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