toga-ai 1.0.484 → 1.0.486

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

@@ -7,6 +7,7 @@
 | [CloudFront Client Setup](features/cloudfront-client-setup.md) | An SSO-gated admin tool at **`/devops/cloudfront-clients`** in the Tools 1.0 app that onboards a client onto **CloudFront + Route 53 across multiple AWS account | tools/_/app/devops/cloudfront.php, tools/mvc/devops/cloudfront-clients/get.php, tools/mvc/devops/cloudfront-clients/post.php, tools/assets/js/cloudfront-clients.js, tools/assets/css/cloudfront-clients.css, tools/_/app/nav.php, tools/_/app/frameworkindex.php, tools/config.production.ini |
 | [Design Demo Admin](features/design-demo-admin.md) | A self-serve admin UI at **`/design`** in the SSO-protected **Tools** app that lets the design team publish self-contained "Claude Design" HTML exports as **ver | tools/_/app/design/github.php, tools/mvc/design/get.php, tools/mvc/design/post.php, tools/assets/css/design.css, tools/assets/js/design.js, tools/_/app/frameworkindex.php, tools/_/app/nav.php, tools/composer.json |
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | The first two tools shipped in the Tools app, both under the **Developers** folder and gated to personas **Development Team** / **TOGa Technology**. | tools/mvc/developers/uuid/get.php, tools/mvc/developers/password/get.php |
+| [/errors Curation Console (Tools → shared Core Logs DB)](features/errors-curation-console.md) | Internal-only triage/curation screen for the 2.0 Issue/Event error-reporting pipeline, built as a 1.0 Tools MVC page reading the **shared Core Logs DB** through | tools/mvc/errors/get.php, tools/mvc/errors/post.php, tools/_/app/nav.php, tools/config.production.ini |
 | [Tools MVC — Routing, CSRF & App_Database Access Patterns](features/mvc-data-access-patterns.md) | The load-bearing 1.0 (`App_`) framework conventions a developer needs when adding a page to the Tools app — URL routing, CSRF, and DB access through `App_Databa | tools/_/app/nav.php, tools/mvc/get.php |
 | [Tools Persona-Gated Navigation (App_Nav)](features/persona-gated-navigation.md) | `App_Nav` is the Tools app's two-level, **persona-gated** navigation. | tools/_/app/nav.php, tools/mvc/get.php |
 | [Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)](features/saml-sso-auth.md) | `App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=` handoff (see the 2.0 SAML downstream integration contract), establishe | tools/_/app/auth.php, tools/mvc/sso/initiate/get.php, tools/mvc/sso/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/get.php, tools/mvc/get.php, tools/config.production.ini, tools/config.local.ini |

package/knowledge/1.0/apps/tools/features/errors-curation-console.md

@@ -0,0 +1,81 @@
+---
+title: /errors Curation Console (Tools → shared Core Logs DB)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-07-30
+owners: ["jcardinal"]
+files:
+  - tools/mvc/errors/get.php
+  - tools/mvc/errors/post.php
+  - tools/_/app/nav.php
+  - tools/config.production.ini
+related:
+  - ../architecture.md
+  - ./mvc-data-access-patterns.md
+  - ../../../2.0/apps/_underscore/features/error-reporting-issue-event.md
+  - ../../../2.0/apps/worker2/features/error-escalation-cron.md
+---
+
+## Summary
+
+Internal-only triage/curation screen for the 2.0 Issue/Event error-reporting pipeline, built as
+a 1.0 Tools MVC page reading the **shared Core Logs DB** through a new **`db_toga2logs`**
+alias. It curates; it never notifies.
+
+The highest-value view is the list of issues **below the ClickUp threshold** — errors that are
+happening and were deliberately never ticketed. Nobody had that view before.
+
+## How it works
+
+- **Curate** subject, description, `minimumUrgency`, assignee, and mute window.
+- **Manage per-client email recipients** (`IssueEmailAddresses`). `clientId = 0` means **all
+  clients** and requires an explicit confirmation flag; the list view renders it as
+  **"ALL CLIENTS"**.
+- **Merge fingerprints** — repoint an `IssueFingerprints` row at an existing Issue. Without this,
+  the fingerprint/Issue split is inert: a refactor that shifts line numbers produces a new Issue
+  and the curated one is orphaned.
+- **Any save sets `isManaged`**, which does double duty: it protects the curated text from being
+  overwritten by later occurrences, **and** it exempts the Issue from the cron's GC sweep.
+
+**This page notifies nobody.** Escalation, ClickUp ticketing, and email are owned entirely by
+`_Worker_Infrastructure_Errors::Escalate`. Adding a notify action here would create a second,
+untracked alerting path.
+
+### Why Tools and not TOGa Hub
+
+The 2026-06-12 meeting had proposed TOGa Hub, but Hub is far off. The tables are the same either
+way, so the choice is not load-bearing — a Hub port later reads the same schema.
+
+## Configuration
+
+`[database_toga2logs]` was added to `tools/config.production.ini`.
+
+**`dbname` is NOT necessarily `Logs`.** 2.0 resolves the Core Logs database name at **runtime**
+from `Core.Databases` id **11** (`worker2` `CORE_LOGS_DATABASE_ID`); `Logs` is only the
+`_underscore` *register alias*. Read the real name from `Core.Databases` before configuring a new
+environment, or the console silently points at a database that may not exist.
+
+## Gotchas / known issues
+
+- **This is a 1.0 app reading a 2.0 shared database.** Access is plain `App_Database` via the
+  `db_toga2logs` alias, not the `_Model` layer — so none of the 2.0 model protections apply.
+  Escape every interpolated value and allowlist every identifier (see the 1.0 back-end standard).
+- **Cross-tenant surface.** The Core Logs DB is shared by every client, so this console can show
+  one client's captured context to a viewer looking at another client's problem. It is
+  internal-only and persona-gated for that reason — do not expose any part of it to a client.
+- **Curated text is authoritative.** Once `isManaged` is set, later occurrences no longer update
+  subject/description, so a stale curated subject stays stale until someone edits it again.
+
+## Change history
+
+- 2026-07-30 — Built as part of TRUE-78188: new `/errors` triage/curation console over the
+  shared Core Logs DB via a new `db_toga2logs` alias; curation sets `isManaged` (protects text
+  and exempts from GC); fingerprint merging; per-client recipient management with an explicit
+  confirmation for `clientId = 0` ("ALL CLIENTS"). Chosen over TOGa Hub because Hub is far off
+  and the schema is the same either way. Documented that the Core Logs `dbname` resolves at
+  runtime from `Core.Databases` id 11 and is not necessarily "Logs". (jcardinal)
+</content>

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

@@ -15,7 +15,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, worker2/Worker/Infrastructure/Email/Send.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 |
+| [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/Exception/Business.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, dbchanges2/Logs/2026-07-30a - Error reporting Issues and Events.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 |
 | [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 |
 | [isFulfillable Propagation Up the SO↔PO Chain](features/fulfillable-item-propagation.md) | `Items.isFulfillable` is a boolean that gates whether a storefront line's **Qty Fulfilled** cell is actionable. | _underscore/Model/Client/Item.php, _underscore/Model/Compass/Item.php, dbchanges2/Core/2026-07-17 - Items isFulfillable RecordField.sql, dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql, dbchanges2/Client/2026-07-17 - ItemsisFulfillable.sql |

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

@@ -1,148 +1,271 @@
 ---
-title: Error Reporting — Issue/Event Aggregation (agreed POST-to-receiver design)
+title: Error Reporting — Issue/Event Capture, Fingerprinting & Aggregation
 framework: "2.0"
 repo: _underscore
 project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-15
-owners: ["dfranks"]
+updated: 2026-07-30
+owners: ["dfranks", "jcardinal"]
 files:
   - _underscore/Error.php
+  - _underscore/Exception/Business.php
   - _underscore/Model/Core/Logs/Issue.php
   - _underscore/Model/Core/Logs/Event.php
-  - dbchanges2/Logs/2026-07-06 - Issue and Event tables.sql
+  - _underscore/Model/Core/Logs/IssueFingerprint.php
+  - _underscore/Model/Core/Logs/IssueClickupTask.php
+  - _underscore/Model/Core/Logs/IssueEmailAddress.php
+  - _underscore/Model/Core/Logs/IssueAreaOwner.php
+  - dbchanges2/Logs/2026-07-30a - Error reporting Issues and Events.sql
+  - dbchanges2/Core/2026-07-30a - Error escalation cron job.sql
 related:
   - ../architecture.md
   - ./per-client-database-connections.md
+  - ./email-send-pipeline.md
+  - ../../worker2/features/error-escalation-cron.md
+  - ../../../1.0/apps/tools/features/errors-curation-console.md
   - ../../dbchanges2/architecture.md
 ---
 
 ## Summary
 
-Platform-wide error-reporting infrastructure for TOGA 2.0, built around a two-table
-**Issue / Event** aggregation model in the shared **Core Logs DB**. An **Issue** is the
-deduplicated record for a distinct error (keyed by a hash of the stack trace) carrying an
-aggregate `occurrences` counter and an escalatable `urgency`; an **Event** is one row per
-individual occurrence with its own trace and context.
-
-**The agreed architecture (see below) decouples *reporting* from *persistence*:**
-application error handlers **POST** error payloads to a centralized `/errors` receiver
-endpoint; a **worker2 cron** consumes them and does all the hashing, upserting, aggregation,
-escalation, and ClickUp sync into the Core Logs DB. Handlers do **not** write Issue/Event
-rows to the database directly. This is the canonical target design for the whole
-error-monitoring epic (TRUE-781xx) — the handler ticket, the dashboard ticket, and the
-escalation-cron ticket must all conform to it.
-
-## Agreed error-monitoring architecture
-
-Source: the **"2026-05-21 - Errors, Monitoring and Alerts"** meeting design (approved;
-cited via Talos DevCore meeting notes). Pipeline:
-
-1. **Report (application side).** An application's error/exception handler serializes the
-   error (message, stack trace, context) and **POSTs it to a centralized `/errors` receiver
-   endpoint** (the meeting referenced `webhook.hub.com/error`). The handler's only job is to
-   transmit — it performs **no direct database persistence**.
-2. **Ingest (worker2 cron).** A worker2 cron consumes the received error payloads and:
-   - builds `issueHash` from the stack trace to identify the distinct error,
-   - **upserts an Issue** and **inserts an Event** into the **Core** Logs DB,
-   - aggregates occurrence counts within a time window,
-   - auto-escalates / de-escalates the Issue `urgency` based on occurrence frequency,
-   - syncs the Issue to ClickUp.
-3. **Scope.** API 2.0 handlers first; 1.0 is deferred.
-
-The critical rule: **handlers POST; the cron persists (to Core).** Any approach where the
-handler writes Issue/Event rows inline to a database contradicts this design.
-
-## Data model (Core Logs DB)
-
-- **`_underscore/Model/Core/Logs/Issue.php`** — `const DATABASE = _underscore::DB_LOGS;
-  const TABLE = 'Issues';`. Fields: `id, uuid, dtCreated, dtLastOccurred, urgency, subject,
-  description, clickupIdentifier, hash, errorMessage, occurrences, trace`. One row per
-  distinct error (dedup key = `hash`); `occurrences` is the rolling count, `dtLastOccurred`
-  the most-recent hit, `urgency` a list field, `clickupIdentifier` links to an escalation
-  ticket. There is **no `type` column**.
-- **`_underscore/Model/Core/Logs/Event.php`** — `const DATABASE = _underscore::DB_LOGS;
-  const TABLE = 'Events';`. Fields: `id, uuid, issueId (FK → Issue), errorMessage, trace,
-  context, dtCreated`. One row per occurrence.
-
-The `Issues`/`Events` tables live in the shared **Core Logs** DB, provisioned from
-`dbchanges2/Logs/` (the `Logs/` folder targets the framework-level, non-tenant `Logs` DB
-with unqualified table names — see the dbchanges2 architecture folder→DB mapping). Contrast
-with per-client API/error logging in `Logs_<Tenant>` via `Model/Client/Logs/*`
-(`DB_CLIENT_LOGS`, `dbchanges2/Logs_Client/`).
-
-## Current state of `_underscore/Error.php` (important — reads differently than you'd expect)
-
-`_underscore/Error.php` registers `exceptionHandler()` via `set_exception_handler`, but in
-**`_production` it does NOT persist any Issue/Event rows.** It builds a debug HTML body,
-writes it to an S3 error-details file, and (when a Logs register is present) records a
-single `_Model_Client_Logs_Error` / `_Model_Core_Logs_Error` row — the older flat error log.
-There is no Issue/Event aggregation, no `issueHash` upsert, and no ClickUp escalation in the
-handler on `_production`.
-
-**An inline-DB-persist approach exists on an in-flight branch, but it conflicts with the
-agreed design and must not be treated as the model to follow:** that approach has the
-handler compute `$issueHash = md5(serialize($backtrace))` and directly upsert
-`_Model_Client_Logs_Issue` + insert `_Model_Client_Logs_Event`, committing a transaction —
-i.e. handler-side direct persistence, and to the **Client** Logs DB rather than **Core**.
-That contradicts the approved architecture on two counts: (a) handlers should POST to the
-`/errors` receiver, not persist; and (b) aggregation belongs in the Core Logs DB, driven by
-the worker2 cron. New work (TRUE-78178 handlers) should implement the POST-to-receiver path,
-not extend the inline-persist branch.
+Platform-wide error reporting for TOGA 2.0, built on an **Issue / Event** aggregation model in
+the **shared Core Logs DB**. An **Issue** is the deduplicated record for a distinct problem
+(carrying curated text, an urgency, and a quotable reference); an **Event** is one row per
+occurrence. Capture lives in `_underscore/Error.php`; escalation and ClickUp/email
+notification live entirely in the worker2 cron (see
+[error-escalation-cron](../../worker2/features/error-escalation-cron.md)); curation lives in
+the 1.0 Tools `/errors` console.
+
+`_Error::captureException(Throwable $e, ?int $clientId): ?string` is the **single capture
+entry point** — the exception handler, the shutdown handler, and api2 all funnel through it,
+and it returns the quotable reference. Add new capture paths by calling it, never by
+re-implementing persistence.
+
+## Data model (shared Core Logs DB)
+
+Six tables, created by `dbchanges2/Logs/2026-07-30a - Error reporting Issues and Events.sql`:
+`Issues`, `IssueFingerprints`, `Events`, `IssueEmailAddresses`, `IssueClickupTasks`,
+`IssueAreaOwners`.
+
+**An Issue is never client-scoped.** An Issue is identified by *code*, and code is global — the
+same bug hitting six clients is **one** Issue. Per-client scoping lives on the occurrence
+(`Events.clientId`) and on notification routing (`IssueEmailAddresses.clientId`), never on the
+Issue itself. Anything that reads like "this client's issue" is a modelling error.
+
+`IssueEmailAddresses.clientId = 0` means **all clients**.
+
+## How it works
+
+### Fingerprinting (identity)
+
+The fingerprint is the normalized top-N **application** frames (repo-relative `path:line`) plus
+the exception class; framework/vendor plumbing is filtered out. The exception **message is
+deliberately excluded** — it carries per-occurrence data (ids, values) and would defeat dedup.
+
+This replaced `md5(serialize(debug_backtrace()))`, which serialized **call arguments** and so
+produced a different hash on every request — dedup never actually worked.
+
+`IssueFingerprints` is many-to-one against `Issues`, so a refactor that shifts line numbers
+cannot orphan a curated Issue: an admin repoints the new fingerprint at the existing Issue
+from the Tools console to merge them.
+
+### `_Exception_Business` — identity immune to refactoring
+
+`_underscore/Exception/Business.php` carries a stable `issueKey` plus a `minimumUrgency` floor.
+When an `issueKey` is declared, **the key is the fingerprint**, so the Issue's identity does not
+depend on line numbers at all. It extends `Exception` (not `_Exception`), matching
+`_Exception_Validation`.
+
+It **deliberately never throws on a bad argument** — it normalizes and `error_log()`s instead.
+Replacing the caller's business error with an argument error destroys the real signal.
+
+### The quotable reference
+
+`Issues.reference` is a Sentry-style base-26 encoding of `Issues.id`: 1 → `1A`, 26 → `1Z`,
+27 → `2A`. Because `AUTO_INCREMENT` never reuses ids, gaps are expected and permanent — a
+reference can never be recycled onto a different problem, so it is safe to quote to a customer.
+
+The reference is written by PHP in a second statement (see MySQL constraints below), which is
+why the column is nullable even though it is always populated.
+
+### Shutdown handler
+
+`register_shutdown_function` is registered with a **pre-allocated memory reserve**. Before this,
+`_underscore` had **no shutdown handler at all**, so fatals, OOM, and timeouts were completely
+uncaptured.
+
+## MySQL constraints that shaped the schema (verified on 8.0.46)
+
+- **A stored generated column blocks `ON DELETE CASCADE`.** A foreign key with
+  `ON DELETE CASCADE` is rejected with error **1215** when the constrained column is the base
+  column of a **STORED** generated column. `IssueClickupTasks.issueId` is the base of
+  `openEpisodeIssueId`, so that generated column must be **VIRTUAL**. VIRTUAL has no such
+  restriction and still supports a UNIQUE secondary index. Proved both ways locally.
+- **Error 3109: a generated column cannot refer to an auto-increment column.** This is why
+  `Issues.reference` cannot be generated and must be written by PHP.
+
+## One-open-episode guard (UNIQUE on a generated column)
+
+`INSERT ... SELECT ... WHERE NOT EXISTS` does **not** prevent a double insert under
+REPEATABLE READ: two overlapping cron runs each evaluate the `NOT EXISTS` against their own
+snapshot and both pass. The guard is instead a VIRTUAL generated column
+`openEpisodeIssueId = issueId while dtResolved IS NULL, else NULL` with a **UNIQUE** key —
+MySQL permits duplicate NULLs, so many resolved episodes coexist while at most one is open.
+
+The code **claims the episode before calling ClickUp**, so a losing run fails (error 1062)
+before it can create a duplicate external task; the claim is **released on API failure** so a
+stuck placeholder row cannot permanently block the Issue. Verified: second open episode → 1062;
+resolve-then-reopen allowed; many resolved episodes allowed; cascade delete works.
+
+## Sentry coexistence (removal is a separate ticket)
+
+Sentry stays running **in parallel**. Shipping an unproven replacement for the only working
+error reporting with no overlap means going blind. Three findings make removal its own ticket:
+
+1. `_Worker_Sentry::Webhook` is an **existing Sentry→ClickUp pipeline writing into the same
+   list `901110669877`** this work replaces — retiring it also means turning off the Sentry-side
+   issue alerts.
+2. `\Sentry\configureScope()` calls `http_response_code(500)` as a blanket default, and api2
+   documents working *around* it. Remove Sentry without fixing every early-exit branch and
+   validation 400s ship as HTTP 200 — which changes whether apiproxy retries across regions.
+3. `\Sentry\init()` registers PHP error handlers. `_Error::errorHandler()` also throws on
+   warnings, but that promotion must be verified **empirically** — if it does not survive,
+   code that currently 500s would silently continue with a null value, which is worse.
+
+Also: this pipeline is **2.0-only**. Sentry must remain for the 1.0 apps (desk1, retail1,
+forecast1, worker1, view1, commerce1) until a `library` / `App_Error` port lands, so the
+Sentry-removal ticket cannot complete until the 1.0 port does.
 
 ## Gotchas / known issues
 
-- **Do not assume error persistence "already works."** On `_production` the handler writes
-  only an S3 debug body and a flat `*_Logs_Error` row — no Issue/Event aggregation exists in
-  production yet. The Issue/Event model is the *target*, delivered by the POST→cron pipeline.
-- **`occurrences` must be incremented, not just seeded** — a naive upsert that sets
-  `occurrences = 0` only at creation never advances the aggregate counter. The cron must
-  increment on every occurrence.
-- **`Event.trace` must be populated per occurrence** — the per-Event `trace` column is easy
-  to leave empty; record it on every Event.
-- **Persistence must be conditional on the Core-Logs register.** If the Core Logs register
-  (`\_Database::$_registers[_underscore::DB_LOGS]`) isn't set, an Issue/Event write must be
-  skipped rather than fatal — but this belongs in the cron, not the handler.
-- **Client vs Core Logs DB mix-up.** The Issue/Event tables belong in the **Core** Logs DB
-  (`DB_LOGS`, `Model/Core/Logs/*`). Writing them to a per-client Logs DB
-  (`DB_CLIENT_LOGS`, `_Model_Client_Logs_*`) is the wrong target and does not match the
-  agreed design.
-- **Shared-schema migration collision.** Because `Issues`/`Events` live in the *shared* Core
-  Logs DB, two dbchanges2 `Logs/` migrations that both `CREATE TABLE Issues`/`Events` will
-  collide ("table already exists"). Only **one** migration may create the shared tables;
-  later migrations only `ALTER`.
-- **Cross-tenant secret exposure when captured context lands in the shared Core Logs DB.**
-  Moving the Issue/Event sink from a per-client Logs DB to the *shared* Core Logs DB widens
-  the blast radius of anything captured in `context`. A pre-migration `print_r($GLOBALS, true)`
-  dump (session tokens, auth headers, credentials from superglobals) that was acceptable while
-  per-tenant becomes a cross-tenant leak once every tenant can read the shared table.
-  `_underscore/Error.php::redactSensitiveContext()` recursively redacts superglobal keys
-  matching sensitive fragments (`password/secret/token/authorization/auth/apikey/credential/`
-  `cookie/session/jwt/private`) **before** persisting. Rule: sanitize captured context at the
-  point you move a log sink from per-client to shared.
-- **Strict-mysqli varchar overflow silently drops the Issue/Event row.** `_Error::initialize()`
-  sets `mysqli_report(MYSQLI_REPORT_STRICT)`, so assigning an over-255-char value to a
-  `varchar(255)` column (`errorMessage`, `subject`) **throws** on `->save()`. Because the write
-  happens inside the error handler's `catch(Throwable)`, the throw is swallowed and the row is
-  silently dropped — the error pipeline fails precisely when a long/detailed message matters
-  most. Truncate any raw exception message / user string to the column width before `save()`
-  on any `_underscore` model write under strict mysqli.
+- **Read-your-writes: reads go to the READ host and cannot see an uncommitted write.** A
+  second `$issue->save()` re-reads the row via `_Model::initialize()`, and that SELECT goes to
+  the read host — a separate connection that cannot see the still-uncommitted INSERT on the
+  write connection. Symptom: `Issues` rows with `reference` NULL, **zero** Events, **zero**
+  IssueFingerprints, no reference in the API response, and the logged cause *"Error during
+  Model build for primary key id '1' … Exactly 1 row was expected to be returned but 0 were."*
+  Capture aborted half-written. Fix: force reads to the writer for the whole capture block via
+  `_Database::getIsReadHostEnabled()` / `setIsReadHostEnabled(false)` with a `finally` restore
+  — the same TRUE-80448 pattern `_Email::send()` uses.
+- **Never rebuild a model inside an error handler.** `_Model`'s build **throws** when the row
+  is missing, and nothing inside an error handler should throw over a value derivable from the
+  primary key. `new _Model_Core_Logs_Issue($id)` rebuilds were replaced with a light SELECT
+  helper, and `reference` is written with a plain UPDATE rather than a second `save()`.
+- **`Issues.issueKey` is UNIQUE — handle the first-occurrence race.** Two concurrent first
+  occurrences of the same declared business condition raced on the INSERT and the loser's
+  occurrence was **silently dropped**. The loser must adopt the winner's Issue.
+- **`LAST_INSERT_ID(totalOccurrences + 1)` is the atomic event-number allocator** (a `_Model`
+  dirty-check read-modify-write loses increments). But `LAST_INSERT_ID` is only *assigned* when
+  the UPDATE matches a row — proven locally: against a missing row, `affected = 0` while
+  `LAST_INSERT_ID()` still returned the **stale** previous value `2`. Verify affected rows
+  before trusting it, or the event number silently collides with `UNIQUE(issueId, eventNumber)`.
+- **A new Issue must be seeded at its declared `minimumUrgency`**, not at LOW — otherwise the
+  floor is ignored until the next cron run.
+- **MySQL `UUID()` is forbidden for inserted records** by the 2.0 standard (time-based, not
+  random) — use `_String::generateUuid()` in PHP. It remains acceptable inside `.sql`
+  migrations, where no PHP exists (65 existing migrations do this).
+- **`VALUES()` in `ON DUPLICATE KEY UPDATE` is deprecated in MySQL 8.0.20+** — use the row-alias
+  form. **Evaluation order matters:** in `IssueAreaOwners`, `consecutiveCount` is assigned
+  **before** `clickupUserId` so the `IF()` compares against the *old* owner. Reversing them
+  makes the condition always true and the counter never resets.
+- **`Events.context` is an allowlist, never a dump.** It replaced `print_r($GLOBALS)` filtered
+  by a key-name blocklist — that blocklist recursed **arrays only** and walked straight past
+  objects whose *properties* hold DB credentials, into a table shared by every client.
+  `requestUri` and `referer` have query strings stripped (a `?token=abc` was `[REDACTED]` under
+  `get` and stored in clear in `requestUri`). The sensitive-fragment list covers **PII**, not
+  just credentials. Persisted traces are rebuilt **argument-free**.
+- **Keep the debug `print_r($GLOBALS)` dump inside the `isDebugMode()` branch.** It was being
+  built on every exception — including the OOM path the memory reserve exists to protect.
+- **Strict-mysqli varchar overflow silently drops the row.** `_Error::initialize()` sets
+  `mysqli_report(MYSQLI_REPORT_STRICT)`, so assigning an over-255-char value to a
+  `varchar(255)` (`errorMessage`, `subject`) **throws** on `->save()`. Inside the handler's
+  `catch(Throwable)` the throw is swallowed and the row is silently dropped — precisely when a
+  long message matters most. Truncate to column width before `save()`.
+- **Shared-schema migration collision.** Because these tables live in the *shared* Core Logs
+  DB, only **one** migration may `CREATE` them; later migrations only `ALTER`.
+- **Pre-existing committed secrets in this area (not fixed — out of scope, report only).**
+  A ClickUp API token at `_underscore/Component/Api/Clickup/Clickup.php:5`; SES SMTP
+  credentials at `_underscore/Email.php:11-12`; a named individual's Sentry personal access
+  token at `worker2/Worker/Sentry.php:4`. Also unfixed: api2 writes `apache_request_headers()`
+  verbatim into `Logs.Api` (bearer tokens in plaintext) and ships `$_SERVER` to Sentry. Treat
+  all of these as compromised whenever this area is touched again.
+
+## Decisions superseding the 2026-05-21 design
+
+### The POST-to-a-central-`/errors`-receiver hop is DROPPED (jcardinal, 2026-07-30)
+
+The **"2026-05-21 – Errors, Monitoring and Alerts"** meeting had approved a *POST-to-receiver*
+pipeline: application handlers POST a serialized error to a centralized `/errors` receiver
+endpoint (`webhook.hub.com/error`) and perform **no** database persistence; a worker2 cron
+consumes the payloads and does all hashing, upserting, aggregation, escalation, and ClickUp
+sync into the Core Logs DB.
+
+**That hop is dropped.** Error capture writes **directly** to the Core Logs DB from
+`_Error::captureException()`. Inline persistence is the model to follow; do not reintroduce an
+HTTP hop.
+
+Rationale: an error is frequently caused **by something being down**, so routing error capture
+through an HTTP call to api2 would lose exactly the errors you most need. Inline capture also
+buys the synchronous `reference` the api2 response envelope needs, which a fire-and-forget POST
+cannot. The agreed design still holds on the *sink* (shared Core Logs DB, not per-client) and on
+*who escalates* (the worker2 cron owns escalation and notification only).
+
+The cost of a direct write is that **each app must have the Core Logs connection registered**.
+The capture path already guards this with
+`isset(_Database::$_registers[_underscore::DB_LOGS])` — it **skips** capture rather than
+fatalling when the register is absent.
+
+### Why api2 is in scope at all
+
+api2 catches `Throwable` in its own front controller and therefore **never reaches
+`_Error::exceptionHandler`**. `captureException()` had to become a shared entry point that
+api2's catch blocks call directly — otherwise the entire inbound-API 500 surface would go
+unrecorded.
+
+### `Issues.type` enum and `BusinessIssues_Users` were proposed and not built (jcardinal, 2026-07-30)
+
+The **2026-06-12 "Monitoring Business Exceptions Sync"** meeting proposed an `Issues.type` enum
+(`'technical'`/`'business'`) and a `BusinessIssues_Users` bridge table (clientId +
+clientUserId). **Neither was built.** As built instead:
+
+- **No `type` column.** `issueKey` (non-null = a developer declared it a business condition in
+  code) plus `isManaged` (a human curated it) carry the same information while also being
+  useful on their own.
+- **`IssueEmailAddresses` uses varchar email addresses scoped by `clientId`** (`0` = all
+  clients) rather than client-user ids, so recipients who have **no login** can still be
+  addressed.
 
 ## Change history
 
+- 2026-07-30 — Reworked TRUE-78188: six-table schema in the shared Core Logs DB (Issue is
+  global by code; client scope lives on Events/IssueEmailAddresses); `_Error::captureException()`
+  as the single capture entry point; trace-frame fingerprinting with the message excluded
+  (replacing `md5(serialize(debug_backtrace()))`, which never deduped); many fingerprints → one
+  Issue for refactor safety; `_Exception_Business` with a stable `issueKey` + `minimumUrgency`;
+  base-26 quotable reference; a shutdown handler with a memory reserve (there was none).
+  Documented two MySQL constraints (1215 stored-generated-column vs. ON DELETE CASCADE; 3109
+  generated column cannot refer to auto-increment), the UNIQUE-on-VIRTUAL-generated-column
+  open-episode guard (`WHERE NOT EXISTS` is not safe under REPEATABLE READ), the read-host
+  read-your-writes failure that broke capture entirely, the issueKey first-occurrence race, the
+  `LAST_INSERT_ID` stale-value trap, the `Events.context` allowlist replacing the
+  `print_r($GLOBALS)` blocklist, and the Sentry-parallel decision. (jcardinal)
+- 2026-07-30 — **Decided: the 2026-05-21 POST-to-a-central-`/errors`-receiver hop is dropped.**
+  Capture writes directly from `_Error::captureException()`, guarded by
+  `isset(_Database::$_registers[_underscore::DB_LOGS])`; an HTTP hop would lose errors caused by
+  something being down. Recorded that api2 is in scope because its front controller catches
+  `Throwable` and never reaches `_Error::exceptionHandler`. Also recorded that the 2026-06-12
+  meeting's proposed `Issues.type` enum and `BusinessIssues_Users` bridge table were **not
+  built** — `issueKey` + `isManaged` and `clientId`-scoped varchar `IssueEmailAddresses` are the
+  as-built equivalents. Supersedes the 2026-07-08 correction. (jcardinal)
 - 2026-07-15 — Added two framework gotchas from aligning the `_underscore` side of the
-  Issue/Event pipeline to the shared Core Logs DB: (1) cross-tenant secret exposure when
-  captured context lands in the shared DB, mitigated by `redactSensitiveContext()` in
-  Error.php; (2) strict-mysqli varchar overflow throwing inside the handler's `catch(Throwable)`
-  silently drops the Issue/Event row — truncate to column width before `save()`. (dfranks)
+  Issue/Event pipeline to the shared Core Logs DB: cross-tenant secret exposure in captured
+  context, and strict-mysqli varchar overflow throwing inside `catch(Throwable)`. (dfranks)
 - 2026-07-08 — Corrected KB drift: documented the approved 2026-05-21 error-monitoring
-  architecture (handlers POST to a centralized `/errors` receiver; a worker2 cron builds
-  issueHash, upserts Issues + inserts Events into the Core Logs DB, aggregates/escalates,
-  syncs ClickUp — handlers do not persist). Clarified that `_production` Error.php performs
-  no Issue/Event persistence (only an S3 debug body + flat `*_Logs_Error` row), and that the
-  inline-DB-persist approach (handler-side upsert to the *Client* Logs DB) conflicts with the
-  agreed design and is not the pattern to follow. (dfranks)
+  architecture (handlers POST to a centralized `/errors` receiver; a worker2 cron aggregates
+  into the Core Logs DB). **Superseded 2026-07-30 — the receiver hop was dropped.** (dfranks)
 - 2026-07-06 — Prior doc described the exceptionHandler as directly persisting Issue/Event
-  rows to the Core Logs DB with dedup; superseded by the 2026-07-08 correction above. (dfranks)
+  rows with dedup; superseded by the 2026-07-08 correction. (dfranks)
+</content>
+</invoke>

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

@@ -17,7 +17,7 @@
 | [TableView row-filtering via apiWhereClause (options.where grammar, end to end)](features/tableview-apiwhereclause-row-filtering.md) | `TableViews.apiWhereClause` (TEXT, nullable) is the sanctioned, code-free way to restrict or exclude rows from a 2.0 table view. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/TableView.php, toga2-supply/src/api/toga.ts |
 | [TableView field/column metadata (TableViewFields, hidden projected columns)](features/tableview-field-metadata.md) | The columns of a 2.0 table view are defined by DB metadata, not code. | _underscore/Model/Client/TableView.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
-| [V2 API error/message codes (EV/EZ troubleshooting map)](features/v2-api-error-codes.md) | The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the response `error` field, grouped by family: `EN-*` authentication, `EZ-*` a | api2/Component/Api/V2/V2.php, _underscore/Model/Client/TrackingNumber.php |
+| [V2 API error/message codes (EV/EZ troubleshooting map)](features/v2-api-error-codes.md) | The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the response `error` field, grouped by family: `EN-*` authentication, `EZ-*` a | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, api2/Component/Api/V2/Response/Oauth/Oauth.php, api2/Controller/Index.php, toga2-supply/src/globalTypes.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, _underscore/Model/Client/TrackingNumber.php |
 | [V2 REST query contract (params, where grammar, encoding, ACL behavior)](features/v2-rest-query-contract.md) | What an **HTTP client** has to get right to query the Toga v2 REST API: which query params are recognized, the exact `where` grammar, how the query string is (n | api2/Component/Api/V2/V2.php |
 | [V2 reverse hasMany collections must be named in the fetch fields whitelist](features/v2-reverse-hasmany-fields-whitelist.md) | In the V2 JSON engine, a **reverse hasMany** relationship — the collection of child records that foreign-key back to a parent (e.g. | api2/Component/Api/V2/V2.php |
 | [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. | api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php |

package/knowledge/2.0/apps/api2/features/v2-api-error-codes.md

@@ -6,12 +6,18 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-29
+updated: 2026-07-30
 owners: [mhammontree, tcox, jcardinal]
 files:
   - api2/Component/Api/V2/V2.php
+  - api2/Component/Api/V2/Response/Response.php
+  - api2/Component/Api/V2/Response/Oauth/Oauth.php
+  - api2/Controller/Index.php
+  - toga2-supply/src/globalTypes.ts
+  - toga2-supply/src/pages/Orders/api/OrdersApi.ts
   - _underscore/Model/Client/TrackingNumber.php
 related:
+  - ../../_underscore/features/error-reporting-issue-event.md
   - ../../_underscore/features/acl-permission-chain.md
   - scripted-api-post-body-args.md
   - v2-rest-query-contract.md
@@ -91,6 +97,61 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
    DB fully migrated. On a local dev box with PHP opcache disabled a branch switch takes effect
    immediately (files are read fresh per request) — no Apache restart needed.
 
+## BREAKING (2026-07-30): `error` is now an object, not a bare string
+
+The V2 envelope's `error` changed from a bare string (`"EO-1"`) to an **object**:
+
+```json
+"error": { "code": "EO-1", "id": "1C-1" }
+```
+
+- **`code`** — the same short message code documented above.
+- **`id`** — the quotable **Core Logs reference** for a *captured exception* (see
+  [error reporting](../../_underscore/features/error-reporting-issue-event.md)), and **`null`**
+  for a graceful rejection. `id` is **always present** so the shape is predictable — consumers
+  must not branch on its absence.
+
+The object is assembled from **private** properties (`json_encode` emits public only) via
+`setErrorReference()` + `refreshError()`, so it works whether the reference arrives **before or
+after** the code — the controller sets the reference first. All six orderings were verified.
+
+**The OAuth response subclass deliberately keeps the flat string form**
+(`const USES_STRUCTURED_ERROR = false`). RFC 6749 §5.2 defines `error` as a single ASCII string,
+and both classes share `addDefinedMessage()`, so emitting the object there would break every
+conforming OAuth client library. Do not "unify" this.
+
+**Also fixed here (CRITICAL): api2 returned `$e->getTrace()` to external callers on every 500.**
+Unlike `getTraceAsString()`, `getTrace()` returns raw frame **arguments** — and the DB-bootstrap
+catch has `_Database::register()` on the stack, so the **database username and password were
+reachable by anyone who could force a 500**. `message` and `trace` are now gated behind
+`_Environment::isDebugMode()`.
+
+### Consumer audit
+
+- **`library/app/api/toga2.php`** (the 1.0↔2.0 bridge) branches on `isSuccess` only, never
+  `error` — safe.
+- **`toga2-supply`** — `ApiResponse<T>.error` is now `ApiError | null`; 30 envelope reads in
+  `OrdersApi.ts` became `.error?.code` (all 21 declarations there are
+  `await togaApiRequest(...)`, verified).
+- **`toga-blox-npm` is not affected** — no `isSuccess` anywhere; it reads axios'
+  `response.data.data.…`.
+- **Outstanding:** the external `API-DOCUMENTATION.md` lives outside the checkout and still
+  documents `error` as a string.
+
+### Gotcha — do NOT regex-sweep `.error` → `.error?.code`
+
+Only direct `togaApiRequest()` results are envelopes. These look identical and are **local
+`{success, error}` shapes whose `error` is a plain string** — adding `?.code` breaks the failure
+guard and swaps the real backend message for a generic fallback:
+
+- `payload` in `UpdateShipmentApi.ts` (`response?.data?.itemFulfillments?.generateReturnLabel`)
+- `shipmentResponse` from `fulfillShipment()`
+- `response` in `EditShipmentForm.tsx` from `updateShipment()` / `saveShipment()`
+- `messages[0].identifiers.error` — that is the message-identifiers map, not the envelope.
+
+Verification gap: `toga2-supply` had no `node_modules`, so `tsc` could not be run.
+**`npm run build` is the definitive check** — the type change will surface anything missed.
+
 ## Related recipes
 
 - **Add a writable field to a V2 record (3-file migration)** and **expose a scripted API**
@@ -103,6 +164,17 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
 
 ## Change history
 
+- 2026-07-30 — **BREAKING:** envelope `error` changed from a bare string to
+  `{ code, id }`, where `id` is the quotable Core Logs reference for a captured exception and
+  `null` for a graceful rejection (always present, for a predictable shape); assembled from
+  private properties via `setErrorReference()`/`refreshError()` so code and reference can arrive
+  in any order. The OAuth subclass keeps the flat string form
+  (`USES_STRUCTURED_ERROR = false`) per RFC 6749 §5.2. Fixed a CRITICAL disclosure: api2
+  returned `$e->getTrace()` (raw frame **arguments**, including `_Database::register()`'s DB
+  username/password) to external callers on every 500 — `message`/`trace` are now gated behind
+  `_Environment::isDebugMode()`. Recorded the consumer audit (library bridge and toga-blox-npm
+  unaffected; toga2-supply migrated) and the regex-sweep gotcha for look-alike local
+  `{success, error}` shapes. (jcardinal)
 - 2026-07-29 — Added **EV-13** (`recordsPerPage` over the 10000 max) and **diagnosis note 6**:
   what a denial looks like from the client side — `EZ-1` = record-level (`data.<route>` null,
   and a bare `allowRead=1` with no logic group still returns it); `EZ-2` = field-level,

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

@@ -18,6 +18,7 @@
 | [Compass VIP Support Importer (worker2)](features/compass-vip-support-importer.md) | A worker2 action that ingests Compass's quarterly VIP spreadsheet and assigns each VIP user's support technician by setting `Users.c_supportedByUserId` in `Clie | worker2/Worker/Client/Compass/VipSupport.php |
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
+| [Error Escalation Cron (Errors::Escalate → ClickUp / email)](features/error-escalation-cron.md) | `_Worker_Infrastructure_Errors::Escalate` (renamed from `SyncWithClickup`) is the sole owner of **escalation, de-escalation, ClickUp ticketing, reminders, busin | worker2/Worker/Infrastructure/Errors.php, worker2/Worker/Clickup/ErrorTask.php, worker2/Worker/Clickup.php, worker2/Config/production.ini, dbchanges2/Core/2026-07-30a - Error escalation cron job.sql |
 | [Etilize Catalog Item Import & Refresh](features/etilize-catalog-item-import.md) | Client-generic catalog onboarding from an S3 CSV plus an Etilize re-pull. | worker2/Worker/Etilize/Items.php |
 | [Etilize Item Translation Import](features/etilize-item-translation-import.md) | The abstract worker class `_Worker_Etilize_ItemTranslations` imports **non-English** item text from Etilize into the client's `ItemTranslations` table. | worker2/Worker/Etilize/ItemTranslations.php |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Monitors/RateEntitlement.php, worker2/Worker/Notification/Email.php, worker2/Worker/Rate.php, dbchanges2/Core/2026-05-21 - Monitors.sql, dbchanges2/Core/2026-06-29a - Rate Entitlement Contract Monitor.sql |

package/knowledge/2.0/apps/worker2/features/error-escalation-cron.md

@@ -0,0 +1,157 @@
+---
+title: Error Escalation Cron (Errors::Escalate → ClickUp / email)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-07-30
+owners: ["jcardinal"]
+files:
+  - worker2/Worker/Infrastructure/Errors.php
+  - worker2/Worker/Clickup/ErrorTask.php
+  - worker2/Worker/Clickup.php
+  - worker2/Config/production.ini
+  - dbchanges2/Core/2026-07-30a - Error escalation cron job.sql
+related:
+  - ../../_underscore/features/error-reporting-issue-event.md
+  - ../../../1.0/apps/tools/features/errors-curation-console.md
+  - ./creating-worker-actions.md
+  - ./clickup-project-routing.md
+---
+
+## Summary
+
+`_Worker_Infrastructure_Errors::Escalate` (renamed from `SyncWithClickup`) is the sole owner of
+**escalation, de-escalation, ClickUp ticketing, reminders, business email, owner learning, and
+GC** for the Issue/Event error-reporting pipeline. Capture is `_underscore`'s job (see
+[error-reporting-issue-event](../../_underscore/features/error-reporting-issue-event.md)); the
+Tools `/errors` console curates but **notifies nobody**. All outbound notification funnels
+through this one action, so there is exactly one place to mute or debug alerting.
+
+## How it works
+
+### Urgency = max of two independent axes, plus a floor
+
+- **Volume** — occurrences in a 10-minute window: **20 / 50 / 100**.
+- **Neglect** — hours an *unacknowledged* ClickUp task has sat: **1 / 4 / 24**.
+- **Floor** — the Issue's declared `minimumUrgency` applies under *both* axes.
+
+The neglect axis exists because volume alone cannot see a rare-but-serious error, nor a serious
+error that everyone is ignoring.
+
+### Fast up, slow down
+
+Escalation applies **the same run** a band is crossed. De-escalation requires the count to sit
+under a **lower release band (12 / 35 / 70)** for **3 consecutive windows**. Without that gap,
+an issue hovering near a threshold flaps every minute and burns a ClickUp write each time.
+
+### Task-creation gate
+
+A ClickUp task is created only when urgency ≥ NORMAL, **or** a floor is set, **or** the Issue is
+curated, **or** it is still rare. Creating a task for every distinct error on first sight is what
+buries a team.
+
+### Reminders
+
+Backed off **30m → 1h → 4h → daily**. Never sent on de-escalation. Suppressed entirely while
+`dtMutedUntil` is in the future.
+
+### Sprint promotion
+
+Uses the ClickUp **v2 multi-list** "Add Task To List" endpoint
+(`POST /list/{id}/task/{taskId}`) so the errors list stays the task's **permanent home**. The v3
+`home_list` move endpoint was rejected: v3 is not reliably deployed, it needs a workspace id
+that exists nowhere in the codebase, and it requires `status_mappings` maintenance.
+
+The target sprint list is resolved from `[clickup] sprint_folder_id` because `Team.Sprints`
+carries no ClickUp list id — `GET /folder/{id}/list`, then the list whose `start_date`/`due_date`
+range contains today.
+
+### Recurrence (episodes)
+
+One `IssueClickupTasks` row per ClickUp **episode**. Closing the task fires a webhook that stamps
+`dtResolved` and increments `recurrenceCount`. A later occurrence opens a **new** task linked to
+its predecessors via `POST /task/{id}/link/{links_to}` — a **link, not a dependency**; a
+dependency would *block* the task. A cooldown prevents recreating a task 60 seconds after
+someone closed it while the error was still firing.
+
+### Acknowledgement
+
+ClickUp is the acknowledge/resolve system — developers already live there, and a second inbox in
+Tools would just be ignored. **Any** status change on an error task counts as acknowledgement,
+which is safe only because the automation never sets status itself.
+
+### Area-level owner learning (observation only)
+
+`IssueAreaOwners` learns an owner after **5 in a row** and ships **observation-only** — a hint in
+the task body, never an auto-assignment. Misassignment is expensive: a few wrong tickets and
+developers stop trusting the queue. Learning is per **area**, not per issue, because one issue
+rarely recurs enough to learn from before it is fixed.
+
+### Garbage collection (split, deliberately)
+
+- **Events** purge at **7 days**.
+- **Issues** purge only when nothing curated them: not `isManaged`, no `issueKey`, no floor, no
+  recipients, no ClickUp history, no events.
+
+The original blanket 30-day delete would have **cascaded a configured business issue's email
+recipients away** after a quiet month.
+
+## Configuration
+
+- **`[_underscore] error_escalation_enabled`** — added to **all 8** worker2 configs: `1` in
+  `production.ini` **only**, `0` elsewhere. It is the master switch for **all outbound
+  notification**; errors are still **captured** regardless, so non-production records everything
+  and notifies nobody.
+  - Gated on a config key rather than string-matching `_Environment::$name` because
+    `_Environment` has **no `isProduction()`** — only a raw name string and an ad-hoc
+    `substr($name, 0, 4) == 'dev-'` idiom. Guessing env names would silently spam, or silently
+    stay quiet, in the wrong place.
+  - Read via `_Config::_underscore(key, false)`. **The second falsy argument matters:** it makes
+    `_Config` return `false` for a missing key/group **instead of throwing**, and an uncaught
+    throw would fail the whole cron.
+- **`[clickup] sprint_folder_id`** — added to `worker2/Config/production.ini`, left **empty with
+  instructions**. Note `[clickup]` exists in only **2 of the 8** worker2 configs.
+
+## Gotchas / known issues
+
+- **The working-set query must be a UNION, not an OR.** It is a UNION of three separately
+  indexable branches. MySQL will **not** `index_merge` across an `OR` when one branch is a
+  correlated `EXISTS`, so the OR form **full-scans `Issues` every 60 seconds, forever**.
+- **`INSERT ... SELECT ... WHERE NOT EXISTS` is not a concurrency guard** under REPEATABLE READ.
+  The open-episode guard is a UNIQUE key on a VIRTUAL generated column, and the code **claims
+  the episode before calling ClickUp** so a losing run fails before creating a duplicate
+  external task — see the `_underscore` doc for the full mechanics.
+- **Business email must be scoped per client.** Recipients were resolved from the **most recent
+  event's** client, so with two clients firing in the same window **client B's business users
+  received email about client A's data**. It now sends one email **per distinct client that
+  actually fired in the window**.
+- **Business email bodies/subjects must not carry `errorMessage` or `trace`.** Both are seeded
+  once from whichever client created the Issue and are never re-scoped. An uncurated business
+  issue gets a **neutral** subject rather than another client's raw error text.
+- **`IssueEmailAddresses.clientId = 0` means "all clients"** and requires an explicit
+  confirmation flag in the Tools console; list views render it as **"ALL CLIENTS"**.
+- **The ClickUp webhook has no HMAC signature verification** (pre-existing, unfixed). A forged
+  POST can mark issues acknowledged — freezing the neglect axis — or resolve episodes. That is
+  alert suppression against the error-reporting system itself. Fix before relying on this
+  pipeline as the only alerting path.
+- **`_Worker_Sentry::Webhook` writes into the same ClickUp list (`901110669877`)** this cron
+  targets. Both pipelines run in parallel by design until the Sentry-removal ticket lands, so
+  expect duplicate-looking tasks from two sources.
+
+## Change history
+
+- 2026-07-30 — Built as part of TRUE-78188: action renamed `SyncWithClickup` → `Escalate`; new
+  `Worker/Clickup/ErrorTask.php`. Two-axis urgency (volume 20/50/100 + neglect 1/4/24) with a
+  `minimumUrgency` floor; fast-up/slow-down with release bands 12/35/70 over 3 windows; a
+  task-creation gate; 30m→1h→4h→daily reminders honouring `dtMutedUntil`; sprint promotion via
+  the v2 multi-list endpoint (v3 `home_list` rejected); episode recurrence via task *links* not
+  dependencies; a UNION (not OR) working-set query; and split GC (Events 7d, Issues only when
+  uncurated). Fixed from review: per-client business email scoping (client B was receiving
+  client A's data), neutral subjects with no errorMessage/trace, seeding new issues at their
+  declared floor, `_String::generateUuid()` over MySQL `UUID()`, and the row-alias form of
+  `ON DUPLICATE KEY UPDATE`. Added `error_escalation_enabled` (all 8 configs) and
+  `[clickup] sprint_folder_id`. (jcardinal)
+</content>

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

@@ -393,6 +393,9 @@ Signed integers can reference positive and negative numbers, but unsigned can on
   1. **Use the `_Model` layer.** The metadata-driven ORM builds and escapes queries for you — prefer it over hand-written SQL whenever possible.
   2. **When you must write SQL by hand, escape every interpolated value with `_Database::escape()`** before placing it in the query string.
 * `_Database::escape()` adds MySQL escape characters (`\`, `'`, `"`, newlines, etc.) and is the correct helper for query interpolation. Do **not** confuse it with `_Database::protect()`, which *strips* `% \ / * " '` and the literal ` or` — that is lossy filtering, not escaping, and will corrupt data you intend to store intact.
+* **Prepared statements are not available.** `_Query` accepts only a raw SQL string, and `_Database_Driver` declares no `prepare`/`bind` (verified 2026-07-30 — neither the Mysql nor the Pgsql driver implements one). Escaping and casting *are* the parameterization mechanism in 2.0; do not go looking for a bind API, and do not trust any guidance that names a `_Db` class — there isn't one.
+* **Escaping protects values, not identifiers.** Table names, column names, sort directions, and `LIMIT` expressions must come from a **hardcoded allowlist** — never from a request, and never merely escaped. `ORDER BY " . _Database::escape($_GET['sort'])` is still injectable.
+* **Validate enum values in PHP.** `FIELD_LIST` performs no enum validation and converts any falsy value to SQL `NULL`; MySQL coerces rather than rejects an unknown member. Check against the allowed set before the value reaches the query — a typo'd urgency becomes `NULL`, not an error.
 
 ```php
 // Bad — raw interpolation

package/knowledge/INDEX.md

@@ -14,12 +14,12 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 13 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
-- **tools** (Tools) — 11 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 12 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 40 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 37 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 38 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 20 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)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/knowledge/sessions/2026-07-30-TRUE-80487-Debug-Fix-Rate-WH-Warranty-mhammontree.md

@@ -0,0 +1,97 @@
+---
+type: session
+slug: TRUE-80487-Debug-Fix-Rate-WH-Warranty
+title: Rate Whole Home Warranty per-address dedup — root-caused "works in beta, fails in prod"
+author: mhammontree
+repos: [_underscore, toga2-view, dbchanges2, test]
+framework: "2.0"
+client: rate
+status: active
+created: 2026-07-30
+updated: 2026-07-30
+---
+
+# Session: TRUE-80487-Debug-Fix-Rate-WH-Warranty
+**Date:** 2026-07-30
+**Project/Repo:** _underscore / toga2-view / dbchanges2 / test (2.0)
+**Task:** Production troubleshooting of the Rate Whole Home Warranty per-address duplicate-purchase guard (TRUE-79533, already deployed), reported as "works in beta, not in production" — root-caused to three independent code defects, none of them a deployment gap.
+
+---
+
+## What WORKED
+
+- **Eliminated every deployment-gap hypothesis with hard evidence.** `_underscore` `_production` HEAD is `ba7eff66` (TRUE-79533 PR #661 merged 2026-07-29); `dbchanges2` `_main` is `138df5e` (PR #418). `git diff origin/_beta -- Model/Rate/Entitlement.php` returns **zero diff** — prod and beta run identical code.
+- **Confirmed all prod DB artifacts present.** `Core.RecordFields` id **2482** = `entitlements.serviceAddressId` registered; `Client_Rate.Entitlements.serviceAddressId` column + index exist; ACL grants present (`2482` → role 1 `isWritable=0`, mirroring `saleItemId` 1265; `addresses.id` field 41 → roles 1,2,3). `ApiPayloadInterceptors` in prod is **byte-identical to dev-sandbox** (id 4 = rec 191 PRE/POST `minDepth NULL`; id 2 = rec 191 POST/POST `minDepth 5`).
+- **ROOT CAUSE #1 — the backend guard has never executed, in any environment.** `isWholeHomeWarranty()` at `_underscore/Model/Rate/Entitlement.php:116-118` reads `$payload->saleItem->title`, but the real checkout payload sends `"saleItem":{"uuid":"3e14effa-0f78-4708-b338-60872a39aff3"}` with **no `title`**. `stripos('', 'warranty')` → false → `prePost` returns at line 58 before the guard runs. Evidence: beta payload for entitlement 106, `Logs_Rate.Api` id 48823 (dev-sandbox, 2026-07-27 11:41:15), verbatim.
+- **Proved it with beta's own data.** dev-sandbox has **three active WH entitlements at the same address** `1864 HIGH GROVE LN 60540`: `ET100057` (id 90, 2026-07-24), `ET100067` (id 100, **2026-07-27 10:10**), `ET100073` (id 106, **2026-07-27 11:41**) — two created on the very day the feature was marked "beta-verified". Plus two at `121 N LA SALLE ST 60602` (`ET100071`, `ET100072`). All same borrower `5686507f-a7b2-4fca-b007-dd3ae875e4bb`, all pinned, all active.
+- **Confirmed the guard's rejection message appears in NO log, in either environment, ever.** All 8 beta `POST /v2/entitlements` 400s are `EV-12` (reference errors) and one `EV-8` (`contractFulfillmentPreference`, 2026-07-15, pre-dating the PRE interceptor registration).
+- **ROOT CAUSE #2 — `state.code` vs `state.uuid`.** `prePost:66` reads `$address->state->code`, but the payload sends `"state":{"uuid":"94417b26-..."}`. Fixing #1 alone would make every WH purchase throw *"A valid service address is required"* — a false rejection on valid addresses. **Both must be fixed together.**
+- **ROOT CAUSE #3 — frontend availability check fails open AND is borrower-scoped.** `toga2-view/src/pages/ZipValidation/viewModels/useZipValidationViewModel.ts:135-139` — `const address = entitlement.serviceAddress; if (!address?.line1) return false;` and `serviceAddress` is derived only from the pin (`useActiveServices.ts:108`). Worse, `useActiveServices.ts:69-71` scopes the query `where: { and: [{ "Customers.c_borrowerId": { "=": borrowerId } }] }` — so it can **never** see another borrower's warranty, while the backend guard is explicitly global. Its code comment claims "same source as the backend guard's dedup join" — that comment is wrong; the backend uses `COALESCE(serviceAddressId, ContactAddresses.addressId)`, the frontend has no fallback.
+- **Verified the backend WOULD block, without paying.** Replicated `hasActiveWarrantyAtAddress()` SQL read-only against prod for `1864 HIGH GROVE LN / Naperville / 60540 / IL` → returns entitlement **43 (`ET100017`)**. So a real purchase reaches PayPal, the customer is charged, and *then* the entitlement POST is rejected.
+- **Confirmed the apartment-building exposure is real.** Property type lives only in router state / `sessionStorage` (`useCheckoutPageViewModel.ts:178-205`) and is **never sent to the API** — the purchase payload contains no `propertyType` / `isEligible`. `prePost:68-70` requires line1/city/state/zip but **not** `line2`. The `requireUnitNumber` flow (`ZipValidation.tsx:62-75`, `198-199`) is client-side only and bypassable. Live proof: beta `ET100073` carries `line2: "STE 500"` on a single-family home, while ids 90/100 at the same `line1` have no unit.
+- **Production data repaired by the developer and verified clean.** Three active WH warranties, all pinned + validated, both-or-neither invariant holds on all nine rows: 43 (`ET100017`) → addr 9 Naperville, 40 (`ET100014`) → addr 6 Nashua, 38 (`ET100012`) → addr 4 Wailuku. Subscription 22 (`ET100015`, Daniel Moran) closed out `isActive=0, dateCancelled='2026-06-03'`; address 7 `city` corrected `60657` → `Chicago`.
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **"A migration is missing in production."** DISPROVEN. `Core.RecordFields` 2482 exists; `Client_Rate.Entitlements.serviceAddressId` column + index exist; both ACL grants landed. Do not re-audit `Core/2026-07-22a`, `Client/2026-07-22a`, `Client/2026-07-23a`, `Client_Rate/2026-07-23a`, `Client_Rate/2026-07-24a` — all applied.
+- **"TRUE-79251 merge damage deleted the WH helper methods."** DISPROVEN. `git diff origin/_beta -- Model/Rate/Entitlement.php` → zero diff. `PASSTHROUGH_KEY_FULFILLMENT_PREFERENCE` (line 32) and all three private helpers (`normalizedField` 107, `isWholeHomeWarranty` 116, `hasActiveWarrantyAtAddress` 137) present.
+- **"`_underscore` prod wasn't redeployed past the uuid-clobber fix `9c2e4b1c`."** DISPROVEN by the same zero diff + PR #661 merged.
+- **"`toga2-view` prod still sends `{depth:-1}` and starves `postPost`."** DISPROVEN. `genericApi.ts:54,68` only append `?depth=-1` when `returnPayloadDepth` is explicitly set; no checkout override. Diff vs `_beta` touches only GetSupport files.
+- **"Cross-cluster `Core.RecordFields` references from `Client*/` migration folders fail in prod."** DISPROVEN for this case. Despite prod splitting `prod-core` / `prod-client` / `prod-logs` / `prod-archive` onto separate clusters, the ACL grants landed correctly. ~20 long-standing ACL migrations use this same pattern. (Note: the `dbchanges2-cluster-isolation` hook was NOT found under `.claude/hooks/toga/` — separate follow-up, not this bug.)
+- **"The interceptor row is missing, inactive, or duplicated in prod."** DISPROVEN — prod rows are identical to dev-sandbox, same ids and uuids.
+- **"`POST /v2/entitlement-sales-orders` is the prod purchase path (record 257, no interceptor)."** DISPROVEN. It is only a bridge link: payload is `{"entitlement":{"uuid"},"salesOrder":{"uuid"}}`. It creates no entitlement and fires no interceptor.
+- **"Production simply hasn't processed a purchase since deploy, so there's nothing to debug."** TRUE as a fact (last `POST /v2/entitlements` in prod = 2026-07-10, two × 400 `EV-8`; newest `Entitlements` row 2026-06-15) but WRONG as a conclusion — the developer then reproduced the failure live through the UI. Do not stop at this observation.
+- **Query that hangs — do not run.** `SELECT ... FROM Logs_Rate.Api WHERE route LIKE '%address%'` timed out after **300s** (unindexed full scan on a ~12.7M-row table). Always constrain with the `dtStamp` index: `WHERE dtStamp >= '...' AND dtStamp < '...'`.
+- **Columns that do not exist (queries will error).** `Client_Rate.ApiPayloadInterceptors.phpMethod` — absent in prod (yet `Client_Rate/2025-12-10 - PostInterceptor.sql` inserts it, so that file is not re-runnable). `Client_Rate.Contacts.emailAddress` — does not exist. `Logs_Rate.Api.uri` — the column is `route`.
+- **Widening the frontend `useActiveServices` query to all borrowers.** REJECTED, do not do this — it would let any portal user read other customers' entitlements and addresses. A data-leak fix worse than the bug.
+
+## Not tried yet (candidates for next session)
+
+- Fix `isWholeHomeWarranty()` to resolve `saleItem.uuid` → item (fall back to payload `name` and/or `WH_SALE_ITEM_ID = 3`), matching the authority `hasActiveWarrantyAtAddress()` already uses in SQL.
+- Fix state resolution to accept `state.uuid` with `state.code` as fallback.
+- Normalize zip to first 5 digits in the dedup comparison (`Entitlement.php:161` is exact-match; frontend already truncates at `addressCompare.ts:22`). Untested risk: USPS returning `60540-9233` vs stored `60540`.
+- Normalize the unit designator before comparison so `STE 500` / `Suite 500` / `#500` / `Unit 500` collapse to one dwelling.
+- Build the server-side global pre-check: boolean-only scripted endpoint reusing `hasActiveWarrantyAtAddress()`, called from the availability step, deleting the frontend's local dedup. Needs a `dbchanges2` migration registering it in `Core.RecordScripts` **plus** the client ACL grant — note `validateAddress` (RecordScripts id 17) exists only in the live DB and NOT in `dbchanges2`, the exact parity trap to avoid.
+- Log one raw USPS / FedEx / UPS validation response for a known apartment vs a known single-family address, to settle field names empirically. `Fedex.php:417-421` already receives the full `attributes` object and reads only `Matched` / `Resolved`; `Ups.php:801-807` reads only `NoCandidatesIndicator` / `Candidate`.
+- Capture the USPS DPV "valid but secondary unit missing" signal into `validateAddress`'s normalized return with an explicit unknown state, and enforce in `prePost`.
+- Send and persist `propertyType` with the purchase so eligibility is enforced server-side rather than trusted from the browser.
+- Update `test/@Mark/Rate/verify_wholehome_per_address_guard.php` to use the REAL payload shape (uuid-only `saleItem`, uuid-only `state`). It currently passes 18/18 against a shape production never sends — this is why all three defects survived review.
+- Clean up beta duplicates: dev-sandbox entitlements 100, 105, 106.
+- Controlled prod WH purchase to exercise the untested `minDepth = 5` on the POST interceptor, and to test USPS "Suggested" (`60540-9233`) vs "You entered" (`60540`).
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `_underscore/Model/Rate/Entitlement.php` | **investigated, NOT modified** | Holds root causes #1 (line 116-118) and #2 (line 66). Also: raw SQL string concatenation at lines 371/375 violates the parameterized-query standard; accepted TOCTOU noted at 133-135. |
+| `toga2-view/src/pages/ZipValidation/viewModels/useZipValidationViewModel.ts` | **investigated, NOT modified** | Root cause #3 fail-open at 135-139. Misleading comment claims parity with backend join. |
+| `toga2-view/src/hooks/useActiveServices.ts` | **investigated, NOT modified** | Borrower-scoped `where` at 69-71; pin-only `serviceAddress` resolution at 108; silent EZ-2 degrade at 90. |
+| `toga2-view/src/pages/CheckOut/viewModel/useCheckoutPageViewModel.ts` | **investigated, NOT modified** | `propertyType` read from router state / sessionStorage (178-205), never sent to API. |
+| `_underscore/Model/Client/Address.php` | **investigated, NOT modified** | `validateAddress` waterfall USPS→FedEx→UPS (31-46); returns success + normalized fields only, no unit-required signal. |
+| `_underscore/Component/Library/Carriers/{Usps,Fedex,Ups}` | **investigated, NOT modified** | Signals available but discarded. NOTE: this is a namespace inside `_underscore`, NOT the 1.0 `library` repo. |
+| `test/@Mark/Rate/verify_wholehome_per_address_guard.php` | **not opened** | Passes 18/18 against the wrong payload shape. Needs rewrite. |
+| **Production `Client_Rate` data** | **CHANGED by developer, verified** | Ents 43→addr 9, 40→addr 6, 38→addr 4 pinned; those 3 addresses `isValidated=1`; subscription 22 closed `isActive=0, dateCancelled='2026-06-03'`; address 7 `city` → `Chicago`. No repo files changed this session. |
+
+## Decisions made
+
+- **Keep `dateEnd` OUT of the dedup predicate.** Rationale: the guard's contract is `isActive = 1 AND dateCancelled IS NULL`; adding `dateEnd` would let real duplicates through when a renewal hasn't rolled `dateEnd` forward yet. Rejected alternative: filter on `dateEnd`. Confirmed instance of the underlying problem: Kimberly Stearns (`ET100014`) has `dateEnd = 2026-06-01` yet was charged 2026-07-01 — renewals are not advancing `dateEnd`. **Separate ticket.**
+- **Do NOT widen the frontend query to all borrowers; move the check server-side instead.** Rationale: the frontend fundamentally cannot answer "does anyone have a warranty here?" without exposing other customers' data. A boolean-only endpoint reusing the existing helper makes availability and purchase the same code path, so they cannot drift.
+- **Skip the legacy-entitlement backfill migration.** Rationale: only two rows mattered and they were fixed by hand; once the server-side check ships, pinning is no longer required for dedup correctness. Migration would be pure data churn.
+- **Do not chase "dwelling type" from shipping carriers.** Rationale: postal data models deliverability, not property characteristics — no carrier returns single-family vs multi-unit. UPS `AddressClassification` / FedEx `classification` only give Residential vs Commercial, and an apartment building is "Residential". The actionable signal is USPS DPV "secondary unit required but missing". True dwelling type needs property data (assessor/parcel, or Melissa/Smarty-class vendor) — a procurement decision for Paulina + underwriting.
+- **Did NOT complete the PayPal test payment.** Rationale: the backend rejects *after* the charge; the read-only SQL replication already proved what the guard decides.
+- **Branch naming = bare ticket ID `TRUE-80487`.** Rationale: matches live convention in all four repos (`TRUE-78188`, `TRUE-78314`, `TRUE-79191`, `TRUE-79868`). The documented `fix/short-description` rule in the git-workflow standard is stale — flag for correction.
+- **Repo scope:** minimum `_underscore` + `test` (makes the global rejection actually work); add `dbchanges2` + `toga2-view` for the server-side pre-check. `api2` NOT needed (scripted endpoints are served by the V2 engine from `_underscore` models; registration is DB-side). Recommendation: branch all four — an unused branch is free, discovering a needed migration mid-sprint is not.
+- **Reframed the ticket premise.** "Works in beta, fails in prod" is false. Same code, same migrations, same interceptor rows. Beta only *appeared* to work because its test data satisfied both frontend preconditions by accident — a single test borrower, and data created after the pin shipped. Production satisfied neither.
+
+## Blockers
+
+- **Need the current dev branch name** to base the four `TRUE-80487` branches on. `_underscore` shows `_beta`; `toga2-view` shows both `_beta` and `_stage`. Developer said they are on "a different dev branch now" — unresolved.
+- **Need a product decision from Paulina: per-dwelling or per-building coverage?** Currently `123 Main St` and `123 Main St APT 2` are distinct addresses, so both can hold a warranty. This changes what the fix does. Sharpened by the finding that a *no-unit* purchase at a multi-unit address is indistinguishable from a single-family purchase and carries building-scale liability at single-home pricing.
+- **Need a scope decision:** does property-type / unit-required enforcement land in TRUE-80487, or a separate ticket? Materially larger than "one warranty per address" — it is "what counts as an insurable address". The gate fixes are independent of both blockers and can proceed regardless.
+
+## Exact next step
+
+> Create the `TRUE-80487` branch on `_underscore` (base = the dev branch the developer names), then fix `isWholeHomeWarranty()` at `_underscore/Model/Rate/Entitlement.php:116-118` to identify a WH purchase by resolving `saleItem.uuid` → `Items` (with payload `name` / `WH_SALE_ITEM_ID = 3` as fallbacks) **together with** the `state.uuid` → `code` resolution at line 66 — never one without the other, or every WH purchase throws "A valid service address is required". Then run `test/@Mark/Rate/verify_wholehome_per_address_guard.php` rewritten to the real payload shape (uuid-only `saleItem` and `state`), and confirm it FAILS on the current code before the fix and passes after.
+
+---
+_Saved by /session-save on 2026-07-30_

package/package.json

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

package/rules/common/security.md

@@ -4,24 +4,74 @@ These rules are critical. Violations create exploitable vulnerabilities. Follow
 
 ## SQL injection prevention
 
-Never build SQL strings by concatenating or interpolating user input.
+Never build SQL strings by concatenating or interpolating **unescaped** values.
+
+> **Neither framework supports prepared statements.** This rule previously demanded them and
+> gave `_Db::select()` as the correct pattern. **`_Db` does not exist.** Verified 2026-07-30:
+> in 2.0, `_Query` accepts only a raw SQL string and `_Database_Driver` declares no
+> `prepare`/`bind` (neither the Mysql nor the Pgsql driver implements one); 1.0 is the same
+> through `App_Database`. There are zero uses of `bind_param`, `mysqli_stmt`, `PDO::`, or
+> `::prepare(` anywhere in the non-vendor codebase. Escaping **is** the parameterization
+> mechanism here, so that is what this rule requires.
+
+**Prefer the model layer.** `_Model` (2.0) and `App_Model` (1.0) build and escape queries for
+you. Hand-written SQL is the fallback, not the default.
+
+**When you write SQL by hand, every interpolated value must be escaped or cast — no exceptions
+for "internal" or "trusted" sources.**
 
 ```php
 // CRITICAL VIOLATION — never do this
-$sql = "SELECT * FROM users WHERE id = " . $_GET['id'];
-$sql = "SELECT * FROM orders WHERE email = '$email'";
+$sql = "SELECT * FROM Users WHERE id = " . $_GET['id'];
+$sql = "SELECT * FROM Orders WHERE email = '$email'";
+
+// CORRECT (2.0) — cast numerics, escape strings
+$sql = "
+    SELECT *
+    FROM Orders
+    WHERE
+        id = " . ((int) $_GET['id']) . " AND
+        email = '" . _Database::escape($email) . "'
+";
+
+// CORRECT (1.0) — same shape, different helper
+$sql = "
+    SELECT *
+    FROM Orders
+    WHERE
+        id = " . ((int) $_GET['id']) . " AND
+        email = '" . App_Database::sqlEscape($email) . "'
+";
+```
 
-// CORRECT — always use prepared statements
-$stmt = $pdo->prepare('SELECT * FROM users WHERE id = ?');
-$stmt->execute([$_GET['id']]);
+Applies to every operation: SELECT, INSERT, UPDATE, DELETE, and DDL.
+
+**Cast numerics with `(int)`/`(float)`; escape strings.** A cast is sufficient on its own for a
+numeric — there is nothing left to inject once the value is an integer. A string always needs the
+escape helper.
+
+**Identifiers are not covered by escaping.** `_Database::escape()` and
+`App_Database::sqlEscape()` protect *values*, not table names, column names, sort directions, or
+`LIMIT` expressions. Anything used as an identifier must come from a **hardcoded allowlist** —
+never from a request, and never merely escaped.
+
+```php
+// CRITICAL VIOLATION — escaping does not make an identifier safe
+$sql = "SELECT * FROM Orders ORDER BY " . _Database::escape($_GET['sort']);
 
-// CORRECT — framework parameterized query
-_Db::select('orders', ['email' => $email]);
+// CORRECT — allowlist
+$allowedSortColumns = ['dtCreated', 'total', 'status'];
+$sortColumn = in_array($_GET['sort'], $allowedSortColumns, true) ? $_GET['sort'] : 'dtCreated';
+$sql = "SELECT * FROM Orders ORDER BY $sortColumn";
 ```
 
-This applies to every SQL operation: SELECT, INSERT, UPDATE, DELETE, and DDL. No exceptions for "internal" data or "trusted" sources — use parameterized queries everywhere.
+**Enum columns need validating in PHP.** 2.0's `FIELD_LIST` performs no enum validation and
+silently converts a falsy value to SQL `NULL`; MySQL will coerce rather than reject an unknown
+member. Check the value against the allowed set before it reaches the query.
 
-Integer casting (`(int) $_GET['id']`) reduces risk but is not a substitute for prepared statements. Use both.
+One caveat on 2.0's helpers: `_Database::escape()` is the correct one. Do **not** confuse it with
+`_Database::protect()`, which *strips* `% \ / * " '` and the literal ` or` — lossy filtering, not
+escaping, and it will corrupt data you meant to store intact.
 
 ## XSS prevention