toga-ai 1.0.1081 → 1.0.1083

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

@@ -63,8 +63,9 @@
 | [SO↔PO and TO↔PO bridge tables are TWO tables in OPPOSITE directions (upstream vs downstream)](features/sales-order-purchase-order-bridge-direction.md) | The two SO↔PO (and two TO↔PO) bridge tables mean opposite things (upstream = customer PO, downstream = vendor PO); open when an SO/TO↔PO query returns an empty |
 | [Per-client sales-order status filter (Surface FILTER_SET → table meta `filterOptions`)](features/sales-order-status-filter-surface.md) | Per-client status-filter dropdown on the sales-orders table, driven by a Surface `FILTER_SET`; open when the offered statuses are wrong for a tenant or when onb |
 | [Service request links (ServiceRequests_Tickets, ServiceRequests_ServiceRequests bridges)](features/service-request-links.md) | Many-to-many links from a service request to tickets and to other service requests; open before linking SRs, reading `_linkCount`, or touching the old `ServiceR |
+| [2.0 Service Request status (`_status`) is derived; stages are manual-only; standard schedule / crew / location columns](features/service-request-status-and-stages.md) | How a 2.0 service request's `_status` is computed, what stages are for, the standard SR columns, and the set-stage write; open when an SR shows the wrong status |
 | [Shipping Carriers & Carrier Account Numbers (records, matching, duplication, deletion)](features/shipping-carriers-and-accounts.md) | Per-client `ShippingCarriers` / `ShippingCarrierAccountNumbers` model, how the syncs match/create carrier rows, and the duplication + blank-carrier + pagination |
-| [Ticket SLA engine (_Component_Sla) — two clocks, per-stage effects, client switch + operator recompute](features/sla-engine.md) | How 2.0 ticket SLA due times, pauses and the per-client switch are computed and written (`_Component_Sla`); open when an SLA countdown is wrong, a stage does no |
+| [SLA engine (_Component_Sla) — record-generic (tickets + service requests), two clocks, per-stage effects, client switch + operator recompute](features/sla-engine.md) | How 2.0 SLA due times, pauses and the per-client switch are computed and written for tickets AND service requests (`_Component_Sla`); open when an SLA countdown |
 | [_String helpers — ASCII-safe HTML entity encoding (and the parseBetween trap)](features/string-html-entity-helpers.md) | `_String` static string utilities: use `encodeToAsciiHtmlEntities` for any dynamic text going into a 2.0 email; open when escaping email text or parsing substri |
 | [Surface FIELD ↔ RecordField binding (maxLength / validationType / isWritable fold-in)](features/surface-field-recordfield-binding.md) | Resolver capability that folds `Core.RecordFields` input-contract metadata (maxLength/validationType/isWritable) onto a surface FIELD element; open when a 2.5 s |
 | [DECLINED 2026-10-08 — re-key Client.SurfaceOverrides from numeric Core ids to uuids](features/surface-overrides-uuid-rekey.md) | **Decision 2026-10-08 (jcardinal): keep numeric ids; no uuid re-key.** The plan below is not scheduled; see the Layer boundary in [surface-resolver](surface-res |

package/knowledge/2.0/apps/_underscore/features/email-template-sending.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-10-15
+updated: 2026-10-19
 owners: ["jcardinal", "bala", "mhammontree", "apeterson"]
 files:
   - _underscore/Model/Client/EmailTemplate.php
@@ -113,6 +113,7 @@ can keep using `sendEmail($api, ...)`.
 
 ## Gotchas / known issues
 
+- **⚠ `email-templates/sendEmail` is called straight from the public togatech.com bundle** (footer form, contact form, Talos chat lead) as a GET with uuid/to/cc/body in the URL, and it checks no captcha. Anyone can replay it with their own recipients. Open follow-up (2026-10-19): verify reCAPTCHA v3 server-side (actions `footer_form_submit`, `contact_form_submit`, `talos_lead`; hostname `togatech.com`; score ≥ 0.5), pin recipients per template and ignore public `to`/`cc`, rate-limit, prefer POST, and **exempt authenticated service callers**, because Talos sends reminder/scheduled-run emails through it server-to-server. Details: [togatech talos-chat-widget](../../../../standalone/apps/togatech/features/talos-chat-widget.md).
 - **⚠ `replaceTemplateVariables()` does NO escaping — the CALLER must escape.** It is a plain
   `str_replace` per key, and the Send worker transmits with `IsHTML(true)`, so any stored value
   holding a `<` (a site name, a contact name, an address line, a PO number) lands in the delivered
@@ -237,6 +238,7 @@ worker method) in-process instead.
 
 ## Change history
 
+- 2026-10-19 — Recorded the public, unverified togatech.com use of sendEmail and the lockdown follow-up. (akhokhani)
 - 2026-10-15 — Recorded the empty-string `to` + cc gap (queued, fails in worker2). (jcardinal)
 - 2026-10-06 — Noted the 1054 symptom when the email-review migrations are missing in an env (client-sandbox). (bala)
 - 2026-09-23 — Added the review hold (`isReviewRequired` + `REVIEW` addresses → `HELD` real email +

package/knowledge/2.0/apps/_underscore/features/service-request-status-and-stages.md

@@ -0,0 +1,60 @@
+---
+title: 2.0 Service Request status (`_status`) is derived; stages are manual-only; standard schedule / crew / location columns
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-10-19
+owners: [jcardinal]
+files:
+  - _underscore/Model/Client/ServiceRequest.php
+  - _underscore/Model/Client/ServiceRequestNote.php
+  - _underscore/Model/Client/User.php
+  - _underscore/Model/Client/Case.php
+  - _underscore/Model/Prudential/ServiceRequest.php
+  - _underscore/Model/Growrk/ServiceRequest.php
+  - _underscore/Model/Adyen/ServiceRequest.php
+  - _underscore/Model/Elite/ServiceRequest.php
+  - dbchanges2/Core/2026-10-19i - TRUE-82915 ServiceRequestInterceptors.sql
+  - dbchanges2/Client_Prudential/2026-10-19a - TRUE-82915 ServiceRequestStageStatusLinks.sql
+  - dbchanges2/Client_Growrk/2026-10-19a - TRUE-82915 ServiceRequestStageStatusLinks.sql
+related:
+  - ./ticket-status-from-stage.md
+  - ./case-status-and-stage-gate.md
+  - ./sla-engine.md
+  - ./service-request-links.md
+  - ../../api2/features/api-payload-interceptors.md
+---
+
+How a 2.0 service request's `_status` is computed, what stages are for, the standard SR columns, and the set-stage write; open when an SR shows the wrong status, you add a stage, or you add a base SR hook.
+
+## Summary
+
+`_Model_Client_ServiceRequest::_status` is a `FIELD_SQL` calculated field (same idea as Tickets and Cases). Status comes from the SR's own fields; stages hold only manual states that cannot be derived. Full detail: toga25-desk `docs/decisions/0166-sr-status-derived-from-fields-stages-manual-only.md` and `0167-sr-site-schedule-crew-tags-reported-by.md`.
+
+## How it works
+
+`_status` returns, in order:
+1. the linked status slug, when the stage has `serviceRequestStatusId`;
+2. `closed`, when the stage is unlinked and `isOpen = 0`;
+3. `in-progress`, when a Lead (`assignedToContactId`) or crew (`ServiceRequests_Users`) is set;
+4. `scheduled`, when `dtScheduledStart` is set;
+5. else `new`.
+
+- **Stages = manual, non-derivable states only:** blockers (roadblocked / on-hold / awaiting-user / awaiting-parts — each needs a reason note in `ServiceRequestNotes`), pending-client-approval, resolved, closed. No stage is the normal flow.
+- **Per-client stage → status links** go in `Client_<Name>/` files (e.g. `Client_Prudential` / `Client_Growrk` `2026-10-19a`), never a `Client/` fan-out.
+- **Standard columns:** `assignedToContactId` (Lead), `reportedByContactId`, `locationId` (the site — NOT `deliverToAddressId`, which is the shipping address), `isRemote`, `dtScheduledStart` / `dtScheduledEnd` (NOT `dateDelivery`). `ServiceRequestTypes`: `isSiteVisit`, `iconName`, `colorHex`. Bridges `ServiceRequests_Users` (crew), `_Tags`, `_Files` (Core.Records 422-424, RecordFields 3106-3152).
+- **Set stage** = table-based `PUT /v2/service-requests/{uuid}` with nested `serviceRequestNotes` (the reason note). A stage PUT without a uuid = 400 for signed-in users (CSO).
+- **Crew "required"** is a UI rule only — integration-created SRs send no crew.
+- **Base hooks** (`prePost` / `postPost` / `postPut` / `postPatch`) are registered for every client by `Core/2026-10-19i` (`clientId` / `apiId` NULL). They run the schedule check, the set-stage gate, and the [SLA engine](./sla-engine.md).
+
+## Gotchas
+
+- **⚠ Never delete or rename existing stage rows.** Client integrations match stage NAMES: Prudential `postPut` ('Cancelled' / 'Update'), Growrk ('Completed'), worker 1.0 cron ('Exception' + stage id 2).
+- **⚠ A client SR override must call `parent::` in every hook it overrides.** Before 2026-10-19 the Prudential / Growrk / Adyen / Elite `ServiceRequest` overrides did not, so every base SR hook was silently skipped for those clients. Adding a base hook? Check each `_Model_<Client>_ServiceRequest` calls `parent::` first (and that the parent declares the method — see [interceptors](../../api2/features/api-payload-interceptors.md#the-client-model-resolution-that-decides-which-class-must-define-the-method)).
+- **⚠ A NULL stage is now the normal case — never INNER JOIN the SR stage.** `User::_openWorkCount` and `Case::_resolvedCount` used INNER JOIN on stage + `isOpen` and dropped stageless SRs. Rule: open = no stage OR stage `isOpen = 1`; open work counts the SR's own crew.
+
+## Change history
+- 2026-10-19 — `_status` derived from fields; stages manual-only; schedule / crew / location / reported-by columns; client overrides call `parent::`; open counts include stageless SRs (TRUE-82915). (jcardinal)

package/knowledge/2.0/apps/_underscore/features/sla-engine.md

@@ -1,65 +1,76 @@
 ---
-title: Ticket SLA engine (_Component_Sla) — two clocks, per-stage effects, client switch + operator recompute
+title: SLA engine (_Component_Sla) — record-generic (tickets + service requests), two clocks, per-stage effects, client switch + operator recompute
 framework: "2.0"
 repo: _underscore
 project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-10-16
+updated: 2026-10-19
 owners: [jcardinal]
 files:
   - _underscore/Component/Sla/Sla.php
   - _underscore/Model/Client/Ticket.php
   - _underscore/Model/Client/TicketStage.php
   - _underscore/Model/Client/TicketNote.php
+  - _underscore/Model/Client/ServiceRequest.php
+  - _underscore/Model/Client/ServiceRequestNote.php
   - _underscore/Model/Core/Client.php
   - dbchanges2/Core/2026-10-16a - SlaReplyClockCore.sql
   - dbchanges2/Client/2026-10-16a - SlaReplyClockFanout.sql
   - dbchanges2/Client_True/2026-10-16a - SlaStageDataRepair.sql
-  - dbchanges2/Client_Elite/2026-10-16a - SlaReplyClockOpenStage.sql
+  - dbchanges2/Core/2026-10-19k - TRUE-82915 ServiceRequestSlaCore.sql
+  - dbchanges2/Client/2026-10-19i - TRUE-82915 ServiceRequestSla.sql
 related:
   - ./ticket-status-from-stage.md
+  - ./service-request-status-and-stages.md
   - ../../api2/features/api-payload-interceptors.md
   - ../../api2/features/tickets-api.md
   - ../../dbchanges2/features/rerunnable-additive-inserts.md
 ---
 
-How 2.0 ticket SLA due times, pauses and the per-client switch are computed and written (`_Component_Sla`); open when an SLA countdown is wrong, a stage does not pause, or you need to recompute a client.
+How 2.0 SLA due times, pauses and the per-client switch are computed and written for tickets AND service requests (`_Component_Sla`); open when an SLA countdown is wrong, a stage does not pause, you need to recompute a client, or you want SLA on another record type.
 
 ## Summary
 
-`_Component_Sla` (`_underscore/Component/Sla/Sla.php`) is the ONLY code that writes `Tickets.sla*` / `dtSla*` / `dtFirstResponse`. It is static, shared by every 2.0 app, and called from api2 payload interceptors (not model save hooks). Two clocks — resolution and reply (first response) — each with its own pause bookkeeping, driven by per-stage effects stored as client data.
+`_Component_Sla` (`_underscore/Component/Sla/Sla.php`) is the ONLY code that writes the stored SLA columns (`sla*` / `dtSla*` / `dtFirstResponse`). One engine, record-generic: every record-specific name comes from `_Component_Sla::descriptor($record)`. Static, shared by every 2.0 app, called from api2 payload interceptors (not model save hooks). Two clocks — resolution and reply (first response) — each with its own pause bookkeeping, driven by per-stage effects stored as client data.
 
 ## How it works
 
-- **Targets:** `TicketSlas (ticketTypeId, urgencyId)` → minutes (MINUTES ×1, HOURS ×60, DAYS ×1440). Any other unit (e.g. `BUSINESS_DAYS`) = no target. No business-day math.
+- **Descriptor:** `descriptor(RECORD_TICKET | RECORD_SERVICE_REQUEST)` (`'ticket'` / `'serviceRequest'`) returns `record, label, table, typeColumn, stageColumn, contactColumn, targetsTable, stagesTable, hasReplyEffectColumn, notesTable, noteRecordColumn, noteStageColumn, noteAuthorUserColumn`. `allRecordTypes()` = what the client switch and recompute cover. **New record type = a new descriptor + the same columns — never a copy of the engine** (decided, CTO). Detail: toga25-desk `docs/decisions/0168-sla-engine-record-generic.md`.
+- **Tickets (descriptor 1):** `TicketSlas`, `TicketStages.slaEffect` + `slaFirstResponseEffect`, `TicketNotes`, contact = `contactId`. Moving tickets onto the descriptor changed nothing (275-scenario old-vs-new harness and a live recompute replay: 0 diffs).
+- **Service requests (descriptor 2):** same 9 stored SLA columns + 11 calc fields on `ServiceRequests`; targets `ServiceRequestSlas`; effect `ServiceRequestStages.slaEffect`. No reply-effect column (`hasReplyEffectColumn = false`) — the reply clock follows `slaEffect`. Contact = `requestedForContactId`. First response = first external note with a signed-in author (`authorUserId`) OR a contact other than the requester.
+- **Targets:** `(typeColumn, urgencyId)` → minutes (MINUTES ×1, HOURS ×60, DAYS ×1440). Any other unit (e.g. `BUSINESS_DAYS`) = no target. No business-day math.
 - **Due:** `dtCreated + targetMinutes + pausedMinutes`, per clock.
-- **Resolution clock:** effect = `TicketStages.slaEffect` (`RUN`/`PAUSE`/`STOP`, no stage = RUN). Columns `dtSlaPaused`, `slaPausedMinutes`. STOP time is charged like pause time; `_slaState` shows `STOPPED`.
-- **Reply clock:** effect = `TicketStages.slaFirstResponseEffect` (`RUN`/`PAUSE`, column default `PAUSE`, no stage = RUN). Columns `dtSlaFirstResponsePaused`, `slaFirstResponsePausedMinutes`. Seeded RUN only for new / open / reopened stages. Keeps tracking after the first response so stamps stay right.
-- **`resolvePauseState(params)`** is clock-agnostic and called once per clock. Reuse it for the Service Request SLA clocks — do not fork the math.
-- **First response** = `MIN(TicketNotes.dtStamp)` of external notes by a contact other than the ticket's own contact. Authorless notes never count.
-- **Read side:** `_slaTime`, `_slaState`, `_slaPausedAt` (FIELD_SQL on `_Model_Client_Ticket`). `_slaPausedAt` returns the paused stamp of the clock being shown (reply while unanswered and a reply due exists, else resolution). The Desk countdown reads it, not the raw columns.
+- **Resolution clock:** stage `slaEffect` (`RUN`/`PAUSE`/`STOP`, no stage = RUN). Columns `dtSlaPaused`, `slaPausedMinutes`. STOP time is charged like pause time; `_slaState` shows `STOPPED`.
+- **Reply clock (tickets):** `TicketStages.slaFirstResponseEffect` (`RUN`/`PAUSE`, column default `PAUSE`, no stage = RUN). Columns `dtSlaFirstResponsePaused`, `slaFirstResponsePausedMinutes`. Seeded RUN only for new / open / reopened stages. Keeps tracking after the first response so stamps stay right.
+- **`resolvePauseState(params)`** is clock-agnostic, called once per clock. Do not fork the math.
+- **Ticket first response** = `MIN(TicketNotes.dtStamp)` of external notes by a contact other than the ticket's own contact. Authorless notes never count.
+- **Read side:** `_slaTime`, `_slaState`, `_slaPausedAt` (FIELD_SQL on the record model). `_slaPausedAt` returns the paused stamp of the clock being shown (reply while unanswered and a reply due exists, else resolution). UIs read it, not the raw columns.
 - **Time = DB clock** (`SELECT NOW()` on the client writer), read once, then advanced by PHP elapsed time.
-- **Client switch:** `Core.Clients.isSlaEnabled`. OFF = every SLA column NULL. Flipping it in `PUT /v2/clients/{uuid}` runs `applyClientSwitch` (backfill, skips STOP-stage tickets when turning on).
-- **Operator recompute (no OFF/ON):** `PUT /v2/clients/{uuid}` body `{"recomputeSla": true}`. `_Model_Core_Client::prePut` strips the key (not a column), requires boolean `true`, parks it on `$api->passThrough`; `postPut` runs `recomputeClient` (all tickets, STOP included). Allowed only for callers who can WRITE `Clients.isSlaEnabled` (same field ACL as the V2 write gate). A body that is empty after the strip becomes `{}` in V2.php and `postPut` still runs. Pattern: [command keys in interceptors](../../api2/features/api-payload-interceptors.md#passing-state-from-a-pre-hook-to-a-post-hook).
-- **One run per client:** the shared backfill takes `GET_LOCK('sla-recompute-<clientId>', 0)` on the SAME connection as its writes, `RELEASE_LOCK` in `finally`. Lock busy → `_Exception_Validation` 400. Any failure throws, so the API write rolls back. Reuse this shape for any "only one at a time per client" operation.
-- **Cross-client:** the switch/recompute path uses `DB_TARGET_CLIENT` (`registerTargetClientDatabase`), never the caller's `DB_CLIENT`. Core and client data are never joined.
+- **Client switch:** `Core.Clients.isSlaEnabled` covers every record type. OFF = every SLA column NULL. Flipping it in `PUT /v2/clients/{uuid}` runs `applyClientSwitch` (backfill, skips STOP-stage records when turning on).
+- **Operator recompute (no OFF/ON):** `PUT /v2/clients/{uuid}` body `{"recomputeSla": true}` — all record types. `_Model_Core_Client::prePut` strips the key (not a column), requires boolean `true`, parks it on `$api->passThrough`; `postPut` runs `recomputeClient` (STOP included). Allowed only for callers who can WRITE `Clients.isSlaEnabled`. A body empty after the strip becomes `{}` in V2.php and `postPut` still runs. Pattern: [command keys in interceptors](../../api2/features/api-payload-interceptors.md#passing-state-from-a-pre-hook-to-a-post-hook).
+- **One run per client:** the backfill takes `GET_LOCK('sla-recompute-<clientId>', 0)` on the SAME connection as its writes, `RELEASE_LOCK` in `finally`. Lock busy → `_Exception_Validation` 400. Any failure throws, so the API write rolls back. Reuse this shape for any "one at a time per client" operation.
+- **Cross-client:** switch/recompute use `DB_TARGET_CLIENT` (`registerTargetClientDatabase`), never the caller's `DB_CLIENT`. Core and client data are never joined.
 
 ## Gotchas
 
-- **⚠ A stage that "never pauses" is usually data, not code.** Check `TicketStages.slaEffect` / `slaFirstResponseEffect` per stage in that environment first. QA alpha `Client_True` (2026-10-16): every stage stayed RUN because the `Client/2026-09-29d` seed matched by slug before the slugs existed; fixed by `Client_True/2026-10-16a - SlaStageDataRepair.sql`. See [fan-out seed keyed on a slug](../../dbchanges2/features/rerunnable-additive-inserts.md#gotchas).
+- **⚠ A stage that "never pauses" is usually data, not code.** Check the stage table's `slaEffect` (and `slaFirstResponseEffect` for tickets) in that environment first. QA alpha `Client_True` (2026-10-16): every ticket stage stayed RUN because the `Client/2026-09-29d` seed matched by slug before the slugs existed; fixed by `Client_True/2026-10-16a - SlaStageDataRepair.sql`. See [fan-out seed keyed on a slug](../../dbchanges2/features/rerunnable-additive-inserts.md#gotchas).
+- **⚠ Writes that skip api2 skip the SLA.** worker 1.0 Prudential crons set `ServiceRequests.serviceRequestStageId = 2` by direct SQL — no pause is recorded until the next api2 write or a recompute. Accepted gap.
+- **⚠ Full recompute resets accrued paused minutes on records no longer paused** (both engines, pre-existing). Know this before running `recomputeSla` on a client with long past pauses.
 - **⚠ The lock is released before api2 commits.** A second recompute started right after can overlap the first's uncommitted writes. Accepted (operator-only, rare) — do not copy this gap into a high-traffic operation; hold the lock past commit there.
-- **No worker job for big clients** (decided). The recompute runs inside the request, so a very large client can hit the 300 s request cap. Paged at 500 tickets.
-- **`FIELD_LIST` does not validate ENUMs** — `TicketStage::save()` checks both effects explicitly. Keep that check when adding a value.
-- **Changing a stage's effect does not move existing tickets** until their next write or a recompute. Run `{"recomputeSla": true}` after a stage-effect data fix.
+- **No worker job for big clients** (decided). Recompute runs inside the request; a very large client can hit the 300 s request cap. Paged at 500 records.
+- **`FIELD_LIST` does not validate ENUMs** — `TicketStage::save()` checks both effects explicitly. Keep that check (and add it on any new stage model) when adding a value.
+- **Changing a stage's effect does not move existing records** until their next write or a recompute. Run `{"recomputeSla": true}` after a stage-effect data fix.
 
 ## Related
 
 - [Ticket status from stage](./ticket-status-from-stage.md)
+- [Service request status and stages](./service-request-status-and-stages.md)
 - [API payload interceptors](../../api2/features/api-payload-interceptors.md)
 - [Tickets API](../../api2/features/tickets-api.md)
 - [Re-runnable additive migrations](../../dbchanges2/features/rerunnable-additive-inserts.md)
 
 ## Change history
+- 2026-10-19 — Engine made record-generic via `descriptor()`; service requests are descriptor 2 (same columns, `ServiceRequestSlas`, reply clock follows `slaEffect`); tickets unchanged (0 diffs) (TRUE-82915). (jcardinal)
 - 2026-10-16 — Reply clock gets its own per-stage effect (`slaFirstResponseEffect`, pauses outside new/open/reopened); operator recompute via `{"recomputeSla": true}`; per-client named lock (TRUE-82849). (jcardinal)

package/knowledge/2.0/apps/api2/features/api-payload-interceptors.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-10-18
+updated: 2026-10-19
 owners: ["mhammontree", "dfranks", "bala", "snaredla", "jcardinal", "rgirish"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -50,6 +50,7 @@ related:
   - ./language-translation-layer.md
   - ../../_underscore/features/persona-nav-visibility-gate.md
   - ../../../clients/compass-usa/features/approval-decision-flow.md
+  - ../../_underscore/features/service-request-status-and-stages.md
 ---
 
 How `_Model` prePost/postPost/prePut/postPut hooks are dispatched by the api2 /v2 engine only when a metadata row exists — the missing-row silent no-op, the wrong-row hard fatal, and the persistence/transaction traps; open before writing, activating, or debugging any interceptor.
@@ -343,7 +344,8 @@ Refuse API-key callers when the rule is "the signed-in user" (no user on the tok
 - **⚠ Client behaviour never goes on `_Model_Client_X`.** Every tenant with a row for that record inherits it through `parent::` calls. Put it on `_Model_<Client>_X`.
 - **⚠ An own-row PRE guard that checks only `userId` is bypassable** — alias keys (`user`) map after PRE, and a parent-route POST overwrites the stamped FK. Allowlist keys + refuse parent routes. See [own-row guards](#own-row-guards-in-a-pre-interceptor).
 - **A client's rows may be in `Core` (with `clientId`), not in `Client_<X>`** — check both before concluding a client has no interceptors.
-- **⚠ The same hook in BOTH `Core` (with `clientId`) and `Client_<X>` fires TWICE** — both tables are read, nothing dedupes. Adyen (2026-10-08): Core ids 15–17 duplicated client rows 1, 2, 5 → double worker jobs and double NetSuite queueing; fixed by deactivating the Core rows. Keep each `(record, phase, method)` in one table only. See [Adyen reclaim flow](../../../clients/adyen/features/service-request-salesorder-netsuite.md#gotchas).
+- **Duplicate rows are de-duplicated (since 2026-10-19, TRUE-82915).** `registerApiPayloadInterceptorLookupEntry` (`V2.php`) keeps ONE entry per `(record, PRE|POST, httpMethod)` across Core and client tables; the highest `minDepth` wins (NULL lowest). So a generic row (`clientId` / `apiId` NULL) plus a client's own row dispatches once. Before this, both fired (Adyen 2026-10-08: double worker jobs; Elite / Adyen SR `postPost` → double sales-order tasks). **Rollback order:** deactivate generic rows that overlap client rows BEFORE rolling api2 back, or the double dispatch returns. Pre-release check query: header of `dbchanges2/Core/2026-10-19i - TRUE-82915 ServiceRequestInterceptors.sql`. Still keep each key in one table.
+- **⚠ A client override that skips `parent::` silently disables every base hook for that client.** Found 2026-10-19 on four `ServiceRequest` overrides — see [SR status and stages](../../_underscore/features/service-request-status-and-stages.md#gotchas). Adding a base hook = check every client subclass calls `parent::`.
 - **The method name is derived, so a typo'd enum silently misses.** A row with `prePostProcessing = 'PRE'`, `httpMethod = 'PUT'` resolves to `prePut`, not `prePost`; the engine finds no method and moves on.
 - **Registration is per-environment.** Like `RecordFields` / `RecordScripts` / ACL rows, this is metadata — "works in prod, not in beta/dev-sandbox" is the signature of drift, not of a bad deploy. See the [non-prod metadata drift repair workflow](../../dbchanges2/workflows/nonprod-metadata-drift-repair.md).
 - **⚠ An in-request read-after-write in an interceptor works on beta and fails 100% in production.** Reads default to the **reader** connection, which cannot see the request's own uncommitted row; dev-sandbox points writer and reader at the same endpoint, so it hides the bug. Pin with `setIsReadHostEnabled(false)` (restore in `finally`).
@@ -368,6 +370,7 @@ Refuse API-key callers when the rule is "the signed-in user" (no user on the tok
 - [Email template sending](../../_underscore/features/email-template-sending.md)
 - [Elite SalesOrder → NetSuite push](../../../clients/elite/features/salesorder-netsuite-push.md)
 - [Compass sales-order line renumbering](../../../clients/compass-usa/features/sales-order-line-renumbering.md)
+- [Service request status and stages](../../_underscore/features/service-request-status-and-stages.md)
 
 ## Change history
 - 2026-10-08 — `internalApiRequest` "[]" throw also fires on the OUTER request's warnings (e.g. WO-1); throw site now ~L2436; Core + client duplicate rows fire twice. (rgirish)
@@ -376,3 +379,4 @@ Refuse API-key callers when the rule is "the signed-in user" (no user on the tok
 - 2026-10-16 — Command keys: strip in `prePut`, park on `passThrough`, act in `postPut`; empty body → `{}` (TRUE-82849). (jcardinal)
 - 2026-10-18 — Write intent that writes another record via internal request (caller ACL, rollback, `addNote` after the call) (TRUE-82876). (jcardinal)
 - 2026-10-17 — "Action table" pattern for audited actions; write intents before a stage gate; new interceptor rows ship in a file run after the code deploy (TRUE-82889). (jcardinal)
+- 2026-10-19 — Lookup de-duplicates rows per record / PRE|POST / method (highest `minDepth` wins); client overrides must call `parent::` (TRUE-82915). (jcardinal)

package/knowledge/2.0/apps/api2/features/v2-rest-query-contract.md

@@ -49,7 +49,9 @@ controller.
 `fields`, `where`, `join` / `ojoin`, `sort`, `group`, `distinct`, `page`, `recordsPerPage`,
 `depth`, `calcDepth` (or one base64(JSON) `_` blob).
 
-- **Pagination is `page` + `recordsPerPage`. There is no `limit`/`offset`.** Defaults:
+- **Pagination is `page` + `recordsPerPage`. There is no `limit`/`offset`.** A `limit=5` on a
+  list GET is not ignored — it returns **404 `EV-14`** "Expecting one record ... multiple records
+  were found". Defaults:
   `recordsPerPage` **25**, `depth` **3**. Max `recordsPerPage` **10000** — exceeding it returns
   **`EV-13`** (HTTP 400).
 - **Sort:** `-field` = DESC, `+field` = ASC, bare `field` = ASC. All three are handled
@@ -656,6 +658,7 @@ If you need the behaviour, loop uuids client-side. Point 3 is the durable, non-o
   [V2 request logging](request-logging.md).
 
 ## Change history
+- 2026-10-19 — `limit` on a list GET = 404 `EV-14`, use `recordsPerPage` (TRUE-82915). (jcardinal)
 - 2026-10-19 — Self-join `where` needs an `ojoin` alias (`Locations@p`); `_` field ACL bypass does not apply cross-client (TRUE-82911). (jcardinal)
 - 2026-10-18 — Grouped queries: stored root group key now selected + ACL-gated; known gaps (joined key, total count, `ORDER BY uuid` under ONLY_FULL_GROUP_BY) (TRUE-82876). (jcardinal)
 - 2026-10-17 — Child-path `where` must start at an inherent child; FK-first path → TableView join alias (TRUE-82872). (jcardinal)
@@ -667,7 +670,6 @@ If you need the behaviour, loop uuids client-side. Point 3 is the durable, non-o
 - 2026-09-18 — `in` instead of an OR-chain of `contains` shortens SQL only, not speed. (apeterson)
 - 2026-09-17 — Bulk DELETE by `where`: exists, unused, unsafe; zero matches looks like an ACL denial. (rgirish)
 - 2026-09-14 — `where` on a calculated field works with the bare name; `calcDepth` does not gate a named calc field; list GET cost model. (apeterson)
-- 2026-09-08 — `depth` read-back cost (~830s at `depth=5` on a write). (jcardinal)
 - 2026-09-04 — URL-encoded `where` → 500/`EO-1` (`Logs.Issue` 97). (rgirish)
 - 2026-09-01/02 — `_` field in `fields=` is never ACL-checked; inherent-child keys govern writes; bridge `InherentRecordChildren` rows. (apeterson, bala)
 - 2026-07-29 → 08-30 — Created; then: `fields=` does not narrow SELECT, `depth` races deletes, sort `+`/DISTINCT, uuid-READ ignores `where`, joins drive filter not shape, `calcDepth` default 1, FK omitted at max depth, PUT echo can omit fields. (tcox, bala, apeterson, jcardinal)

package/knowledge/2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-10-17
+updated: 2026-10-19
 owners: [bala, kyalamarthi, apeterson, ajean, jcardinal, rgirish]
 files:
   - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
@@ -491,6 +491,7 @@ an INSERT that names only `uuid`/`tableViewId`/`recordFieldId`/`isVisible`/`inde
 - **⚠ `NOT NULL DEFAULT <value>` does not save a `_Model` column** — the ORM writes an explicit NULL,
   which skips the DEFAULT and errors 1048. Ship a model default with the ALTER.
 - **⚠ `col = 0` never matches a NULL** — guard flag-enabling UPDATEs with `COALESCE(col, 0) = 0`, or the migration reports success and changes nothing.
+- **⚠ A `WHERE col <> 'New text'` guard SKIPS a case-only change on a `_ci` column.** `'service request' <> 'Service Request'` is FALSE under `utf8mb4_general_ci`, so the copy UPDATE runs and changes nothing. Guard copy updates with `BINARY col <> 'New text'`. Bug `Core/2026-10-19j`; fixed in `Core/2026-10-19n`..`p` (TRUE-82915).
 - **⚠ An unguarded ACL grant migration duplicates silently — `AclRecordPermissions` has no unique key
   that stops it (found in prod 2026-09-15).** `_modules/netsuite/2026-09-11c - ItemClassRecordPermission.sql`
   is a plain `INSERT … VALUES` for `(recordId 105, roleId 3)` with **no `NOT EXISTS` guard**. Every
@@ -560,6 +561,7 @@ an INSERT that names only `uuid`/`tableViewId`/`recordFieldId`/`isVisible`/`inde
   [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
 ## Change history
+- 2026-10-19 — `<>` copy-update guard skips a case-only change on a `_ci` column; use `BINARY` (TRUE-82915). (jcardinal)
 - 2026-10-17 — `TicketTypes.code` has no UNIQUE and may hold duplicates; guard seeds on `code` (TRUE-82889). (jcardinal)
 - 2026-10-16 — Backfill an api2-identifier column before the deploy (seed file), stragglers + ALTER after (TRUE-82841). (jcardinal)
 - 2026-10-16 — NOT NULL alternative for big tables: strict session + `ALGORITHM=INPLACE, LOCK=NONE`

package/knowledge/INDEX.md

@@ -21,7 +21,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 110 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 111 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 91 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 27 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 22 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
@@ -39,10 +39,10 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## standalone framework
 
-- **togatech** (TOGA Technology Website) — 10 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
+- **togatech** (TOGA Technology Website) — 11 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
 - **websocket** (WebSocket Server) — 2 doc(s) → [standalone/apps/websocket/INDEX.md](standalone/apps/websocket/INDEX.md)
 - **talos** (TOGa Talos Chat) — 3 doc(s) → [standalone/apps/talos/INDEX.md](standalone/apps/talos/INDEX.md)
-- **talos-backend** (TOGa Talos) — 32 doc(s) → [standalone/apps/talos-backend/INDEX.md](standalone/apps/talos-backend/INDEX.md)
+- **talos-backend** (TOGa Talos) — 33 doc(s) → [standalone/apps/talos-backend/INDEX.md](standalone/apps/talos-backend/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 6 doc(s) → [standalone/apps/voice-to-voice/INDEX.md](standalone/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 5 doc(s) → [standalone/apps/ai-bdr/INDEX.md](standalone/apps/ai-bdr/INDEX.md)
 - **forward** (Forwarder) — 3 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)

package/knowledge/standalone/apps/bdr/features/landing-chat-drawer.md

@@ -6,7 +6,7 @@ project: BDR
 client: shared
 type: feature
 status: active
-updated: 2026-10-07
+updated: 2026-10-19
 owners: [tcox, akhokhani]
 files:
   - bdr/src/components/TalosDrawer.tsx
@@ -110,6 +110,7 @@ The `.chatveil` / `.chatpanel` block was ported from the security mockup's `styl
 - **The drawer runs on a LINKED blox checkout — it is not deployable.** `node_modules/@agilant/toga-blox` is a junction to the local `toga-blox-npm` working tree on an **unmerged, unpublished** branch. A build on any other machine (or Amplify) has no Talos. Do not treat a green local `next build` as evidence the sandbox will build.
 - **A portaled panel does not inherit `.security-shell`.** See *Styling* — theme values must be literals inside `TalosDrawer`, and anything that needs `security.css` rules has to sit inside a `.security-shell` wrapper with `display: contents`.
 - **`api.togaiq.com` chat endpoints are origin/UA-gated — verified 2026-08-25 with browser-shaped `curl` probes:** from origin `http://localhost:3000` the whole flow works end-to-end (token minted, real Sonnet reply with `suggestions`/`cta`/`cited_slides`), so **local dev gets live answers**. From origin `https://bdr.dev.sandbox.togatech.com` the session mint returns **`403 Forbidden`** — the sandbox origin is **not allowlisted**, so the deployed drawer silently answers from the scripted fallback and looks like it works. The eventual production domain will need the same. **Fix = the Talos backend owner adds the origin to the talos-chat allowlist (aegra-api); no BDR change.** CORS is not the problem (preflight returns `access-control-allow-origin: *` with `authorization,content-type` allowed; one 502 on a preflight was transient). Diagnose from the browser console: `talos-chat unavailable, using scripted fallback: session mint failed: 403` = origin not allowlisted; `...: Failed to fetch` = a CORS/preflight failure. Check for suggestion chips before concluding the backend is live.
+- **`talos-session` now checks a reCAPTCHA v3 token** (2026-10-19, see [talos-backend website-chat-security](../../talos-backend/features/website-chat-security.md)). The drawer sends none, so in an env set to `TALOS_CHAT_RECAPTCHA_MODE=enforce` (beta today; prod is `monitor`) the mint returns 403 `missing_token` and the drawer silently falls back to scripted answers. Its domain must also be a `togatech.com` host to pass the hostname check.
 - **Do not "fix" the transcript by sending the visible message list.** The greeting and any merged/trimmed turns would break the strict alternating shape and return a 422.
 - **The chat is fully client-side**, which is why `/landing` still builds as a **prerendered static** route. Adding a server call here changes that.
 - **`/landing` is not rate-limited** (`src/proxy.ts` matches `/` and the API routes, not the page). The drawer talks to a third-party origin, not a BDR API route, so the limiter still does not apply to *chat* — but the abuse surface exists on the page. The drawer's new "Call me now" action does hit a BDR route, and that one **is** limited (`/api/landing-call`, on the `/api/call-now` bucket).
@@ -125,4 +126,5 @@ The `.chatveil` / `.chatpanel` block was ported from the security mockup's `styl
 
 ## Change history
 
+- 2026-10-19 — noted the reCAPTCHA v3 requirement on talos-session (akhokhani)
 - 2026-10-07 — moved to standalone/bdr (framework axis per CONVENTIONS) (akhokhani)

package/knowledge/standalone/apps/talos-backend/INDEX.md

@@ -24,6 +24,7 @@
 | [Tenant configuration — control plane, assistants, personas, system_config](features/tenant-configuration.md) | Where every piece of per-tenant and per-assistant Talos configuration lives (control plane, assistant rows, personas, junction tables, system_config, prompt tem |
 | [TOGa Platform MCP — user-authorized TOGa Supply and Commerce reads over api2](features/toga-platform-mcp.md) | The MCP server that lets the Talos `toga-supply` assistant read TOGa Supply (and, when approved, TOGa Commerce) data as the signed-in user, with api2 enforcing |
 | [Usage dashboard API (/api/usage) and the usage cache jobs](features/usage-dashboard-api.md) | The server-to-server usage analytics API behind the TOGA tools admin usage dashboard (engagement, tokens, cost, Excel exports) and the out-of-process jobs that |
+| [Website chat security — reCAPTCHA v3 session mint, replay guard, one lead per session, rate limits](features/website-chat-security.md) | Abuse controls on the public website chat (`POST /api/ai/talos-session` → `POST /api/ai/talos-chat`): Google reCAPTCHA v3 on session mint, token replay guard, o |
 | [Authoring a BLP — write, lint, upload, bind and verify a Business Logic Protocol file](workflows/authoring-a-blp.md) | The complete guide to writing a Talos BLP file that the parser, the API and the Deep Agent actually honor, then uploading, binding and verifying it; open whenev |
 | [Debugging agent behavior — symptom → cause → fix cookbook for the Deep Agent](workflows/debugging-agent-behavior.md) | How to find out why the Talos Deep Agent answered wrongly, ignored the knowledge base or business logic, lost tools, looped, froze or failed a run, with a sympt |
 | [Debugging Talos in production with Claude Code and the AWS CLI](workflows/debugging-production.md) | Read-only triage procedure for a broken Talos environment (API down, runs stuck, deploy stuck, errors for one client) using Claude Code with the AWS CLI; open w |

package/knowledge/standalone/apps/talos-backend/features/ai-service-endpoints.md

@@ -6,7 +6,7 @@ project: TOGa Talos
 client: shared
 type: feature
 status: active
-updated: 2026-10-08
+updated: 2026-10-19
 owners: [akhokhani]
 files:
   - talos-backend/libs/aegra-api/src/aegra_api/api/ai_generate.py
@@ -23,6 +23,7 @@ related:
   - auth-and-access-control.md
   - client-integration-contract.md
   - bedrock-models-and-cost-attribution.md
+  - website-chat-security.md
   - ../../../../2.0/apps/_underscore/features/togaiq-gateway-client.md
   - ../../../../2.0/apps/worker2/features/clickup-task-fluffer-talos.md
   - ../../togatech/features/talos-product-page.md
@@ -44,7 +45,7 @@ Besides the Agent Protocol chat surface, Talos exposes service endpoints under `
 | `POST /api/ai/agent` | `X-API-Key` with the assistant slug in `allowed_model_slugs` (fail-closed 403) | Runs the **full Deep Agent graph** for `assistant_slug` with `messages`, optional `thread_id`, `tool_categories`; `stream:true` → SSE, otherwise sync with a 300 s timeout (504 "Agent run did not complete before the timeout"); `format` = `json` (default) / `markdown` / `text` for the sync response | worker2 `Worker/Clickup/Fluffer.php` (ClickUp task "fluffer", `stream:false`, runs of 3–4 min); config in worker2 `Config/*.ini` |
 | `POST /api/ai/chat` | `X-API-Key` | Direct Bedrock Converse chat with a caller-supplied model (tenant AIP enforced), no tools, no graph | No live caller found (2026-10-07); a stale Cypress env in `togatech` references it |
 | `POST /api/ai/talos-session` | Public, browser-gated | Mints an HS256 session JWT (`TALOS_CHAT_JWT_SECRET`, TTL `TALOS_CHAT_SESSION_TTL_SECONDS` 900 s) bound to IP, UA and a client `fingerprint` | togatech.com website widget (`togatech` `src/lib/talosSession.ts`), BDR landing chat drawer |
-| `POST /api/ai/talos-chat` | `Bearer <session JWT>` + browser gate | Direct Bedrock reply (`TALOS_CHAT_MODEL` = Sonnet 4.6, billed to `TALOS_CHAT_ORG_ID` = `True`), returns `message` plus structured `data` (suggestion chips, CTA, cited slides, lead signal). Optional `campaign_id` grounds the answer in that campaign's collateral. Redis rate limits per IP, per fingerprint and global (`TALOS_CHAT_GLOBAL_MAX_PER_MIN/DAY`) — see Gotchas | togatech.com, BDR landing pages |
+| `POST /api/ai/talos-chat` | `Bearer <session JWT>` + browser gate | Direct Bedrock reply (`TALOS_CHAT_MODEL` = Sonnet 4.6, billed to `TALOS_CHAT_ORG_ID` = `True`), returns `message` plus structured `data` (suggestion chips, CTA, cited slides, lead signal). Optional `campaign_id` grounds the answer in that campaign's collateral. Redis rate limits per IP, per fingerprint and global (`TALOS_CHAT_GLOBAL_MAX_PER_MIN/DAY`); reCAPTCHA, replay and lead rules in [website-chat-security](website-chat-security.md) | togatech.com, BDR landing pages |
 | `POST /api/ai/campaigns` | User or API key with `campaign:manage` | Ingests a campaign deck (PDF/images) into `campaigns`, `campaign_documents`, `campaign_document_pages` and registers it in control-plane `campaign_registry` (so a public `campaign_id` resolves its tenant) | Operators/scripts (`scripts/create_campaign_api_key.py`, `scripts/seed_campaign.py`); API key `campaign-seed` in `True` |
 | `GET /api/ai/campaign/{campaign_id}` | Same browser gate as talos-chat | Returns the deck for display (no LLM) | BDR landing pages |
 
@@ -59,13 +60,14 @@ Every talos-session/talos-chat/campaign-read request must have: an `Origin` matc
 - `/api/ai/agent` sync calls hold the HTTP request up to 300 s; callers need longer client timeouts than that, or use `stream:true`.
 - `/api/ai/generate` is admission-limited per tenant; bursts from a worker2 batch see 429s — honor `Retry-After`.
 - Repo `docs/talos-chat-campaign-context.md` describes a `campaign_context` request field that no longer exists; the current field is `campaign_id`.
-- **Per-IP and per-fingerprint limits are effectively disabled** (2026-10-07): the code carries "TEMP firefight: lifted" thresholds of 100,000/min and 10,000,000/day instead of the documented 5/min-30/day (sessions) and 10/min-30/min-100/day (chat), and prod sets the global budget to 100,000/min and 100,000,000/day. The intended fix is a correct `TALOS_CHAT_TRUSTED_PROXY_COUNT` plus configurable limits; until then cost protection rests on the origin gate.
+- **Per-IP limits are still effectively lifted** in prod/beta (2026-10-19): `TALOS_CHAT_TRUSTED_PROXY_COUNT` is unset behind EB nginx + ALB, so all visitors share one peer IP. Limits are now settings and globals are back to 300/min, 10,000/day; reCAPTCHA v3 on session mint, the replay guard and one-lead-per-session live in [website-chat-security](website-chat-security.md).
 - A blocked website origin fails silently in the BDR drawer (it falls back to scripted answers); look for "session mint failed: 403" in the browser console.
 
 ## Related
-- [auth-and-access-control](auth-and-access-control.md) · [client-integration-contract](client-integration-contract.md) · [bedrock-models-and-cost-attribution](bedrock-models-and-cost-attribution.md)
+- [website-chat-security](website-chat-security.md) · [auth-and-access-control](auth-and-access-control.md) · [client-integration-contract](client-integration-contract.md) · [bedrock-models-and-cost-attribution](bedrock-models-and-cost-attribution.md)
 - Callers: [_underscore togaiq-gateway-client](../../../../2.0/apps/_underscore/features/togaiq-gateway-client.md) · [worker2 clickup-task-fluffer-talos](../../../../2.0/apps/worker2/features/clickup-task-fluffer-talos.md) · [togatech talos-product-page](../../togatech/features/talos-product-page.md) · [bdr campaign-chat-handoff](../../bdr/features/campaign-chat-handoff.md)
 
 ## Change history
+- 2026-10-19 — rate-limit gotcha updated (limits now configurable, globals restored); security detail moved to website-chat-security (akhokhani)
 - 2026-10-08 — corrected cross-framework/client links after standalone migration (akhokhani)
 - 2026-10-07 — created: endpoint/auth/caller map for `/api/ai/*`; website chat gate verified in code (wildcard matches any subdomain depth) (akhokhani)

package/knowledge/standalone/apps/talos-backend/features/website-chat-security.md

@@ -0,0 +1,62 @@
+---
+title: Website chat security — reCAPTCHA v3 session mint, replay guard, one lead per session, rate limits
+framework: "standalone"
+repo: talos-backend
+project: TOGa Talos
+client: shared
+type: feature
+status: active
+updated: 2026-10-19
+owners: [akhokhani]
+files:
+  - talos-backend/libs/aegra-api/src/aegra_api/services/talos_chat_service.py
+  - talos-backend/libs/aegra-api/src/aegra_api/api/talos_chat.py
+  - talos-backend/libs/aegra-api/src/aegra_api/models/talos_chat.py
+  - talos-backend/libs/aegra-api/src/aegra_api/settings.py
+  - talos-backend/docs/talos-chat-security.md
+related:
+  - ai-service-endpoints.md
+  - bedrock-models-and-cost-attribution.md
+  - ../../togatech/features/talos-chat-widget.md
+  - ../../bdr/features/landing-chat-drawer.md
+  - ../../bdr/features/campaign-chat-handoff.md
+---
+
+Abuse controls on the public website chat (`POST /api/ai/talos-session` → `POST /api/ai/talos-chat`): Google reCAPTCHA v3 on session mint, token replay guard, one lead email per session, configurable rate limits and the proxy-count gap; open when the togatech/BDR chat gets 403/503, a lead is emailed twice, or limits need tuning.
+
+## Summary
+
+The website chat has no user login. Protection is layered: the browser header gate (Origin/Referer/Sec-Fetch/UA, see [ai-service-endpoints](ai-service-endpoints.md)), Redis rate limits, a **reCAPTCHA v3 check when the session is minted**, then a 15-min HS256 session JWT bound to fingerprint + hashed IP + hashed UA. `/talos-chat` needs that JWT as `Bearer`, and the model, prompt and output schema are pinned on the server. The repo's own write-up is `docs/talos-chat-security.md` (commit `c3fffd27` on `_beta`; PR agilantsolutions/talos-backend#209 `_beta`→`_main`, open as of 2026-10-19).
+
+## How it works
+
+**Session mint order:** header checks → rate limit → reCAPTCHA → mint JWT.
+
+**reCAPTCHA v3 (settings `TalosChatSettings` in `settings.py`):**
+- The request body takes `recaptcha_token` (max 4096 chars). The client mints it with action `talos_session`.
+- The server POSTs to Google `siteverify` with `TALOS_CHAT_RECAPTCHA_SECRET_KEY` + `remoteip`. It requires `success`, a matching `action`, a `hostname` in `TALOS_CHAT_RECAPTCHA_HOSTNAMES` (`togatech.com,*.togatech.com`), and `score >= TALOS_CHAT_RECAPTCHA_MIN_SCORE` (0.5).
+- `TALOS_CHAT_RECAPTCHA_MODE`: `off` (code default) | `monitor` (verifies and logs, never blocks) | `enforce` (generic **403** on failure, **503** if Google is unreachable). `enforce` without a secret fails settings validation at startup.
+- Logs: `talos_chat_recaptcha_result` (score, reason) and `talos_chat_recaptcha_rejected` with reason `missing_token`, `not_successful`, `action_mismatch`, `hostname_not_allowed`, `score_missing`, `low_score` or `replayed_token`.
+- Env (2026-10-19): `.env.beta` = `enforce`, `.env.prod` = `monitor`. The secret lives only in the env files. Plan: flip prod to `enforce` once togatech PR #44 is deployed and real prod scores look right.
+
+**Replay guard:** the SHA-256 of each accepted token is stored in Redis for 5 min (`talos:session:recaptcha:<digest>`). A second use is rejected as `replayed_token`.
+
+**One lead per session:** the website emails a lead whenever a response carries every required output-schema field (`name`, `email`, `company`, `phone`, `intent`, derived from `TALOS_OUTPUT_SCHEMA` `required=True`). `/talos-chat` releases a complete lead **once per session `jti`** (Redis `talos:chat:lead:<jti>`). Later responses keep `message` / `suggestions` / `cta` and drop the lead fields. Internal service-key callers are unchanged.
+
+**Rate limits are settings now:** `TALOS_CHAT_SESSION_MAX_PER_IP_PER_MIN` / `_PER_DAY`, `TALOS_CHAT_MAX_PER_IP_PER_MIN`, `TALOS_CHAT_MAX_PER_FINGERPRINT_PER_MIN` / `_PER_DAY`. Global budgets went back to 300/min and 10,000/day (they were 100,000 during the "TEMP firefight").
+
+## Gotchas
+
+- **Google `siteverify` returned `success:true` for the same v3 token twice** in live testing. Do not count on Google to reject replays. The Redis replay guard above is what stops them.
+- **Scores depend on the browser.** An automated or extension-driven browser scored 0.3, and the same browser later scored 0.9. Always run `monitor` first and read real `talos_chat_recaptcha_result` scores before you switch to `enforce`.
+- **Per-IP limits stay lifted in prod and beta** because `TALOS_CHAT_TRUSTED_PROXY_COUNT` is unset behind the EB nginx + ALB, so every visitor resolves to the same peer IP. Open follow-up: verify the hop count (likely 2: ALB + nginx), set it, then tighten the per-IP limits. Until then the fingerprint, global and reCAPTCHA checks carry the load.
+- **Every consumer must send a token once its env is in `enforce`.** A session request with no `recaptcha_token` gets a 403 `missing_token`. Consumers that degrade silently (the BDR drawer) then look like they work but answer from a script. Note that the hostname allowlist only covers `togatech.com` domains.
+- **The lead email itself is not protected by any of this.** The website sends it straight from the browser to TogaHub `email-templates/sendEmail`, which checks no reCAPTCHA (see [togatech talos-chat-widget](../../togatech/features/talos-chat-widget.md)). Talos also calls `sendEmail` server-to-server for reminder and scheduled-run emails (`services/notification_provider.py`, per-tenant TogaHub API key exchanged for a bearer), so any TogaHub lockdown must exempt authenticated service callers.
+
+## Related
+- [ai-service-endpoints](ai-service-endpoints.md) — endpoint map and the browser header gate
+- [togatech talos-chat-widget](../../togatech/features/talos-chat-widget.md) — client side (token minting)
+- [bdr landing-chat-drawer](../../bdr/features/landing-chat-drawer.md) · [bdr campaign-chat-handoff](../../bdr/features/campaign-chat-handoff.md) — the other `/talos-session` consumer
+
+## Change history
+- 2026-10-19 — created: reCAPTCHA v3 on session mint (off/monitor/enforce), Redis replay guard, one lead per session `jti`, configurable rate limits, proxy-count gap (akhokhani)

package/knowledge/standalone/apps/togatech/INDEX.md

@@ -7,6 +7,7 @@
 | [NavV2 Global Nav — menus, panel shell, scroll reveal, Talos FAB](features/navv2-global-nav.md) | togatech NavV2 header (designer "phase one"): data-driven menus, one shared panel shell + WebGL canvas, `data-nav-reveal` scroll hide/show, opt-in `data-nav-pin |
 | [Platform Product Page (/our-platform) — ported designer prototype](features/platform-product-page.md) | togatech `/our-platform` TOGa Platform product page, ported from designer prototype `our-platform-v5`; open for the page-root-as-`<html>` rule, effect-order rul |
 | [SEO / AEO / GEO — Prerendering, Single-Source Meta & Structured Data](features/seo-aeo-geo-prerender.md) | togatech SEO/AEO/GEO — build-time Puppeteer prerender + hydration, code-split routes (`lazyRoute`), single-source per-page meta + JSON-LD; open for the robots d |
+| [Talos chat widget — session mint, reCAPTCHA v3 token, lead email path](features/talos-chat-widget.md) | togatech.com Talos chat client: how it mints a session (fingerprint + reCAPTCHA v3 token), how the lead email goes out through TogaHub `sendEmail`, and the open |
 | [Talos Product Page (/talos) — ported designer prototype](features/talos-product-page.md) | togatech `/talos` Talos AI product page, ported from a designer HTML/JSX/CSS prototype; open for its talos.css port edits, section notes, open port work and pla |
 | [Creating Pull Requests on togatech](workflows/creating-pull-requests.md) | Open a PR on `agilantsolutions/togatech` — `gh` CLI lacks `read:org`, so use a raw GitHub REST call with the keychain token; base is `_production`. |
 | [Porting a Designer Prototype to a togatech Page](workflows/designer-prototype-port.md) | togatech procedure for turning a designer HTML/JSX/CSS prototype into a live page (`/talos`, `/our-platform`): where drops and port tools live, generated prefix |

package/knowledge/standalone/apps/togatech/features/talos-chat-widget.md

@@ -0,0 +1,53 @@
+---
+title: Talos chat widget — session mint, reCAPTCHA v3 token, lead email path
+framework: "standalone"
+repo: togatech
+project: TOGA Technology Website
+client: shared
+type: feature
+status: active
+updated: 2026-10-19
+owners: [akhokhani]
+files:
+  - togatech/src/lib/talosSession.ts
+  - togatech/src/lib/talosRecaptcha.ts
+  - togatech/src/lib/api.ts
+  - togatech/src/components/Footer/Footer.tsx
+  - togatech/src/pages/Contact/view/components/ContactForm/ContactForm.tsx
+related:
+  - ../architecture.md
+  - talos-product-page.md
+  - ../../talos-backend/features/website-chat-security.md
+  - ../../talos-backend/features/ai-service-endpoints.md
+  - ../../../../2.0/apps/_underscore/features/email-template-sending.md
+---
+
+togatech.com Talos chat client: how it mints a session (fingerprint + reCAPTCHA v3 token), how the lead email goes out through TogaHub `sendEmail`, and the open security gaps on that path; open when the site chat gets 403s, reCAPTCHA errors, or when touching forms or emails on the website.
+
+## Summary
+
+The site chat talks to Talos through a public two-step flow: `POST /api/ai/talos-session` mints a session JWT, then `POST /api/ai/talos-chat` carries the turns (server rules in [talos-backend website-chat-security](../../talos-backend/features/website-chat-security.md)). The session request now also carries a Google reCAPTCHA v3 token (PR agilantsolutions/togatech#44, base `_production`, open as of 2026-10-19). When Talos returns a complete lead, the **browser** emails it through TogaHub, just as the footer and contact forms do.
+
+## How it works
+
+1. `src/lib/talosRecaptcha.ts` reads `window.grecaptcha`, which `GoogleReCaptchaProvider` in AppLayout loads (it mounts only when `VITE_RECAPTCHA_V3_SITE_KEY` is set), and runs `execute` with action `talos_session`.
+2. `src/lib/talosSession.ts` `mintSession` sends `{ fingerprint, recaptcha_token }`. If the script or site key is missing it sends no token and lets the backend decide (403 in `enforce`, pass in `monitor`/`off`). The change is backward compatible: a backend without the check ignores the extra field.
+3. Chat turns use `Bearer <session token>`. The backend releases a complete lead once per session.
+4. **Lead and form emails:** the footer form, the contact page form and the Talos chat lead all call TogaHub `GET https://api.togahub.com/v2/email-templates/sendEmail` from the browser through `useSendEmail` (`src/lib/api.ts`). It uses template `f64f8b8d-9238-4367-81d9-55c2bff277b2`, recipient `website@togatech.com`, and the contact page adds its own to/cc addresses. The uuid, to, cc and body values all travel in the URL.
+
+## Gotchas
+
+- **⚠ `sendEmail` is callable by anyone.** Its endpoint, template uuid and recipients all sit in the public JS bundle, and the server checks no captcha, so a bot can call it directly. The Talos session checks cannot protect it. `Footer.tsx` and `ContactForm.tsx` generate a `recaptchaToken`, but `useSendEmail` **drops it** because it only forwards `fieldMapping` fields. Open TogaHub/PHP follow-up: verify reCAPTCHA in `sendEmail` (actions `footer_form_submit`, `contact_form_submit`, `talos_lead`; hostname `togatech.com`; score ≥ 0.5), pin recipients per template and ignore public `to`/`cc`, rate-limit, ideally switch to POST, and exempt authenticated service callers (Talos sends reminder emails through it).
+- **⚠ `VITE_HUBSPOT_SERVICE_KEY` (a HubSpot private-app token) is compiled into the public bundle.** Any `VITE_*` value ships to the browser. It should move server-side.
+- **The page loads two reCAPTCHA release scripts.** Calling `grecaptcha.execute` from an isolated or extension context (for example a test harness that injects a script) throws `auto_render_clients` errors. Code that runs in the page context works, so test token minting through the app itself.
+- **Low scores from automation are normal.** An automated or extension-driven browser scored 0.3 (0.9 later in the same browser). Do not take a single test run as the real-user score.
+- **ESLint cannot run in this repo** (a legacy `.eslintrc` with ESLint 9). Use `tsc --noEmit` as the working check.
+
+## Related
+- [talos-backend website-chat-security](../../talos-backend/features/website-chat-security.md) — server side of the session/reCAPTCHA/lead rules
+- [talos-backend ai-service-endpoints](../../talos-backend/features/ai-service-endpoints.md) — header gate and allowed origins
+- [_underscore email-template-sending](../../../../2.0/apps/_underscore/features/email-template-sending.md) — the `sendEmail` server side
+- [talos-product-page](talos-product-page.md) · [architecture](../architecture.md)
+
+## Change history
+- 2026-10-19 — created: session mint now sends a reCAPTCHA v3 token (PR #44); recorded the open `sendEmail` and HubSpot-key exposure (akhokhani)

package/package.json

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