toga-ai 1.0.233 → 1.0.235

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

@@ -7,7 +7,8 @@
 | [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/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.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 |
-| [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/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
+| [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 |
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |

package/knowledge/2.0/apps/_underscore/features/event-publish-sqs.md

@@ -0,0 +1,60 @@
+---
+title: Record-Changed Event Publishing (_Event::publish to SQS)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-29
+owners: [rgirish]
+files:
+  - _underscore/Event.php
+related:
+  - ../../../../standalone/apps/websocket/features/sqs-fanout.md
+---
+
+## What it is
+
+`_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event
+pipeline. After a successful V2 write (POST/PUT/PATCH), it publishes a single JSON message
+to the `toga-events` SQS queue describing what changed. The `websocket` standalone server
+consumes that queue and fans out `record:changed` to browsers. The whole call is wrapped in
+a `try/catch (\Throwable)` so an SQS failure logs but never blocks or errors the API
+response.
+
+## How it works
+
+`publish(object &$api, string $httpMethod, array $routeVars)`:
+
+1. Reads `aws_event_queue_url` / `aws_event_queue_region` from `_Config::cloud()`; returns
+   early if no queue URL is configured.
+2. Determines the affected record's `recordRoute`, `recordId`, `uuid`.
+3. Derives `parentRoute` / `parentUuid` from `$routeVars` when the URL is a nested resource
+   (`count($routeVars) >= 3` → `parentRoute = $routeVars[0]`, `parentUuid = $routeVars[1]`).
+4. JSON-encodes `{ clientId, clientUuid, recordRoute, recordId, uuid, httpMethod,
+   parentRoute, parentUuid, dtEvent }` and enqueues via `_Cloud::addSqsMessage()`.
+
+SQS credentials come from `_Config::cloud('aws_event_queue_access_key_id' /
+'..._secret_access_key')` — values live in config/cloud, never in code or this doc.
+
+## Gotchas
+
+- **`recordRoute` must come from `$routeVars[0]`, not `$api->record->route`.** Post-`POST`
+  interceptors can swap `$api->record` to a *different* model before `publish()` runs (e.g.
+  `service-requests`' `postPost` switches `$api->record` to the `service-request-bundles`
+  model), so `$api->record->route` would point at the wrong route. Read the original URL
+  segment `$routeVars[0]`, falling back to `$api->record->route` only when `routeVars` is
+  empty.
+- **`$api->response->data` is a PHP array, not a stdClass object.** `processRoutePairs()`
+  in V2.php returns e.g. `['serviceRequests' => $outData]`. Using object access
+  (`$data->{$topKey}`) on it silently returns null, so `uuid`/`recordId` were always null in
+  published events. Cast first: `$data = (array) $api->response->data;` then
+  `$topRecord = (object) $data[array_key_first($data)];` before reading `->id` / `->uuid`.
+
+## Change history
+- 2026-06-29 — Fixed `recordRoute` to read `$routeVars[0]` (authoritative URL route) because
+  post-interceptors can mutate `$api->record` to a different model before publish. (rgirish)
+- 2026-06-29 — Fixed null `uuid`/`recordId` in SQS events: response data is a PHP array, so
+  cast `(array)` before `array_key_first()` and `(object)` the top record before property
+  access (was using object access on an array → silent null). (rgirish)

package/knowledge/2.0/apps/_underscore/features/forecast-sale-import.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-26
+updated: 2026-06-29
 owners: [dfranks]
 files:
   - _underscore/Component/Forecast/SaleImport/SaleImport.php
@@ -28,6 +28,7 @@ files:
   - 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
 related:
@@ -161,11 +162,27 @@ location, memo). Handler `_Worker_Netsuite_JournalEntry`: `post`/`put` → `sync
 item-line upsert/reconcile machinery (`syncLines`/`guardedInsert`/`deleteRows`).
 
 **Mapping model (durable design):**
-- A JE line carries **no native item and no salesRep** (confirmed against the live account:
-  0 JEs carry an item on a revenue/cost line). The fields the business rule needs **do not
-  exist in NetSuite yet** — they are stubbed behind constants `JE_LINE_ITEM_FIELD` /
-  `JE_LINE_SALESREP_FIELD` (currently **null**), so until the fields are added every kept
-  line groups under `(null, null)` into **one aggregate row**.
+- **Sales rep is now LIVE on JE lines** as the custom column **`custcol_sales_rep_line`**
+  (`JE_LINE_SALESREP_FIELD = 'custcol_sales_rep_line'`, wired 2026-06-29 after live Apr–May
+  2026 probing). The value is a NetSuite **employee REFERENCE object** `{links, id, refName}`;
+  `.id` is the employee internalId (a **string** in JSON). `journalLineLookup()` resolves it
+  via `lookupId('Employees','netsuiteInternalId', .id)` → local `salesRepEmployeeId`. The
+  per-run **account-number allowlist isolates exactly the lines that carry the rep** — offset/
+  balancing lines omit class/entity/`custcol_sales_rep_line`, so they group to null and are
+  dropped. No schema/migration (`salesRepEmployeeId` already on `Forecast.Sales`).
+- **JE lines carry NO item field at all — item ingestion from NetSuite is not possible.**
+  Confirmed across multiple Apr–May 2026 JEs: the full union of line keys is
+  `{account, class, cleared, debit, credit, custcol_sales_rep_line, entity, line, memo, location}`.
+  There is **no native `item` and no custom item column**. `JE_LINE_ITEM_FIELD` stays **null
+  by design**; kept lines now group **per-salesRep with a null item**. The dimension that
+  exists *instead of* item is **`entity`** (the customer ref). Probe tool:
+  `test/@dave/probe_je_shape.php` (dumps line column shapes + custom columns).
+- **No salesRep self-heal (unlike the item path).** `journalLineLookup()` for Employees has
+  **no `syncEmployee()` fallback** (the item path self-heals via
+  `_Worker_Netsuite_Item::syncItem()`). A rep missing from `Forecast.Employees` silently
+  resolves to **null** and re-aggregates under null. It relies on the **supporting-records
+  pull** keeping `Forecast.Employees` current. (Sample coverage was complete — rep IDs
+  482, 569, 685, 30954, 34877 all present in prod `Forecast.Employees`.)
 - Lines hitting a **revenue** or **cost** GL account are grouped by **(salesRep, item)**:
   `revenue = Σ(credit − debit)` over revenue lines, `cost = Σ(debit − credit)` over cost
   lines, `profit = revenue − cost`.
@@ -411,6 +428,21 @@ record is deleted in NetSuite.)
 - The cron's sign handling is not portable here — see Sign convention.
 
 ## Change history
+- 2026-06-29 — **Wired JE sales-rep ingestion live** (TRUE-79862): set
+  `JE_LINE_SALESREP_FIELD = 'custcol_sales_rep_line'` after live Apr–May 2026 probing
+  confirmed the rep is now present on JE lines as that custom column — a NetSuite employee
+  **reference** object `{links,id,refName}` whose `.id` (string) resolves via
+  `lookupId('Employees','netsuiteInternalId',.id)`. Kept lines now group per-salesRep with a
+  null item. One-line change, no schema/migration (`salesRepEmployeeId` already exists).
+  **Confirmed JE lines carry NO item field** (native or custom) — line key union is
+  `{account,class,cleared,debit,credit,custcol_sales_rep_line,entity,line,memo,location}`; the
+  dimension *instead of* item is `entity` (customer ref), so `JE_LINE_ITEM_FIELD` stays null
+  by design (item ingestion from NetSuite is not possible). **Gotcha: JE salesRep lookup has
+  no self-heal** (the item path does via `syncItem()`) — a rep missing from
+  `Forecast.Employees` resolves to null and aggregates under null; relies on the
+  supporting-records pull. Still dormant in prod (JE webhook fires only once the AMQ enqueuer
+  deploys on the Journal Entry record type). Probe tool: `test/@dave/probe_je_shape.php`.
+  (dfranks)
 - 2026-06-26 — **Changed JE revenue/cost classification from `accttype` buckets to an EXACT
   account-NUMBER allowlist** (sales-team-defined): `JE_REVENUE_ACCOUNT_NUMBERS =
   {41100,41300,41500}`, `JE_COST_ACCOUNT_NUMBERS = {51100,51200}`; everything else ignored.

package/knowledge/INDEX.md

@@ -16,7 +16,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 18 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 19 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 22 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)
@@ -34,6 +34,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## standalone framework
 
 - **togatech** (TOGA Technology Website) — 4 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
+- **websocket** (WebSocket Server) — 2 doc(s) → [standalone/apps/websocket/INDEX.md](standalone/apps/websocket/INDEX.md)
 - **forward** (Forwarder) — 4 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)
 
 ## Clients

package/knowledge/clients/prudential/profile.md

@@ -5,11 +5,12 @@ apps:
   - _underscore
   - api2
   - dbchanges2
+  - websocket
 project: _Underscore
 client: prudential
 type: profile
 status: active
-updated: 2026-06-18
+updated: 2026-06-29
 owners: ["jcardinal", "rgirish"]
 files: []
 related:

package/knowledge/clients/tow-foundation/features/receipt-processing.md

@@ -60,7 +60,7 @@ Credit Card Receipts/
    - **`.docx` files bypass Talos** and route to `extractDocxData()` (Talos returns HTTP 500 on a `.docx` MIME type — it only accepts PDF/image). That method opens the docx as a ZIP, extracts `word/document.xml`, strips tags, and regex-parses `MM/DD/YY: description` lines into `line_items[]`
    - All other types POST to Talos AI `/api/ai/generate` → structured `{vendor_name, invoice_date, total, payment_memo, category, ...}`
    - **Year guard on AI dates** — if Talos returns an `invoice_date` whose year is more than 1 year from the current year (AI hallucination on two-digit year inputs, e.g. `5/13/76` → 1976, `5/28/28` → 2028), the year is clamped to the current year while month/day are preserved
-   - Cross-verify amount ± $0.01 against parsed statement; if matched, override `payment_memo` with the statement description. The statement memo is the **authoritative source for activity-purpose headings** (Grantee meeting, Peer meeting, Grantee event, etc.); the AI memo is good for location/detail but defaults to a bare `"Transportation:"` heading on ride-share/taxi receipts even when the receipt has handwritten activity notes. The override now fires when **either** the AI `payment_memo` is empty **or** it is a bare transportation memo — `isBareTranportationMemo()` returns true when the memo (left-trimmed) starts with `"Transportation:"`. Previously the override only fired on an empty AI memo, so a wrong `"Transportation:"` heading was never corrected.
+   - Cross-verify amount ± $0.01 against parsed statement; if matched, the statement description **may** override `payment_memo`. The statement memo is the **authoritative source for activity-purpose headings** (Grantee meeting, Peer meeting, Grantee event, etc.) — but only when it actually *is* such a heading. The Amex statement's `Description` column for ride-share/taxi charges holds raw bank strings (e.g. `"AplPay LYFT 855-280-0278 CA"`, `"UBER"`), not activity headings. **Priority order (enforced):** (1) statement memo wins only if it is a proper activity heading; (2) otherwise the AI memo is kept — including when the statement only has a raw bank string, because the AI's descriptive memo (e.g. `"Transportation: Lyft ride from East Side at 105th to 925 9th Ave"`) is more useful than a raw Apple Pay string. The override condition is `empty($extracted->payment_memo) || self::isActivityHeadingMemo($matched)`. `isActivityHeadingMemo()` returns true only when the statement memo (left-trimmed, lowercased) starts with a recognised activity-purpose prefix followed by a colon (`grantee meeting:`, `grantee event:`, `peer meeting:`, `colleague meeting:`, `staff theater:`, `professional development:`, `dining:`, `travel:`). This **replaces** the earlier `isBareTranportationMemo()` approach, which fired whenever the AI memo started with `"Transportation:"` and so let the raw bank string overwrite a useful AI memo on ride-share rows (degraded rows 1, 17, 18, 21, 26, 31, 32, 34 on Emily Tow's statement).
    - **Zero-total fallback** — if the extracted/docx total is 0, `lookupStatementTotalByVendor()` derives the amount from the billing statement (see *Statement structure* below)
    - Build base filename (no suffix yet) and store in `$pendingRenames`
    - On extract failure → move to `Archive/exception/` immediately
@@ -236,6 +236,7 @@ Fatal errors send only to `NOTIFY_EMAIL_DEV` (no CC/BCC).
 
 ## Change history
 
+- 2026-06-29 — **Reversed the over-aggressive memo override.** Replaced `isBareTranportationMemo()` (added earlier same day) with `isActivityHeadingMemo()`: the statement memo now overrides the AI memo **only** when it is a proper activity-purpose heading (e.g. `Grantee meeting:`, `Peer meeting:`), not whenever the AI memo started with `"Transportation:"`. The previous approach replaced semi-useful AI memos with raw bank strings (`"AplPay LYFT …"`, `"UBER"`) on ride-share/taxi rows where the statement has no activity heading — degraded 8 rows on Emily Tow's statement (1, 17, 18, 21, 26, 31, 32, 34). New priority: statement heading > AI memo, with AI memo kept for any non-heading statement description. (rgirish)
 - 2026-06-29 — `payment_memo` override now also fires on a **bare** `"Transportation:"` AI memo, not just an empty one: new `isBareTranportationMemo()` lets the cardholder's statement Excel (the authoritative source for activity-purpose headings like "Peer meeting:", "Grantee event:") override the AI's generic transportation heading. Fixes wrong headings on Emily Tow May 2026 transit rows. Added the committed `MoveBack` action (+ `collectFilesRecursiveRaw()`) to restore a person's archived receipts into a billing-cycle folder for reprocessing, replacing the throwaway `/tmp/tow_restore_archives.php` script. (rgirish)
 - 2026-06-25 — Statement parsing hardened for Emily Tow's May 2026 Amex xlsx: `loadStatementExcel()` now iterates `getAllSheets()` (4 weekly-period sheets) instead of `getActiveSheet()` and captures the `Receipt` column; `lookupStatementTotalByVendor()` now **sums** all receipt-label-matched rows (14 × $3.00 "Subway Rides" = $42.00) before falling back to description-keyword match — fixes subway totals reading $0/$9.00. Added `extractDocxData()` so `.docx` receipts bypass Talos (Talos 500s on docx), parsing `MM/DD/YY: description` line items into per-entry Excel rows. Added a year guard clamping AI-hallucinated `invoice_date` years (e.g. 1976, 2028) to the current year. Fixed archive-path bug: SharePoint move now uses the actual folder name (`"Emily Tow CC receipts"`) not the normalized name, fixing 404 on archive moves. 5 more vendors found missing from the QB vendor list (client action). (rgirish)
 - 2026-06-23 — `TowFoundationCategories.php` added: AI category values now mapped to exact QB account strings via `mapCategory()`; `"Transportation"` → `"6610 Travel expense"` etc. (19 mappings). QB vendor substring match minimum lowered from 4 to 3 chars with whole-word boundary guard for short needles — fixes `"CVS"` → `"CVS Pharmacy"`, `"MTA"` → `"MTA Metro card"`, prevents `"UPS"` → `"USPS"` false positive. (rgirish)

package/knowledge/registry.json

@@ -96,6 +96,16 @@
     "role": "app",
     "dependsOn": []
   },
+  {
+    "repo": "websocket",
+    "project": "WebSocket Server",
+    "framework": "standalone",
+    "role": "app",
+    "dependsOn": [
+      "api2",
+      "_underscore"
+    ]
+  },
   {
     "repo": "webhook",
     "project": "Webhook",

package/knowledge/standalone/apps/websocket/INDEX.md

@@ -0,0 +1,6 @@
+# websocket (WebSocket Server) — standalone knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [WebSocket Server Architecture](architecture.md) | `websocket` (npm package `toga-socket-server`) is the real-time push tier for TOGA 2.0 frontends. | websocket/index.js, websocket/auth.js, websocket/rooms.js, websocket/fanout.js, websocket/metadata.js, websocket/ecosystem.config.js, websocket/aws-setup.sh, websocket/package.json |
+| [SQS Fan-out to Socket.io Rooms](features/sqs-fanout.md) | The fan-out logic that turns one SQS `toga-events` message (published by api2 after a write) into `record:changed` emits to every Socket.io room that should lea | websocket/fanout.js, websocket/metadata.js, websocket/rooms.js |

package/knowledge/standalone/apps/websocket/architecture.md

@@ -0,0 +1,90 @@
+---
+title: WebSocket Server Architecture
+framework: "standalone"
+repo: websocket
+project: WebSocket Server
+client: shared
+type: architecture
+status: active
+updated: 2026-06-29
+owners: [rgirish]
+files:
+  - websocket/index.js
+  - websocket/auth.js
+  - websocket/rooms.js
+  - websocket/fanout.js
+  - websocket/metadata.js
+  - websocket/ecosystem.config.js
+  - websocket/aws-setup.sh
+  - websocket/package.json
+related:
+  - ../../../2.0/apps/_underscore/features/event-publish-sqs.md
+---
+
+## Summary
+
+`websocket` (npm package `toga-socket-server`) is the real-time push tier for TOGA 2.0
+frontends. It is a **standalone Node.js / Socket.io server** — it uses neither PHP
+framework (`_underscore` 2.0 nor `App_` 1.0), which is why it lives under the
+`standalone/` knowledge partition. It consumes the `toga-events` SQS queue published by
+`api2` (via `_Event::publish()` in `_underscore`) and fans out `record:changed` events to
+connected browsers over Socket.io rooms. It ships no client-facing CRUD of its own.
+
+**Critical rules:**
+- It is a **consumer** of an event contract owned by the PHP side — the event payload
+  shape is defined by `_underscore`'s `_Event::publish()`. Changes to the payload must be
+  coordinated across both repos (see the related `event-publish-sqs` feature doc).
+- Room keys use **`clientUuid`**, not `clientId` — the per-tenant isolation boundary.
+- All secrets (`TOGA_JWT_SECRET`/`API_SECRET_ACCESS_TOKEN`, `SQS_*`, `DB_*`) come from env
+  (`.env` locally, Elastic Beanstalk env vars in prod) or the Core DB. Never commit values.
+- JWT secrets are **sourced at runtime from `Core.Parameters`** (`API_SECRET_ACCESS_TOKEN`
+  + `_PREVIOUS`) so the server stays in sync as api2 rotates them every 3–10 days.
+
+## Stack
+
+- **Node.js ≥ 18**, **Socket.io 4.7**, **@aws-sdk/client-sqs 3**, **mysql2 3**,
+  **jsonwebtoken 9** (HS256), **dotenv**.
+- Process management via **PM2** (`ecosystem.config.js`, 2 workers, auto-restart).
+- Deployed to **AWS Elastic Beanstalk**; `aws-setup.sh` provisions an instance and is
+  reusable across multiple environments.
+
+## Pipeline
+
+```
+api2 PHP write (POST/PUT/PATCH)
+  → _underscore _Event::publish() → SQS toga-events queue
+    → this server polls SQS (long-poll loop)
+      → fanOut() → Socket.io rooms → connected browsers (record:changed)
+```
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `index.js` | HTTP server, Socket.io init, SQS poll loop startup |
+| `auth.js` | JWT validation middleware (HS256, same secret as api2) |
+| `rooms.js` | `subscribe` / `unsubscribe` handlers; `listRoom()` / `instanceRoom()` helpers |
+| `fanout.js` | SQS message → room emit (fan-out to list + instance + parent + child rooms) |
+| `metadata.js` | Core DB cache (route→id, parent/children maps, JWT secrets); refreshed every 5 min |
+| `ecosystem.config.js` | PM2 config |
+| `aws-setup.sh` | Elastic Beanstalk provisioning |
+
+## Room naming
+
+```
+List room:      toga:{clientUuid}:record:{recordRoute}
+Instance room:  toga:{clientUuid}:record:{recordRoute}:{uuid}
+```
+
+## Metadata cache (`metadata.js`)
+
+A single Core DB connection-per-refresh (every 5 minutes, plus at startup) populates three
+in-memory maps plus the JWT secret list:
+
+- `routeMap` — `route` string → `recordId` (from `Core.Records`).
+- `parentMap` — child `recordId` → parent `recordId` (from `Core.InherentRecordChildren`,
+  column `inherentChildOfRecordId`).
+- `childrenMap` — parent `recordId` → `Set` of child `recordId`s (inverse of `parentMap`).
+- `jwtSecrets` — `[current, previous]` from `Core.Parameters`, checked in order on verify.
+
+Accessors: `getRouteMap()`, `getParentMap()`, `getChildrenMap()`, `getJwtSecrets()`.

package/knowledge/standalone/apps/websocket/features/sqs-fanout.md

@@ -0,0 +1,86 @@
+---
+title: SQS Fan-out to Socket.io Rooms
+framework: "standalone"
+repo: websocket
+project: WebSocket Server
+client: shared
+type: feature
+status: active
+updated: 2026-06-29
+owners: [rgirish]
+files:
+  - websocket/fanout.js
+  - websocket/metadata.js
+  - websocket/rooms.js
+related:
+  - ../../../../2.0/apps/_underscore/features/event-publish-sqs.md
+---
+
+## What it is
+
+The fan-out logic that turns one SQS `toga-events` message (published by api2 after a
+write) into `record:changed` emits to every Socket.io room that should learn about the
+change. Implemented in `fanOut(event)` in `websocket/fanout.js`, driven by a continuous
+SQS long-poll loop.
+
+## How it works
+
+`pollLoop()` long-polls SQS (`MaxNumberOfMessages: 10`, `WaitTimeSeconds: 20`), parses each
+message body to an `event`, calls `fanOut(event)`, then deletes the message. Malformed
+bodies are logged and deleted (not retried); fan-out errors are logged without deleting
+fan-out from blocking the loop. On a receive error it backs off 5s before retrying.
+
+`fanOut(event)` reads `{ clientUuid, recordRoute, uuid, httpMethod, dtEvent, parentRoute,
+parentUuid }` and emits to up to four kinds of rooms (all keyed by `clientUuid`):
+
+1. **Own list room** — `listRoom(clientUuid, recordRoute)` — always.
+2. **Own instance room** — `instanceRoom(clientUuid, recordRoute, uuid)` — only when `uuid`
+   is present.
+3. **Inherent children's list rooms** — for each child of the fired record, emit to that
+   child's list room with `{ ...payload, parentRoute: recordRoute }`. Resolved from the
+   metadata `childrenMap` (parent recordId → Set of child recordIds), looked up via
+   `routeMap` to translate the fired `recordRoute` → `recordId` → child recordIds → child
+   routes. This lets a list view of children refresh when the parent changes (e.g. a
+   `service-requests` write notifies `service-request-bundles`, `service-request-units`,
+   and `service-request-notes` list rooms).
+4. **Parent rooms** — when the event itself is a nested write, notify the parent's list
+   room (always) and instance room (only if `parentUuid` present) with
+   `{ ...payload, childRoute: recordRoute }`.
+
+### Parent-route resolution from metadata
+
+When api2 posts a flat URL with no `parentRoute` in the event, `fanOut()` resolves the
+parent itself: it reuses the `recordId` already looked up for step 3, then reads
+`getParentMap().get(recordId)` (child recordId → parent recordId) and reverse-looks-up the
+parent's route from `routeMap`. So parent notifications work even when the publisher did
+not supply `parentRoute`.
+
+## Frontend subscription
+
+The frontend joins rooms by emitting `subscribe` once per route — there is **no server-side
+array support and none is needed**. Multiple sequential emits each join a distinct
+Socket.io room and are effectively simultaneous from the client's perspective:
+
+```js
+const routes = ['service-requests', 'service-request-bundles', 'service-request-units'];
+routes.forEach(route => socket.emit('subscribe', { record: route }));
+socket.on('record:changed', (payload) => { /* refresh the matching list/detail view */ });
+```
+
+## Gotchas
+
+- Room keys are built from **`clientUuid`**, never `clientId` — using `clientId` cross-wires
+  tenants or misses rooms entirely.
+- The children-room lookup is a nested scan of `routeMap` (recordId → route) per child; it
+  is correct but O(routes × children) — fine at current route counts, watch if routes grow.
+- Children notification depends on `Core.InherentRecordChildren` being populated and the
+  metadata cache being fresh (refreshes every 5 min) — a brand-new parent/child relation
+  will not fan out until the next refresh.
+
+## Change history
+- 2026-06-29 — Added inherent-children list-room notification: a parent write now emits
+  `record:changed` (with `parentRoute`) to each inherent child's list room, via new
+  `childrenMap` / `getChildrenMap()` in metadata.js. Parent-route resolution reuses the
+  recordId/routeMap lookup from the children step. (rgirish)
+- 2026-06-26 — Initial fan-out loop: SQS long-poll → list + instance + parent rooms, with
+  malformed-message drop and fan-out error isolation. (rgirish)

package/package.json

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