toga-ai 1.0.263 → 1.0.265

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

@@ -5,7 +5,7 @@
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql |
 | [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 |
+| [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [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 |

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

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-06-29
-owners: ["jcardinal", "rgirish"]
+updated: 2026-07-02
+owners: ["jcardinal", "rgirish", "mhammontree"]
 files:
   - _underscore/_underscore.php
   - _underscore/Loader.php
@@ -35,6 +35,9 @@ can be silently dropped — confirm commit semantics before relying on a write.
 The Surface presentation layer replaces `Page::meta()` but `meta()` must NOT be deleted until
 every page is cut over (per-surface, with a parity diff); config describes, PHP decides —
 business logic never moves into Surface config.
+Storage fields (`FIELD_STORAGE`) must be written by assigning then `save()` — historically a
+`__get` refetch on the write path silently dropped the assigned value (fixed 2026-07); still avoid
+*reading* a storage field between assign and save (it refetches and discards the unsaved value).
 
 ## Entry point & boot sequence
 
@@ -319,9 +322,19 @@ multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentNa
 
 ## Gotchas / known issues
 
+- **`FIELD_STORAGE` writes were silently dropped platform-wide (fixed 2026-07, `Model.php`).** Two
+  bugs: (a) `buildSqlFieldValue()` read the field via `$this->$field`, which for a storage field
+  triggers `__get()` → a disk/S3 **refetch** that overwrote the just-assigned value before `save()`
+  persisted it — so storage-field writes never persisted, on both S3 and folder backends; fixed by
+  reading the raw `_model_fields[$field]['value']` for storage fields. (b) The folder-mode READ
+  branch checked `filesize($cacheFilePath)` (an S3-only temp path) instead of `filesize($filePath)`,
+  so folder reads always returned null; fixed. **Remaining follow-up (separate ticket):** `__get()`
+  still refetches storage unconditionally, so a dirty read (read-after-assign, pre-save) discards the
+  unsaved value.
 - **`_Database::register()` auto-starts a lazy transaction (since Apr 2 2026, commit `fa7835ed`).** Any code that calls `register()` and then writes to that DB must call `_Database::transactionCommit()` before the request ends — otherwise MySQL silently rolls back all writes when the connection closes. Lazy transactions only materialise on the first write, so read-only callers are unaffected. See `_underscore/Database.php:48`. First discovered when Rate SAML user provisioning silently discarded all new user INSERTs (Jun 2026).
 
 ## Change history
 - 2026-06-11 — Documented lazy transaction gotcha in `_Database::register()` (rgirish)
 - 2026-06-25 — Added the Surface platform UI presentation/configuration layer (DB-driven UI config replacing `Page::meta()`, CTO-reviewed AGREE-WITH-ADJUSTMENTS) (jcardinal)
 - 2026-06-29 — Surface made the enforced (un-flagged) presentation path; reserved id blocks renumbered to Records 333–341 / RecordFields 2246–2433 (known seed-vs-provisioned drift). (jcardinal)
+- 2026-07-02 — Fixed framework-wide `FIELD_STORAGE` write-drop and folder-read bugs in `Model.php`; noted the remaining unconditional-refetch dirty-read follow-up. (mhammontree)

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
-owners: ["jcardinal"]
+updated: 2026-07-02
+owners: ["jcardinal", "mhammontree"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Core/Page.php
@@ -90,6 +90,28 @@ then checks the caller's roles against `AclRecordPermissions` (→ `EZ-1` if no
 readable/writable fields from `AclFieldPermissions`. `_Model_Core_Page::meta()` reads the same
 tables to return per-page ACL to the frontend.
 
+## Record-script dispatch grant (`AclRecordScripts`) — a separate gate
+
+A **scripted API** (Record Script) has its own ACL gate, **distinct from the four-table record-CRUD
+chain above**: dispatch is authorized by an **`AclRecordScripts`** row, not by
+`AclRecordPermissions`. Without it the call **403s** even though the route and the PHP method exist.
+
+To expose a scripted API on a `_Model` in 2.0:
+1. **Route** — a `Core.RecordScripts` row (id-agnostic; resolve the record by `route=`, not a
+   hardcoded id — same discipline as the reserved-id-block work). Fields: `recordId`, `method`
+   (GET/POST/…), `route` (the segment after the record name), `phpMethod`.
+2. **Dispatch grant** — a Client-DB **`AclRecordScripts`** row for the roles that may call it
+   (typically Public / SuperUser / Base). This is the 403-preventing gate and is the step most
+   easily missed; it mirrors the **Surface `meta`** precedent (`GET /v2/surfaces/meta`).
+3. **PHP method** — signature `public static function <phpMethod>(&$api, …namedQueryArgs)`; the
+   named args are parsed from the query string; the return value is JSON-encoded into the
+   response `data`. Tenant scope comes from the JWT-pinned client DB — no manual client filtering.
+
+Worked example: the reprint API `GET /v2/tracking-numbers/reprint`
+(`_Model_Client_TrackingNumber::reprintLabelsApi`) required both a `Core.RecordScripts` route and a
+Client-DB `AclRecordScripts` grant (migrations in `dbchanges2`) before it stopped 403ing — see the
+carrier-shipping-labels feature doc.
+
 ## Checklist (so the chain is never half-built)
 
 - [ ] `AclRecordPermissions` row for the role × record with the right CRUD flags.
@@ -101,6 +123,10 @@ tables to return per-page ACL to the frontend.
 
 ## Change history
 
+- **2026-07-02** — Added the record-script dispatch grant (`AclRecordScripts`) as a gate distinct
+  from the record-CRUD chain, with the full recipe for exposing a scripted API on a `_Model`
+  (Core.RecordScripts route + Client `AclRecordScripts` grant + `(&$api, …)` method), discovered
+  wiring the `tracking-numbers/reprint` scripted API. (mhammontree)
 - **2026-06-23** — Documented after repeatedly missing the logic-group/expression rows when
   granting access to new records. Created alongside the `item-translations` record (331) ACL,
   whose grant in `dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql` is a worked example of

package/knowledge/2.0/apps/_underscore/features/carrier-shipping-labels.md

@@ -6,12 +6,14 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-18
+updated: 2026-07-02
 owners: [mhammontree]
 files:
   - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Model/Client/TrackingNumber.php
   - _underscore/Model/Client/ItemFulfillments/TrackingNumber.php
   - _underscore/Component/Library/LabelPdf/LabelPdf.php
+  - _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php
   - _underscore/Component/Library/Carriers/Ups/Ups.php
   - _underscore/Component/Library/Carriers/Fedex/Fedex.php
   - _underscore/Trait/Netsuite/ItemFulfillment.php
@@ -33,7 +35,11 @@ Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label
 (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracking
 number and label attached. As of 2026-06 the label is requested + stored as a raw
 **PNG** and the printable PDF is **generated on demand** via `_Component_Library_LabelPdf`
-(FPDF) — superseding the old Labelary ZPL→PDF approach.
+(FPDF) — superseding the old Labelary ZPL→PDF approach. As of 2026-07 the **reprint** combine
+also runs on the backend — a scripted API (`reprintLabelsApi`) reads the stored PNGs and returns
+one combined base64 PDF (the client-side `pdf-lib` merge is gone); **return labels** are generated
+per carrier (`generateReturnLabel`); and carrier **billing account** is threaded from the tracking
+record instead of a hardcoded constant.
 
 ## Key files / entry points
 
@@ -51,6 +57,20 @@ number and label attached. As of 2026-06 the label is requested + stored as a ra
   (`Component/Library/LabelPdf/LabelPdf.php`): builds a multi-page 4x6 PDF from raw PNG label
   images (one per page, optional "Return Label" caption) via FPDF; returns the PDF as a binary
   string. Built to take N pages so a combined shipping + return label is one print-once PDF.
+- `_Model_Client_TrackingNumber::reprintLabelsApi(&$api, $uuids, $caption)`
+  (`Model/Client/TrackingNumber.php`): the **backend reprint** scripted API, exposed as a
+  `Core.RecordScripts` route **`GET /v2/tracking-numbers/reprint`**. Loads each `TrackingNumbers`
+  record by UUID, reads its stored raw PNG (`labelPdfFile`), and returns a **combined base64 PDF**
+  via `buildFromPngLabels`. Replaced the frontend `pdf-lib` merge (which broke once labels became
+  PNG — it expected a base64 PDF). Requires a Client-DB `AclRecordScripts` dispatch grant or it
+  403s — see the ACL permission-chain doc's record-script dispatch section.
+- `_Model_Client_ItemFulfillment::generateReturnLabel(&$api, $uuid)`
+  (`Model/Client/ItemFulfillment.php`): builds a per-carrier **return** shipment request
+  (ship-from = customer, ship-to = warehouse return address; Ground service; FedEx uses drop-off
+  pickup), creates a **second** `TrackingNumbers` record, stores its raw PNG, and links it as
+  `returnTrackingNumberId` on the `ItemFulfillments_TrackingNumbers` header bridge.
+- `getLabelFormat()` (client UPS config helper): now **defaults to `PNG`** (was ZPL) and validates
+  against a supported-format allowlist, so a carrier label reliably comes back as an embeddable PNG.
 - `_Component_Library_Carriers_Ups::submitShipmentRequest`
   (`Component/Library/Carriers/Ups/Ups.php`): returns `{ success, errorMessage,
   trackingNumber, encodedLabel }`.
@@ -70,8 +90,8 @@ number and label attached. As of 2026-06 the label is requested + stored as a ra
 The label is **stored as the raw carrier PNG** (not a Labelary PDF) and the printable PDF is
 **generated on demand** server-side:
 
-1. **Carrier returns PNG.** UPS via `[ups] label_format = "PNG"` config (the client's
-   `getLabelFormat()` reads it; defaults ZPL); FedEx via `$shipmentRequest->labelImageType =
+1. **Carrier returns PNG.** UPS via `getLabelFormat()`, which **now defaults to `PNG`** (was ZPL)
+   and validates against a supported-format allowlist; FedEx via `$shipmentRequest->labelImageType =
    'PNG'` + `labelStockType = 'PAPER_4X6'`. Labelary is gone.
 2. **Store the raw PNG** on `TrackingNumbers.labelPdfFile` (a `FIELD_STORAGE` field; the name is
    retained though it now holds a PNG) via the model/S3 mechanism — never touch S3 by hand.
@@ -80,9 +100,28 @@ The label is **stored as the raw carrier PNG** (not a Labelary PDF) and the prin
    display + the NetSuite File Cabinet copy.
 
 Jeff approved **PNG over GIF**: a PDF lib embeds PNG with **no extra extension** (FPDF parses
-non-alpha PNG in pure PHP — no GD/Imagick). Remaining wiring: the reprint/return-label combine
-(frontend calls a backend generate endpoint instead of the client-side `pdf-lib` merge), and
-the return-label generation itself.
+non-alpha PNG in pure PHP — no GD/Imagick). The remaining wiring is now done (2026-07): the
+reprint combine moved to the backend `reprintLabelsApi` scripted API and return-label generation
+(`generateReturnLabel`) is implemented — see the sections below.
+
+## Carrier billing account & return labels (implemented 2026-07)
+
+**Billing account is data-driven, not a constant.** The selected
+`shippingCarrierAccountNumber` on the tracking record is threaded into the carrier request as
+`ShipmentRequest->$shipperAccountNumber` for both UPS and FedEx billing. The old hardcoded
+`SHIPPER_NUMBER` / `ACCOUNT_NUMBER` constants were **removed**. Two guards:
+- **Fail fast on an empty account** — never ship on a blank billing account.
+- **Fail if an Item Fulfillment has more than one tracking number** — with >1 tracking record the
+  code can't decide which account to bill, so it errors rather than guess.
+
+**Return labels.** When `ShipmentRequest->isReturn` is set, the carrier request injects the
+return-service flags: UPS `Shipment.ReturnService.Code = '9'` (Print Return Label); FedEx
+`shipmentSpecialServices.returnShipmentDetail` (`returnType = PRINT_RETURN_LABEL`, RMA reason
+"Customer Return"). `generateReturnLabel` builds the return request with **ship-from = customer,
+ship-to = warehouse**, at **Ground / customer-drops-off** service level (decision), creates a 2nd
+`TrackingNumbers` record, stores its raw PNG, and links `returnTrackingNumberId` on the
+`ItemFulfillments_TrackingNumbers` bridge. Warehouse return addresses come from a `RETURN_ADDRESSES`
+set (two verified addresses: Naperville default + Plainview).
 
 ## `FIELD_STORAGE` mechanics (reference)
 
@@ -101,14 +140,34 @@ store whatever value was assigned. `_Cloud::copyFileToS3` **re-throws** on AWS e
 if no exception reached the caller and execution continued, the write was never
 attempted.
 
+**Root cause of the "labelPdfFile never lands" bug — two framework-core `Model.php` bugs
+(fixed 2026-07):** these were the true reason storage-field writes silently vanished, and they
+affect **every** 2.0 model that uses `FIELD_STORAGE`, not just labels — so a fuller
+framework-level note is pending on the `_underscore` architecture doc.
+1. **Write path re-fetched over the assigned value.** `buildSqlFieldValue()` read the field via
+   `$this->$field`, which for a `FIELD_STORAGE` field triggers `__get()` → a disk/S3 **refetch**
+   that overwrote the just-assigned in-memory value *before* `save()` persisted it. Net effect:
+   storage-field writes silently never persisted (both S3 and folder backends). Fixed by reading
+   the raw `_model_fields[$field]['value']` for storage fields instead of going through `__get`.
+2. **Folder-mode read used the wrong path for its size check.** The folder-storage READ branch
+   checked `filesize($cacheFilePath)` (an S3-only temp path) instead of `filesize($filePath)`, so
+   folder-mode reads always returned null. Fixed to check `$filePath`.
+
+**Known remaining follow-up (separate ticket):** `__get()` still refetches storage
+**unconditionally**, so a *dirty read* (reading a storage field after assigning but before saving)
+still discards the unsaved in-memory value.
+
 ## Gotchas / known issues
 
 - UPS **test** endpoint (`wwwcie.ups.com`, debug mode) returns a constant tracking
   number `1ZXXXXXXXXXXXXXXXX` + SAMPLE labels → `TrackingNumbers.number` UNIQUE
   collision and File Cabinet duplicate-filename failures on repeat tests (see the
   fulfill-and-ship doc for the cleanup SQL). Never in prod.
-- `upsShipmentApi` reads ship-to from the **Sales Order** (`shipToAddressId`), not the
-  Item Fulfillment — form-edited addresses never reach UPS.
+- ~~`upsShipmentApi` reads ship-to from the Sales Order, not the Item Fulfillment.~~
+  **Fixed 2026-07:** carrier label ship-to now uses
+  `COALESCE(ItemFulfillments.shipToAddressId, SalesOrders.shipToAddressId)` — the edited IF address,
+  falling back to the SO — aligning the label with `fulfill()`'s NetSuite query. Form-edited
+  addresses now reach the carrier.
 - UPS `AddressLine` max 35 chars/line; send an array of trimmed lines (FedEx already
   does), not `line1 . ' ' . line2`.
 - `ShippingMethods.code` is carrier-scoped: UPS numeric (`03` Ground, `01` Next Day
@@ -142,19 +201,33 @@ attempted.
   works with the no-throw second arg: `_Config::fedex('tracking_client_id', false) ?: …` (same as
   the UPS client). Without it, FedEx shipping dies with "Configuration parameter
   'tracking_client_id' … has not been defined".
-- **`labelPdfFile` (`FIELD_STORAGE`) write can silently skip** when set on a lazy
-  `new _Model_Client_TrackingNumber($id)` (never loaded): `number` (a real column) saves but the
-  storage write is skipped (no error, no S3 object — and `copyFileToS3` re-throws, so a skip ≠ a
-  failed write). Likely needs `->load()` before setting `labelPdfFile`. **Open issue** — the S3
-  label save was still not landing as of 2026-06-18.
+- ~~`labelPdfFile` (`FIELD_STORAGE`) write silently skips / S3 label save not landing.~~
+  **Root cause found + fixed 2026-07** — it was two framework-core `Model.php` `FIELD_STORAGE`
+  bugs (a `__get` refetch overwriting the assigned value on the write path, and a wrong-path
+  `filesize` check on the folder-mode read), not a lazy-load issue. See the *FIELD_STORAGE
+  mechanics* section above.
+- **`ItemFulfillment.php` had two SQL injections + debug output (fixed 2026-07).** `postPost()`
+  interpolated `$payload->uuid` and `fulfill()` interpolated the NetSuite `$internalId` into an
+  UPDATE — both now escaped (`_Database::escape`). `fulfill()` also had leftover debug
+  `echo`/`print_r` that leaked PII and could corrupt the JSON API envelope — removed. Never emit raw
+  output from a scripted API/interceptor; it breaks the `{isSuccess,…,data}` response.
 - **FPDF can't embed alpha-channel or interlaced PNG** — carrier label PNGs must be flat raster.
   If one isn't, `buildFromPngLabels` throws; fix = GD normalize (flatten/de-interlace) or TCPDF.
 - **UPS shipper number must match the endpoint.** Beta hits the UPS **CIE test** endpoint
   (`wwwcie.ups.com`); a production account number there returns `120100`/`120121`
   ("missing/invalid shipper number" / "cannot be used"). Use a CIE-enabled shipper number for
-  test, or point at prod UPS. `SHIPPER_NUMBER` is a hardcoded constant in the UPS client.
+  test, or point at prod UPS. **The shipper/billing account is now the tracking record's
+  `shippingCarrierAccountNumber`** (threaded via `ShipmentRequest->$shipperAccountNumber`); the
+  hardcoded `SHIPPER_NUMBER`/`ACCOUNT_NUMBER` constants were removed. So for CIE tests the account
+  on the tracking record itself must be CIE-enabled.
+- **FedEx credentials are hardcoded in `Fedex.php` and were intentionally retained** (Mark's
+  decision) — do not "fix" them into config as part of unrelated work.
+- **Ship guards (2026-07).** Shipping now **fails fast** if the selected carrier account is empty,
+  and **errors if an Item Fulfillment has >1 tracking number** (can't determine which account to
+  bill) — expect a hard error rather than a silently-wrong bill in those cases.
 
 ## Change history
+- 2026-07-02 — Reprint combine moved to the backend: new `_Model_Client_TrackingNumber::reprintLabelsApi` scripted API (RecordScript `GET /v2/tracking-numbers/reprint`) returns a combined base64 PDF from the stored PNGs (frontend `pdf-lib` merge removed). Added return-label generation (`generateReturnLabel`; UPS ReturnService `9` / FedEx `PRINT_RETURN_LABEL`; Ground/customer-drops-off; `RETURN_ADDRESSES`; links `returnTrackingNumberId`). Carrier billing account threaded from the tracking record (`shippingCarrierAccountNumber`) — removed `SHIPPER_NUMBER`/`ACCOUNT_NUMBER` constants, fail-fast on empty account, error on >1 tracking number per IF. Ship-to now `COALESCE(IF, SO)` address. `getLabelFormat()` defaults PNG + allowlist. Fixed two SQL injections (`postPost` `$payload->uuid`, `fulfill` NetSuite `$internalId`) and removed leftover debug `echo`/`print_r` from `fulfill()`. Found + fixed the framework-core root cause of storage writes silently vanishing (two `Model.php` `FIELD_STORAGE` bugs — see FIELD_STORAGE mechanics). (mhammontree)
 - 2026-06-18 — Implemented the label-storage rework: request PNG from UPS/FedEx, store the raw PNG, generate the printable PDF on demand via the new `_Component_Library_LabelPdf` (FPDF); dropped Labelary. Added the FedEx tracking-cred config-fallback fix and the `_Loader`→Composer FPDF autoloader toggle. Open: the `labelPdfFile` S3 write still skips on a lazy-model save. (mhammontree)
 - 2026-06-16 — Repointed the carrier-label/NS-IF tracking-number queries (`upsShipmentApi`, `fedexShipmentApi`, `fulfill`, `createNetsuiteItemFulfillment`) from the dropped `ItemFulfillmentPackages` table to the `ItemFulfillments_TrackingNumbers` bridge — they had been saving the label/`number` to the wrong/null record (reprint `labelPdfFile` null; NS IF missing tracking). Confirmed working on beta. (mhammontree)
 - 2026-06-10 — Documented carrier shipping label mechanics (UPS/FedEx) + the authoritative GIF label-storage decision and NetSuite IF attachment. (mhammontree)

package/knowledge/2.0/apps/toga2-supply/architecture.md

@@ -6,7 +6,7 @@ project: TOGa Supply
 client: shared
 type: architecture
 status: active
-updated: 2026-06-10
+updated: 2026-07-02
 owners: [mhammontree]
 files:
   - toga2-supply/src/api/toga.ts
@@ -28,6 +28,11 @@ Fulfillment creation, label printing/reprinting). It is a pure frontend: all bus
 logic lives in the 2.0 API (`api2` engine over `_underscore` models). It has **no
 backend code of its own** — `dependsOn: [api2]`.
 
+**Critical rules:** `toga2-supply` is a **legacy app slated for replacement** — build UI
+**in-repo** and do **not** extract shared components to `@agilant/toga-blox` (that investment
+belongs in the successor app). It is a pure frontend (`dependsOn: [api2]`); all business logic
+stays in the 2.0 API, never in the frontend.
+
 ## Topology (dev/test setup)
 
 - The frontend runs **locally** on the developer machine (e.g.
@@ -66,6 +71,8 @@ Response envelope (2.0 API): `{ isSuccess, status, error, messages, data: { <rou
 - Browser print: the print dialog handles one file at a time and `window.print()` fires
   once per session — hence the combined-PDF reprint design. Popups must be allowed
   (label window is `window.open`).
+- Legacy status: this repo is being replaced; do not refactor toward `toga-blox` extraction —
+  keep new UI local to the repo.
 
 ## Related docs
 

package/knowledge/2.0/apps/toga2-supply/features/fulfill-and-ship.md

@@ -6,7 +6,7 @@ project: TOGa Supply
 client: shared
 type: feature
 status: active
-updated: 2026-06-18
+updated: 2026-07-02
 owners: [mhammontree]
 files:
   - toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx
@@ -59,18 +59,19 @@ GroWrk, June 2026); FedEx + UPS both need verification before prod.
    `saveShipmentToNetsuite` → `createNetsuiteItemFulfillment`, which attaches the label
    to the IF **after** creating it (the IF doesn't exist yet when the label is bought).
 
-## Reprint (being rewired to the backend)
+## Reprint (backend-combined, 2026-07)
 
 Fulfilled-shipments view (`FulfilledShipmentsPage` → `ShipmentsCardTableForm` with
-`isFulfilledShipmentsView`): multi-select shipments, merge each stored label into one
-multi-page PDF, print once. The label-storage rework (see the carrier-shipping-labels doc)
-now stores the raw carrier **PNG** on `TrackingNumbers.labelPdfFile` and builds the PDF on the
-**backend** (`_Component_Library_LabelPdf`/FPDF). So the current client-side `pdf-lib` merge —
-which reads `labelPdfFile` expecting a base64 **PDF** — is now **stale**: it receives a PNG.
-Reprint must be rewired to call a backend generate endpoint that returns the combined
-(shipping + return) PDF; until then it won't produce a printable label even when one is stored.
-The reprint reference was also corrected from `shipment.itemFulfillmentPackages` to
-`itemFulfillmentTrackingNumbers` (bridge migration).
+`isFulfilledShipmentsView`): multi-select shipments, print one combined multi-page PDF once.
+Because labels are now stored as raw carrier **PNG** on `TrackingNumbers.labelPdfFile` (see the
+carrier-shipping-labels doc), the **combine now runs on the backend**: `ShipmentsApi.ts` calls the
+scripted API **`GET /v2/tracking-numbers/reprint`** (`_Model_Client_TrackingNumber::reprintLabelsApi`,
+passing the selected tracking UUIDs + caption), which reads the stored PNGs and returns one combined
+base64 **PDF**. The old client-side `pdf-lib` merge (which expected a base64 PDF and broke on a PNG)
+was **removed**. The tracking source was also corrected from `shipment.itemFulfillmentPackages` to
+`itemFulfillmentTrackingNumbers` (bridge migration). Reading tracking still needs the bridge ACL
+chain (see gotchas) **and** the reprint RecordScript needs its `AclRecordScripts` dispatch grant, or
+the call 403s and returns no label.
 
 ## Gotchas / known issues
 
@@ -81,9 +82,10 @@ The reprint reference was also corrected from `shipment.itemFulfillmentPackages`
   both between runs:
   `UPDATE TrackingNumbers SET number = CONCAT(number,'-',id) WHERE number='1ZXXXXXXXXXXXXXXXX'`
   and delete/rename the prior File Cabinet file. Never happens in prod.
-- **Address source mismatch**: `upsShipmentApi` reads ship-to from the **Sales Order**
-  (`SalesOrder.shipToAddressId`), NOT the address edited in the form (the IF's) — form
-  address edits never reach the carrier. Open decision: read the IF address instead.
+- ~~Address source mismatch: ship-to read from the SO, not the edited IF address.~~
+  **Fixed 2026-07:** carrier ship-to now uses `COALESCE(ItemFulfillments.shipToAddressId,
+  SalesOrders.shipToAddressId)` — the form-edited IF address, falling back to the SO — so
+  address edits now reach the carrier.
 - **UPS address limits**: `AddressLine` max 35 chars/line; code currently sends
   `line1 + ' ' + line2` as one line — should send a trimmed array (FedEx path already
   does).
@@ -139,16 +141,15 @@ The reprint reference was also corrected from `shipment.itemFulfillmentPackages`
 
 ## Remaining work
 
-- Reprint rewire: call the backend `LabelPdf` generate endpoint (PNG → combined PDF) instead
-  of the stale client-side `pdf-lib` merge (per the carrier-shipping-labels doc). The backend
-  half (PNG store + on-demand PDF) is done.
-- Return-label flow: `returnTrackingNumberId` (nullable) on `ItemFulfillmentItemUnits`;
-  "needs return label" checkbox; return-address editable combo ("Rolodex pattern" of
-  client locations, overridable, validated); "return label" text on return pages of the
-  combined PDF.
-- Address-source decision, UPS 35-char hardening, location-scoped inventory lookup,
-  carrier/method on the NS IF, responsiveness per Figma, FedEx + UPS end-to-end
-  verification before prod.
+- ~~Reprint rewire~~ — done (backend `reprintLabelsApi` combine; see Reprint section).
+- ~~Address-source decision~~ — done (`COALESCE(IF, SO)`).
+- Return-label flow: backend generation is done (`generateReturnLabel`; UPS ReturnService `9` /
+  FedEx `PRINT_RETURN_LABEL`; 2nd tracking number linked via `returnTrackingNumberId` on the
+  bridge; Ground/customer-drops-off). Remaining **frontend** polish: "needs return label" control,
+  a return-address editable combo ("Rolodex pattern" of client locations, overridable, validated),
+  and "return label" text on return pages of the combined PDF.
+- UPS 35-char hardening, location-scoped inventory lookup, carrier/method on the NS IF,
+  responsiveness per Figma, FedEx + UPS end-to-end verification before prod.
 
 ## Client variations
 
@@ -158,6 +159,7 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 2026-07-02 — Reprint rewired to the backend: `ShipmentsApi.ts` now calls `GET /v2/tracking-numbers/reprint` (`reprintLabelsApi`) for a combined base64 PDF built from the stored PNGs; removed the stale client-side `pdf-lib` merge. Return-label backend generation landed (`generateReturnLabel`, `returnTrackingNumberId` on the bridge). Ship-to address source resolved to `COALESCE(IF, SO)`. (mhammontree)
 - 2026-06-18 — PNG label-storage rework reflected on the frontend: labels now store as PNG and the PDF is built on the backend (`LabelPdf`), so the client-side `pdf-lib` reprint is stale and must be rewired to a backend generate endpoint. Fixed the Fulfilled Shipments responsiveness/clip bug (Reprint button unreachable at 100% zoom) — `overflow-scroll` → `overflow-auto` and gave `FulfilledShipmentsPage`'s outer its own scroll; documented the `/shipments` vs `/fulfilled-shipments` two-component trap and the `AuthLayout overflow-hidden` clip. (mhammontree)
 - 2026-06-16 — Drove the full beta flow green for UPS/GroWrk. Updated the save step to the `/item-fulfillment-tracking-numbers` bridge (FE commit `b5c16592d`, key `itemFulfillmentTrackingNumbers`). Added gotchas: local-FE↔deployed-beta-BE skew, `dtSubmitted` fulfilled/pending gating, `createNetsuiteItemFulfillment` orderLine fragility on partial/already-fulfilled orders, and the bridge-ACL 403 that nulls tracking/labels (reprint). (mhammontree)
 - 2026-06-10 — Documented the Fulfill & Ship flow (SO sync, label purchase, NetSuite IF creation, success gating, reprint). Driven green on beta for UPS/GroWrk; FedEx + prod verification pending. (mhammontree)

package/knowledge/2.0/standards/backend-testing.md

@@ -0,0 +1,58 @@
+---
+title: 2.0 Backend Testing (no PHPUnit — ad-hoc client-pinned scripts)
+framework: "2.0"
+project: _Underscore
+client: shared
+type: standard
+status: active
+updated: 2026-07-02
+owners: [mhammontree]
+files: []
+related:
+  - ../apps/_underscore/architecture.md
+  - ../apps/_underscore/features/per-client-database-connections.md
+  - ../apps/test/architecture.md
+---
+
+## Summary
+
+The 2.0 backend (`_underscore` + its apps) has **no PHPUnit harness**. Verify backend behavior
+with **ad-hoc scripts in the `test` repo** (per-dev folders, e.g. `@Mark`) that bootstrap
+`_underscore` from a 2.0 app and pin a real client database explicitly. This is the accepted
+verification path until/unless a formal harness exists — do not assume a `phpunit` suite.
+
+## Bootstrapping a verification script
+
+From a 2.0 app root (e.g. `worker2`): `chdir` into the app, require Composer autoload, require
+`_underscore.php`, and set `ENVIRONMENT` before bootstrap:
+
+```php
+chdir('/path/to/worker2');
+require 'vendor/autoload.php';
+require '_underscore.php';   // boots Loader/Config/etc.
+// ENVIRONMENT must be set (env var / server) so _Config picks the right INI
+```
+
+## You MUST pin the client DB explicitly
+
+`_underscore::DB_CLIENT` is a **logical alias**, not a schema name — there is no database literally
+named `Client`. Real per-client schemas are `Client_True`, `Client_Aig`, etc. In a real request V2
+pins the concrete schema from the JWT; a standalone script has no JWT, so **you must register it**:
+
+```php
+_Database::register(
+    database: 'Client_True',      // real per-client schema
+    // …host/user/pw from config…
+    alias: _underscore::DB_CLIENT // the logical alias models resolve against
+);
+```
+
+Without this, any `Model/Client/*` query resolves the unmapped alias and fails. Use a client whose
+schema you have locally/on the target env (internal testing uses `Client_True` = TOGA Technology).
+Remember the per-client **logs** connection trap too (see the per-client-database-connections doc).
+
+## Rules
+
+- Do not add or assume a PHPUnit suite for 2.0 backend work; write a `test`-repo script instead.
+- Always pin the concrete `Client_<Id>` schema to `DB_CLIENT` (and logs/archive if the code logs).
+- Keep scripts in your per-dev `test` folder; never point them at production databases.

package/package.json

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

package/skills/kickoff/SKILL.md

@@ -33,6 +33,52 @@ description: Start-of-session context loader for TOGA Technology projects. Run t
 > block message is never to fight it: run Steps 0–3, and the moment preflight executes you
 > are free to read docs and work. (Emergency override only: `KICKOFF_GATE_DISABLED=1`.)
 
+## Session permission policy — auto-accept local file I/O, ALWAYS confirm dangerous execution
+
+> **This policy is in force for the ENTIRE session, from the moment `/kickoff` runs until it
+> ends. It is a standing, team-wide default — apply it without being reminded.**
+>
+> The intent: keep the developer in flow for safe, reversible, local work, while never letting
+> an irreversible or environment-touching action happen without an explicit human "go ahead".
+
+**Auto-accept (proceed without a permission prompt) — safe, local, reversible:**
+
+- **Reading files** — `Read`, `Grep`, `Glob`, and any read-only inspection of the local
+  working tree. Never pause to ask "may I read this?".
+- **Writing/editing files** in the local working tree — `Write`, `Edit`, `NotebookEdit`, and
+  creating new local files. Proceed as long as the target is inside the developer's local
+  checkout(s). (Standard write discipline still applies — see the stub-first rule in Step 6.)
+
+**ALWAYS ask for explicit permission first (never auto-run) — anything that executes, leaves
+the machine, or touches a shared/remote/production environment:**
+
+- **Shell execution** — every `Bash` / PowerShell command runner invocation. Before running
+  one, state what it does and why, and wait for the developer's "go ahead". (The kickoff gate
+  already blocks shell during priming; this extends the caution to the whole session.)
+- **Deploys, AWS / DevOps, and infrastructure** — `/ship`, `/land-and-deploy`, `/canary`, the
+  `devops` agent's AWS CLI/console actions, Elastic Beanstalk / EC2 / RDS / S3 / IAM changes,
+  and any command that mutates infrastructure. Confirm the target environment explicitly.
+- **Remote database access** — the `toga-db` MCP tools (`toga_query`, etc.) and any query run
+  against **production or any non-local environment**. Name the cluster/environment and get a
+  yes before executing. Treat production as require-confirmation on every call.
+- **Network, browser, and remote git** — `WebFetch`/`WebSearch`, the `/browse` browser
+  automation, `git push`, PR creation/merge, and any call that sends data off the machine or
+  writes to a remote. Confirm before each.
+
+**Rules of application:**
+
+1. When in doubt about whether an action executes something or reaches outside the local
+   environment, **treat it as dangerous and ask.** The default for the unknown is *confirm*.
+2. "Auto-accept file I/O" does **not** mean "act without judgment" — still respect
+   `/freeze`, `/guard`, and any directory scoping the developer set.
+3. A blanket "go ahead", "just do it", or "you have full access" from the developer covers the
+   current task's expected actions, but you must **still flag** any dangerous action that falls
+   outside the scope they approved (a different environment, a production write, a deploy).
+4. This is a **directive, not an enforcement mechanism.** For hard, mechanical enforcement the
+   team should also encode these as `permissions` allow/ask rules in the checked-in
+   `.claude/settings.json` (allow `Read`/`Edit`/`Write`; `ask` for `Bash` and the remote/DB/
+   deploy tools). Until that exists, follow this policy by discipline on every session.
+
 ## Arguments — text passed after `/kickoff` never skips any step
 
 Trailing text (e.g. `/kickoff worker2 backend fix for Compass`, even a detailed paragraph
@@ -253,6 +299,10 @@ Tell the developer concisely:
   summaries" list — the developer must see that the core is loaded and which app pulled it in.
 - Which knowledge docs you loaded (by title). Where a repo/standard has **no knowledge yet**,
   say so explicitly: "No knowledge captured yet for X — `capture` will build it as you work."
+- **State the session permission policy in one line** so the developer knows the rules for
+  this session: "File reads and local edits run automatically; anything that executes, deploys,
+  hits a remote/production environment, or leaves this machine, I'll confirm with you first."
+  (See *Session permission policy* near the top of this skill.)
 - Confirm you're primed and ready for their first task.
 
 **Heavy-load check (from preflight `estimate`).** Preflight returns