toga-ai 1.0.775 → 1.0.777

package/knowledge/2.0/apps/saml/architecture.md

@@ -6,7 +6,7 @@ project: SAML SSO Gateway
 client: shared
 type: architecture
 status: active
-updated: 2026-08-27
+updated: 2026-09-04
 owners: ["rgirish", "jcardinal"]
 files:
   - saml/index.php
@@ -49,7 +49,7 @@ Legacy `/?meta`, `/?acs`, `/?sls` query-style paths are rewritten automatically.
 2. **Version + time check** — RelayState JSON: `v` (currently `1`), `time`, `domain` UUID, optional `urlParameters`. Validated against `MAX_TIME_TO_LIVE` (300s).
 3. **Parse SAMLResponse** — base64-decoded, deserialized via LightSaml.
 4. **Status check** — proceeds only on `STATUS_SUCCESS`.
-5. **Assertion decryption** — TOGa SP credential from `_underscore/Assets/ssl/`.
+5. **Assertion decryption (dual-credential during cert overlap).** `/acs` builds two `X509Credential`s from the SP encryption keys in `_underscore/Assets/ssl/` (new + old) and calls `$reader->decryptMultiAssertion([$credentialNew, $credentialOld], $ctx)`. LightSaml's `decryptMulti()` tries each credential and only re-throws once all fail (fails closed), so an assertion encrypted to either the new or old SP key decrypts during a rotation overlap. See the SP cert-rotation workflow.
 6. **Resolve client + environment** — `_Model_Core_Domain` by RelayState `domain` UUID → `_Model_Core_Client` + `_Model_Core_Environment`. Dev on real AWS instance downgrades to beta.
 7. **Dynamic DB registration** — SQL joins `Clients`, `Databases`, `DatabaseHosts`, `Environments` for the environment slug. Calls `_Database::register()` + `connect()` for `DB_CLIENT`, `DB_CLIENT_LOGS`, `DB_CLIENT_ARCHIVE`.
 8. **Identity mapping** — `_Model_<ClientIdentifier>_ClientAuthentication::getAuthenticatedSsoUser($assertion)`. Wrapped in try/catch; exceptions sent to Sentry.
@@ -59,6 +59,10 @@ Legacy `/?meta`, `/?acs`, `/?sls` query-style paths are rewritten automatically.
 ### Failure responses
 `Invalid SAMLResponse (Code = 1–4)`, `SAML Authentication Failed`, `User Authentication Failed`.
 
+## /meta SP credential (signing vs encryption)
+
+`/meta` publishes TWO independent `KeyDescriptor`s: `use="signing"` and `use="encryption"`. They can carry **different** certs, which lets the SP encryption cert rotate without touching the signing cert. The private key that signs our **outbound** AuthnRequests lives in `_underscore` (`_Model_Core_ClientAuthentication::PATH_TO_PRIVATE_KEY`) and is **global — one key for all client IdPs**, so the signing cert cannot flip until every IdP has loaded the new metadata. Cert paths are set via class constants in `saml/Controller/Index.php` (`PATH_TO_SIGNING_CERTIFICATE`, `PATH_TO_ENCRYPTION_CERTIFICATE_NEW/OLD` + matching private-key constants — paths only, no key material). Full procedure: SP cert-rotation workflow.
+
 ## Per-client SSO extension pattern
 
 Identity mapping lives in `_underscore/Model/<ClientIdentifier>/ClientAuthentication.php`.
@@ -90,6 +94,7 @@ To onboard a new SSO client, add the class in `_underscore` — not in this repo
 - **`_Database::register()` auto-starts a lazy transaction (since Apr 2 2026).** Any code that registers DBs then writes must call `_Database::transactionCommit()` before exiting — otherwise MySQL silently rolls back all writes on connection close. The `/acs` handler calls `transactionCommit()` after `getAuthenticatedSsoUser()` succeeds and before the redirect. See `_underscore/Database.php:48`.
 - **SAML signature verification is commented out — this is the repo's top security priority.** The IdP X509 cert verification block in the `/acs` flow is disabled, so the gateway accepts any well-formed, status-success `SAMLResponse` without proving it was signed by the expected IdP. The only remaining gate is the encrypted RelayState, which authenticates the *originating TOGa request* — not the *asserting IdP*. Threat model: an attacker who can craft or replay a `SAMLResponse` (or a malicious/compromised IdP) can forge an identity assertion for any user, since nothing binds the assertion to a trusted signing key. Re-enabling per-IdP X509 signature verification is the single highest-impact security fix for this repo.
 - **Plaintext secrets in source — move to AWS SSM Parameter Store.** `saml/Config/production.ini` stores credentials in plaintext, and a Sentry DSN is hardcoded in `saml/Controller/Index.php`. Both are checked into the repo. Migrate these to AWS SSM Parameter Store (SecureString) and load at runtime; the source tree should reference parameter names only, never literal credential values.
+- **`/meta` cert lines must be `trim()`-ed (CRLF).** The `.crt` files in `_underscore/Assets/ssl` are CRLF-encoded; the cert-format code does `explode("\n", ...)` and indents each line, so without a per-line `trim()` a stray `\r` ends up on every base64 line inside `<ds:X509Certificate>`. Trim each line in both the signing and encryption blocks.
 - **SLS not implemented.** `/sls` falls through to the default banner.
 - **`set_exception_handler(null)` at top of `saml()`.** Unhandled exceptions output raw PHP errors. All exceptions from `getAuthenticatedSsoUser()` are caught and sent to Sentry.
 
@@ -97,3 +102,4 @@ To onboard a new SSO client, add the class in `_underscore` — not in this repo
 - 2026-06-11 — Added `transactionCommit()` before redirect; wrapped `getAuthenticatedSsoUser()` in try/catch with Sentry; echo+exit on auth failure (rgirish)
 - 2026-06-25 — Sharpened signature-verification gotcha with explicit threat model and flagged it as the repo's top security priority; documented plaintext secrets in `production.ini` + hardcoded Sentry DSN in `Controller/Index.php` with SSM Parameter Store recommendation (jcardinal)
 - 2026-08-27 — Documented non-prod shared-ALB self-registration postdeploy hook (`060_...sh` + `ebs/register_instance_to_shared_application_load_balancer.php`); skips `production`, requires `aws/aws-sdk-php` + two IAM actions; cross-linked worker2 ALB auto-registration feature (jcardinal)
+- 2026-09-04 — `/acs` now dual-credential decrypt (`decryptMultiAssertion([new, old])`) for SP encryption-cert overlap; documented `/meta`'s two KeyDescriptors (signing vs encryption) and the global outbound-signing key; added the CRLF `/meta` cert-line `trim()` gotcha. (jcardinal)

package/knowledge/2.0/apps/saml/workflows/rotating-the-saml-sp-certificate.md

@@ -6,7 +6,7 @@ project: SAML SSO Gateway
 client: shared
 type: workflow
 status: active
-updated: 2026-08-27
+updated: 2026-09-04
 owners: ["jcardinal"]
 files:
   - _underscore/Assets/ssl/togahub_com.crt
@@ -32,16 +32,58 @@ cert), see the SSL certificate trust-model strategy standard.
 
 ## How the SP credential is used
 
-- **Private key — signs outgoing SP AuthnRequests.** `_Model_Core_ClientAuthentication`
-  (`_underscore/Model/Core/ClientAuthentication.php`) points its `PATH_TO_PRIVATE_KEY` constant
-  at `_underscore/Assets/ssl/togahub_private_key.key` and signs with XMLSecLibs `RSA_SHA256`
-  (around lines 11 / 95 / 107).
-- **Public cert — published in SP metadata and used to decrypt assertions.** The `saml` repo's
-  `Controller/Index.php` uses the cert for assertion decryption; the `/meta` route publishes it
-  in SP metadata via `file_get_contents` read fresh on each request (no server-side cache).
+The SP cert/key is used in **four** places — three in `saml`, one in `_underscore`:
+
+- **(a) `/meta` signing `KeyDescriptor`** — `saml/Controller/Index.php` publishes the cert IdPs
+  use to verify our outbound AuthnRequest signature. Read fresh via `file_get_contents` on each
+  request (no server-side cache).
+- **(b) `/meta` encryption `KeyDescriptor`** — the cert IdPs use to encrypt assertions to us.
+- **(c) `/acs` assertion decryption** — `saml/Controller/Index.php` decrypts the inbound
+  encrypted assertion with the matching private key.
+- **(d) Outbound AuthnRequest signing (GLOBAL)** — `_Model_Core_ClientAuthentication`
+  (`_underscore/Model/Core/ClientAuthentication.php`, `PATH_TO_PRIVATE_KEY`, around lines
+  11 / 95 / 107) signs the redirect-binding AuthnRequest query string with XMLSecLibs
+  `RSA_SHA256`. **One key signs the login requests we send to ALL client IdPs — you cannot sign
+  per-client.** This is why signing and encryption rotate on different schedules (see
+  *Encryption-only rotation*).
+
 - **IdPs cache metadata up to 7 days** (`cacheDuration PT604800S`), so a cert change is not
   guaranteed to be picked up by every IdP immediately after deploy.
 
+## Encryption-only rotation with an overlap window (2026-09-04)
+
+Because a cert change is not picked up by every IdP at once, the safe rotation splits the two
+uses and **rotates encryption first, signing later**:
+
+- **Signing stays on the OLD cert.** If `/meta` advertised the new signing cert (or (d) signed
+  with the new key) before every IdP loaded the new metadata, any IdP that verifies our
+  AuthnRequest signature could **reject our login requests**. Signing flips only after all IdPs
+  are on the new metadata — a later, coordinated step.
+- **Encryption rotates now, with both keys accepted.** `/meta` presents TWO independent
+  `KeyDescriptor`s: `use="signing"` = current/old cert, `use="encryption"` = new cert. Two
+  independent KeyDescriptors is valid SAML metadata, so encryption can rotate without touching
+  signing.
+- **`/acs` accepts EITHER encryption key during overlap.** It builds two `X509Credential`s
+  (new + old) and calls `$reader->decryptMultiAssertion([$credentialNew, $credentialOld], $ctx)`.
+  In vendored LightSaml, `decryptMulti()` tries each credential and only re-throws once all fail
+  — so it fails closed. This lets an IdP that has re-encrypted to the new cert and one still on
+  the old cert both succeed.
+- **Class constants (paths only, no key material)** in `saml/Controller/Index.php` replaced the
+  old single pair: `PATH_TO_SIGNING_CERTIFICATE`; `PATH_TO_ENCRYPTION_CERTIFICATE_NEW` +
+  `PATH_TO_ENCRYPTION_PRIVATE_KEY_NEW`; `PATH_TO_ENCRYPTION_CERTIFICATE_OLD` +
+  `PATH_TO_ENCRYPTION_PRIVATE_KEY_OLD`.
+- **What forced it:** old cert `togahub_com.crt` (O=Agilant Solutions) expires **2026-09-16**;
+  new cert `togahub_com_2036-08-27.crt` (O=TOGA Technology, Inc.) is valid to 2036.
+
+### Remaining steps / follow-ups (not yet done)
+1. **Flip signing to the new cert** once every IdP has loaded the new metadata — advertise the
+   new signing cert in `/meta` and switch (d) to the new key. Coordinate the date.
+2. **Log which SP key decrypted** (new vs old, identifier only — never assertion data) so you can
+   see which IdPs have cut over and when it is safe to drop the old key.
+3. **Wrap the `/acs` decrypt in try/catch** and echo `Invalid SAMLResponse (Code = 5)` to match
+   the existing coded failure responses.
+4. **Dedupe the two `/meta` cert-format blocks** into a shared helper (non-blocking).
+
 ## Current credential (as of 2026-08-27, staged — cutover pending)
 
 A dedicated **self-signed** replacement was generated to decouple the SP credential from the
@@ -88,6 +130,14 @@ short-lived DigiCert/Thawte TLS wildcard that had been reused as the SP cert (se
 6. **Deploy the cert+key to the other bilateral services** that use the same SP credential —
    AS2 (AWS Transfer Family) and any other pinned endpoint — importing both cert and key.
 
+### Gotcha — trim each cert line (CRLF)
+
+The `.crt` files in `_underscore/Assets/ssl` are **CRLF-encoded**. The `/meta` cert-format code
+does `explode("\n", ...)` then indents each line. Without a per-line `trim()`, a stray carriage
+return (`\r`) is embedded on every base64 line inside `<ds:X509Certificate>` in the metadata XML.
+Fix: `trim()` each line in the cert-format code — applied to both the signing and encryption
+blocks. (Latent bug that pre-dated this change in the single original block.)
+
 ## Background — why the change
 
 The old `_underscore/Assets/ssl/togahub_com.crt` was a **reused DigiCert/Thawte multi-domain
@@ -105,5 +155,12 @@ every pinning partner to reinstall on each renewal. The dedicated self-signed 10
   `_underscore`-then-`saml` cutover ordering. Discovered the prior cert was a reused short-lived
   DigiCert wildcard TLS cert, which is the reason for the switch. Cutover itself still pending.
   (jcardinal)
-</content>
-</invoke>
+- 2026-09-04 — Documented the **encryption-only rotation** actually built in
+  `saml/Controller/Index.php`: `/meta` now presents two `KeyDescriptor`s (signing=old,
+  encryption=new) and `/acs` uses `decryptMultiAssertion([new, old])` so both encryption keys
+  work during overlap; new path-only class constants replaced the single cert/key pair.
+  Recorded that outbound AuthnRequest signing uses one GLOBAL key for all IdPs, which is why
+  signing stays on the old cert until every IdP loads the new metadata. Added the CRLF
+  per-line-`trim()` gotcha for `/meta` cert formatting, and the open follow-ups. Change is
+  working-tree only (deploys via `saml` on `_production`); Rate is testing against
+  `saml-production`. (jcardinal)

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 24 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 33 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 34 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/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) — 13 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)

package/knowledge/clients/nycdoe/INDEX.md

@@ -2,6 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [NYCDOE EDI 850 Receive & 997 Acknowledgement](features/edi-850-receive-and-997-ack.md) | 1.0 | DOE sends purchase orders as **EDI 850** files over their SFTP; TOGA turns each one into a NetSuite Sales Order and sends back an **EDI 997** functional acknowl | worker/crons/sync/nycdoe/receive_edi_purchase_orders.php, worker/schedules/cron.worker.sync.json, library/app/edi.php |
 | [NYCDOE Ticket Hold-Status Sync (ServiceNow ⇄ TOGaDesk)](features/hold-status-sync.md) | 1.0 | DOE ticket **hold** status must round-trip between ServiceNow (SNOW) and TOGaDesk and **stay held** — holds are SLA-bearing in both systems. | worker/crons/sync/nycdoe/send_ticket_updates.php, worker/crons/sync/nycdoe/process_tickets.php, worker/crons/sync/nycdoe/send_request_item_updates.php, library/app/model/togadesk/repairorder.php, library/app/api/nycdoev2.php, togadesk/desk/includes/classes/class.repair.php |
 | [NYCDOE ServiceNow / ASN Integration](features/servicenow-integration.md) | 1.0 | The NYCDOE/ServiceNow integration mirrors DOE's ServiceNow tickets (Incidents + RITMs) into local tables, turns vendor shipment notices into NetSuite Sales Orde | worker/crons/sync/nycdoe/import_asn.php, worker/crons/sync/nycdoe/import_inc.php, worker/crons/sync/nycdoe/legacy_import_asn.php, worker/crons/sync/nycdoe/legacy_process_asn_queue.php, worker/crons/sync/nycdoe/process_tickets.php, worker/crons/sync/nycdoe/1_send_asn_to_netsuite.php, worker/crons/sync/nycdoe/2_send_serials_to_netsuite.php, worker/crons/sync/nycdoe/3_create_installation_ticket.php, worker/crons/sync/nycdoe/test_multi_po_receipt_resolution.php, worker/crons/sync/nycdoe/send_ticket_updates.php, worker/crons/sync/nycdoe/send_request_item_updates.php, worker/crons/sync/nycdoe/send_nycdoe_proof_of_delivery.php, worker/crons/sync/nycdoe/sync_nycdoe_locations.php, worker/crons/sync/nycdoe/receive_edi_purchase_orders.php, worker/crons/sync/nycdoe/send_edi_open_invoices.php, worker/crons/notifications/nycdoe/, worker/schedules/cron.worker.sync.json, worker/schedules/cron.worker.notification.json, library/app/api/nycdoe.php, library/app/api/nycdoev2.php, library/app/nycdoe.php, library/app/asnprocessor/manufacturer.php, library/app/asnprocessor/apple.php, library/app/asnprocessor/lenovo.php, library/app/asnprocessor/lexmark.php, library/app/asnprocessor/acer.php, library/app/edi.php, library/app/netsuite.php, dbchanges/Core/SK/, dbchanges/TOGaDeskSupport/SK/, worker2/Worker/Monitor/Nycdoe.php |
 | [New York City Department of Education](profile.md) | 1.0 | NYC DOE (New York City Department of Education) is a TOGA client whose entire integration runs in the **1.0 worker tier** (~30 cron scripts under `worker/crons/ |  |

package/knowledge/clients/nycdoe/features/edi-850-receive-and-997-ack.md

@@ -0,0 +1,108 @@
+---
+title: NYCDOE EDI 850 Receive & 997 Acknowledgement
+framework: "1.0"
+repo: worker
+project: Worker
+client: nycdoe
+type: client-feature
+status: active
+updated: 2026-09-04
+owners: [mhammontree]
+files:
+  - worker/crons/sync/nycdoe/receive_edi_purchase_orders.php
+  - worker/schedules/cron.worker.sync.json
+  - library/app/edi.php
+related:
+  - servicenow-integration.md
+  - ../profile.md
+  - ../../../1.0/apps/worker/architecture.md
+  - ../../../1.0/apps/library/architecture.md
+---
+
+## Summary
+
+DOE sends purchase orders as **EDI 850** files over their SFTP; TOGA turns each one into a
+NetSuite Sales Order and sends back an **EDI 997** functional acknowledgement. There is
+**no separate 997 cron** — the 997 is built and uploaded inline at the end of the 850
+receiver, so anything that aborts the receiver also means DOE never gets an ack.
+
+This doc owns the 850-in / 997-out surface. The broader DOE ticket + ASN pipeline lives in
+[servicenow-integration.md](servicenow-integration.md).
+
+## How it works
+
+1. **Cron:** `worker/crons/sync/nycdoe/receive_edi_purchase_orders.php`, schedule
+   `30 9,15 * * *` (9:30 AM and 3:30 PM) in `worker/schedules/cron.worker.sync.json`.
+2. Pulls every file from `/outbound` on DOE's SFTP `transfer.schools.nyc` (SSH key file
+   `library/ssl/doe/doedimedu.pem`; username and key live in the
+   [DOE profile](../profile.md) / on disk — never in this doc).
+3. `App_Edi::translatePurchaseOrder850()` parses each file. Only files whose
+   `senderId == 'NYCDOE'` are processed.
+4. Creates the NetSuite Sales Order (DOE customer internal id **21797**) and attaches the
+   raw 850 file.
+5. **Then** builds the 997 via
+   `App_Edi::generateAcknowledgements997FromPurchaseOrders850()` (`library/app/edi.php`,
+   ~line 348) and `put`s it to `/inbound` as `997_<original 850 filename>`
+   (cron ~lines 338-350).
+6. Logs **both** the 850 and the 997 to `App_Model_FileLog` (`db_logs`, table
+   `Logs.FileLog`, `legacy` environment) under job `EDI_NYCDOE_PO`, then deletes the 850
+   from DOE's SFTP.
+
+### 997 segment structure
+
+`ISA` / `GS(FA)`, then per PO: `ST(997)`, `AK1(PO, groupStartIdentifier)`,
+`AK2(850, transactionSetIdentifier)`, `AK5(A)`, `AK9(A,1,1,1)`, `SE(6)`; then `GE` / `IEA`.
+Transaction set control number starts at **1001** and increments per PO. Default
+separators: `~` element, `\n` segment.
+
+Field mapping (verified against 850 FileLog id 880810):
+
+| 997 segment | Source in the 850 |
+|---|---|
+| `AK1~PO~2` | the 850's `GS~PO~NYCDOE~2127360111~…~2~X~004010` |
+| `AK2~850~004204317` | the 850's `ST~850~004204317` |
+| (PO number, elsewhere) | `BEG~00~KN~WR270037765` |
+
+## Gotchas
+
+- **The cron header comment is STALE.** It says "INTENDED TO BE RUN EVERY HOUR". It runs
+  twice a day. `worker/schedules/cron.worker.sync.json` is the source of truth.
+- **The 997 generator is an "always accept" stub — still OPEN.**
+  `library/app/edi.php` ~lines 393-412 hardcode `AK5 = 'A'` and `AK9 = 'A','1','1','1'`, so
+  every 997 reports "accepted, 1 transaction set" no matter what the 850 contained. It can
+  never report a reject or a real transaction count. Out of scope for TRUE-81757; needs its
+  own ticket if DOE ever audits the acks beyond `AK2`.
+- **An exception in the NetSuite loop skips the 997 entirely** and leaves the 850 on SFTP,
+  so the file re-processes next run and DOE gets no ack at all. That fail-loud abort is
+  correct for 1.0 sync/cron code, but it is a distinct cause from a *malformed* 997 —
+  check which one you have before touching the generator.
+- **`generateAcknowledgements997FromPurchaseOrders850()` has exactly one production
+  caller** (this DOE cron). The other two callers are dev scratch scripts under
+  `test/@jeff/edi/` and `test/@pinal/netSuites/`, so a change to it is DOE-only in effect.
+- **`sync/prudential/receive_edi_purchase_orders.php` does NOT use this 997 function.** Do
+  not assume the two EDI receivers share the ack path.
+- **EDI PO104 leading-zero suppression** — DOE's IBM translator sends `.94` not `0.94`;
+  exposure is in `App_Edi::translatePurchaseOrder850()`, not the cron. See
+  [servicenow-integration.md](servicenow-integration.md).
+
+## Debugging a DOE 997 complaint
+
+1. Query `Logs.FileLog` on the `legacy` environment for job `EDI_NYCDOE_PO`.
+2. Match the pair: the 997 row's `fileName` is `997_` + the 850's `fileName` (e.g. id
+   `880810` = the 850, `880811` = its 997).
+3. `fileData` is a BLOB — read it with `CONVERT(fileData USING latin1)` to see the EDI text.
+4. The 850 is deleted from DOE's SFTP after a successful run, but the **raw file data is
+   retained in `Logs.FileLog`**, so a 997 can be regenerated from the stored 850 without
+   asking DOE to resend.
+
+## Change history
+- 2026-09-04 — **Fixed (TRUE-81757): `AK2` sent the wrong transaction set id.**
+  `App_Edi::generateAcknowledgements997FromPurchaseOrders850()` (`library/app/edi.php`
+  line 400) hardcoded `'855'`; changed to `'850'` — the 997 acknowledges an inbound **850**
+  Purchase Order, so `AK201` must be `850`. Not an isolated event: the line has read `'855'`
+  since the function was first written (commit `3136e813`), and every 997 in `Logs.FileLog`
+  back to at least 2026-03-20 shows `AK2~855` (ids 880811, 868639, 814727, 810405) — DOE's
+  translator silently accepted it for months and complained only once. **Business decision
+  (Eric): fix going forward only** — no back-fix and no resend of historical 997s.
+  Also documented the full 850-in/997-out flow, the always-accept `AK5`/`AK9` stub (still
+  open), and the `Logs.FileLog` debugging path. (mhammontree)

package/knowledge/clients/nycdoe/features/servicenow-integration.md

@@ -6,7 +6,7 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-08-18
+updated: 2026-09-04
 owners: [mhammontree, sking]
 files:
   - worker/crons/sync/nycdoe/import_asn.php
@@ -42,6 +42,7 @@ files:
   - worker2/Worker/Monitor/Nycdoe.php
 related:
   - ../profile.md
+  - edi-850-receive-and-997-ack.md
   - ../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md
   - hold-status-sync.md
   - ../../../1.0/apps/worker/architecture.md
@@ -90,7 +91,7 @@ ticket state / ETA / proof-of-delivery back to ServiceNow. A parallel EDI surfac
 | Proof of delivery → ServiceNow | `send_nycdoe_proof_of_delivery.php` | every 5 min |
 | Locations sync | `sync_nycdoe_locations.php` | daily 3:00 AM |
 | Site-id monitor | `email_notification_siteid.php` | daily 7:01 AM |
-| EDI 850 POs in → NetSuite SO + 997 ack | `receive_edi_purchase_orders.php` (`senderId == 'NYCDOE'` only) | 9:30 AM & 3:30 PM |
+| EDI 850 POs in → NetSuite SO + 997 ack | `receive_edi_purchase_orders.php` (`senderId == 'NYCDOE'` only) — see [edi-850-receive-and-997-ack.md](edi-850-receive-and-997-ack.md) | 9:30 AM & 3:30 PM |
 | EDI invoices out (NetSuite saved search 2108) | `send_edi_open_invoices.php` | every 2 h at :13 |
 | Installation schedule reports | `notifications/nycdoe/send_installation_schedules_doe.php` (3 business days ahead, weekends skipped, **holidays NOT skipped**), daily + current-week variants, weekly part-orders | 5–8 AM daily/Mondays |
 
@@ -647,6 +648,7 @@ the client's `apps:` scope solely so this monitor loads, and its presence is **n
    of the consumer query; `php -l` every touched file.
 
 ## Change history
+- 2026-09-04 — Split the EDI 850-in / 997-ack surface into its own doc, [edi-850-receive-and-997-ack.md](edi-850-receive-and-997-ack.md) (TRUE-81757 `AK2~855`→`850` fix, always-accept `AK5`/`AK9` stub, `Logs.FileLog` debugging). This doc keeps the ticket/ASN pipeline. (mhammontree)
 - 2026-08-18 — Repaired stranded ASN `26644` / customer PO `WR260175404-RPL` (**data-only, no code
   in `worker` or `dbchanges`**): item `54552` (`DOE-62C5GAR1US`, unit `604254`, serial `VKVY4802`)
   had been `pending` with a NULL `togadeskRepairOrderId` since 2026-07-02. Repointed
@@ -757,6 +759,7 @@ the client's `apps:` scope solely so this monitor loads, and its presence is **n
 ## Related docs
 
 - [NYC DOE client profile](../profile.md)
+- [NYCDOE EDI 850 Receive & 997 Acknowledgement](edi-850-receive-and-997-ack.md) — 850-in/997-out
 - [Worker (1.0) architecture](../../../1.0/apps/worker/architecture.md) — cron dispatch,
   role election, schedule files
 - Local deep-dive (full WR260236464 case study with record IDs):

package/knowledge/clients/nycdoe/profile.md

@@ -11,11 +11,12 @@ project: Worker
 client: nycdoe
 type: profile
 status: active
-updated: 2026-08-17
+updated: 2026-09-04
 owners: [mhammontree, sking]
 files: []
 related:
   - features/servicenow-integration.md
+  - features/edi-850-receive-and-997-ack.md
 ---
 
 ## Summary

package/package.json

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