toga-ai 1.0.311 → 1.0.313

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

@@ -11,5 +11,6 @@
 | [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t | library/app/framework.php, library/app/frameworkindex.php, library/app/mvc.php, library/app/database.php, library/app/model.php, library/app/config.php |
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem, test/@dave/Junk Drawer/nsq.php |
 | [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. | library/app/api/netsuite/rest.php |
+| [NetSuite Sync Alert Monitor (App_SystemMonitor_NetSuiteIntegration)](features/netsuite-sync-alert-monitor.md) | `App_SystemMonitor_NetSuiteIntegration` (`library/app/systemmonitor/netsuiteintegration.php`, title **"NetSuite Sync Alert"**) is a 1.0 system monitor that watc | library/app/systemmonitor/netsuiteintegration.php, worker/crons/infrastructure/system_monitors.php |
 | [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | `library/app/api/toga2.php` handles bidirectional ticket sync for PC Matic B2B between TOGaDesk 1.0 and TOGA 2.0. | library/app/api/toga2.php, library/app/api/startechticket.php, worker/crons/toga2/startech/common_import_supporting_records.php |
 | [App_Api_Toga2 — TOGa2 API Client & 1.0↔2.0 Sync Bridge](features/toga2-api-client-and-bridge.md) | `App_Api_Toga2` (`library/app/api/toga2.php`, ~8400 lines) is the **1.0-side client for the TOGa 2 (`_underscore`/api2) public API** *and* the home of the cross | library/app/api/toga2.php, worker/crons/toga2/aig/sync_togasupply_aig.php, worker/crons/toga2/wje/sync_togasupply_wje.php |

package/knowledge/1.0/apps/library/features/netsuite-sync-alert-monitor.md

@@ -0,0 +1,116 @@
+---
+title: NetSuite Sync Alert Monitor (App_SystemMonitor_NetSuiteIntegration)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-07-10
+owners: ["bala"]
+files:
+  - library/app/systemmonitor/netsuiteintegration.php
+  - worker/crons/infrastructure/system_monitors.php
+related:
+  - ../../worker/features/netsuite-togasupply-per-client-sync.md
+  - cron-execution-monitoring.md
+  - toga2-api-client-and-bridge.md
+---
+
+## Summary
+
+`App_SystemMonitor_NetSuiteIntegration` (`library/app/systemmonitor/netsuiteintegration.php`,
+title **"NetSuite Sync Alert"**) is a 1.0 system monitor that watches every TOGa Supply
+client's NetSuite sync checkpoints and opens/updates a ClickUp task when any checkpoint goes
+stale. It reads each client's six `NETSUITE_LAST_SYNC_DATETIME_*` parameters over the TOGa2
+REST API and flags any older than **48h** (`STALE_THRESHOLD_SECONDS`). It is the alerting
+surface sitting on top of the [NetSuite → TOGa Supply per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md);
+that worker job does the syncing, this library class notices when it stops.
+
+## Key files / entry points
+
+- **`library/app/systemmonitor/netsuiteintegration.php`** — the monitor class. Extends
+  `App_SystemMonitor`. Holds the hardcoded per-client allowlist (`CLIENT_CONFIGURATIONS`),
+  the checkpoint key list (`NETSUITE_SYNC_PARAMETER_KEYS`), the 48h threshold, and all
+  ClickUp task create/update logic.
+- **`worker/crons/infrastructure/system_monitors.php`** — the shared dispatcher (runs once a
+  minute). It instantiates every active monitor and calls `getStatus()`. This monitor is
+  registered there as `new App_SystemMonitor_NetsuiteIntegration`.
+
+## How it works
+
+- **Schedule.** `minuteFrequency = 60`, `minHourToRun = 10`, `maxHourToRun = 17` — so its
+  only tick is the **top of each hour**, 10:00–17:00. There is exactly one run per hour; if
+  that run dies, the monitor produces nothing until the next hour.
+- **`getStatus()`** iterates `CLIENT_CONFIGURATIONS`, calls `getClientStatus()` per client,
+  and returns OK only if **every** client is OK (messages joined with `<br>`).
+- **`getClientStatus()`** reads all six `NETSUITE_SYNC_PARAMETER_KEYS` for the client in a
+  **single** TOGa2 `GET /parameters` call using the options `where..in` DSL
+  (`['where' => ['AND' => [['key' => ['in' => KEYS]]]]]`), then compares each `value`
+  (`strtotime`) against `time() - STALE_THRESHOLD_SECONDS`. Any checkpoint older than 48h is
+  collected as stale.
+- **`extractParameterRows()`** normalizes the api2 response: a single match comes back as an
+  **object**, many matches as an **array** — this helper always returns an array to iterate
+  (guarding on `isSuccess` + `data->parameters`).
+- **`reportStaleParametersToClickUp()`** resolves the current True Dev sprint list, then for
+  each stale checkpoint creates or updates one ClickUp task titled
+  `"<client name> - <PARAMETER_KEY> Error"`. Existing tasks are matched by that exact title
+  and updated in place (description + Last Occurrence + incremented Occurrences), so repeated
+  stalls don't duplicate tasks. One task per client + sync type.
+
+## Data model
+
+- **Monitored clients** — hardcoded in `CLIENT_CONFIGURATIONS` (each entry = plain-English
+  `name` + the client/api/secret consts from `App_Api_Toga2`). Only clients in this array are
+  ever checked; anything omitted is invisible to the monitor. As of 2026-07-10 the list holds
+  15 clients: Canon, Endeavor Health, NYCHH, Trividia, Prudential-EDI, Broward Sheriff's
+  Office, Miami-Dade, Compass Group, S&P Global, ERAU, Masonite, NCCI, SHRSS, SBA, Quad,
+  Growrk. **AIG is deliberately excluded** (see the sync doc's AIG gotcha — a held account
+  whose checkpoints never advance, so it would alert forever).
+- **Checkpoints** — the six `NETSUITE_LAST_SYNC_DATETIME_{SALES_ORDERS,PURCHASE_ORDERS,INVOICES,ITEM_RECEIPTS,ITEM_FULFILLMENTS,INVENTORY_ADJUSTMENTS}`
+  parameters, written per client by `common_sync_togasupply.php` and read here over the API.
+- **Reporting state** — the dispatcher records `lastReported` / `lastStatus` /
+  `lastMessage` per monitor in the **`SystemMonitors`** table in **`db_log`** (title
+  "NetSuite Sync Alert"). ClickUp tasks land in the current True Dev sprint list.
+
+## Gotchas / known issues
+
+- **A monitor that can't finish inside the cron budget silently never runs.** The dispatcher
+  calls `App_Framework::cronInitialization(300, true)` — a hard **300s** budget shared across
+  **all** monitors in one process. When each of the six checkpoints was read in its own
+  `/parameters` call (14 clients × 6 = 84 serialized ~2.7s calls ≈ 230s), the whole
+  `system_monitors.php` run blew the budget and was killed mid-execution. Because this
+  monitor's only tick is the top of the hour — the exact run that died — it never completed
+  and **never reported**. Fixed 2026-07-10 by reading all six keys per client in one
+  `where..in` call (~230s → ~40s). If you add more clients/keys or more per-client calls,
+  watch the total against 300s.
+- **Two silent-failure traps hide a dead monitor.** (1) The dispatcher wraps `getStatus()` in
+  `catch (Exception)` and on a throw sets `$status = array(true, 'Unexpected error occurred')`
+  — a **thrown monitor is recorded OK**, not ALERT. (2) A run killed by the time limit records
+  nothing at all (no `cronFinished()`). Either way the monitor looks fine while doing nothing.
+- **"Seeded/listed but not reporting = dead monitor."** To catch this: check
+  `SystemMonitors.lastReported` in `db_log` — if this monitor's row is stale while every other
+  monitor is current, its hourly run is dying. Cross-check the cron log
+  (`Vision_Log.Log`, `sourceJob LIKE '%system_monitors%'`) for a **Started without a Finished**
+  on the heavy runs. This is exactly how the 2026-06-29 → 07-10 blind period was found:
+  `lastReported` was frozen at 2026-06-29 14:19 while everything else advanced.
+- **Hardcoded ClickUp API token in source.** `CLICK_UP_API_ACCESS_TOKEN` is a literal constant
+  in this file (pre-existing). It should be moved to config/secrets rather than living in the
+  class — treat the in-repo token as compromised if the repo leaks. (Documenting that it
+  exists and where; the value itself must never be copied into the KB.)
+- **Adding a client here is not the same as onboarding it to the sync.** This list only
+  controls *alerting*. A client must actually be provisioned on the sync engine (wrapper +
+  schedule + Parameters seed + customer link + custom fields — see the sync doc) before its
+  checkpoints mean anything; and a client that is held / never transacts supply (AIG) must be
+  left **off** this list or it produces permanent false-positive tickets.
+
+## Change history
+
+- 2026-07-10 — **Fixed the monitor timing out and silently not running since 2026-06-29.**
+  Rewrote `getClientStatus()` to read all six checkpoints per client in one TOGa2
+  `where..in` `/parameters` call (was 84 serialized calls ≈ 230s, over the 300s
+  `system_monitors.php` budget → killed every hourly run); added `extractParameterRows()` to
+  normalize api2's single-object-vs-array response. Run dropped ~230s → ~40s (verified
+  read-only against prod, 41.2s). Added **Quad** and **Growrk** to `CLIENT_CONFIGURATIONS`
+  (previously unmonitored); **AIG deliberately left off** (held account, would alert forever).
+  Documented the dead-monitor detection path and the two silent-failure traps. (bala)

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -153,11 +153,27 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   (e.g. this parse error), not per-client data. When the fix deploys, MODE flips to RUNNING and the
   watermark jumps to ~now on completion (a positive live signal); the sync self-recovers and
   backfills the gap.
-- **Monitoring blind spot — not every client is in the NetSuite sync monitor.**
+- **The NetSuite sync monitor's coverage is a per-client allowlist.**
   `App_SystemMonitor_NetSuiteIntegration` (`library/app/systemmonitor/netsuiteintegration.php`)
-  alerts ClickUp when any client's checkpoint is >48h stale, but its `CLIENT_CONFIGURATIONS` list
-  (~line 16) **omits Quad, AIG, and Growrk**. Their stalls raise no alert (Quad's 3-day July-2026
-  outage went unflagged for that reason). Follow-up: add Quad/AIG/Growrk to `CLIENT_CONFIGURATIONS`.
+  alerts ClickUp when any client's checkpoint is >48h stale, but it only checks the clients in
+  its hardcoded `CLIENT_CONFIGURATIONS` list — an unlisted client's stall raises no alert.
+  Quad and Growrk were added 2026-07-10 (previously omitted); **AIG is deliberately left off**
+  because it's a held account whose checkpoints never advance (see the AIG gotcha) and would
+  alert forever. Full monitor mechanics + its own silent-failure traps live in the
+  [NetSuite Sync Alert Monitor doc](../../library/features/netsuite-sync-alert-monitor.md).
+- **Item Fulfillments + Inventory Adjustments syncs are stalled across most togasupply clients
+  (real stalls, not disabled/false positives) as of 2026-07-10.**
+  `NETSUITE_LAST_SYNC_DATETIME_ITEM_FULFILLMENTS` has been frozen since ~2026-04-28/05-05 and
+  `NETSUITE_LAST_SYNC_DATETIME_INVENTORY_ADJUSTMENTS` since ~2026-06-12/20 on **Canon,
+  Endeavor, Trividia, Miami-Dade, S&P, ERAU, NCCI, SHRSS** and **Growrk (IF/InvAdj)**, while
+  **Prudential-EDI** is fully frozen (all six checkpoints) since ~2026-06-20. The other four
+  sync types (sales orders, POs, invoices, item receipts) advance normally for these clients.
+  All wrappers have `IS_ENABLED_INTEGRATION_ITEM_FULFILLMENTS = true` and
+  `IS_ENABLED_INTEGRATION_INVENTORY_ADJUSTMENTS = true`, so the IF/InvAdj sections are
+  **erroring while the others succeed** — a real data issue, not a disabled integration type.
+  Healthy across all six: **NYCHH, Broward, Compass, Masonite, SBA.** When the fixed monitor
+  runs, expect it to surface these as ~24 legitimate ClickUp tickets on its first successful
+  pass.
 - **Seeded-but-stale = stalled sync.** Verify health by reading `LAST_SYNC_DATETIME_*` in each
   `Client_<Id>.Parameters`: a healthy client advances to ~now every 5 min. As of 2026-06-17,
   Quad was seeded but frozen at 2025-04/05 (not advancing) while the other 12 deployed clients
@@ -175,9 +191,19 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   opportunity/entitlement account, not a procurement/supply customer. Lesson: before onboarding a
   client, confirm it actually transacts supply orders in NetSuite (SuiteQL the `customer`'s
   transaction history) — being in the array doesn't mean it belongs on this engine.
+  Confirmed again 2026-07-10: `Client_Aig`'s six checkpoints are all still frozen at exactly
+  the seed date `2026-04-28 00:00:00` (never advanced), which is why AIG is **deliberately
+  excluded** from the NetSuite Sync Alert monitor — including it would generate permanent
+  false-positive stale tickets.
 
 ## Change history
 
+- 2026-07-10 — Added **Quad + Growrk** to the NetSuite Sync Alert monitor's
+  `CLIENT_CONFIGURATIONS` (previously unmonitored); **AIG deliberately left off** (held
+  account, checkpoints frozen at the 2026-04-28 seed). Recorded a real, ongoing IF/InvAdj
+  stall across most togasupply clients (Prudential-EDI fully frozen) surfaced during the
+  monitor fix — see the new gotchas. Monitor mechanics moved to their own
+  [library feature doc](../../library/features/netsuite-sync-alert-monitor.md). (bala)
 - 2026-07-09 — **Tier-wide outage (2026-07-06 → 07-09): a dropped brace in shared `rest.php`
   killed every client's sync for 3 days.** A bad merge (`c3caa11a`, "Merge branch '_production'
   into TRUE-79078", 2026-06-24) silently dropped two tokens at the `listLocations()` /

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

@@ -23,7 +23,7 @@
 | [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 |
-| [Talos Transcript Ingestion Pipeline (worker2 → AWS Bedrock KBs)](features/talos-transcript-ingestion.md) | `_Worker_Team_Transcripts` runs a fully automated, cron-driven pipeline that ingests raw Teams transcripts into the **Talos / TOGa IQ** AWS Bedrock knowledge ba | worker2/Worker/Team/Transcripts.php, worker2/bin/sync-knowledge-bases.php, worker2/Config/production.ini, dbchanges2/Team/2026-06-30a, dbchanges2/Team/2026-06-30b, dbchanges2/Team/2026-06-30c, dbchanges2/Team/2026-06-30d, dbchanges2/Team/2026-06-30e, dbchanges2/Core/2026-06-30a, dbchanges2/Core/2026-07-02a, dbchanges2/Team/2026-07-02a, dbchanges2/Team/2026-07-08a, dbchanges2/Team/2026-07-09a |
+| [Talos Transcript Ingestion Pipeline (worker2 → AWS Bedrock KBs)](features/talos-transcript-ingestion.md) | `_Worker_Team_Transcripts` runs a fully automated, cron-driven pipeline that ingests raw Teams transcripts into the **Talos / TOGa IQ** AWS Bedrock knowledge ba | worker2/Worker/Team/Transcripts.php, worker2/bin/sync-knowledge-bases.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Team/2026-06-30a, dbchanges2/Team/2026-06-30b, dbchanges2/Team/2026-06-30c, dbchanges2/Team/2026-06-30d, dbchanges2/Team/2026-06-30e, dbchanges2/Core/2026-06-30a, dbchanges2/Core/2026-07-02a, dbchanges2/Team/2026-07-02a, dbchanges2/Team/2026-07-08a, dbchanges2/Team/2026-07-09a, dbchanges2/Team/2026-07-10a |
 | [Team Sprint Management & Reporting](features/team-sprint-management.md) | `_Worker_Team_Sprint` (file `Worker/Team/Sprint.php`) is the engine behind TOGA's internal **development-sprint process and reporting**. | worker2/Worker/Team/Sprint.php |
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | > **SUPERSEDED (2026-07-09) — the S3-staging model below is history.** `Export` is now a thin > **GRAPH-DIRECT** cron poller: it no longer archives raw VTT to ` | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Core/2026-06-18a - Teams Transcript Export schedule.sql |
 | [VAPI Webhook Handler (worker2 — AI-BDR end-of-call processing)](features/vapi-webhook-handler.md) | `_Worker_Vapi` ([worker2/Worker/Vapi.php](worker2/Worker/Vapi.php)) is the **PHP side of the AI-BDR call loop** — the webhook that receives VAPI's end-of-call r | worker2/Worker/Vapi.php, worker2/Worker/Ai/Bdr/Vapi.php |

package/knowledge/2.0/apps/worker2/features/talos-transcript-ingestion.md

@@ -6,12 +6,13 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-09
+updated: 2026-07-10
 owners: [jcardinal]
 files:
   - worker2/Worker/Team/Transcripts.php
   - worker2/bin/sync-knowledge-bases.php
   - worker2/Config/production.ini
+  - worker2/Database/TeamsTranscriptExports.sql
   - dbchanges2/Team/2026-06-30a
   - dbchanges2/Team/2026-06-30b
   - dbchanges2/Team/2026-06-30c
@@ -22,6 +23,7 @@ files:
   - dbchanges2/Team/2026-07-02a
   - dbchanges2/Team/2026-07-08a
   - dbchanges2/Team/2026-07-09a
+  - dbchanges2/Team/2026-07-10a
 related:
   - ./teams-transcript-export.md
   - ./notification-email-template.md
@@ -65,20 +67,48 @@ JSON that PHP renders to an inline-styled HTML recap email, enqueued to the orga
 ## How it works
 
 ### `Export(int $lookbackDays, ?int $limit = null, array $cc = [], array $bcc = [])` (cron)
-Thin poller. The old `organizers` parameter was **REMOVED** — organizers are always resolved
-from config now.
-1. For each configured organizer, poll Microsoft Graph for transcripts in the lookback window.
-2. Resolve the organizer email (see *Organizer email resolution*).
-3. Record a discovery-ledger row in `Team.TranscriptExports` — **synchronously, then
-   committed** (see the durability gotcha).
-4. Enqueue one `Process` job per transcript.
+Thin poller with a **quiet-period stability gate** — it does **not** enqueue a transcript on
+first sight (that processed still-in-progress meetings and emailed half-meeting recaps). The old
+`organizers` parameter was **REMOVED** — organizers are always resolved from config now.
+
+**Why a gate is needed:** the Graph `callTranscript` object carries **no "meeting ended"
+signal** — only `id, meetingId, createdDateTime, transcriptContentUrl, meetingOrganizer` (no
+`endDateTime`, no `duration`, no `status`, verified against Graph v1.0 `onlineMeeting:
+getAllTranscripts`). Teams keeps **appending to the VTT while the meeting is live**.
+`onlineMeeting.endDateTime` is only the **scheduled** end and for recurring meetings is the
+series anchor (same unreliability that already rules out `startDateTime` for the meeting date).
+So the only reliable end proxy is **that the transcript content stopped growing**.
+
+**Observe-until-stable**, per organizer, per transcript:
+1. Skip immediately if already handed off (`dtEnqueued` set) — **no re-download**.
+2. Otherwise download the VTT **only to measure `strlen` (byte size)**.
+3. First sighting → `recordObservation()` (INSERT, `dtEnqueued` NULL) and **defer**.
+4. Size grew since last poll → still live → `updateObservationSize()` (resets the
+   `dtLastChanged` anchor) and **defer**.
+5. Size unchanged for `>= TRANSCRIPT_STABLE_QUIET_SECONDS` (const = **1200s / 20 min**) →
+   meeting ended → `markEnqueued()` (stamps `dtEnqueued`, commit) then enqueue one
+   `Team/Transcripts/Process` job. At the hourly Export cron cadence this is effectively
+   "second poll with unchanged size ⇒ process," with the 20-min floor guarding against
+   unusually frequent polls.
 
 - `$limit` caps enqueues per run (mainly for testing; e.g. `1` = a single meeting).
 - `cc` / `bcc` thread through each `Process` job into the recap email; validated in
   `enqueueRecapEmail` (deduped, organizer excluded). **Fallback:** if the organizer email
   can't be resolved but `cc` is present, the recap sends **TO** the cc addresses.
-- A Graph `callTranscript` already recorded (`alreadyExported()`) is skipped. Export treats a
-  Duplicate-entry exception as **"skipped"**, not a hard error.
+
+**Watermark (`resolveWatermark`) — must not skip past an open observation.** The per-organizer
+Graph window start takes `MIN(dtCreated)` over **open** observations (`dtEnqueued IS NULL`),
+falling back to `MAX(dtCreated)` over handed-off rows, minus the 1-min overlap. Without this a
+long meeting whose `createdDateTime` predates a newer already-handed-off meeting falls outside
+the Graph date filter and gets stuck "observing" forever.
+
+**Private helpers (Transcripts.php):** `loadObservation` (`useQueryCache(false)`; returns
+`id,sizeBytes,dtLastChanged,dtEnqueued,meetingSubject,organizerEmail`), `recordObservation`
+(replaces `recordExport`; synchronous + `_Database::transactionCommit(DB_TEAM)`),
+`updateObservationSize`, `markEnqueued`, `meetingFor` (memoized `getMeeting` wrapper),
+`secondsSince` (parses a MySQL UTC datetime with `' UTC'` suffix → elapsed seconds).
+`alreadyExported()` and `recordExport()` were **removed** (superseded by the observation
+helpers).
 
 ### `Process(int $transcriptId, string $graphUserId, string $meetingId, string $organizerEmail, string $subject, string $meetingStartIso, array $cc = [], array $bcc = [])`
 1. Download the VTT **straight from Graph** (no S3 round trip).
@@ -128,12 +158,27 @@ spacing (Bedrock allows only one in-flight ingestion per KB, so parallel syncs r
 - **`Team.TranscriptPromptTemplate`** — `name, bodyText, instruction, model, temperature, …`.
 - **`Team.KnowledgeBases`** — `slug, name, isGeneral, bedrockKbId, isActive`; auto-kept-current
   from Bedrock by the daily `SyncKnowledgeBases`.
-- **`Team.TranscriptProcessing`** — pipeline ledger + idempotency. `status` ENUM
-  (`pending/cleaned/uploaded/archived/synced/failed`). **`transcriptIdentifier` widened to
-  `VARCHAR(768)`** (dbchanges2 `Team/2026-07-09a`).
-- **`Team.TranscriptExports`** — discovery ledger written by `Export`.
-  `transcriptIdentifier` **also widened to `VARCHAR(768)`**. Graph-direct columns +
-  `organizerEmail` added (dbchanges2 `Team/2026-07-08a`).
+**The two tables are BOTH live and NOT redundant** — different owners, different jobs:
+
+- **`Team.TranscriptExports`** — **discovery/observation ledger** owned by `Export()`: drives
+  the per-organizer watermark, transcript dedupe, and the quiet-period observation. Keyed on
+  `transcriptIdentifier` (widened to `VARCHAR(768)`, dbchanges2 `Team/2026-07-09a`).
+  Quiet-period columns (dbchanges2 `Team/2026-07-10a`): `sizeBytes` **repurposed** as the
+  last-observed raw VTT byte count; `dtLastChanged` (the quiet-period anchor); `dtEnqueued`
+  (**NULL = still observing; non-NULL = handed off**, the new done-marker). Dead column
+  `s3Key` **dropped** (leftover from the removed S3-staging scheme, no code refs).
+- **`Team.TranscriptProcessing`** — **pipeline state machine** owned by `Process()`: `status`
+  ENUM (`pending/cleaned/uploaded/archived/synced/failed`), KB result keys
+  (`kbSlug/approvedKey/archiveKey/aiModel/failureReason`), and its own
+  `transcriptIdentifier`-keyed idempotency (also `VARCHAR(768)`). Dead column `sourceKey`
+  (and its unique index) **dropped** (removed S3-staging leftover).
+
+**Dedupe key rule:** recurring meetings **reuse the same `meetingIdentifier`** but get a
+**new `transcriptIdentifier` per occurrence**, so dedupe MUST stay keyed on
+`transcriptIdentifier`, never `meetingIdentifier`.
+
+**Migration ordering (`Team/2026-07-10a`):** ADD columns → backfill
+`dtEnqueued=dtExported` on existing rows → DROP `s3Key` → DROP INDEX + `sourceKey`.
 
 ## Configuration
 
@@ -146,6 +191,20 @@ part of the ingestion loop** (raw reads removed). Credential values live only in
 
 ## Gotchas / known issues
 
+- **DEPLOY ORDER: apply migration `2026-07-10a` BEFORE deploying the new worker2 code.** The
+  code reads/writes `dtEnqueued`/`dtLastChanged`; deploying code first errors on every poll.
+  The migration also backfills every existing row as handed-off (`dtEnqueued=dtExported`) so
+  no historical or legacy-duplicate row is re-observed or re-processed.
+- **Root cause of the earlier "same meeting processed multiple times" duplicate rows.**
+  Diagnosed from prod `Team.TranscriptExports` rows 573/577 (same "Craftex Open Items"
+  meeting): row 573's `transcriptIdentifier` was truncated to exactly 255 chars and is the
+  byte-for-byte prefix of row 577's full 304-char id. These were pre-`2026-07-09a` truncated
+  rows; the removed `alreadyExported()` compared the full 304-char id and never matched the
+  truncated stored value, so the meeting re-enqueued. The `2026-07-09a` widen fixed it going
+  forward but left stale truncated rows that could never match. Across the table 42
+  `meetingIdentifier`s had duplicates (lengths 56/255/304) — a mix of truncation artifacts and
+  **legitimate recurring occurrences** (recurring reuses `meetingIdentifier`, new
+  `transcriptIdentifier` each time). `2026-07-10a`'s backfill marks all historical rows inert.
 - **Idempotency: 304-char Graph ids truncated at `VARCHAR(255)` (root cause of endless
   reprocessing).** Graph `callTranscript` ids are ~304 chars; `transcriptIdentifier` columns
   were `VARCHAR(255)`, so ids were silently truncated. `alreadyExported()` compared the full
@@ -183,6 +242,20 @@ part of the ingestion loop** (raw reads removed). Credential values live only in
 
 ## Change history
 
+- 2026-07-10 — **Added the quiet-period stability gate to `Export`** so in-progress meetings
+  are no longer processed (was emailing half-meeting recaps). `callTranscript` has no
+  end-of-meeting signal, so `Export` now observes each transcript's VTT byte size and only
+  hands off (enqueues `Process`) once size is unchanged for `TRANSCRIPT_STABLE_QUIET_SECONDS`
+  (1200s). New `TranscriptExports` columns `dtLastChanged`/`dtEnqueued` + repurposed
+  `sizeBytes`; new helpers (`recordObservation`, `updateObservationSize`, `markEnqueued`,
+  `loadObservation`, `meetingFor`, `secondsSince`); removed `alreadyExported`/`recordExport`.
+  `resolveWatermark` now floors at `MIN(dtCreated)` of open observations so a long meeting
+  can't fall out of the Graph window. Confirmed both `Team` tables are non-redundant
+  (Exports = discovery/observation, Processing = pipeline state machine); dropped dead columns
+  `TranscriptExports.s3Key` and `TranscriptProcessing.sourceKey`. Diagnosed the prior
+  duplicate-row root cause (pre-`2026-07-09a` truncated ids never matched; dedupe must stay
+  keyed on `transcriptIdentifier`, never `meetingIdentifier`). **Apply `2026-07-10a` before
+  deploying the code.** dbchanges2: `Team/2026-07-10a`. (jcardinal)
 - 2026-07-09 — **Re-architected to GRAPH-DIRECT.** `Export` is now a thin cron poller
   (removed the `organizers` param; added `$limit`, `cc`/`bcc`); `Scan` and
   `bin/reprocess-transcripts.php` deleted; the `toga-private` staging bucket dropped entirely.

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)_ — 11 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 12 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 14 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 9 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)

package/package.json

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