toga-ai 1.0.660 → 1.0.662

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

@@ -190,6 +190,40 @@ See the [tracking-number bridge doc](../../../2.0/apps/_underscore/features/trac
   0 of their fulfillments resolve an upstream sales order). `/units` writes and all three
   tracking-bridge models have **no** interceptor, and **DELETE fires none**.
 
+### Single-tracking-number fan-out to items (318) and units (319) — corrected 2026-08-26
+
+The earlier "maintains all three bridges" claim was **only true for 317 (header)**: in prod
+`Client_Quad` had **0** rows in 318 and only partial 319. A NetSuite item fulfillment carries
+**exactly one** tracking number, and item (318) + unit (319) tracking are meant to **mirror** that
+single header number. Two bugs sat in the `if ($cntTrackingNumbers == 1)` branch of
+`syncItemFulfillmentFromNetsuite`:
+
+- **318 (item) was NEVER written** — the item-level bridge went unpopulated, so any fulfillment
+  TableView reading 318 showed a blank Tracking #/Carrier column (the Quad live bug).
+- **319 (unit) received only the LAST item's units.**
+  `$lookupItemFulfillmentItemUnitsByNetsuite…AssignementId` (and the sibling existing-unit-tracking
+  lookup) was **rebuilt/reset per item inside the item loop** but **consumed once after the loop** —
+  so only the final processed item's units got tracking; serialized units on earlier items were
+  silently skipped (e.g. `Client_Quad` IF 1688 / SO 287406, whose one unit sat on the first item and
+  got none). Same lesson as the sparse-client `TypeError` above: a per-item structure consumed
+  outside its loop must not be reset inside it.
+
+**Fix (2026-08-26, `library` only, `php -l` clean):** after confirming exactly one tracking number,
+**re-GET the IF's items+units** with their current 318/319 tracking (each `App_Api_Toga2::send` is
+its own committed api2 request, so the re-fetch sees everything just synced), then **fan the one
+tracking number to every item and every serialized unit** — idempotent (skip if already linked) and
+**pruning any stale tracking whose number ≠ the current NetSuite one**. Behavior change: the old
+code deleted **all** unit tracking whenever NetSuite sent 0 or >1 numbers; the new code only prunes
+non-matching tracking **within the single-number case** (single-number is the norm for NetSuite).
+Leftover: the now-unused
+`$lookupExistingItemFulfillmentItemUnitTrackingNumbersByItemFulfillmentItemUnitUuidAndTrackingNumberUuid`
+lookup (~L4423, 4446-4453) is harmless dead code, left in place to avoid a whitespace-fragile edit
+(minor future cleanup). Quad's historical rows were backfilled separately (single-TN IFs only) — see
+the [Quad profile](../../../clients/quad/profile.md) and the
+[tracking-number bridge doc](../../../2.0/apps/_underscore/features/tracking-number-bridges.md).
+Design rationale for putting this at the source writer rather than a 317 interceptor lives on the
+[recursive item fulfillments doc](../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md).
+
 ### Custom field contract (hardcoded in `common_sync_togasupply.php`)
 
 The engine requests these `c_` fields by literal name per route — every synced client must have
@@ -431,6 +465,20 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 
 ## Change history
 
+- 2026-08-26 — Corrected the IF full-reconcile tracking claim and **fixed two bugs** in
+  `syncItemFulfillmentFromNetsuite`'s single-tracking-number branch: **318 (item) was never written**
+  (`Client_Quad` had 0 rows → blank Tracking # column) and **319 (unit) received only the last
+  processed item's units** (a per-item lookup was rebuilt inside the item loop but consumed once
+  after it — `Client_Quad` IF 1688/SO 287406). It now re-GETs the IF's items+units and **fans the one
+  NetSuite tracking number to every item + serialized unit**, idempotent + pruning non-matching
+  tracking; the old delete-all-on-0-or->1 behavior is narrowed to prune-non-matching within the
+  single-number case. `library`-only deploy. Quad's historical rows backfilled by two
+  `dbchanges2/Client_Quad/2026-08-26a/b` migrations (single-TN IFs only; ~120 multi-TN IFs excluded)
+  — see the [Quad profile](../../../clients/quad/profile.md) and
+  [tracking-number bridges](../../../2.0/apps/_underscore/features/tracking-number-bridges.md).
+  Design rationale (source writer vs. a 317 interceptor) on the
+  [recursive item fulfillments doc](../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md).
+  (jcardinal)
 - 2026-08-18 — Recorded the **next poison-order variant** that re-froze Compass USA's SALES_ORDERS
   section on SO **14106** right after the 2026-08-17 fix let the sync advance past SO 7447. This one
   is 2.0-side: the api2 `PUT /sales-orders` → `postPut` → `renumberLineNumbers()` **single-UPDATE**

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

@@ -45,7 +45,7 @@
 | [Table-View Hyperlink Columns (meta → ACL → computed URL → render)](features/tableview-hyperlink-columns.md) | Any 2.0 table-view column can render its value as a clickable link instead of plain text. | _underscore/Model/Client/TableView.php, _underscore/Model/Client/TrackingNumber.php, api2/Component/Api/V2/V2.php, toga2-supply/src/api/toga.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/convertData.tsx, toga2-supply/src/components/ui/Tables/hooks/useDataTableState.tsx, dbchanges2/Client/2026-07-20 - TrackingNumberHyperlinkAndFieldPermission.sql |
 | [TableView joins (TableViewJoins → SQL) — aliasing, chained multi-hop joins, ACL](features/tableview-joins.md) | `Client_*.TableViewJoins` rows are what let a table view show a column from a table other than its base record. | _underscore/Model/Client/TableView.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql, dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql |
 | [TogaIQ Gateway Client (_Component_Api_Togaiq) — AI generate/translate from 2.0](features/togaiq-gateway-client.md) | `_Component_Api_Togaiq` is the 2.0 framework's client for the **TogaIQ** (Talos) AI gateway. | _underscore/Component/Api/Togaiq/Togaiq.php, _underscore/ApiRequest.php |
-| [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Elite/2026-08-17 - FulfillmentTableViews.sql |
+| [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Elite/2026-08-17 - FulfillmentTableViews.sql, dbchanges2/Client_Quad/2026-08-26a - BackfillQuadUnitLevelTrackingSingleTn.sql, dbchanges2/Client_Quad/2026-08-26b - BackfillQuadItemLevelTrackingSingleTn.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView | _underscore/Model/Client/ServiceRequest.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql |
 | [USPS DPV Deliverability Verdict (is this address actually insurable/shippable?)](features/usps-dpv-deliverability.md) | **USPS returning HTTP 200 with a populated address is NOT evidence that the address is deliverable.** The authoritative signal is USPS's **DPV (Delivery Point V | _underscore/Component/Library/Carriers/Usps/Usps.php, _underscore/Model/Client/Address.php, _underscore/Model/Rate/Entitlement.php |
 | [Refreshing a Local Dev Database from Beta (dev-sandbox)](workflows/local-db-refresh-from-beta.md) | How to reset a local 2.0 dev database from the **beta / dev-sandbox** environment: dump each schema (`Core`, `Client_<Id>`, `Logs_<Id>`, …) from the beta host, | api2/Config/, _underscore/Loader.php, _underscore/Model/Client/BundleTranslation.php, api2/Component/Api/V2/V2.php, toga25-supply/sync_compasscanada_schema.sql |

package/knowledge/2.0/apps/_underscore/features/recursive-item-fulfillments.md

@@ -155,12 +155,31 @@ inheritance. Verified against prod `Client_Compass` chains (≥3 levels deep).
   an IF while the item walk is empty/broken would **DELETE the adopted IF's legitimate line items**.
   Requires a CTO design review before implementing adoption semantics. The 2026-07-02 broken-bridge
   guard prevents the duplicate cascade for this failure mode without needing adoption.
+- **Source-side IF tracking population belongs in the NetSuite sync writer, not a 317 interceptor
+  (design decision, CTO-reviewed 2026-08-26).** For NetSuite-integrated clients the fix that
+  populates item/unit tracking (318/319) from a fulfillment's single header tracking number lives in
+  the **source writer** `App_Api_Toga2::syncItemFulfillmentFromNetsuite` (see the
+  [per-client sync doc](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)) —
+  **not** an `_underscore` payload interceptor on `ItemFulfillments_TrackingNumbers` (317). An
+  interceptor fires **per row** as tracking is attached, so it cannot know at insertion time whether
+  the shipment is single- or multi-package, and it would **fight this engine**:
+  `reconcileUpstreamUnits`/`reconcileUpstreamPackages` own upstream 319 with delete-stale logic. The
+  source writer knows NetSuite's one tracking number and the full item/unit set up front, and this
+  recursive engine then mirrors it upstream. A 317-interceptor approach was prototyped and
+  **abandoned**.
 - **Out of scope:** NetSuite sync of upstream IFs; transfer-order fulfillments
   (`transferOrderId`) are skipped.
 - **Performance:** every child write re-runs a full upstream walk (read-heavy, but each
   upstream record is written at most once — idempotent). Fine for normal fulfillment sizes.
 
 ## Change history
+- 2026-08-26 — Recorded the **design decision** (CTO-reviewed) that source-side IF tracking
+  population for NetSuite clients belongs in `App_Api_Toga2::syncItemFulfillmentFromNetsuite`, not a
+  317 (`ItemFulfillments_TrackingNumbers`) payload interceptor: a per-row interceptor cannot tell
+  single- vs multi-package at insert time and would fight this engine's upstream 319 delete-stale
+  reconcile. Prototyped interceptor abandoned. Source-side fix + Quad backfill live on the
+  [per-client sync doc](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
+  (jcardinal)
 - 2026-08-18 — **Bundle scaling now discriminates on distinct downstream items, not SOI lines
   (CTO-approved "Option B").** `reconcileUpstreamLevel`'s Recipe query takes one ordered-qty
   slot per distinct downstream `itemId` and scales only when `distinctDownstreamItemCount > 1`;

package/knowledge/2.0/apps/_underscore/features/tracking-number-bridges.md

@@ -27,6 +27,8 @@ files:
   - dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql
   - dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql
   - dbchanges2/Client_Elite/2026-08-17 - FulfillmentTableViews.sql
+  - dbchanges2/Client_Quad/2026-08-26a - BackfillQuadUnitLevelTrackingSingleTn.sql
+  - dbchanges2/Client_Quad/2026-08-26b - BackfillQuadItemLevelTrackingSingleTn.sql
 related:
   - recursive-item-fulfillments.md
   - ../../api2/features/cxml-shipnotice-gateway.md
@@ -110,9 +112,11 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
   OUTER unit/tracking chain and tracking via the item-level bridge **318** (`dbchanges2/Client_Nychh/2026-06-19a`,
   `dbchanges2/Client_Quad/2026-06-19a`). NYCHH had no custom columns; Quad preserves three
   Units-level customs (`c_hostIdentifier`/CustomRecordFields 1, `c_pkIdentifier`/2, `macAddress`/rf 1432),
-  re-attached to the Units join. **Caveat — record 318 is empty in both client DBs today** (see the
-  portability gotcha below), so the re-root immediately fixes the "0 records" bug but the
-  Outbound Tracking # / Carrier columns stay blank until item-level tracking is backfilled.
+  re-attached to the Units join. **Caveat — record 318 was empty in both client DBs when the views
+  were rebuilt** (see the portability gotcha below), so the re-root fixed the "0 records" bug but the
+  Outbound Tracking # / Carrier columns stayed blank until item-level tracking was backfilled.
+  **Quad's 318 is now populated (2026-08-26 writer fix + backfill — see the resolved gotcha below);
+  NYCHH's 318 is still empty.**
 - **Prudential (Client_Prudential):** Dell posts the legacy `advanceShippingNoticeUnits` key with flat
   tracking — a PRE/POST interceptor rewrites it (see the prudential client doc).
 - **NetSuite-integrated clients:** `Trait/Netsuite/ItemFulfillment.php` now reads
@@ -225,20 +229,34 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
   | CompassCanada | 169 | 138 | 318 |
   | Elite | **0** | 109 | **319** (fixed 2026-08-17) |
   | Prudential | **0** | 380 | **319** |
-  | Quad | **0** | 633 | **319** - but its views read 318 (**live bug**, see below) |
+  | Quad | 0 → +5,129¹ | 633 → +779¹ | **318** — writer + backfill **fixed 2026-08-26** |
   | NYCHH | **0** | unit-level | **319** |
 
+  ¹ Quad's 2026-08-26 backfill (single-tracking-number IFs only) added **5,129** item-level (318)
+  rows (was 0) and **779** unit-level (319) rows; ~120 multi-tracking-number IFs were deliberately
+  excluded. `App_Api_Toga2::syncItemFulfillmentFromNetsuite` now populates both bridges going
+  forward by mirroring each NetSuite IF's single header (317) number down to every item + serialized
+  unit — so for NetSuite-integrated clients 318 and 319 are meant to **mirror** 317, not diverge.
+
   Worked example: copying Compass's **318** join into Elite yields 402 rows with **zero** tracking
   numbers; **319** yields 500 rows with 109 populated. `SELECT COUNT(*)` both bridges in the target
   client DB **before** choosing - the wrong choice produces a structurally-correct view with a
   permanently blank Tracking # / Carrier column, which reads as "the data is missing" rather than
   "the join is wrong."
 
-- **Live bug: Quad's Tracking # column is empty today.** Quad's two fulfillment views are a direct
-  copy of Compass and read **318**, but Quad has **0** rows in 318 and **633** in 319. Same visible
-  symptom as the Elite bug, different cause (Elite's was dead ids; Quad's is the wrong bridge
-  level). **Not fixed** - out of scope when found 2026-08-17. This supersedes the earlier note that
-  Quad's tracking "lives at 317 (~98%)"; the unit-level bridge is where it is now.
+- **RESOLVED 2026-08-26 (was a live bug): Quad's Tracking # column — fixed by populating 318, not by
+  repointing views.** Quad's two fulfillment views read **318**, but Quad had **0** rows in 318 and
+  **633** in 319, so the column was blank. The right fix was **not** the interim "repoint to 319"
+  idea: Quad's IFs come from **NetSuite** (`syncItemFulfillmentFromNetsuite`), one tracking number
+  per IF, and 318/319 are meant to **mirror** the single 317 header number. The source writer was
+  fixed to fan that number to every item (318, previously never written) and every serialized unit
+  (319, previously only the last item's units), and Quad's historical rows were backfilled for
+  single-tracking-number IFs by `Client_Quad/2026-08-26a - BackfillQuadUnitLevelTrackingSingleTn.sql`
+  (319, 779 rows) and `Client_Quad/2026-08-26b - BackfillQuadItemLevelTrackingSingleTn.sql` (318,
+  5,129 rows); ~120 multi-tracking-number IFs excluded. See the
+  [per-client sync doc](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md) for
+  the writer fix. This supersedes the older "Quad's tracking lives at 317 (~98%)" note. (Elite's bug
+  was a different cause — dead ids — and remains a 319 repoint.)
 
 - **The dead-id breakage spans TEN clients, not just Elite (measured 2026-08-17).**
   `item-fulfillments-for-sales-orders` / `item-fulfillments-for-sales-order-items` still carry
@@ -253,6 +271,17 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
   for record 41.
 
 ## Change history
+- 2026-08-26 — **Quad's empty-Tracking-# live bug RESOLVED** — by populating **318**, not repointing
+  views to 319. Root: Quad's IFs come from NetSuite (one tracking number per IF) and 318/319 are
+  meant to **mirror** the single 317 header number; `App_Api_Toga2::syncItemFulfillmentFromNetsuite`
+  was fixed to fan that number to every item (318, previously never written) + serialized unit (319,
+  previously only the last item's units — see the
+  [per-client sync doc](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)),
+  and Quad's history was backfilled for single-tracking-number IFs (`Client_Quad/2026-08-26a` 319
+  +779 rows, `2026-08-26b` 318 +5,129 rows; ~120 multi-TN IFs excluded). Updated the 318-vs-319
+  table and the NYCHH/Quad view caveat (Quad's 318 now populated; NYCHH's still empty). Design
+  rationale (source writer vs. 317 interceptor) captured on the recursive-item-fulfillments doc.
+  (jcardinal)
 - 2026-08-20 — Recorded the **`childPolicy` asymmetry across the three ASN tracking bridges** (1437
   `MATCH_CREATE`, 1441/1445 `MATCH`) and the resulting per-API `Apis_RecordFields` provisioning
   requirement for any client posting item- or header-level tracking. Compass Canada had zero override

package/knowledge/2.0/apps/toga-blox/INDEX.md

@@ -13,3 +13,4 @@
 | [Talos AI-Assistant Component (launcher + slide-out chat panel)](features/talos-assistant.md) | `Talos` is a **shared, pure-UI** AI-assistant component in `@agilant/toga-blox`: a header launcher button (`TalosLauncher`) plus a slide-out chat panel (`TalosP | toga-blox/src/components/Talos/TalosLauncher.tsx, toga-blox/src/components/Talos/TalosPanel.tsx, toga-blox/src/components/Talos/TalosMessage.tsx, toga-blox/src/components/Talos/types.ts, toga-blox/src/components/Talos/theme.ts, toga-blox/src/components/Talos/helpers.tsx, toga-blox/src/components/Talos/stub.ts, toga-blox/src/components/Talos/Talos.module.css, toga-blox/src/components/Talos/index.ts, toga-blox/src/components/index.ts |
 | [Toaster — host-token styling contract](features/toaster.md) | The blox `Toaster` is a CSS-Module component whose every visual property reads a `--toaster-*` custom property supplied by the **host app**. | toga-blox/src/components/Toaster/Toaster.module.css, toga-blox/src/components/Toaster/Toaster.tsx, toga-blox/src/components/Toaster/ToasterContext.tsx, toga2-commerce/src/styles/index.css, toga2-commerce/src/components/Toasters/ToasterList.tsx |
 | [Dynamic npm Publish Pipeline (branch → channel)](workflows/dynamic-publish-pipeline.md) | How `@agilant/toga-blox` (checkout folder `toga-blox-npm`, registry repo key `toga-blox`) publishes a per-environment npm **channel** (dist-tag) from a `_<mode> | toga-blox/.github/workflows/publish.yml, toga-blox/package.json, toga-blox/src/utils/getFontAwesomeIcon.tsx |
+| [Landing a Large Long-Lived Feature Branch (merge, never rebase)](workflows/landing-a-large-feature-branch.md) | The procedure for landing a long-lived, very large feature branch (months old, hundreds of commits) into `_production` in `toga-blox-npm`. | toga-blox/package.json, toga-blox/.github/workflows/publish.yml |

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

@@ -14,6 +14,7 @@ files:
   - toga-blox/src/utils/getFontAwesomeIcon.tsx
 related:
   - ../architecture.md
+  - ./landing-a-large-feature-branch.md
   - ../../toga2-commerce/workflows/amplify-build-and-deploy.md
 ---
 

package/knowledge/2.0/apps/toga-blox/workflows/landing-a-large-feature-branch.md

@@ -0,0 +1,80 @@
+---
+title: Landing a Large Long-Lived Feature Branch (merge, never rebase)
+framework: "2.0"
+repo: toga-blox
+project: TOGa Blox
+client: shared
+type: workflow
+status: active
+updated: 2026-08-26
+owners: [apeterson]
+files:
+  - toga-blox/package.json
+  - toga-blox/.github/workflows/publish.yml
+related:
+  - ./dynamic-publish-pipeline.md
+  - ../architecture.md
+---
+
+## What it is
+
+The procedure for landing a long-lived, very large feature branch (months old, hundreds of
+commits) into `_production` in `toga-blox-npm`. The decision recorded here is **merge
+`_production` into the feature branch — do not rebase.** Use this doc before starting any
+big-branch integration; the recon step is the transferable part.
+
+## How it works
+
+### 1. Measure the divergence first
+
+```
+git rev-list --left-right --count origin/_production...<branch>
+```
+
+Concrete case (2026-08-26): `feature-new-table` was **281 commits ahead / 8 behind**
+`origin/_production`, forked ~3 months earlier, 530 files changed (+46,795 / −14,209).
+
+### 2. Preview the conflict surface BEFORE merging
+
+```
+git merge-tree $(git merge-base origin/_production <branch>) <branch> origin/_production
+```
+
+This shows the exact conflicting files without touching the working tree, which turns
+"530 changed files" into an actionable list. In the case above it was only **4 files**:
+
+| File | Resolution |
+|---|---|
+| `package-lock.json` | **regenerate**, never hand-merge |
+| a component `index.ts` | added independently on both sides — union the exports |
+| a `utils` file | `_production` held two type fixes — keep them |
+| `.github/workflows/publish.yml` | both sides added publish channels — **keep both sets** |
+
+### 3. Merge `_production` into the feature branch, then PR
+
+1. `git merge origin/_production` **on the feature branch**.
+2. Resolve the (small, known) conflict set **once**.
+3. Open a normal PR: feature → `_production`.
+
+### Why not rebase
+
+Rebasing 281 commits onto `_production` replays every commit, forces the **same conflicts to
+be re-resolved repeatedly**, and **force-rewrites an already-pushed shared branch** — which
+the git-workflow rules forbid on a branch others may have pulled. Merging resolves the
+conflict set exactly once and preserves the pushed history.
+
+## Gotchas
+
+- **Confirm the release version before merging.** The `version` in `package.json` drives what
+  the publish workflow releases. The feature branch carried `1.0.322` while `_production` was
+  at `1.0.314`, so the merge publishes the *branch's* number. See
+  [dynamic-publish-pipeline](./dynamic-publish-pipeline.md) for how CI derives the published
+  version from that base.
+- **Do not read a behind-count as staleness** in this repo — much of it is release plumbing
+  generated on the release branch and never merged back (see the publish-pipeline doc).
+
+## Change history
+- 2026-08-26 — Created. Recorded the merge-not-rebase decision for landing `feature-new-table`
+  (281 ahead / 8 behind, 530 files) into `_production`, and the
+  `rev-list --left-right --count` → `merge-tree` recon pair that narrowed the conflict surface
+  to 4 files before any merge was started. (apeterson)

package/knowledge/INDEX.md

@@ -31,7 +31,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **ai-bdr** (AI-BDR) — 13 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 19 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 12 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
-- **toga-blox** (TOGa Blox) — 11 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
+- **toga-blox** (TOGa Blox) — 12 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)
 
 ## standalone framework

package/knowledge/clients/quad/profile.md

@@ -11,6 +11,7 @@ apps:
   - worker2
   - worker
   - dbchanges2
+  - library
 project: _Underscore
 client: quad
 type: profile
@@ -75,14 +76,23 @@ Client-specific DB change-sets live in `dbchanges2/Client_Quad/`.
   client role 1, id-agnostic + NOT-EXISTS-guarded, beta only). Quad exposes surfaces to role 1 only,
   vs Compass's 1/3/4 — revisit if broader roles are needed. See
   [Surface Resolver](../../2.0/apps/_underscore/features/surface-resolver.md).
-- **LIVE BUG (found 2026-08-17, not fixed): Quad's Tracking # column is empty today.** The two
-  fulfillment views are a direct copy of Compass and read the **item-level bridge 318**, but a
-  fresh count shows `Client_Quad` has **0** rows in 318 and **633** in the **unit-level bridge
-  319**. The views are structurally correct and will never show a tracking number until either they
-  are repointed to 319 or 318 is backfilled. This supersedes the earlier note that Quad's tracking
-  "lives at 317 (~98% coverage)". Repointing is the same shape as the Elite fix
-  (`dbchanges2/Client_Elite/2026-08-17 - FulfillmentTableViews.sql`) - **but choose the bridge from
-  Quad's own row counts, not from Compass**. See
+- **RESOLVED 2026-08-26 (was a LIVE BUG found 2026-08-17): Quad's Tracking # column populated by
+  backfilling 318, not by repointing views.** Quad's fulfillment views correctly read the
+  **item-level bridge 318**, but `Client_Quad` had **0** rows in 318 (and **633** in unit-level
+  319), so the column was blank. Root context: Quad's item fulfillments come from **NetSuite** via
+  the per-client TOGa Supply sync (`App_Api_Toga2::syncItemFulfillmentFromNetsuite`,
+  `worker/crons/sync/toga2/sync_togasupply_quad.php`) — **not** TOGa Supply "Fulfill & Ship" — and a
+  NetSuite item fulfillment carries **exactly one** tracking number that item (318) and unit (319)
+  tracking are meant to **mirror** off the single header (317). Fixed two ways: (1) the source writer
+  now fans that one number to every IF item + serialized unit (see the
+  [per-client sync doc](../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)), so
+  new IFs populate 318/319 going forward; (2) historical rows backfilled by two idempotent,
+  single-tracking-number-only migrations —
+  `dbchanges2/Client_Quad/2026-08-26a - BackfillQuadUnitLevelTrackingSingleTn.sql` (319, 779 rows)
+  and `dbchanges2/Client_Quad/2026-08-26b - BackfillQuadItemLevelTrackingSingleTn.sql` (318, 5,129
+  rows), both run by the dev. **~120 multi-tracking-number IFs were deliberately excluded** (which
+  line/unit shipped under which label is not recorded). This supersedes both the earlier note that
+  Quad's tracking "lives at 317 (~98%)" and the interim proposal to repoint views to 319. See
   [Tracking-Number Bridge Migration](../../2.0/apps/_underscore/features/tracking-number-bridges.md).
 - Quad is one of only **two** clients (with Compass) whose fulfillment views are free of the
   dangling `joinRecordId` 41 / `parentRecordFieldId` 211+321 config, because both were migrated to

package/package.json

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