toga-ai 1.0.1045 → 1.0.1046

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

@@ -55,6 +55,7 @@
 | [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 |
 | [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 |
 | [_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/sla-engine.md

@@ -0,0 +1,65 @@
+---
+title: Ticket SLA engine (_Component_Sla) — 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
+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/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
+related:
+  - ./ticket-status-from-stage.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.
+
+## 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.
+
+## 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.
+- **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.
+- **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.
+
+## 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).
+- **⚠ 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.
+
+## Related
+
+- [Ticket status from stage](./ticket-status-from-stage.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-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-15
+updated: 2026-10-16
 owners: ["mhammontree", "dfranks", "bala", "snaredla", "jcardinal", "rgirish"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -254,6 +254,8 @@ A `postPut`/`postPost` runs after the save, so it cannot compare old vs new valu
 
 Main use: **fire a POST side effect only on a REAL field change.** Edit forms resend unchanged fields (TOGa Commerce resends `contact` on every order save), so "key present in `$api->httpPayload`" is not "value changed". In `prePut`, read the current DB value, compare to the payload, store a bool; `postPut` acts only when it is true. Both hooks need their own interceptor row — if the PRE row is missing, the key is absent, so fall back to the old check rather than silently skipping. Reference: `_Model_Compass_SalesOrder::rememberWhetherOrderForPersonIsChanging()` (TRUE-82727, see [Compass approval-decision flow](../../../clients/compass-usa/features/approval-decision-flow.md)). Also used to carry a non-column field past PRE: Rate's `PASSTHROUGH_KEY_FULFILLMENT_PREFERENCE` ([AIG contract creation](../../../clients/rate/features/aig-contract-creation.md)).
 
+**Command keys** (a non-column payload key that asks for an action): `prePut` strips the key (api2 would reject an unknown column), validates the exact value, parks it on `$api->passThrough`; `postPut` runs the action. Gate it on write access to a real field (field ACL). A body that is empty after the strip becomes `{}` in V2.php and `postPut` still runs. Reference: `{"recomputeSla": true}` on `PUT /v2/clients/{uuid}` ([SLA engine](../../_underscore/features/sla-engine.md)).
+
 ### Own-row guards in a PRE interceptor
 
 A PRE hook that limits a user to their own rows must close four bypasses — each found by review on the `user-global-settings` guard (TRUE-82613):
@@ -322,3 +324,4 @@ Refuse API-key callers when the rule is "the signed-in user" (no user on the tok
 - 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)
 - 2026-10-09 — Own-row guards in PRE hooks (alias keys + parent-route bypasses, PRE before field ACL); user-global-settings reference; known open holes. (jcardinal)
 - 2026-10-15 — PRE → POST state hand-off via `$api->passThrough`; detect a real field change, not a resent one (TRUE-82727). (bala)
+- 2026-10-16 — Command keys: strip in `prePut`, park on `passThrough`, act in `postPut`; empty body → `{}` (TRUE-82849). (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-01
+updated: 2026-10-16
 owners: [bala, kyalamarthi, apeterson, ajean, jcardinal, rgirish]
 files:
   - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
@@ -18,7 +18,9 @@ files:
   - dbchanges2/Client_Compass/2026-09-21a - BackfillUpstreamItemFulfillmentUnits.sql
   - dbchanges2/Client_Compass/2026-09-23a - BundlesTableViewFieldFlags.sql
   - dbchanges2/Client_Compass/2026-09-24a - DeduplicateBundleItemPrices.sql
+  - dbchanges2/Client_True/2026-10-16a - SlaStageDataRepair.sql
 related:
+  - ../../_underscore/features/sla-engine.md
   - ../architecture.md
   - ../../worker2/features/netsuite-salesorder-open-orders-sync.md
   - ../../_underscore/features/acl-permission-chain.md
@@ -534,12 +536,21 @@ an INSERT that names only `uuid`/`tableViewId`/`recordFieldId`/`isVisible`/`inde
   and a nullable FK column takes it, leaving a structurally broken row that looks inserted. Prefer a
   `JOIN` (so a missing lookup inserts **no row** at all) or add the lookup to the guard's
   `WHERE EXISTS`.
+- **⚠ A `Client/` fan-out seed keyed on a slug that ANOTHER folder sets can silently no-op.** Files in
+  `Client/` and `Client_<Name>/` run in no fixed order across folders, so a fan-out `UPDATE … WHERE slug
+  = '…'` that runs before the client file back-fills the slugs matches zero rows and reports success.
+  Found 2026-10-16: `Client/2026-09-29d` left every QA alpha `Client_True` stage `slaEffect = RUN`
+  (Resolved/Closed slugs NULL); fixed forward by `Client_True/2026-10-16a - SlaStageDataRepair.sql`.
+  Rule: in the same file, first back-fill the slug from the stable code (guarded), then seed by slug;
+  end with a verify SELECT and check it per environment. See [SLA engine](../../_underscore/features/sla-engine.md).
 - **`Core.RecordFields` has NO `sql` column.** A calculated field's SQL is **not** stored in
   metadata — it lives in the `_underscore` model as a `FIELD_SQL` static method. Do not go looking
   for a migration to change a calculated field's expression; there is none. See
   [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
 ## Change history
+- 2026-10-16 — Fan-out seed keyed on a slug another folder sets can silently no-op; back-fill slugs
+  first, verify per environment (TRUE-82849). (jcardinal)
 - 2026-10-01 — Added the `_Model` + column-DEFAULT trap: `_Model` writes every declared field, so an
   explicit NULL skips a `NOT NULL DEFAULT` clause and the insert dies 1048; a unique key over a
   nullable column enforces nothing, so the model default must ship with the ALTER

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)_ — 99 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 100 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 87 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 26 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)

package/package.json

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