toga-ai 1.0.456 → 1.0.457

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

@@ -24,7 +24,7 @@
 | [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, _underscore/Model/Client/EmailTemplate.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
 | [OneUptime push-metric monitors for 2.0 workers](features/oneuptime-worker2-monitoring.md) | A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from the 1.0 `App_SystemMonitor_Compass` monitors. | worker2/Worker/Monitor/Compass.php, worker2/Worker/Client/Compass.php, worker2/composer.json, _underscore/Cloud.php |
-| [Platform Cache Cleanup (_Worker_Platform_Cache::Clean)](features/platform-cache-cleanup.md) | `_Worker_Platform_Cache::Clean()` is the reaper for the shared **Cache** cluster that backs api2's [multi-client data retrieval](../../api2/features/cross-clien | worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
+| [Platform Cache Cleanup (_Worker_Platform_Cache — Clean + Truncate)](features/platform-cache-cleanup.md) | `_Worker_Platform_Cache` owns maintenance of the shared **Cache** cluster that backs api2's [multi-client data retrieval](../../api2/features/cross-client-data- | worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |
 | [Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)](features/talos-meeting-notes-integration.md) | How a **dev tool / agent consumes Talos (TOGa IQ)** to query the team meeting-notes corpus programmatically. | .claude/skills/plan-ticket/scripts/talos.js |
 | [Talos Pricing Automation (worker2 Cron — AWS Actuals, Calibration, Monthly Report)](features/talos-pricing-automation.md) | The worker2 half of the **Talos Pricing Platform** (see the talos `pricing-cogs-model` and tools `talos-pricing-ui` docs for the other halves). | worker2/Worker/Talos/Pricing.php, worker2/Database/TalosPricingCrons.sql |

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: architecture
 status: active
-updated: 2026-07-21
+updated: 2026-07-28
 owners: [jcardinal]
 files:
   - worker2/Controller/Index.php
@@ -163,6 +163,37 @@ file `Worker/Team/Github.php`.
 `_Worker_Infrastructure_Worker_Cleanup`: `WorkerJobs()` deletes `isSuccess=1` rows >90 days
 (≤1000/run); `WebhookLogs()` deletes `Logs.Webhook` >90 days. Two daily CronJobs at 2 AM.
 
+## Cron actions must return a result on BOTH paths
+
+**A new cron action is expected to return a result for a success as well as a failure.** Both
+outcomes are recorded against the job, and the **successful** results are what auditing reads — a
+run that completed but returned nothing is indistinguishable in the audit trail from one that never
+executed.
+
+So an action must not return only on the failure path, and must not return nothing on success
+because "there was nothing to do". Return a result describing the outcome — including the no-op case
+(`0 deleted, 0 dropped` is a meaningful audit record; silence is not). Make it structured and
+countable rather than prose, so one run can be compared against its neighbours:
+
+```php
+public static function Clean(): string {
+    // ... work ...
+    return json_encode([
+        'isSuccess' => true,
+        'deletedRowCount' => $deletedRowCount,
+        'droppedTableCount' => $droppedCount,
+        'failedDropCount' => $failedCount,
+    ]);
+}
+```
+
+Reserve throwing for genuinely **retriable** conditions, where the queue re-running the job is the
+behaviour you want. A handled, non-retriable failure should return a result saying so rather than
+throwing — throwing costs the full retry cycle and still records nothing useful for the audit.
+
+See the worker contract in [2.0 framework rules](../../standards/framework-rules.md) for the
+class/method shape and the named-argument parameter contract.
+
 ## Critical transaction pattern
 
 **Any INSERT/UPDATE that must be visible to another connection before an SQS message is
@@ -229,6 +260,12 @@ the MySQL-first design was departed from **on purpose** here.
 
 ## Change history
 
+- 2026-07-28 — Added **Cron actions must return a result on BOTH paths**: a new cron action is
+  expected to return a structured result for a success as well as a failure, because both are
+  recorded against the job and the successful results are what auditing reads (a completed run that
+  returned nothing is indistinguishable from one that never executed). Formalises the intent of the
+  2026-07-21 `output` change below. Also documents `_Worker_Platform_Cache::Truncate()`, a manual
+  companion to the scheduled `Clean()` action. (jcardinal)
 - 2026-07-21 — `Core.WorkerJobs.failureReason` renamed to `output` and repurposed to capture
   successful run results as well as failures (success writes the composed "Successfully Executed"
   message, return value `json_encode`d). Multi-producer rename: PHP worker (both paths), `Retry()`

package/knowledge/2.0/apps/worker2/features/platform-cache-cleanup.md

@@ -1,5 +1,5 @@
 ---
-title: Platform Cache Cleanup (_Worker_Platform_Cache::Clean)
+title: Platform Cache Cleanup (_Worker_Platform_Cache — Clean + Truncate)
 framework: "2.0"
 repo: worker2
 project: Worker
@@ -17,20 +17,28 @@ related:
   - ../../api2/features/cross-client-data-retrieval.md
   - ./creating-worker-actions.md
   - ../../_underscore/features/per-client-database-connections.md
+  - ../architecture.md
 ---
 
 ## Summary
 
-`_Worker_Platform_Cache::Clean()` is the reaper for the shared **Cache** cluster that backs api2's
-[multi-client data retrieval](../../api2/features/cross-client-data-retrieval.md). It deletes
-expired `Cache.Tables` rows and drops the per-query `TableResults_<Tables.id>` tables that no
-longer have a parent. Without it the Cache schema grows one table per distinct cross-client query,
-forever.
+`_Worker_Platform_Cache` owns maintenance of the shared **Cache** cluster that backs api2's
+[multi-client data retrieval](../../api2/features/cross-client-data-retrieval.md). It exposes **two**
+actions on the same class (both listed in the class docblock in `Worker/Platform/Cache.php`):
 
-Action path `Platform/Cache/Clean`, scheduled on a **`*/5`** cron registered in
-`dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql`.
+| Action | Path | Scheduled? | Scope |
+|---|---|---|---|
+| `Clean()` | `Platform/Cache/Clean` | yes — `*/5` cron | **expired** entries only, with a 2-minute grace |
+| `Truncate()` | `Platform/Cache/Truncate` | **no — deliberately manual** | **everything**, no grace, spares nothing |
 
-## How it works
+Without `Clean()` the Cache schema grows one `TableResults_<Tables.id>` table per distinct
+cross-client query, forever. `Truncate()` is the administrative "reset the whole cache" hammer.
+
+The `Clean()` cron is registered in `dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql`.
+Both actions return a summary string on **every** path (success and handled failure) — see
+[cron actions must return a result on both paths](../architecture.md#cron-actions-must-return-a-result-on-both-paths).
+
+## How it works — `Clean()` (scheduled reaper)
 
 1. **Reap expired parents.** Delete `Cache.Tables` rows whose TTL has elapsed, with a **2-minute
    grace period** so a request that is mid-read cannot have its rows deleted out from under it.
@@ -41,6 +49,44 @@ Action path `Platform/Cache/Clean`, scheduled on a **`*/5`** cron registered in
    status is **re-verified on the write host immediately before each `DROP`** — a `DROP TABLE` is
    irreversible and non-transactional, so a stale read replica must never be the basis for one.
 
+## How it works — `Truncate()` (manual, unscheduled)
+
+`_Worker_Platform_Cache::Truncate(): string` removes the **entire** cross-client cache. It is
+deliberately **not** registered as a cron — invoke it explicitly:
+
+```php
+_Worker::runTask('Platform/Cache/Truncate', []);
+```
+
+1. `_Database::useQueryCache(bool: false)` at the top, because the action re-reads tables it has
+   just emptied and a cached result set would make it act on stale contents.
+2. `DELETE FROM Tables` — `Tables_Clients` follows automatically via `ON DELETE CASCADE`.
+3. A **defensive** `DELETE FROM Tables_Clients` afterwards, to catch any cursor row orphaned by an
+   earlier partial failure (the cascade only covers rows whose parent still existed).
+4. Drop every `TableResults_*` table.
+
+**Each delete is committed immediately** with
+`_Database::transactionCommit(database: _underscore::DB_CACHE)`. This is not optional:
+`_Database::register()` opens a **lazy transaction**, so anything left uncommitted is rolled back
+at connection close and the truncate silently does nothing.
+
+Drops still go through the existing `dropResultTable()` **allowlist** (`^TableResults_[1-9][0-9]*$`),
+so a table that merely shares the prefix is never dropped. A drop failure is logged and counted and
+does **not** abort the remaining drops.
+
+### `Clean()` vs `Truncate()` — the difference that matters
+
+| | `Clean()` | `Truncate()` |
+|---|---|---|
+| Selects | **expired** entries only | **everything** |
+| Grace period | **2 minutes** — in-flight requests keep their rows | **none** |
+| Safe on a busy environment | yes, by design | **no** |
+
+`Truncate()` gives a request that is mid-build no protection: it loses its rows and serves an empty
+or short page. Nothing is *corrupted* — the cache is derived data and rebuilds on the next request —
+but the visible-wrong-output window is real, so it must not be run casually against a busy
+environment.
+
 ## Key rules
 
 - **Delete-parent-then-drop-child, and re-check on the writer.** Never drop a result table based on
@@ -51,18 +97,41 @@ Action path `Platform/Cache/Clean`, scheduled on a **`*/5`** cron registered in
   (`Databases.name = 'Cache'`) in `worker2/Controller/Index.php` — the same rule as api2. There is
   deliberately no `CACHE_DATABASE_ID`: `Databases.id` is auto-assigned per Core instance and a
   hardcoded id fails silently in every environment where it does not happen to match.
+- **Commit each delete immediately in `Truncate()`.** `_Database::register()`'s lazy transaction
+  rolls back at connection close, so an uncommitted truncate is a no-op that *looks* like it worked.
+- **Never bypass `dropResultTable()`'s allowlist.** `^TableResults_[1-9][0-9]*$` is the only thing
+  standing between a prefix-sharing table and an irreversible `DROP`.
+- **Both actions return a summary string on every path** — success, no-op, and handled failure. See
+  the [worker2 architecture rule](../architecture.md#cron-actions-must-return-a-result-on-both-paths);
+  a run that returns nothing is indistinguishable in the audit trail from one that never executed.
 
 ## Gotchas
 
 - **Worker classes are `abstract class _Worker_<Path>` with `public static` entry methods**,
   dispatched as `$className::$functionName()`. They do **not** `extends _Worker` — that is the
   dispatcher. See [Creating Worker Actions](./creating-worker-actions.md). (The 2.0
-  `standards/framework-rules.md` worker contract still describes the older `extends _Worker` +
-  `run()` shape and needs reconciling.)
+  `standards/framework-rules.md` worker contract now matches this shape — reconciled
+  2026-07-28.)
 - **Adding the cron is a dbchanges2 change, not a code change** — the schedule lives in Core, so a
   new worker action is not actually scheduled until that SQL is applied per environment.
+- **`Truncate()` is unscheduled on purpose.** Do not "helpfully" add a cron for it — it has no grace
+  period, so on a schedule it would periodically blank live requests' cache rows.
+- **`ON DELETE CASCADE` is not sufficient on its own.** The extra `DELETE FROM Tables_Clients` in
+  `Truncate()` exists because an earlier partial failure can leave cursor rows whose parent is
+  already gone — the cascade never fires for those.
+- **Stale reads inside a truncate.** Without `_Database::useQueryCache(bool: false)` the action
+  re-reads its own just-emptied tables from the query cache and mis-decides what is left.
 
 ## Change history
+- 2026-07-28 — Added second action `_Worker_Platform_Cache::Truncate()` on the same class: manual /
+  administrative, deliberately **not** scheduled. Removes the entire cross-client cache
+  (`DELETE FROM Tables` + cascade, defensive `DELETE FROM Tables_Clients` for orphaned cursors, then
+  drops every `TableResults_*`), committing each delete immediately because `_Database::register()`'s
+  lazy transaction would otherwise roll it back at connection close; `useQueryCache(false)` since it
+  re-reads tables it just emptied; drops still gated by the `dropResultTable()` allowlist and a
+  failed drop is logged/counted without aborting. Unlike `Clean()` it applies **no** grace period —
+  an in-flight request loses its rows and serves a short page (no corruption; cache rebuilds).
+  Both actions return a summary string on every path. (jcardinal)
 - 2026-07-28 — Initial capture: `_Worker_Platform_Cache::Clean()` reaps expired `Cache.Tables` rows
   (2-minute grace) and drops orphaned `TableResults_*` tables (parent deleted+committed first,
   orphan status re-verified on the write host immediately before each DROP); `DB_CACHE` registered

package/knowledge/2.0/standards/framework-rules.md

@@ -138,22 +138,30 @@ Do not add a worker class without registering it. Unregistered workers cannot be
 Workers must catch specific exceptions and handle them appropriately. A worker that throws an uncaught exception will be retried by the queue (up to the configured retry limit) and then dead-lettered.
 
 ```php
-public function run(): void {
+public static function ProcessOrder(int $orderId): string {
     try {
-        $this->processOrder($this->payload['order_id']);
+        self::processOrder(orderId: $orderId);
     } catch (_Exception_OrderNotFound $e) {
         // Do not retry — log and discard
         error_log('Worker: order not found, discarding job: ' . $e->getMessage());
-        return;
+        return json_encode(['isSuccess' => false, 'isRetriable' => false, 'orderId' => $orderId, 'error' => $e->getMessage()]);
     } catch (_Exception_Database $e) {
-        // Retriable — re-throw so queue retries
+        // Retriable — re-throw so the queue retries
         error_log('Worker: DB error, will retry: ' . $e->getMessage());
         throw $e;
     }
+
+    return json_encode(['isSuccess' => true, 'orderId' => $orderId]);
 }
 ```
 
-Distinguish between retriable errors (transient DB/network issues — re-throw) and non-retriable errors (bad data, missing record — log and return).
+Distinguish between retriable errors (transient DB/network issues — re-throw) and non-retriable errors (bad data, missing record — log and return a failure result).
+
+**Always return a result — on the failure path as well as the success path.** Both outcomes are
+recorded against the job, and the successful results are relied on for auditing, so a worker that
+returns nothing (or returns only when it succeeds) leaves a blind spot in the audit trail. Re-throw
+only for genuinely retriable conditions, where the queue's retry is the intended behaviour; a
+handled non-retriable failure should return a result describing what happened rather than throwing.
 
 ## Change history
 - 2026-07-28 — Corrected the **Worker contract** and **Worker dispatch** sections to match the actual codebase: worker actions are `abstract class _Worker_<Name>` with `public static` entry methods dispatched via `_Worker::runTask(string $action, array|object $parameters)` on the `Category/Sub/File/MethodName` path, with parameters spread as **named arguments** (`$className::$functionName(...$parameters)`, worker2 `Controller/Index.php:325,567`; `_underscore/Worker.php:8`). This replaces the previous `extends _Worker` / `run()` / `_Queue::dispatch()` guidance — no worker in worker2 follows it, `_Queue::dispatch()` does not exist in the codebase, and following the old text would produce a worker that never dispatches. (jcardinal)

package/package.json

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