toga-ai 1.0.497 → 1.0.498

package/knowledge/2.0/apps/_underscore/features/error-reporting-issue-event.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-01
+updated: 2026-08-03
 owners: ["dfranks", "jcardinal"]
 files:
   - _underscore/Error.php
@@ -87,6 +87,28 @@ produced a different hash on every request — dedup never actually worked.
 cannot orphan a curated Issue: an admin repoints the new fingerprint at the existing Issue
 from the Tools console to merge them.
 
+### Where each exception class routes (the class you throw IS the routing decision)
+
+| Thrown class | HTTP | Sentry | `Logs.Issue` | Fingerprint / routing |
+|---|---|---|---|---|
+| `_Exception_Validation` | **400** | no | **no** | n/a — bad client input. Still leaves a full `Logs.Api` row (see [api2 request logging](../../api2/features/request-logging.md)) |
+| `_Exception_Business` | **500** | yes | **yes** | stable `issueKey` (refactor-immune) → business recipients configured in the Tools console |
+| plain global `Exception` | **500** | yes | **yes** | **trace**-based fingerprint (moves when code moves) → developer ClickUp task |
+| `_Exception` | — | — | — | **never throw it deliberately** (below) |
+
+Verified against `api2/Controller/Index.php` (≈L205-245, L369-377) and `_Error.php`
+(`captureException` ≈L222-265, `buildFingerprint` ≈L455-490) on **2026-08-03**, while TRUE-78188
+was still in flight — **re-verify against `Controller/Index.php`** rather than trusting the table
+blindly.
+
+**`_Exception` must never appear at a deliberate throw site.** Its constructor takes **five**
+required args (`errorNumber`, `errorString`, `errorFile`, `errorLine`, `trace`) because it is an
+*error-handler shape* populated by `_Error` from `set_error_handler` context — not a general
+exception. `throw new _Exception('msg')` raises an `ArgumentCountError` **before** the intended
+exception is ever constructed, so the real signal is destroyed. Jeff states this rationale in the
+`Exception/Business.php` docblock. Census in `_underscore`: 173 plain `throw new Exception` vs 14
+`_Exception`.
+
 ### `_Exception_Business` — identity immune to refactoring
 
 `_underscore/Exception/Business.php` carries a stable `issueKey` plus a `minimumUrgency` floor.
@@ -267,6 +289,12 @@ clientUserId). **Neither was built.** As built instead:
 
 ## Change history
 
+- 2026-08-03 — Added the **exception-class routing table** (`_Exception_Validation` → 400/no
+  Issue; `_Exception_Business` → 500 + `issueKey`-fingerprinted Issue to business recipients;
+  plain `Exception` → 500 + trace-fingerprinted Issue to a developer task) and recorded that
+  **`_Exception` must never be thrown deliberately** — its 5-arg error-handler constructor raises
+  `ArgumentCountError` first. Verified against `Controller/Index.php` / `_Error.php` while
+  TRUE-78188 was still in flight. (dfranks)
 - 2026-08-01 — **Decided: `Logs` cluster tables use SINGULAR names.** Renamed all six
   post-deployment (`Issues`→`Issue`, `Events`→`Event`, `IssueFingerprints`→`IssueFingerprint`,
   `IssueClickupTasks`→`IssueClickupTask`, `IssueEmailAddresses`→`IssueEmailAddress`,

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

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: architecture
 status: active
-updated: 2026-07-28
-owners: [jcardinal, bala, mhammontree]
+updated: 2026-08-03
+owners: [jcardinal, bala, mhammontree, dfranks]
 files:
   - api2/Controller/Index.php
   - api2/Component/Api/V2/V2.php
@@ -102,6 +102,12 @@ One ~2,000-line `execute()` then `processRoutePairs()`:
    `public`, `delegator`/`encrypted`. JWTs HS256, `sub` access/refresh (access 3600s,
    refresh 30d); signing secret **rotated** with current+previous accepted across the
    boundary. The JWT `id` claim carries the full identity used for ACL.
+   **`/v2/auth/oauth` credential transport:** OAuth 2.0 `client_credentials`. `client_id` +
+   `client_secret` may arrive as **HTTP Basic** *or* as POST body fields — **Basic takes
+   priority** when both are present. `scope` is **required**; `grant_type` is **optional** and
+   defaults to `client_credentials` (accepted: `client_credentials`, `password`,
+   `refresh_token`). The call mints a JWT; subsequent requests carry `Authorization: Bearer`.
+   (`api2/Component/Api/V2/V2.php` L414-460.)
 4. **Response envelope** — `{transactionId, timestamp, authority, audience, isSuccess,
    status, error, messages[], meta{}, data{}}`; `isSuccess` = 2xx status.
 5. **Transaction logging** — every request logged (to client/core Logs DB, or as a JSONL

package/knowledge/2.0/apps/api2/features/request-logging.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-29
+updated: 2026-08-03
 owners: ["mhammontree", "dfranks"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -46,6 +46,21 @@ In `api2/Component/Api/V2/V2.php` (~L2168) every request is logged and routed:
 - There is also a **config-gated branch** (~L2166): when `_Config::api('log_filepath')` is set,
   the log entry is written to a **file** on the host instead of the DB.
 
+### A rejected request (HTTP 400) is NOT unlogged
+
+`api2/Controller/Index.php` (L369-377) handles a non-success response by **committing** the
+`DB_LOGS` and `DB_CLIENT_LOGS` transactions and rolling back **only** the business-data
+transaction. A rejection therefore still writes a **full `Client_Logs.Api` / `Core_Logs.Api`
+row** — request payload, response payload, `apiId`, `sourceIp`, `transactionId` — while the
+business row is discarded.
+
+So a 400 **is** SQL-queryable and attributable to the calling credential. What a 400 lacks is a
+`Logs.Issue` row: **no alerting, no aggregation, no owner** (see
+[Error Reporting — Issue/Event Capture](../../_underscore/features/error-reporting-issue-event.md)).
+That is the deciding factor when choosing between `_Exception_Validation` (400, logged as a
+request, no Issue) and `_Exception_Business` (500, Sentry + a routed Issue). Do **not** reach for
+`_Exception_Business` merely to "make sure the rejection is recorded" — it already is.
+
 ## Blind spots when auditing a client's API traffic
 
 Looking only at `Logs_<Client>.Api` misses four sources:
@@ -95,6 +110,11 @@ re-send.
 
 ## Change history
 
+- 2026-08-03 — Corrected a common wrong assumption: an **HTTP 400 leaves a full log row**.
+  `Controller/Index.php` L369-377 commits `DB_LOGS`/`DB_CLIENT_LOGS` and rolls back only the
+  business transaction, so rejections are queryable and attributable to the credential; what they
+  lack is a `Logs.Issue` (no alerting/owner) — the deciding factor between `_Exception_Validation`
+  and `_Exception_Business`. (dfranks)
 - 2026-07-29 — Documented (TRUE-80179) that the core/writer `Logs.Api` retains the **full original
   `requestPayload`** on failed writes, making it a **replayable backlog source** and a scope
   diagnostic: dedupe to one-per-contract with a window function on

package/knowledge/2.0/standards/backend-php.md

@@ -5,8 +5,8 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-08-01
-owners: [jcardinal, mhammontree]
+updated: 2026-08-03
+owners: [jcardinal, mhammontree, dfranks]
 files: []
 related:
   - ../apps/_underscore/architecture.md
@@ -573,15 +573,42 @@ $c = 'Hello ' . $world;
 
 * Always use exceptions to handle unexpected conditions.
 
-### Interceptor / model client-error rejections → throw `_Exception_Validation`, not `_Exception`
-
-A hard-block raised inside a pre/post interceptor (or model op) to reject a **bad client request**
-must throw **`_Exception_Validation`** (`_underscore/Exception/Validation.php`), which
-`api2/Controller/Index.php` (≈lines 204–222) maps to `DEFINED_MESSAGE_ERROR_BAD_REQUEST` →
-**HTTP 400** with the message carried in the response envelope (so the front end can drive a
-toaster). Throwing a plain `_Exception` yields an **HTTP 500 + stack trace** — wrong for a
-client-input rejection and an information leak. First applied: the three Rate WH hard-blocks
-(missing / invalid / duplicate service address), TRUE-79533.
+### Choosing an exception class is a ROUTING decision, not style
+
+At a deliberate throw site the class you pick determines the HTTP status, whether Sentry sees
+it, whether a `Logs.Issue` is created, how that Issue is fingerprinted, and **who gets
+notified**. Pick deliberately:
+
+| Throw this | When | HTTP | Sentry | `Logs.Issue` | Goes to |
+|---|---|---|---|---|---|
+| `_Exception_Validation` | bad **client input** — a hard-block in a pre/post interceptor or model op | **400** | no | no | the caller, via the response envelope (front end can toast it) |
+| `_Exception_Business` | a **business condition a business user can act on and a developer cannot fix** | 500 | yes | yes, keyed by a stable `issueKey` | business recipients configured in the Tools `/errors` console |
+| plain global `Exception` | a genuine **code defect / unexpected state** | 500 | yes | yes, fingerprinted by **trace** | a developer ClickUp task |
+
+`_Exception_Business`'s constructor is `(issueKey, message, minimumUrgency)`. The `issueKey` is
+the fingerprint, so the Issue's identity survives refactoring; a plain `Exception`'s
+trace-based fingerprint changes when the code moves.
+
+**A 400 is not "unlogged."** `api2/Controller/Index.php` commits the log transactions and rolls
+back only the business transaction, so a rejection still writes a full `Logs.Api` row (request
++ response payload, `apiId`, `sourceIp`, `transactionId`). What a 400 lacks is a `Logs.Issue` —
+no alerting, no aggregation, no owner. Do not upgrade a client-input rejection to
+`_Exception_Business` just to "make sure it's recorded."
+
+### NEVER `throw new _Exception(...)`
+
+`_Exception` is an **error-handler shape**, not a general exception: its constructor requires
+five arguments (`errorNumber`, `errorString`, `errorFile`, `errorLine`, `trace`) because
+`_Error` populates it from `set_error_handler` context. `throw new _Exception('msg')` raises an
+`ArgumentCountError` **before** your exception is ever constructed, destroying the real signal.
+Throwing a plain `_Exception` also yields an HTTP 500 + stack trace — wrong for a client-input
+rejection and an information leak. Census in `_underscore`: 173 plain `throw new Exception` vs
+14 `_Exception`.
+
+Sources: `_underscore/Exception.php`, `Exception/Validation.php`, `Exception/Business.php`,
+`_underscore/Error.php`, `api2/Controller/Index.php`. First applied: the three Rate WH
+hard-blocks (TRUE-79533). Taxonomy verified 2026-08-03 **while TRUE-78188 was still in flight** —
+re-verify against `Controller/Index.php` before relying on it.
 
 ### Comprehensive Error Handling
 

package/knowledge/clients/compass-usa/features/mits-po-to-so-item-linking.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-07-13
-owners: ["jcardinal", "rgirish"]
+updated: 2026-08-03
+owners: ["jcardinal", "rgirish", "dfranks"]
 files:
   - _underscore/Model/Compass/PurchaseOrder.php
   - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
@@ -29,6 +29,56 @@ production data-integrity bug.
 - USA/Canada subclasses (`Model/Compass/Usa|Canada/PurchaseOrder.php`) are empty and inherit
   this behavior — edit the parent.
 
+## Who actually calls `POST /v2/purchase-orders` (MITS is NOT the only caller)
+
+`/v2/purchase-orders` for Compass is a **shared endpoint with two unrelated inbound channels**,
+distinguished in `Core.ClientApiIdentities` (clientId 2). **The channels are told apart by the
+FIELD NAME, not by whether a MITS SO is present at all:**
+
+| Identity | Channel | SO field sent | Values | `purchaseOrderItems` |
+|---|---|---|---|---|
+| `153531108` | MITS | **`mitsSalesOrder`** (unprefixed) | only `SA…` or `MR…` | always present |
+| `COMPASS-CXML` | cXML / EDI | **`c_mitsSalesOrder`** (`c_`-prefixed) | numeric, e.g. `472981379001` | present |
+| `COMPASS-CXML` | cXML / EDI | **neither field** | — | often **absent entirely** |
+
+Measured over 60 days of inbound `POST /v2/purchase-orders` (`Logs_Compass.Api`):
+- **MITS — 4,547 posts, 100% carry the unprefixed `mitsSalesOrder`**; `SA` 2,928, `MR` 1,619.
+  Never `MA`, never any other prefix. **No `SA` value has ever been sent by a non-MITS caller.**
+- **COMPASS-CXML — 2,697 posts**: 2,455 carry `c_mitsSalesOrder`, and **242 carry neither field**.
+  In a 30-day slice: 1,508 `c_mitsSalesOrder` posts all had items; **136 posts had neither field
+  and no `purchaseOrderItems` key** — the legitimate header-first EDI POs.
+- Compass **Canada** posts under a **separate identity (`409531`)**, so never hardcode an
+  identity id.
+
+**Consequences for any validation added to this endpoint:**
+- **The unprefixed `mitsSalesOrder` is the MITS marker** — not the identity id, and not the
+  `SA`/`MR` prefix. Supporting evidence: `prePost` reads `$payload->mitsSalesOrder`; the only
+  `c_mitsSalesOrder` occurrence in the codebase is the model field declaration at
+  `_underscore/Model/Compass/PurchaseOrder.php:18`; and `Core.ApiPayloadInterceptors` has **no
+  rows for `recordId = 17`** (the `purchase-orders` record), so nothing rewrites field names in
+  flight.
+- A "reject purchase orders with zero line items" rule keyed on the **unprefixed** field cannot
+  touch the 136 item-less EDI posts — they carry neither field. Gating on **item count alone**
+  would reject all of them.
+- **`MA` orders never arrive from MITS.** Compass creates them manually; they go to ODP, reach us
+  over EDI, and land on an exception report for manual NetSuite entry. (An earlier belief that MA
+  is a third MITS prefix to filter on is wrong.)
+
+> **⚠ Querying trap — a substring match on `mitsSalesOrder` conflates the two callers**, because
+> `c_mitsSalesOrder` *contains* it. Anyone characterising this traffic from `Logs_Compass.Api`
+> must match the **exact key**; a pattern like `"mitsSalesOrder":"` also silently misses the
+> prefixed form, which is how this session first reached the wrong conclusion that cXML never
+> sends an SO reference. Second trap: payloads appear **both minified**
+> (`"mitsSalesOrder":"MR…"`) **and pretty-printed** (`"mitsSalesOrder": "MR…"`, space after the
+> colon), so a naive pattern under-counts a second way.
+
+> **OPEN / UNVERIFIED:** it is **not** confirmed whether the 2.0 framework strips the `c_` prefix
+> when populating `$payload` for an interceptor. If it does, cXML requests carrying
+> `c_mitsSalesOrder` would also enter a guard keyed on `$payload->mitsSalesOrder`. Harmless while
+> those posts all carry items, but a future item-less cXML post carrying `c_mitsSalesOrder` would
+> then be wrongly rejected. This **cannot be settled from logs** — it needs a dev-environment
+> check.
+
 ## How it works
 - **SA orders (normal):** each inbound PO item carries `createdFromSalesOrderItem.lineNumber`
   (the MITS line, which includes configuration-line offsets). `prePost` remaps it to the real
@@ -50,6 +100,17 @@ production data-integrity bug.
   because SA/MR originate in Compass (their Compass SO+items pre-exist) whereas MA is
   ODP-originated, so nothing else would populate it.
 
+### MR and SA consume PO line items differently (asymmetry inside one method)
+- **MR** — `handleMrOrder` (≈L54-57) **silently skips** any item whose
+  `vendorItem->item->partNumber` is empty while building `salesOrderItems`. So an MR PO whose
+  lines *all* lack a `partNumber` passes a naive `count($payload->purchaseOrderItems) > 0` check
+  and still creates an **empty Sales Order**. A "usable item" filter for MR must therefore test
+  `partNumber`, not array length.
+- **SA** — items are linked via `createdFromSalesOrderItem` →
+  `salesOrderItemPurchaseOrderItems`, and the quantity cross-check (≈L318-324) explicitly
+  `continue`s past `partNumber`-less lines rather than discarding them. Applying the MR
+  `partNumber` filter to SA would **reject valid orders**.
+
 ## Data model
 - `SalesOrderItems_PurchaseOrderItems` (`Client_Compass`): `uuid`, `salesOrderItemId`,
   `purchaseOrderItemId`. One row per (SO item, PO item) the PO fulfills.
@@ -59,6 +120,15 @@ production data-integrity bug.
 USA and Canada share the parent handler unchanged.
 
 ## Gotchas / known issues
+- **SQL injection in `prePost` (OPEN as of 2026-08-03).** `_underscore/Model/Compass/PurchaseOrder.php`
+  **L232** interpolates the raw client payload straight into SQL:
+  `WHERE SalesOrders.number LIKE '{$payload->mitsSalesOrder}'` — no escape, no cast. The **same
+  value is escaped at L301**, so the file is internally inconsistent and the correct pattern is
+  already present. Fix with `_Database::escape()` per the 2.0 back-end standard. Reachable only by
+  a caller holding valid Compass API credentials (OAuth2 `client_credentials`), so it is **not**
+  anonymous or internet-facing — normal priority, not an emergency. Separately, five sites in this
+  file (L148, L301, L461, L462, L471) use **`addslashes()`** where the standard requires
+  `_Database::escape()`.
 - **Spurious cross-part links from the `postPost` lineNumber join (fixed 2026-06-11).** The
   `postPost` link pass matched `SalesOrderItems.lineNumber = PurchaseOrderItems.lineNumber`
   for *all* orders. For SA orders that is wrong: PO line numbers are PO-local, so whenever an
@@ -137,6 +207,16 @@ USA and Canada share the parent handler unchanged.
   need item backfill from the sibling ODP SO first).
 
 ## Change history
+- 2026-08-03 — Documented that `/v2/purchase-orders` has **two** Compass inbound channels (MITS
+  `153531108` vs `COMPASS-CXML`; Canada is a third identity `409531`), told apart by **field
+  name**: unprefixed `mitsSalesOrder` = MITS, `c_mitsSalesOrder` = cXML, neither = the item-less
+  header-first EDI POs. So a zero-item rejection keyed on the unprefixed field is safe, while
+  gating on item count alone is not. Recorded the substring/pretty-print querying traps that
+  conflate the two callers, and left open whether the framework strips the `c_` prefix for
+  interceptor payloads. Also recorded the MR-vs-SA `partNumber` item-consumption
+  asymmetry (MR silently skips `partNumber`-less lines → empty SO despite `count() > 0`) and an
+  open SQL-injection at L232 plus five `addslashes()` sites. Corrects the earlier belief that
+  `MA` arrives from MITS. (dfranks)
 - 2026-07-13 — Fixed empty MA orders: the 3a ODP-PO-import cron's new-SO branch now builds
   `salesOrderItems` from the 850 PO items (the MA back-linking block excludes MA by design).
   Forward-only; 192 historical empties still need item backfill. (rgirish)

package/package.json

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