toga-ai 1.0.455 → 1.0.457

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: architecture
 status: active
-updated: 2026-07-27
+updated: 2026-07-28
 owners: [jcardinal, bala, mhammontree]
 files:
   - api2/Controller/Index.php
@@ -141,6 +141,8 @@ Aliases: `DB_CORE`, `DB_CLIENT`, `DB_CLIENT_LOGS`, `DB_CLIENT_ARCHIVE`, `DB_LOGS
 `DB_STORE_1`/`DB_VISION_1` (legacy). `_Database::registerClientDatabases(clientId,
 environment)` joins `Clients`/`Databases`/`DatabaseHosts`/`Environments`, preferring the
 instance's own region; reads→readers, writes→writers, per-connection transactions.
+`DB_CACHE` (shared Cache cluster) is resolved **by name** (`Databases.name = 'Cache'`) — never by
+a hardcoded id, which differs per Core instance.
 
 ## Deployment (EB)
 
@@ -169,11 +171,39 @@ build. These must be **rotated** (treat the committed tokens as compromised) and
 Parameter Store / EB env properties. **Flag this if you touch config or deploy.** (Location +
 remediation only — do not record the token value anywhere.)
 
-**Follow-up (deferred, separate ticket): raw exception disclosure to clients.** The error paths that
-surface a caught `\Throwable` (now that Route.php rethrows and the bootstrap guard reports failures)
-must not return raw `getMessage()`/`getTrace()` output in the client-facing envelope — that leaks
-internal paths, schema names, and stack frames to API consumers. Sanitize the client envelope
-(generic message + code; full detail to Sentry/logs only). Not yet done.
+## Known issues / accepted risks
+
+Open items a maintainer should know before changing this tier. None are "bugs to fix right now" —
+they are the known sharp edges. Do not re-discover these from scratch.
+
+1. **Raw exception disclosure to clients (deferred, separate ticket).** The error paths that
+   surface a caught `\Throwable` (now that Route.php rethrows and the bootstrap guard reports
+   failures) must not return raw `getMessage()`/`getTrace()` output in the client-facing envelope —
+   that leaks internal paths, schema names, and stack frames to API consumers. Sanitize the client
+   envelope (generic message + code; full detail to Sentry/logs only). Not yet done.
+2. **Committed plaintext credentials, not yet rotated.** See the Security note above —
+   `Config/*.ini` secrets and the per-env `.ebextensions/git.*.json` GitHub PAT. Treat as
+   compromised until rotated and moved to SSM / EB env properties.
+3. **The pre-execute phase still runs before `execute()`'s try/catch.** The 2026-07-23 fix wraps the
+   Core/Logs bootstrap specifically; it did not move the phase inside the main guard. Any *new* code
+   added to the pre-execute block is again outside `execute()`'s protection and must carry its own
+   `try/catch (\Throwable)`.
+4. **Local Logs DB name mismatch reads as "missing".** The Core Logs schema name comes from a
+   `Core.Database` row (`id = CORE_LOGS_DATABASE_ID`); a local Logs DB whose actual schema name
+   differs throws `Unknown database`. This is environment config, not a code bug — fix the row or
+   the local schema name, don't patch the bootstrap.
+5. **CORS is fully permissive.** `Access-Control-Allow-*` is wide open on every route. Acceptable
+   only because auth is bearer-token (not cookie) based — if any cookie/session-backed auth is ever
+   added here, this becomes an exploitable hole and must be tightened first.
+6. **`_underscore` is cloned at build from a moving branch** (`_<ENVIRONMENT>`), not pinned to a
+   commit. Two deploys of the same api2 commit can produce different runtime behavior. Check the
+   framework branch state when triaging an "it worked yesterday" regression.
+7. **`V2.php::execute()` is a ~2,000-line monolith** with `processRoutePairs()` recursion beneath
+   it. There is no unit-test harness around it; changes are validated by integration traffic. Make
+   surgical edits and preserve the transaction/logging invariant.
+8. **JWT signing-secret rotation accepts current + previous.** During the overlap window a token
+   signed with the retired secret still validates. Revocation is therefore not immediate —
+   don't rely on rotation alone to lock out a compromised token.
 
 ## When making changes here
 
@@ -191,5 +221,6 @@ internal paths, schema names, and stack frames to API consumers. Sanitize the cl
   or `execute()`.
 
 ## Change history
+- 2026-07-28 — Added a consolidated **Known issues / accepted risks** section (8 items), absorbing the previously free-floating deferred raw-exception-disclosure follow-up as item 1, so the tier's sharp edges (unrotated committed secrets, pre-execute phase still outside the main guard, local Logs DB name mismatch, permissive CORS, unpinned `_underscore` build clone, untested `V2.php` monolith, JWT rotation overlap window) are in one place instead of scattered. Recorded that `DB_CACHE` is resolved by name (`Databases.name = 'Cache'`), never by a hardcoded id, which differs per Core instance. (jcardinal)
 - 2026-07-27 — Sharpened the committed-secret note: the plaintext GitHub PAT lives in the per-env **`.ebextensions/git.*.json`** files (used by the `prebuild/git.sh` clone hook to pull `_underscore`), must be rotated and moved to SSM / EB env properties (location + remediation only, no value). (mhammontree)
 - 2026-07-23 — Documented the now-guarded Core/Logs DB bootstrap in the front controller: the pre-execute block runs before the `execute()` try/catch, the Core Logs schema name is resolved from a `Core.Database` row (`id = CORE_LOGS_DATABASE_ID`) so a name-mismatched local Logs DB reads as missing, and the failure is now wrapped in `try/catch (\Throwable)` returning `INVALID_CONFIGURATION` + Sentry instead of a fatal (guarded no-op rollback, `Database.php:219–226`). Added the deferred raw-getMessage/getTrace client-disclosure follow-up to the Security note. (jcardinal)

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

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-06-16
+updated: 2026-07-28
 owners: [jcardinal]
 files: []
 related:
@@ -26,41 +26,52 @@ All framework classes use a leading underscore prefix:
 
 - Controllers: `_Controller` base, subclasses `_Controller_<Name>`
 - Models: `_Model` base, subclasses `_Model_<Name>`
-- Workers: `_Worker` base, subclasses `_Worker_<Name>`
+- Workers: `_Worker` dispatcher; action classes are `abstract class _Worker_<Name>` with static entry methods
 - API handlers: `_Api` base or `_Api_<Name>`
 
 Application code in `worker2` and `api2` follows the same leading-underscore convention for framework-extending classes.
 
 ## Worker contract
 
-Every worker class must extend `_Worker` and implement the `run()` method.
+Worker action classes **do not extend `_Worker`** and have no `run()` method. A worker is an
+`abstract class` of static entry methods, one method per queue action, mirrored by its file path.
 
 ```php
-// CORRECT
-class _Worker_BatchOrders extends _Worker {
-    public function run(): void {
-        // process the job payload from $this->payload
+// CORRECT — worker2/Worker/Platform/Cache.php
+abstract class _Worker_Platform_Cache {
+    public static function Clean(int $graceSeconds = 60): void {
+        // do the work; parameters arrive as named arguments
     }
 }
 ```
 
-The `run()` method has no parameters and returns void. Job data is accessed via `$this->payload` (or the framework's equivalent property). Do not add parameters to `run()`.
+The class is `abstract` (never instantiated), the entry methods are `public static`, and the
+action's queue name is the `Category/Sub/File/MethodName` path — `Platform/Cache/Clean` above.
+Job data arrives as **method parameters**, not as a payload property: the dispatcher spreads the
+parameter array as named arguments, so parameter names are part of the public contract. Renaming
+a parameter is a breaking change to every queued job already in flight. Give parameters defaults
+where a sensible one exists, so an older enqueued job missing a newly added key still runs.
 
 ## Worker dispatch — never call directly
 
-Workers must only be invoked via the queue dispatcher. Never call a worker's `run()` method directly from a controller, another worker, or any non-queue context.
+Workers must only be invoked through the queue. Never call a worker's entry method directly from a
+controller, another worker, or any non-queue context.
 
 ```php
 // CRITICAL VIOLATION — direct call
-$worker = new _Worker_BatchOrders($payload);
-$worker->run();
+_Worker_Platform_Cache::Clean();
 
-// CORRECT — dispatch through queue
-_Queue::dispatch('_Worker_BatchOrders', $payload);
-// or the framework's equivalent dispatch method
+// CORRECT — dispatch through the queue
+_Worker::runTask('Platform/Cache/Clean', ['graceSeconds' => 120]);
 ```
 
-Direct calls bypass retry logic, error handling, visibility timeout, and monitoring. Even in development or testing, use the sync queue adapter — do not call `run()` directly.
+`_Worker::runTask(string $action, array|object $parameters)` is the only supported entry point. The
+action is the `Category/Sub/File/MethodName` path; `parameters` is string-keyed and is spread as
+**named arguments** at dispatch (`$className::$functionName(...$parameters)`), so every key must
+match a parameter name on the target method.
+
+Direct calls bypass retry logic, error handling, SQS visibility timeout, WorkerJobs tracking and
+monitoring. Even in development, dispatch through the queue — do not invoke the method directly.
 
 ## API response envelope (api2 only)
 
@@ -127,19 +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.455",
+  "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",