toga-ai 1.0.291 → 1.0.292

package/knowledge/2.0/apps/_underscore/features/component-model-namespace-registration.md

@@ -92,6 +92,15 @@ project-local `_Component_*`/`_Model_*` must still declare the project namespace
   unqualified `catch (Exception $e)` fails **silently** — the more insidious of the two.
 
 ## Change history
+- 2026-07-08 — **Production recurrence** of this exact fatal (concrete fingerprint, no doc change
+  to the mechanism): a worker2 deploy declared `_Component_Forecast_SaleImport`
+  (`Worker/Netsuite/Invoice.php` autoload) and its sibling `_Component_Forecast_Db`
+  (`Component/Forecast/Db/Db.php`, opportunity jobs) in the global namespace → every
+  Forecast-writing NetSuite webhook type threw at autoload the moment the deploy landed, flipping
+  a Forecast-wide ~98%-success window to ~72%-failure at a single timestamp. Confirms the
+  invisible-to-`php -l`, blocks-all-writes-before-DB behavior in prod. Diagnostic path (how the
+  before/after `isSuccess` split is read out of `Core.WorkerJobs`) is captured in the
+  [Forecast.Sales import doc's diagnostic playbook](./forecast-sale-import.md). (dfranks)
 - 2026-07-08 — Documented the `_Component_*`/`_Model_*` project-namespace registration
   requirement (Loader.php eval-bridge mechanism, ~71-83), the runtime-only failure mode (not
   caught by `php -l`), and the three constructs that must be backslash-qualified inside a

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

@@ -447,6 +447,46 @@ Keep **create→delete windows short** so most records slip between cron runs; o
 `import_sales` during a batch. (The daily discrepancy-fix also cleans stragglers since the
 record is deleted in NetSuite.)
 
+## Diagnostic playbook — proving whether inbound webhooks actually wrote Forecast.Sales (run cold)
+Durable procedure for answering "did the real-time webhook path work, or is a `fixer.php`
+sweep masking a broken pipeline?" It spans **two DB clusters** — correlate them; never infer
+success from a `Forecast.Sales` row alone.
+1. **Receipt (prod-logs `Logs.Webhook`)** — proves the POST *arrived*, nothing more. Columns:
+   `id, uuid, dtStamp, sourceIp, method, route, requestPayload` (JSON with
+   `recordType`/`internalId`/`eventType`/`action`). NetSuite hits land on route `/netsuite`.
+   **There is NO status/error column** — a row here means "received", not "succeeded".
+2. **Success/failure (prod-core `Core.WorkerJobs`)** — the authoritative outcome:
+   `isSuccess` (NULL=pending/running, 0=fail, 1=success), `failureReason` (mediumtext, full
+   stack trace), `action`, `dtCreated`.
+3. **Two-stage fan-out.** The router job `action='Netsuite/Webhook'` fans out to per-record-type
+   **child** jobs (`Netsuite/Invoice/post`, `Netsuite/SalesOrder/put`, `Netsuite/Opportunity/*`,
+   etc.). The **router almost always succeeds**; the Forecast writes — and their failures — live
+   in the **child** jobs. Filter WorkerJobs on the child `action`, not the router, to judge the
+   pipeline.
+4. **CRITICAL — a `Forecast.Sales` row does NOT prove the webhook worked.** `fixer.php` (the
+   reconciliation sweep) independently writes/repairs rows, so a present row can mask a fully
+   broken webhook path. **Always correlate `Logs.Webhook.dtStamp` against
+   `WorkerJobs.isSuccess`/`dtCreated` by uuid/timestamp** — never conclude success from row
+   presence.
+5. **Bucket errors by class.** `failureReason` embeds a per-row `[uuid] ` prefix; strip it with
+   `CASE`/`REGEXP_REPLACE` to collapse per-row UUIDs into error classes and get clean counts —
+   the fast way to distinguish a deployment-wide fatal from long-tail noise.
+
+**Known WorkerJobs failure classes on this pipeline (durable):**
+- **Autoload fatal blocks ALL Forecast writes before any DB work** — a global-namespace
+  `_Component_Forecast_SaleImport`/`_Component_Forecast_Db` throws at autoload (see the
+  [namespace-registration doc](./component-model-namespace-registration.md)); every
+  Forecast-writing child type (Invoice/SalesOrder/Opportunity/JournalEntry/CashSale/CreditMemo)
+  fails identically and the fatal is **invisible to `php -l`**. A clean before/after `isSuccess`
+  split at a single deploy timestamp is the fingerprint (a bad push flips a Forecast-wide
+  ~98%-success window to ~72%-failure). Recurred in production 2026-07-08.
+- **`Netsuite/InventoryItem/*` / `NonInventoryItem/post` — `watchdog: exceeded maxExecutionTime
+  without completing`**: item syncs timing out at the 300s watchdog.
+- **`Netsuite/Invoice/post` — MySQL error 1213 `Deadlock found when trying to get lock`** on the
+  Forecast DB: pre-existing, low-volume, ~1.6–3.9s each.
+- **`Netsuite/Webhook` router — `Unsupported NetSuite eventType: approve`** (`Worker/Netsuite.php`
+  ~line 53): salesOrder `approve` events aren't handled by the router and fail at fan-out.
+
 ## Gotchas / known issues
 - **Testing locally pollutes PROD unless you UNDEPLOY the prod AMQ enqueuer first.** Each sale
   transaction type has **TWO** NetSuite UE enqueuer deployments: **"AMQ — Enqueuer"**
@@ -499,6 +539,19 @@ record is deleted in NetSuite.)
 - The cron's sign handling is not portable here — see Sign convention.
 
 ## Change history
+- 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`/
+  `failureReason`), judge the **child** `Netsuite/<Type>/<verb>` jobs (not the almost-always-OK
+  `Netsuite/Webhook` router), and **never infer success from a `Forecast.Sales` row** because
+  `fixer.php` independently writes/masks rows — correlate timestamps. Bucket `failureReason` with
+  `CASE`/`REGEXP_REPLACE` (strip the `[uuid] ` prefix) into error classes. Recorded a concrete
+  **production recurrence (2026-07-08)** of the global-namespace autoload fatal on
+  `_Component_Forecast_SaleImport`/`_Component_Forecast_Db` (Forecast-wide, invisible to `php -l`,
+  clean before/after `isSuccess` split at a single deploy timestamp), plus three lower-volume
+  WorkerJobs failure classes on this pipeline (item-sync watchdog timeout; Invoice deadlock 1213;
+  router `Unsupported NetSuite eventType: approve`). Read-only diagnostic session, no code change.
+  (dfranks)
 - 2026-07-08 — **Clarified the revenue sign convention is NOT the `amountDue` "store raw
   positive" rule.** The TRUE-78923 "don't sign-flip credit memos/refunds" guidance applies
   only to `amountDue` (which this importer does not write); the line `amount`/revenue sign

package/package.json

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