toga-ai 1.0.733 → 1.0.735

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

@@ -6,8 +6,8 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-29
-owners: ["dfranks", "jcardinal", "kyalamarthi"]
+updated: 2026-09-02
+owners: ["dfranks", "jcardinal", "kyalamarthi", "ajean"]
 files:
   - library/app/api/netsuite/rest.php
   - library/ssl/netsuite_ec_key.pem
@@ -325,7 +325,7 @@ field changed, **including sublist LINE edits that fire no User Event and theref
 
 | NS internalId | Script id | Description |
 |---------------|-----------|-------------|
-| 3149 | `CUSTBODY_END_CUSTOMER` | End Customer (on transaction) |
+| 3149 | `CUSTBODY_END_CUSTOMER` | End Customer (on transaction) — **List/Record** (a customer ref); raw SuiteQL needs `BUILTIN.DF`, while the **REST record** returns `{id, refName}` under the **lower-cased** key `custbody_end_customer` |
 | 7097 | `CUSTBODY_STOCKING_ORDER` | Stocking Order flag |
 | 4968 | `custentity10` | Consolidated Customer (on customer record) — List/Record; needs `BUILTIN.DF` |
 | 10719 | `custentity_account_type` | Account Type (on customer record) — List/Record; needs `BUILTIN.DF` |
@@ -454,6 +454,10 @@ numbers. Budget hours for multi-year runs and launch them under `nohup`/`tmux`.
 
 ## Change history
 
+- 2026-09-02 — Noted the shape of `custbody_end_customer` (internalId **3149**) now that worker2 reads
+  it: it is a **List/Record** customer reference, so SuiteQL needs `BUILTIN.DF` while the REST record
+  hands back `{id, refName}` — and the payload uses the **lower-cased** script id, not the uppercase
+  form this table listed, so a reader should try both casings. (ajean)
 - 2026-08-29 — Corrected `fetchInvoiceFile` (deploy/verify session): it is **RESTlet-based**, not a
   REST record GET — `GET /record/v1/file/{id}` 404s (`file` record not in this account's REST Record
   Service), SuiteQL `file` is metadata-only, `media.nl` isn't OAuth-fetchable, so a SuiteScript 2.1

package/knowledge/1.0/apps/tools/INDEX.md

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/.ebextensions/020_setup_git_libraries.config, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/assets/img/favicon/favicon.ico, tools/assets/img/favicon/favicon-32x32.png, tools/assets/img/favicon/favicon-16x16.png, tools/assets/img/favicon/apple-touch-icon.png, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md, tools/assets/css/theme.css, tools/assets/js/theme.js |
+| [/clickup/aliases — ClickUp Label-Alias Admin (Tools → 2.0 Team schema)](features/clickup-label-aliases-admin.md) | The human side of the NetSuite→ClickUp **Stakeholders / End Customer** labels. | tools/mvc/clickup/aliases/get.php, tools/mvc/clickup/aliases/post.php, tools/_/app/clickup/aliases.php, tools/_/app/nav.php |
 | [Developer Dashboard (ClickUp Sprint, tools /developer)](features/clickup-sprint-dashboard.md) | A native **ClickUp sprint dashboard** in the 1.0 `tools` app at route `/developer` (the **"Developer Dashboard"**, renamed from `/clickup/react` / "Clickup" — s | tools/_/app/clickup/sprint.php, tools/v2/sprints/tile/index.php, tools/v2/sprints/current/index.php, tools/v2/sprints/status-breakdown/index.php, tools/v2/sprints/worktype-breakdown/index.php, tools/v2/sprints/points-by-dev/index.php, tools/v2/sprints/burndown/index.php, tools/assets/clickup/sprint-dashboard.html, tools/mvc/developer/get.php, tools/mvc/login/get.php, tools/_/app/nav.php |
 | [CloudFront Client Setup](features/cloudfront-client-setup.md) | An SSO-gated admin tool at **`/devops/cloudfront-clients`** in the Tools 1.0 app that onboards a client onto **CloudFront + Route 53 across multiple AWS account | tools/_/app/devops/cloudfront.php, tools/mvc/devops/cloudfront-clients/get.php, tools/mvc/devops/cloudfront-clients/post.php, tools/assets/js/cloudfront-clients.js, tools/assets/css/cloudfront-clients.css, tools/_/app/nav.php, tools/_/app/frameworkindex.php, tools/config.production.ini |
 | [Design Demo Admin](features/design-demo-admin.md) | A self-serve admin UI at **`/design`** in the SSO-protected **Tools** app that lets the design team publish self-contained "Claude Design" HTML exports as **ver | tools/_/app/design/github.php, tools/mvc/design/get.php, tools/mvc/design/post.php, tools/assets/css/design.css, tools/assets/js/design.js, tools/_/app/frameworkindex.php, tools/_/app/nav.php, tools/composer.json |

package/knowledge/1.0/apps/tools/features/clickup-label-aliases-admin.md

@@ -0,0 +1,106 @@
+---
+title: /clickup/aliases — ClickUp Label-Alias Admin (Tools → 2.0 Team schema)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-09-02
+owners: ["ajean"]
+files:
+  - tools/mvc/clickup/aliases/get.php
+  - tools/mvc/clickup/aliases/post.php
+  - tools/_/app/clickup/aliases.php
+  - tools/_/app/nav.php
+related:
+  - ./mvc-data-access-patterns.md
+  - ./errors-curation-console.md
+  - ./persona-gated-navigation.md
+  - ../../../2.0/apps/worker2/features/netsuite-opportunity-client-labels.md
+---
+
+## Summary
+
+The human side of the NetSuite→ClickUp **Stakeholders / End Customer** labels. worker2 inserts a row
+in `Team.ClickUpLabelAliases` with `clickupOptionId` NULL for every company name it could not resolve
+to a ClickUp label option; this page is where a person points that name at an existing option (or
+clears one back to unresolved).
+
+`Team.ClickUpLabelAliases` is **both the alias store and the work queue** — one table, two jobs. The
+page splits the backlog accordingly: *Needs an alias* (the option probably already exists under
+another spelling) and *Resolved* (editable, and clearable).
+
+Derivation, matching, and how an alias is used live in the worker2 doc:
+[ClickUp Opportunity Client vs End-Customer Labels](../../../2.0/apps/worker2/features/netsuite-opportunity-client-labels.md).
+
+## Key files / entry points
+
+- `tools/mvc/clickup/aliases/get.php` — the page (route `/clickup/aliases`).
+- `tools/mvc/clickup/aliases/post.php` — the save; redirect-after-POST, no JavaScript.
+- `tools/_/app/clickup/aliases.php` — `App_Clickup_Aliases`: `options()`, `optionsUpdatedAt()`,
+  `all()`, `setOption()`. Connection alias `db_team` (config section `[database_team]`), tables
+  `ClickUpLabelAliases` + `ClickUpLabelOptions`.
+- `tools/_/app/nav.php` — listed under **Developers** next to `/errors`, personas
+  `Development Team` / `TOGa Technology`.
+
+Field ids are constants on the class: Stakeholders `ec15edfd-5920-4c12-a1dc-94ede4a62438`,
+End Customer `67bb359f-fa59-40e1-b94a-0076450bb7c0`. **The two fields are separate option-id spaces.**
+
+## How it works
+
+- **The dropdowns read worker2's MIRROR, not ClickUp.** Tools deliberately holds **no ClickUp
+  credential**: every ClickUp token on the platform authenticates as an individual person, so a copy
+  here would embed someone's identity in a third place. worker2 already needs a token and already
+  fetches the option lists for its own matching, so it republishes them into
+  `Team.ClickUpLabelOptions` on every digest and backfill run.
+- **Queue order comes from SQL, not PHP** — `all()` has **no `WHERE`** and orders
+  `(clickupOptionId IS NOT NULL) ASC, opportunityCount DESC, sourceName ASC`, so unresolved rows sort
+  to the top, highest-impact first, and the page renders in queue order without re-sorting.
+- **Hand-written SQL through `App_Database`, matching `/errors`** — a 1.0 app reading a 2.0 shared
+  schema, so none of the 2.0 model protections apply and every interpolated value is escaped or cast
+  at the call site. See [mvc-data-access-patterns](./mvc-data-access-patterns.md).
+- **The option list is the save allowlist.** `post.php` reads `options()` once and validates the
+  submitted uuid against it. Escaping alone would stop injection but would happily store a uuid that
+  is not a real option — which the sync then reports as `alias_stale` forever.
+- **A row's FIELD comes from the database, never from the request** — otherwise a caller could attach
+  a Stakeholders option id to an End Customer row, storing an id that does not exist on that field.
+- **Clearing is always allowed** (retires the alias, returns the name to the queue); a **submitted id
+  that is not in the allowlist is skipped, not written** — which covers both tampering and the stale
+  option case (the page keeps flagging it instead of silently wiping the value).
+- **Auth + CSRF are explicit:** both files call
+  `App_Auth::requireAuth(['TOGa Technology', 'Development Team'])`, and `post.php` additionally calls
+  `App_Page::validateCrossSiteRequestForgery()` — a non-GET request never reaches
+  `App_FrameworkIndex_Tools::actionHandler()`, so **the framework does not validate CSRF for POSTs**.
+- Storage holds **plain text**; escaping happens exactly once at display. Escaping on the way in
+  would accumulate entities and break equality against the NetSuite name.
+
+## Gotchas / known issues
+
+- **⚠ An option you just created in ClickUp is INVISIBLE here until worker2 republishes the mirror.**
+  The dropdowns are as fresh as the last worker2 run. **Fix: run any digest — it refreshes the mirror
+  in ~2 seconds, and `dryRun` works too**, because on the digest `$dryRun` means "do not send the
+  email", *not* "do not write". This was exactly the confusion after adding 19 new options.
+- **While the mirror is EMPTY, saving is disabled entirely** (the queue still renders). That is a
+  distinct state from a failure, and the notice says so: it fills in on the next worker2 digest or
+  backfill run. `optionsUpdatedAt()` shows the freshness date on the page.
+- **A name with no plausible option cannot be fixed here.** ClickUp's public API cannot create a
+  `labels` option, so someone has to add it in the ClickUp UI first. Those rows still list, ordered by
+  impact.
+- **`?saved=0` is a real outcome, not a no-op** — somebody pressed Save without changing a dropdown,
+  or every change was rejected by the allowlist. `get.php` distinguishes "not a save" from "a save
+  that changed nothing" via `isset($_GET['saved'])`.
+- **`buildArrayOfRows()` takes its argument by reference** — assign the query result to a variable
+  first. Passing `App_Database::query(...)` inline raises *"Only variables should be passed by
+  reference"*, which the `E_ALL` handler promotes to a fatal 500.
+- **An alias outranks exact AND fuzzy matching in worker2, and seed-if-empty makes a wrong one
+  sticky** — a mis-picked option **will** be written to tasks and no later run corrects it. Audit
+  before saving; see the worker2 doc's gotchas.
+
+## Change history
+- 2026-09-02 — Documented the page (built 2026-08-27, previously uncaptured), and specifically **why
+  the dropdown can look stale**: it reads `Team.ClickUpLabelOptions`, worker2's mirror, because Tools
+  holds no ClickUp credential — so newly created options only appear after the next digest/backfill
+  run, and saving is disabled while the mirror is empty. Also recorded the SQL-side queue ordering,
+  the option-list-as-allowlist save rule, field-from-DB-not-request, and the explicit CSRF call POSTs
+  need. (ajean)

package/knowledge/2.0/apps/toga-blox/workflows/dynamic-publish-pipeline.md

@@ -6,8 +6,8 @@ project: TOGa Blox
 client: shared
 type: workflow
 status: active
-updated: 2026-08-31
-owners: [jcardinal, apeterson]
+updated: 2026-09-02
+owners: [jcardinal, apeterson, tcox]
 files:
   - toga-blox/.github/workflows/publish.yml
   - toga-blox/package.json
@@ -86,12 +86,13 @@ environment needs its own maintained `_<mode>` branch in `toga-blox-npm`.
 ## Gotchas
 
 - **⚠ There is a STALE UNDERSCORED dist-tag on the registry — `_sandbox-client` (with the
-  underscore) is NOT the channel.** Verified 2026-08-31, the registry carries **both**
-  `_sandbox-client` = `1.0.316-sandbox-client.1` (vestigial, predates the current pipeline) **and**
-  `sandbox-client` = `1.1.1-sandbox-client.140` (the live channel head). Branch `_<mode>` maps to
+  underscore) is NOT the channel.** Re-verified 2026-09-02, the registry still carries **both**
+  `_sandbox-client` = `1.0.316-sandbox-client.1` (vestigial, predates the current pipeline; it has
+  **not** moved in over a month) **and** `sandbox-client` = `1.1.2-sandbox-client.142` (the live
+  channel head). Branch `_<mode>` maps to
   channel `<mode>` with the underscore **stripped** (same convention as `amplify.yml`), so the
   **branch** `_sandbox-client` tracks the **tag** `sandbox-client`. Asking npm for "the latest
-  `_sandbox-client` tag" literally installs something **139 publishes behind**. Always resolve the
+  `_sandbox-client` tag" literally installs something **141 publishes behind**. Always resolve the
   head with `npm view @agilant/toga-blox dist-tags` and install the underscore-less name.
 - **Publish before build.** `npm install @agilant/toga-blox@<mode>` fails `ETARGET No matching
   version` in the app build until this repo has published that channel. GitHub Actions runs the
@@ -131,8 +132,19 @@ environment needs its own maintained `_<mode>` branch in `toga-blox-npm`.
   was then made **on `_sandbox-client`**, at the developer's explicit direction. That **deviates
   from the `deploy-sandbox-client` skill's "never commit the bump directly to `_sandbox-client`"
   rule.** It was safe *only* because the feature branch does not carry the version line, so nothing
-  could be clobbered — **record this as a one-off, not a new default.** CI then published base+1 →
-  `1.0.334-sandbox-client.136`.
+  could be clobbered. CI then published base+1 → `1.0.334-sandbox-client.136`.
+- **Bumping the base directly on `_sandbox-client` is the ACTUAL practice — it is safe under three
+  preconditions, and it is no longer a one-off.** Second occurrence 2026-09-02 (`1.1.0` → `1.1.1`,
+  commit `543a7186`, published `1.1.2-sandbox-client.142`), same shape as 2026-08-26. Stop treating
+  the skill's "never bump on `_sandbox-client`" line as absolute; treat it as conditional. The bump
+  on the release branch is fine when **all three** hold:
+  1. The working tree is **clean**.
+  2. The branch is **in sync with `origin`** (nothing unpushed, nothing to pull).
+  3. No feature branch pending merge **touches the `version` line** — which is normally true,
+     because feature branches never edit it (see the gotcha above).
+  If any one fails, bump on the feature branch instead. Note the bump commit lands *only* on
+  `_sandbox-client` and is never merged back, which is precisely what generates the "N behind"
+  release plumbing described two gotchas up.
 - **`gh` is not installed on every dev machine.** The skill's `gh run watch` monitoring step simply
   does not work there. Fall back to polling the registry:
   `npm view @agilant/toga-blox@sandbox-client version` (or `npm dist-tag ls @agilant/toga-blox`)
@@ -200,6 +212,17 @@ environment needs its own maintained `_<mode>` branch in `toga-blox-npm`.
   you push to a release branch.
 
 ## Change history
+- 2026-09-02 — Released `1.1.2-sandbox-client.142` (base `1.1.0` → `1.1.1` on `_sandbox-client`,
+  commit `543a7186`) and rolled it into `toga25-supply` (pin `1.1.1-sandbox-client.140` →
+  `1.1.2-sandbox-client.142`, clean `npm install`, `tsc --noEmit` zero errors). The documented
+  workflow was accurate end-to-end — no new gotchas. **Promoted the on-branch version bump from a
+  "one-off deviation" to the actual practice with three stated preconditions** (clean tree, in sync
+  with origin, no pending merge touching the `version` line); this was its second occurrence under
+  identical conditions. Refreshed the live `sandbox-client` head in the stale-dist-tag gotcha
+  (`.140` → `.142`); the vestigial `_sandbox-client` tag is unmoved at `1.0.316-sandbox-client.1`.
+  Confirmed the registry-polling fallback (`npm view @agilant/toga-blox@sandbox-client version`)
+  is the working verification path where `gh` is absent, and that publish lands ~2 min after the
+  push. (tcox)
 - 2026-08-31 — Recorded the **stale underscored dist-tag trap**: the registry carries both
   `_sandbox-client` (`1.0.316-sandbox-client.1`, vestigial) and `sandbox-client`
   (`1.1.1-sandbox-client.140`, live head). Installing the underscored name silently pins 139

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

@@ -27,11 +27,11 @@
 | [Etilize Item Translation Import](features/etilize-item-translation-import.md) | The abstract worker class `_Worker_Etilize_ItemTranslations` imports **non-English** item text from Etilize into the client's `ItemTranslations` table. | worker2/Worker/Etilize/ItemTranslations.php |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Monitors/RateEntitlement.php, worker2/Worker/Notification/Email.php, worker2/Worker/Rate.php, dbchanges2/Core/2026-05-21 - Monitors.sql, dbchanges2/Core/2026-06-29a - Rate Entitlement Contract Monitor.sql |
 | [NetSuite Integrations Monitor (Monitor/Operations/NetsuiteIntegrations)](features/netsuite-integrations-monitor.md) | `_Worker_Monitor_Operations::NetsuiteIntegrations()` is a cross-client health check that detects **stuck NetSuite ↔ 2.0 integrations**. | worker2/Worker/Monitor/Operations.php, dbchanges2/Core/2026-08-10a - Netsuite Integrations Monitor.sql, _underscore/Database.php, _underscore/Query.php |
-| [ClickUp Opportunity Client vs End-Customer Labels (Stakeholders / End Customer)](features/netsuite-opportunity-client-labels.md) | The NetSuite→ClickUp opportunity task carries **two** customer labels, not one (TRUE-81010, PR #142): - **Stakeholders** = the **client** — the consolidated par | worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/OpportunityStakeholderDigest.php, worker2/Worker/Netsuite/OpportunityStakeholderBackfill.php |
+| [ClickUp Opportunity Client vs End-Customer Labels (Stakeholders / End Customer)](features/netsuite-opportunity-client-labels.md) | The NetSuite→ClickUp opportunity task carries **two** customer labels, not one (TRUE-81010, PR #142): - **Stakeholders** = the **client** — the consolidated par | worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/OpportunityStakeholderDigest.php, worker2/Worker/Netsuite/OpportunityStakeholderBackfill.php, worker2/Worker/Netsuite/OpportunityEndCustomerBackfill.php, dbchanges2/Forecast/2026-09-01a - Add endCustomerName to Opportunities.sql, tools/mvc/clickup/aliases/get.php, tools/mvc/clickup/aliases/post.php, tools/_/app/clickup/aliases.php |
 | [NetSuite ↔ ClickUp / TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Clickup.php, worker2/Worker/Clickup/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, test/@dave/test_model_load_behavior.php, dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql, _underscore/Model/Forecast/Opportunity.php, test/@dave/approach/TRUE-80044.md, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, worker2/Component/Forecast/Db/Db.php, worker2/Worker/Netsuite/Location.php, worker2/Worker/Netsuite/OpenOrderLocationBackfill.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_amq_invoice_resync_salesorder.js, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.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_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, test/@dave/probe_ooi_location_gap.php, library/app/api/netsuite/rest.php, dbchanges2/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql |
 | [Toga → NetSuite Sales-Order Push (multi-client, mapping-driven worker)](features/netsuite-salesorder-outbound-push.md) | The **outbound** half of `worker2/Worker/Netsuite/SalesOrder.php` (everything from the `OUTBOUND PUSH (REST)` banner down) pushes a Toga sales order **into** Ne | worker2/Worker/Netsuite/SalesOrder.php, test/@Bala/tests/netsuite_salesorder_payload_tests.php, worker/crons/toga2/prudential/transmissions_to_netsuite.php |
-| [NetSuite Supporting-Record Backfill Worker (bulk reconciliation recipe)](features/netsuite-supporting-record-backfill-worker.md) | The **bulk counterpart** to the [supporting-record webhook importer](./netsuite-supporting-record-webhook-importer.md). | worker2/Worker/Netsuite/CustomerAccountTypeBackfill.php, worker2/Worker/Netsuite/ItemFulfillableBackfill.php, worker2/Worker/Netsuite/Customer.php, library/app/model/forecast2/customer.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
+| [NetSuite Supporting-Record Backfill Worker (bulk reconciliation recipe)](features/netsuite-supporting-record-backfill-worker.md) | The **bulk counterpart** to the [supporting-record webhook importer](./netsuite-supporting-record-webhook-importer.md). | worker2/Worker/Netsuite/CustomerAccountTypeBackfill.php, worker2/Worker/Netsuite/ItemFulfillableBackfill.php, worker2/Worker/Netsuite/OpportunityEndCustomerBackfill.php, worker2/Worker/Netsuite/Customer.php, library/app/model/forecast2/customer.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite Supporting-Record Webhook Importer (the reusable recipe)](features/netsuite-supporting-record-webhook-importer.md) | A single **repeatable recipe** for porting a legacy daily-pull NetSuite *supporting-record* importer (the lookup/dimension tables behind Forecast2 — Employees, | worker2/Worker/Netsuite/Employee.php, worker2/Worker/Netsuite/Account.php, worker2/Worker/Netsuite/Classification.php, worker2/Worker/Netsuite/Customer.php, worker2/Worker/Netsuite/Item.php, worker2/Worker/Netsuite.php, _underscore/Model/Forecast/Employee.php, _underscore/Model/Forecast/Account.php, _underscore/Model/Forecast/Classification.php, _underscore/Component/Forecast/Db/Db.php, test/@dave/test_employee_lifecycle.php, test/@dave/test_account_lifecycle.php, test/@dave/test_classification_lifecycle.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, worker/crons/toga2/forecast2/import_supporting_records.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker2/Worker/Netsuite/CustomerAccountTypeBackfill.php, library/app/api/netsuite/rest.php, library/app/model/forecast2/customer.php |
 | [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, _underscore/Model/Client/EmailTemplate.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-02
 owners: [jcardinal, dfranks, mhammontree, tcox, bala, ajean]
 files:
   - worker2/Worker/
@@ -423,6 +423,27 @@ Rules: rename **both sides in one PR and one deploy**; grep every repo for the o
 - **A new action does not run on a schedule until a `Core.CronJobs` row exists.** The schedule
   registry is **data, not code** — shipping the PHP file changes nothing on its own. Ship the code
   deploy and the `dbchanges2` cron-row migration together (see "Adding a new cron job" above).
+- **⚠ If your code names a column that arrives in a HAND-APPLIED migration, GATE it on the column
+  existing.** dbchanges2 migrations are run by a human, so the deploy can legitimately land first.
+  The damage is not local: a `save()`/`SELECT` naming a missing column fails the **whole** query, so
+  a one-field enhancement can break every webhook the handler serves. (Real case: the
+  `Opportunities.endCustomerName` label field would have taken down the entire NetSuite opportunity
+  sync — see
+  [netsuite-opportunity-client-labels](./netsuite-opportunity-client-labels.md#the-deploy-gate-hasendcustomercolumn--and-why-a-label-feature-needs-one).)
+  **Pattern:** check `information_schema.COLUMNS`, memoise the answer in a **`static`** (not a
+  constant — a long-lived worker then picks the column up on its next job; it cannot change
+  mid-job), `error_log` **once** when it is missing so a silently inert feature does not go unnoticed
+  for weeks, and apply the gate at **every** site that names the column — writes *and* reads.
+  Proven in `Worker/Netsuite/ItemFulfillableBackfill.php::doesClientColumnExist` and
+  `Worker/Sync/ServiceRequest.php`.
+- **Type-CHECK a value that came out of `json_decode`; do not `(string)`-cast it.** For an optional
+  field, `trim((string) ($payload->{$key}->name ?? ''))` fails two ways: a nested **array** casts to
+  the literal string `"Array"`, which passes a non-empty test and is then used as real data; a nested
+  **object** without `__toString` is a **fatal `Error`** that kills the job over an optional field.
+  Treat "not a string" as "not set" (`is_string()` first, return `null` otherwise) so a wrong guess
+  about the payload shape **degrades** instead of breaking. Verified on PHP 8.5: `null`, arrays and
+  objects all `TypeError` against a userland `string` parameter, while **ints coerce silently** — so
+  a wrong-typed number fails later, not at the boundary.
 - **For a code path gated behind a RARE condition, build a dry-run entry point and fire it
   deliberately — do not wait for the path to fire naturally.** A dry run enqueued against production
   found a fatal bug in ~2 seconds that two weeks of green telemetry had not: the path was reached
@@ -435,6 +456,12 @@ Rules: rename **both sides in one PR and one deploy**; grep every repo for the o
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-09-02 — Added two authoring rules learned on the End Customer label work (worker2 PR #158/#159):
+  **gate any code that names a column from a hand-applied dbchanges2 migration** on an
+  `information_schema.COLUMNS` check memoised in a `static` (an ungated write fails the whole query
+  and can take down every webhook the handler serves, not just the new field), and **type-check
+  JSON-decoded values instead of `(string)`-casting them** (a nested array becomes the literal
+  `"Array"`; a nested object is a fatal `Error`). (ajean)
 - 2026-08-31 — Documented that **the real time budget for any hand-triggered action is 300s and
   cannot be raised**: the JobScheduler watchdog only honours `CronJobs.maxExecutionTime` through
   `LEFT JOIN … ON wj.cronJobId = cj.id`, and `cronJobId` is NULL for every webhook / `runTask` /

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

@@ -6,16 +6,24 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-02
 owners: ["ajean"]
 files:
   - worker2/Worker/Netsuite/Opportunity.php
   - worker2/Worker/Netsuite/OpportunityStakeholderDigest.php
   - worker2/Worker/Netsuite/OpportunityStakeholderBackfill.php
+  - worker2/Worker/Netsuite/OpportunityEndCustomerBackfill.php
+  - "dbchanges2/Forecast/2026-09-01a - Add endCustomerName to Opportunities.sql"
+  - tools/mvc/clickup/aliases/get.php
+  - tools/mvc/clickup/aliases/post.php
+  - tools/_/app/clickup/aliases.php
 related:
   - ./netsuite-opportunity-sync.md
   - ./creating-worker-actions.md
   - ./notification-email.md
+  - ./netsuite-supporting-record-backfill-worker.md
+  - ../../../../1.0/apps/tools/features/clickup-label-aliases-admin.md
+  - ../../../../1.0/apps/library/features/netsuite-suiteql-api-reference.md
 ---
 
 ## Summary
@@ -23,8 +31,14 @@ related:
 The NetSuite→ClickUp opportunity task carries **two** customer labels, not one (TRUE-81010, PR #142):
 
 - **Stakeholders** = the **client** — the consolidated parent company we contract with.
-- **End Customer** = the NetSuite opportunity `entity` — the specific (often sub-)customer the work
-  is for.
+- **End Customer** = NetSuite's **`custbody_end_customer`** field (NS internalId 3149) when it is
+  populated; otherwise it **mirrors the client** (PR #158 + PR #159, 2026-09-01).
+
+> **End Customer was originally derived from the opportunity `entity`. That could never be right for
+> a partner-routed deal** — when we sell *through* a partner, the `entity` **is** the partner.
+> Opportunity 75717 sits on entity `"Staples, Inc."`, so both labels read "Staples" while the real
+> end customer (Legacy Health Services) existed only in the free-text `title`. Only NetSuite knows
+> the end customer, and it has carried it all along in `custbody_end_customer` — nothing read it.
 
 Before this change the sync pushed `entity->refName` into **Stakeholders**, flattening the two
 levels of the NetSuite customer hierarchy into one field. Verified against production that `entity`
@@ -43,6 +57,12 @@ and a **seed-if-empty backfill** for the 761 tasks that already exist.
   `Netsuite/OpportunityStakeholderDigest/Daily` (`dryRun=false`, `to=null`).
 - `worker2/Worker/Netsuite/OpportunityStakeholderBackfill.php` — action
   `Netsuite/OpportunityStakeholderBackfill/Backfill` (`dryRun=true`, `taskId=null`, `exactOnly=true`).
+- `worker2/Worker/Netsuite/OpportunityEndCustomerBackfill.php` — action
+  `Netsuite/OpportunityEndCustomerBackfill/Backfill` (`dryRun=true`, `onlyMissing=true`); the
+  re-import pass that fills the new `endCustomerName` column.
+- `dbchanges2/Forecast/2026-09-01a - Add endCustomerName to Opportunities.sql` — the column.
+- `tools/mvc/clickup/aliases/` + `tools/_/app/clickup/aliases.php` — the human alias queue; see
+  [Tools ClickUp label-alias admin](../../../../1.0/apps/tools/features/clickup-label-aliases-admin.md).
 
 **ClickUp field ids** on list `901111987449` (Presales Qualification), both `labels` type with ~169
 options each: `Stakeholders` = `ec15edfd-5920-4c12-a1dc-94ede4a62438`,
@@ -58,20 +78,102 @@ So the client is resolved through Forecast:
 Opportunities.customerId → Customers.consolidatedCustomerId → ConsolidatedCustomers.name
 ```
 
-`deriveLabelNames()` then applies three rules, each sized against production data:
+`deriveLabelNames()` then applies these rules, each sized against production data:
+
+1. **Stakeholders: no consolidated parent → the entity IS the client.** 186 of 759 task-bearing
+   opportunities (24.5%) have no parent. Stakeholders then receives exactly what it received before
+   the split, so the swap was not a regression for them. (25 distinct entity/parent pairs are
+   genuinely different — 83 of 573 parented opportunities — which is the case the split exists for.)
+2. **End Customer: `Opportunities.endCustomerName` when set, else mirror the client.** Both fields
+   carry the same value rather than one being left blank — which makes an **empty field an
+   unambiguous signal that resolution FAILED**, and nothing else.
+
+Net effect measured on production when the split shipped: Stakeholders exact-match rose from
+**31.5% to 36.4%** (47.0% including fuzzy).
+
+### Where End Customer comes from (2026-09-01 — this is the current rule)
+
+**Decision: NetSuite `custbody_end_customer`, else mirror the client.** The alternative considered
+was falling back to the `entity`. Mirroring won because neither label is ever blank either way, and
+mirroring stops End Customer repeating near-duplicate spellings of the client.
+
+**Accepted cost, recorded in the method comment so nobody later "fixes" it as a bug:** where the
+entity is a *genuine* subsidiary, that detail is no longer surfaced. `"Office Depot"` /
+`"ODP Veyer (B2B)"` (19 opportunities) and `"CDW"` / `"CDW_Northwell"` (5) now read as the parent on
+both labels unless NetSuite names an end customer. The old **equal-names collapse** (force End
+Customer = client when the two normalize equal) was deleted with this change — mirroring is now the
+default, so the collapse had nothing left to do.
+
+Why the entity could never stand in for the end customer, in numbers: of 771 task-bearing
+opportunities, **599 (78%) had End Customer identical to Stakeholders by construction**, and most of
+the 172 that differed were near-duplicate spellings of one company (`"Masonite"` vs
+`"Masonite Holding, Inc."`) rather than real distinctions. `Forecast.Opportunities` has exactly one
+customer link and had **no** end-customer column — a `%endcustomer%` column search across every
+production schema returned zero.
+
+**Reading the field.** `custbody_end_customer` is a **List/Record** field (a customer reference with
+a customer number), so on the **REST record** it arrives as `{id, refName}` like
+`custbody_sales_stage` — *not* a bare string, and no `BUILTIN.DF` is needed on the REST path (a
+**SuiteQL** reader of the same field would need it — see
+[SuiteQL/REST reference](../../../../1.0/apps/library/features/netsuite-suiteql-api-reference.md)).
+`readEndCustomerRefName()` tries **both key casings** (our own reference documents it as
+`CUSTBODY_END_CUSTOMER`, while the REST payload lower-cases its siblings); a miss returns `null`, so
+a wrong guess degrades to the pre-existing mirror behaviour instead of breaking the label.
+
+**Stored as the NAME, not a FK to `Customers`.** The `entity` is resolved with
+`lookupId(…netsuiteInternalId)`, which returns NULL on a miss, and — unlike the entity — **nothing
+upserts an end-customer row**. A FK would therefore be NULL exactly when the field *is* populated
+but that customer has not synced yet. The label only needs the name, and the payload always carries
+`refName`.
+
+`importOpportunity()` reads it and threads it through `deriveLabelNames()` to all three call sites:
+the create path, the backfill and the digest.
+
+**The field is sparse and not uniformly a company name.** Only **30 of 776** task-bearing
+opportunities carry it (3.9%). The rate rises with recency — 1.6% over the oldest 188, ~4–6%
+mid-range, **20% over the newest 10** — consistent with recent adoption, so an early-chunk
+extrapolation *understates* it. Content: 11 clean company names, 17 sub-customer paths, and 2 values
+that are not companies at all (`"Epic Training Support and Imprivata Enrollment Supervision/Support
+Wave 3"`, `"NW SOW -Under $25k"`). Plan for the field to keep collecting that.
+
+### The deploy gate (`hasEndCustomerColumn()`) — and why a label feature needs one
+
+`endCustomerName` arrives in a **dbchanges2 migration a human applies by hand**, so worker2 can
+legitimately be running before the column lands. An **ungated write does not degrade the label — it
+breaks the ENTIRE opportunity sync**, because `importOpportunity()`'s save names a column that does
+not exist and *every* NetSuite webhook fails. A label enhancement must not be able to do that.
 
-1. **No consolidated parent → the entity IS the client.** 186 of 759 task-bearing opportunities
-   (24.5%) have no parent. Stakeholders then receives exactly what it received before the change,
-   so the swap is not a regression for them.
-2. **Mirror when equal.** For 678 of 761 the parent is the same company as the entity
-   (`"4679 Staples, Inc."` → `"Staples, Inc."`). Both fields carry the same value rather than one
-   being left blank — which makes an **empty field an unambiguous signal that resolution FAILED**,
-   and nothing else.
-3. **Genuinely different parent** in only 83 of 573 parented opportunities (14.5%, 25 distinct
-   pairs) — the case the split exists for.
+- `information_schema.COLUMNS` check, **memoised per process** in a `static` (the answer cannot
+  change mid-job, and the import runs per webhook) — `static`, not a constant, so a long-lived
+  worker picks the column up on its next job.
+- `error_log`s **once** when the column is missing, because a silently inert feature goes unnoticed
+  for weeks.
+- Applied at **three** sites: the import write, plus the backfill and digest `SELECT`s — which would
+  otherwise fail the whole query with *Unknown column* rather than omit one field.
+- Precedent already in the repo: `Worker/Netsuite/ItemFulfillableBackfill.php::doesClientColumnExist`
+  and `Worker/Sync/ServiceRequest.php`. See
+  [creating-worker-actions](./creating-worker-actions.md#gotchas).
 
-Net effect measured on production: Stakeholders exact-match rose from **31.5% to 36.4%** (47.0%
-including fuzzy).
+### End Customer re-import pass (`OpportunityEndCustomerBackfill/Backfill`)
+
+`importOpportunity()` only runs on a **NetSuite webhook**, so an opportunity nobody touches again is
+never re-imported and its new column stays NULL — measured **0 of 776 populated** immediately after
+the migration. This action re-reads every opportunity from NetSuite and fills the column.
+
+- **It writes ONE column; it is not a re-import.** Calling `importOpportunity()` per row is the
+  obvious shortcut and the wrong tool: it rewrites every header column, re-processes line items, and
+  shares the claim/label machinery — so a "fill one field" job would carry the whole sync's blast
+  radius.
+- **Blank/absent in NetSuite is COUNTED, never written.** Leaving NULL is what makes the label mirror
+  the client, and writing `''` would be a value that normalizes to nothing and can never match an
+  option.
+- **`onlyMissing` defaults TRUE**, so re-runs are cheap — measured **4** NetSuite calls instead of 11
+  on a second pass.
+- **Pacing is 200 ms**, deliberately shorter than the ClickUp pacing, because the NetSuite constraint
+  is **concurrency, not requests/minute**, and the job is strictly serial.
+- **Self-chunks using the `OpportunityStakeholderBackfill` pattern verbatim** rather than inventing a
+  second shape — see
+  [creating-worker-actions](./creating-worker-actions.md#self-chunking-the-pattern-for-work-that-cannot-finish-in-one-job).
 
 ### Daily digest (`OpportunityStakeholderDigest/Daily`)
 
@@ -116,6 +218,7 @@ passes:
 | 1 | 2026-08-28 | 11 chunks, 32m | 1,112 | first live pass, 0 failures |
 | 2 | 2026-08-31 | 5 chunks, 15m | 39 | after 21 new ClickUp options; 1,143 already set |
 | 3 | 2026-08-31 | 6 chunks, ~17m | 191 | after 100 more options; unmatched 194 → 2, coverage **89.0%** |
+| 4 | 2026-09-02 | 5 chunks | 26 | after the End Customer re-import; 0 unmatched, 0 fuzzy, coverage **100%** (1,552 of 1,552 slots at 776 opportunities) |
 
 Every pass: **0 failures**, and totals always reconcile to `examined × 2`.
 
@@ -123,7 +226,48 @@ Every pass: **0 failures**, and totals always reconcile to `examined × 2`.
   when write-heavy, because each filled field adds a paced request. Size expectations by mode, not by
   the last run.
 - **Dry run and live agreed EXACTLY on all five counters** (1112 / 29 / 231 / 166 / 0). That equality
-  is a cheap, high-value integrity check — repeat it before every live pass.
+  is a cheap, high-value integrity check — repeat it before every live pass. It has now held on
+  **every** pass across this project, including the End Customer re-import (dry run and live both
+  reporting 30 populated over 776 NetSuite reads, 5 chunks, 0 failures) — keep using it.
+- **End-to-end verification of the case that opened the investigation:** task `868kw9t2v` now reads
+  Stakeholders `"Staples"`, End Customer `"Legacy Health Services"`.
+
+### Operating the queue (things you will need and cannot guess)
+
+**The Tools alias dropdown reads worker2's MIRROR, not live ClickUp.** Options you just created in
+ClickUp are **invisible** on `/clickup/aliases` until worker2 republishes `Team.ClickUpLabelOptions`
+(`publishLabelOptions()`), and **saving is disabled entirely** while the mirror is empty. **Any
+digest run refreshes it in ~2 seconds, including `dryRun`** — on the digest, `$dryRun` means "do not
+send the email", *not* "do not write". This was the fix when 19 newly-added options could not be
+seen. Details in
+[Tools ClickUp label-alias admin](../../../../1.0/apps/tools/features/clickup-label-aliases-admin.md).
+
+**Seed the alias queue by hand with `recordUnresolvedAliases()`.** It is callable directly as a
+worker action, which is how to surface names the digest's fuzzy blind spot hides (see the gotcha
+below — still unfixed):
+
+```json
+{"action":"Netsuite/Opportunity/recordUnresolvedAliases",
+ "parameters":{"rows":[[fieldId, sourceName, opportunityCount]]}}
+```
+
+Its `ON DUPLICATE` refreshes `opportunityCount` and leaves `clickupOptionId` alone, so it is safe to
+re-run and **cannot erase an alias a human assigned**. The field ids are counterintuitive:
+Stakeholders = `ec15edfd-5920-4c12-a1dc-94ede4a62438`, End Customer =
+`67bb359f-fa59-40e1-b94a-0076450bb7c0`.
+
+**Correcting an ALREADY-POPULATED label takes a specific order — and clearing alone is unsafe.**
+Seed-if-empty never overwrites, so a corrected alias changes nothing while a stale value sits in the
+field; and clearing *before* the new derivation is deployed just refills the old value on the next
+run. The working sequence:
+
+1. Apply the dbchanges2 migration.
+2. Deploy worker2.
+3. Run the End Customer re-import (`OpportunityEndCustomerBackfill/Backfill`).
+4. Clear the affected ClickUp fields (27 tasks by hand this round).
+5. Run `OpportunityStakeholderBackfill/Backfill` to re-seed them.
+
+A one-shot rem+add corrector was scoped and deliberately **not** built.
 
 ## Gotchas / known issues
 
@@ -165,6 +309,28 @@ Every pass: **0 failures**, and totals always reconcile to `examined × 2`.
   use this composite form** (1,418 of 9,211) and they are precisely the hierarchical customers this
   feature exists to distinguish. Now `/^(\d+(?::\d+)*)\s+(.*)$/` — still requiring the whitespace so
   `"3M Company"` is not decapitated.
+- **⚠ `splitCustomerRefName()` strips a NUMERIC prefix only — a NAME hierarchy passes through whole,
+  so AN ALIAS MUST BE KEYED ON THE FULL PATH STRING.** NetSuite sub-customers also arrive as a name
+  path, `" : "`-separated — `"ODP Veyer (B2B) : Compass Group"` — not just the numeric
+  `"6096:6308 Compass Group"` the splitter was written for. The name path survives intact, normalizes
+  to `"odp veyer b2b compass group"`, and can **never** match an option. Consequence when you queue
+  an alias: the full path is the needle `resolveLabelOption()` receives, so an alias entered as just
+  `"Compass Group"` **never fires**. **17 of the 30 populated end-customer rows are this shape.**
+- **Type-CHECK a JSON-sourced value; never `(string)`-cast it.** `readEndCustomerRefName()` returns
+  `null` for anything that is not a string, because `trim((string) ($opp->{$key}->refName ?? ''))`
+  is wrong two ways on decoded JSON: a nested **array** casts to the literal `"Array"` (which passes
+  a non-empty test and becomes the label name), and a nested **object** with no `__toString` is a
+  **fatal `Error` that takes down the whole import** for an optional field. General rule and the
+  PHP 8.5 verification are in
+  [creating-worker-actions](./creating-worker-actions.md#gotchas).
+- **`trimDetail()` is already safe to apply repeatedly — do not add an "ends in `...`" guard.**
+  A review asked for an early return on entries already carrying the truncation suffix, to stop
+  repeated shortening across chunks. Measured: applying it 10 times gives byte-identical output after
+  the first pass on both the ASCII and multi-byte paths, because `substr($entry, 0, CARRIED_DETAIL_MAX_CHARS)`
+  recovers exactly the same content bytes and the dots sit beyond the cut. The proposed guard would
+  return an **over-length entry unmodified** whenever it happened to end in `"..."` — which API error
+  text routinely does — defeating the byte cap and breaking the chunk chain, the exact failure the cap
+  exists to prevent. Skipped, with the reasoning posted on the PR.
 - **Option ids ride on `$body`, not on extra positional arguments.** `buildCustomFields()` used to
   take the Stakeholders option id as an optional 3rd argument, but `updateTask()` called it as
   `buildCustomFields($body, $presalesUserId)` — two arguments — so that path could never set the
@@ -182,6 +348,27 @@ Every pass: **0 failures**, and totals always reconcile to `examined × 2`.
   injection before they go into the digest.
 
 ## Change history
+- 2026-09-02 — **End Customer now comes from NetSuite `custbody_end_customer`, else mirrors the
+  client (worker2 PR #158 + dbchanges2 PR #477; re-import PR #159 — all merged).** Root cause: End
+  Customer was derived from the opportunity `entity`, which **is the partner** on a partner-routed
+  deal — opp 75717 read "Staples" on both labels while the real end customer (Legacy Health Services)
+  sat only in `title`; 599 of 771 (78%) were identical to Stakeholders by construction. NetSuite has
+  carried the field all along (NS internalId 3149) and nothing read it; it is List/Record, so REST
+  delivers `{id, refName}` and `readEndCustomerRefName()` tries both key casings. Added
+  `Forecast.Opportunities.endCustomerName` (stored as the **name**, not a FK — nothing upserts an
+  end-customer row), a `hasEndCustomerColumn()` **deploy gate** at three sites (an ungated write
+  breaks the *whole* sync, not just the label), and `Netsuite/OpportunityEndCustomerBackfill/Backfill`
+  (writes one column, never calls `importOpportunity()`; blank counted not written; `onlyMissing`
+  default true; 200 ms pacing because NetSuite limits concurrency, not rate). Deleted the equal-names
+  collapse; **accepted cost:** genuine subsidiaries (ODP Veyer 19, CDW_Northwell 5) now read as the
+  parent on both labels. Recorded that the NetSuite field is sparse (30 of 776, rising with recency)
+  and not always a company; that `splitCustomerRefName()` passes a **name** path through whole so an
+  alias must be keyed on the full `" : "` string (17 of 30 rows); that the Tools alias dropdown reads
+  worker2's option **mirror**, so any digest run — `dryRun` included — is what makes new options
+  visible; the hand-seeding call for the alias queue; and the migrate → deploy → re-import → clear →
+  backfill order needed to correct an already-populated label. Verified end to end: 5 chunks, 0
+  failures over 776 reads, coverage 100% (1,552 slots), task 868kw9t2v now Staples / Legacy Health
+  Services. (ajean)
 - 2026-08-31 — **Made the backfill self-chunking and ran three live passes (PR #157, merged).** The
   action now works 180s and re-enqueues itself with a keyset `resume` cursor, one `WorkerJobs` row per
   chunk labelled CONTINUES/COMPLETE — previously a full pass was declared failed by the 300s watchdog

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-02
 owners: ["dfranks", "kyalamarthi", "ajean"]
 files:
   - worker2/Worker/Netsuite.php
@@ -174,8 +174,11 @@ Shared helpers: `buildCustomFields()` (the field array, used by both create and
   (the customer **name**, deliberately — not the NetSuite customer number). Plus `Sales Rep`,
   `Presales Lead Email`, and `Presales Lead` (users field).
   **Since 2026-08-26 the two customer *labels* fields are a separate subject** — `Stakeholders`
-  carries the **client** (the consolidated parent) and `End Customer` carries the opportunity
-  `entity`. See [ClickUp Opportunity Client vs End-Customer Labels](./netsuite-opportunity-client-labels.md);
+  carries the **client** (the consolidated parent) and `End Customer` carries NetSuite's
+  `custbody_end_customer` (stored as `Opportunities.endCustomerName`), falling back to **mirroring the
+  client** when NetSuite names none (changed 2026-09-01; it used to carry the opportunity `entity`,
+  which is the *partner* on a partner-routed deal). See
+  [ClickUp Opportunity Client vs End-Customer Labels](./netsuite-opportunity-client-labels.md);
   do not re-derive that mapping here.
 - The ClickUp token comes from `[clickup] token` in the worker2 config (legacy webhook received
   it on the payload; the new contract drops it).
@@ -346,6 +349,12 @@ the legacy cron's OPPORTUNITIES section:
   (same as `App_Api_Netsuite_Rest::listOpportunities`) — **not** `entityStatus` (that's the
   sales-stage percent → `percentToCloseStatusId`). The REST record GET doesn't return that
   letter, so the handler runs a one-row SuiteQL query for it.
+- **`endCustomerName`** (added 2026-09-01, `dbchanges2/Forecast/2026-09-01a …`) holds NetSuite
+  `custbody_end_customer`'s `refName` — a **name, not a FK**, because nothing upserts an
+  end-customer `Customers` row. The write and both reads are gated on the column existing
+  (`hasEndCustomerColumn()`), since the migration is applied by hand and an unknown column would fail
+  the whole query and break every opportunity webhook. See
+  [the labels doc](./netsuite-opportunity-client-labels.md).
 - Writes use raw `_Query` against `_underscore::DB_FORECAST` and **must**
   `_Database::transactionCommit(DB_FORECAST)` (lazy-transaction gotcha).
 
@@ -652,6 +661,10 @@ deprecated** for production opportunity code.
   blocked on the Aaron stakeholder decision noted above.
 
 ## Change history
+- 2026-09-02 — `Opportunities.endCustomerName` added to the header write (dbchanges2 PR #477 /
+  worker2 PR #158), gated on the column existing; the **End Customer** label no longer comes from the
+  opportunity `entity`. Derivation stays owned by
+  [netsuite-opportunity-client-labels](./netsuite-opportunity-client-labels.md). (ajean)
 - 2026-08-31 — **Triage knowledge from a read-only "is the opportunity sync dead?" investigation — no
   code changed.** Added a *Triage* section: the `Core.WorkerJobs.output` `clickup` verdict census is
   the fast, NetSuite-free answer, and it has exactly **three** verdicts in practice, with a healthy

package/knowledge/2.0/apps/worker2/features/netsuite-supporting-record-backfill-worker.md

@@ -6,11 +6,12 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
-owners: ["kyalamarthi"]
+updated: 2026-09-02
+owners: ["kyalamarthi", "ajean"]
 files:
   - worker2/Worker/Netsuite/CustomerAccountTypeBackfill.php
   - worker2/Worker/Netsuite/ItemFulfillableBackfill.php
+  - worker2/Worker/Netsuite/OpportunityEndCustomerBackfill.php
   - worker2/Worker/Netsuite/Customer.php
   - library/app/model/forecast2/customer.php
   - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
@@ -28,9 +29,10 @@ The webhook keeps a `Forecast` column current *going forward*, one record at a t
 history, and it never fires for a NetSuite **bulk** change. A backfill worker re-derives one column
 for **every** row from NetSuite in batches, and is the reconciliation path after any mass edit.
 
-Two exist and they share one recipe: `Netsuite/ItemFulfillableBackfill/…` (the original) and
-`Netsuite/CustomerAccountTypeBackfill/Backfill` (TRUE-80206). Treat the recipe as fill-in-the-blanks —
-the interesting decisions are already made.
+Three exist and they share one recipe: `Netsuite/ItemFulfillableBackfill/…` (the original),
+`Netsuite/CustomerAccountTypeBackfill/Backfill` (TRUE-80206) and
+`Netsuite/OpportunityEndCustomerBackfill/Backfill` (2026-09-01, per-record REST reads instead of
+batched SuiteQL). Treat the recipe as fill-in-the-blanks — the interesting decisions are already made.
 
 ## Key files / entry points
 
@@ -57,6 +59,26 @@ the interesting decisions are already made.
 6. **Idempotent by construction.** An immediate re-run must report *N already correct / 0 updated*.
    That re-run is the acceptance test.
 
+### Three rules that hold for every one of these (confirmed again on the End Customer pass)
+
+- **Write the ONE column. Never call the full importer per row.** Reusing `importOpportunity()` /
+  `importCustomer()` is the obvious shortcut and the wrong tool: it rewrites every header column,
+  re-processes child rows and shares the claim/label machinery, so a "fill one field" job inherits the
+  whole sync's blast radius. A raw `UPDATE … SET <one column>` is the point of the recipe.
+- **Blank/absent in NetSuite is COUNTED, not written.** Leave the column NULL and report the count.
+  Writing `''` invents a value that downstream matching can never resolve, and it destroys the
+  "NULL = fall back to the default behaviour" signal.
+- **An `onlyMissing`-style filter (default true) is what makes re-runs cheap** — measured 4 NetSuite
+  calls instead of 11 on a second pass of the End Customer backfill.
+- **Pacing depends on WHICH limit the API enforces.** ClickUp caps requests/minute, so that backfill
+  paces 700 ms per *request*. NetSuite caps **concurrency**, and these jobs are strictly serial, so
+  200 ms is enough. Copying a pacing number between APIs is how a backfill ends up 3× slower than it
+  needs to be — or throttled.
+- **A per-record (non-batched) variant must self-chunk.** 776 REST reads cannot finish inside the 300s
+  watchdog; reuse the `OpportunityStakeholderBackfill` chunking shape verbatim rather than inventing a
+  second one — see
+  [creating-worker-actions](./creating-worker-actions.md#self-chunking-the-pattern-for-work-that-cannot-finish-in-one-job).
+
 ### The dry run doubles as the field-type probe
 
 `CustomerAccountTypeBackfill::detectAccountTypeExpression()` issues **one** probe query using
@@ -133,6 +155,16 @@ that sent TRUE-81213's investigation down the wrong path. **Count the jobs; do n
 
 ## Change history
 
+- 2026-09-02 — Recorded a **third** instance of the recipe,
+  `Netsuite/OpportunityEndCustomerBackfill/Backfill` (worker2 PR #159), which reads **per record over
+  REST** instead of batched SuiteQL and therefore **self-chunks**. Generalized four rules it
+  re-confirmed: write the one column and never call the full importer per row (that would inherit the
+  whole sync's blast radius); **count** a blank NetSuite value instead of writing `''`; an
+  `onlyMissing` filter (default true) makes re-runs cheap (4 calls vs 11); and pace against the limit
+  the API actually enforces — NetSuite constrains **concurrency** (200 ms is fine for a serial job)
+  where ClickUp constrains requests/minute (700 ms per request). Details and the production baseline
+  live in
+  [netsuite-opportunity-client-labels](./netsuite-opportunity-client-labels.md). (ajean)
 - 2026-08-28 — Added **"When a backfill is the WRONG tool"** after TRUE-81213 proved the point: a
   blank-Consolidated-Business-Name defect that looked like backfill work was **self-healing**, because
   `listCustomers()` pulls the full population with no date filter (the corrected cron re-linked 793 rows
@@ -158,6 +190,8 @@ that sent TRUE-81213's investigation down the wrong path. **Count the jobs; do n
   real-time single-record sibling; the Customers variant and the List/Record `BUILTIN.DF` rule live there.
 - [Running worker2 locally against real NetSuite](../workflows/running-worker2-locally.md) — how this was
   tested before it touched production.
+- [ClickUp Opportunity Client vs End-Customer Labels](./netsuite-opportunity-client-labels.md) — the
+  third instance of this recipe, its deploy gate, and what a full production pass looks like.
 - [NetSuite SuiteQL/REST API Reference](../../../../1.0/apps/library/features/netsuite-suiteql-api-reference.md)
 - [Forecast2 Supporting-Records Nightly Import (1.0 cron)](../../../../1.0/apps/worker/features/forecast2-supporting-records-import.md)
   — the full pull that made TRUE-81213 self-healing, and the orphan-group diagnostic.

package/knowledge/INDEX.md

@@ -14,7 +14,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 15 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 3 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
-- **tools** (Tools) — 15 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 16 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 

package/package.json

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