toga-ai 1.0.1200 → 1.0.1201

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.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",