toga-ai 1.0.1199 → 1.0.1201

package/knowledge/1.0/apps/api/INDEX.md

@@ -3,5 +3,6 @@
 | Doc | Summary |
 |-----|---------|
 | [API 1.0 (api) Architecture](architecture.md) | The 1.0 REST `api` (clients, suppliers, Talos Voice): single front controller `api.php`, route classes in `_/app/route/`, no sessions, error handling from libra |
+| [BitStorm diagnostic post (1.0 api POST /order/<n>/diagnostic) — Device + Diagnostics + results document](features/bitstorm-order-diagnostic-endpoint.md) | How BitStorm posts PC scan results to an ODP quote, why one failure wipes the whole post, and how to debug the 1.0 api; open when a quote has no device/diag dat |
 | [Talos Ticket API (1.0 api POST/PUT /ticket) — Desk tickets + file uploads from Talos Voice](features/talos-ticket-endpoint.md) | 1.0 `api` route that Talos Voice calls to create (`POST /ticket`) and update (`PUT /ticket/{ticketNumber}`) TOGa Desk tickets and attach call files; open before |
 | [Deploying API 1.0 to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the 1.0 `api` deploys on EB PHP 8.5 / AL2023 (Apache proxy) — prod env + pipeline, the nonprod api sandbox (= beta), s3fs 1.97 mount over IMDSv2, cross-acco |

package/knowledge/1.0/apps/api/features/bitstorm-order-diagnostic-endpoint.md

@@ -0,0 +1,49 @@
+---
+title: "BitStorm diagnostic post (1.0 api POST /order/<n>/diagnostic) — Device + Diagnostics + results document"
+framework: "1.0"
+repo: api
+project: API 1.0
+client: office-depot
+type: feature
+status: active
+updated: 2026-10-29
+owners: ["snaredla"]
+files:
+  - api/_/app/route/order.php
+  - api/api.php
+  - api/ebs/s3fs.prod.json
+  - library/app/model/toga/document.php
+related:
+  - ../../library/features/app-cloud-aws-credentials.md
+  - ./talos-ticket-endpoint.md
+  - ../../togadesk/features/s3fs-asifiles-file-storage.md
+  - ../../library/features/error-capture-1-0.md
+  - ../../toga/features/odp-tech-services-job-jacket-answers.md
+  - ../../../../clients/office-depot/profile.md
+---
+How BitStorm posts PC scan results to an ODP quote, why one failure wipes the whole post, and how to debug the 1.0 api; open when a quote has no device/diag data or a diag post returns 500.
+
+## Summary
+
+`postOrderDiagnostic` in `api/_/app/route/order.php` saves the Device, the Diagnostics rows and (on a full scan, i.e. every Existing PC quote) the HTML results document via `App_Model_Toga_Document::save()`. The store needs the device/diag data to sell a service.
+
+## How it works
+
+- `api.php` ~229 wraps **every** route in `App_Database::beginTransaction()`. Any fatal → HTTP 500 → the Device and Diagnostics rows roll back too.
+- Results document → `Document::save()` → s3fs mount write (`api` has no AWS SDK; see the no-SDK fallback in [App_Cloud](../../library/features/app-cloud-aws-credentials.md)).
+
+## Gotchas
+
+- **~2026-10-05 to TRUE-83311: every post with a results document returned 500** (`Document::save()` called `App_Cloud::copyFileToS3` → missing SDK `Error`). Posts with an empty document passed. Quotes from that window with Existing PC diag posts have no diag data — the store must re-run the diag.
+- **OPEN (developer to decide): result documents are now public-read.** `api/ebs/s3fs.prod.json` mounts `asifiles` with `default_acl=public-read`; `copyFileToS3` uploaded private. systemInformation and Talos uploads already go through the same mount.
+- **OPEN (seen, not confirmed a bug):** toga `finalizequote.php` ~628 skips saving service answers when a device is in session.
+
+### Debugging the 1.0 api
+
+1. `Logs.API` row with `responseCode` NULL = the request died.
+2. api errors are **not** in `Logs.Errors`: api's `App_Error` inserts columns (`dtStamp`, `framework`, `urlDetails`, …) the legacy table lacks.
+3. EB env `togatech-legacy-api-production` (profile `toga-production`, us-east-1) has no CloudWatch log shipping. Use `aws elasticbeanstalk request-environment-info --info-type bundle`, then read httpd `access_log` (`500 1105` = App_Error page).
+4. Compare failing vs passing posts with `JSON_EXTRACT` on `Logs.API.requestPayload`.
+
+## Change history
+- 2026-10-29 — Created: no-SDK document save fixes 500 + rollback of diag data; api debug recipe; open ACL risk (TRUE-83311) (snaredla)

package/knowledge/1.0/apps/library/features/app-cloud-aws-credentials.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-10-23
+updated: 2026-10-29
 owners: [jcardinal, mhammontree, bala, snaredla, rgirish]
 files:
   - library/app/cloud.php
@@ -80,6 +80,7 @@ CodePipeline `Worker` (502, us-west-2) sources `_production` of **both** `agilan
   - **Testing gotcha:** after one passing run, `databaseReadHost.txt` is fresh for 30-60 s, so a control run right after also passes. Wait > 60 s (or delete the cache file) before the control.
   - store: fixed on branch (TRUE-82856, ae1861f4f — same pins plus aws-crt-php 1.2.7, psr/http-client 1.0.3, polyfill-mbstring 1.31.0; verified on PHP 7.2.33); needs merge + deploy. Its `.ebextensions/015_install_composer.config` already runs `composer install --no-dev`.
   - **Missed by the audit (TRUE-82935): the 1.0 `api` repo** (no composer at all) and **togadesk's email cron** (`crons/tickets.php` loads only `desk/vendor/autoload.php`; the root togadesk composer with aws is not loaded there). Both stopped `App_Cloud`: [Talos ticket API](../../api/features/talos-ticket-endpoint.md), [email intake](../../togadesk/features/email-to-ticket-intake.md). Audit per **entry point**, not per repo: a CLI cron or sub-app can load a different autoloader than the web app.
+  - **`App_Model_Toga_Document::save()` has a no-SDK fallback (TRUE-83311).** If `!class_exists('Aws\S3\S3Client')` it writes to `storage_folder` + the same `/togadocuments-<env>/<clientId>/<id>` path (`storage_folder` = s3fs mount of `asifiles`) instead of `App_Cloud::copyFileToS3`. SDK apps (toga, togadesk, worker, togaview) unchanged; api, vision, store, worker1.5, compass take the mount path. The library autoloader returns `false` on a `class_exists` miss, so the check is safe. Caller: [BitStorm diagnostic endpoint](../../api/features/bitstorm-order-diagnostic-endpoint.md).
   - The missing class throws **`Error`, not `Exception`** — `catch (Exception)` around an App_Cloud call does not catch it; use `\Throwable` where a fallback is meant.
   - Not changed on TRUE-82856: walmarttechservices — GitHub repo `agilantsolutions/walmarttechservices` no longer exists ("Repository not found", checked 2026-10-16); webhook — reported no longer active by the developer (2026-10-16). Removal / deprecation is left to the owners.
 - Verify assume-role in CloudTrail (`AssumeRole` on `WorkloadsRuntime`, by session name: `library-app-cloud`, `setup-git-libraries`, `register-instance`, `worker-deploy`).
@@ -87,6 +88,7 @@ CodePipeline `Worker` (502, us-west-2) sources `_production` of **both** `agilan
 - Every long-lived key still in code across repos (SES SMTP, s3fs, ALB scripts, other accounts): [audit 2026-10-13](../../../../2.0/apps/worker2/features/cross-account-aws-access.md#long-lived-keys-still-in-code-audit-2026-10-13).
 
 ## Change history
+- 2026-10-29 — `App_Model_Toga_Document::save()` falls back to the s3fs mount when the SDK is missing (TRUE-83311) (snaredla)
 - 2026-10-23 — walmart-activate added aws-sdk-php; moved-app check + read-host cache testing gotcha (TRUE-83161) (rgirish)
 - 2026-10-22 — Leaked key was abused (Bedrock LLM-jacking, GuardDuty, TRUE-82983) (jcardinal)
 - 2026-10-19 — aws-sdk-php audit missed `api` + togadesk email cron; `Error` not `Exception` (TRUE-82935) (jcardinal)

package/knowledge/1.0/apps/library/features/app-session-db-store.md

@@ -6,12 +6,14 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-10-16
-owners: ["rgirish"]
+updated: 2026-10-29
+owners: ["rgirish", "snaredla"]
 files:
   - library/app/session.php
+  - library/app/framework.php
 related:
   - ../architecture.md
+  - ../../toga/features/odp-tech-services-job-jacket-answers.md
   - ../../store/features/prudential-equipme-home.md
 ---
 How 1.0 `App_Session` stores sessions (DB `Sessions` + local cache file + `SessionUpdates`), why concurrent AJAX requests can overwrite each other, and what read-only endpoints must do; open before adding AJAX endpoints or session writes in a 1.0 app.
@@ -34,6 +36,8 @@ How 1.0 `App_Session` stores sessions (DB `Sessions` + local cache file + `Sessi
 - **Read-only endpoints: copy what you need from `$_SESSION`, then `session_abort()`.** No write, no 0.5s sleep, no stale overwrite.
 - **Long endpoints that change the session: make the change first, then `session_write_close()`** so it saves now, not at shutdown.
 - **Do not rely on a value set at the end of the same page load** being visible to a parallel request, especially one served by another instance.
+- **`$_SESSION` writes inside an `ajaxAction` method are silently lost.** `App_Framework::ajaxHandler` (`library/app/framework.php` ~147) calls `session_write_close()` before running the action. To save a session value there: `if (session_status() !== PHP_SESSION_ACTIVE) { session_start(); }`, set it, then `session_write_close()` — same as `App_Model_ServiceRequest::createNewServiceRequest`. Missing this created every ODP Existing PC quote twice ([job jacket flow](../../toga/features/odp-tech-services-job-jacket-answers.md), TRUE-83311).
 
 ## Change history
 - 2026-10-16 — Initial: storage model, no-locking stale-write risk, `session_abort()` / early `session_write_close()` rules (found on TRUE-82596). (rgirish)
+- 2026-10-29 — Gotcha: ajaxHandler closes the session before ajax actions (TRUE-83311). (snaredla)

package/knowledge/1.0/apps/toga/features/odp-tech-services-job-jacket-answers.md

@@ -6,8 +6,8 @@ project: TOGa
 client: office-depot
 type: client-feature
 status: active
-updated: 2026-10-23
-owners: [jcardinal]
+updated: 2026-10-29
+owners: [jcardinal, snaredla]
 files:
   - toga/app/togarefresh2026/customersearch/computerquestions.php
   - toga/app/togarefresh2023/customersearch/computerquestions.php
@@ -38,9 +38,11 @@ The Tech Services path asks job jacket questions, carries the answers in the URL
 
 - **Every argument is user input.** Both methods are called by browser `ajaxAction`, so `$serviceId`, question ids and option ids come from the client. Cast ids to `(int)`; save option id `0` / `'undefined'` as `null`. FK fields are NOT cast by the 1.0 model layer — see the `App_Model::getFieldValueForQuery()` gotcha in the [library architecture](../../library/architecture.md).
 - **A stray quote in the redirect URL broke the whole path** (MySQL 1064). The old "Next" code ended with `+ "'"`, so the last option id became `0'` and reached the INSERT raw. When editing the redirect, check the last pair survives the `&`/`=` split clean.
+- **Quote must be in `$_SESSION['serviceRequestId']` before `servicequestions.php` runs.** `servicequestions.php` (~21-32) creates a new quote when that key is empty. `createNewServiceRequestRefresh()` (ajax from 2026 `view.php` ~638, 2023 `view.php` ~600) did not save it (ajax session gotcha, see [App_Session](../../library/features/app-session-db-store.md)), so every Existing PC quote (job jacket 1) was created twice, 0-2 s apart (since at least 2026-10-01). Fixed TRUE-83311.
 - **Two copies of `computerquestions.php`** (togarefresh2023 and togarefresh2026) — fix both.
 - **OPEN (not fixed, needs a ticket): no ownership check.** Neither method checks that the session user may write to the given ServiceRequest id — any logged-in user can rewrite another SR's answers.
 - **OPEN (not fixed, needs a ticket): `refreshArrayJobJacketQuestions` saves the option id into the wrong property** — `jobJacketQuestionId` (~line 679) and `answerJobJacketQuestion` (~line 707) instead of `answerJobJacketQuestionOptionId`.
 
 ## Change history
 - 2026-10-23 — Removed stray `+ "'"` from both `computerquestions.php` redirects (fixed MySQL 1064 on save); `(int)`-cast serviceId/question/option ids in both refresh methods, option 0 → null (TRUE-83172) (jcardinal)
+- 2026-10-29 — `createNewServiceRequestRefresh()` now saves `serviceRequestId` to session; stops duplicate quotes (TRUE-83311) (snaredla)

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

@@ -11,6 +11,7 @@
 | [_ApiRequest — JSON encode/decode & api-logging behavior](features/apirequest-json-content-type.md) | `_ApiRequest`, the 2.0 outbound HTTP client — JSON encode/decode, retry, and api-logging traps; open before calling it or reading `Logs.Api`. |
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment names in multiple languages via an `AssortmentTranslations` sidecar table on the metadata-driven translation layer; open when translating asso |
 | [Asynchronous Query Execution (writes-only, via Worker)](features/async-query-execution.md) | Run a slow WRITE asynchronously via the Worker tier so a long request write cannot hold a stale connection and hit "MySQL server has gone away"; open before usi |
+| [Aurora MySQL binlog on the 2.0 clusters — current settings, who reads it, and what a change costs](features/aurora-binlog-configuration.md) | Binlog state of the prod and non-prod 2.0 Aurora MySQL clusters, the us-east-1 vs us-west-2/eu-west-1 parameter group mismatch, proof nothing reads the binlog, |
 | [Record numbering (FIELD_AUTOINCREMENT: per-client sequential numbers from RecordNumbers)](features/autoincrement-record-numbering.md) | ORM record numbers (`SA139197`, `AJ100000`, `CL146`) counted in order per client from a `RecordNumbers` table; open when adding a numbered model/prefix, debuggi |
 | [Calculated-column filter options (`<field>FilterOptions` model static → table meta)](features/calculated-column-filter-options.md) | Lets a calculated (`FIELD_SQL`) table column supply its own filter dropdown options via a `<field>FilterOptions` model static; open when adding a data-driven co |
 | [FIELD_SQL calculated fields — the underscore-prefix + same-name-method contract](features/calculated-sql-fields.md) | A `FIELD_SQL` (calculated) field on a `_Model` is bound by a **two-part contract that `_Model` enforces by throwing at model-construction time**, not by convent |

package/knowledge/2.0/apps/_underscore/features/aurora-binlog-configuration.md

@@ -0,0 +1,82 @@
+---
+title: Aurora MySQL binlog on the 2.0 clusters — current settings, who reads it, and what a change costs
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-10-29
+owners: ["rgirish"]
+files: []
+related:
+  - ../architecture.md
+  - ../../../../1.0/apps/worker1.5/features/database-backups.md
+---
+
+Binlog state of the prod and non-prod 2.0 Aurora MySQL clusters, the us-east-1 vs us-west-2/eu-west-1 parameter group mismatch, proof nothing reads the binlog, and why a binlog_format change needs a writer reboot (outage); open before touching any binlog parameter or planning CDC/replication off the 2.0 databases.
+
+## Summary
+
+Prod has binlog ON (`STATEMENT`, enhanced binlog) on core/client/archive/logs, but **nothing reads it** (checked 2026-10-29, TRUE-83342). `binlog_format` is a **static** parameter: changing it needs a **writer reboot**, and every prod cluster has **one instance only**, so the reboot is a real write outage for that family. The same-named parameter group **differs by region** — change all 3 regions together.
+
+## How it works
+
+### Prod (account 654654170868, primary us-east-1)
+
+- 5 Aurora MySQL Global Databases, engine `8.0.mysql_aurora.3.08.2`: `production-{core,client,archive,logs,cache}-global`.
+- Writer cluster `production-<x>-1` (us-east-1); secondaries `-2` (us-west-2), `-3` (eu-west-1).
+- **Each cluster has exactly 1 instance** (`production-<x>-1-i01`). No in-region reader, no in-region failover target.
+- Global Database replicates at the **storage layer**, not via binlog. Binlog is not needed for the secondaries.
+
+| Cluster | Cluster parameter group | Binlog |
+|---|---|---|
+| core, client, archive, logs | `true-rds-cluster-parameters` | ON |
+| cache | `default.aurora-mysql8.0` | OFF |
+
+`true-rds-cluster-parameters` values per region:
+
+| Parameter | us-east-1 (writers today) | us-west-2 and eu-west-1 |
+|---|---|---|
+| `binlog_format` | `STATEMENT` | `STATEMENT` |
+| `aurora_enhanced_binlog` | `1` | off |
+| `binlog_backup` | `0` | `1` |
+| `binlog_replication_globaldb` | `0` | `1` |
+| `binlog_row_image` | `MINIMAL` | not checked |
+
+Live check on us-east-1 writers: `log_bin = ON`.
+
+### Non-prod (account 975050298201, us-east-1)
+
+- 19 single-instance clusters (`sandbox-dev`, `sandbox-client`, `stage`, `demo`, `client-*`, `qa-*`, `qc-*`), engine `3.10.3`.
+- All on `true-rds-cluster-parameters` with `binlog_format = OFF` (`log_bin = 0`). No Global Database.
+
+### Who reads the binlog (2026-10-29: nobody)
+
+- No `Binlog Dump` threads on prod core/client/archive/logs writers (the login sees `rdsadmin` threads, so the processlist is complete).
+- Only `rdsadmin` and `rds_superuser_role` hold `REPLICATION SLAVE` / `REPLICATION CLIENT`.
+- No RDS zero-ETL integrations and no binlog replica clusters in us-east-1, us-west-2, eu-west-1.
+- **Not checked:** AWS DMS — SSO role `GoAgilant-Developers` gets AccessDenied on `dms:Describe*`. The processlist check is one point in time.
+
+### Changing a binlog parameter
+
+1. Re-run the reader checks below first (a reader may have appeared).
+2. Change the parameter in `true-rds-cluster-parameters` in **all 3 regions** (us-east-1, us-west-2, eu-west-1).
+3. `binlog_format` (and other `ApplyType = static` parameters) leave the cluster `pending-reboot` until the writer reboots.
+4. Reboot each writer in a window. Estimate ~30-60 s per writer, maybe longer: with binlog ON, binlog recovery runs at startup (enhanced binlog shortens it). Secondaries keep serving reads during the primary reboot. No real reboot timing exists (no reboot events in the last 14 days); a non-prod test gives only a lower bound because binlog is off there.
+
+### Read-only checks
+
+- Static vs dynamic: `aws rds describe-db-cluster-parameters --db-cluster-parameter-group-name true-rds-cluster-parameters --region <r>` → `ApplyType` column.
+- Binlog readers (toga-db): `SELECT * FROM information_schema.PROCESSLIST WHERE COMMAND LIKE 'Binlog Dump%'`.
+- Replication grants: `SELECT * FROM information_schema.USER_PRIVILEGES WHERE PRIVILEGE_TYPE LIKE 'REPLICATION%'`.
+- Zero-ETL: `aws rds describe-integrations --region <r>`.
+
+## Gotchas
+
+- **Region mismatch:** after a Global Database failover, the new writer (us-west-2 or eu-west-1) runs plain, non-enhanced binlog with `binlog_backup = 1`. Settings silently change on failover unless all 3 regions match.
+- **Reboot = outage:** one instance per cluster, so rebooting `production-<x>-1-i01` stops writes for that whole family.
+- Binlog ON with no reader only costs write overhead and storage; turning it off is safe today only if the reader checks are still empty.
+
+## Change history
+- 2026-10-29 — First version: prod/non-prod binlog state, region mismatch, no readers found, static-parameter reboot cost (TRUE-83342) (rgirish)

package/knowledge/INDEX.md

@@ -18,11 +18,11 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **store** (Store) — 5 doc(s) → [1.0/apps/store/INDEX.md](1.0/apps/store/INDEX.md)
 - **tools** (Tools) — 25 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 - **vision** (Vision) — 2 doc(s) → [1.0/apps/vision/INDEX.md](1.0/apps/vision/INDEX.md)
-- **api** (API 1.0) — 3 doc(s) → [1.0/apps/api/INDEX.md](1.0/apps/api/INDEX.md)
+- **api** (API 1.0) — 4 doc(s) → [1.0/apps/api/INDEX.md](1.0/apps/api/INDEX.md)
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 117 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 118 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 102 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 29 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 24 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/package.json

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