toga-ai 1.0.221 → 1.0.222

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/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, 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 |
 | [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

@@ -6,9 +6,11 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-25
+updated: 2026-06-26
 owners: [dfranks]
 files:
+  - test/@dave/checker.php
+  - test/@dave/looper.php
   - test/@dave/reconcile_netsuite_totals.php
   - test/@dave/fixer.php
   - test/@dave/analyze_netsuite_forecast_diff.php
@@ -42,6 +44,37 @@ by reconciling a chosen tranDate range directly against NetSuite.
 
 ## Key files / entry points
 
+- `checker.php [--from --to] [--category sales|openorders|opportunities|all] [--verbose] [--no-banner] [--fix --prod]`
+  — **hyper-fast drift detector** using a **moment-fingerprint drill-down** (default window = YTD).
+  Instead of materializing every row on both sides and diffing (the OOM trap that gates `reconcile`'s
+  per-txn diffs), each side computes a **5-number fingerprint PER TIME BUCKET** entirely in-DB in one
+  `GROUP BY`: `n` = COUNT of non-zero-measure records; `rev` = `ROUND(SUM(revenue),2)`;
+  `profit` = `ROUND(SUM(profit),2)` (Sales only); `idSum` = `MOD(SUM(MOD(id,P)),P)`;
+  `idSq` = `MOD(SUM(MOD(id*id,P)),P)`, where `P = 2147483647` (2³¹−1 Mersenne prime). `(rev,profit)`
+  catch **value drift**; `(n,idSum,idSq)` are a **power-sum fingerprint of the id SET** that catches the
+  **compensating case** a plain SUM total can't see (a missing txn masked by an extra txn of equal value).
+  Power-sums are pure integer arithmetic, so they compute **identically on Oracle-flavored SuiteQL and
+  MySQL** (no cross-engine hash-portability problem); `MOD` by the prime keeps the running sums inside
+  64-bit. Compared **top-down, descending only where fingerprints disagree**: L1 `GROUP BY` month → L2
+  `GROUP BY` day (only inside bad months) → L3 per-id list (`--verbose`, reporting only). A clean system
+  **stops at L1 in seconds pulling no rows**. Match identity is the **NetSuite internal id**
+  (`netsuiteTransactionInternalId` / `netsuiteSalesOrderInternalId` / `netsuiteOpportunityInternalId`);
+  date + category are only **scoping/localization**, never identity. Identity (count + id-moments) is
+  computed over **non-zero-measure rows only**, so checker's "in sync" verdict equals fixer.php's "nothing
+  to fix" **by construction** (a missing $0 row is a non-issue). On drift it hands `fixer.php` a **tight
+  day window** (window handoff, not id handoff — see decision below). `--fix` requires `--prod` (auto-runs
+  fixer on the localized window); a **bare run never writes**. Reads the prod core2 **read-replica**
+  directly (same pattern as `reconcile_netsuite_totals.php` / `fixer.php` — creds live in
+  `worker/config.worker.ini` / `CLAUDE.md`, not reproduced here).
+- `looper.php [--interval=60] [--count=0] [--cmd "<verbatim>"] [--args "<extra checker flags>"] [--no-banner] [--no-fix]`
+  — **generic loop runner**, self-contained (no framework bootstrap; shells out via `passthru`). **DEFAULT
+  BEHAVIOR (bare `php looper.php`): loops `checker.php --no-banner --fix --prod` every 60s — i.e. it
+  continuously AUTO-CORRECTS PRODUCTION** (prints a bold warning Mode line; the once-only LOOPER ASCII
+  banner gets the subline "Looper / Checker / Fixer" in fix-prod mode). `--no-fix` gives a **read-only
+  detect loop**. `--count 0` = forever; `--cmd` loops a verbatim command instead of checker (no flags
+  added); `--args` appends extra checker flags. Suppresses checker's own per-run banner; prints per-run
+  dividers with run #, timestamp, exit code, elapsed. Rationale: continuous unattended drift monitoring +
+  auto-correction.
 - `reconcile_netsuite_totals.php [from] [to] [--verbose]` — category grand totals NS vs Forecast2
   (Sales, Sales Profit, Open Orders, Opportunities) with deltas. Read-only. Connects explicitly to
   the **prod core2 reader**; NetSuite via SuiteQL SUMs. `--verbose` additionally prints the
@@ -141,6 +174,18 @@ by reconciling a chosen tranDate range directly against NetSuite.
   stays bounded under the existing 1G `memory_limit`. (This corrected a prior docblock claim that `$sqls`
   was never accumulated globally.)
 
+- **checker → fixer handoff is WINDOW-based, not id-based (decision).** checker hands fixer a tight day
+  window and lets fixer **re-find** the discrepant ids inside it, rather than passing exact ids. Rationale:
+  maker≠checker independence (fixer re-derives the drift), and checker has already shrunk the window, so a
+  re-scan is cheap. Id-passing only wins when drift is **sparse across a wide span** (it would skip fixer
+  re-scanning clean gaps). **Deferred (NOT built):** (a) an `--ids` skip-find path so checker passes exact
+  ids; (b) a `--since` "recency-pruned fingerprint" mode that uses NS `lastmodifieddate` to choose which
+  `trandate` buckets to fingerprint, walking backward until clean. ⚠ A `--since` mode has **structural blind
+  spots**: pure NS **deletions** (orphan Forecast rows) and **old untouched drift** are invisible to a
+  lastmodified scan, so the full `trandate` fingerprint stays the authoritative backstop. Forecast tables key
+  on `tranDate`, not NS `lastmodifieddate`, so a **symmetric** lastmodified fingerprint isn't possible — it
+  would require NS-pull-then-id-lookup or the recency-pruned approach.
+
 ## Data model
 
 `Forecast.Sales`, `Forecast.OpenOrderItems` on the **core2** cluster
@@ -206,6 +251,24 @@ None — Forecast2 is a single shared dataset.
   concentrated **Dec 2025–Apr 2026**, driven by NetSuite re-valuing `costestimate` on older
   invoices that no `lastmodifieddate`-based sync re-pulls. (Revenue reconciles to the penny; only
   profit drifts.)
+- **Open-orders "round-then-sum" vs "sum-then-round" — the most broadly reusable rounding gotcha.**
+  `Forecast.OpenOrderItems.revenue`/`profit` is `decimal(14,2)`: Forecast stores each open-order **LINE's**
+  revenue (`qtyOpen × rate`) **rounded to cents on store, then sums** (`SUM(round(line,2))`). A NetSuite-side
+  aggregate that does `ROUND(SUM(qtyOpen*rate),2)` (**sum-then-round**) diverges by up to ~½¢ **per line** —
+  benign rounding noise that **scales with line count**, so **no fixed aggregate-dollar tolerance can separate
+  it from real drift** (a busy bucket's benign band can reach whole dollars). This produced an **unfixable
+  phantom**: `fixer.php`'s FIND flags such a penny SO, but its FIX compares **per-line**, finds every line
+  already correct to the cent, writes nothing — and the SO churns forever in a loop. **FIX: round each line to
+  cents BEFORE summing on the NS side** — `SUM(ROUND(((-tl.quantity) - NVL(tl.quantitybilled,0)) * tl.rate, 2))`
+  — so NS matches Forecast's `decimal(14,2)` storage exactly; any remaining diff is then genuinely different
+  inputs = real drift. Applied to **both** `checker.php` (open-orders `nsSub` SELECT + HAVING) and `fixer.php`
+  `findOpenOrderDiscrepancies`. **Affects ONLY open orders** (a computed `qty×rate` product); Sales/Opportunities
+  sum pre-rounded `foreignamount`/`projectedtotal` and were already exact. Verified: full 18-month open-orders
+  window went from "drift" to cents-exact in sync after the fix. The previously-reported open-orders deltas were
+  entirely this artifact, NOT data drift: the ~$0.04 `reconcile` delta, and the per-SO 1¢ on **SO 6870666**
+  (NS 852.06 vs FC 852.07). **Correction to any prior note:** the open-orders **2025-04 "unlocalized month" was
+  this round-then-sum noise, NOT NS-live-vs-Forecast-replica timing jitter** — the rounding fix eliminated it,
+  disproving the earlier replica-jitter hypothesis.
 - **Compare money at 2 decimals.** DB columns store 2dp but PHP `revenue - cost` carries float
   dust (`313.6` vs `313.60000001`); raw `!=` produced thousands of phantom UPDATEs that re-wrote
   identical values (1,839 on one open-orders run). Both tools now compare `round((float)$x, 2)`.
@@ -297,6 +360,20 @@ None — Forecast2 is a single shared dataset.
 
 ## Change history
 
+- 2026-06-26 — **Added `checker.php` (moment-fingerprint drift detector) + `looper.php` (loop runner), and
+  found/fixed the open-orders round-then-sum rounding gotcha.** `checker.php` confirms sync in seconds and
+  localizes real drift via a 5-number per-bucket fingerprint (`n,rev,profit,idSum,idSq`; power-sums mod the
+  2³¹−1 prime → engine-portable) drilled top-down month→day→id, descending only into mismatched buckets,
+  pulling no rows on a clean book; hands fixer a tight **day window** (window handoff, not id — decision
+  recorded). `--fix` requires `--prod`; bare run never writes. `looper.php` defaults to looping
+  `checker --no-banner --fix --prod` every 60s (continuous prod auto-correction; `--no-fix` = read-only).
+  **Rounding gotcha:** `OpenOrderItems` `decimal(14,2)` stores each line round-then-sum, so a NS-side
+  sum-then-round aggregate diverges up to ~½¢/line (an unfixable phantom that loops fixer forever); fixed by
+  rounding each NS line to cents before summing (`SUM(ROUND(qtyOpen*rate,2))`) in both `checker.php` and
+  `fixer.php` `findOpenOrderDiscrepancies` — open-orders only (Sales/Opps already exact). This also
+  **disproves the earlier replica-jitter hypothesis** for the open-orders 2025-04 unlocalized month — it was
+  the same per-line rounding. Deferred: `--ids` skip-find and a `--since` recency-pruned fingerprint (blind to
+  NS deletions + old untouched drift). (dfranks)
 - 2026-06-25 — **`trueup_open_orders` Step 4 now lists the exact per-statement SQL** (`<NS SO id>  <SQL>`,
   one line per statement) for both live and `--dry-run` passes, so a dry-run is auditable and any
   unexpected insert/update/delete is traceable to its source order. Implemented via a global `$sqlLog`

package/package.json

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