toga-ai 1.0.428 → 1.0.430

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

@@ -5,6 +5,7 @@
 | [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 |
+| [Health-check endpoint (/health liveness short-circuit)](features/health-check-endpoint.md) | `_Controller_Index::api()` short-circuits **liveness/health-probe** requests to an HTTP 200 **before** any routing, DB bootstrap, or V2 engine work runs. | api2/Controller/Index.php |
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, plus item **feature** text — `Features.name`, `ItemCategoryFeatureGroups.name`, `ItemFeatures | 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, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql |
 | [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php |
 | [Record Scripts (computed/aggregate /v2 endpoints — the authoring contract)](features/record-scripts.md) | In api2 you almost never write a controller. | api2/Component/Api/V2/V2.php, _underscore/Model/Team/Sprint.php |

package/knowledge/2.0/apps/api2/features/health-check-endpoint.md

@@ -0,0 +1,64 @@
+---
+title: "Health-check endpoint (/health liveness short-circuit)"
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-24
+owners: [jcardinal]
+files:
+  - api2/Controller/Index.php
+related:
+  - ../architecture.md
+  - v2-api-error-codes.md
+---
+
+## Summary
+
+`_Controller_Index::api()` short-circuits **liveness/health-probe** requests to an HTTP 200
+**before** any routing, DB bootstrap, or V2 engine work runs. EB/LB (Elastic Beanstalk /
+load balancer) probes depend on this always returning 200 cheaply — the architecture doc's
+critical rule is literally "Don't break `/health`". This doc records the **matching contract**
+so a teammate doesn't reintroduce a brittle exact-string check.
+
+## How it works
+
+The short-circuit lives at the top of `Index.php::api()`, before host dispatch and before the
+Core/Logs DB bootstrap. It matches against a class constant:
+
+```php
+const HEALTH_CHECK_ROUTES = ['/health', '/v2/health'];
+```
+
+The incoming path is **normalized** before comparison — lowercased, query string stripped,
+trailing slash removed — then matched strictly:
+
+```php
+$path = strtolower(rtrim(strtok($_SERVER['REQUEST_URI'] ?? '', '?'), '/'));
+if (in_array($path, self::HEALTH_CHECK_ROUTES, true)) { /* return 200 */ }
+```
+
+This means **all** of these probe variants return 200 and never touch routing or the DB:
+`/health`, `/v2/health`, `/health/` (trailing slash), `/health?x=1` (query string), and any
+case variant. On match it returns 200 with an empty object.
+
+## Why the normalization matters (the bug this fixed)
+
+The original check was an exact match `$_SERVER['REQUEST_URI'] == '/health'`, so any variant
+(`/v2/health`, trailing slash, query string) **fell through into the V2 routing engine**
+instead of short-circuiting. There it hit auth/DB work and could surface as an **HTTP 500
+(`EO-1`)** — a failing liveness probe. Health probes must degrade to a 200 short-circuit, not
+enter routing. When adding a new probe path, add it to `HEALTH_CHECK_ROUTES` (already
+normalized form: lowercase, no trailing slash, no query) rather than re-adding an exact-string
+branch.
+
+## Change history
+- 2026-07-24 — Replaced the brittle exact-string `REQUEST_URI == '/health'` check with a
+  `HEALTH_CHECK_ROUTES` constant + normalized (lowercase / strip query / strip trailing slash)
+  strict `in_array` match, so `/v2/health`, `/health/`, and `/health?x` all short-circuit to 200
+  before routing/DB work instead of falling through to the V2 engine and returning 500 (EO-1).
+  Verified via live curl on all variants. (jcardinal)
+</content>
+</invoke>

package/knowledge/2.0/apps/api2/features/v2-api-error-codes.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
-owners: [mhammontree, tcox]
+updated: 2026-07-24
+owners: [mhammontree, tcox, jcardinal]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Client/TrackingNumber.php
@@ -35,6 +35,7 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
 | **EV-8** | Request field does not exist | A field sent in the payload isn't registered as a **`Core.RecordFields`** row for that record | Register the field in `Core.RecordFields` (see the "add a field to a V2 record" recipe in the ACL doc) |
 | **EV-9** | No permission to write field | The field exists but the caller's role has no **`AclFieldPermissions`** grant (`isWritable=1`) in the CLIENT DB | Add the `AclFieldPermissions` row for the role (clone a writable sibling field's grant) |
 | **EO-1** | Operation failed — identifier "There is no field called 'X' in the '_Model_Client_Y' model" | The DB column **and** `Core.RecordFields` exist, but the **generated model class** `_underscore/Model/Client/<Name>.php` doesn't declare the field. This is the **4th** requirement beyond the 3-file migration — and most often it's a **cross-repo git branch mismatch** (`_underscore` on a branch whose generated model lacks a field the DB/RecordFields already carry) | Declare the field in the generated model class (`public $field = self::FIELD_*`) and put all related repos (`_underscore`, `api2`, `dbchanges2`, `toga2-supply`) on the **same** feature branch — see the ACL doc's writable-field recipe |
+| **EO-1** | Operation failed — **surfaced from a PHP warning/notice, not a real op error** (e.g. "Attempt to read property 'id' on bool", undefined variable) | A latent PHP warning escalates to a 500 because **Sentry's `ErrorHandler` in api2 promotes warnings/notices into thrown exceptions** (see diagnosis note 5). The known instance: in `V2.php::processRoutePairs()` an **unresolved route** leaves the local `$record = false`, and the post-processing payload interceptor layer then dereferenced `$record->id` → warning → 500 | Guard before dereferencing an unresolved record. The fix added a guard clause `if (!$record) return [$rawRequestedRouteName => $outData];` **before** the interceptor/logging layer (so a bad route returns a clean envelope, not a fatal), and initializes `$record = false;` at the top of the `foreach ($lookupByRouteNames ...)` loop so the invalid-HTTP-method / null-`$action` branch can't leave `$record` undefined (an undefined-variable warning would itself escalate to a 500) |
 | **EZ-1** | Unauthorized record/script dispatch | Missing **`AclRecordScripts`** (scripted APIs) or the **`AclRecordPermissions`** four-table chain (records) for the caller's role | Grant `AclRecordScripts` (scripts) or complete the record-CRUD chain |
 | **EZ-2** | Field-level authorization denied (READ) | The field is registered (`Core.RecordFields` present → no `EV-8`) but the caller's role has no **`AclFieldPermissions`** grant to **read** it. The read-side counterpart of `EV-9` (write) | Add the `AclFieldPermissions` row for the role (`isWritable=0` if the field is server-written). For a **custom** `c_` field use `AclCustomFieldPermissions` instead — see the ACL doc's standard-vs-custom table |
 | **EV-5** | Duplicate `transactionId` | The globally-unique `transactionId` was reused | Send a fresh unique `transactionId` per request |
@@ -54,6 +55,15 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
 3. **EV-6 vs EZ-1** are the two halves of exposing a scripted API: EV-6 = no `Core.RecordScripts`
    route (the segment falls through to record lookup); EZ-1 = the route exists but there's no
    `AclRecordScripts` dispatch grant for the caller's role.
+5. **EO-1 can be a masked PHP warning, not an operation error.** Sentry's `ErrorHandler` in
+   api2 **escalates PHP warnings/notices into thrown exceptions**, so a latent "read property on
+   bool" or "undefined variable" surfaces to the client as an **HTTP 500 (EO-1)** rather than a
+   log line. Practical consequence: in `V2.php` you must guard against warnings as if they were
+   fatals — an unresolved route (or a parent FK-field path) leaves `$record = false`, and any
+   later `$record->id` deref becomes a 500. Return a clean envelope for unresolved records
+   **before** the interceptor/logging layer, and initialize loop-locals so no branch leaves a
+   variable undefined.
+
 4. **EO-1 ("no field called 'X' in the model") is NOT a DB problem.** EV-8 means the Core
    `RecordFields` registration is missing; EO-1 means the DB column and RecordFields are both
    present but the **generated PHP model class** lacks the field. Before touching migrations,
@@ -71,6 +81,12 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
 
 ## Change history
 
+- 2026-07-24 — Added a second **`EO-1`** case: a latent PHP **warning** (unresolved route →
+  `$record->id` on `bool` in `V2.php::processRoutePairs()`, or an undefined loop variable)
+  escalates to an HTTP 500 because api2's Sentry `ErrorHandler` promotes warnings/notices into
+  exceptions. Fix = guard clause returning a clean envelope for unresolved records before the
+  post-processing interceptor layer + initialize `$record = false` at the loop top. Added
+  diagnosis note 5 (warnings surface as EO-1 500s). (jcardinal)
 - 2026-07-23 — TRUE-79533: added **`EZ-2`** (field-level READ authorization denied) — the read-side
   counterpart of `EV-9`; a registered field (no `EV-8`) with no `AclFieldPermissions` read grant.
   Clarified EV-8/EV-9/EZ-2 as three states of one field and the standard-vs-custom grant-table

package/knowledge/clients/nycdoe/features/servicenow-integration.md

@@ -6,7 +6,7 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-07-09
+updated: 2026-07-23
 owners: [mhammontree, sking]
 files:
   - worker/crons/sync/nycdoe/import_asn.php
@@ -248,6 +248,45 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
   164785 (internalId 6971859 → `38S0500` synced, 15 ROs) and PO 165751 (`50M7280` + `A3L980`
   NOT synced). PRs: library#831 (merge first) then worker#1670.
 
+- **⚠ REGRESSION of the 2026-07-09 multi-PO fix — a cross-wired SO/PO stamp silently drops
+  install tickets (diagnosed 2026-07-23; deferred to a one-off backfill, cron NOT changed).**
+  The 2026-07-09 fix (library#831 + worker#1670) made Stage 5 resolve item receipts **only**
+  Sales-Order-wide via `App_NetSuite::listItemReceiptsCreatedFromSalesOrder($soId)` (which fans
+  across the POs from `listPurchaseOrdersCreatedFromSalesOrder($soId)`). It **replaced** —
+  rather than augmented — the old by-stamped-PO lookup (`listItemReceiptsCreateFromPurchaseOrder`).
+  So when an ASN item's stamped `netSuiteInternalPurchaseOrderId` is **not a child of** its
+  stamped `netSuiteInternalSalesOrderId`, the SO-wide fan-out never inspects the stamped PO,
+  finds zero receipts, and the cron **silently creates no repair order and raises no error** —
+  the same "serials never sync, no error" symptom as the bug it replaced, in a distinct case.
+  - **Fingerprint:** an item stamped an SO whose only child PO has no receipt, while the stamped
+    PO (often an internalId *lower* than the SO's, i.e. created earlier) carries the real receipt
+    with the matching serials.
+  - **Root cause of the cross-wired stamp (SME Skyler King confirmed) = a warehouse
+    manual-entry error, not automation.** Confirmed case ASN **26215** (customer PO
+    `S202641365`): original SO `6901611` processed only `DOE-30HSS1BB00` (qty 1), PO `6901612`,
+    item receipt `6910404` (ticketed fine, RO 811791). Two monitors `DOE-62C5GAR1US` (serial
+    `VKWD9092`) and `DOE-64B6MAR1UZ` (serial `V600F9M6`) were **manually** added to SO `6901611`
+    with a **manually** created PO `6910401`, received on item receipt `6910410`. Separately,
+    when the real ASN arrived, the automation created a **duplicate** SO `6996287` (auto-PO
+    `6996288`, never used to receive — the serials were already on `6910410`). Net: ASN items
+    53905/53914 ended stamped SO=`6996287` (the duplicate) but PO=`6910401` (the manual PO under
+    the *original* SO), so SO-wide resolution finds nothing.
+  - **SME-confirmed correct end-state:** the units belong to the **original** SO (`6901611`);
+    the automation-created duplicate SO `6996287` / PO `6996288` is a NetSuite cleanup item
+    (cancel). The owed installs (one repair order per received unit) are **independent** of the
+    NetSuite duplicate and are created **TOGa Desk-side only**. Warehouse process has since been
+    corrected by training.
+  - **Recovery (chosen fix — one-off, not a cron change):** a run-once backfill reuses
+    `doeCreateInstallationRepairOrder` verbatim from Stage 5 (`3_create_installation_ticket.php`)
+    but scoped to a single ASN (id via CLI arg), resolving receipts from the **UNION** of the
+    SO's child POs *and* the item's stamped PO. It is idempotent (only units with
+    `togadeskRepairOrderId IS NULL`), guards double dispatch (skips a serial that already has a
+    `repair_order` in `db_togadesk`), never adds new `AdvanceShippingNoticeUnits`, is
+    serialized-only, and makes no NetSuite/ServiceNow writes. Confirmed on ASN 26215 (created the
+    two owed ROs). A **permanent union fix in the cron** (resolve receipts from SO child POs plus
+    the stamped PO) was considered but **deferred** — the team chose the one-off because the
+    warehouse process error is now prevented by training.
+
 ## Debugging & DB topology (DOE 1.0 sync)
 
 Reference for future DOE investigations — the 1.0 worker cannot run on a dev/Windows box;
@@ -265,6 +304,14 @@ use the toga DB MCP + `Logs.API` instead of running prod code locally.
   6971859 returned `totalRecords=1`, only `38S0500`.)
 - **`Bridge_NetSuite`** (legacy) has `SalesOrders` / `SalesOrderItems` / `SerialNumbers` but
   **no `PurchaseOrders` table** — POs are pulled live from the NetSuite API.
+- **Stuck-vs-received check, per ASN item:** compare
+  `listItemReceiptsCreatedFromSalesOrder($stampedSO)` against
+  `listItemReceiptsCreateFromPurchaseOrder($stampedPO)`, dumping each receipt line's `itemName`
+  plus its `inventoryAssignment` serials. If the SO-wide call returns 0 but the stamped PO
+  returns the receipt with the matching serials, it is the cross-wired-stamp regression above.
+- **`App_Model_Core_AdvanceShippingNotice` does NOT map `dtCreatedInstallationTicket`** — its
+  `__get` throws "No field or quick query defined for key …". Read that column via **raw SQL**,
+  not the model.
 
 ## Operating rules when changing this integration
 
@@ -278,6 +325,17 @@ use the toga DB MCP + `Logs.API` instead of running prod code locally.
    of the consumer query; `php -l` every touched file.
 
 ## Change history
+- 2026-07-23 — Diagnosed a regression of the 2026-07-09 multi-PO fix: Stage 5's SO-wide receipt
+  resolution *replaced* the by-stamped-PO lookup, so a cross-wired stamp (an item's stamped PO
+  not a child of its stamped SO) silently drops install tickets with no error. Root cause of the
+  cross-wire = a warehouse manual-entry error (a duplicate SO was auto-created while the real
+  receipt sat under a manually-created PO on the original SO); SME Skyler King confirmed the
+  correct end-state (units on the original SO, duplicate SO cancelled, owed installs are TOGa
+  Desk-side only). Recovered stuck ASN 26215 with a one-off union-receipt backfill (union of SO
+  child POs + the stamped PO; idempotent; no NetSuite/ServiceNow writes) that created the two
+  owed ROs; a permanent union fix in the cron was considered but deferred (warehouse process now
+  corrected by training). Added a regression gotcha + two debugging notes. No production code
+  changed. (mhammontree; SME sking)
 - 2026-07-09 — Fixed silent install-ticket drop when a NetSuite SO is fulfilled across
   multiple POs: Stage 5 now resolves item receipts Sales-Order-wide via new helper
   `App_NetSuite::listItemReceiptsCreatedFromSalesOrder` (fans across all POs from the SO,

package/package.json

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