toga-ai 1.0.606 → 1.0.608

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

@@ -5,6 +5,7 @@
 | [Test (test) Architecture](architecture.md) | `test` (project **Test**) is a **repository of ad-hoc developer scripts** — not a deployed application. | test/team/ |
 | [2.0 Deployment — Per-Client SQL Generator](features/2-0-deployment-client-sql.md) | `team/2.0 deployment/generate_client_sql.php` fans a single SQL change-set out across **all 2.0 client databases**. | test/team/2.0 deployment/generate_client_sql.php, test/team/2.0 deployment/Clients_Db.txt, test/team/2.0 deployment/Client.sql |
 | [Active Directory Authentication Test](features/active-directory-auth-test.md) | `team/active_directory_authentication_test.php` is an interactive CLI tool to test **Active Directory authentication**. | test/team/active_directory_authentication_test.php |
+| [Compass retrofix2 — Retroactive Data-Fix SQL Generator](features/compass-retrofix2-sql-generator.md) | `@jeff/compass/retrofix2.php` is a standalone **1.0 `App_`** script that retroactively repairs historical Compass USA (`Client_Compass`, 2.0) order data left in | test/@jeff/compass/retrofix2.php |
 | [Create Elastic Beanstalk Environment (script)](features/create-elastic-beanstalk.md) | `team/aws/create_elastic_beanstalk.php` is a **standalone** (no `App_` framework) constants-driven PHP generator. | test/team/aws/create_elastic_beanstalk.php |
 | [Developer Generators (password, UUID)](features/dev-generators.md) | Two tiny **1.0 `App_` framework** convenience scripts for everyday developer needs. | test/team/generate_password.php, test/team/uuid.php |
 | [Forecast vs NetSuite Discrepancy Analysis](features/forecast-netsuite-discrepancy-analysis.md) | `team/forecast-netsuite/discrepancy_analysis.php` detects discrepancies between our **Forecast database** and **NetSuite** (the source of truth for all sales da | test/team/forecast-netsuite/discrepancy_analysis.php |

package/knowledge/1.0/apps/test/features/compass-retrofix2-sql-generator.md

@@ -0,0 +1,102 @@
+---
+title: Compass retrofix2 — Retroactive Data-Fix SQL Generator
+framework: "1.0"
+repo: test
+project: Test
+client: shared
+type: feature
+status: active
+updated: 2026-08-18
+owners: [jcardinal]
+files:
+  - test/@jeff/compass/retrofix2.php
+related:
+  - ../architecture.md
+  - ../../../clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md
+  - ../../../clients/compass-usa/features/mits-po-to-so-item-linking.md
+---
+
+## Summary
+
+`@jeff/compass/retrofix2.php` is a standalone **1.0 `App_`** script that retroactively repairs
+historical Compass USA (`Client_Compass`, 2.0) order data left in the wrong shape by 50+ past bugs.
+It **emits review-first `.sql`** — it never writes the DB directly. It supersedes the older sibling
+`retrofix.php` in the same folder (that one is superseded/kept only for reference). The domain facts
+it repairs against (the supply chain, item-link bridges, both fulfillment flows, over-fulfill cap)
+live in the Compass
+[order-lifecycle & data-integrity workflow](../../../clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md);
+this doc covers the **script's structure**.
+
+## How it works
+
+`processOrder()` runs three phases per Compass SO, newest-first. **Phase ordering is load-bearing:
+Phase 0 must run before Phase 1/2** because units are **shared up the chain** (the same `Units.id`
+at every level), so unit corrections must land before Phase 2 mirrors fulfillments upward.
+
+### Phase 0 — CG-unit asset-tag merge (new)
+Reproduces retroactively what the forward fix does at `library/app/api/toga2.php` (~lines 3688–3965):
+NetSuite delivers asset tags on **separate service-item lines** whose part number contains
+`ASSETTAG` (e.g. `ODP-COMPASS-ASSETTAG1`); older Compass imports landed each asset tag as its **own
+`Units` row** whose `serialNumber` holds the CG value (e.g. `CG2000027730`), attached via
+`ItemFulfillmentItemUnits` alongside the real serialized unit on the same fulfillment. Phase 0 folds
+each duplicate CG unit into its real device.
+
+Per fulfillment, order the IFIU-attached units by `ItemFulfillmentItemUnits.id` and split into CG
+(serial starts `CG`) vs real (non-CG serialized), then:
+- **1:1** → merge (≈17,500 fulfillments).
+- **equal N:N** → order-pair and emit a `REVIEW` comment (≈7).
+- **unequal, or zero real units** → logged and skipped (≈184).
+
+Each merge emits, in order:
+1. `UPDATE Units SET assetTag = <CG serial>` on the real unit — **only if empty; never clobbers a
+   different existing tag**.
+2. Repoint `InventoryAdjustmentItemUnits.unitId` CG→real (decided: **repoint, not delete**, to
+   preserve stock history — 14,249 CG units have inventory-adjustment rows).
+3. Delete the CG unit's `ItemFulfillmentItemUnits` rows (and their `..._TrackingNumbers` bridges).
+4. `DELETE` the CG unit.
+
+Scope: **IFIU-attached CG units only** (per developer). DB facts at time of build: 22,288 total
+CG-serial units, none with `assetTag` set; 19,214 attached to an IFIU.
+
+### Phase 1 — header/link/bridge repairs (levels L1–L4)
+Repairs the supply-chain header chain and the item-link bridges. Levels:
+- **L1** `repairOdpPoToAgilantSoLinks` — **always calls NetSuite** (`buildNetsuiteGroupMap`), even
+  when the L1 links already exist.
+- **L2/L3/L4** — NetSuite-free bridge repairs. **L3** repairs the
+  `PurchaseOrderItems_SalesOrderItems` rung (MITS PO item → ODP SO item) that the Flow-B recursive
+  IF mirror depends on.
+
+### Phase 2 — fulfillment mirror climb
+Walks each source ItemFulfillment up the chain (Agilant → ODP → Compass), creating the mirror IFs.
+
+## Level isolation — `runLevel()`
+
+Originally Phase 1 ran L1→L4 with **no isolation**. Because L1 unconditionally calls NetSuite, a
+NetSuite SSL/SOAP failure there threw, `main()`'s catch marked the **whole order FAILED**, and the
+independent NetSuite-free L2/L3/L4 repairs (including the L3 rung Phase 2 needs) were skipped — even
+though L1 usually had nothing to insert (the affected orders' Agilant SOIs were already fully linked,
+so the NetSuite call was pure overhead/risk).
+
+`runLevel()` wraps each Phase-1 level (and each Phase-2 source-IF climb) so **a level's exception is
+logged as a skip and swallowed**, letting the remaining independent levels still emit. This is the
+core reliability fix: independent repairs no longer share a failure fate with L1's external call.
+
+## Write guards — `emit()` vs `emitUnit()`
+
+- `emit()` — the default SQL sink; **hard-blocks any write to the `Units` and `TrackingNumbers`
+  tables**.
+- `emitUnit()` — a narrow helper for the Phase-0 units track that **permits `Units` UPDATE/DELETE
+  but still blocks `TrackingNumbers`**. This is a deliberate, scoped exemption to the
+  never-write-`Units` guard, used only by Phase 0.
+
+Never emit writes to `TrackingNumbers`; existing tracking rows are only ever linked, never created
+(consistent with the Compass workflow invariants).
+
+## Change history
+- 2026-08-18 — Initial doc. Recorded retrofix2.php's Phase 0/1/2 structure, the new **Phase 0
+  CG-unit asset-tag merge** (merge/order-pair/skip cases, the 4 emitted statements, repoint-not-delete
+  for inventory history), the **`runLevel()` level isolation** fix (L1's unconditional NetSuite call
+  no longer fails the whole order and skips the L2/L3/L4 bridge repairs), and the scoped **`emitUnit()`**
+  exemption to the never-write-Units guard. (jcardinal)
+</content>
+</invoke>

package/knowledge/INDEX.md

@@ -12,7 +12,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **togaview** (TOGa View) — 7 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
-- **test** (Test) — 14 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
+- **test** (Test) — 15 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 3 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
 - **tools** (Tools) — 15 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 

package/knowledge/clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md

@@ -5,10 +5,11 @@ project: _Underscore
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-08-04
+updated: 2026-08-18
 owners: ["jcardinal", "bala", "dfranks"]
 files: []
 related:
+  - 1.0/apps/test/features/compass-retrofix2-sql-generator.md
   - clients/compass-usa/profile.md
   - clients/compass-usa/features/asn-to-item-fulfillment.md
   - clients/compass-usa/features/mits-po-to-so-item-linking.md
@@ -71,6 +72,27 @@ back-link chain climbs **Agilant → ODP → Compass**. Item back-links use
 `ItemFulfillmentItems.upstreamItemFulfillmentItemId` the same direction and may be many-downstream →
 one-upstream for bundles.
 
+> **Mirror-gap root cause — a missing item bridge stalls the climb (verified 2026-08-18).** The
+> recursive IF mirror climbs Agilant → ODP → Compass through **BOTH** bridge tables. If the
+> `PurchaseOrderItems_SalesOrderItems` rung linking the Compass/MITS PO item → the ODP SO item is
+> **missing**, the mirror **cannot map past the ODP SO** and never creates the ODP/Compass mirror IFs
+> — the Compass SO shows "nothing fulfilled" even though the Agilant SO has an ItemFulfillment
+> (`c_netsuiteInternalItemFulfillmentId` set, created by NetSuite sync). Orders SA130530, SA130334,
+> SA130430 all had an intact header chain and every other item bridge, but were missing **only** that
+> one rung (confirmed against a healthy order that had it). When diagnosing a Flow-B order that
+> fulfilled upstream but shows empty on Compass, check that specific bridge first.
+
+### Asset tags arrive as separate CG "units" (Flow B)
+NetSuite delivers asset tags on **separate service-item lines** whose part number contains
+`ASSETTAG` (e.g. `ODP-COMPASS-ASSETTAG1`). Older Compass imports landed each asset tag as its **own
+`Units` row** whose `serialNumber` holds the CG value (e.g. `CG2000027730`), attached via
+`ItemFulfillmentItemUnits` alongside the real serialized unit on the **same** fulfillment. The
+forward fix (`library/app/api/toga2.php` ~lines 3688–3965) applies those asset tags to the serialized
+items **in order** and sets `Units.assetTag` on the real device. Retroactively this is Phase 0 of the
+[retrofix2 tool](../../../1.0/apps/test/features/compass-retrofix2-sql-generator.md); because units
+are **shared up the chain** (same `Units.id` at every level), the correction must land before the
+fulfillment mirror climbs.
+
 ## Expected raw-data invariants (for detect-and-repair)
 
 1. **Links:** every SOI that should be procured has exactly one PURE bridge to the matching POI on the
@@ -141,12 +163,18 @@ column is `ON UPDATE CURRENT_TIMESTAMP`), which can look like a fresh modificati
 `api2` cXML ShipNotice handler; the `_underscore` recursive item-fulfillment engine.
 
 ## Retrofix tooling
-A standalone repair script lives in the worker 1.0 test area (`test/@jeff/compass/retrofix.php`,
-machine-local path tracked in dev memory). It sweeps Compass SOs newest-first, detects deviations from
-the invariants above, and repairs via direct SQL on `db_prod2_compass`. Safety rules baked in: rehearsal
-mode (logs intended writes, rolls back), per-phase gating, a hard block on any write to the
-`TrackingNumbers` table, and the never-over-fulfill cap. It is a diagnostic/repair tool, not part of the
-runtime workflow.
+The current repair script is **`test/@jeff/compass/retrofix2.php`** (1.0 `App_`), which
+**supersedes** the older `retrofix.php` sibling in the same folder. Unlike the description below of the
+earlier tool, retrofix2 **emits review-first `.sql`** rather than writing the DB directly. It runs
+three phases newest-first per SO — **Phase 0** (CG-unit asset-tag merge; must run first because units
+are shared up the chain), **Phase 1** (header/link/bridge repairs, levels L1–L4, where L3 fixes the
+`PurchaseOrderItems_SalesOrderItems` rung the mirror needs), **Phase 2** (fulfillment mirror climb).
+Each level is wrapped in `runLevel()` so one level's exception (notably L1's unconditional NetSuite
+call failing) is logged as a skip and swallowed, letting the independent NetSuite-free repairs still
+emit. Write guards: `emit()` hard-blocks `Units` and `TrackingNumbers` writes; the Phase-0-only
+`emitUnit()` permits `Units` UPDATE/DELETE but still blocks `TrackingNumbers`. Full structure in the
+[retrofix2 feature doc](../../../1.0/apps/test/features/compass-retrofix2-sql-generator.md). It is a
+diagnostic/repair tool, not part of the runtime workflow.
 
 ## Edge cases & escalation
 - Incomplete orders (no PO/ASN/Agilant leg yet) are normal — repair only the layers that exist.
@@ -155,6 +183,12 @@ runtime workflow.
 - High-multiplier over-fulfillment (5×–20×) does not fit the split-PO spurious-link pattern — separate cause.
 
 ## Change history
+- 2026-08-18 — Recorded the **Flow-B mirror-gap root cause** (a missing `PurchaseOrderItems_SalesOrderItems`
+  rung stalls the recursive IF mirror past the ODP SO, so a fulfilled Agilant order shows empty on
+  Compass — orders SA130530/SA130334/SA130430), the **CG asset-tag "unit" data shape** (asset tags land
+  as their own CG-serial `Units` rows), and repointed the Retrofix tooling section to the new
+  **retrofix2.php** (review-first `.sql`; Phase 0/1/2; `runLevel()` level isolation; `emit()`/`emitUnit()`
+  write guards). (jcardinal)
 - 2026-08-04 — Added the **"empty shell" order signature** — the ODP importer writes the SO header
   and its items in two separate API requests, so a fatal on the second leaves a committed,
   zero-item order — plus the three orphan sweeps that detect it (zero-item SOs, zero-item POs, ODP

package/knowledge/sessions/2026-08-18-table-cell-actions-surface-apeterson.md

@@ -0,0 +1,61 @@
+---
+type: session
+slug: table-cell-actions-surface
+title: Table cell/row actions — settle surface-layer design
+author: apeterson
+repos: [dbchanges2, api2, toga25-supply]
+framework: "2.0"
+client: elite
+status: active
+created: 2026-08-18
+updated: 2026-08-18
+---
+
+# Session: table-cell-actions-surface
+**Date:** 2026-08-18
+**Project/Repo:** dbchanges2 / api2 / toga25-supply (2.0)
+**Task:** Recover the settled design for moving table cell/row actions (e.g. Elite's "See units" chevron) into the surface layer so per-client visibility (Elite off, NYCHH on) is a surface override — and clean up the stale first-attempt migration.
+
+---
+
+## What WORKED
+- Located the original design conversation: **api2 session `e761c825-6073-40fc-ab0f-a984bca7f770`** (Aug 13, 2026, `surface-layer` branch). Transcript at `~/.claude/projects/-Applications-XAMPP-xamppfiles-htdocs-api2/e761c825-6073-40fc-ab0f-a984bca7f770.jsonl` (1076 lines, 3.2MB).
+- Extracted the full plan/decision text verbatim via a general-purpose subagent (raw dump saved at `scratchpad/dump.txt` in the api2 session scratchpad). The settled design is captured in this session's Decisions section.
+- Confirmed current on-disk SQL state in `dbchanges2`: **no Phase 1/Phase 3 SQL for the final plan exists yet**; grep for `ROW_ACTIONS` only hit unrelated Core seeds (SalesOrder login surface, PO details row-action menu item 2026-08-18a).
+- **Deleted the stale migration** `dbchanges2/Client_Elite/2026-08-14a - InventoryUnitsByItemsRemoveUnitsDrill.sql` (the rejected drop-the-grouping-level approach). Shows as staged deletion (`D`) in git — NOT yet committed.
+
+## What did NOT work — DO NOT RETRY THESE
+These are the mechanisms explicitly rejected in the e761c825 design thread. Do not re-propose them:
+- **Dropping the `inventory_units` grouping level** from Elite's `unitsByItems` CONFIG override (the shipped `2026-08-14a` migration). Reason: destroys the nested-table definition instead of just hiding the button; wrong mechanism. This file was deleted this session.
+- **Per-field `is*` boolean flags** (`isNestedTableEnabled`, `isRowActionEnabled`, `isCellActionEnabled`) on `TableViews`. Reason: wrong grain — a drill/action is not a field capability like isSortable; and it would duplicate the existing `childTableViewId`.
+- **A new dedicated binding table** (`TableViewCellActions` / `TableViewFieldActions`). Reason: label/icon/style/visibility/ACL/per-client overrides is *the surface layer's entire job* — a parallel table duplicates `SurfaceElements` + `SurfaceOverrides`.
+- **Table-meta `actions[]` array with numeric `surfaceElementId` pointers** (the `surfaceElementId: 412` sketch). Reason: superseded once the schema explore found `Surface.type=ROW_ACTIONS` + `Surface.tableViewId` + `SurfaceElement.recordFieldId`/`actionId` already bind everything natively. Also numeric id is wrong key — emitted element key is the `uuid`.
+
+## Not tried yet (candidates for next session)
+- **Phase 1 SQL** — seed a `ROW_ACTIONS` surface for `inventory_units` (`Core.Surfaces` `type=ROW_ACTIONS`, `tableViewId=<inventory_units view>`) + a "See units" BUTTON `SurfaceElement` (labelMessageId, `iconToken=chevronsRight`, an `actionId` for a nested-table action, anchored to its column).
+- **Phase 2 FE** — cell-action renderer in `toga25-supply`/`toga-blox`: fetch the table's `ROW_ACTIONS` surface, render each element as a cell action, wire behavior via `actionRegistry` (add nested-table/route/modal handlers), replace hardcoded `makeSeeUnitsColumns`. Injection point: `useGenericTableViewModel.tsx:36-63` meta memo → `actionColumns`.
+- **Phase 3 Elite** — one `SurfaceOverride` row `isVisible=0` on the "See units" element for Elite.
+- **CTO second opinion** — recommended in the original thread, never run.
+- **Verify whether deleted `2026-08-14a` was already applied to sandbox** — if so, DB state still has the drill dropped; may need the Phase work (or an interim revert) to restore.
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| `dbchanges2/Client_Elite/2026-08-14a - InventoryUnitsByItemsRemoveUnitsDrill.sql` | Deleted (staged, uncommitted) | Rejected drop-the-grouping-level approach; removed per final design |
+| `scratchpad/dump.txt` (api2 session scratchpad) | Created | Raw verbatim extraction of the e761c825 design thread |
+
+## Decisions made
+- **Surface layer owns cell/row actions** — not a new table, not FE hardcoding. The button (label, icon, style, visibility, enablement, ACL, per-client/role/persona overrides) is a `SurfaceElement` on a `type=ROW_ACTIONS` Surface linked to the table via `Surface.tableViewId`. Rationale: the surface layer already models all of this; a parallel mechanism duplicates it. Vindicates the original "this is surface-layer" instinct — only earlier mechanisms were wrong.
+- **Grain rule:** table-level toggles → table block; per-cell action presentation → surface element bound to a field (`recordFieldId`/`customRecordFieldId`). Cell action (chevron) and row action (row-click → modal) are conceptually independent (today wrongly coupled at `GenericNestedTables.tsx:37-42`).
+- **Elite vs NYCHH gating** = one `SurfaceOverride` `isVisible=0` on the "See units" element scoped to Elite; element stays visible for NYCHH/others on the same shared table.
+- **Cross-DB binding** (Core surface ↔ Client table view) uses **soft integer FKs** — framework FK traversal can't cross Core↔Client. Stable FE-facing key is the SurfaceElement **uuid**, not numeric id. CONFIG override REPLACES (does not merge).
+- **Two open questions to settle before seeding:** (1) how FE finds a table's ROW_ACTIONS surface — lean **slug convention** `<tableViewSlug>-row-actions` over `tableViewId` query; (2) how element anchors to a column — lean **column-slug in element `config`** over `recordFieldId`.
+
+## Blockers
+- None hard. Soft: the two open questions above should be settled before writing Phase 1 SQL; and confirm whether `2026-08-14a` was already applied to sandbox before assuming Elite DB is clean.
+
+## Exact next step
+> Settle the two open questions (slug-convention lookup + column-slug-in-config anchor), then write **Phase 1 SQL**: a `Core/` migration seeding the `inventory_units` `ROW_ACTIONS` surface + "See units" BUTTON `SurfaceElement`. Check first whether deleted `2026-08-14a` was applied to sandbox.
+
+---
+_Saved by /session-save on 2026-08-18_

package/package.json

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