toga-ai 1.0.830 → 1.0.832

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

@@ -2,4 +2,4 @@
 
 | Doc | Summary |
 |-----|---------|
-| [Authoring & Shipping a 1.0 dbchanges SQL File](workflows/authoring-and-shipping-sql-files.md) | Authoring & shipping a 1.0 `dbchanges` `.sql` file: the crude runner's parse/fail-stop model, the only working all-or-nothing guard, folder=database, and which |
+| [Authoring & Shipping a 1.0 dbchanges SQL File](workflows/authoring-and-shipping-sql-files.md) | `dbchanges` is the **1.0** (legacy/V1) schema-and-data change repository — the 1.0 sibling of 2.0's `dbchanges2`. |

package/knowledge/1.0/apps/dbchanges/workflows/authoring-and-shipping-sql-files.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-09-16
+updated: 2026-08-14
 owners: [sking]
 files:
   - dbchanges/index.php
@@ -19,36 +19,42 @@ related:
   - ../../../../clients/nycdoe/features/servicenow-integration.md
 ---
 
-Authoring & shipping a 1.0 `dbchanges` `.sql` file: the crude runner's parse/fail-stop model, the only working all-or-nothing guard, folder=database, and which branches auto-apply; open before writing any 1.0 dbchanges SQL.
-
 ## Summary
 
-`dbchanges` is the **1.0** (legacy/V1) schema-and-data change repo — the 1.0 sibling of 2.0's `dbchanges2`. Unlike `dbchanges2` it ships **its own runner**, `dbchanges/index.php`, invoked by the worker tier. The runner's parsing model is crude and its error path is **fail-stop for the whole queue**, so *how* you write the `.sql` file decides whether your change (and everyone else's queued behind it) applies at all.
+`dbchanges` is the **1.0** (legacy/V1) schema-and-data change repository — the 1.0 sibling of
+2.0's `dbchanges2`. Unlike `dbchanges2` it ships **its own runner**, `dbchanges/index.php`, which
+is invoked by the worker tier. The runner's parsing model is crude and its error path is
+**fail-stop for the whole queue**, so *how* you write the `.sql` file decides whether your change
+(and everyone else's queued behind it) applies at all.
 
 Two rules dominate everything below:
-1. **A chunk that contains only comments aborts the entire queue.** Put all commentary *before* the final statement; never end a commented line with a semicolon.
-2. **`_production` does NOT auto-apply.** Merged production data changes land on the next worker **deploy**, not within minutes.
 
-> `dbchanges/Core/*` targets the **legacy (V1) `Core` schema** — not the 2.0 prod `Core`. Confirm the target environment before writing anything.
+1. **A chunk that contains only comments aborts the entire queue.** Put all commentary *before*
+   the final statement; never end a commented line with a semicolon.
+2. **`_production` does NOT auto-apply.** Merged production data changes land on the next worker
+   **deploy**, not within minutes.
 
-## Steps
+> `dbchanges/Core/*` targets the **legacy (V1) `Core` schema** — not the 2.0 prod `Core`. Confirm
+> the target environment before writing anything.
 
-1. Confirm the target schema/environment (`Core/` = legacy V1 `Core`).
-2. Branch per the git-workflow rules (`fix/...`, `feature/...`) — never commit to `_production`.
-3. Write **one file, commentary first, statements last**, no trailing comment chunk, no explicit `COMMIT`, and no `DELIMITER`/stored-routine constructs.
-4. Wrap any risky data change in the derived-table preflight guard (below) so a drifted before-state is a no-op rather than a wrong write.
-5. Open a PR into `_production` (or the target `_<env>` branch).
-6. After merge: `_<env>` branches apply within ~2 min; **`_production` waits for the next worker deploy** — verify with a read-only query afterward rather than assuming. **Merging the PR applies nothing by itself** — `dbchanges` has no CI, no workflow, no runner of its own; every application is driven from the worker tier.
-7. If the change spans more than one top-level (database) folder, verify **each database separately** — see the silent-skip trap below.
+## How the runner parses a file (`dbchanges/index.php`)
 
-### How the runner parses a file (`dbchanges/index.php`)
+- Each `.sql` file is read whole and split on the **literal `";\n"`** (semicolon + newline)
+  — `index.php` ~L140. There is no SQL lexer: no awareness of strings, comments, or delimiters.
+- Every non-empty chunk is sent to MySQL through a single **`mysqli_query()`** (~L145). Multi-
+  statement execution is not used.
+- On error (~L146–170) the runner writes to `Logs.Errors` and, on the prod path, **`exit()`s** —
+  which **blocks every dbchanges file queued behind it** until the offending file is fixed.
+- Each file runs **inside a transaction**: `mysqli_autocommit($link, false)` is set before the
+  `_dbchanges` bookkeeping INSERT, and autocommit is only re-enabled (implicit COMMIT) after the
+  whole file succeeds. So on error the statement **and** its `_dbchanges` row roll back together,
+  and the file is retried on the next run.
 
-- Each `.sql` file is read whole and split on the **literal `";\n"`** (semicolon + newline) — `index.php` ~L140. There is no SQL lexer: no awareness of strings, comments, or delimiters.
-- Every non-empty chunk is sent to MySQL through a single **`mysqli_query()`** (~L145). Multi-statement execution is not used.
-- On error (~L146–170) the runner writes to `Logs.Errors` and, on the prod path, **`exit()`s** — which **blocks every dbchanges file queued behind it** until the offending file is fixed.
-- Each file runs **inside a transaction**: `mysqli_autocommit($link, false)` is set before the `_dbchanges` bookkeeping INSERT, and autocommit is only re-enabled (implicit COMMIT) after the whole file succeeds. So on error the statement **and** its `_dbchanges` row roll back together, and the file is retried on the next run.
+### Consequence: the "empty query" trap
 
-**The "empty query" trap:** a chunk consisting solely of `--` comment lines comes back as MySQL error **1065 "Query was empty"** — a hard failure that stops the queue. Easy to trigger by pasting verification queries or notes *after* the last statement.
+A chunk consisting solely of `--` comment lines comes back as MySQL error **1065 "Query was
+empty"** — a hard failure that stops the queue. This is easy to trigger accidentally by pasting
+verification queries or explanatory notes *after* the last statement.
 
 ```sql
 -- CORRECT: all commentary lives above the statement, one trailing statement.
@@ -65,14 +71,22 @@ UPDATE ...;
 
 All 13 pre-existing files under `dbchanges/Core/` comply with this. Follow them.
 
-### The all-or-nothing guard pattern (the only one that works)
+## Expressing an all-or-nothing guard (the only pattern that works)
 
 Procedural guards are **not expressible** in a dbchanges file:
-- `IF` / `SIGNAL` / conditional `COMMIT`-`ROLLBACK` on `ROW_COUNT()` are legal only inside a stored routine.
-- A routine body cannot be shipped anyway: its internal semicolons are shredded by the `";\n"` split, and `DELIMITER` is a **client** directive that `mysqli` does not understand.
-- An explicit `COMMIT` is **actively harmful** — it lands the data change independently of the `_dbchanges` bookkeeping row, breaking retry-on-failure.
 
-The working pattern is a **single-statement inline preflight guard**: a derived-table subquery that counts the rows in the expected *before* state and requires an exact count, so the statement is a no-op unless reality matches the assumption. The **derived-table wrapper is load-bearing** — it is what avoids MySQL error **1093** ("can't specify target table for update in FROM clause"). Validated on **MySQL 8.0.42**.
+- `IF` / `SIGNAL` / conditional `COMMIT`-`ROLLBACK` on `ROW_COUNT()` are legal only inside a
+  stored routine.
+- A routine body cannot be shipped anyway: its internal semicolons are shredded by the `";\n"`
+  split, and `DELIMITER` is a **client** directive that `mysqli` does not understand.
+- An explicit `COMMIT` is **actively harmful** — it lands the data change independently of the
+  `_dbchanges` bookkeeping row, breaking retry-on-failure.
+
+The working pattern is a **single-statement inline preflight guard**: a derived-table subquery
+that counts the rows in the expected *before* state and requires an exact count, so the statement
+is a no-op unless reality matches the assumption. The **derived-table wrapper is load-bearing** —
+it is what avoids MySQL error **1093** ("can't specify target table for update in FROM clause").
+Validated on **MySQL 8.0.42**.
 
 ```sql
 UPDATE SomeTable t
@@ -84,15 +98,28 @@ WHERE t.id IN (<ids>)
       ) AS preflight) = <expected-row-count>;
 ```
 
-### One top-level folder = one DATABASE (and the silent-skip trap)
+## One top-level folder = one DATABASE (and the silent-skip trap)
 
-The repo's top level is a list of **database names**, not modules: `Core`, `TOGaDeskSupport`, `Common`, `Logs`, `Bridge_NetSuite`, … The runner walks every top-level directory and treats the **folder name as the database to connect to** (`index.php` ~L55–60), then — for each folder — scans `config.<env>.ini` and uses the **first `[database*]` group it finds** (~L76–80; in `config.prod.ini` that is `[database_main]`) for hostname/username/password. So *all* folders are attempted with **one** set of credentials against one host, with only the DB name varying.
+The repo's top level is a list of **database names**, not modules: `Core`, `TOGaDeskSupport`,
+`Common`, `Logs`, `Bridge_NetSuite`, … The runner walks every top-level directory and treats the
+**folder name as the database to connect to** (`index.php` ~L55–60), then — for each folder — scans
+`config.<env>.ini` and uses the **first `[database*]` group it finds** (`~L76–80`; in
+`config.prod.ini` that is `[database_main]`) for hostname/username/password. So *all* folders are
+attempted with **one** set of credentials against one host, with only the DB name varying.
 
-Consequence: **a folder whose database is not reachable from that host is skipped silently.** The failure path is a bare `echo "Skipping <db> Database... unable to connect"` (~L189) — no `Logs.Errors` row, no `exit()`, no `_dbchanges` bookkeeping. Nothing retries it, and nothing tells you. A change spanning two databases on two different clusters (e.g. `Core` on **db_core** and `TOGaDeskSupport` on **db_togadesk**) therefore needs **two separate runs**, one per cluster, and an applier pointed at only one of them **half-applies the change and reports success**.
+Consequence: **a folder whose database is not reachable from that host is skipped silently.**
+The failure path is a bare `echo "Skipping <db> Database... unable to connect"` (`~L189`) — no
+`Logs.Errors` row, no `exit()`, no `_dbchanges` bookkeeping. Nothing retries it, and nothing tells
+you. A change that spans two databases on two different clusters (e.g. `Core` on **db_core** and
+`TOGaDeskSupport` on **db_togadesk**) therefore needs **two separate runs**, one per cluster, and
+an applier pointed at only one of them **half-applies the change and reports success**.
 
-**Rule: a multi-database change is not done until you have verified each database independently.** Verify **per-pair** (does *this* key have *this* value?), not by a `COUNT(*) ... IS NOT NULL` total — a per-count check passes on the cluster that applied and tells you nothing about the one that didn't.
+**Rule: a multi-database change is not done until you have verified each database independently.**
+Verify **per-pair** (does *this* key have *this* value?), not by a `COUNT(*) ... IS NOT NULL` total —
+a per-count check passes on the cluster that applied and tells you nothing about the one that
+didn't.
 
-### Which branches actually auto-apply
+## Which branches actually auto-apply
 
 | Path | Trigger | Timing |
 |---|---|---|
@@ -100,20 +127,64 @@ Consequence: **a folder whose database is not reachable from that host is skippe
 | Elastic Beanstalk container command (`worker/.ebextensions/030_dbchanges.config`) | worker **deploy** | on next deploy |
 
 The repo ships `config.alpha/beta/demo/hotfix/prod/stage/test/worker.ini`, therefore:
+
 - **Auto-apply within ~2 min of a push:** `_alpha`, `_beta`, `_demo`, `_hotfix`, `_stage`.
-- **`_production` does NOT auto-apply** — it would need `config.production.ini`, which does not exist (the shipped file is `config.prod.ini`). Production applies via the EB deploy container command instead, i.e. **on the next worker deploy**. Plan comms and expectations accordingly.
+- **`_production` does NOT auto-apply** — it would need `config.production.ini`, which does not
+  exist (the shipped file is `config.prod.ini`). Production applies via the EB deploy container
+  command instead, i.e. **on the next worker deploy**. Plan comms and expectations accordingly.
 
-## Gotchas
+## Steps
 
-- **A comment-only chunk stops the whole queue** (error 1065 + `exit()` on the prod path). Your malformed file blocks unrelated teammates' migrations — a team-wide failure, not a local one.
-- **No `DELIMITER`, no stored routines, no explicit `COMMIT`.** See the guard-pattern section.
-- **Error 1093** is why the preflight subquery must be wrapped in a derived table.
-- **A merged PR is not an applied change.** Confirmed live 2026-08-13 (PR dbchanges#265): after the merge into `_production`, both target tables were still 100% unchanged. Never tell a customer or a ticket "applied" off a merge — always re-read the data.
-- **A cross-database change half-applies without warning.** Same incident: the `TOGaDeskSupport` file landed and the `Core` file did not, leaving `assets.tag` 87/87 correct while `Core.AdvanceShippingNoticeUnits.assetTag` was 87/87 still empty — a state that *looks* fixed in the UI. Cause is the one-credential-set / folder-is-a-database model above. Verify every database in the change, per-pair.
-- **Retry semantics are a feature**: because the data change and the `_dbchanges` row share a transaction, a failing file re-runs next cycle. Do not "help" it with a manual COMMIT.
-- **⚠ SECURITY — hardcoded GitHub token.** `worker/crons/infrastructure/execute_dbchanges.php` contains a **plaintext GitHub personal access token** in the small config block near the top of the file (~L14–18), and interpolates it into a `shell_exec()` git-clone command line — which also exposes it in the worker host's process listing. Treat the token as **compromised**: rotate it, move it to config/env (`config.<env>.ini`), and pass it without embedding it in an argv string. No credential value is recorded here by design.
+1. Confirm the target schema/environment (`Core/` = legacy V1 `Core`).
+2. Branch per the git-workflow rules (`fix/...`, `feature/...`) — never commit to `_production`.
+3. Write **one file, commentary first, statements last**, no trailing comment chunk, no explicit
+   `COMMIT`, and no `DELIMITER`/stored-routine constructs.
+4. Wrap any risky data change in the derived-table preflight guard above so a drifted before-state
+   is a no-op rather than a wrong write.
+5. Open a PR into `_production` (or the target `_<env>` branch).
+6. After merge: `_<env>` branches apply within ~2 min; **`_production` waits for the next worker
+   deploy** — verify with a read-only query afterwards rather than assuming. **Merging the PR
+   applies nothing by itself** — `dbchanges` has no CI, no workflow, no runner of its own; every
+   application is driven from the worker tier.
+7. If the change spans more than one top-level (database) folder, verify **each database
+   separately** — see the silent-skip trap above.
 
-## Related
+## Gotchas
 
-- [Worker architecture](../../worker/architecture.md) — the worker tier drives every dbchanges application.
-- [NYCDOE ServiceNow integration](../../../../clients/nycdoe/features/servicenow-integration.md)
+- **A comment-only chunk stops the whole queue** (error 1065 + `exit()` on the prod path). Your
+  malformed file blocks unrelated teammates' migrations, so this is a team-wide failure, not a
+  local one.
+- **No `DELIMITER`, no stored routines, no explicit `COMMIT`.** See above.
+- **Error 1093** is why the preflight subquery must be wrapped in a derived table.
+- **A merged PR is not an applied change.** Confirmed live 2026-08-13 (PR dbchanges#265): after the
+  merge into `_production`, both target tables were still 100% unchanged. Never tell a customer or a
+  ticket "applied" off a merge — always re-read the data.
+- **A cross-database change half-applies without warning.** Same incident: the `TOGaDeskSupport`
+  file landed and the `Core` file did not, leaving `assets.tag` 87/87 correct while
+  `Core.AdvanceShippingNoticeUnits.assetTag` was 87/87 still empty — a state that *looks* fixed in
+  the UI. Cause is the one-credential-set / folder-is-a-database model above. Verify every database
+  in the change, per-pair.
+- **Retry semantics are a feature**: because the data change and the `_dbchanges` row share a
+  transaction, a failing file re-runs next cycle. Do not "help" it with a manual COMMIT.
+- **⚠ SECURITY — hardcoded GitHub token.** `worker/crons/infrastructure/execute_dbchanges.php`
+  contains a **plaintext GitHub personal access token** in the small config block near the top of
+  the file (~L14–18), and interpolates it into a `shell_exec()` git-clone command line — which
+  also exposes it in the worker host's process listing. Treat the token as **compromised**:
+  rotate it, move it to config/env (`config.<env>.ini`), and pass it without embedding it in an
+  argv string. No credential value is recorded here by design.
+
+## Change history
+- 2026-08-14 — Documented that each **top-level folder is a database name** and that the runner uses
+  the **first `[database*]` config group** for every folder, so a folder on another cluster is
+  **silently skipped** (bare echo, no `Logs.Errors`, no `exit()`, no retry). Confirmed live during
+  the DOE asset-tag backfill (PR dbchanges#265): merging the PR applied nothing, and then a
+  `TOGaDeskSupport`-only run left `Core` untouched — a half-fix that looked complete in the UI.
+  Added the rule that a multi-database change needs one run per cluster and **per-pair**
+  verification, not a non-null count. (sking)
+- 2026-07-29 — Repo onboarded to the KB (1.0 `dbchanges`, framework core sibling of `dbchanges2`).
+  Documented the `index.php` `";\n"` split + `mysqli_query()` model and the comment-only-chunk /
+  error-1065 queue abort, the per-file transaction & retry semantics, the derived-table preflight
+  guard as the only workable all-or-nothing pattern (verified MySQL 8.0.42), and which `_%`
+  branches actually auto-apply (`_production` does **not** — it lands on the next worker deploy).
+  Flagged the plaintext GitHub token in `worker/crons/infrastructure/execute_dbchanges.php` for
+  rotation. (sking)

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

@@ -2,26 +2,25 @@
 
 | Doc | Summary |
 |-----|---------|
-| [Library (1.0 Framework) Architecture](architecture.md) | The 1.0 `App_` framework core: bootstrap/autoloader, the `app/` (`App_`) + `browser/` (`Browser_`) class trees, and vendored packages; open for how any 1.0 app |
-| [Address Validation Gateway (App_Api_OfficeDepot::validateAddress + USPS fallback)](features/address-validation-gateway.md) | The shared 1.0 address-validation gateway (`App_Api_OfficeDepot::validateAddress` → USPS fallback); open when standardizing/verifying a typed address before sav |
-| [Where a new App_ class goes — the app/ folder IS a behavioral contract](features/app-class-placement-base-contracts.md) | Where a new `App_` class goes — each `app/` folder's base class carries real inherited behavior; open before creating any class under `app/model|client|api`. |
-| [App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)](features/app-sso-initiation.md) | Reusable 1.0 SP-initiated SAML SSO via `saml.togahub.com` (`App_Sso::initiate`); the canonical doc to follow for any "add SSO to `<1.0 app>`" request. |
-| [Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)](features/cron-execution-monitoring.md) | 1.0 cron check-in/out lifecycle via `App_Framework::cronInitialization()`/`cronFinished()` → `Common.CronJobExecutions`; open to monitor a 1.0 cron or read its |
-| [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | TOGa Refresh 2026 "View Recommended Services" routing — per-device diagnostic `resultCode` decides serviceselection vs techsupport; open when touching that rout |
-| [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | Elite bidirectional ticket/attachment sync between TOGA 2 and TOGaDesk (`App_Api_Toga2::syncWithTogadesk`); open for the sync mechanics, watermarks, and Elite-s |
-| [App_Email Queued Sending & Attachments (Common.EmailsQueued)](features/email-queue-attachments.md) | 1.0 `App_Email` queued sending + attachment embedding via `Common.EmailsQueued`; open when a queued email loses attachments or when deploying worker/togadesk to |
-| [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | Branded HTML email base class `App_Email_Template` (header/body/footer); open when building or fixing a 1.0 branded email or its Outlook rendering. |
-| [App_Email Side Effects & Test Mode (how to send a real email that writes nothing)](features/email-test-mode-and-write-free-sends.md) | 1.0 `App_Email::send()` side effects (log/queue writes, test-mode recipient rewrite) and how to send a genuinely write-free test; open before writing any 1.0 dr |
-| [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | 1.0 error-reporting into the shared 2.0 Logs DB (`App_Error_Capture::captureException`), mirroring 2.0's Issue/Event; open when adding a 1.0 capture path or deb |
-| [HTTP 500 Error Monitor (App_SystemMonitor_500Error) — and why its \"Error Type\" is not a diagnosis](features/http-500-error-monitor.md) | 1.0 monitor `App_SystemMonitor_500Error` watching `Logs.Api` responseCode=500; open when an api2 500 alert arrives — its "Error Type" is noise, use `error.id`. |
-| [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | Recipe for a new 1.0 (`App_`) app and for adding pages: folder-based MVC routing, page lifecycle, models, multi-DB config; open when standing up a 1.0 app or ad |
-| [NetSuite File Cabinet Content Retrieval via RESTlet (fetchInvoiceFile)](features/netsuite-filecabinet-restlet.md) | How 1.0 pulls NetSuite File Cabinet binary content (invoice PDFs) via a SuiteScript RESTlet (`fetchInvoiceFile`); open when fetching NetSuite file bytes over RE |
-| [assetType from NetSuite itemtype during Item Sync (opt-in per client)](features/netsuite-item-assettype-sync.md) | Stamp `Items.assetTypeId` from NetSuite `item.itemtype` during item sync (opt-in per client, fill-NULL-only); open before enabling asset-type mapping for a clie |
-| [NetSuite classification → ItemClasses sync (opt-in per client)](features/netsuite-item-class-sync.md) | Mirror NetSuite's classification tree into client `ItemClasses` + stamp `Items.itemClassId` (`getCreateItemClass`, opt-in per client); open before enabling item |
-| [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | 1.0 Phase-1 stamping of the NetSuite `isfulfillable` flag onto the Agilant source item during sync; open before changing fulfillability sync or a client overrid |
-| [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | Working reference for the Agilant NetSuite REST/SuiteQL integration (`App_Api_Netsuite_Rest`): auth, SuiteQL mechanics, table schemas, type/status codes, perfor |
-| [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | Non-obvious NetSuite SuiteQL/REST field semantics behind `App_Api_Netsuite_Rest` shims (signs, `tl.id`==line, `iscogs`, ShipItem cost, `createdFrom`, shim-shape |
-| [NetSuite Sync Alert Monitor (App_SystemMonitor_NetSuiteIntegration)](features/netsuite-sync-alert-monitor.md) | 1.0 monitor `App_SystemMonitor_NetSuiteIntegration` — flags stale per-client NetSuite sync checkpoints (>48h) to ClickUp; open when a sync-stale alert is missin |
-| [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | PC Matic B2B bidirectional ticket sync between TOGaDesk 1.0 and TOGA 2.0 (`App_Api_Toga2`); open for ticket-type maps, StarTech client onboarding, and the V1 th |
-| [App_Api_Toga2 — TOGa2 API Client & 1.0↔2.0 Sync Bridge](features/toga2-api-client-and-bridge.md) | `App_Api_Toga2` — the 1.0-side client for the TOGa2/api2 REST API + cross-framework sync routines (`send`/`authenticate`, options DSL, `syncWithToga`/`syncWithT |
-| [Rendering a 1.0 App_Email Template to HTML Offline (no DB, no send)](workflows/render-1-0-email-templates-offline.md) | Produce a standalone `.html` copy of any 1.0 `App_Email` template offline (no DB / mail / queue) via stubs; open when asked "show me exactly what we email the c |
+| [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. |
+| [Address Validation Gateway (App_Api_OfficeDepot::validateAddress + USPS fallback)](features/address-validation-gateway.md) | `App_Api_OfficeDepot::validateAddress()` is the shared 1.0 (`App_`) address-validation gateway. |
+| [Where a new App_ class goes — the app/ folder IS a behavioral contract](features/app-class-placement-base-contracts.md) | In `library/app/`, choosing a folder is **not** a filing decision — the autoloader maps `App_<Folder>_<File>` to `app/<folder>/<file>.php`, and each folder's ba |
+| [App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)](features/app-sso-initiation.md) | `App_Sso` (`library/app/sso.php`) is the **1.0 port of the 2.0 SAML gateway's SP-initiated SSO initiation**, packaged as a reusable, framework-level capability |
+| [Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)](features/cron-execution-monitoring.md) | `App_Framework::cronInitialization()` / `App_Framework::cronFinished()` (in `library/app/framework.php`) give every 1.0 (`App_`) cron job a check-in/check-out l |
+| [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | Two "View Recommended Services" buttons exist in the TOGa Refresh 2026 SR view: 1. |
+| [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. |
+| [App_Email Queued Sending & Attachments (Common.EmailsQueued)](features/email-queue-attachments.md) | `App_Email::send()` can either send **inline** (PHPMailer talks to SES right there) or **queue** the message: `base64(serialize($this))` is inserted into `Commo |
+| [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. |
+| [App_Email Side Effects & Test Mode (how to send a real email that writes nothing)](features/email-test-mode-and-write-free-sends.md) | `App_Email::send()` is **not** side-effect free. |
+| [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | The 1.0 side of the platform error-reporting pipeline (TRUE-78188). |
+| [HTTP 500 Error Monitor (App_SystemMonitor_500Error) — and why its \"Error Type\" is not a diagnosis](features/http-500-error-monitor.md) | `App_SystemMonitor_500Error` (`library/app/systemmonitor/500error.php`, title **"HTTP 500 Error Alert"**) is the 1.0 system monitor that watches **`Logs.Api` fo |
+| [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t |
+| [NetSuite File Cabinet Content Retrieval via RESTlet (fetchInvoiceFile)](features/netsuite-filecabinet-restlet.md) | How 1.0 pulls **File Cabinet binary content** (invoice PDFs) out of NetSuite over REST. |
+| [assetType from NetSuite itemtype during Item Sync (opt-in per client)](features/netsuite-item-assettype-sync.md) | `getCreateItem()` never sent `assetType`, so **every item the NetSuite importer created had `Items.assetTypeId = NULL`** — for every client, since the importer |
+| [NetSuite classification → ItemClasses sync (opt-in per client)](features/netsuite-item-class-sync.md) | `App_Api_Toga2::getCreateItemClass()` mirrors NetSuite's **classification tree** into the client's `ItemClasses` table and stamps `Items.itemClassId`. |
+| [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite `isfulfillable` flag during item sync and stamping it onto the **Agilant |
+| [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w |
+| [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. |
+| [NetSuite Sync Alert Monitor (App_SystemMonitor_NetSuiteIntegration)](features/netsuite-sync-alert-monitor.md) | `App_SystemMonitor_NetSuiteIntegration` (`library/app/systemmonitor/netsuiteintegration.php`, title **"NetSuite Sync Alert"**) is a 1.0 system monitor that watc |
+| [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | `library/app/api/toga2.php` handles bidirectional ticket sync for PC Matic B2B between TOGaDesk 1.0 and TOGA 2.0. |
+| [App_Api_Toga2 — TOGa2 API Client & 1.0↔2.0 Sync Bridge](features/toga2-api-client-and-bridge.md) | `App_Api_Toga2` (`library/app/api/toga2.php`, ~8400 lines) is the **1.0-side client for the TOGa 2 (`_underscore`/api2) public API** *and* the home of the cross |

package/knowledge/1.0/apps/library/architecture.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: architecture
 status: active
-updated: 2026-09-17
+updated: 2026-06-08
 owners: [jcardinal]
 files:
   - library/_.php
@@ -15,47 +15,57 @@ files:
 related: []
 ---
 
-The 1.0 `App_` framework core: bootstrap/autoloader, the `app/` (`App_`) + `browser/` (`Browser_`) class trees, and vendored packages; open for how any 1.0 app loads and where server-side classes live.
-
 ## Summary
 
-`library` is the shared repo for **all 1.0 (legacy) applications** — the `App_` framework. It provides every server-side PHP asset those apps consume: server-side classes, vendored third-party packages, and the bootstrap/autoloader. Target PHP 7.2+, compatible through 8.1. Each app `require`s `library/_.php` to bootstrap.
-
-**Critical rules:** All folder/file names under `app/` and `browser/` are **lowercase** (autoloader lowercases before lookup). **No front-end assets here** — JS/CSS belong in the `resources/` repo. **No Composer in consuming apps** — add packages directly to `library/`. Remove all `debugVar()` calls before merging. A class that only makes HTTP calls to an external/cross-framework API belongs in `app/api/` and should **extend nothing** (see the class-placement feature doc).
+`library` is the shared library repository for **all 1.0 (legacy) applications** — the
+`App_` framework. It provides every server-side PHP asset those apps consume:
+server-side classes, vendored third-party packages, and the bootstrap/autoloader.
+Target PHP 7.2+, compatible through 8.1.
 
 ## Role in the stack
 
 - **`library/`** — server-side PHP classes, third-party packages, bootstrap/autoloader.
-- **Application repos** — each `require`s `library/_.php` to bootstrap the framework.
-- **`resources/` repo** — purely front-end assets (JS/CSS).
+- **Application repos** — each app `require`s `library/_.php` to bootstrap the framework.
+- **`resources/` repo** — purely front-end assets (JS/CSS). **Do not put front-end here.**
 
 ## Bootstrap & autoloader (`_.php`)
 
-`_.php` is the single framework include. Every app starts with `require_once '/path/to/library/_.php';`. It:
+`_.php` is the single framework include. Every app starts with
+`require_once '/path/to/library/_.php';`. It:
 
-1. Sets PHP environment — `display_errors`, `error_reporting(E_ALL)`, timezone `America/Chicago`.
-2. Defines constants — `__APPROOT__` (resolved by walking up from the script's directory until a folder named `_` is found) and `__LIBROOT__` (the `library/` dir).
+1. Sets PHP environment — `display_errors`, `error_reporting(E_ALL)`, timezone
+   `America/Chicago`.
+2. Defines constants — `__APPROOT__` (resolved by walking up from the script's directory
+   until a folder named `_` is found) and `__LIBROOT__` (the `library/` dir).
 3. Registers the autoloader via `spl_autoload_register('autoloader')`.
 
-Global helper: `debugVar($input, $stopExecution, $withHrLineBreaker)` — dumps a variable as HTML `<PRE>`, optionally halting.
+Global helper: `debugVar($input, $stopExecution, $withHrLineBreaker)` — dumps a variable
+as HTML `<PRE>`, optionally halting. **Remove all `debugVar()` calls before merging.**
 
 ### Class-to-file mapping
 
-Convert the class name to a path by replacing every `_` with `/`, then **lowercase the entire result** and append `.php`:
+Convert the class name to a path by replacing every `_` with `/`, then **lowercase the
+entire result** and append `.php`:
 
 ```
 App_Email_Nycdoe_InstallationConfirmation
   → app/email/nycdoe/installationconfirmation.php   (under __APPROOT__ or __LIBROOT__)
 ```
 
+- All folder/file names **must be lowercase**.
 - Class names are **not** case-sensitive (autoloader lowercases before lookup).
-- Both `__APPROOT__` and `__LIBROOT__` are checked, so app-level classes can **shadow** library classes. Namespace separators (`\`) normalize to `_`.
+- Both `__APPROOT__` and `__LIBROOT__` are checked, so app-level classes can **shadow**
+  library classes. Namespace separators (`\`) normalize to `_`.
 
 ## Custom code — `app/` and `browser/`
 
 ### `app/` — back-end logic (prefix `App_`)
 
-Pure server-side business logic, no HTML output. Core singletons at root (`App_Config`, `App_Database`, `App_Auth`, `App_Api`, `App_Model`, `App_Email`, `App_Session`). Subfolders: `api/` (vendor integrations), `model/`, `email/`, `notification/`, `pdf/`, `asnprocessor/`, `catalog/`, `client/` (client overrides), `events/`, `edi/`, `trait/`, `systemmonitor/`, `mvc/`.
+Pure server-side business logic, no HTML output. Core singletons at root (`App_Config`,
+`App_Database`, `App_Auth`, `App_Api`, `App_Model`, `App_Email`, `App_Session`).
+Subfolders: `api/` (vendor integrations), `model/`, `email/`, `notification/`, `pdf/`,
+`asnprocessor/`, `catalog/`, `client/` (client overrides), `events/`, `edi/`, `trait/`,
+`systemmonitor/`, `mvc/`.
 
 ```php
 class App_Model_Client extends App_Model {
@@ -66,23 +76,40 @@ class App_Model_Client extends App_Model {
 }
 ```
 
-API pattern: `abstract class App_Api` with static methods; `class App_Api_Microsoft extends App_Api` with `initialize()`.
+API pattern: `abstract class App_Api` with static methods; `class App_Api_Microsoft
+extends App_Api` with `initialize()`.
 
 ### `browser/` — server-rendered UI (prefix `Browser_`)
 
-PHP classes that emit HTML. Core components (`Browser_Form`, `Browser_Datagrid`, `Browser_Dialog`, `Browser_Widget`, `Browser_Sidebar`) plus subfolders: `datagrid/` (140+ grid views), `form/`, `dialog/`, `search/`, `widget/`, `status/` (35+ states), `sidebar/`, `buttonbar/`, `calendar/`, `chat/`.
+PHP classes that emit HTML. Core components (`Browser_Form`, `Browser_Datagrid`,
+`Browser_Dialog`, `Browser_Widget`, `Browser_Sidebar`) plus subfolders: `datagrid/`
+(140+ grid views), `form/`, `dialog/`, `search/`, `widget/`, `status/` (35+ states),
+`sidebar/`, `buttonbar/`, `calendar/`, `chat/`.
 
 ## Third-party packages (vendored, no Composer)
 
-Consuming apps use **no Composer** — this library is the "vendor" directory. Packages are top-level folders: `phpmailer/`, `twilio/`, `php-imap2/`, `fpdf/`/`tcpdf/`, `PhpOffice/`/`phpexcel/`, `Smalot/`, `phpseclib/`, SAML libs, barcode/chart libs, `netsuitetoolkit/`, `payeezy/`, `Zend/`/`Psr/`/`pear/`, etc. The only Composer-managed packages: `phpoffice/phpspreadsheet ^1.6`, `smalot/pdfparser ^0.14.0`.
+The consuming apps use **no Composer** — this library is the "vendor" directory. Packages
+are top-level folders: `phpmailer/`, `twilio/`, `php-imap2/`, `fpdf/`/`tcpdf/`,
+`PhpOffice/`/`phpexcel/`, `Smalot/`, `phpseclib/`, SAML libs, barcode/chart libs,
+`netsuitetoolkit/`, `payeezy/`, `Zend/`/`Psr/`/`pear/`, etc. The only Composer-managed
+packages: `phpoffice/phpspreadsheet ^1.6`, `smalot/pdfparser ^0.14.0`.
 
-## App_String cross-framework crypto (`encryptWithKey` / `decryptWithKey`)
+## Key conventions
 
-`App_String::encryptWithKey($data, $key)` and `decryptWithKey($data, $key)` (public static) do **AES-256-CBC**: random IV via `random_bytes`, returning `base64(iv . ciphertext)` with openssl flag `0`. They are **deliberately byte-for-byte interoperable** with the 2.0 `_String::encryptWithKey` / `decryptWithKey`, so a SAML handoff token encrypted by the 2.0 gateway decrypts in any 1.0 app (round-trip verified). Net-new methods — no existing method changed. First consumer: the Tools app's `App_Auth` (`1.0/apps/tools/features/saml-sso-auth.md`).
+- **Lowercase everything** under `app/` and `browser/`.
+- **No front-end assets here** — JS/CSS belong in `resources/`.
+- **No Composer in consuming apps** — add packages directly to `library/`.
+- **`debugVar()`** is the debug helper; remove all calls before merging.
+- **Timezone** is always `America/Chicago` (set in `_.php`).
+- **`__APPROOT__`** is resolved by locating an ancestor folder named `_`; each app must
+  have that `_` folder at its root.
 
-## Gotchas
+## App_String cross-framework crypto (`encryptWithKey` / `decryptWithKey`)
 
-- **`debugVar()` can halt execution** (its `$stopExecution` arg) — remove all calls before merging.
-- **app/ classes silently shadow library/ classes.** The autoloader checks both `__APPROOT__` and `__LIBROOT__`, so an app-level file with the same class path overrides the core one with no warning.
-- **`__APPROOT__` resolution needs the `_` folder.** It is found by locating an ancestor folder named `_`; each app must have that `_` folder at its root or the constant won't resolve.
-- **⚠ SECURITY — OPEN, SYSTEMIC, not fixed (2026-09-17): TLS peer verification is OFF by default for EVERY `App_ApiTransaction` call.** `library/app/apitransaction.php:363` computes `CURLOPT_SSL_VERIFYPEER` from `$sslVerifyPeer` (default `null`, line 77) as `(((is_null($sslVerifyPeer) && isHTTPS()) || !$sslVerifyPeer) ? false : true)` — which resolves to **`false` on HTTPS**. So every outbound HTTPS call through the shared transport (NetSuite OAuth token exchange, every REST read, the RESTlet call, and any other `App_Api_*` integration) runs with peer verification disabled — a MITM can capture the bearer token or inject responses. Pre-existing core defect, **not** caused by the NetSuite retry; affects all callers. Fix: `CURLOPT_SSL_VERIFYPEER = is_null($sslVerifyPeer) ? isHTTPS() : (bool)$sslVerifyPeer;` and have `rest.php` pass `setSSLVerifyPeer(true)` explicitly. No fix chosen yet. The paired token-logging defect (`send()` writes the bearer token to the request log) is on the [SuiteQL/REST shim doc](features/netsuite-suiteql-rest-shim.md).
+`App_String::encryptWithKey($data, $key)` and `decryptWithKey($data, $key)` (public static) do
+**AES-256-CBC**: random IV via `random_bytes`, returning `base64(iv . ciphertext)` with openssl
+flag `0`. They are **deliberately byte-for-byte interoperable** with the 2.0
+`_String::encryptWithKey` / `decryptWithKey`, so a SAML handoff token encrypted by the 2.0
+gateway decrypts in any 1.0 app (round-trip verified). Net-new methods — no existing method
+changed, no behavior change for existing apps. First consumer: the Tools app's `App_Auth`
+(`1.0/apps/tools/features/saml-sso-auth.md`).

package/knowledge/1.0/apps/library/features/address-validation-gateway.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-08-13
 owners: [jcardinal]
 files:
   - library/app/api/officedepot.php
@@ -15,29 +15,63 @@ related:
   - ../../toga/features/odp-customer-search-loyalty-persistence.md
 ---
 
-The shared 1.0 address-validation gateway (`App_Api_OfficeDepot::validateAddress` → USPS fallback); open when standardizing/verifying a typed address before save, or debugging a saved-raw-address bug.
-
 ## Summary
+`App_Api_OfficeDepot::validateAddress()` is the shared 1.0 (`App_`) address-validation gateway.
+It is the entry point every TOGa 1.0 flow calls (via classic AJAX
+`ajaxAction('App_Api_OfficeDepot','validateAddress')`) to standardize/verify a typed address
+before it is saved. It wraps ODP's address-validation service and falls back to
+`App_Api_USPS::validateAddress()` (USPS REST API v3, OAuth `client_credentials`, in
+`library/app/api/usps.php`). It returns a standardized address (corrected city/casing/zip) that
+callers are expected to write back before saving.
 
-`App_Api_OfficeDepot::validateAddress()` is the shared 1.0 (`App_`) address-validation gateway. Every TOGa 1.0 flow calls it (via classic AJAX `ajaxAction('App_Api_OfficeDepot','validateAddress')`) to standardize/verify a typed address before save. It wraps ODP's address-validation service, falls back to `App_Api_USPS::validateAddress()` (USPS REST API v3, OAuth `client_credentials`), and returns a standardized address (corrected city/casing/zip) that callers must write back before saving.
-
-## How it works
-
-Entry points:
+## Key files / entry points
 - `library/app/api/officedepot.php` — `App_Api_OfficeDepot::validateAddress()`, the gateway.
 - `library/app/api/usps.php` — `App_Api_USPS::validateAddress()`, the fallback carrier.
 
-1. **Endpoint selection.** Calls the ODP **sandbox** endpoint when `App_Registry::inTestMode()` is true (`inTestMode` = `config['internal']['test_mode'] > 0`), and the **live** ODP endpoint otherwise. Production is effectively hard-pinned to live (comment "2024-01-22 JC - Always using production...").
-2. **On a real ODP answer** (HTTP 200, accept or reject) returns ODP's standardized result.
-3. **On any non-200 ODP response** (sandbox down/expired, etc.) falls back to `App_Api_USPS::validateAddress()` and returns the USPS result — a genuine standardization **or** a genuine bad-address rejection both count as a real answer and are returned.
-4. **Only when BOTH ODP and USPS are unavailable** returns `array('success' => true)` with no standardized fields (fail-open, so associates are never hard-blocked by an outage).
-
-## Gotchas
+## How it works
+1. **Endpoint selection.** The gateway calls the ODP **sandbox** endpoint when
+   `App_Registry::inTestMode()` is true (`inTestMode` = `config['internal']['test_mode'] > 0`),
+   and the **live** ODP endpoint otherwise. Production is effectively hard-pinned to live
+   (comment "2024-01-22 JC - Always using production...").
+2. **On a real ODP answer** (HTTP 200, whether it accepts or rejects the address) the gateway
+   returns ODP's standardized result.
+3. **On any non-200 ODP response** (sandbox down/expired, etc.) it falls back to
+   `App_Api_USPS::validateAddress()` and returns the USPS result — a genuine standardization
+   **or** a genuine bad-address rejection both count as a real answer and are returned.
+4. **Only when BOTH ODP and USPS are unavailable** does it return `array('success' => true)`
+   with no standardized fields (fail-open, so associates are never hard-blocked by an outage).
 
-- **Beta-bypass class of bug (fixed 2026-08-13).** Previously the ODP-failure `else` branch returned `array('success' => true)` with **no** standardized address fields and the USPS fallback was commented out. Beta/test uses the ODP **sandbox**; when the sandbox was down/expired, callers saw `success:true` and saved the **raw typed address** (wrong city, wrong casing) with no validation. Production was unaffected (working live ODP endpoint). The fix restores the USPS fallback so validation only truly fails open when **both** carriers are down.
-- **"Both unavailable" must check BOTH USPS service-down strings.** USPS signals unavailability two ways: `'Address validation service is temporarily unavailable'` **and** `'USPS OAuth authentication failed'`. The fail-open condition must match either. Checking only the first wrongly blocks associates when ODP is down *and* USPS OAuth also fails (a php-reviewer pass caught this).
-- **Front-end write-back anti-pattern (widespread, mostly UNFIXED).** Many 1.0 front-end callbacks use the gateway response only as a pass/fail **gate**, then rebuild the save payload from the raw DOM inputs — discarding the standardized `address1`/`city`/`state`/`zipCode` the gateway returned. So even a successful validation never persists the corrected address. Known flows still with this anti-pattern: `toga/app/togarefresh2026/servicerequests/finalizequote.php`, `toga/app/togarefresh2026/appointment/select.php`, `toga/app/servicerequests/builder.php`, `toga/app/loaners/checkout.php`, `toga/app/jobjackets/view.php`, and the `togarefresh2023` variants. The 2026-08-13 gateway fix protects all from the beta bypass, but the write-back was only corrected in the `togarefresh2026` customersearch flow (see related doc). When touching any of these, write the standardized address back into the inputs before building the save payload.
+## Gotchas / known issues
+- **Beta-bypass class of bug (fixed 2026-08-13).** Previously the ODP-failure `else` branch
+  returned `array('success' => true)` with **no** standardized address fields and the USPS
+  fallback was commented out. Beta/test uses the ODP **sandbox**; when the sandbox was
+  down/expired, callers saw `success:true` and saved the **raw typed address** (wrong city,
+  wrong casing) with no validation. Production was unaffected because it hits the working live
+  ODP endpoint. The fix restores the USPS fallback so a validation only truly fails open when
+  **both** carriers are down.
+- **"Both unavailable" must check BOTH USPS service-down strings.** USPS signals unavailability
+  two ways: `'Address validation service is temporarily unavailable'` **and**
+  `'USPS OAuth authentication failed'`. The fail-open condition must match either. Checking only
+  the first string wrongly blocks associates when ODP is down *and* USPS OAuth also fails
+  (a php-reviewer pass caught this).
+- **Front-end write-back anti-pattern (widespread, mostly UNFIXED).** Many 1.0 front-end
+  callbacks use the gateway response only as a pass/fail **gate**, then rebuild the save payload
+  from the raw DOM inputs — discarding the standardized `address1`/`city`/`state`/`zipCode` the
+  gateway returned. So even a successful validation never persists the corrected address. Known
+  flows with this anti-pattern still present:
+  `toga/app/togarefresh2026/servicerequests/finalizequote.php`,
+  `toga/app/togarefresh2026/appointment/select.php`,
+  `toga/app/servicerequests/builder.php`, `toga/app/loaners/checkout.php`,
+  `toga/app/jobjackets/view.php`, and the `togarefresh2023` variants. The 2026-08-13 gateway fix
+  protects all of them from the beta bypass, but the write-back was only corrected in the
+  `togarefresh2026` customersearch flow (see related doc). When touching any of these, write the
+  standardized address back into the inputs before building the save payload.
 
-## Related
+## Related docs
+- `../../toga/features/odp-customer-search-loyalty-persistence.md` — the customersearch save
+  flow, where the write-back fix was applied.
 
-- `../../toga/features/odp-customer-search-loyalty-persistence.md` — the customersearch save flow, where the write-back fix was applied.
+## Change history
+- 2026-08-13 — Fix: restored the USPS fallback in `App_Api_OfficeDepot::validateAddress` so the
+  beta/sandbox path no longer fakes `success:true` and saves unvalidated addresses; fail-open now
+  requires BOTH ODP and USPS down, checking both USPS service-down strings. (jcardinal)