toga-ai 1.0.142 → 1.0.144

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

@@ -58,12 +58,12 @@ App_Api_Netsuite_Rest::authenticate();   // acquire OAuth2 token once
 - In our usage the client is effectively **read-only**: only `GET` (record fetch) and `POST`
   (SuiteQL) are exercised. `send()` accepts any verb (incl. PATCH/PUT) but we don't write through it.
 
-### The `send()` logging trap (dev laptop)
+### Disabling logging for ad-hoc SuiteQL probes
 
-`App_Api_Netsuite_Rest::send()` auto-authenticates but does **not** call `setLogging(false)`. From a
-dev laptop the API-log DB write then fails and the framework error handler reports a **misleading
-"Could not connect to database 'Vision'"** that masks the real result. Workaround: `authenticate()`
-once, then issue your own `App_ApiTransaction` with logging off:
+`App_Api_Netsuite_Rest::send()` auto-authenticates and logs to the API-log DB by default (it does
+**not** call `setLogging(false)`). That's fine in normal environments; for a one-off **read-only
+probe** you can keep the call out of the API log by authenticating once and issuing your own
+`App_ApiTransaction` with logging off:
 
 ```php
 $url = rtrim(App_Api_Netsuite_Rest::$endpoint, '/') . App_Api_Netsuite_Rest::API_BASE_PATH

package/knowledge/1.0/apps/worker/workflows/onboarding-client-to-netsuite-togasupply-sync.md

@@ -90,7 +90,7 @@ the directory; no `USE`).
   with "Unknown database 'logs_<name>'" if absent.
 - Run the cron in place with `C:\xampp8\php\php.exe` from the `worker/` dir; the autoloader
   walks up to `worker/_` for `__APPROOT__`. `App_Api_Netsuite_Rest::authenticate()` +
-  `App_ApiTransaction->setLogging(false)` is the laptop-safe NetSuite pattern (see
+  `App_ApiTransaction->setLogging(false)` is the read-only SuiteQL probe pattern (see
   `test/@dave/nsq.php`, a read-only SuiteQL runner).
 - Verified behavior: empty window → 0 writes, checkpoint advances (clean no-op); record
   already present → `PUT` update (idempotent, keyed on `c_netsuiteInternalSalesOrderId`, no

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

@@ -145,8 +145,8 @@ Shared helpers: `buildCustomFields()` (the field array, used by both create and
   `Presales Lead Email`, and `Presales Lead` (users field).
 - The ClickUp token comes from `[clickup] token` in the worker2 config (legacy webhook received
   it on the payload; the new contract drops it).
-- Every ClickUp `_ApiRequest` calls `setLogging(self::CLICKUP_API_LOGGING_ENABLED=false)` — the
-  `_ApiRequest` Logs-DB default otherwise surfaces a misleading "connection refused" on dev laptops.
+- Every ClickUp `_ApiRequest` calls `setLogging(self::CLICKUP_API_LOGGING_ENABLED=false)`, so ClickUp
+  traffic is not written to the Logs DB.
 
 ## Data model
 
@@ -181,6 +181,35 @@ None — platform-wide Forecast sync.
   at all. Give `ss_amq_drain` a dedicated `Not Scheduled` deployment as the on-demand slot (add more
   for concurrency) and keep a `Scheduled` one for the cron. Submit by **scriptId only** — the
   deployment id is prefix-doubled (`customdeploycustomdeploy_ss_amq_drain`).
+- **Under a create/edit burst the on-demand kick still drops with `NO_DEPLOYMENTS_AVAILABLE`, and the
+  scheduled drainer is the ONLY backstop — but its floor is 15 min, which is NOT acceptable as the normal
+  path.** When the automated process mass-creates records, enqueues outrun the `Not Scheduled` slot pool;
+  the enqueuer logs `AMQ drainer NOT kicked (cron will catch it)` and the row sits `Created` until the cron
+  sweeps it. Widening the slot pool (we run **1 Scheduled + ≥4 Not Scheduled** `ss_amq_drain` deployments)
+  raises the ceiling; `Created` is sweepable so a dropped kick is a *delay*, not a loss (only terminal
+  `Failed`, after `maxRetries`, is a true dead-letter). **But the push must stay near-real-time via the
+  kick — do not "fix" the read-races by deferring delivery to the cron.** And you **cannot add a settle
+  delay inside the SuiteScript**: server-side SuiteScript has **no `sleep()` and no `setTimeout`** (no event
+  loop); a `while(Date.now()<t){}` busy-wait would block the UE `afterSubmit` (the user's save) and trip the
+  execution-time limit. Any "let the record settle before reading" mitigation belongs on the **worker2 read
+  side** (PHP can sleep), never the enqueuer. (See the open-orders doc's REST-sublist read-after-write-lag
+  gotcha for why a settle/SuiteQL-source fix is wanted in the first place.)
+- **A `Released` UE deployment with an EMPTY audience fires for NO ONE — `Released` ≠ active.** Live
+  incident 2026-06-18: the Opportunity `ue_amq_enqueue` deployment was flipped `Testing → Released` at
+  ~4:41 pm but **Audience: All Roles / All Employees were still F**, so it enqueued nothing for ~1 h until
+  the audience was set to T at ~5:39 pm. Result: a batch of opportunities created in that window never
+  enqueued (no queue row, no worker2 job) and silently missed the Forecast import — diagnosed by the
+  enqueuer's `scriptnote` AUDIT log going quiet and the missing opps having zero log entries. When opps go
+  missing, **check the enqueuer deployment's Status AND Audience (All Roles/All Employees = T)**, not just
+  "is it Released." Backfill the gap window with `trueup_opportunities.php`.
+- **NetSuite SuiteQL renders timestamps in TWO different zones — do not compare them naïvely.** Stored
+  datetime fields (a custom record's `created`, transaction dates, `systemnote.date`) and the NetSuite UI
+  render in the **account/user TZ (Eastern here)**, but **`SYSDATE` and `scriptnote.date` render in
+  server/Pacific (UTC−7)**. Meanwhile webhook payload timestamps are UTC (`...Z`) and `WorkerJobs` is CDT
+  (UTC−5). Mixing these silently produces hours-off conclusions (it sent us down a wrong "out-of-order /
+  empty-record" path for a while). Anchor every comparison to UTC, and verify the zone of each source with a
+  known same-event cross-reference (e.g. a `scriptnote` AUDIT entry's internalId ↔ that event's UTC webhook
+  payload ↔ its `WorkerJobs.dtCreated`) before trusting a delta.
 - **worker2 routes EVERY request to `_Controller_Index::worker()`** — `worker2/_.php` sets
   `DEFAULT_CONTROLLER_METHOD = ['_Controller_Index','worker']`, which short-circuits `_Route`'s
   URI matching. There is no per-URL routing, and `.htaccess` denies direct `.php` files, so you
@@ -277,6 +306,14 @@ 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-18 — **Diagnosed the live opportunity-import gap as a deployment misconfig + characterized the
+  AMQ burst behavior.** The Opportunity `ue_amq_enqueue` deployment was `Released` but with an **empty
+  audience** (~4:41–5:39 pm) so it enqueued nothing; missing opps had no queue row and no worker2 job
+  (enqueuer `scriptnote` log went silent). Also recorded: under bursts the on-demand kick drops with
+  `NO_DEPLOYMENTS_AVAILABLE` (widened to 1 Scheduled + ≥4 Not Scheduled `ss_amq_drain` slots; cron is the
+  redundancy backstop but its 15-min floor is not an acceptable normal path); **SuiteScript has no
+  `sleep`/`setTimeout`** so settle delays must live on the worker2 read side; and the **SuiteQL mixed-TZ
+  rendering** trap (stored fields = account/Eastern; `SYSDATE`/`scriptnote` = server/Pacific). (dfranks)
 - 2026-06-18 — **Verified live in production** (no code change): real NetSuite SuiteScript webhooks
   (`user-agent: NetSuite/2026.1`) arrive at `webhook.togahub.com/netsuite` and process successfully
   (e.g. opp 6926224 PUT). Clarified that **`UPDATE_CLICKUP = false` is an intentional one-way guard**

package/package.json

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