toga-ai 1.0.277 → 1.0.278

package/knowledge/INDEX.md

@@ -6,6 +6,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **library** (Library) _(framework core)_ — 11 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 13 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/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) — 8 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)

package/knowledge/clients/compass-usa/INDEX.md

@@ -3,6 +3,7 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/PurchaseOrder.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql, dbchanges2/Client_Compass/2026-06-16 - CleanupSA132763CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16b - CleanupSA132743CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16c - BackfillSA132763C40QYUCTracking.sql, dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql, dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
+| [Cost Centers — Unit Locations, numeric-only policy](features/cost-centers.md) | 2.0 | A Compass "cost center" — the value a user picks in commerce and that lands on an order — is **not** a `CostCenters` row. | toga2-commerce/src/pages/Cart/api/CartApi.ts, worker1.5/crons/toga2/compass/import_locations.php, _underscore/Model/Compass/SalesOrder.php, api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-06 - RemoveNonNumericCostCenters.sql |
 | [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql |
 | [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Compass MITS PO Transmission to Vendors](features/mits-po-transmission-to-vendors.md) | 2.0 | The 1.0 worker cron `2_transmit_mits_purchase_orders_to_vendors.php` transmits Compass PurchaseOrders to their vendors (Office Depot, Strategic Systems, Compass | worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, library/app/client/compass.php |

package/knowledge/clients/compass-usa/features/cost-centers.md

@@ -0,0 +1,115 @@
+---
+title: Cost Centers — Unit Locations, numeric-only policy
+framework: "2.0"
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-07-06
+owners: [bala]
+files:
+  - toga2-commerce/src/pages/Cart/api/CartApi.ts
+  - worker1.5/crons/toga2/compass/import_locations.php
+  - _underscore/Model/Compass/SalesOrder.php
+  - api2/Component/Api/V2/V2.php
+  - dbchanges2/Client_Compass/2026-07-06 - RemoveNonNumericCostCenters.sql
+related:
+  - ../profile.md
+  - ../../../2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
+---
+
+## Summary
+A Compass "cost center" — the value a user picks in commerce and that lands on an order — is
+**not** a `CostCenters` row. In `Client_Compass` it is a **Unit-level Location**
+(`locationTypeId = 1`) identified by its **`c_erpSystemEntityId`** custom field. The
+`CostCenters` table (and the `Users_CostCenters` / `Locations_CostCenters` bridges,
+`SalesOrders.costCenterId`, `Users.defaultCostCenterId`) are **empty / vestigial** for Compass
+and unused. As of **2026-07-06**, Compass policy is **numeric-only cost centers**: users may only
+select cost centers whose `c_erpSystemEntityId` is all digits, all existing non-numeric ones are
+soft-deactivated, and the import will never re-create or re-activate a non-numeric one.
+
+This is US Compass only (`Client_Compass`). Compass Canada is explicitly out of scope.
+
+## How it works
+
+### What a cost center actually is
+- A cost center = a **Unit Location** in `Client_Compass.Locations` (`locationTypeId = 1`),
+  keyed by the custom field **`c_erpSystemEntityId`**.
+- `c_erpEntityId` is a **different** field on the Unit row (the unit id) — do not confuse the
+  two. At checkout the chosen cost-center value is written to **`SalesOrders.c_erpEntityId`** as a
+  **plain string, not a foreign key**. `_underscore/Model/Compass/SalesOrder.php` exposes a
+  `_costCenter` computed field.
+- The `CostCenters` table is empty for Compass; nothing reads
+  `Users_CostCenters` / `Locations_CostCenters` / `SalesOrders.costCenterId` /
+  `Users.defaultCostCenterId`.
+
+### The commerce dropdown
+- Built by **`fetchCostCenter()`** in
+  `toga2-commerce/src/pages/Cart/api/CartApi.ts`, which calls
+  `GET /locations` filtered on `c_erpSystemEntityId LIKE %search% AND isActive = 1`, and displays
+  each as `"{c_erpSystemEntityId} - {name}"`.
+- It funnels **both** the cart checkout and the New-User form, so a single filter in
+  `fetchCostCenter` covers both entry points.
+- **api2 does no cost-center validation** — the FE is the only selection gate.
+
+### Where the values come from (import)
+- `worker1.5/crons/toga2/compass/import_locations.php` reads an SFTP file and sets
+  `c_erpSystemEntityId` on Unit rows from **column 16**.
+- Repeated imports have massively **duplicated** cost-center rows (~730× per value).
+
+### Numeric-only enforcement (2026-07-06) — three layers
+1. **Front-end selection block** — in `fetchCostCenter`, on the **search path**
+   (`useSearchOptions === true`), returned locations are filtered to numeric-only cost centers
+   with `/^[0-9]+$/` on `c_erpSystemEntityId.trim()`. The non-search / display path is left
+   untouched (so an already-saved value still renders). Done client-side because api2 rejects a
+   server-side numeric filter (see gotcha) and api2 was out of scope.
+2. **Data cleanup (one-time, reversible)** —
+   `dbchanges2/Client_Compass/2026-07-06 - RemoveNonNumericCostCenters.sql` runs
+   `UPDATE Locations SET isActive = 0` for every active row whose `c_erpSystemEntityId` is
+   non-empty and does **not** match `^[0-9]+$`. **Soft delete (isActive=0), not a hard delete.**
+   ~401,719 active rows across 1,185 distinct non-numeric codes. They then drop out of the
+   commerce lookup automatically via its existing `isActive = 1` filter.
+3. **Import durability guard** — in `import_locations.php`, in **both** Unit branches
+   (new-create and existing-update), after `$isActiveValue` is computed it is forced to `0` when
+   the cost center is non-empty and not `ctype_digit`, so future imports never re-activate or
+   create active non-numeric cost centers.
+
+## Gotchas
+- **api2 cannot do a server-side numeric filter.** The V2 query-string where-parser
+  (`api2/Component/Api/V2/V2.php` → `parseOptionsWhere`) **whitelists operators and rejects
+  `regexp` with a 500**. Any numeric/regex filtering must happen client-side (or via a new
+  operator in api2, which was out of scope here).
+- **Two fields, easy to swap.** `c_erpSystemEntityId` is the cost center (what users pick);
+  `c_erpEntityId` is the unit id and the value that orders record on
+  `SalesOrders.c_erpEntityId`.
+- **Second, possibly-live copy of the import cron not yet guarded.** A second copy exists at
+  `worker/crons/toga2/compass/DOA_Scripts/import_locations.php` (appears disabled / "DOA"). It
+  did **not** receive the numeric guard — **confirm whether it is live** before trusting the
+  guard to be complete.
+- Non-numeric cost centers include both number+alphabet combos (e.g. `10007A`, `224GT`) and
+  letters-only codes (e.g. `EAGLE`, `TAMU`). All are retired in favor of numeric-only.
+
+## Safety verification (before deactivation, prod Client_Compass)
+Deactivation was proven safe against prod data:
+- **0** users (active or inactive, via `Users.locationId`), **0** sales orders / SO items /
+  purchase orders / item fulfillments / item receipts / transfer orders / inventory adjustments /
+  tickets / contacts / child locations reference these non-numeric Unit locations.
+- Only **1,180** `Locations_Addresses` links point at them (harmless, left intact).
+- Only **2** sales orders ever used a non-numeric cost-center value (stored as string on
+  `SalesOrders.c_erpEntityId`, unaffected by deactivating the Location).
+- **0** active users have a non-numeric `c_erpEntityId`, so no cost-center display goes blank.
+- Proven end-to-end in dev-sandbox: after the migration, active non-numeric rows = **0** (all
+  1,185 codes incl. the 725 number+alphabet combos) while pure-numeric stayed untouched at
+  **440,005** active rows.
+
+## Scope constraints (from the developer)
+- Do **not** change anything in `api2`.
+- Do **not** hard-delete — use `isActive = 0` (reversible).
+- **US Compass only** (`Client_Compass`); Compass Canada is out of scope.
+
+## Change history
+- 2026-07-06 — Established numeric-only cost-center policy across three layers: FE `fetchCostCenter`
+  search-path filter (`/^[0-9]+$/`), one-time `RemoveNonNumericCostCenters.sql` soft-deactivation
+  (~401,719 rows / 1,185 codes), and an `import_locations.php` guard forcing `isActive=0` on
+  non-`ctype_digit` cost centers in both Unit branches. Documented that a Compass cost center is a
+  Unit Location keyed by `c_erpSystemEntityId` (not the vestigial `CostCenters` table). (bala)

package/knowledge/clients/compass-usa/profile.md

@@ -8,16 +8,18 @@ apps:
   - toga25-supply
   - toga2-commerce
   - worker
+  - worker1.5
   - dbchanges2
 project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-06-30
+updated: 2026-07-06
 owners: [jcardinal, bala, tcox]
 files: []
 related:
   - features/asn-to-item-fulfillment.md
+  - features/cost-centers.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
 ---
@@ -34,7 +36,9 @@ separate, related client (see its own profile).
 - **2.0:** `_underscore` backend, prod schema `Client_Compass` (worker link `db_compass`).
   Client-specific model overrides live under `_underscore/Model/Compass/`.
 - **1.0:** worker crons under `worker/crons/toga2/compass/` handle email-based imports and
-  notifications.
+  notifications. A separate **`worker1.5`** repo (also App_/1.0-style) runs the SFTP location
+  import (`worker1.5/crons/toga2/compass/import_locations.php`) that seeds Unit Locations /
+  cost centers.
 - Storefront: compass.togacommerce.com / compass.togahub.com. The storefront app repo is
   **`toga2-commerce`** (2.0, consumes api2).
 
@@ -56,6 +60,9 @@ separate, related client (see its own profile).
 ## Key features (this client)
 - [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) — the
   `_Model_Compass_AdvanceShippingNotice::postPost` handler.
+- [Cost Centers (Unit Locations, numeric-only)](features/cost-centers.md) — what a Compass
+  "cost center" actually is (a Unit Location keyed by `c_erpSystemEntityId`), and the
+  numeric-only selection/import/data policy (2026-07-06).
 
 ## Notes
 - **Order status is shipped-only (2026-06-30).** Compass imports all IF stages

package/knowledge/registry.json

@@ -41,6 +41,15 @@
     "role": "app",
     "dependsOn": []
   },
+  {
+    "repo": "worker1.5",
+    "project": "Worker 1.5",
+    "framework": "1.0",
+    "role": "app",
+    "dependsOn": [
+      "library"
+    ]
+  },
   {
     "repo": "toga2-supply",
     "project": "TOGa Supply",

package/package.json

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