toga-ai 1.0.455 → 1.0.456

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/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)
 
@@ -143,3 +154,6 @@ public function run(): void {
 ```
 
 Distinguish between retriable errors (transient DB/network issues — re-throw) and non-retriable errors (bad data, missing record — log and return).
+
+## 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.456",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",