toga-ai 1.0.1200 → 1.0.1202

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

@@ -30,7 +30,7 @@ How BitStorm posts PC scan results to an ODP quote, why one failure wipes the wh
 ## 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)).
+- 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)). Mount missing or short write → throw → 500 + full rollback, so nothing half-saved.
 
 ## Gotchas
 
@@ -46,4 +46,5 @@ How BitStorm posts PC scan results to an ODP quote, why one failure wipes the wh
 4. Compare failing vs passing posts with `JSON_EXTRACT` on `Logs.API.requestPayload`.
 
 ## Change history
+- 2026-10-29 — Document save fails closed (unmounted s3fs / short write) (TRUE-83311) (snaredla)
 - 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

@@ -15,6 +15,7 @@ files:
   - toga/ebs/register_instance_to_shared_application_load_balancer.php
   - tools/ebs/check_s3fs.php
   - library/app/model.php
+  - library/app/model/toga/document.php
   - togadesk/ebs/check_s3fs.php
   - togadesk/ebs/register_instance_to_shared_application_load_balancer.php
   - togadesk/.ebextensions/020_setup_git_libraries.config
@@ -80,7 +81,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).
+  - **`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. **Fails closed:** throws `Storage folder is not mounted` when `storage_folder` has the same `stat` device as its parent (dropped s3fs mount = plain local folder, writes never reach S3); writes with `fopen`/`fwrite`/`fclose` and throws unless every byte is written and `fclose` succeeds (s3fs uploads on close). An `fopen` failure raises a warning that `App_Error` turns into exit before the throw — still a failed request. 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`).
@@ -88,6 +89,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 — no-SDK document save fails closed on unmounted folder / short write (TRUE-83311) (snaredla)
 - 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)

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

@@ -22,7 +22,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 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.1200",
+  "version": "1.0.1202",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",