toga-ai 1.0.277 → 1.0.279

package/knowledge/2.0/apps/_underscore/features/per-client-database-connections.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-06-18
-owners: ["dfranks"]
+owners: ["dfranks", "jcardinal"]
 files:
   - _underscore/Database.php
   - _underscore/ApiRequest.php
@@ -62,6 +62,17 @@ Engine InnoDB, `utf8mb4_unicode_ci`.
 
 None — uniform across clients; only the `<Id>` suffix differs.
 
+## Related shared clusters (not per-client)
+
+Alongside the three per-client aliases and the shared **Core** cluster, a dedicated shared
+**Cache** cluster was added (2026-07-07): `Core.Databases` id **145**, `_underscore` alias
+`DB_CACHE`, `CACHE_DATABASE_ID = 145`. It is modeled like Core (a single shared cluster, **not**
+per-client), region-aware (1=us-east-1, 2=us-west-2, 3=eu-west-1) with per-region `DatabaseHosts`
+(`hostCluster` DevOps-TBD). It exists to keep cache churn off Core and backs the api2
+[multi-client data retrieval](../../api2/features/cross-client-data-retrieval.md) engine. Boot
+registration is region-aware in `api2/Controller/Index.php`; the alias const is in `api2/_.php`.
+`Records.ttlCache` (TINYINT UNSIGNED, default 15) governs cache TTL.
+
 ## Gotchas / known issues
 
 - **The "logs DB write trap" (local dev).** A laptop usually imports only `Client_<Id>`, not
@@ -82,6 +93,8 @@ None — uniform across clients; only the `<Id>` suffix differs.
 
 ## Change history
 
+- 2026-07-07 — Noted the new shared **Cache** cluster (`Databases` id 145, alias `DB_CACHE`,
+  region-aware) added for the api2 cross-client retrieval engine. (jcardinal)
 - 2026-06-18 — Documented after the `Logs_Growrk`/`Logs_Aig` local 500s while testing the
   NetSuite TOGa Supply wrappers; created the missing local log schemas structure-only. (dfranks)
 

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

@@ -3,6 +3,8 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
+| [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | A single authenticated V2 GET listing can return records across **many** clients (designed for 1000+) that the caller is entitled to, honoring **each target cli | api2/Component/Api/CrossClient/CrossClient.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, api2/_.php, _underscore/Model/Cache/Table.php, _underscore/Model/Cache/Tables/Client.php, dbchanges2/Core/2026-06-30b - CacheClusterRegistrationAndRecordTtl.sql, dbchanges2/Cache/2026-06-30a - MultiClientCacheTables.sql |
+| [Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)](features/encrypted-user-uuid-auth-handoff.md) | `POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**: given an encrypted `{client, user}` UUID pair, it mints a fr | api2/Component/Api/CrossClient/CrossClient.php |
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, expanding later) in multiple languages without forking the schema or breaking English consume | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql |
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |
 | [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |

package/knowledge/2.0/apps/api2/features/cross-client-data-retrieval.md

@@ -0,0 +1,120 @@
+---
+title: Multi-Client (Cross-Client) Data Retrieval
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: draft
+updated: 2026-07-07
+owners: [jcardinal]
+files:
+  - api2/Component/Api/CrossClient/CrossClient.php
+  - api2/Component/Api/V2/V2.php
+  - api2/Controller/Index.php
+  - api2/_.php
+  - _underscore/Model/Cache/Table.php
+  - _underscore/Model/Cache/Tables/Client.php
+  - dbchanges2/Core/2026-06-30b - CacheClusterRegistrationAndRecordTtl.sql
+  - dbchanges2/Cache/2026-06-30a - MultiClientCacheTables.sql
+related:
+  - ./encrypted-user-uuid-auth-handoff.md
+  - ../../_underscore/features/per-client-database-connections.md
+  - ../../_underscore/features/acl-permission-chain.md
+---
+
+## What it is
+
+A single authenticated V2 GET listing can return records across **many** clients (designed for
+1000+) that the caller is entitled to, honoring **each target client's own ACL**. It is triggered
+by a non-empty `client` query-string option on a GET listing; without that option the ordinary
+single-client path is byte-for-byte unchanged.
+
+Because client DBs live on **different clusters**, a cross-DB JOIN/UNION is impossible. The feature
+is a **scatter-gather** engine: it fans out to each entitled client's own V2 API, merges the
+streams, and caches the result per-user on a dedicated Cache cluster.
+
+> **Status: code-complete + reviewer-hardened, NOT yet runtime-tested.** Result rows are stored as
+> a JSON `rowData` column (deliberate v1 deviation from real typed columns). Phases 4 (single-record
+> cross-client), 5 (worker2 page-ahead prefetch), and 7 (live load test / verify `_Query`/`_Database`
+> method names against a running instance) are open. Per-client token hardening (§0) is an
+> owner-accepted deferred risk.
+
+## How it works
+
+Entry point is `_Component_Api_CrossClient` (`api2/Component/Api/CrossClient/CrossClient.php`),
+delegated to from a guard at the **top** of the `ACTION__LIST` case in
+`_Component_Api_V2::processRoutePairs()`: when `isCrossClientRequest($httpOptions)` is true (a
+non-empty `client` option), it calls `handleListing()`, merges result rows into `$outData` and meta
+into `$this->response->meta`, sets status 200, and breaks. The guard is **inert** on ordinary
+single-client GETs.
+
+1. **resolveScope** — the caller's entitled clients resolve via the `Users_Clients` bridge
+   (`Users.homeClientUserId` maps one home user to per-client user records across tenant DBs); each
+   target yields a minted per-client identity.
+2. **queryHash** — SHA-256 of the normalized query; the cache key.
+3. **Build lock** — a named `GET_LOCK` (`tablecache:<clientId>:<userId>:<hash>`) prevents duplicate
+   concurrent builds.
+4. **Fan out** — a two-phase concurrent HTTP handshake per client (see
+   [encrypted-user-uuid-auth-handoff](./encrypted-user-uuid-auth-handoff.md)): Phase A mints an
+   access token, Phase B issues the authenticated GET.
+5. **Watermark k-way merge** — client streams are merged into a globally-correct sort order using a
+   watermark (`safeRowCount`/`keyBeyond`); a `deepen` loop pulls more from lagging streams, capped
+   by a 50-iteration backstop.
+6. **Cache build/serve** — rows are cached on the Cache cluster; `servePage` emits a keyset page.
+
+### Total order + keyset pagination (V2 query builder, Phase 0a/0b)
+
+Cross-client global sort correctness requires each client's stream to be a **total order**:
+- **0a** — the LIST query builder always appends a **primary-key ASC tiebreaker** to `ORDER BY`
+  (also improves single-client determinism).
+- **0b** — a new keyset/seek pagination mode runs alongside offset mode; it engages **only** when
+  the caller passes `seekValue` + `seekId` options. It injects a seek `WHERE` predicate (V2.php
+  ~line 3782) and switches `LIMIT` from offset to `recordsPerPage` (~line 3861). The composite
+  unique sort key is `(sortfield, clientId, primaryKeyId)`.
+
+### Query-string forwarding (load-bearing gotcha)
+
+V2 parses list options (`fields`/`where`/`sort`/`join`/`group`…) from the **raw** query-string
+values into structured `$httpOptions` — re-serializing the parsed array does **not** round-trip.
+The fan-out therefore forwards the caller's **original** `$_SERVER['QUERY_STRING']` through an
+explicit **allowlist** of forwardable keys (`fields, where, sort, group, distinct, join, ojoin,
+depth, calcDepth, _`), re-stamping `recordsPerPage`, `seekValue`/`seekId`, and a fresh
+`transactionId` per client. The allowlist (not a denylist) prevents internal flags like
+`surface`/`debug` from leaking into sub-requests.
+
+### Cache cluster
+
+A new dedicated **Cache** cluster (Core-style shared cluster, `Databases` id **145**, alias
+`DB_CACHE`, `CACHE_DATABASE_ID = 145`) keeps cache churn off Core. It is region-aware
+(1=us-east-1, 2=us-west-2, 3=eu-west-1) with per-region `DatabaseHosts`; `hostCluster` values are
+DevOps TBD. Boot registration lives in `api2/Controller/Index.php`; the alias const in `api2/_.php`.
+See [per-client-database-connections](../../_underscore/features/per-client-database-connections.md)
+for how it sits among the shared/per-client clusters.
+
+## Key rules
+
+- **Triggered only by a non-empty `client` option** — single-client GETs are unaffected.
+- **Each target client's ACL is honored** via a minted per-client identity, not a global aggregate
+  view. This preserves ACL fidelity across tenants.
+- **Every outbound sub-request needs its own globally-unique `transactionId`** — the API enforces
+  uniqueness; it is the load-bearing idempotency/audit key across Core + Client logs.
+- **Forward the original query string, not the parsed options** — parsed `$httpOptions` do not
+  round-trip through re-serialization.
+- `MAX_CONCURRENT_CLIENT_FETCHES = 25` bounds fan-out concurrency (PHP-FPM has no in-process
+  concurrency, so transport is an HTTP pool via `curl_multi`).
+
+## Gotchas
+
+- **Cross-client output row shape must match single-client.** Served rows are cast to `(object)` in
+  `servePage` so payload interceptors reading `$row->prop` don't throw — the single-client path
+  emits `(object)$outRow`.
+- **The X-Cross-Client / X-Cross-User custom-header transport was a dead stub** — the V2 engine
+  never reads such headers. The real transport is the two-phase encrypted-UUID auth handshake.
+- **`curl_multi` busy-spin guard** — both multi loops `usleep(100)` when
+  `curl_multi_select() === -1`.
+
+## Change history
+- 2026-07-07 — Initial capture: scatter-gather cross-client retrieval engine (orchestrator, watermark
+  k-way merge, keyset pagination Phase 0a/0b, `client`-option delegation, Cache cluster id 145).
+  Code-complete + reviewer-hardened, not yet runtime-tested. (jcardinal)

package/knowledge/2.0/apps/api2/features/encrypted-user-uuid-auth-handoff.md

@@ -0,0 +1,54 @@
+---
+title: Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-07
+owners: [jcardinal]
+files:
+  - api2/Component/Api/CrossClient/CrossClient.php
+related:
+  - ./cross-client-data-retrieval.md
+---
+
+## What it is
+
+`POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**:
+given an encrypted `{client, user}` UUID pair, it mints a fresh access token for that client+user
+without the caller holding the target client's credentials. It is what the scatter-gather
+[cross-client data retrieval](./cross-client-data-retrieval.md) engine uses to authenticate each
+per-client sub-request.
+
+## How it works
+
+- The encrypted `{client, user}` pairs are produced during **normal** auth: `/auth/api` and
+  `/auth/login` emit them as `data.clients[].encrypted.{client, user}`, encrypted with
+  `KEY_API_SECRET_REFRESH_TOKEN`.
+- The route reads `$httpPayload->client` and `$httpPayload->user` (the encrypted UUIDs) from the
+  **JSON body**, decrypts them against the API secret rotation keys, and mints an access token.
+- The token is returned at `response data.tokens.access`.
+
+### Two-phase fan-out handshake (as used by cross-client retrieval)
+
+- **Phase A** — concurrent `POST /auth/encrypted-user-uuid` with the minted `{client, user}`
+  encrypted-UUID pair in the JSON body → read `data.tokens.access`.
+- **Phase B** — concurrent authenticated `GET` with `Authorization: Bearer <token>`.
+- Every request (both phases) carries its own globally-unique `transactionId` (query string); the
+  API enforces uniqueness.
+
+## Key rules
+
+- **Identity source of truth is the `Users_Clients` bridge** — `Users.homeClientUserId` maps one
+  home user to its per-client user records across tenant DBs; that is where the per-client UUIDs
+  come from.
+- **Never store or log the encrypted UUID values** — they are credentials; document where they live
+  (`data.clients[].encrypted`), never the value.
+- The encrypted pairs are encrypted with `KEY_API_SECRET_REFRESH_TOKEN` (rotation keys); decryption
+  tolerates the rotation set.
+
+## Change history
+- 2026-07-07 — Documented `/auth/encrypted-user-uuid` as the cross-client/SSO identity-handoff route
+  and its two-phase use by the cross-client fan-out engine. (jcardinal)

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)
@@ -18,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 22 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 27 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 7 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 9 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/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.279",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",