toga-ai 1.0.329 → 1.0.331

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/checker.php, _underscore/Component/Forecast/SaleImport/SaleImport.php, test/@dave/looper.php, 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 |
+| [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/checker.php, worker2/Component/Forecast/SaleImport/SaleImport.php, test/@dave/looper.php, 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, library/app/api/netsuite/rest.php, library/app/systemmonitor/netsuiteintegration.php |
 | [OneUptime external uptime monitoring for 1.0 workers](features/oneuptime-worker-uptime-monitoring.md) | Every 1.0 worker box self-reports its liveness to an external OneUptime monitor once per minute by curl-POSTing to a per-worker "Incoming Request" heartbeat URL | library/app/worker.php, worker/crons/worker/worker_heartbeat.php |
 | [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 |

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

@@ -6,11 +6,11 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
+updated: 2026-07-14
 owners: [dfranks]
 files:
   - test/@dave/checker.php
-  - _underscore/Component/Forecast/SaleImport/SaleImport.php
+  - worker2/Component/Forecast/SaleImport/SaleImport.php
   - test/@dave/looper.php
   - test/@dave/reconcile_netsuite_totals.php
   - test/@dave/fixer.php
@@ -223,8 +223,8 @@ by reconciling a chosen tranDate range directly against NetSuite.
   `41100/41300/41500`, cost `51100/51200` (exact-number, never prefix — see the sale-import doc for the
   sub-account traps). `revenue = Σ(−foreignamount)` over revenue-acct lines; `profit = Σ(−foreignamount)`
   over **all** allowlisted lines (cost lines net profit down via debit-positive `foreignamount`). Group by
-  **(local salesRep, item)** → one Sales row per group; synthetic `lineNumber` from
-  `ksort(json_encode([salesRepId,itemId]))` then `1..N` — **fixer MUST key identically** or its upsert
+  **(local salesRep, item, customer)** → one Sales row per group; synthetic `lineNumber` from
+  `ksort(json_encode([salesRepId,itemId,customerId]))` then `1..N` — **fixer MUST key identically** or its upsert
   dupes against the webhook importer's rows. JE `foreignamount`s are **cent-precision**, so a per-JE
   sum-then-round equals the importer's per-salesRep round-then-sum **exactly** — this is what keeps
   checker's "in sync" == fixer's "nothing to fix" for JEs (the compute-identically invariant applied to JEs).
@@ -249,6 +249,35 @@ by reconciling a chosen tranDate range directly against NetSuite.
   correctly re-derives "no raw rep" from NetSuite. One-time cleanup =
   `fixer.php --commit --prod --category sales` over the JE window, then `checker.php` to confirm
   (in current prod this was a no-op — 0 no-rep JE rows — so the importer filter is preventative).
+- **`fixer.php` now resolves `customerId` on JE lines, mirroring the importer (TRUE-80129,
+  dfranks 2026-07-14).** Both `fixJournalEntries()` (the hand-maintained MIRROR of
+  `buildJournalEntryRows` — same account allowlist, same group key, same `ksort` ordering,
+  which must stay in lockstep or its upsert dupes against the webhook importer's rows) used to
+  hard-code `customerId = NULL` in its UPDATE and INSERT. The fix:
+  - Added a `Customers` lookup (reusing the exact pattern `fixOpportunities()` already uses in
+    the same file).
+  - Added **`tl.entity AS customer`** to the bulk-line SuiteQL SELECT. `tl.entity` is a
+    **NATIVE** column, so it needs **no** `> 0` / `IS NOT NULL` perf-trap workaround (unlike the
+    `custcol_*` salesRep/item columns — see the custom-column planner gotcha below); the comment
+    in-file notes native columns carry no such predicate risk.
+  - Extended the group key to `(salesRep, item, customer)` (`json_encode([$salesRepId, $itemId,
+    $customerId])`) to key **identically** to the importer.
+  - Added `customerId` to the **read-back SELECT + change-detection compare** (a deliberate guard
+    against the known "new column dropped from change-detection" footgun class), plus the UPDATE
+    and INSERT.
+  - New constant `JE_CUSTOMER_LINE_FIELD = 'entity'`. Non-Customer entities (vendor/employee
+    refs) resolve to null naturally — NetSuite internal ids are one global sequence across entity
+    subtypes, so a non-customer id simply misses `Customers`.
+- **Backfilling `customerId` onto existing JE rows is a MANUAL, all-time developer step — not
+  part of the code PR (TRUE-80129 decision).** Because the checker (`journalEntryNsTotals()`)
+  only detects **revenue/profit** drift per JE, a JE row with a correct total but a missing
+  `customerId` is **not** flagged discrepant, so a normal checker/fixer pass will never
+  repopulate it — shipping the code fix alone does **not** backfill history. The chosen backfill
+  (run once, manually, by the developer after deploy): **DELETE all**
+  `netsuiteTransactionType='journalEntry'` rows from `Sales` (**no date-window restriction**),
+  then run **`fixer.php --commit --prod --category sales`** over full JE history so
+  `fixJournalEntries()` takes the INSERT branch for every group and repopulates every JE row
+  including `customerId`. Explicitly **out of scope for the code PR**.
 - **JE item dimension is NULL today; here is how to enable it later.** `itemId` is null on JE Sales rows
   because the JE import path reads item **only** via the configurable `JE_LINE_ITEM_FIELD` (currently null)
   — it does **not** read native `transactionline.item`, so even a populated native `tl.item` would NOT flow
@@ -256,7 +285,8 @@ by reconciling a chosen tranDate range directly against NetSuite.
   `custcol_*` if a custom column is added) — `journalLineLookup` then resolves it via
   `lookupId('Items','netsuiteItemInternalId',…)` and the group key already carries the item slot; AND (2)
   update **`fixer.php`** to SELECT the item column in its JE SuiteQL, resolve NS item→local id (reuse
-  `createMissingForecastItemFromNetSuite` self-heal), and extend the group key to `(salesRep, item)`.
+  `createMissingForecastItemFromNetSuite` self-heal), and keep the group key `(salesRep, item, customer)`
+  (customer was added under TRUE-80129; the item slot is already present).
   **`checker.php` needs no change.** Consider whether item should self-heal (salesRep does **not** — see
   the sale-import doc). The salesRep dimension itself is the JE line custom column `custcol_sales_rep_line`
   (wired under TRUE-79862).
@@ -519,6 +549,20 @@ None — Forecast2 is a single shared dataset.
 
 ## Change history
 
+- 2026-07-14 — **`fixer.php` now resolves `customerId` on JE lines, mirroring the importer +
+  recorded the manual all-time backfill** (TRUE-80129, dfranks). `fixJournalEntries()` (the
+  hand-maintained mirror of `buildJournalEntryRows`) previously hard-coded `customerId = NULL`;
+  it now adds a `Customers` lookup (same pattern as `fixOpportunities()`), selects
+  **`tl.entity AS customer`** (a **native** column → no `> 0`/`IS NOT NULL` perf-trap workaround
+  needed), extends the group key to `(salesRep, item, customer)` — keying identically to the
+  importer or its upsert dupes — and adds `customerId` to the read-back SELECT + change-detection
+  compare (guarding the "column dropped from change-detection" footgun) + UPDATE + INSERT. New
+  const `JE_CUSTOMER_LINE_FIELD = 'entity'`. Also documented that the **backfill of existing JE
+  rows is a manual, all-time developer step** (DELETE all `journalEntry` Sales rows, then
+  `fixer.php --commit --prod --category sales` over full JE history) — the checker only flags
+  revenue/profit drift, so a missing-only `customerId` is never auto-detected. Corrected the
+  misattributed `files:` path: `_Component_Forecast_SaleImport` lives in **worker2**, not
+  `_underscore`. (dfranks)
 - 2026-07-07 — **Recorded that these reconcilers are the only backstop for NetSuite sublist
   line-field inline edits + added `Logs.Webhook` forensics** (SALES profit-drift forensics; invoice
   6715127, 2026-02-20, $3,392.70). A line-level inline edit (e.g. `TRANLINE.MCOSTESTIMATE`) fires no

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

@@ -14,7 +14,7 @@
 | [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 |
 | [Error Reporting — Issue/Event Aggregation (agreed POST-to-receiver design)](features/error-reporting-issue-event.md) | Platform-wide error-reporting infrastructure for TOGA 2.0, built around a two-table **Issue / Event** aggregation model in the shared **Core Logs DB**. | _underscore/Error.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, dbchanges2/Logs/2026-07-06 - Issue and Event tables.sql |
 | [Record-Changed Event Publishing (_Event::publish to SQS)](features/event-publish-sqs.md) | `_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event pipeline. | _underscore/Event.php |
-| [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _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/fixer.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
+| [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/probe_je_shape.php, test/@dave/fixer.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [Item-Fulfillment Stage Lifecycle (picked/packed/shipped) & Order Status](features/item-fulfillment-stage-lifecycle-and-order-status.md) | Every ItemFulfillment (IF) now carries an explicit **stage** — picked → packed → shipped — resolved through `ItemFulfillmentStages → ItemFulfillmentStatuses` (m | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Client/SalesOrderItem.php, _underscore/Model/Client/Item.php, _underscore/Model/Client/PurchaseOrderItem.php, library/app/api/toga2.php, dbchanges2/Client/2026-06-30a - BackfillNullStageItemFulfillmentsToShipped.sql, dbchanges2/Client/2026-06-30b - SalesOrderStatusesPickedPacked.sql, dbchanges2/Client/2026-06-30c - ItemFulfillmentStageIdNotNull.sql, dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql |
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
 | [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 |

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

@@ -6,11 +6,11 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-07
+updated: 2026-07-14
 owners: [dfranks]
 files:
-  - _underscore/Component/Forecast/SaleImport/SaleImport.php
-  - _underscore/Component/Forecast/Db/Db.php
+  - worker2/Component/Forecast/SaleImport/SaleImport.php
+  - worker2/Component/Forecast/Db/Db.php
   - _underscore/Component/Api/Netsuite/Netsuite.php
   - worker2/Worker/Netsuite/Invoice.php
   - worker2/Worker/Netsuite/CashSale.php
@@ -57,14 +57,20 @@ The shared engine is `_Component_Forecast_SaleImport`; thin worker2 handlers
 - **Sign convention differs from the cron** — the raw REST record is all-positive, so the
   webhook applies the sign factor **uniformly to every line**, not just shipping. Copying
   the cron's sign handling reintroduces the credit-memo sign bug. (See Sign convention.)
-- The engine is a `_Component_*` class and therefore **must live in `_underscore`**, not in
-  worker2 — the autoloader rejects a `_Component_*` loaded from a project path. (See Gotchas.)
+- **The engine is checked into the `worker2` repo, NOT `_underscore`** — despite its
+  `_Component_*` name. `_Component_Forecast_SaleImport` and `_Component_Forecast_Db` both
+  live under `worker2/Component/Forecast/…` and declare `namespace worker;` (the project-local
+  `_Component_*` requirement). The class-name convention alone does **not** imply an
+  `_underscore` home — planning/context tools repeatedly assert `_underscore` and are **wrong**;
+  a `git` checkout of `_underscore` has **no** `Component/Forecast/SaleImport/SaleImport.php`.
+  Only `_Component_Api_Netsuite` (the REST client, `fetchRecord`/`createRecord`) is genuinely in
+  `_underscore`. (See Gotchas.)
 
 ## Key files / entry points
 | File | Role |
 |---|---|
-| `_underscore/Component/Forecast/SaleImport/SaleImport.php` | the engine (shared body for all four types) |
-| `_underscore/Component/Forecast/Db/Db.php` | shared NS-REST + sublist-pagination helpers |
+| `worker2/Component/Forecast/SaleImport/SaleImport.php` | the engine (shared body for all four types); checked into **worker2**, declares `namespace worker;` |
+| `worker2/Component/Forecast/Db/Db.php` | shared NS-REST + sublist-pagination helpers (also **worker2**, `namespace worker;`) |
 | `worker2/Worker/Netsuite/Invoice.php` etc. | four sale-type thin handlers; `post`/`put` → `sync`, `delete` → `removeAll` |
 | `worker2/Worker/Netsuite/JournalEntry.php` | thin JE handler; `post`/`put` → `syncJournalEntry`, `delete` → `removeAllJournalEntry` |
 | `test/@dave/test_je_lifecycle.php` | JE lifecycle harness (direct-engine create/update/delete) |
@@ -237,8 +243,34 @@ item-line upsert/reconcile machinery (`syncLines`/`guardedInsert`/`deleteRows`).
   `51200→249` COGS Service. Read-only resolver tool: `test/@dave/probe_je_accounts.php`.
 - **Likely future one-line tweak:** if the Agent sub-accounts should count, add `41300.01` to
   the revenue list and `51200.01` to the cost list.
-- Group key uses `json_encode([salesRep, item])` (not a string-join) to stay collision-safe
-  once the fields go live — an empty-string separator would let `"5|" + null` collide.
+- **Customer is now resolved on JE lines and is a THIRD grouping dimension (TRUE-80129,
+  dfranks 2026-07-14).** `buildJournalEntryRows` previously hard-coded `customerId = null` on
+  every JE row. It now reads `JE_LINE_CUSTOMER_FIELD = 'entity'` — a **NATIVE JE-line reference
+  field**, unlike the `custcol_*` salesRep/item fields — via the same `journalLineLookup()`
+  bare-lookup helper, resolving against `Customers.netsuiteInternalId` (the identical
+  table/column the four sale-transaction types already use for `customerId`). `customerId` is
+  folded into the group key as a third dimension (see below), so JE lines sharing rep/item but
+  differing by customer now split into **separate** `Forecast.Sales` rows.
+  - **Non-Customer entities resolve to null with no explicit type check needed** — a JE line's
+    `entity` may be a vendor or employee ref, but NetSuite **internal ids are a single global
+    sequence across all entity subtypes** (customer/vendor/employee never share an id), so a
+    vendor/employee id simply misses `Customers.netsuiteInternalId` and yields null. No
+    `is-customer` guard required. (Reusable NetSuite fact: internal ids are globally unique
+    across record subtypes, not namespaced per subtype.)
+- Group key uses `json_encode([salesRep, item, customer])` (not a string-join) to stay
+  collision-safe — an empty-string separator would let `"5|" + null` collide. (The customer
+  slot was added under TRUE-80129; the fixer mirror MUST key identically — see the
+  reconciliation doc.)
+
+**Backfilling `customerId` onto existing JE rows requires a manual, all-time re-import — the
+code fix alone does NOT backfill (TRUE-80129 decision).** The checker/fixer only detect
+**revenue/profit** drift per JE, so an already-correct-total JE row that is merely **missing
+`customerId`** is **not** flagged discrepant and a normal fixer pass will never repopulate it.
+The chosen backfill (run **manually, once, by the developer after deploy — explicitly out of
+scope for the code PR**): `DELETE` **all** `netsuiteTransactionType='journalEntry'` rows from
+`Sales` (no date-window restriction), then run `fixer.php --commit --prod --category sales`
+over full JE history so `fixJournalEntries()` takes the INSERT branch for every group and
+repopulates all JE rows including `customerId`. (See the reconciliation doc for the fixer side.)
 
 **Reversal handling (a JE-only pattern):**
 - Setting a reversal date makes NetSuite auto-create a **paired reversing JE**, but **only
@@ -524,21 +556,40 @@ success from a `Forecast.Sales` row alone.
   webhook or the daily discrepancy-fix.
 - **Local _underscore boots on PHP 8.0.30 (xampp8)** — the floor enforced in `_underscore.php` is
   **8.0.0**, not 8.1.
-- **`_Component_*` classes must live under the `_underscore` framework root, never a project
-  repo.** The autoloader rejects a `_Component_*`/`_Model_*` loaded from a project path
-  (e.g. `./` under worker2) with "namespace … has not been defined" — at **class-load
-  (runtime), not `php -l`**. So this engine lives in `_underscore` next to
-  `_Component_Forecast_Db` even though only worker2 uses it; it references the worker2 class
-  `_Worker_Netsuite_Item`, resolved lazily at runtime in the worker2 context. **A
-  legitimately project-local `_Component_*`/`_Model_*` (e.g. the worker2 copies of these
-  classes) must still declare `namespace worker;` or it throws the same error at autoload —
-  and this exact global-namespace mistake caused the SALES drift (webhooks fatally threw
-  before writing, presenting as 7-month historical drift). See the
+- **This engine is a project-local `_Component_*` that lives in `worker2`, NOT `_underscore` —
+  correcting the earlier assumption.** `_Component_Forecast_SaleImport` and
+  `_Component_Forecast_Db` are checked into **`worker2/Component/Forecast/…`** and declare
+  `namespace worker;`. A `_Component_*`/`_Model_*` loaded from a project path is legal **only
+  when it declares its project namespace** — omit it and the autoloader throws "namespace …
+  has not been defined" at **class-load (runtime), not `php -l`** (this exact global-namespace
+  mistake caused the SALES drift: webhooks fatally threw before writing, presenting as 7-month
+  historical drift). So the naming convention does **not** put the file in `_underscore`; the
+  namespace declaration is what makes the worker2 location valid. It references the worker2
+  class `_Worker_Netsuite_Item`, resolved lazily at runtime. Only `_Component_Api_Netsuite`
+  (the REST client) is actually in `_underscore`. **Planning/context tooling has repeatedly
+  mis-asserted an `_underscore` home for this engine — verify against a `git` checkout, not the
+  class name.** See the
   [namespace-registration doc](./component-model-namespace-registration.md) for the
-  eval-bridge mechanism and the `catch`/`throw`/`extends` backslash-qualify traps.**
+  eval-bridge mechanism and the `catch`/`throw`/`extends` backslash-qualify traps.
 - The cron's sign handling is not portable here — see Sign convention.
 
 ## Change history
+- 2026-07-14 — **JE lines now resolve `customerId` (was hard-coded null) + corrected the
+  engine's repo location to worker2** (TRUE-80129, dfranks). `buildJournalEntryRows` reads
+  `JE_LINE_CUSTOMER_FIELD = 'entity'` — a **native** JE-line reference field (not a `custcol_*`,
+  unlike salesRep/item) — via `journalLineLookup()` against `Customers.netsuiteInternalId` (same
+  table/column the four sale types use), and folds `customerId` into the group key as a third
+  dimension: `json_encode([salesRep, item, customer])`. Non-Customer entities (vendor/employee
+  refs) resolve to null with no type check because **NetSuite internal ids are one global
+  sequence across all entity subtypes**. Recorded that the backfill of existing JE rows is a
+  **manual, all-time** developer step (DELETE all `journalEntry` Sales rows, then
+  `fixer.php --commit --prod --category sales` over full JE history) — the code fix alone does
+  NOT backfill because the checker only flags revenue/profit drift, not a missing customerId.
+  **Also corrected a long-standing misattribution:** `_Component_Forecast_SaleImport` and
+  `_Component_Forecast_Db` are checked into the **worker2** repo (`namespace worker;`), NOT
+  `_underscore` — the `_Component_*` name does not imply an `_underscore` home; a `git` checkout
+  of `_underscore` has no such file. Only `_Component_Api_Netsuite` is actually in `_underscore`.
+  (dfranks)
 - 2026-07-08 — **Added the webhook-vs-fixer diagnostic playbook** for proving whether inbound
   NetSuite webhooks actually wrote `Forecast.Sales`: correlate `Logs.Webhook` (prod-logs;
   receipt-only, NO status column) against `Core.WorkerJobs` (prod-core; `isSuccess`/

package/knowledge/2.0/apps/ai-bdr/features/bdr-web-funnel-plan.md

@@ -6,7 +6,7 @@ project: "AI-BDR"
 client: shared
 type: feature
 status: draft
-updated: 2026-07-13
+updated: 2026-07-14
 owners: [tcox]
 files:
   - bdr/PLAN.md
@@ -16,8 +16,15 @@ files:
 related:
   - architecture.md
   - web-funnel-content-model.md
+  - web-funnel-app.md
 ---
 
+> **Execution status (2026-07-14):** PLAN **Phases 0–5 are BUILT and QA'd** — the web
+> app engine, full mockup port, and real backend are done. Remaining work is
+> decision-gated, not code (§9.10 HubSpot mechanism, leadership copy, Phase 7 polish,
+> Phase 8 deploy). The built codebase is documented in `web-funnel-app.md`; this doc
+> stays a plan mirror. This body still mirrors `BDR/PLAN.md`.
+
 # BDR: Multi-Campaign "AI BDR / Agent Studio" Web App — Implementation Plan
 
 > **Status:** Draft 2 (needs one more review). Open items tracked in §9; final campaign direction /
@@ -194,7 +201,7 @@ the bundle carries the UUID so a slug maps to the right campaign for logging.
 ## 4. Decisions locked at kickoff
 | Decision | Choice | Consequence |
 |---|---|---|
-| Repo name | **`bdr`** | New greenfield repo. Not yet in the TOGA registry. |
+| Repo name | **`bdr`** | Greenfield repo, registered in the TOGA registry (`agilantsolutions/BDR`). |
 | Framework | **Next.js (App Router) + TypeScript** | Chosen because the site is highly public: SSR + SEO, and a built-in server for the secret-bearing HubSpot/Toga/content calls. Matches `info`, so its patterns port directly. |
 | UI source | **The mockup** | Rebuild its Agent Studio flow faithfully (pixel-perfect). The mockup is React, so components port cleanly into Next.js client components. |
 | Backend source | **`info`** | Reuse HubSpot/Toga/callback logic directly (same framework). |
@@ -551,5 +558,11 @@ so fidelity should be near-exact.
 - [ ] Pixel-perfect parity pass against the mockup screens + screenshots.
 
 ## Change history
+- 2026-07-14 — Phases 0–5 executed and QA'd (engine + full mockup port + real backend);
+  built codebase now documented in `web-funnel-app.md`. `BDR/PLAN.md` itself corrected:
+  absolute local paths genericized, and the stale "not yet in TOGA registry" note fixed
+  (bdr IS registered). Repo now lives at `agilantsolutions/BDR` (branch `BDR-Development`);
+  the local `.claude/` harness is gitignored (devs pull it via `npx toga-ai`). Body still
+  mirrors PLAN.md. (tcox)
 - 2026-07-13 — Draft 2 resync: re-mirrored the body from the current `BDR/PLAN.md`. Framework locked to Next.js App Router (earlier React/Vite SPA idea dropped); content store decided HubSpot over Contentful (rationale in §4/§5.2); no-hardcoding (HubSpot-owned, fetched by slug from the start); same-product framing confirmed (front door of the existing AI-BDR backend, "backend relationship" open question resolved); meeting-specific dates/cadence removed. Still a draft. (tcox)
 - 2026-07-08 — Captured the full BDR web-funnel implementation plan verbatim into the knowledge repo as a companion to the distilled `web-funnel-content-model.md` feature doc (redundancy intentional). (tcox)

package/knowledge/2.0/apps/ai-bdr/features/web-funnel-app.md

@@ -0,0 +1,143 @@
+---
+title: Web Funnel — Built Next.js App (structure, stack, how to run)
+framework: "2.0"
+repo: ai-bdr
+project: AI-BDR
+client: shared
+type: feature
+status: active
+updated: 2026-07-14
+owners: [tcox]
+files:
+  - bdr/PLAN.md
+  - bdr/.gitignore
+  - bdr/eslint.config.mjs
+  - bdr/amplify.yml
+  - bdr/src/app
+  - bdr/src/lib/resolveCampaignId.ts
+  - bdr/src/content
+  - bdr/src/components
+  - bdr/src/flow
+  - bdr/src/server
+  - bdr/src/app/api
+  - bdr/test
+  - bdr/public
+  - bdr/mockup/styles.css
+related:
+  - web-funnel-content-model.md
+  - bdr-web-funnel-plan.md
+  - ../architecture.md
+---
+
+## What this is
+
+The **built** state of the BDR web funnel — the Next.js UI / lead-capture front
+door of the existing AI-BDR product (see `../architecture.md`). The forward-looking
+plan lives in `bdr-web-funnel-plan.md`; the config-driven content contract lives in
+`web-funnel-content-model.md`. **This doc covers the actual shipped codebase: the
+stack, the directory map, what was ported vs. parked, the test suite, and the
+decisions that are load-bearing for anyone touching the repo.**
+
+As of this writing **PLAN Phases 0–5 are BUILT and QA'd** — the web app engine and
+full mockup port are complete, all screens/modals render config-driven from a
+bundle, and the real backend is wired behind adapters. Developer QA verdict: the UI
+is "very close, minimal adjustments to be near exact" vs. the mockup. Remaining work
+is **decision-gated, not code** (see "What is parked / not built").
+
+- **Repo:** `agilantsolutions/BDR` on GitHub, working branch `BDR-Development`. The
+  machine-local `.claude/` harness is **gitignored** — committing it would snapshot
+  the whole KB stale; devs get the harness via `npx toga-ai`, not from this repo.
+
+## Stack
+
+- **Next.js 16.2.3, App Router + TypeScript**, mirroring the `info` repo's config.
+- **No Tailwind (deliberate).** Tailwind 4's preflight reset would fight the mockup's
+  hand-authored CSS (ported verbatim as `src/app/studio.css`) and threaten pixel
+  parity. Do **not** add Tailwind to this repo — the styling is intentionally the
+  mockup's own CSS-variable system. See the styles.css escape-sequence gotcha below.
+- **ESLint flat config** carries a **no-em-dash rule** on shipped strings
+  (`Literal` / `TemplateElement` / `JSXText` selectors) — enforces the mockup copy
+  rule on in-repo strings (`eslint.config.mjs`).
+- **Vitest** test suite: **67 tests across 7 files, all green.** Every phase was
+  verified with `tsc` + lint + build + a live SSR `curl` before commit.
+- **Deploy target:** AWS Amplify (SSR), `amplify.yml` present (Phase 8 not done).
+
+## Directory map (what got built)
+
+- `src/app/*` — App Router shell + pages; `page.tsx` is a server component that
+  resolves the campaign and primes the lead server-side (from `?hsContactId`) and
+  **never fails rendering**. `src/app/studio.css` is the mockup CSS ported verbatim.
+- `src/lib/resolveCampaignId.ts` — campaign entry resolution: `?campaign=<slug>` →
+  `?hsCampaignId=` mapped → `DEFAULT`. Slug regex `^[a-z0-9][a-z0-9-]{0,63}$`.
+- `src/content/*` — the content layer (schema/provider/default/hook). See
+  `web-funnel-content-model.md` for the contract; the schema is now THE contract.
+- `src/components/*` — full mockup component library port: `Ico` (27-icon registry
+  hydrating bundle icon keys), `SwapFade`, `TalkingPreview`, `VoiceDial`, etc., with
+  the mockup's motion hardening ported **verbatim** (do not "simplify" the settle
+  guards / effect-owned timers away).
+- `src/flow/*` — `useAgentFlow` state machine (the `go()` / `back` map, modal gates)
+  plus the screens. Persists to `localStorage` (`aibdr.v2`) where **only voice
+  survives a refresh**; the flow restarts at Welcome.
+- `src/server/*` — the real backend, ported from `info`'s `toga.ts` / `hubspot.ts`
+  behind `LeadSink` + `CallbackService` adapters (detail in
+  `web-funnel-content-model.md`).
+- `src/app/api/*` — route handlers `call-now`, `call-later`, `contact`.
+- `public/*` — assets pruned to the **default campaign only** (~6.2 MB).
+- `test/*` — the 67-test Vitest suite.
+
+## How the built app behaves (key runtime facts)
+
+- **Agent identity is campaign config.** AutoBuild lands on the campaign's
+  `bundle.agent`, **not** a hardcoded "Alex" — the presented agent (art, accent,
+  voice, name) comes from the resolved bundle. The manual Creator is parked, so the
+  user does not pick the agent in the default flow.
+- **Template tokens** `<agent>` / `<date>` / `<tz>` / `<time>` / `<detail>` in bundle
+  strings are substituted at render by an `agentize()` helper.
+- **Funnel always renders.** `resolveCampaign` never throws — an unknown slug or a
+  provider failure returns the `DEFAULT` bundle. The server page primes the lead but
+  never fails rendering on a bad/absent contact.
+- **Boundary validation on every route handler.** 16 KB body cap; phone / UUID / ISO
+  checks; all handlers return the `{isSuccess, status, error, messages, data}`
+  envelope (same contract as `info`/Toga).
+
+## What is parked / not built
+
+- **Creator screen + `TweaksPanel` — deliberately NOT ported** (parked per plan
+  §9.3 / §9.7).
+- **`hubspotProvider` is a throwing stub**, gated on the §9.10 HubSpot content-
+  modeling decision. Until HubSpot is seeded, `DEFAULT_BUNDLE` carries the mockup's
+  copy verbatim as documented **interim dev content**; it slims to a bare
+  engineering fallback once HubSpot is seeded.
+- **`info`'s dead 501 `visit` route was dropped** on purpose (attack surface, no
+  caller).
+- **Remaining work is decision-gated, not code:** §9.10 HubSpot content mechanism
+  (HubDB likely — gates the provider + campaign seeding, Phase 6); leadership's
+  first-campaign copy; Phase 7 pixel/GA4/accessibility polish; Phase 8 Amplify SSR +
+  `togatech` integration.
+
+## Gotchas
+
+- **The mockup's `mockup/styles.css` contains literal `\n` and `\"` escape sequences**
+  (JS-string generation artifacts, around lines ~759 / ~840) that break real CSS
+  parsers. This was **fixed in the ported `src/app/studio.css`**, but
+  `mockup/styles.css` was intentionally left pristine — so **anyone re-porting the
+  mockup CSS must re-apply this fix.**
+- **No PII in logs.** All of `info`'s PII-logging was stripped on port (identifier-
+  only logs); the Toga error paths **strip query strings** because the contact
+  lookup carries the email in the query. Do not reintroduce value logging.
+- **No Tailwind** — see Stack. The mockup CSS is the styling system; adding Tailwind
+  risks pixel parity.
+- **`.claude/` is gitignored** in the BDR repo on purpose — do not commit the
+  harness; pull it with `npx toga-ai`.
+
+## Change history
+- 2026-07-14 — Initial doc: recorded the BUILT state of the BDR web funnel (PLAN
+  Phases 0–5 executed + QA'd). Next.js 16.2.3 App Router/TS, deliberate no-Tailwind,
+  ESLint no-em-dash rule, `resolveCampaignId`, full mockup component/flow port
+  (`useAgentFlow`, Ico registry, motion hardening verbatim), agent identity as
+  campaign config, real backend behind LeadSink/CallbackService with PII logging
+  stripped and boundary-validated route handlers, 67 green Vitest tests. Recorded the
+  parked items (Creator/TweaksPanel, throwing hubspotProvider, dropped `visit` route)
+  and the `mockup/styles.css` escape-sequence re-port gotcha. (tcox)
+</content>
+</invoke>

package/knowledge/2.0/apps/ai-bdr/features/web-funnel-content-model.md

@@ -6,22 +6,31 @@ project: AI-BDR
 client: shared
 type: feature
 status: draft
-updated: 2026-07-13
+updated: 2026-07-14
 owners: [tcox]
 files:
   - bdr/src/content/schema.ts
   - bdr/src/content/hubspotProvider.ts
   - bdr/src/content/useCampaign.ts
   - bdr/src/content/default.ts
+  - bdr/src/lib/resolveCampaignId.ts
   - bdr/src/server/leadSink.ts
   - bdr/src/server/callbackService.ts
   - bdr/src/app/api/call-now/route.ts
   - bdr/src/app/api/call-later/route.ts
+  - bdr/src/app/api/contact/route.ts
 related:
   - ../architecture.md
   - call-orchestration.md
+  - web-funnel-app.md
 ---
 
+> **Status note:** the content **contract** below (schema, provider seam, adapters)
+> is now BUILT and QA'd (PLAN Phases 0–5). The built codebase — structure, stack,
+> how to run — is documented in `web-funnel-app.md`. The one part still **not** built
+> is the HubSpot content *sourcing* (`hubspotProvider` is a throwing stub gated on the
+> §9.10 mechanism decision), which is why this doc stays `draft`.
+
 ## What this is
 
 The **public-facing web funnel** is the new UI / lead-capture front door of the **same
@@ -100,6 +109,24 @@ optional `build` (AutoBuild beats), `analytics`, and `features[]` capability fla
 `RichLine` supports the accent-inked span the mockup uses (e.g. `"<agent> is ready to
 work."`). The mapping layer is the seam between HubSpot storage and this contract.
 
+**Schema calibrated by building (the §6 plan sketch was a sketch; `src/content/schema.ts`
+is now THE contract).** Additions made while building the real screens: `chrome`
+(wordmark / rail labels); capabilities `eyebrows` + qbank strings + `howLink`;
+`connectNote` split to `{label, value}`; `earlyAccess` / `phone` / `recap` groups;
+`build` made **required**. Bundle template tokens `<agent>` / `<date>` / `<tz>` /
+`<time>` / `<detail>` are substituted **at render** by an `agentize()` helper (they are
+plain strings in the bundle, so HubSpot only ever stores strings).
+
+**`resolveCampaign` never throws** (built): an unknown slug or a provider failure
+returns the `DEFAULT` bundle, so the funnel always renders. Entry resolution lives in
+`src/lib/resolveCampaignId.ts` (`?campaign=<slug>` → mapped `?hsCampaignId=` →
+`DEFAULT`; slug regex `^[a-z0-9][a-z0-9-]{0,63}$`).
+
+**`hubspotProvider` is a throwing stub** explicitly gated on the §9.10 HubSpot-modeling
+decision — it is not wired yet. Until HubSpot is seeded, **`DEFAULT_BUNDLE` carries the
+mockup's copy verbatim as documented interim dev content**; once HubSpot is seeded it
+slims to a bare engineering safety-net fallback (not authored marketing copy).
+
 ## Backend reuse (from the `info` repo; existing AI-BDR calls)
 
 The funnel's Call Now / Schedule screens submit to a real backend **ported from the
@@ -118,6 +145,16 @@ so only the impl changes later:
 - `CallbackService.requestCall(ref, whenOrNow, phone)` → Toga `requestCall`, immediate vs.
   scheduled mapped to `CONTACT_CALL_TYPE_UUID`.
 
+**Built (PLAN Phase 5):** `info`'s `toga.ts` / `hubspot.ts` are ported into `src/server/`
+behind those adapters with **all of `info`'s PII logging stripped** (identifier-only
+logs; the Toga error paths **strip query strings** because the contact lookup carries
+the email in the query). Route handlers `/api/call-now`, `/api/call-later`, `/api/contact`
+**validate at the boundary** (16 KB body cap; phone / uuid / ISO checks) and always
+return the `{isSuccess, status, error, messages, data}` envelope. The page primes the
+lead server-side from `?hsContactId` and never fails rendering. `info`'s dead 501
+`visit` route was deliberately dropped (attack surface, no caller). Verified by 67 green
+Vitest tests. See `web-funnel-app.md` for the full built structure.
+
 Note on "campaign": `info` uses HubSpot **only to fetch the contact**; the URL's
 `hsCampaignId` is passed to Toga as the attribution campaign UUID
 (`addContactToCampaign`) — attribution-only in `info`. **Fetching marketing content by
@@ -158,6 +195,16 @@ right campaign for logging.
   `var(--accent)` (+ derived `--accent-fill`); never hardcode an accent value.
 
 ## Change history
+- 2026-07-14 — Content contract BUILT + QA'd (PLAN Phases 0–5): schema calibrated by
+  building the real screens (`src/content/schema.ts` is now THE contract — chrome,
+  capabilities eyebrows/qbank/howLink, `connectNote` {label,value}, earlyAccess/phone/
+  recap groups, `build` required, `agentize()` token substitution); `resolveCampaign`
+  never throws (unknown slug/provider failure → DEFAULT); `hubspotProvider` is a throwing
+  stub gated on §9.10; `DEFAULT_BUNDLE` carries the mockup copy as interim dev content.
+  Backend ported from `info` behind LeadSink/CallbackService with PII logging stripped,
+  boundary-validated route handlers, dead `visit` route dropped; 67 green Vitest tests.
+  Built structure split out to `web-funnel-app.md`. Kept `draft` because HubSpot content
+  sourcing (§9.10) is still open. (tcox)
 - 2026-07-13 — Draft 2 resync to the current plan: framework locked to Next.js App Router
   (earlier React/Vite SPA idea dropped); recorded the **HubSpot-over-Contentful** content-store
   decision + rationale (marketing already in HubSpot, campaign model already exists, trivial

package/package.json

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