toga-ai 1.0.448 → 1.0.449

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

@@ -12,6 +12,7 @@
 | [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/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.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 |
 | [_Cloud S3 helpers (copy / get / delete / list)](features/cloud-s3-helpers.md) | `_Cloud` centralizes AWS SDK S3 usage for the 2.0 stack so the `S3Client` never leaks into workers or app code. | _underscore/Cloud.php |
 | [_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps](features/component-model-namespace-registration.md) | Every **project-local** `_Component_*` and `_Model_*` class in a 2.0 app **must declare the project namespace** at the top of the file: ```php namespace <NAMESP | _underscore/Loader.php, worker2/_.php, api2/_.php, worker2/Component/Forecast/Db/Db.php, worker2/Component/Forecast/SaleImport/SaleImport.php, api2/Component/Api/Netsuite/Netsuite.php |
+| [Re-pointing a DB alias mid-request (_Database::register park/restore)](features/database-alias-repointing.md) | `_Database` keys **all live per-database runtime state by the connection ALIAS** (`Client` / `_underscore::DB_CLIENT`, `ClientLogs`, `Archive`), **not** by the | _underscore/Database.php, _underscore/Query.php, api2/Component/Api/V2/V2.php, api2/Component/Api/CrossClient/CrossClient.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 |
 | [Error Reporting — Issue/Event Aggregation (agreed POST-to-receiver design)](features/error-reporting-issue-event.md) | Platform-wide error-reporting infrastructure for TOGA 2.0, built around a two-table **Issue / Event** aggregation model in the shared **Core Logs DB**. | _underscore/Error.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, dbchanges2/Logs/2026-07-06 - Issue and Event tables.sql |
 | [Record-Changed Event Publishing (_Event::publish to SQS)](features/event-publish-sqs.md) | `_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event pipeline. | _underscore/Event.php |

package/knowledge/2.0/apps/_underscore/features/database-alias-repointing.md

@@ -0,0 +1,120 @@
+---
+title: Re-pointing a DB alias mid-request (_Database::register park/restore)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-27
+owners: ["jcardinal"]
+files:
+  - _underscore/Database.php
+  - _underscore/Query.php
+  - api2/Component/Api/V2/V2.php
+  - api2/Component/Api/CrossClient/CrossClient.php
+related:
+  - ./per-client-database-connections.md
+  - ../../api2/features/cross-client-data-retrieval.md
+  - ../architecture.md
+---
+
+## Summary
+
+`_Database` keys **all live per-database runtime state by the connection ALIAS**
+(`Client` / `_underscore::DB_CLIENT`, `ClientLogs`, `Archive`), **not** by the physical schema
+name. Four statics are alias-keyed: `$_connections`, `$_queryCache`, `$_transactionStarts`,
+`$_modelCache`.
+
+Historically `_Database::register()` only rewrote `$_registers[$alias]`. It never touched
+`$_connections`, and `getConnection()` returns an already-cached link if one exists under that
+key. So **re-registering an alias changed the credentials but not the open mysqli link** — every
+query after a mid-request client switch silently ran against the *previous* client's database.
+`register()` now **parks and restores** the alias-keyed live state when an alias is re-pointed at a
+different physical database, which makes mid-request client switching actually work.
+
+## Key files / entry points
+
+- **`_underscore/Database.php`** — `register()` (park/restore), `registerClientDatabases()`
+  (per-client alias registration + Core host lookup), `getConnection()`,
+  `transactionCommit()` / `transactionRollback()` / `resolveParkedTransactions()`.
+- **`api2/Component/Api/V2/V2.php`** — a call site that switches the `Client` alias mid-request.
+- **`api2/Component/Api/CrossClient/CrossClient.php`** (~lines 193, 201, 207) — the cross-client
+  fan-out uses the same `registerClientDatabases()` + `_underscore::DB_CLIENT` pattern.
+
+## How it works
+
+Two new statics on `_Database`:
+
+- `public static $_aliases` — alias => the physical database name currently behind it.
+- `private static $_parked` — physical database name => that database's parked live state
+  (connection, queryCache, transactionStart, modelCache).
+
+On `register()`:
+
+1. If the alias is being pointed at the **same** physical database, this is a **no-op** for live
+   state. (This also fixes a latent bug where a redundant `register()` reset an already-begun
+   transaction flag from `true` back to `false`.)
+2. If it is being pointed at a **different** database, the **outgoing** database's connection,
+   queryCache, transactionStart and modelCache are parked under its own physical name, and the
+   alias slots are cleared.
+3. The **incoming** database's previously-parked state is restored if present — so an open
+   transaction on that database continues uninterrupted. If nothing is parked for it,
+   `transactionStart()` is armed as before.
+
+`registerClientDatabases()` caches only the **Core host-lookup row** per clientId
+(`static $cachedLookups`), and always runs the three `register()` calls. It **throws** when the
+Core host lookup returns no row.
+
+**Request boundary.** `transactionCommit(null)` / `transactionRollback(null)` iterate
+`$_connections`, which is alias-keyed, so a parked database would be skipped and left with an open
+transaction on a pooled connection. The null-branch of both now calls private
+`resolveParkedTransactions(bool $isCommit)`, which sweeps `$_parked` for any entry with
+`transactionStart === true`, commits or rolls it back, and marks it resolved so a later
+switch-back cannot double-commit.
+
+## Key rules
+
+- **Re-registering an alias does not, by itself, reconnect.** Any code that changes credentials
+  under an existing alias must go through `register()`'s park/restore path.
+- **Any change that hides a connection from `$_connections` must also resolve its transaction at
+  the request boundary** — otherwise the transaction leaks onto a pooled connection.
+- **Client-DB config that cannot be resolved must throw, not fall through.** Falling through leaves
+  the aliases pointed at the previous client, which reads as "wrong data," not "an error."
+
+## Design tradeoff (deliberate)
+
+Park/restore was chosen over re-keying all four caches by **physical database name**, which would
+have touched `Database.php`, `Query.php` and `Model.php`. Park/restore is contained to one function
+and keeps every existing call site working unchanged. It is correct **only while every access to
+those four caches goes through the alias** — nothing accesses them by physical name today. If that
+ever changes, the re-keying approach becomes the right fix.
+
+## Gotchas / known issues
+
+- **The original symptom is silent, not an error.** A cross-client user lookup aimed at
+  `Client_Compass` returned **0 rows** because it actually ran against `Client_True` (the home
+  client). Wrong-database bugs here look like missing data.
+- **The old `static $cached` guard in `registerClientDatabases()` made switch-back a no-op.** It was
+  keyed on clientId (commented as an "efficiency patch so we don't re-register and break
+  connections") and skipped the entire registration block for any client already seen in the
+  request — so the common "switch to B, then switch back to A" pattern never re-registered A.
+  Replaced by `$cachedLookups`, which caches only the Core lookup.
+- **`CrossClient.php` had the same latent bug** and needed no edit — the `Database.php` fix corrects
+  its cross-client reads in place.
+- **Not yet runtime-tested** as of this capture: `php -l` passes and php-reviewer cleared the diff,
+  but no live cross-client run has confirmed it.
+
+## Change history
+
+- 2026-07-27 — Initial capture. Root-caused a cross-client API bug to alias-keyed live state in
+  `_Database`: re-registering an alias never swapped the open mysqli link, so post-switch queries
+  hit the previous client's DB. Added `$_aliases`/`$_parked` park/restore in `register()`,
+  `resolveParkedTransactions()` on the null-branch of commit/rollback (parked transactions were
+  invisible to the request boundary), a throw when the Core host lookup returns no row, and
+  replaced the `static $cached` no-op guard with `$cachedLookups`. (jcardinal)
+
+## Related docs
+
+- [Per-Client Database Connections & the Local Logs Trap](./per-client-database-connections.md)
+- [Multi-Client (Cross-Client) Data Retrieval](../../api2/features/cross-client-data-retrieval.md)

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-23
+updated: 2026-07-27
 owners: ["dfranks", "jcardinal", "mhammontree", "apeterson", "kyalamarthi"]
 files:
   - _underscore/Database.php
@@ -16,6 +16,7 @@ files:
 related:
   - ../architecture.md
   - ../workflows/local-db-refresh-from-beta.md
+  - ./database-alias-repointing.md
 ---
 
 ## Summary
@@ -118,12 +119,20 @@ here — they live in `Config/*.ini`.)
   A connect failure here threw past `api()` and got masked by `Route.php` as the misleading line-525
   "Failed to determine how to render view" error — see the Route.php swallow→mask gotcha in
   [_underscore architecture](../architecture.md#gotchas--known-issues).
+- **These aliases key ALL live connection state — re-registering one does not reconnect.**
+  `$_connections`, `$_queryCache`, `$_transactionStarts` and `$_modelCache` are keyed by the
+  alias (`Client`, `ClientLogs`, `Archive`), not by the physical schema, so switching a client
+  mid-request needs `_Database::register()`'s park/restore path. See
+  [Re-pointing a DB alias mid-request](./database-alias-repointing.md).
 - 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-07-27 — Recorded that the three per-client aliases key **all** live connection state, so
+  re-pointing an alias mid-request does not reconnect on its own; split the detail into
+  [Re-pointing a DB alias mid-request](./database-alias-repointing.md). (jcardinal)
 - 2026-07-23 — Documented that the **`Team` schema** (`Tasks`/`Sprints`, `_Model_Team_*`,
   `DB_TEAM`) is not a first-class api2 DB (not in `Records.aclDatabase`, which is CORE/CLIENT
   only) and physically resolves to the **core cluster** (reads → `reader1.core…`, writes →

package/knowledge/2.0/apps/api2/features/cross-client-data-retrieval.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: draft
-updated: 2026-07-07
+updated: 2026-07-27
 owners: [jcardinal]
 files:
   - api2/Component/Api/CrossClient/CrossClient.php
@@ -21,6 +21,7 @@ related:
   - ./encrypted-user-uuid-auth-handoff.md
   - ../../_underscore/features/per-client-database-connections.md
   - ../../_underscore/features/acl-permission-chain.md
+  - ../../_underscore/features/database-alias-repointing.md
 ---
 
 ## What it is
@@ -111,10 +112,19 @@ for how it sits among the shared/per-client clusters.
   emits `(object)$outRow`.
 - **The X-Cross-Client / X-Cross-User custom-header transport was a dead stub** — the V2 engine
   never reads such headers. The real transport is the two-phase encrypted-UUID auth handshake.
+- **Switching the `Client` DB alias mid-request used to silently not switch.** `CrossClient.php`
+  (~lines 193/201/207) uses `_Database::registerClientDatabases()` + `_underscore::DB_CLIENT`, and
+  `_Database` keys its live connection state by **alias**, not physical schema — so cross-client
+  reads were executing against the *home* client's DB and returning 0 rows. Fixed in
+  `_underscore/Database.php` (no api2 edit needed); see
+  [Re-pointing a DB alias mid-request](../../_underscore/features/database-alias-repointing.md).
 - **`curl_multi` busy-spin guard** — both multi loops `usleep(100)` when
   `curl_multi_select() === -1`.
 
 ## Change history
+- 2026-07-27 — Root-caused cross-client reads hitting the home client's DB: `_Database` keys live
+  connection state by alias, so re-registering `DB_CLIENT` never swapped the open link. Fixed in
+  `_underscore/Database.php`; CrossClient needed no edit. (jcardinal)
 - 2026-07-07 — Initial capture: scatter-gather cross-client retrieval engine (orchestrator, watermark
   k-way merge, keyset pagination Phase 0a/0b, `client`-option delegation, Cache cluster id 145).
   Code-complete + reviewer-hardened, not yet runtime-tested. (jcardinal)

package/knowledge/INDEX.md

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