toga-ai 1.0.761 → 1.0.763

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

@@ -21,7 +21,7 @@
 | [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 |
 | [2.0 Email Send Pipeline (queue + Send worker)](features/email-send-pipeline.md) | In 2.0, `_Email::send()` **does not transmit** — it queues the message. | _underscore/Email.php, _underscore/String.php, worker2/Worker/Infrastructure/Email/Send.php, _underscore/Model/Client/Logs/Email.php, _underscore/Model/Client/Logs/EmailAttachment.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/Quad/ApprovalDecision.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
-| [Error Reporting — Issue/Event Capture, Fingerprinting & Aggregation](features/error-reporting-issue-event.md) | Platform-wide error reporting for TOGA 2.0, built on an **Issue / Event** aggregation model in the **shared Core Logs DB**. | _underscore/Error.php, _underscore/Database.php, _underscore/Exception/Business.php, api2/Controller/Index.php, worker2/Controller/Index.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, _underscore/Model/Core/Logs/IssueFingerprint.php, _underscore/Model/Core/Logs/IssueClickupTask.php, _underscore/Model/Core/Logs/IssueEmailAddress.php, _underscore/Model/Core/Logs/IssueAreaOwner.php, worker2/Worker/Infrastructure/Errors.php, tools/mvc/errors/issue/get.php, tools/mvc/errors/post.php, dbchanges2/Logs/2026-07-30a - Error reporting Issues and Events.sql, dbchanges2/Logs/2026-08-01a - Rename tables to singular.sql, dbchanges2/Logs_Client/2026-08-01a - Drop Error table.sql, dbchanges2/Core/2026-07-30a - Error escalation cron job.sql |
+| [Error Reporting — Issue/Event Capture, Fingerprinting & Aggregation](features/error-reporting-issue-event.md) | Platform-wide error reporting for TOGA 2.0, built on an **Issue / Event** aggregation model in the **shared Core Logs DB**. | _underscore/Error.php, _underscore/Query.php, _underscore/Database.php, _underscore/Exception/Business.php, _underscore/Exception/Database.php, _underscore/Test/DatabaseFingerprint.php, api2/Controller/Index.php, worker2/Controller/Index.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, _underscore/Model/Core/Logs/IssueFingerprint.php, _underscore/Model/Core/Logs/IssueClickupTask.php, _underscore/Model/Core/Logs/IssueEmailAddress.php, _underscore/Model/Core/Logs/IssueAreaOwner.php, worker2/Worker/Infrastructure/Errors.php, tools/mvc/errors/issue/get.php, tools/mvc/errors/post.php, dbchanges2/Logs/2026-07-30a - Error reporting Issues and Events.sql, dbchanges2/Logs/2026-08-01a - Rename tables to singular.sql, dbchanges2/Logs_Client/2026-08-01a - Drop Error table.sql, dbchanges2/Core/2026-07-30a - Error escalation cron job.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 |
 | [FIELD_STORAGE fields — per-row lazy hydration and the platform-wide missing-column 500](features/field-storage-row-hydration.md) | `FIELD_STORAGE` is the 2.0 field type for blob-backed columns (S3 or local folder). | _underscore/Model.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/Invoice.php, dbchanges2/Core/HISTORIC/2024/2024-11b - item-fulfillments.sql |
 | [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/probe_je_shape.php, test/@dave/fixer.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |

package/knowledge/2.0/apps/_underscore/features/error-reporting-issue-event.md

@@ -6,12 +6,15 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-19
+updated: 2026-09-03
 owners: ["dfranks", "jcardinal", "mhammontree", "ajean", "bala", "apeterson"]
 files:
   - _underscore/Error.php
+  - _underscore/Query.php
   - _underscore/Database.php
   - _underscore/Exception/Business.php
+  - _underscore/Exception/Database.php
+  - _underscore/Test/DatabaseFingerprint.php
   - api2/Controller/Index.php
   - worker2/Controller/Index.php
   - _underscore/Model/Core/Logs/Issue.php
@@ -132,6 +135,61 @@ produced a different hash on every request — dedup never actually worked.
 cannot orphan a curated Issue: an admin repoints the new fingerprint at the existing Issue
 from the Tools console to merge them.
 
+#### Database errors fingerprint on the MESSAGE, not the trace (added 2026-09-03)
+
+The trace-based scheme above **over-merges database errors**, because they all surface from a
+few shared query methods. Every DB failure is thrown as a plain `Exception` from `_Query`, so
+their top ~5 frames are nearly identical (e.g. `_Query->getFoundRows()` → `processRoutePairs()`
+→ `execute()`). The one thing that told two DB bugs apart — the message (errno + column/table) —
+was exactly what the fingerprint **discards**. Result: production Issue `3L` (id 64) bundled a
+`1146` "table doesn't exist" **plus four different `1054` "unknown column"** bugs, across
+clients, into one Issue with ~2,514 occurrences — genuinely different defects hidden as one.
+
+The fix routes DB errors down their own fingerprint path:
+
+- **`_Query` now throws a typed `_Exception_Database`** (`_underscore/Exception/Database.php`,
+  `class _Exception_Database extends Exception`) instead of a plain `Exception`, carrying typed
+  `errorNumber` / `errorText` (getters `getErrorNumber()` / `getErrorText()`). It **extends plain
+  `Exception`, NOT `_Exception_Validation`**, so a DB error stays **HTTP 500 + creates a
+  `Logs.Issue`** (api2 maps only `_Exception_Validation` to 400). Every existing
+  `catch (Exception|Throwable)` and the deadlock-retry (which reads the stored errno, not the
+  type) are unaffected. It **deliberately does NOT keep the SQL** as a property/getter — that
+  avoids an easy leak of a query with literal values.
+- **`_Error::buildFingerprint()` gains an early `instanceof _Exception_Database` branch** →
+  `buildDatabaseFingerprint()`, which keys the fingerprint on
+  **`errno + normalizeDatabaseErrorText(errorText)`** instead of stack frames. So DB errors
+  split by exact table/column, while everything else keeps the trace scheme.
+
+`normalizeDatabaseErrorText()` masks the error text, **in this order**, so no per-row value or
+echoed SQL fragment reaches the shared `Logs.IssueFingerprint` table:
+
+1. Cap the input at 2000 chars.
+2. **Strip the tenant DB prefix** `(Client|Archive|Logs)_<Tenant>.` from identifiers — so the
+   **same bug on two clients is ONE Issue** (which tenant is still recorded on `Event.clientId`).
+3. Mask the value in `Duplicate entry '<value>' for key '<key>'` — **keep the key**, drop the
+   value (groups across values, still splits on a different key).
+4. **DEFAULT-DENY:** keep a quoted token only if it matches a schema-identifier shape
+   `^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$`; otherwise mask it to `?`. This keeps
+   row values, password hashes, and echoed SQL fragments from a `1064` **out** of the shared
+   fingerprint table.
+5. Digits → `N`.
+
+`firstApplicationArea()` derives the context `areaPath` from the first application frame.
+
+> **Forward-only, one-time re-grouping (expected).** Existing Issues keep their old fingerprint
+> hashes; new events form new fingerprints. On deploy, Issue `3L` fans out into ~5 fresh Issues
+> — fresh notifications and up to 5 new ClickUp tasks, **no carryover of any muting**. This is a
+> one-time, deliberate effect. **No schema change.** (CTO-reviewed: AGREE-WITH-ALTERNATIVE —
+> scope message-based grouping to DB errors ONLY, because arbitrary exception messages have no
+> known shape to mask safely.)
+
+> **No PHPUnit harness in `_underscore`.** There is only the vendored `library` test suite. The
+> masking is covered by a **standalone CLI script**, `_underscore/Test/DatabaseFingerprint.php`
+> (`php Test/DatabaseFingerprint.php`, 16 checks): the 5 errors that merged into `3L` now split
+> into 5; same bug on two clients = one Issue; duplicate-entry groups across values but splits on
+> the key; default-deny masks non-identifier values / hashes / SQL fragments; a different errno
+> is a different Issue.
+
 ### Where each exception class routes (the class you throw IS the routing decision)
 
 | Thrown class | HTTP | Sentry | `Logs.Issue` | Fingerprint / routing |
@@ -139,6 +197,7 @@ from the Tools console to merge them.
 | `_Exception_Validation` | **400** | no | **no** | n/a — bad client input. Still leaves a full `Logs.Api` row (see [api2 request logging](../../api2/features/request-logging.md)) |
 | `_Exception_Business` | **4xx** (was 500 before 2026-08-04) | yes | **yes** | stable `issueKey` (refactor-immune) → business recipients configured in the Tools console. **Now a subclass of `_Exception_Validation` — must be caught FIRST, see below** |
 | plain global `Exception` | **500** | yes | **yes** | **trace**-based fingerprint (moves when code moves) → developer ClickUp task |
+| `_Exception_Database` | **500** | yes | **yes** | **not thrown by hand** — `_Query` throws it for every DB error. **Fingerprinted by `errno + masked error text`, not trace** (below). Subclass of plain `Exception`, so it routes exactly like one → developer ClickUp task |
 | `_Exception` | — | — | — | **never throw it deliberately** (below) |
 
 Verified against `api2/Controller/Index.php` (≈L205-245, L369-377) and `_Error.php`
@@ -567,6 +626,16 @@ gracefully — it silently deletes all observability for the whole tier. Any cha
   redactor (in `_underscore/Error.php` **and** `library/app/error/capture.php` together, per the
   gotcha above), and until then **never paste a `Logs.Event.context` or `Logs_<Client>.Api` row
   into a ticket, chat, or knowledge doc** — those rows carry live tokens and customer PII.
+- **⚠ OPEN (pre-existing, not fixed 2026-09-03): the raw DB-error message — including ~120 chars
+  of SQL with literal values and the tenant DB name — is stored into `Issue.subject` /
+  `Event.errorMessage`.** `_Error.php` (~L413 and ~L487) does `substr(..., 255)` of the assembled
+  message ("Database Error Occurred… Query:\n<sql>") into those columns on the **shared** `Logs`
+  cluster. This predates the `_Exception_Database` work (the old plain `Exception` carried the
+  same message), so it did not block that change. **Recommended follow-up:** for
+  `_Exception_Database`, store the **masked signature**
+  (`'DB #' . errno . ': ' . normalizeDatabaseErrorText(errorText)`) as subject/errorMessage
+  instead of the raw SQL. The 2026-09-03 fix shipped **without** this — treat it as a known
+  open item.
 - **Hand-written SQL is what a table rename actually breaks — and it fails *after* the model
   succeeds.** The singular rename left plural literals in hand-written statements across four
   files, so `$issue->save()` succeeded and then `UPDATE Issues …` threw **1146** before the
@@ -696,6 +765,26 @@ read you feed it — `_Error` promotes a *"read property on int"* warning into a
 
 ## Change history
 
+- 2026-09-03 — **Database errors now fingerprint on the message, not the trace.** Root cause of
+  a real prod problem: Issue `3L` (id 64, ~2,514 occurrences) bundled a `1146` plus four
+  different `1054` bugs across clients into one Issue, because every DB error is thrown from a
+  few shared `_Query` methods with near-identical top frames and the trace scheme drops the
+  message — the only thing telling them apart. Fix: `_Query` (~L356) now throws a typed
+  **`_Exception_Database`** (`_underscore/Exception/Database.php`, extends **plain `Exception`**
+  so it stays 500 + `Logs.Issue`; typed `errorNumber`/`errorText`; deliberately keeps NO SQL to
+  avoid a value leak). `_Error::buildFingerprint()` gets an early `instanceof _Exception_Database`
+  branch → `buildDatabaseFingerprint()`, keyed on `errno + normalizeDatabaseErrorText(errorText)`.
+  The masker: cap 2000 chars; strip the tenant DB prefix so the same bug on two clients is ONE
+  Issue (tenant still on `Event.clientId`); mask the duplicate-entry value but keep the key;
+  **default-deny** — keep a quoted token only if it matches a schema-identifier shape, else `?`,
+  so no row values/hashes/SQL fragments reach the shared `Logs.IssueFingerprint`; digits → `N`.
+  Forward-only, one-time re-grouping on deploy (`3L` fans into ~5 fresh Issues, no muting
+  carryover, no schema change). CTO AGREE-WITH-ALTERNATIVE: scope message-grouping to DB errors
+  only. No PHPUnit harness in `_underscore`, so covered by a standalone CLI script
+  `_underscore/Test/DatabaseFingerprint.php` (16 checks). **Left OPEN (pre-existing, cso-flagged):**
+  the raw DB-error message with ~120 chars of literal-value SQL + the tenant DB name is still
+  `substr(...,255)` into `Issue.subject`/`Event.errorMessage` on the shared `Logs` cluster —
+  recommended follow-up is to store the masked signature there instead. (jcardinal)
 - 2026-08-19 — Recorded that **email recipients are configured per `issueId`, not per `issueKey`**,
   so they cannot be pre-configured before a condition first fires — the `Logs.Issue` row must exist
   first, which means the **first occurrence of any new business exception always routes to a

package/knowledge/2.0/apps/toga-blox/INDEX.md

@@ -14,5 +14,5 @@
 | [Talos AI-Assistant Component (launcher + docked/drawer chat panel)](features/talos-assistant.md) | `Talos` is a **shared, pure-UI** AI-assistant component in `@agilant/toga-blox`: a header launcher button (`TalosLauncher`) plus a chat panel (`TalosPanel`) tha | toga-blox/src/components/Talos/TalosLauncher.tsx, toga-blox/src/components/Talos/TalosPanel.tsx, toga-blox/src/components/Talos/TalosMessage.tsx, toga-blox/src/components/Talos/types.ts, toga-blox/src/components/Talos/theme.ts, toga-blox/src/components/Talos/helpers.tsx, toga-blox/src/components/Talos/stub.ts, toga-blox/src/components/Talos/Talos.module.css, toga-blox/src/components/Talos/index.ts, toga-blox/src/components/Talos/TalosPanel.test.tsx, toga-blox/src/components/index.ts, toga-blox/src/components/Talos/README.md, toga-blox/src/components/TableRecordModal/TableRecordModal.tsx |
 | [Toaster — host-token styling contract](features/toaster.md) | The blox `Toaster` is a CSS-Module component whose every visual property reads a `--toaster-*` custom property supplied by the **host app**. | toga-blox/src/components/Toaster/Toaster.module.css, toga-blox/src/components/Toaster/Toaster.tsx, toga-blox/src/components/Toaster/ToasterContext.tsx, toga2-commerce/src/styles/index.css, toga2-commerce/src/components/Toasters/ToasterList.tsx |
 | [Dynamic npm Publish Pipeline (branch → channel)](workflows/dynamic-publish-pipeline.md) | How `@agilant/toga-blox` (checkout folder `toga-blox-npm`, registry repo key `toga-blox`) publishes a per-environment npm **channel** (dist-tag) from a `_<mode> | toga-blox/.github/workflows/publish.yml, toga-blox/package.json, toga-blox/src/utils/getFontAwesomeIcon.tsx |
-| [Landing a Large Long-Lived Feature Branch (merge, never rebase)](workflows/landing-a-large-feature-branch.md) | The procedure for landing a long-lived, very large feature branch (months old, hundreds of commits) into `_production` in `toga-blox-npm`. | toga-blox/package.json, toga-blox/.github/workflows/publish.yml |
-| [Local-linking an unpublished blox into a consumer app (incl. a React 19 / Next host)](workflows/local-link-into-a-consumer-app.md) | How to develop a **blox component that is not published yet** against a real consuming app, on Windows, including the hard case: a **React 19 / Next.js (Turbopa | toga-blox/package.json, toga-blox/postcss.config.cjs, toga25-supply/vite.config.ts |
+| [Landing a Large Long-Lived Feature Branch (merge, never rebase)](workflows/landing-a-large-feature-branch.md) | The procedure for landing a long-lived, very large feature branch (months old, hundreds of commits) into `_production` in `toga-blox-npm`. | toga-blox/package.json, toga-blox/.github/workflows/publish.yml, toga25-supply/vite.config.ts, toga25-supply/package-lock.json |
+| [Local-linking an unpublished blox into a consumer app (incl. a React 19 / Next host)](workflows/local-link-into-a-consumer-app.md) | How to develop a **blox component that is not published yet** against a real consuming app, on Windows, including the hard case: a **React 19 / Next.js (Turbopa | toga-blox/package.json, toga-blox/postcss.config.cjs, toga25-supply/vite.config.ts, toga25-supply/package.json, toga25-supply/tsconfig.node.json |

package/knowledge/2.0/apps/toga-blox/workflows/landing-a-large-feature-branch.md

@@ -6,13 +6,16 @@ project: TOGa Blox
 client: shared
 type: workflow
 status: active
-updated: 2026-08-26
+updated: 2026-09-03
 owners: [apeterson]
 files:
   - toga-blox/package.json
   - toga-blox/.github/workflows/publish.yml
+  - toga25-supply/vite.config.ts
+  - toga25-supply/package-lock.json
 related:
   - ./dynamic-publish-pipeline.md
+  - ./local-link-into-a-consumer-app.md
   - ../architecture.md
 ---
 
@@ -23,6 +26,9 @@ commits) into `_production` in `toga-blox-npm`. The decision recorded here is **
 `_production` into the feature branch — do not rebase.** Use this doc before starting any
 big-branch integration; the recon step is the transferable part.
 
+Steps 4–5 cover the routine case too: merging the **same** `_production` commit into **several**
+feature branches at once (proven on `toga25-supply`, 2026-09-03).
+
 ## How it works
 
 ### 1. Measure the divergence first
@@ -56,6 +62,42 @@ This shows the exact conflicting files without touching the working tree, which
 2. Resolve the (small, known) conflict set **once**.
 3. Open a normal PR: feature → `_production`.
 
+### 4. Regenerate `package-lock.json` — never hand-merge it
+
+```bash
+npm install --package-lock-only
+```
+
+It rebuilds the lockfile from the **merged `package.json`** and does **not** touch
+`node_modules` — which matters in this repo family because it therefore cannot destroy a blox
+symlink (see [local-link](./local-link-into-a-consumer-app.md) §1a). `toga25-supply/.npmrc`
+already sets `legacy-peer-deps=true`, so no flag is needed. Confirm afterwards that the
+regenerated lock matches the pin in `package.json`.
+
+### 5. Copying one resolution across several branches — diff BOTH sides first
+
+When the same `_production` commit is merged into several feature branches, the conflict often
+*looks* identical and the resolution can be copied:
+
+```bash
+git show <already-resolved-branch>:<file> > <file>   # then verify byte-identical
+```
+
+**But check first — "the same conflict" is frequently not the same.** Before copying, diff both
+conflict sides against the branch you are copying from:
+
+```bash
+git show :2:<file>   # ours  (the feature branch)
+git show :3:<file>   # theirs (_production)
+```
+
+Concrete case (toga25-supply, 2026-09-03, all three branches merging `_production` `4c99ced`,
+blox pin `1.1.2-production.144`): `TRUE-81379` and `TRUE-81217` had identical sides and copied
+cleanly. `TRUE-79020-v2` had **drifted** — its side was space-indented (52 space lines against
+the repo's tabs-only standard) and was missing the react-query alias, the `isBloxLinked`
+branching, and the whole `server.fs.allow` block, while already carrying two `dedupe` members the
+others lacked. A blind copy would have silently reverted work.
+
 ### Why not rebase
 
 Rebasing 281 commits onto `_production` replays every commit, forces the **same conflicts to
@@ -70,10 +112,23 @@ conflict set exactly once and preserves the pushed history.
   at `1.0.314`, so the merge publishes the *branch's* number. See
   [dynamic-publish-pipeline](./dynamic-publish-pipeline.md) for how CI derives the published
   version from that base.
+- **⚠ git can auto-merge a DUPLICATE import with no conflict marker.** One side had
+  `import fs from "fs"`, the other `import fs from "node:fs"`. Git saw two independent additions,
+  merged **both**, and flagged nothing. The result is a duplicate identifier that breaks the
+  build. **After resolving any conflict, scan the whole file for duplicate imports** — "no
+  conflict markers left" does not mean "the file is correct."
 - **Do not read a behind-count as staleness** in this repo — much of it is release plumbing
   generated on the release branch and never merged back (see the publish-pipeline doc).
 
 ## Change history
+- 2026-09-03 — Broadened past the huge-branch case to cover merging one `_production` commit into
+  **several** feature branches. Added step 4 (`npm install --package-lock-only` regenerates the
+  lockfile from the merged `package.json` without touching `node_modules`, so it cannot break a
+  blox symlink) and step 5 (**diff `git show :2:`/`:3:` before copying a resolution between
+  branches** — of three toga25-supply branches merging the same commit, one had drifted to space
+  indentation and was missing three config blocks). Added the gotcha that git **auto-merged a
+  duplicate `import fs`** — `fs` vs `node:fs` — with **no conflict marker**, breaking the build.
+  (apeterson)
 - 2026-08-26 — Created. Recorded the merge-not-rebase decision for landing `feature-new-table`
   (281 ahead / 8 behind, 530 files) into `_production`, and the
   `rev-list --left-right --count` → `merge-tree` recon pair that narrowed the conflict surface

package/knowledge/2.0/apps/toga-blox/workflows/local-link-into-a-consumer-app.md

@@ -6,12 +6,14 @@ project: TOGa Blox
 client: shared
 type: workflow
 status: active
-updated: 2026-09-02
+updated: 2026-09-03
 owners: [tcox, apeterson]
 files:
   - toga-blox/package.json
   - toga-blox/postcss.config.cjs
   - toga25-supply/vite.config.ts
+  - toga25-supply/package.json
+  - toga25-supply/tsconfig.node.json
 related:
   - ./dynamic-publish-pipeline.md
   - ../features/talos-assistant.md
@@ -73,6 +75,15 @@ rm -rf node_modules/.vite
   (see §2c).
 - Same rule after editing blox source: `npm run build` in `toga-blox-npm`, **then** clear
   `node_modules/.vite` in the consumer.
+- **`npm ci` does it too, and switching branches forces it.** Each feature branch pins its own
+  blox version, so a branch switch means an install, which silently replaces the link. There is
+  no config fix — re-linking is a required manual step in the branch-switch routine. Shortest
+  re-link from the consumer root: `npm install --no-save ../toga-blox-npm`.
+- **The one npm command that CANNOT break the link: `npm install --package-lock-only`.** It
+  regenerates `package-lock.json` from the merged `package.json` **without touching
+  `node_modules`**. That is also the only correct way to resolve a lockfile merge conflict —
+  never hand-merge one. (`toga25-supply/.npmrc` sets `legacy-peer-deps=true`, so no flag is
+  needed.) Verified 2026-09-03 on toga25-supply at blox `1.1.2-production.144`.
 
 ### 2. Collapse to ONE React (the React 19 case)
 
@@ -127,6 +138,30 @@ dedupe: [
   `@tanstack/react-query`, `@tanstack/react-query-persist-client`, `@tanstack/react-table`,
   `react-hook-form`. `react-hook-form` was nested under blox as well — the same latent bug for
   `BaseInput` / `useFormContext`, just not throwing yet.
+- **Closed out 2026-09-03: `react-hook-form` was the next one to bite, in `toga25-supply`.** It
+  was in **neither** `dedupe` **nor** `resolve.alias`, while **24 files** under
+  `toga25-supply/src` import it and blox's `BaseInput` calls `useFormContext()` — `<FormProvider>`
+  fills one copy, `BaseInput` reads the other. blox's own `node_modules` ships
+  `react-hook-form@7.82.0` (alongside `react`/`react-dom` 18.3.1, `@tanstack/react-query`
+  5.101.4, `@tanstack/react-table` 8.21.3, `framer-motion`, `react-select`, `react-day-picker`,
+  and the react-query persist/devtools packages). Same version on both sides does **not** save
+  you — two folders means two module instances. `toga25-desk` already deduped it; supply had the
+  gap. Supply's list is now:
+
+  ```ts
+  dedupe: [
+    "react", "react-dom",
+    "@tanstack/react-table",
+    "@tanstack/react-query",
+    "@tanstack/react-query-persist-client",
+    "@tanstack/react-query-devtools",
+    "react-hook-form",
+  ]
+  ```
+
+  **Check it after every install:** `npm ls react react-dom @tanstack/react-query
+  @tanstack/react-table react-hook-form` must show exactly one copy of each (verified after
+  `npm ci`, 2026-09-03).
 - **`optimizeDeps.include` is why the throw appears to come from inside blox.** With blox in
   `optimizeDeps.include`, esbuild pre-bundles blox **together with its nested copy**, so the error
   surfaces from `@agilant_toga-blox.js` rather than from app code, and the `?v=<hash>` in the error
@@ -183,6 +218,42 @@ const isLinked = fs.lstatSync(bloxDir).isSymbolicLink();
 - **Result: a blox rebuild now just triggers HMR.** No `rm -rf node_modules/.vite`, no browser cache
   fight. For the **linked** case this **supersedes** §2b's "editing `dedupe` is not enough — clear
   `.vite` and hard-reload"; that step remains true for a published install.
+- **Switching branches between a linked and a published blox also self-heals — verified in Vite
+  source 2026-09-03.** Vite 7.3.6's `getConfigHash()` hashes `resolve` **and**
+  `optimizeDeps.include`/`exclude` (read at
+  `node_modules/vite/dist/node/chunks/config.js:32429`). Because the config branches those exact
+  values on `isBloxLinked`, moving between a symlinked and a published blox changes the hash and
+  Vite re-runs optimizeDeps by itself — **no `rm -rf node_modules/.vite` needed on a branch
+  switch.** This was asserted in a code comment before; it is now checked against Vite's source.
+  It does **not** cover a blox *rebuild*: the hash never sees a linked package's `dist`, which is
+  why the linked branch keeps blox out of the pre-bundle entirely.
+
+**The settled `vite.config.ts` shape (toga25-supply, 2026-09-03 — now identical on the three
+in-flight branches `TRUE-81379`, `TRUE-81217`, `TRUE-79020-v2`):**
+
+```ts
+const bloxDir       = path.resolve(__dirname, "node_modules/@agilant/toga-blox");
+const isBloxLinked  = fs.existsSync(bloxDir) && fs.lstatSync(bloxDir).isSymbolicLink();
+```
+
+- **Auto-detect, never a developer-flipped flag.** A hand-set boolean is always wrong on someone
+  else's machine. Keep the `existsSync` guard first — `lstatSync` throws when blox is not installed.
+- **`optimizeDeps` has exactly two branches.** LINKED → `exclude: [BLOX]` + `include:
+  BLOX_EXTERNALS`. PUBLISHED → `include: [BLOX]`.
+- **`server.fs.allow` — use `searchForWorkspaceRoot(process.cwd())`, NOT `path.resolve(__dirname)`:**
+
+  ```ts
+  server: { fs: { allow: [searchForWorkspaceRoot(process.cwd()), ...(bloxRealPath ? [bloxRealPath] : [])] } }
+  ```
+
+  Setting `allow` **replaces** Vite's default list rather than extending it, so hardcoding the
+  project root silently narrows what the dev server will serve. This form also needs no
+  `isBloxLinked` branch — it is a no-op on a normal install.
+- **The explicit `resolve.alias` for `@tanstack/react-query` was kept on top of `dedupe`** —
+  `_production` had deleted it, the original author's comment says dedupe alone did not beat the
+  symlink. It is a no-op on a published install, so keeping it costs nothing. ⚠ **Still unverified
+  in an actual symlinked run — open question.** If you reproduce it either way, record the answer
+  here.
 
 **Trade-off: `BLOX_EXTERNALS` is a hand-maintained list** (the grep that regenerates it sits in a
 comment beside it). If blox adds a dependency and the list is not updated, the symptom is **"does not
@@ -253,11 +324,29 @@ edit; clearing `node_modules/.vite` matters because Vite's pre-bundle cache hold
   believing a deploy will work.
 - **Linked ≠ shippable.** A consumer on a link **cannot deploy**. The component has to merge and
   publish, and the consumer has to move to the npm version, before anything ships.
+- **Type-check `vite.config.ts` with `-p tsconfig.node.json`.** The config file is covered by
+  `tsconfig.node.json`, not `tsconfig.app.json`, so the usual
+  `npx tsc --noEmit -p tsconfig.app.json` never looks at it. After editing the Vite config run
+  `npx tsc --noEmit -p tsconfig.node.json` as well.
 - **Import subpaths to keep the bundle small.** blox's `exports` allows `./dist/*`, so
   `@agilant/toga-blox/dist/components/<X>/index.js` pulls just that component; the package barrel
   drags every component's CSS into the consumer bundle.
 
 ## Change history
+- 2026-09-03 — Recorded the **settled `vite.config.ts` shape** now shared by supply's three
+  in-flight branches, and closed two open threads. (1) `react-hook-form` was in **neither**
+  `dedupe` nor `alias` in `toga25-supply` while 24 `src` files import it and blox's `BaseInput`
+  calls `useFormContext()` — added, and supply's full 7-member `dedupe` list is written down.
+  (2) Verified in Vite source (`chunks/config.js:32429`) that `getConfigHash()` hashes `resolve`
+  **and** `optimizeDeps.include`/`exclude`, so branching them on `isBloxLinked` makes a
+  linked↔published branch switch invalidate the dep cache **by itself** — no
+  `rm -rf node_modules/.vite`. Also: `server.fs.allow` must use
+  `searchForWorkspaceRoot(process.cwd())` because `allow` **replaces** Vite's default rather than
+  extending it; `npm ci` un-links blox just like `npm install`, and
+  `npm install --package-lock-only` is the one command that cannot (so it is also how you resolve
+  a lockfile conflict); and `vite.config.ts` is type-checked with `-p tsconfig.node.json`, not the
+  app config. The kept `@tanstack/react-query` alias remains **unverified** under a real symlink.
+  (apeterson)
 - 2026-09-02 — Expanded step 4: the consumer's `tsc` resolves blox **types from source** through the
   symlink while Vite loads the package from **`dist/`**, so a clean `tsc --noEmit` does **not** prove
   the browser has your change. Every blox edit needs `npm run build` in blox **plus**

package/knowledge/2.0/apps/toga25-supply/architecture.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: architecture
 status: active
-updated: 2026-09-01
+updated: 2026-09-03
 owners: [apeterson]
 files:
   - toga25-supply/src/main.tsx
@@ -98,11 +98,25 @@ toga-blox table/modal templates.
 ## toga-blox relationship
 
 `@agilant/toga-blox` is the shared frontend component/template/utility library (repo
-`toga-blox-npm`). It is **not published to npm for this app's purposes** — the app is currently
-its primary consumer and resolves it via a symlinked `node_modules/@agilant/toga-blox` →
-`toga-blox-npm`. Because the app imports the built `dist/` (JS + `.d.ts`), any change to toga-blox
-**source** requires a rebuild before it is visible at runtime; in urgent cases the `dist/` files
-(and their `.d.ts`) have been patched directly. The `/update-blox` skill covers version bumps.
+`toga-blox-npm`). The app consumes it in **one of two states, and you must check which you are in**
+before trusting anything else in this section:
+
+- **Published (the normal state, incl. every CI/Amplify build).** `package.json` pins an exact
+  version — `1.1.2-production.144` as of 2026-09-03. A blox source change reaches the app only via
+  publish + pin bump. The `/update-blox` skill covers the bump.
+- **Symlinked (a local dev loop only).** `node_modules/@agilant/toga-blox` points at the
+  `toga-blox-npm` checkout. The app imports the built `dist/`, so **every** blox source edit needs
+  `npm run build` in blox first.
+
+`vite.config.ts` **auto-detects** which state it is in
+(`fs.existsSync(bloxDir) && fs.lstatSync(bloxDir).isSymbolicLink()`) and flips `optimizeDeps`
+accordingly — there is no flag to set by hand.
+
+**⚠ Any `npm install` or `npm ci` silently replaces the symlink with the published package.**
+Switching branches changes the blox pin, which forces an install, which un-links it. There is no
+config fix; re-link with `npm install --no-save ../toga-blox-npm`. The symptom of missing this is a
+misleading "does not provide an export named X". Full procedure and the `dedupe`/`alias` one-copy
+rules: [local-link-into-a-consumer-app](../toga-blox/workflows/local-link-into-a-consumer-app.md).
 
 ## Conventions & gotchas
 

package/knowledge/2.0/standards/backend-php.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-09-02
+updated: 2026-09-03
 owners: [jcardinal, mhammontree, dfranks, bala, ajean]
 files: []
 related:
@@ -741,6 +741,15 @@ notified**. Pick deliberately:
 > throw `_Exception_Validation` on an empty recipient.) Note `_Exception_Business` **extends**
 > `_Exception_Validation`, so it also satisfies this `instanceof` test.
 
+> **DB errors are their own subclass, and you never throw it.** `_Query` throws
+> `_Exception_Database` (a subclass of plain `Exception`, so it routes identically — 500 +
+> `Logs.Issue` → developer task) for every database failure. The one difference is identity:
+> it is **fingerprinted by `errno + a masked error message`, not by the trace**, because all
+> DB errors share the same few `_Query` frames and the trace scheme over-merged genuinely
+> different bugs into one Issue. Do not "upgrade" a DB failure to another class to change its
+> routing — the class and its message-based grouping are set in `_Query`/`_Error`. Detail:
+> `2.0/apps/_underscore/features/error-reporting-issue-event.md`.
+
 `_Exception_Business`'s constructor is `(issueKey, message, minimumUrgency)`. The `issueKey` is
 the fingerprint, so the Issue's identity survives refactoring; a plain `Exception`'s
 trace-based fingerprint changes when the code moves.
@@ -1024,6 +1033,13 @@ See: 2.0/apps/worker2/features/cross-account-aws-access.md
 
 ## Change history
 
+- 2026-09-03 — Error Handling: added a note under the exception-routing table that DB errors are
+  their own subclass — `_Query` throws `_Exception_Database` (subclass of plain `Exception`, so it
+  routes identically: 500 + `Logs.Issue` → developer task), but it is **fingerprinted by
+  `errno` + a masked error message, not by the trace**, because all DB errors share the same few
+  `_Query` frames and the trace scheme over-merged different bugs into one Issue. Do not "upgrade" a
+  DB failure to another class to change its routing; the class and its message-based grouping live in
+  `_Query`/`_Error`. Detail: `2.0/apps/_underscore/features/error-reporting-issue-event.md`. (jcardinal)
 - 2026-09-02 — Database/SQL: any **cross-process counter or shared rollup needs its own DB alias,
   committed immediately**. `Route.php` holds a transaction open on the default connection until the
   request/job ends, so a counter written there is invisible to every other process (a fleet-wide

package/knowledge/2.0/standards/frontend.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-09-01
+updated: 2026-09-03
 owners: [jcardinal, apeterson]
 files: []
 related:
@@ -132,6 +132,13 @@ npx tsc --noEmit -p tsconfig.app.json    # ✅
 npx tsc --noEmit                         # ❌ silent no-op
 ```
 
+**MUST: `vite.config.ts` is checked by `tsconfig.node.json`, not the app config.** The app-config
+run never looks at it, so a broken Vite config type-checks green. After editing it, also run:
+
+```bash
+npx tsc --noEmit -p tsconfig.node.json
+```
+
 Documented independently in two repos on this tsconfig shape — `toga25-supply` (verified
 2026-09-01) and `toga2-view` ([architecture](../apps/toga2-view/architecture.md)) — so assume it
 for any app sharing the shape, but **verify per repo before asserting it**. Note also that a repo
@@ -359,15 +366,28 @@ memory.
   because they follow that app's shared-lib surface — verified 2026-08-18:
 
   ```ts
-  // toga25-supply/vite.config.ts
-  dedupe: ["react", "react-dom", "@tanstack/react-table"]
+  // toga25-supply/vite.config.ts — verified 2026-09-03
+  dedupe: [
+    "react", "react-dom",
+    "@tanstack/react-table",
+    "@tanstack/react-query",
+    "@tanstack/react-query-persist-client",
+    "@tanstack/react-query-devtools",
+    "react-hook-form",
+  ]
   // toga25-desk/vite.config.ts
   dedupe: ["react", "react-dom", "react-hook-form"]
   ```
 
-  Supply dedupes the table lib (it consumes blox's table context); desk dedupes react-hook-form (it
-  consumes blox's `BaseInput`, which reads `useFormContext()`). See §13(c) for why a second copy
-  silently breaks blox's hooks.
+  Supply's earlier three-member list (`react`, `react-dom`, `@tanstack/react-table`) is
+  **superseded** — it was incomplete, and each missing member has since caused or nearly caused a
+  live defect. Verified 2026-09-03: `toga-blox-npm/node_modules/` ships its own
+  `react-hook-form@7.82.0`, and supply had it in **neither** `dedupe` **nor** `resolve.alias`
+  while 24 `src` files import it and blox's `BaseInput` calls `useFormContext()` — a
+  `<FormProvider>` filling one copy and `BaseInput` reading the other. **Same version on both
+  sides does not save you**; two folders means two module instances. Desk already deduped it.
+  Apply the principle, then audit the actual list per app: dedupe every peer the shared lib
+  provides context or hooks for. See §13(c).
 
   Verified 2026-08-26: `toga2-commerce` had **no** `dedupe` at all and now declares
   `["react","react-dom","react-hook-form","react-router-dom","framer-motion","@tanstack/react-query","@tanstack/react-table"]`
@@ -375,6 +395,15 @@ memory.
   ships its own `react@18.3.1`/`react-dom@18.3.1`, so consuming blox through a **local symlink**
   resolves React to blox's own copy. Dedupe is what makes the symlink workflow safe — it is not
   optional polish.
+- **SHOULD: branch `optimizeDeps` on whether the shared lib is symlinked, and let Vite's config
+  hash do the cache-busting.** Verified in Vite 7.3.6 source 2026-09-03
+  (`node_modules/vite/dist/node/chunks/config.js:32429`): `getConfigHash()` hashes `resolve` **and**
+  `optimizeDeps.include`/`exclude`. So a config whose `optimizeDeps` differs between a linked and a
+  published blox re-optimizes **by itself** on a branch switch — no `rm -rf node_modules/.vite`.
+  Also: `server.fs.allow` **replaces** Vite's default allow-list, it does not extend it — use
+  `searchForWorkspaceRoot(process.cwd())`, never a hardcoded `path.resolve(__dirname)`, or you
+  silently narrow what the dev server will serve. Mechanics:
+  [local-link-into-a-consumer-app](../apps/toga-blox/workflows/local-link-into-a-consumer-app.md) §2c.
 - **MUST: one env-read chokepoint.** Read `VITE_API` in exactly **one** module (see §17). Verified:
   both apps read it (plus a per-host override) only in `src/api/api.ts`.
 - **SHOULD: ESLint flat config**, verified identical in both apps:
@@ -680,6 +709,13 @@ consuming app, guard against them and move on.
 
 ## Change history
 
+- 2026-09-03 — §11: replaced supply's stale three-member `dedupe` list with the verified
+  seven-member one and added `react-hook-form` (it was in neither `dedupe` nor `alias` while 24
+  `src` files import it and blox's `BaseInput` calls `useFormContext()`). Added a SHOULD for
+  branching `optimizeDeps` on the symlink — Vite's `getConfigHash()` hashes `resolve` +
+  `optimizeDeps.include`/`exclude` (verified in source), so a branch switch self-invalidates the
+  dep cache — plus the trap that `server.fs.allow` **replaces** Vite's default list. §2: added a
+  MUST to type-check `vite.config.ts` with `-p tsconfig.node.json`. (apeterson)
 - 2026-09-01 — §2: added a MUST to **type-check with `-p tsconfig.app.json` (or `tsc -b`), never
   bare `npx tsc --noEmit`** — the root `tsconfig.json` is references-only (`files: []`), so a bare
   root run compiles nothing and always exits 0, a false green in any pre-commit/CI check. Verified

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.761",
+  "version": "1.0.763",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",