toga-ai 1.0.118 → 1.0.119

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

@@ -5,5 +5,6 @@
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
+| [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql |

package/knowledge/2.0/apps/_underscore/features/per-client-database-connections.md

@@ -0,0 +1,91 @@
+---
+title: Per-Client Database Connections & the Local Logs Trap
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-18
+owners: ["dfranks"]
+files:
+  - _underscore/Database.php
+  - _underscore/ApiRequest.php
+  - _underscore/Model/Client/Logs/Api.php
+related:
+  - ../architecture.md
+---
+
+## Summary
+
+When `_underscore` serves a request for a client it opens **three distinct per-client
+database connections**, not one. Each is an alias whose real schema name comes from Core's
+`Databases` table for that client. Missing any one of them locally makes `mysqli_connect`
+throw `Unknown database` and the whole request returns **HTTP 500 / EO-1** — even when the
+actual work succeeded. The most common victim is the **logs** connection, because API
+transaction logging is on by default.
+
+## Key files / entry points
+
+- **`_underscore/Database.php`** — `connect()` (line ~410) resolves a connection *alias*
+  (`Client`, `ClientLogs`, `Archive`) to the concrete schema via the Core join that selects
+  `ClientDatabase.name`, `LogDatabase.name`, `ArchiveDatabase.name` (lines ~64–137). The alias
+  `_underscore::DB_CLIENT_LOGS` maps to the per-client `Logs_<Id>` schema.
+- **`_underscore/ApiRequest.php`** (line ~240) — writes each API transaction to the logs DB
+  via `_Model_Client_Logs_Api` (falls back to `_Model_Core_Logs_Api` only when the client-logs
+  register points at the same DB as core-logs). This is what fires the logs connection.
+- **`_underscore/Model/Client/Logs/Api.php`** — `const DATABASE = _underscore::DB_CLIENT_LOGS;
+  const TABLE = 'Api';` — the model behind the logged row.
+
+## How it works
+
+The three per-client aliases and their concrete local schemas:
+
+| Alias | Schema (per client) | Holds |
+|---|---|---|
+| `Client` (data) | `Client_<Id>` | operational data |
+| `ClientLogs` (`DB_CLIENT_LOGS`) | `Logs_<Id>` | **API transaction logging** |
+| `Archive` | `Archive_<Id>` | historical snapshots |
+
+`<Id>` is the client's `clientIdentifier` from `Core.Clients` (e.g. `Growrk` → `Client_Growrk`,
+`Logs_Growrk`, `Archive_Growrk`). A `Logs_<Id>` schema has 5 tables:
+`Api, CustomRecordField, Error, Record, RecordField`.
+
+## Data model
+
+`Logs_<Id>.Api` columns: `id, uuid, dtStamp, transactionId, apiId, userId, isAuthRequest,
+direction, source, sourceIp, instanceId, executionTimeSeconds, method, hostname, route,
+responseCode, queryString, requestHeaders, requestPayload, responseHeaders, responsePayload`.
+Engine InnoDB, `utf8mb4_unicode_ci`.
+
+## Client variations
+
+None — uniform across clients; only the `<Id>` suffix differs.
+
+## Gotchas / known issues
+
+- **The "logs DB write trap" (local dev).** A laptop usually imports only `Client_<Id>`, not
+  `Logs_<Id>`/`Archive_<Id>`. Because logging is **on by default**, the first request 500s on
+  `Unknown database 'logs_<id>'` from `ApiRequest.php`'s logging write — *after* the real work
+  ran — so it reads like a mysterious outage, not a missing schema. The trace shows
+  `_Database::connect("ClientLogs","READ")` → `mysqli_connect(..., "Logs_<Id>")`.
+- **Fix once and for all locally:** for every client you run locally, create all three schemas.
+  For logs, structure-only is enough (you never need prod log rows locally):
+  `mysqldump -h reader1.logs.database.togahub.com -u admin -p<pw> --no-data --no-tablespaces
+  --set-gtid-purged=OFF --column-statistics=0 Logs_<Id> | mysql -u root Logs_<Id>` (create the
+  empty DB first). Data DB comes from `reader1.client.database.togahub.com` (see the local-DB
+  refresh notes). This is a **local-environment** gap, not a code bug — do not "fix" it by
+  disabling logging in shared code.
+- Related 1.0 analogue: the legacy `App_` worker has the same hazard writing to `Logs.API`
+  (`db_logs`) — the laptop trap there is documented separately in the worker NetSuite bootstrap
+  notes.
+
+## Change history
+
+- 2026-06-18 — Documented after the `Logs_Growrk`/`Logs_Aig` local 500s while testing the
+  NetSuite TOGa Supply wrappers; created the missing local log schemas structure-only. (dfranks)
+
+## Related docs
+
+- [_underscore architecture](../architecture.md)
+- [NetSuite → TOGa Supply per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md) — the work that surfaced this.

package/knowledge/INDEX.md

@@ -14,7 +14,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 7 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 8 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 8 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 3 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 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.118",
+  "version": "1.0.119",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",