toga-ai 1.0.673 → 1.0.675

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

@@ -5,6 +5,7 @@
 | [Worker (worker2) Architecture](architecture.md) | Worker (repo `worker2`) is an AWS Elastic Beanstalk **Worker Tier** application that processes background jobs. | worker2/Controller/Index.php, worker2/Worker/, worker2/LambdaFunctions/, _underscore/Worker.php, worker2/composer.json |
 | [Deploy-Time Auto-Registration to the Shared ALB Target Group (non-production)](features/alb-target-group-auto-registration.md) | TOGA does **not** pay for EB-managed load-balancer registration, so an EB instance is normally **not** added to its environment's ALB target group — a fresh or | worker2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, worker2/ebs/register_instance_to_shared_application_load_balancer.php, worker2/.platform/hooks/_shared/040-write-instance-id.sh, worker2/.platform/hooks/_shared/041-write-region.sh, worker2/.platform/hooks/_shared/042-write-eb-environment.sh, worker2/.platform/hooks/postdeploy/015_install_composer.sh, saml/.platform/hooks/_shared/040-write-instance-id.sh, saml/.platform/hooks/_shared/041-write-region.sh, saml/.platform/hooks/_shared/042-write-eb-environment.sh, saml/.platform/hooks/prestart/040-write-instance-id.sh, saml/.platform/hooks/prestart/041-write-region.sh, saml/.platform/hooks/postdeploy/040-write-instance-id.sh, saml/.platform/hooks/postdeploy/041-write-region.sh, saml/.platform/hooks/postdeploy/042-write-eb-environment.sh, saml/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, saml/ebs/register_instance_to_shared_application_load_balancer.php, saml/composer.json, api2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh, api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php |
 | [All-Client Email Queue Monitor (Monitor/Operations/EmailQueue)](features/all-client-email-queue-monitor.md) | `_Worker_Monitor_Operations::EmailQueue()` is the cross-client health check for the 2.0 outbound email queue (`Logs_<Client>.Email` — see [2.0 Email Send Pipeli | worker2/Worker/Monitor/Operations.php, _underscore/Database.php, _underscore/Query.php, dbchanges2/Logs_Client/2026-05-21 - Email.sql |
+| [API 2.0 Stability Monitor (Monitor/Operations/ApiStability)](features/api-stability-monitor.md) | `_Worker_Monitor_Operations::ApiStability()` is a cross-client/operational **end-to-end round-trip probe** of the production 2.0 API. | worker2/Worker/Monitor/Operations.php, dbchanges2/Core/2026-08-28a - API 2.0 Stability Monitor Cron.sql |
 | [Automated PR Merger — Concurrent Force-Push Clobber Race](features/automated-pr-merger-force-push-race.md) | The automated PR merger `_Worker_Team_GitHub::Merge` (`worker2` `Worker/Team/Github.php`) merges approved PRs to `_production` by **force-pushing from a clone t | Worker/Team/Github.php |
 | [Callback Scheduling ("call me back") — worker2 AI-BDR](features/callback-scheduling.md) | The **AI-BDR callback path**: what happens between a prospect saying *"call me back later"* on a Vapi call and the dialer actually placing that second call. | worker2/Worker/Vapi.php, worker2/Worker/Ai/Bdr/Vapi.php, worker2/Controller/Index.php |
 | [ClickUp Connectivity Watchdog](features/clickup-connectivity-watchdog.md) | A cron watchdog that emails when the ClickUp integration looks disconnected during business hours. | worker2/Worker/Clickup/Health.php, worker2/Database/ClickupHealthWatchdog.sql |

package/knowledge/2.0/apps/worker2/features/api-stability-monitor.md

@@ -0,0 +1,140 @@
+---
+title: API 2.0 Stability Monitor (Monitor/Operations/ApiStability)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-08-28
+owners: ["jcardinal"]
+files:
+  - worker2/Worker/Monitor/Operations.php
+  - dbchanges2/Core/2026-08-28a - API 2.0 Stability Monitor Cron.sql
+related:
+  - ./oneuptime-worker2-monitoring.md
+  - ./netsuite-integrations-monitor.md
+  - ./all-client-email-queue-monitor.md
+  - ./elastic-beanstalk-health-monitor.md
+---
+
+## Summary
+
+`_Worker_Monitor_Operations::ApiStability()` is a cross-client/operational **end-to-end
+round-trip probe** of the production 2.0 API. Unlike a log-scraper (blind to a dead
+endpoint) or a cheap health-endpoint liveness probe, it performs a real authenticated
+call chain against `api.togahub.com/v2` and only reports OK when the API round-trips a
+representative read correctly. It follows the established "dumb reporter, smart monitor"
+OneUptime push pattern — same shape as the sibling
+[NetsuiteIntegrations](./netsuite-integrations-monitor.md) and
+[EmailQueue](./all-client-email-queue-monitor.md) monitors on
+`_Worker_Monitor_Operations`. Shared internal operational infrastructure, **not** a client
+feature.
+
+**Motivating incident.** A `Core.Records` model failed to deploy to production. Because the
+2.0 API requires a model for every `Core.Records` entry, any call touching the missing
+model returned HTTP 500 — while the Elastic Beanstalk instances stayed "healthy" and the
+`/v2/health` short-circuit route kept returning 200. A monitor that actually round-trips
+the API would have gone red immediately; a health-endpoint probe and an EB health check
+both stayed green. This probe closes that gap.
+
+## Key files / entry points
+
+- `worker2/Worker/Monitor/Operations.php` — `abstract class _Worker_Monitor_Operations`;
+  `public static function ApiStability(): string`, route
+  `Monitor/Operations/ApiStability`. All config is `ALL_CAPS` in-method locals (no
+  arguments): `$ONEUPTIME_URL` (push credential), `$API_BASE`, timeouts, expected statuses,
+  `$EXPECTED_CLIENT_AUTH_TYPE = 'SSO'`, `$DOMAINS_QUERY`, and `$ORIGIN`.
+- `dbchanges2/Core/2026-08-28a - API 2.0 Stability Monitor Cron.sql` — the `Core.CronJobs`
+  seed row (see below).
+
+## How it works
+
+Two sequential sub-checks against **production** `api.togahub.com/v2` (the `$API_BASE` is
+hardcoded — the monitor watches prod regardless of which environment runs it). HTTP goes
+through `_ApiRequest` with `ENCODE__JSON` (so `execute()` returns the decoded object) and a
+fresh `transactionId` per request via `_String::generateUuid()`:
+
+1. **Auth** — `POST /v2/auth/public?transactionId=<uuid>` with an `Origin` header (see the
+   gotcha below). Expect **HTTP 201**; extract the bearer token from `data.tokens.access`.
+2. **Representative read** — `GET /v2/domains?<fields/join/where>&transactionId=<uuid>` with
+   `Authorization: Bearer <token>` and the same `Origin`. The query is a representative
+   joined read across `Domains` + `Environments` + `ClientAuthentications` + `Apps`, scoped
+   to the `compass.togasupply.com` PRODUCTION domain. Expect **HTTP 200 AND**
+   `data.domains[0].ClientAuthentications.type === 'SSO'` (`$EXPECTED_CLIENT_AUTH_TYPE`).
+   This is the exact call that failed during the missing-model incident.
+
+Any failed sub-check sets `alarm = 'DEGRADED'` (else `OK`). The method pushes
+`{status:'reporting', alarm, authStatus, domainsStatus, failureCount, failures,
+checkedAtUtc}` to OneUptime, then returns a structured summary string recorded in
+`WorkerJobs.output`.
+
+Compass USA's production supply domain is used only as a **representative** live call — this
+is shared platform/liveness knowledge, not client-specific behavior.
+
+### Never-throw / non-fatal push
+
+Logging is off, `throwExceptionsOnFailure` is off, and the push is wrapped so a
+monitoring-side failure never fails the worker job — the standard reporter contract from
+[the OneUptime push-metric pattern](./oneuptime-worker2-monitoring.md).
+
+## Cron seed (dbchanges2)
+
+`dbchanges2/Core/2026-08-28a - API 2.0 Stability Monitor Cron.sql` — one `Core.CronJobs`
+row: action `Monitor/Operations/ApiStability`, schedule `*/5 * * * *` (every 5 min, all
+hours), `maxExecutionTime` 120, `parameters` NULL (no arguments), **`isActive = 0`**
+(ships inert per the deploy-inert convention — flip to 1 after the OneUptime monitor exists
+and its push URL is set). Core-database-only references (cluster-isolation satisfied); no
+`Core.Records`/`RecordFields` involved.
+
+## Gotchas / known issues
+
+- **`POST /v2/auth/public` returns HTTP 401 without an `Origin` request header.** The
+  public-auth endpoint carries **no** client credential; the API resolves which client/app
+  the public token is minted for from the request's `Origin` header. A server-side call must
+  set it explicitly (`Origin: https://compass.togasupply.com`) — the browser supplies Origin
+  automatically, which is why the front end's public-token flow
+  (`toga-blox-npm/src/api/auth.ts` POSTs to `/auth/public` with a null body + JSON
+  content-type) never sees this. Send the same `Origin` on the `/domains` call too, mirroring
+  the browser. This is the non-obvious fact for anyone scripting a server-side call to the
+  public-auth endpoint. (Verified 2026-08-28: with Origin, auth → 201 and domains → 200 +
+  `SSO`; without it, auth → 401.)
+- **The push URL is a credential** — it lives only as the in-method `$ONEUPTIME_URL` local,
+  never logged and never written into a doc or into dbchanges2.
+- **Watches PRODUCTION regardless of runner.** `$API_BASE` is hardcoded to prod, so a
+  non-prod worker still probes prod — intended, but do not "fix" it to the running env.
+
+## OneUptime import artifact
+
+Provisioned by importing an Incoming-Request monitor export (a local staging artifact,
+`C:\STAGE\monitor-export-api-2.0-stability-2026-08-28.json` — **not** a repo file) with three
+criteria: body Contains `"alarm":"DEGRADED"` → Degraded + incident (templated with
+`{{requestBody.failures}}` etc.); body Contains `"alarm":"OK"` → Operational;
+not-received-25-min → Offline + incident. Per the
+[activation-ordering trap](./oneuptime-worker2-monitoring.md#gotchas--known-issues), the
+absence criterion ships `isEnabled: false` — enable it after the first push lands.
+Project-specific status/severity ObjectIDs were cloned from an existing monitor export.
+
+## Change history
+
+- 2026-08-28 — Built `ApiStability()` on `_Worker_Monitor_Operations` — a two-step
+  end-to-end round-trip probe (auth/public → 201 → bearer, then a joined `/v2/domains` read
+  → 200 + `SSO`) against production `api.togahub.com/v2`, plus the `Core.CronJobs` seed
+  (`*/5 * * * *`, `isActive=0`) and an Incoming-Request OneUptime import. Motivated by a
+  missing `Core.Records` model that 500'd real calls while EB/health-endpoint stayed green.
+  Recorded the durable gotcha that `POST /v2/auth/public` **401s without an `Origin`
+  header** (the API resolves the client from Origin). Verified working end-to-end after the
+  Origin fix. (jcardinal)
+
+## Related docs
+
+- [OneUptime push-metric monitors for 2.0 workers](./oneuptime-worker2-monitoring.md) — the
+  push/token pattern, OneUptime criteria, import-JSON schema, deploy-inert and
+  activation-ordering conventions, and the liveness-probe-vs-log-scraper distinction.
+- [NetSuite Integrations Monitor](./netsuite-integrations-monitor.md) and
+  [All-Client Email Queue Monitor](./all-client-email-queue-monitor.md) — sibling
+  `_Worker_Monitor_Operations` monitors modeled on the same reporter contract.
+- [Elastic Beanstalk Health Monitor](./elastic-beanstalk-health-monitor.md) — EB-level
+  health this probe deliberately reaches past (EB stayed healthy during the incident).
+</content>
+</invoke>

package/knowledge/2.0/apps/worker2/features/oneuptime-worker2-monitoring.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-20
+updated: 2026-08-28
 owners: ["jcardinal", "mhammontree", "bala"]
 files:
   - worker2/Worker/Monitor/Compass.php
@@ -195,6 +195,21 @@ touches it. Rules for the probe:
   duplicate credentials into a second repo and race the shared access token. Accept and record the
   coverage gap rather than forking the client.
 
+#### A round-trip probe is stronger than a health-endpoint probe
+
+A health endpoint that short-circuits before any real work (`/v2/health` → 200) proves the
+process is up, but **not** that the API can actually serve a request. A missing `Core.Records`
+model once 500'd every real call while `/v2/health` and EB health both stayed green. Where an
+integration matters, add an **end-to-end round-trip probe** that authenticates and reads a
+representative record, asserting on the returned data — not just the HTTP status. First
+instance: [API 2.0 Stability Monitor](./api-stability-monitor.md), which mints a public token
+then reads `/v2/domains` and asserts `ClientAuthentications.type === 'SSO'`.
+
+**Gotcha for a server-side public-auth call:** `POST /v2/auth/public` returns **HTTP 401
+without an `Origin` request header** — the endpoint carries no client credential and resolves
+the client/app from `Origin`. The browser supplies it automatically; a scripted call must set
+it explicitly. See the API-stability doc for details.
+
 ### Tunable thresholds live in `Core.CronJobs.parameters`, everything else stays a local
 
 The alarm threshold is the **one** setting that goes in the DB, as
@@ -356,6 +371,12 @@ check for another client.
   monitors must pass the region (see [Cloud S3 helpers](../../_underscore/features/cloud-s3-helpers.md)).
 
 ## Change history
+- 2026-08-28 — Added the **round-trip probe** refinement (an authenticated end-to-end read
+  that asserts on returned data is stronger than a `/v2/health` short-circuit or EB health
+  check — a missing `Core.Records` model 500'd real calls while both stayed green) and the
+  durable gotcha that `POST /v2/auth/public` **401s without an `Origin` header** (the API
+  resolves the client from Origin). First instance:
+  [API 2.0 Stability Monitor](./api-stability-monitor.md). (jcardinal)
 - 2026-08-24 — Documented the **monitor import-JSON schema** the runbook previously described
   only conceptually: the `oneuptime-resource-export` envelope, `monitorType` must be the
   spaced display name `"Incoming Request"`, the `_type`-tagged
@@ -410,6 +431,7 @@ check for another client.
   5-min cadence → 10/15-min heartbeat timing. (jcardinal)
 
 ## Related docs
+- [API 2.0 Stability Monitor](./api-stability-monitor.md) — the first end-to-end round-trip probe instance (auth/public + /domains SSO assertion)
 - [Monitoring Framework](./monitoring-framework.md) — the parallel DB-driven, email-alert monitoring pattern
 - [Cloud S3 helpers](../../_underscore/features/cloud-s3-helpers.md) — `_Cloud::getS3Objects()` used to list the EDI bucket
 - [OneUptime 1.0 worker uptime monitoring](../../../1.0/apps/worker/features/oneuptime-worker-uptime-monitoring.md) — the 1.0 push-heartbeat predecessor

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 70 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 57 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 58 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 13 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 9 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/knowledge/sessions/2026-08-28-nycdoe-2-0-integration-mhammontree.md

@@ -0,0 +1,244 @@
+---
+type: session
+slug: nycdoe-2-0-integration
+title: NYCDOE 2.0 ServiceNow/ASN/NetSuite Integration — Design & Pseudocode Prep (TRUE-80519)
+author: mhammontree
+repos: [worker, library, togadesk, dbchanges, _underscore, worker2, dbchanges2, api2]
+framework: "both"
+client: nycdoe
+status: active
+created: 2026-08-28
+updated: 2026-08-28
+---
+
+# Session: nycdoe-2-0-integration
+**Date:** 2026-08-28
+**Project/Repo:** worker / library / togadesk / dbchanges (1.0) + _underscore / worker2 / dbchanges2 / api2 (2.0)
+**Task:** Multi-day research/design session (TRUE-80519) producing the rundown and 2.0 redesign of
+NYCDOE's ServiceNow/ASN/NetSuite integration, for Mark to author his own pseudocode proposal for
+Jeff (dev team director) to approve. Explicitly a planning ticket — no code changes. Mid-session,
+Northwell entered the picture as a second client needing the same SFTP→NetSuite pipeline (installs
+only, no ServiceNow/RITM until ~next year), which reframed the work toward a client-agnostic,
+multi-tenant-scalable design. Session ends with Jeff formally scoping **Phase 1 = the SFTP
+ingestion portion**, with an explicit requirement to scale to **1000+ clients**.
+
+---
+
+## What WORKED
+
+- **ASN-first design principle, held throughout without revision**: nothing is ever created in the
+  2.0 system except from a confirmed ingested ASN. ServiceNow and NetSuite are sync *targets*,
+  never trusted sources. This survived every subsequent design pressure-test this session.
+- **Case → ServiceRequest is the correct DOE entity model — confirmed directly by Jeff/Mark,
+  correcting an earlier 3-tier assumption**: `Case` = the 1.0 `managed_service_order` equivalent,
+  `ServiceRequest` = the 1.0 `repair_order` equivalent. **DOE will NOT use `Ticket` at all** — an
+  earlier design (this session) had assumed `Case → ServiceRequest → Ticket`, which was wrong for
+  DOE specifically.
+- **`worker2/Worker/Netsuite/SalesOrder.php` confirmed real, generic, multi-client, already in
+  production** (`Netsuite/SalesOrder::Sync`) — verified by direct code read, not assumed. Includes
+  freeze/idempotency semantics already. Reuse this; do not write a new SO push.
+- **`_Trait_Netsuite_PurchaseOrder::syncNetsuitePurchaseOrder()` and
+  `_Trait_Netsuite_ItemReceipt::syncNetsuiteItemReceipt()` confirmed real, working, inbound sync
+  methods** (NetSuite → Toga) via direct code read — not previously known to exist before this
+  session's code review.
+- **Confirmed gap, verified by code search (not assumed)**: no outbound serial/inventory-assignment
+  push to NetSuite exists anywhere in `_underscore`/`worker2`. `c_netsuiteInternalInventoryAssignmentId`
+  is declared on `Trait_Netsuite_Unit`/`ItemFulfillmentItemUnit` but has zero sync logic behind it.
+  This is genuinely new work (the 2.0 equivalent of 1.0's `2_send_serials_to_netsuite.php`).
+- **`Client_Nycdoe` confirmed already provisioned with the full standard 2.0 platform schema**
+  (`PurchaseOrders`, `SalesOrders`, `PurchaseOrders_SalesOrders`, `PurchaseOrderItems_SalesOrderItems`,
+  `ItemReceipts`, `Units`, `Cases`, `ServiceRequests`, `Tickets`, `Locations`) — verified via live
+  prod schema query, 0 rows in every business table. No new client database needed; this is
+  additive migrations only.
+- **`Locations` table reuse confirmed workable for DOE school-site data** — real columns checked
+  (`locationTypeId`, `parentLocationId`, `primaryLocationAddressId`, `allowReceiving`/`allowSending`).
+  Only new work: 2–3 `c_` fields (LDA/location code, building code, SNOW `sys_id`) + one
+  `LocationTypes` seed row. No new table.
+- **`Files` table reuse confirmed workable for the SFTP import ledger** — real columns checked
+  (`checksum`, `sourceUrl`, `size`, `name`, `type`). `checksum` gives content-based dedupe for free.
+  Workflow-state fields (`c_status`, `c_vendorId`) go as custom fields directly on `Files` — NOT a
+  separate bridge/companion table, since Files↔ledger-status is a strict 1:1 relationship (bridge
+  tables are for genuine one-to-many/many-to-many only — this is the actual platform convention,
+  confirmed by every real example found this session, not written down as an explicit rule anywhere).
+- **`Core.Partners` / `Core.PartnerApiIdentities` confirmed real via direct code read, with a
+  complete, working, production reference implementation** in `worker2/Worker/Startech.php`:
+  resolve `(partnerName, partnerIdentifier)` → `PartnerApiIdentity` → `clientId` → register that
+  client's DB → `clientApiId` → that client's own `Apis` credentials (uuid + secret). This is the
+  mechanism for "which clients have manufacturer X's SFTP feature enabled" and "what credentials do
+  we use to act as that client" — no need to invent a parallel mechanism.
+- **Live production evidence (real ASN CSV + real NetSuite screenshots) root-caused a genuine 1.0
+  bug**: one customer PO (`WR270026786`), one ASN file, containing both a serialized Lexmark
+  printer and a non-serialized Belkin cable, produced **two separate NetSuite Sales Orders a day
+  apart**. Root cause (best-supported theory, not directly log-confirmed): 1.0 has two
+  uncoordinated, independently-scheduled ingestion pipelines (`import_asn.php` polling ServiceNow's
+  API for serialized items vs. `legacy_import_asn.php` reading the SFTP file for non-serialized
+  items) that can race each other on the same shipment. A single ASN-file-only pipeline (this
+  session's design) structurally removes the race.
+- **NetSuite PO vs. SO scoping clarified and used to settle a genuine design flip-flop**: a NetSuite
+  PO is vendor-scoped (Lexmark and Belkin can never share one PO); a Sales Order is customer-scoped
+  and the platform's `PurchaseOrders_SalesOrders` bridge already supports one SO fulfilled by
+  multiple vendor POs. This means the original "SO/PO stamp at the Case/header level" design likely
+  still holds — the observed 2-SO behavior is attributed to 1.0's pipeline race, not a genuine
+  NetSuite/business requirement. (Not fully confirmed — see Not Tried Yet.)
+- **Two independent, opt-in `dbchanges2` modules designed**: `_modules/servicenow/` (RITM/ticketing
+  linkage, generic) and `_modules/sftp-import/` (file ledger, generic, no DOE-specific fields).
+  Deliberately separate because Northwell needs SFTP/NetSuite now but not ServiceNow until ~next
+  year — a client can adopt either independently.
+- **Non-serialized quantity-progress display problem solved architecturally, not with a display
+  hack**: Skyler wants "10/10" not "1/10" for a 10-cable line. Resolution: track
+  `receivedQty`/`orderedQty` directly on `ServiceRequest`, sourced from NetSuite's own `RECEIVED`
+  field on that line's PO — no per-`Unit` counting needed at all, for serialized or non-serialized
+  items, once SO/PO lives at the right grain.
+- **Technician identity gap confirmed via direct schema check**: no synced roster exists in 1.0 —
+  identity resolution is live, per-call (`getUserByEmail`/`getUserSysIdByName` against SNOW's
+  `sys_user`), stored on two columns of the generic `TOGaDeskSupport.people` table
+  (`referenceId`=sys_id, `serviceNowEmail`), reconciled only by two **manual, unscheduled** scripts.
+  2.0 target: a synced roster via the `servicenow` module; `Tickets_Users` (already exists in
+  `Client_Nycdoe`) is the direct 2.0 analog of `repair_order_technicians` — no new bridge table.
+- **Explicit, deliberate decision NOT to poll ServiceNow's Task API as a trigger**, even though
+  ServiceNow's own PCS Vendor Integration Guide documents that as its default vendor-integration
+  pattern (confirmed to be the same `/api/nycd3/v2/data/tasks` endpoint 1.0's `listIncItems()`
+  already calls). Kept the three SNOW docs reviewed (Site Search API, PCS Vendor Guide, API
+  Migration Guide) purely as API-shape reference material.
+- **`cmn_location` confirmed (via SNOW's own API doc) to be refreshed only nightly from LCGMS** —
+  decisively validates syncing locations locally over live-per-line SNOW calls (zero freshness lost).
+- Produced a client-agnostic architecture doc (`2.0-generic-sftp-netsuite-integration-pattern.md`)
+  separating reusable platform pattern from NYCDOE-specific decisions, once Northwell made that
+  separation necessary. Confirmed as the right instinct by the user.
+- Jeff confirmed independently (without prompting) that chained `postPost` interceptors are hard to
+  troubleshoot — validating this session's own prior recommendation to keep interceptor usage to
+  single, well-scoped, already-proven hops (SO creation → NetSuite dispatch; Ticket/ServiceRequest
+  state change → SNOW sync) rather than chaining the whole SFTP-to-NetSuite pipeline through them.
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **Assuming S3 alone (not a temp SFTP subfolder) should bridge 1.0 and 2.0 during parallel
+  testing** — wrong. The SFTP server is externally managed by someone else on the team and is
+  permanent infrastructure, not going away. The actual plan: 1.0's script copies the file to a temp
+  subfolder **on the same SFTP server** before its existing delete step; 2.0's worker points at that
+  temp folder pre-cutover and the real manufacturer folder post-cutover — **only a path config value
+  changes at cutover, not the mechanism**. This means 2.0 needs real SFTP connectivity
+  (phpseclib, credentials) built from day one — my initial "defer SFTP, read from S3 instead" idea
+  was based on the wrong assumption about where the bridge lived.
+- **Recommending a separate "thin companion ledger table" referencing `Files.id` for workflow
+  status** — wrong per platform convention. Files↔ledger-status is a strict 1:1 relationship, not
+  one-to-many, so the idiomatic answer is custom fields (`c_status`, `c_vendorId`) directly on
+  `Files`, not a joined table. Self-corrected only after the user directly asked "what's the
+  platform's actual preference here" — should have applied the shape-driven test (1:1 → custom
+  field; 1:many/many:many → bridge table) the first time.
+- **Claiming "using the ASN as sole source of truth" would fix the `WR270026786` dual-SO bug** —
+  imprecise on first pass. ServiceNow was never involved in producing that specific data (both
+  items came from the same ASN file); the actual fix is the Case-level SO grouping design, a
+  different decision than the ASN-first principle. Corrected when the user pushed back directly.
+- **Concluding (from the `WR270029067`/`WR270026786` live examples) that the NetSuite SO/PO stamp
+  should move from Case-header level down to ServiceRequest/item level** — this flip-flopped twice
+  in one session (header → item-level → back to header) before landing on: header-level SO,
+  vendor-scoped POs underneath via the existing bridge table, with the observed 1.0 dual-SO
+  behavior attributed to the two-pipeline race rather than a genuine requirement. Should have
+  applied the PO-is-vendor-scoped / SO-is-customer-scoped distinction *before* jumping to revise a
+  locked-in design from one live data point.
+- **MCP DB tool (`TOGa Database Integration`) disconnected mid-session** and the `/mcp` reconnect
+  notice was misleading — tools showed as "reconnected" in the system reminder but were not
+  actually reachable via `ToolSearch` or direct call for a period. Required a full VS Code restart
+  to actually restore connectivity. If this recurs: don't trust the reconnect notice alone — verify
+  with an actual tool call before relying on it.
+
+## Not tried yet (candidates for next session)
+
+- Confirm whether `syncNetsuitePurchaseOrder`/`syncNetsuiteItemReceipt` are actually wired to a live
+  trigger (a Record Script row?) in production, or currently dormant — no caller found in
+  `api2`/`worker2` source; could be wired via DB-driven Record Script, which wouldn't show up in a
+  code grep.
+- Confirm with whoever owns NetSuite/accounting whether one-SO-multiple-vendor-PO (e.g. Lexmark +
+  Belkin under one Case) is actually the desired business behavior, or whether always-separate SOs
+  per vendor is intentional — this is the one still-open piece of the SO/PO grain flip-flop above.
+- Confirm per-vendor SFTP delete/move permissions (Mark manually verified his own SFTP credentials
+  can create/write/delete; still need to confirm 1.0's actual service-account credentials have the
+  same access, and separately confirm whether a server-side `rename()` is supported vs.
+  full download+reupload).
+- Confirm actual Lenovo/Apple/Lexmark ASN file sizes before finalizing S3-staging vs.
+  re-fetch-by-name for fanned-out per-file worker jobs.
+- Confirm whether ServiceNow's data model supports multiple RITMs per customer PO cleanly (relevant
+  to the item-grain RITM linkage decision).
+- §4.1 (PO-suffix format variance defeating dedupe — `-RPL`/`-REPL`/etc.) is still fully open, not
+  addressed by any of this session's redesign work.
+- **Incidents (INCs) — entirely deferred**, was scheduled for a "Wednesday" follow-up session; not
+  yet covered in any depth (only that "installs = RITM, not incidents" boundary is established).
+- Design the exact schema for the per-client FTP-credentials table and the per-client
+  manufacturer-to-import table that Jeff's latest meeting notes call for (`manufacturerId` +
+  `ftpCredentialId`, "FTP ID... use for dynamic connections to FTPs").
+- Design the concrete discovery-cron-per-manufacturer / fan-out-per-client mechanism for the
+  confirmed 1000+ client scale target — including whether `Core.PartnerApiIdentities` querying at
+  that volume needs any indexing/pagination consideration.
+- Open question from Jeff's notes, unresolved: **do all manufacturers use the same ASN file format
+  across different clients** (e.g. Lenovo-to-Northwell vs. Lenovo-to-NYCDOE), or does format vary
+  per client/contract? Affects whether per-manufacturer parsers are safely shareable across clients
+  or need per-(client × manufacturer) overrides.
+- Northwell-specific plan file deliberately not yet started (Northwell will get its own ClickUp
+  ticket; this session's scope stays DOE-only per the actual ticket title/user story).
+- Design the exact trigger mechanism (interceptor vs. explicit call) for the outbound NetSuite
+  serial/inventory push once it's built.
+- Design the unified generic "sync `Ticket`/`ServiceRequest` state to RITM" worker action discussed
+  across the hold-status-sync and proof-of-delivery conversations (replacing what are two separate,
+  polling-based scripts in 1.0 with one event-driven mechanism, multiple trigger points).
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `C:\Users\mhammontree\.claude\plans\true-80519-this-is-a-sunny-riddle.md` | Needs update | Main NYCDOE plan file, §1–11 (1.0 rundown, §7 redesign principles, §8 SNOW API wishlist, §10 concrete architecture outline). **Not yet updated** with: Case→ServiceRequest-only (no Ticket) model, the `Core.Partners`/`PartnerApiIdentities` credential mechanism, or Jeff's Phase-1-SFTP-scope + 1000+ client requirement. |
+| `C:\Users\mhammontree\.claude\plans\true-80519-file-mapping.md` | Needs update | 1:1 mapping of every 1.0 file/table to its 2.0 status. Not yet revised for the no-Ticket model change. |
+| `C:\Users\mhammontree\.claude\plans\2.0-generic-sftp-netsuite-integration-pattern.md` | Needs update | Client-agnostic pattern doc. Still references the earlier speculative "Integrations table" concept — needs correcting to the confirmed `Core.Partners`/`PartnerApiIdentities` mechanism, the no-Ticket model, and the 1000+ client scale requirement. |
+| No code files | Unchanged | Entire session was research/design/planning; no implementation work performed. |
+
+## Decisions made
+
+- **ASN-first (never trust SNOW/NetSuite to create/change our records)** — root cause of nearly all
+  1.0 bugs is treating these external systems as reliable/always-in-sync. Rejected: SNOW's own
+  documented default vendor pattern (poll the Task API) — deliberately not adopted.
+- **`Case → ServiceRequest`, no `Ticket`, for DOE** — matches 1.0's actual `MSO → repair_order`
+  two-tier shape exactly. Rejected: the original 3-tier `Case → ServiceRequest → Ticket` design from
+  earlier in this same session, abandoned once Jeff/Mark clarified DOE never had a Ticket-equivalent.
+- **NetSuite SO/PO stamp stays at `Case` (header) level**, supporting multiple vendor-scoped POs per
+  SO via the existing bridge table. Rejected: moving the stamp to `ServiceRequest`/item level
+  (seriously considered and reverted within this session after the PO-is-vendor-scoped /
+  SO-is-customer-scoped distinction was raised).
+- **Interceptor usage narrowed to single, proven hops** (SO creation → NetSuite dispatch;
+  state-change → SNOW sync). Rejected: chaining the entire SFTP-to-NetSuite pipeline through nested
+  `postPost` interceptors — Jeff independently flagged troubleshooting difficulty as the reason.
+- **File ledger via custom fields on the existing `Files` table.** Rejected: a new dedicated ledger
+  table, and a thin companion table referencing `Files.id` — both unnecessary given the real
+  `checksum`/`sourceUrl` columns and the 1:1 relationship shape.
+- **SFTP credential/client resolution via `Core.Partners`/`Core.PartnerApiIdentities`**, reusing the
+  exact pattern already proven in `worker2/Worker/Startech.php`. Rejected: inventing a new generic
+  "Integrations" table from scratch (an earlier speculative proposal this session).
+- **Two independent, opt-in `dbchanges2` modules** (`servicenow`, `sftp-import`) rather than one
+  bundled module — Northwell needs one now, the other later. Rejected: a single combined module.
+- **A separate, client-agnostic architecture document**, apart from the NYCDOE-specific plan file —
+  needed once Northwell entered the picture. Rejected: keeping everything in one NYCDOE-titled file.
+- **Discovery cron scheduled per-manufacturer, not per-client**, fanning out per client via
+  `_Worker::runTask()` — required to hit the confirmed 1000+ client scale target without creating
+  1000+ `Core.CronJobs` rows.
+- **Mark authors his own pseudocode for Jeff's approval; this session's output (plan files) is raw
+  material only, never submitted directly** — standing instruction, repeated and honored throughout
+  (Mark is not permitted to submit Claude's own output as his proposal per his team's process).
+- **This ticket's (TRUE-80519) formal scope stays DOE-only; Northwell gets its own future ClickUp
+  ticket** — the ticket's literal title/user story is DOE-specific; avoids risking a "Rework" cycle
+  from the ClickBot-enforced pseudocode-review gate on this ticket.
+
+## Blockers
+
+None currently. The DB MCP tool had a transient disconnect mid-session (see "did NOT work" above)
+but is confirmed working again as of the last successful query this session.
+
+## Exact next step
+
+> Update `true-80519-this-is-a-sunny-riddle.md` and `2.0-generic-sftp-netsuite-integration-pattern.md`
+> to reflect: (a) the `Case → ServiceRequest`-only model for DOE (no `Ticket`), (b) the
+> `Core.Partners`/`Core.PartnerApiIdentities` credential-resolution mechanism (replacing the
+> speculative "Integrations table" idea), and (c) Jeff's Phase 1 = SFTP scope decision with the
+> explicit 1000+ client scalability requirement. Then design the concrete schema for the per-client
+> FTP-credentials table and manufacturer-import table referenced in Jeff's latest meeting notes.
+
+---
+_Saved by /session-save on 2026-08-28_

package/package.json

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