toga-ai 1.0.267 → 1.0.269

package/knowledge/1.0/apps/library/INDEX.md

@@ -4,6 +4,7 @@
 |-----|---------|-------|
 | [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. | library/_.php, library/app/, library/browser/ |
 | [App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)](features/app-sso-initiation.md) | `App_Sso` (`library/app/sso.php`) is the **1.0 port of the 2.0 SAML gateway's SP-initiated SSO initiation**, packaged as a reusable, framework-level capability | library/app/sso.php, library/sso/togahub_private_key.key |
+| [Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)](features/cron-execution-monitoring.md) | `App_Framework::cronInitialization()` / `App_Framework::cronFinished()` (in `library/app/framework.php`) give every 1.0 (`App_`) cron job a check-in/check-out l | library/app/framework.php |
 | [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | `App_Model_Toga_Diagnostic::initializeDiagnosticDialog()` renders the device modal used across all TOGa service request views. | library/app/model/toga/diagnostic.php |
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |

package/knowledge/1.0/apps/library/features/cron-execution-monitoring.md

@@ -0,0 +1,71 @@
+---
+title: Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-07-06
+owners: [dfranks]
+files:
+  - library/app/framework.php
+related:
+  - ../../worker/architecture.md
+---
+
+## Summary
+
+`App_Framework::cronInitialization()` / `App_Framework::cronFinished()` (in
+`library/app/framework.php`) give every 1.0 (`App_`) cron job a check-in/check-out
+lifecycle recorded in the **`CronJobExecutions`** table in **`db_common`**. On start the job
+INSERTs an execution row; on finish it UPDATEs that row with completion state and an
+`executionTimeSeconds` duration. This is the shared-DB monitoring surface for 1.0 crons
+across all 1.0 apps (worker, togadesk, toga, …), independent of the older `Log`/`CRON_START`
+row in `db_log` and of the per-job Sentry check-in monitors.
+
+## How it works
+
+- **`cronInitialization()`** — INSERTs one row into `CronJobExecutions` (`db_common`) via the
+  execution-id registry variable, records start time, and returns/stores the execution id used
+  to close the row later.
+- **`cronFinished()`** — UPDATEs the same `CronJobExecutions` row (matched by execution id)
+  with completion status and `executionTimeSeconds`.
+- **Connection:** every `CronJobExecutions` read/write goes against **`db_common`**. The table
+  exists **only** in `db_common` — it does **not** exist on the `db_log` connection.
+- **Duration precision:** `executionTimeSeconds` is `round(microtime(true) - $start, 3)` —
+  millisecond precision landing in a `decimal(10,3)` column. Do **not** `(int)`-cast it; the
+  cast silently discards the sub-second precision even when the schema column is `decimal(10,3)`.
+- **Schema:** the table is provisioned by the dbchanges migration
+  `dbchanges/Common/DF/2026-5-7 Cron Checkin.sql` (table `CronJobExecutions`,
+  `executionTimeSeconds decimal(10,3)`, no `note` column).
+- **Design decision:** 1.0 records executions by writing **directly to the shared DB**
+  (`db_common`), *not* by POSTing from 1.0 to a 2.0 API endpoint. Per Jeff Cardinal, 1.0 code
+  must not POST to 2.0 code; the direct shared-DB write is the sanctioned path (TRUE-78182).
+
+## Gotchas
+
+- **`db_log` has no `CronJobExecutions` table.** A `cronFinished()` UPDATE that runs against the
+  `db_log` connection throws on **every** 1.0 cron job. Both the INSERT and the UPDATE must
+  target `db_common`.
+- **A `git merge` can silently resurrect pre-refactor logic.** These functions were cleanly
+  consolidated to a single `db_common`-only INSERT/UPDATE pair (commit `0a3a6f75`), but a later
+  `git merge origin/_production` (`509614036605…`) reintroduced the old dual-path structure from
+  `_production`'s still-unmigrated copy of the file — leaving duplicate INSERT/UPDATE blocks, and
+  reverting one path's connection argument back to `db_log`. Automatic merge resolution updated
+  the SQL text (renamed the table) but restored the wrong connection name, producing a
+  platform-wide breaking bug disguised as a simple PR-feedback rework. **When a merge touches a
+  function you already refactored on your branch and the base branch never got that refactor,
+  diff against the merge-base — do not just eyeball the current file** — to catch resurrected
+  logic. (Fixed 2026-07-06: consolidated back to one `db_common` INSERT/UPDATE pair.)
+
+## Change history
+- 2026-07-06 — Fixed a merge (`origin/_production`) that reintroduced duplicate
+  `CronJobExecutions` writes and pointed one `cronFinished()` UPDATE at `db_log` (where the
+  table doesn't exist), which would have thrown on every 1.0 cron. Consolidated to one
+  `db_common` INSERT/UPDATE pair and switched `executionTimeSeconds` to `round(…, 3)` for the
+  `decimal(10,3)` precision the migration provides. (dfranks, TRUE-78182)
+- 2026-05-07 — Introduced `CronJobExecutions` check-in/out in `App_Framework` cron lifecycle;
+  direct `db_common` write chosen over a 1.0→2.0 API POST. (dfranks)
+</content>
+</invoke>

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

@@ -7,6 +7,7 @@
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
+| [Error Reporting — Issue/Event Aggregation (exceptionHandler)](features/error-reporting-issue-event.md) | `_underscore`'s global exception handler persists every uncaught exception into a two-table **Issue / Event** model in the **shared Core Logs DB** (`_underscore | _underscore/Error.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, dbchanges2/Logs/2026-07-06 - Issue and Event tables.sql |
 | [Record-Changed Event Publishing (_Event::publish to SQS)](features/event-publish-sqs.md) | `_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event pipeline. | _underscore/Event.php |
 | [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/probe_je_shape.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [Item-Fulfillment Stage Lifecycle (picked/packed/shipped) & Order Status](features/item-fulfillment-stage-lifecycle-and-order-status.md) | Every ItemFulfillment (IF) now carries an explicit **stage** — picked → packed → shipped — resolved through `ItemFulfillmentStages → ItemFulfillmentStatuses` (m | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Client/SalesOrderItem.php, _underscore/Model/Client/Item.php, _underscore/Model/Client/PurchaseOrderItem.php, library/app/api/toga2.php, dbchanges2/Client/2026-06-30a - BackfillNullStageItemFulfillmentsToShipped.sql, dbchanges2/Client/2026-06-30b - SalesOrderStatusesPickedPacked.sql, dbchanges2/Client/2026-06-30c - ItemFulfillmentStageIdNotNull.sql, dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql |

package/knowledge/2.0/apps/_underscore/features/error-reporting-issue-event.md

@@ -0,0 +1,95 @@
+---
+title: Error Reporting — Issue/Event Aggregation (exceptionHandler)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-06
+owners: ["dfranks"]
+files:
+  - _underscore/Error.php
+  - _underscore/Model/Core/Logs/Issue.php
+  - _underscore/Model/Core/Logs/Event.php
+  - dbchanges2/Logs/2026-07-06 - Issue and Event tables.sql
+related:
+  - ../architecture.md
+  - ./per-client-database-connections.md
+  - ../../dbchanges2/architecture.md
+---
+
+## Summary
+
+`_underscore`'s global exception handler persists every uncaught exception into a
+two-table **Issue / Event** model in the **shared Core Logs DB** (`_underscore::DB_LOGS`,
+models under `Model/Core/Logs/`) — **not** the per-client Logs DB. An **Issue** is the
+deduplicated record for a distinct error (keyed by a hash of the backtrace) carrying an
+aggregate `occurrences` counter; an **Event** is one row per individual occurrence with
+its own stack trace and context. This is platform-wide error-reporting infrastructure,
+not client-specific.
+
+## Key files / entry points
+
+- **`_underscore/Error.php`** — `exceptionHandler()` (registered via
+  `set_exception_handler`). Computes `$issueHash = md5(serialize($backtrace))`, then, only
+  when the Core-Logs register is present (`isset(\_Database::$_registers[_underscore::DB_LOGS])`),
+  upserts an `_Model_Core_Logs_Issue` and inserts an `_Model_Core_Logs_Event`, committing
+  the `DB_LOGS` transaction.
+- **`_underscore/Model/Core/Logs/Issue.php`** — `const DATABASE = _underscore::DB_LOGS;
+  const TABLE = 'Issues';`. Fields: `id, uuid, dtCreated, dtLastOccurred, urgency, subject,
+  description, clickupIdentifier, hash, errorMessage, occurrences, trace`.
+- **`_underscore/Model/Core/Logs/Event.php`** — `const DATABASE = _underscore::DB_LOGS;
+  const TABLE = 'Events';`. Fields: `id, uuid, issueId (FK → Issue), errorMessage, trace,
+  context, dtCreated`.
+
+## How it works
+
+1. On an uncaught exception, hash the backtrace to identify the distinct error.
+2. Load the existing `Issue` by `hash`. On a miss, create it with `errorMessage`, `trace`,
+   `urgency = 'LOW'`, and `occurrences = 0`.
+3. **Increment `occurrences`** (`($issue->occurrences ?? 0) + 1`) and set
+   `dtLastOccurred`, then save — so the counter advances on every occurrence, hit or new.
+4. Insert one `Event` for this occurrence: `issueId`, `errorMessage`, per-occurrence
+   `trace`, and `context` (`print_r($GLOBALS, true)`).
+5. Commit the `DB_LOGS` transaction; surface `Error {issueId}, Event {eventId}` in the
+   debug body.
+
+The `Issues`/`Events` tables live in the shared **Core Logs** DB, provisioned from
+`dbchanges2/Logs/` (the `Logs/` folder targets the framework-level, non-tenant `Logs` DB
+with unqualified table names — see the dbchanges2 architecture folder→DB mapping). Contrast
+with per-client API/error logging in `Logs_<Tenant>` via `Model/Client/Logs/*`
+(`DB_CLIENT_LOGS`, `dbchanges2/Logs_Client/`).
+
+## Data model
+
+- **Issue** = one row per distinct error (dedup key = `hash`); `occurrences` is the rolling
+  count, `dtLastOccurred` the most-recent hit, `urgency` a list field, `clickupIdentifier`
+  links to an escalation ticket. There is **no `type` column** — it was dropped.
+- **Event** = one row per occurrence, FK `issueId` → Issue, carrying the occurrence's own
+  `trace` and `context`.
+
+## Gotchas / known issues
+
+- **`occurrences` must be incremented, not just seeded.** It was previously set to `0` only
+  at creation and never advanced, so the aggregate counter never moved. Fixed 2026-07-06 to
+  increment on every occurrence.
+- **`Event.trace` must be set per occurrence.** The schema has a per-Event `trace` column
+  that was never populated; now recorded on every Event.
+- **Persistence is conditional on the Core-Logs register.** If
+  `\_Database::$_registers[_underscore::DB_LOGS]` isn't set, the whole Issue/Event block is
+  skipped silently — no error row is written.
+- **Shared-schema migration collision.** Because `Issues`/`Events` live in the *shared* Core
+  Logs DB, any two dbchanges2 `Logs/` migrations that both `CREATE TABLE Issues`/`Events`
+  will collide — the second fails with "table already exists". Two separate error-reporting
+  workstreams introduced these same tables (one adding the escalation cron + an
+  `IssueEmailAddresses` table, one adding this error-class persistence). Only **one**
+  migration may create the shared tables; reconcile overlapping `Logs/` create-scripts at
+  merge so the tables are created exactly once and later migrations only `ALTER`.
+
+## Change history
+
+- 2026-07-06 — Moved Issue/Event tables and exceptionHandler persistence from the per-client
+  Logs DB to the shared Core Logs DB and dropped the `type` column; fixed `occurrences` to
+  increment each occurrence and set `Event.trace` per occurrence; removed dead commented-out
+  per-client-logs persistence block. (dfranks)

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 10 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 11 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 12 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 8 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
@@ -16,7 +16,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 21 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 22 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 25 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 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.267",
+  "version": "1.0.269",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",