toga-ai 1.0.710 → 1.0.712

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

@@ -17,5 +17,6 @@
 | [Staples cXML Order Import (SFTP → NetSuite)](features/staples-cxml-order-import.md) | `sync_staples_cxml.php` is an **hourly** cron (runs at **:45**) that imports Staples cXML purchase orders from SFTP into NetSuite as Sales Orders, then writes a | worker/crons/sync/staples/sync_staples_cxml.php |
 | [Diagnosing frozen 1.0 worker cron check-ins (Sentry "missed" flood)](workflows/diagnosing-frozen-cron-checkins.md) | When 1.0 worker cron timestamps freeze and Sentry project `worker1` fills with **`missed`** check-ins, the intuitive diagnosis — a wedged `App_Framework::isProc | worker/.ebextensions/cron.config, library/app/worker.php |
 | [isFulfillable Multi-Client Backfill (all togasupply clients)](workflows/isfulfillable-multi-client-backfill.md) | One-time backfill that catches up `Items.isFulfillable` on **existing** items across **all 17 togasupply clients** (AIG, Broward Sheriff, Canon, Endeavor Health | worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php, library/app/api/toga2.php |
+| [Deduplicating NetSuite duplicate Items across client DBs (recursive MERGE)](workflows/netsuite-duplicate-items-dedup.md) | A one-time, per-client data cleanup that collapses **duplicate `Items` rows sharing a `partNumber`** in each NetSuite → TOGa Supply client DB down to a single c | library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.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/crons/toga2/netsuite/sync_togasupply_elite.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql, dbchanges2/_modules/netsuite/2026-08-05 - CLEAN NETSUITE CLINET.SQL |
 | [Tracing a 1.0 worker cron run in production (no stdout, silent skips)](workflows/tracing-a-worker-cron-run-in-production.md) | How to answer *"did this cron actually run, and what did it do?"* on the 1.0 `worker` tier, where **there is no usable stdout** and **a skipped run leaves no tr | worker/ebs/cron.worker.php, worker/schedules/cron.worker.sync.json, worker/schedules/cron.worker.infrastructure.json, worker/.ebextensions/009_setup_phpini.config, library/app/framework.php |

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -755,9 +755,55 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   2**) and scope the `Units` lookup by it (returns exactly 1 → reuse). Latent data problem behind it:
   **duplicate `Items` with the same `partNumber`** should be reconciled later (the fix is robust to it).
   GroWrk ITEM_FULFILLMENTS went from stuck `1-RUNNING` (since Aug 21) to green.
+  - **⚠ SUPERSEDED 2026-08-31 — item-scoping ALONE was WRONG for NYCHH.** Where the serial's single
+    existing unit sits under a **different** duplicate `Item` sharing the part number, scoping the `Units`
+    lookup by `$uuidItemForLine` found nothing and re-created the unit → the SAME 1062 collision. Correct
+    rule: **a serial identifies a physical device, so query `Units` by `serialNumber` ONLY**, then *prefer*
+    the unit whose item matches `$uuidItemForLine` when several share the serial (GroWrk's 2-unit case),
+    else reuse the first; create only when **no** unit carries the serial. Handles the 1-unit (NYCHH),
+    2-unit (GroWrk), and new-serial cases. (The duplicate `Items` themselves are the real defect — see the
+    Agilant-catalog root cause and the dedup workflow below.)
+
+- **⚠ Invoice line numbers are NOT unique on multi-SO invoices — assign a sequential `lineNumber`
+  (fixed 2026-08-31).** A NetSuite invoice that bills **multiple sales orders** restarts `line` per source
+  SO, so `$nsItem->line` is not unique within one invoice → `InvoiceItems UNIQUE(invoiceId, lineNumber)` →
+  `POST /v2/invoices` `EV-10` / MySQL **1062**, and because the invoice POST is **atomic** the whole
+  invoice rolls back, freezing `INVOICES` at `1-RUNNING` (NYCHH). **Fix (`syncInvoiceFromNetsuite`):**
+  assign a unique **1..N sequential** `lineNumber` per imported line instead of `$nsItem->line` (identical
+  for the common single-SO invoice; differs only on multi-SO). Safe because nothing downstream keys off
+  invoice `lineNumber` — the SO link uses `orderLine`/`salesOrderItem`.
+- **⚠ Transfer-order invoices are NOT imported (fixed 2026-08-31).** Under NYCHH stocking-flag routing a
+  $0 NetSuite Sales Order becomes a `TransferOrder`, not a `SalesOrder`; `Invoices` has only
+  `salesOrderId` (no `transferOrderId`), so such an invoice imported with a **null order link**. Team
+  decision: **do not import transfer-order invoices at all.** **Fix:** in the "billed order not found in
+  SalesOrders" branch, classify the order authoritatively (`App_Api_Netsuite_Rest::fetchSalesOrderByIdFull`
+  + `self::isTransferOrder`) and **return early** when it is a transfer order, gated on
+  `IS_ENABLED_INTEGRATION_TRANSFER_ORDERS`. Existing TO-billed invoices were deleted by the developer.
+- **⚠ ROOT CAUSE of the duplicate `Items`: the inventory-adjustment item-create OMITTED the catalog
+  (fixed 2026-08-31).** `getCreateItem` (`toga2.php:6233`) and the fulfillment create (~4951) stamp
+  `'catalog' => ['name' => 'Agilant']`; `syncInventoryAdjustmentFromNetsuite`'s item-create did **not** →
+  it produced **NULL-catalog `Items`**. The shared item lookup (`common_sync_togasupply.php` ~L313) is
+  populated **only from Agilant-catalog items**, so those NULL-catalog dupes are **invisible** to it → a
+  NEW duplicate item was created **every run** for the same part number — the source of every
+  `(itemId, serialNumber)` unit collision seen this session. **Fix:** stamp
+  `'catalog' => ['name' => 'Agilant']` on the inventory-adjustment item-create. Stops all new duplicates.
+  The one-time cleanup of the accumulated ~4,300 duplicate part numbers across all 17 clients is the
+  [NetSuite duplicate-Items dedup workflow](../workflows/netsuite-duplicate-items-dedup.md).
 
 ## Change history
 
+- 2026-08-31 — **Invoice + serial-unit + duplicate-Item root-cause fixes (shared, `library`).**
+  `syncInvoiceFromNetsuite` now assigns a **sequential 1..N invoice `lineNumber`** (NetSuite reuses `line`
+  across multi-SO invoices → `InvoiceItems UNIQUE(invoiceId,lineNumber)` 1062 → atomic rollback → NYCHH
+  INVOICES `1-RUNNING`) and **skips transfer-order invoices** (classify via `fetchSalesOrderByIdFull` +
+  `isTransferOrder`, return early, gated on `IS_ENABLED_INTEGRATION_TRANSFER_ORDERS` — `Invoices` has no
+  `transferOrderId`; team decision not to import them). **Corrected** the 2026-08-30 item-scoped serial
+  unit lookup (which broke NYCHH): a serial identifies a physical device, so query `Units` by
+  `serialNumber` ONLY, prefer the unit matching `$uuidItemForLine` when several share it, else reuse first,
+  create only when none exists. Found + fixed the **root cause of the duplicate `Items`**: the
+  inventory-adjustment item-create omitted `catalog => Agilant`, producing NULL-catalog items invisible to
+  the Agilant-only sync lookup → a new dup every run. Companion one-time cleanup across all 17 clients:
+  [NetSuite duplicate-Items dedup workflow](../workflows/netsuite-duplicate-items-dedup.md). (jcardinal)
 - 2026-08-30 — **Inventory-adjustment serialized-unit path now auto-creates a missing unit warehouse
   (`library`).** `syncInventoryAdjustmentFromNetsuite` took the unit's location from the inventory
   number's `custitemnumber_location` but never created a missing warehouse (unlike

package/knowledge/1.0/apps/worker/workflows/netsuite-duplicate-items-dedup.md

@@ -0,0 +1,102 @@
+---
+title: "Deduplicating NetSuite duplicate Items across client DBs (recursive MERGE)"
+framework: "1.0"
+repo: worker
+project: Worker
+client: shared
+type: workflow
+status: active
+updated: 2026-08-31
+owners: [jcardinal]
+files:
+  - library/app/api/toga2.php
+  - worker/crons/toga2/netsuite/common_sync_togasupply.php
+related:
+  - ../features/netsuite-togasupply-per-client-sync.md
+  - ../../library/features/netsuite-suiteql-rest-shim.md
+---
+
+## Summary
+
+A one-time, per-client data cleanup that collapses **duplicate `Items` rows sharing a `partNumber`**
+in each NetSuite → TOGa Supply client DB down to a single canonical item, re-pointing every reference.
+Duplicates accumulated because the NetSuite inventory-adjustment sync created **NULL-catalog `Items`**
+that the sync's own lookup could not see, so a new duplicate was minted every run (root cause below).
+Deleting a duplicate item is a **recursive MERGE**, not a simple `DELETE` — ~23 `itemId` tables plus
+two FK cascades (`VendorItems`, `Units`) reference it. Run **per client, in its own transaction**,
+after the code fix is deployed.
+
+**Verified in prod (2026-08-31):** all **17** NetSuite clients now show **0 duplicate part numbers**
+(e.g. `Client_Nychh` 3954→1818 items, `Client_Canon` 913→425; 0 orphans, 0 collisions).
+
+## Root cause — why the duplicates existed at all
+
+`syncInventoryAdjustmentFromNetsuite`'s item-create **omitted the catalog** that
+`getCreateItem`/`toga2.php:6233` and the fulfillment create both stamp
+(`'catalog' => ['name' => 'Agilant']`), so it produced **NULL-catalog `Items`**. The shared sync item
+lookup in `worker/crons/toga2/netsuite/common_sync_togasupply.php` (~L313) is populated **only from
+Agilant-catalog items**, so a NULL-catalog dupe is **invisible** to it → the sync re-created the item
+every run for the same part number. **The fix (stamp `catalog => Agilant` on that create) stops all NEW
+duplicates** and must be deployed first — see
+[per-client sync](../features/netsuite-togasupply-per-client-sync.md). This cleanup removes the
+**existing** backlog (~4,300 duplicate part numbers / ~15,700 `Items` rows accumulated over time).
+
+## When to run
+
+- After the Agilant-catalog item-create fix is deployed (otherwise the backlog regrows every sync run).
+- Per client, once. Re-runnable safely (idempotent: a client already at 0 duplicates is a no-op).
+
+## Procedure
+
+1. **Report first (read-only).** Run `test/team/2.0 deployment/duplicate_items_merge_analysis.sql`
+   against the client DB — a per-client duplicate + collision report. Confirm the duplicate count and the
+   `(itemId, serialNumber)` / `(vendorId, itemId, vendorPartNumber)` collisions before mutating anything.
+2. **Pick the canonical item per `partNumber`** in this priority order: **Agilant + manufacturer**
+   preferred → else **Agilant** → else **has-manufacturer** → else **lowest `id`**.
+3. **Re-point every `itemId` reference** across the ~23 `itemId` tables **plus `Entitlements.saleItemId`**
+   from each non-canonical item to the canonical one.
+4. **Handle the two FK cascades** (children must move before their parent duplicate is deleted):
+   - **`VendorItems`** is referenced by `PurchaseOrderItems`, `VendorItemCosts`, `Personas_VendorItems`.
+   - **`Units`** is referenced by **10** `*ItemUnits` child tables.
+5. **Resolve unique-key collisions with a SURVIVOR-per-key approach**, NOT a plain "`UPDATE IGNORE` +
+   delete leftover" (that leaves child FKs dangling on dupe-vs-dupe collisions). For each colliding key
+   (`Units.(itemId, serialNumber)`, `VendorItems.(vendorId, itemId, vendorPartNumber)`): choose one
+   survivor row, **re-point the non-survivor rows' children onto the survivor**, delete the non-survivors,
+   then re-point the rest.
+6. **Delete the duplicate `Items` rows LAST** (after all references and cascades are moved).
+7. **Run each client in its own transaction**, continue-on-error (see the missing-table gotcha).
+
+## Validation
+
+- Validate against **local copies of the client DBs before prod** (this session: `Client_Nychh`
+  3954→1818, `Client_Canon` 913→425, **0 orphans, 0 collisions**).
+- After each prod run, re-run the analysis SQL: the client must report **0 duplicate part numbers**.
+
+## Deliverables (live in the repo, not the knowledge base)
+
+- `test/team/2.0 deployment/duplicate_items_merge_analysis.sql` — read-only per-client duplicate +
+  collision report.
+- The per-client merge migration (the recursive MERGE implementing steps 2–6).
+
+## Gotchas / known issues
+
+- **The sync item lookup is Agilant-catalog-only.** Any non-Agilant item is **invisible** to
+  `common_sync_togasupply.php` and will be **re-created** — this is the whole mechanism behind the
+  duplicates. Deploy the catalog-stamp fix before (and independently of) this cleanup.
+- **`Items` has NO unique constraint on `partNumber`.** Duplicates persist silently; nothing at the DB
+  level prevents them, which is why this is a MERGE-and-clean rather than a rely-on-the-constraint fix.
+- **Client DBs are schema-similar but NOT identical.** Some lack optional tables (e.g.
+  `EntitlementServiceItems`). Run the merge **continue-on-error** so a missing-table MySQL **1146** is a
+  **benign skip**, not a failed migration.
+- **A plain `UPDATE IGNORE` + delete-leftover is insufficient.** Dupe-vs-dupe unique-key collisions leave
+  orphaned child FKs; only the survivor-per-key re-pointing (step 5) is correct.
+
+## Change history
+
+- 2026-08-31 — Documented the one-time duplicate-`Items` dedup across all 17 NetSuite clients (recursive
+  MERGE over ~23 `itemId` tables + `Entitlements.saleItemId`, `VendorItems`/`Units` FK cascades,
+  survivor-per-key collision resolution), its root cause (the inventory-adjustment item-create omitted
+  `catalog => Agilant` → NULL-catalog items invisible to the Agilant-only sync lookup → a new dup every
+  run), and the durable gotchas (Agilant-only lookup, no `partNumber` unique constraint, per-client schema
+  drift → continue-on-error). Validated on local copies then run per client in prod; all 17 clients at 0
+  duplicate part numbers. (jcardinal)

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 23 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 31 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 32 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 13 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)

package/knowledge/sessions/2026-08-31-transfer-orders-id-collision-apeterson.md

@@ -0,0 +1,242 @@
+---
+type: session
+slug: transfer-orders-id-collision
+title: Transfer Orders Core id collision + blox symlink dev-loop fix
+author: apeterson
+repos: [dbchanges2, toga25-supply, toga-blox, _underscore]
+framework: "2.0"
+client: nychh
+status: active
+created: 2026-08-31
+updated: 2026-08-31
+---
+
+# Session: transfer-orders-id-collision
+**Date:** 2026-08-31
+**Project/Repo:** dbchanges2 + toga25-supply + toga-blox (2.0)
+**Task:** Get the NYCHH Transfer Orders page working on sandbox-client after a reset-from-production, and permanently fix the toga-blox local-symlink dev loop in toga25-supply.
+
+---
+
+## What WORKED
+
+- **Published `/capture` round two.** 13 doc updates + 4 regenerated `INDEX.md` pushed as
+  `172f85d` `knowledge: capture session updates` on `_main` of `~/toga-tech`, confirmed on
+  `origin/_main` (CI stacked `c0fcabc` on top). `validate` passed (32 repos), index rebuilt to
+  454 docs, nothing outside `knowledge/` staged.
+
+- **Diagnosed the `TalosLauncher` import error correctly on the second pass.**
+  `toga25-supply/node_modules/@agilant/toga-blox` was a REAL DIRECTORY holding published
+  `1.1.1-sandbox-client.140`, which contains **zero** files matching `Talos`. The local
+  checkout (`1.1.0`, branch `TRUE-80692`) had a perfectly intact export chain:
+  `dist/index.js` -> `dist/components/index.js:44` -> `dist/components/Talos/index.js` ->
+  `export { default as TalosLauncher }`. Evidence: `ls -la node_modules/@agilant/` showed no
+  `->`, and `grep -rl Talos node_modules/@agilant/toga-blox/` returned nothing.
+
+- **Created the symlink per the team workflow.** `npm install --no-save
+  /Users/alexpeterson/Agilant/toga-blox-npm` from toga25-supply produced
+  `toga-blox -> ../../../toga-blox-npm` resolving to `1.1.0`, and left `package.json`
+  untouched (git status clean).
+
+- **Permanently fixed the Vite dev loop** in `toga25-supply/vite.config.ts`. It now detects the
+  symlink with `fs.lstatSync(bloxDir).isSymbolicLink()` and picks opposite `optimizeDeps`
+  settings: LINKED -> `exclude: ["@agilant/toga-blox"]` + `include: BLOX_EXTERNALS`;
+  PUBLISHED -> `include: ["@agilant/toga-blox"]` (previous behaviour, unchanged). Also added
+  `server.fs.allow` for the symlink's real path. Verified from the running dev server: the
+  transform now emits
+  `import { SideNav, EnvironmentBadge, TalosLauncher, ... } from "/@fs/Users/alexpeterson/Agilant/toga-blox-npm/dist/index.js"`
+  and `node_modules/.vite/deps/@agilant_toga-blox.js` is absent.
+
+- **Enumerated blox's full external surface** (the `include` list needed once blox is excluded),
+  generated from its dist:
+  `@fortawesome/{free-solid,pro-light,pro-regular,pro-solid}-svg-icons`,
+  `@fortawesome/react-fontawesome`, `@sentry/react`,
+  `@tanstack/{react-query,react-table,react-virtual}`, `axios`,
+  `class-variance-authority`, `classnames`, `clsx`, `dayjs`, `dayjs/plugin/timezone`,
+  `dayjs/plugin/utc`, `framer-motion`, `react-hook-form`, `react-multi-select-component`,
+  `react-select`, `tailwind-merge`, `uuid`.
+  Regeneration command is in a comment above the list in `vite.config.ts`.
+
+- **Root-caused why Transfer Orders did not render on sandbox-client.** The two `Core/` seeds
+  had never run there, AND `Core/2026-08-28a` could no longer run as written: production had
+  shipped a `sales-order-denial-details` feature into the exact reserved blocks
+  (`Surfaces 47`, `SurfaceElements 170-176`, `Messages 227-232`). Sandbox had zero rows
+  matching `%transfer%` in Surfaces or Messages.
+
+- **Confirmed `Core/2026-08-28b` ran cleanly on sandbox with no collision.** Its ids
+  (Surface 52, Elements 187-189, Messages 251-260) all sat above the then-MAX of 47/176/232.
+  Verified present and correct.
+
+- **Proved no damage was done to the other team's feature.** All denial-details rows show
+  `dtCreated == dtUpdated == 2026-08-31 09:45:11` (the reset timestamp) — never updated. And
+  `_underscore/Model/Core/Surface.php:748` `_loadOverrides()` filters
+  `WHERE SurfaceOverrides.surfaceId = $surfaceId`, so the NYCHH override row (surfaceId 39,
+  surfaceElementId 170) is only ever loaded when rendering surface 39 and can never reach
+  surface 47. It is inert in both directions.
+
+- **Renumbered `Core/2026-08-28a` safely.** Shifts applied: Surfaces `47-51 -> 53-57`,
+  SurfaceElements `170-186 -> 190-206`, Messages `227-250 -> 261-284`. Verified after the
+  rewrite: the md5 of every quoted string in the file is IDENTICAL to the backup (UUIDs and
+  slugs untouched), and the occurrence counts of `312`, `351`, `39` and `70` are unchanged.
+  FK graph re-derived and correct — nav element 190 on surface 39; 191-194 -> 54;
+  195-197 -> 55; 198-200 -> 56; 201-206 -> 57.
+
+- **Repointed the cross-DB reference.** `Client_Nychh/2026-08-28b` had 3 occurrences of `170`
+  (comment, INSERT value, NOT EXISTS guard) — all now `190`.
+
+- **Verified the new blocks are free on BOTH sandbox-client and local** (`53-57`, `190-206`,
+  `261-284` all return 0), and that `Core.Surfaces 39` is `navigation` (TAB_STRIP).
+
+---
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **`rm -rf node_modules/.vite` + hard reload did NOT fix the `TalosLauncher` error.** This was
+  the first hypothesis and it was wrong. The export genuinely was not in the package Vite had
+  pre-bundled, because supply was consuming the published tarball, not the local checkout. Do
+  not reach for the cache clear before confirming `ls -la node_modules/@agilant/` shows a `->`.
+
+- **After symlinking, the error STILL persisted** and a normal hard reload did not clear it.
+  Vite serves `/node_modules/.vite/deps/*` with `Cache-Control: max-age=31536000, immutable`.
+  The re-optimize rewrote the file but kept the same `browserHash` (`69916b97`), so the URL
+  never changed and Chrome would not revalidate. Proven by `curl`-ing the dev server for that
+  exact URL and finding `TalosLauncher_default as TalosLauncher` present in the response while
+  the browser still errored. Fix at the time: DevTools -> Network -> **Disable cache**. Fix
+  permanently: the `optimizeDeps` change above.
+
+- **First renumbering attempt CORRUPTED the file — UUIDs got shuffled.** The Python transform
+  protected quoted strings by replacing them with `\x00<index>\x00` placeholders. `\x00` is not
+  a word character, so the subsequent bare-integer regex matched the placeholder INDICES and
+  shifted them, meaning literals were restored to the wrong positions. Caught by comparing the
+  md5 of the extracted UUID list before/after (`CHANGED`). Fixed by restoring from backup and
+  re-running with a **digit-free placeholder** (`\x01<a-j encoded index>\x01`). Always verify a
+  bulk rewrite by diffing the quoted-string set, not by eyeballing.
+
+- **Assuming the hyphenated ranges in the file header would be shifted.** The bare-integer regex
+  is `(?<![\w.\-])\d+(?![\w.\-])`, so `227-250`, `47-51` and `170-186` in comments were skipped
+  (hyphen guard on both sides). A `str.replace` of the old header block asserted false because
+  it still contained the ORIGINAL numbers. This is desirable behaviour — it is why nothing
+  unintended shifted — but the header had to be rewritten by hand afterwards.
+
+- **macOS/zsh tool gaps hit repeatedly** (all cost a round trip):
+  - `timeout` does not exist — use `mysql --connect-timeout=N`.
+  - `cat -A` is illegal on macOS — use `od -c` or `sed -e 's/$/<EOL>/'`.
+  - Unquoted `--include=*.js` is glob-expanded by zsh and fails — quote it.
+  - `grep -oE` does not support lookbehind; `grep -P` is required for `(?<!...)`.
+  - The `mysql` alias is a shell alias, so `$LM="mysql ..."` in a variable is not resolved —
+    call `/Applications/XAMPP/xamppfiles/mysql/bin/mysql` by full path.
+
+- **Do NOT re-run `Client_Nychh/2026-08-28b` on any machine that already has the row.** It now
+  carries element `190`, but its `uuid` is a fixed literal
+  (`7a8b9c0d-1e2f-4304-8516-6a7b8c9d0e1f`), so the insert would fail on the duplicate UUID. Use
+  the `UPDATE ... SET surfaceElementId = 190 WHERE uuid = '...'` instead.
+
+---
+
+## Not tried yet (candidates for next session)
+
+- Running the 4 sandbox steps and 3 local steps listed under **Exact next step** — nothing has
+  been executed yet.
+- Committing the 7 dbchanges2 files. They are ALL still untracked, which is the direct cause of
+  the id collision (no registry, no visibility to the other developer).
+- Production rollout — nothing has been run there at all.
+- Beta — still blocked, it has no `TransferOrderStages` table.
+- Flipping `TRANSFER_ORDER_LINES_ENABLED` to `true` in
+  `toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/hooks/useTransferOrderRecord.ts`
+  once `Client/2026-08-28b` is applied everywhere.
+- Fixing the blank-client template (`Client/2026-06-03- BLANK_CLIENT_DATABASE.sql` line ~9462)
+  so new tenants get `TransferOrderItems.dtCreated`/`dtUpdated`.
+- The Create Transfer Order modal — still a UI shell; its 3 blocking data questions remain
+  unanswered (which `UnitDispositions` slug counts as available; whether `Locations` are
+  hierarchical; who owns the unit-disposition flip to In Transit).
+- Switching `vite.config.ts`'s `BLOX_EXTERNALS` to something generated at config time rather
+  than a hand-maintained list.
+
+---
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `toga25-supply/vite.config.ts` | MODIFIED (uncommitted) | Symlink-aware `optimizeDeps` + `server.fs.allow`. Backup at `scratchpad/vite.config.ts.bak`. Verified working against the running dev server. |
+| `toga25-supply/node_modules/@agilant/toga-blox` | RELINKED | Now `-> ../../../toga-blox-npm` (v1.1.0). `--no-save`, so `package.json` untouched. Any plain `npm i` will clobber it. |
+| `dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql` | RENUMBERED (untracked) | Surfaces 53-57, Elements 190-206, Messages 261-284. Header rewritten with the collision post-mortem + a re-verify warning. NOT RUN ANYWHERE YET. |
+| `dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql` | UNCHANGED (untracked) | Already applied to sandbox-client Core AND local Core. Correct as-is. |
+| `dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql` | MODIFIED (untracked) | `surfaceElementId` 170 -> 190 in 3 places. Already-applied rows need the UPDATE, not a re-run. |
+| `dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql` | UNCHANGED (untracked) | Applied to sandbox (TableView 22, 4 fields) and local. |
+| `dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql` | UNCHANGED (untracked) | Applied to sandbox (4 record perms, 34 field perms). |
+| `dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql` | UNCHANGED (untracked) | NOT RUN on sandbox OR local (0 `color.transferStage.*` tokens on both). |
+| `dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql` | UNCHANGED (untracked) | No action needed — production already had the columns, so sandbox has them via the reset. |
+| `scratchpad/local-undo-transfer-surface-old-ids.sql` | CREATED | Deletes 24 messages / 5 surfaces / 17 elements / 6 vocabulary rows BY UUID in FK order, then repoints local's override to 190. Leaves `2026-08-28b` alone. |
+| `scratchpad/28a.before.sql`, `nychh28b.before.sql`, `vite.config.ts.bak` | CREATED | Pre-change backups. |
+
+---
+
+## Decisions made
+
+- **Renumber into a contiguous block ABOVE the current MAX (53-57 / 190-206 / 261-284) rather
+  than back-filling the gaps** left at Surfaces 48-51, Elements 177-186, Messages 233-250.
+  Rationale: a contiguous block above MAX is trivially verifiable and trivially reversible
+  (`DELETE WHERE id >= n`), whereas a split block is neither. Ids are not scarce. Rejected:
+  filling the gaps to keep numbering compact.
+
+- **Fix already-applied override rows with a targeted `UPDATE` by uuid, not by re-running the
+  migration.** Rationale: the file's uuid is a fixed literal, so a re-run would fail on the
+  duplicate key; and after the UPDATE the file's `NOT EXISTS` guard correctly no-ops. Rejected:
+  DELETE-then-rerun (more destructive for no benefit).
+
+- **`vite.config.ts` detects the symlink instead of exposing a flag/env var.** Rationale: the
+  linked and published cases need OPPOSITE `optimizeDeps` settings, and any flag a developer
+  must remember to flip will be wrong half the time — which is the whole class of bug this
+  session was spent on. Rejected: an env var, and rejected leaving `include` in place and
+  documenting the manual cache-clear ritual.
+
+- **Left `BLOX_EXTERNALS` as a hand-maintained list with the regeneration command in a comment.**
+  Rationale: generating it at config time means reading blox's dist on every server start.
+  Accepted cost: if blox adds a dependency, the symptom is
+  `does not provide an export named 'default'` on that new package.
+
+- **Declined both ELEVATED knowledge-base edits** during `/capture` (developer's call):
+  the dbchanges2 `architecture.md` test-data Critical rule, and the `standards/frontend.md`
+  §11/§13(c) dedupe accuracy fix. Consequence: the dedupe + `rm -rf node_modules/.vite`
+  detail lives ONLY in `toga-blox/workflows/local-link-into-a-consumer-app.md`, and the
+  test-data rule ONLY in `toga25-supply/features/transfer-orders-page.md`.
+
+- **Did not commit the `.env.development` change** in toga25-supply. Rationale: its diff
+  repoints every developer's dev server.
+
+---
+
+## Blockers
+
+- **The 7 dbchanges2 files are all untracked.** This is not incidental — it is the direct cause
+  of the id collision. Two developers both computed `MAX(id)+1` against the same Core; the other
+  one shipped first. Nothing in git could warn either side.
+- **Beta cannot take these migrations** — it has no `TransferOrderStages` table.
+- **Reserved ids remain structurally unsafe.** Core ids must be literals because Core and Client
+  are on separate clusters in production, so a Client file cannot join to Core to resolve one.
+  That forces the number to be chosen at authoring time, opening a race for however long the
+  feature takes to ship. Nothing systemic was changed this session — only this one file was
+  renumbered and a re-verify warning added to its header.
+
+---
+
+## Exact next step
+
+> Run, in order, and stop if any verification returns non-zero:
+>
+> **sandbox-client / `Core`:** (1) `SELECT (SELECT COUNT(*) FROM Surfaces WHERE id BETWEEN 53 AND 57) AS surf, (SELECT COUNT(*) FROM SurfaceElements WHERE id BETWEEN 190 AND 206) AS elem, (SELECT COUNT(*) FROM Messages WHERE id BETWEEN 261 AND 284) AS msg;` — all must be 0.
+> (2) run `Core/2026-08-28a - TransferOrderSurfaceSeed.sql`.
+>
+> **sandbox-client / `Client_Nychh`:** (3) `UPDATE SurfaceOverrides SET surfaceElementId = 190 WHERE uuid = '7a8b9c0d-1e2f-4304-8516-6a7b8c9d0e1f';`
+> (4) run `Client/2026-08-28a - TransferOrderStageThemeTokens.sql`. Then reload the app — the
+> Transfer Orders nav item should appear for NYCHH.
+>
+> **local:** (5) run `scratchpad/local-undo-transfer-surface-old-ids.sql` (its closing SELECT
+> must be all zeros), (6) run the renumbered `Core/2026-08-28a`, (7) run
+> `Client/2026-08-28a` against `Client_Nychh`.
+>
+> Then commit all 7 dbchanges2 files so the id blocks are recorded in git.
+
+---
+_Saved by /session-save on 2026-08-31_

package/package.json

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