toga-ai 1.0.370 → 1.0.372

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

@@ -2,6 +2,7 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
+| [Proposed — ExternalIdentifiers map table for integration id ↔ external-system linkage](architecture/external-identifiers-map-table.md) | A **proposal / counter-proposal (status: proposed — nothing here is built)** that cross-system identifier linkage (e.g. | _underscore/Model/Forecast/Opportunity.php, worker2/Worker/Netsuite/Opportunity.php |
 | [Proposed — git-sourced base+overlay JSON authoring for the Surface layer](architecture/surface-authoring-proposal.md) | A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model move off hand-authored SQL against the `SurfaceOverrides` E | _underscore/Model/Core/Surface.php, _underscore/Model/Client/SurfaceOverride.php |
 | [_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 |
@@ -18,10 +19,11 @@
 | [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). | worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/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/fixer.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [Item-Fulfillment Stage Lifecycle (picked/packed/shipped) & Order Status](features/item-fulfillment-stage-lifecycle-and-order-status.md) | Every ItemFulfillment (IF) now carries an explicit **stage** — picked → packed → shipped — resolved through `ItemFulfillmentStages → ItemFulfillmentStatuses` (m | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Client/SalesOrderItem.php, _underscore/Model/Client/Item.php, _underscore/Model/Client/PurchaseOrderItem.php, library/app/api/toga2.php, dbchanges2/Client/2026-06-30a - BackfillNullStageItemFulfillmentsToShipped.sql, dbchanges2/Client/2026-06-30b - SalesOrderStatusesPickedPacked.sql, dbchanges2/Client/2026-06-30c - ItemFulfillmentStageIdNotNull.sql, dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql |
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
+| [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
-| [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Client_Compass/2026-07-15f - SalesOrderRecordActionsRemoveDeadConfigRuleOverrides.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php |
+| [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Client_Compass/2026-07-15f - SalesOrderRecordActionsRemoveDeadConfigRuleOverrides.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView |  |
 | [Refreshing a Local Dev Database from Beta (dev-sandbox)](workflows/local-db-refresh-from-beta.md) | How to reset a local 2.0 dev database from the **beta / dev-sandbox** environment: dump each schema (`Core`, `Client_<Id>`, `Logs_<Id>`, …) from the beta host, | api2/Config/, _underscore/Loader.php, _underscore/Model/Client/BundleTranslation.php, api2/Component/Api/V2/V2.php, toga25-supply/sync_compasscanada_schema.sql |

package/knowledge/2.0/apps/_underscore/architecture/external-identifiers-map-table.md

@@ -0,0 +1,77 @@
+---
+title: Proposed — ExternalIdentifiers map table for integration id ↔ external-system linkage
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: architecture
+status: proposed
+updated: 2026-07-17
+owners: ["dfranks"]
+files:
+  - _underscore/Model/Forecast/Opportunity.php
+  - worker2/Worker/Netsuite/Opportunity.php
+related:
+  - ../features/model-save-vs-query-atomic-update.md
+  - ../../worker2/features/netsuite-opportunity-sync.md
+---
+
+## Summary
+
+A **proposal / counter-proposal (status: proposed — nothing here is built)** that cross-system
+identifier linkage (e.g. a NetSuite opportunity ↔ its ClickUp task id) live in a dedicated
+**`ExternalIdentifiers` map table** rather than as ad-hoc columns bolted onto whichever business
+table happens to be nearby. The immediate driver is the TRUE-80044 atomic ClickUp-task claim, whose
+currently-mandated approach adds a `clickupTaskId` column to `Forecast.Opportunities`. This doc is
+`dfranks`'s architectural counter-proposal to that mandate, raised for open discussion — **not** a
+silent supersede of the reviewer decision. See the rebuttal section below.
+
+**Critical framing:** This is a **proposal under open discussion**, not the current system and not a
+settled reversal. The mandated approach on record (a `clickupTaskId` column on
+`Forecast.Opportunities`) remains the standing decision until the disagreement is resolved with the
+reviewer.
+
+## Design
+
+A single shared table keyed by (local record identity, external system, external id kind):
+
+- **Columns (sketch):** `id`, `entityType` (e.g. `opportunity`), `entityId` (the local business
+  key, e.g. `netsuiteOpportunityInternalId`), `externalSystem` (e.g. `clickup`), `externalIdKind`
+  (e.g. `task`), `externalId` (the value/sentinel), plus `dtCreated`/`dtUpdated`.
+- **Uniqueness:** a UNIQUE index on `(entityType, entityId, externalSystem, externalIdKind)` — this
+  is the single-row lock that makes the atomic claim (`UPDATE … SET externalId='<uuid sentinel>'
+  WHERE … AND externalId IS NULL`, commit, `affectedRows===1` wins) work exactly as the mandated
+  column approach would, but without touching the Forecast schema.
+- **Atomic claim mechanics are unchanged** from the mandated design — same raw `_Query` guarded
+  UPDATE (ORM `save()` cannot express it — see
+  [model-save-vs-query-atomic-update](../features/model-save-vs-query-atomic-update.md)), same
+  commit-before-external-side-effect, same sentinel-guarded compensation-delete on failure.
+
+## Rebuttal to the clickupTaskId-column mandate
+
+`2.0/apps/worker2/features/netsuite-opportunity-sync.md` records reviewer **Rohan Girish** mandating
+(2026-07-15) that the ClickUp-task dedup claim be implemented as a **`clickupTaskId` column on
+`Forecast.Opportunities`**, and rejecting the earlier plan's dedicated table. This doc is `dfranks`'s
+**counter-proposal**, offered as an open architectural disagreement to be resolved *with* the
+reviewer — the mandate stands until then. The three rebuttal arguments:
+
+1. **Separation of concerns.** A ClickUp task id is *integration-linkage* state, not a business
+   attribute of a Forecast opportunity. Storing it on `Forecast.Opportunities` conflates the
+   integration/mapping layer with the forecasting domain model.
+2. **Forecast-schema dumping-ground.** Every future external linkage (a second external system, a
+   different id kind) under the column approach means another one-off nullable column on a business
+   table, accreting integration cruft on the Forecast schema. A map table absorbs all of them with
+   no schema change per linkage.
+3. **Forecast-sync lifecycle decoupling.** The integration mapping must be able to **outlive a
+   possibly-discontinued Forecast sync.** Binding the ClickUp linkage to the Forecast opportunity row
+   ties its lifetime to the Forecast importer; if that sync is ever retired or reworked, the mapping
+   goes with it. A standalone map table keeps the NS↔ClickUp linkage durable independently of
+   Forecast.
+
+This is framed as a disagreement to resolve, not a reversal already taken. If the reviewer position
+holds, the mandated column approach is what ships.
+
+## Change history
+
+- 2026-07-17 — Proposed as a rebuttal to the reviewer-mandated clickupTaskId-column approach
+  (TRUE-80044). (dfranks)

package/knowledge/2.0/apps/_underscore/features/model-save-vs-query-atomic-update.md

@@ -0,0 +1,75 @@
+---
+title: _Model::save() vs raw _Query — no atomic conditional update
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-17
+owners: ["dfranks"]
+files:
+  - _underscore/Model.php
+  - _underscore/Query.php
+related:
+  - ./model-magic-field-access.md
+  - ../../worker2/features/netsuite-opportunity-sync.md
+---
+
+## Summary
+
+`_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic
+conditional update** (an optimistic-concurrency / row-claim guard such as
+`... WHERE col IS NULL`). For any DB-level claim / optimistic-concurrency pattern you must drop
+to raw `_Query` — `_Query::getAffectedRows()` is the only surface that exposes an affected-rows
+count, which is what a claim needs to know whether *this* caller won. `save()` remains the correct
+idiom for ordinary by-primary-key writes.
+
+## How it works
+
+`_Model::save()`'s update branch always emits:
+
+```sql
+UPDATE <table> SET <changed cols> WHERE <primaryKey> = <id>
+```
+
+(`Model.php` ~line 285). Consequences that make it unusable for a conditional claim:
+
+- **No conditional guard.** The `WHERE` is hard-coded to the primary key; there is no way to attach
+  an extra predicate like `AND clickupTaskId IS NULL`. So two concurrent callers both pass any
+  in-PHP check and both write — the update is not a claim.
+- **Skips the write when nothing changed.** If no field differs from the loaded row, `save()` emits
+  no UPDATE at all. A claim that relies on "did my write land?" gets no signal.
+- **Returns no affected-rows count.** `save()` does not surface how many rows the UPDATE touched, so
+  even a guarded statement (if it could emit one) couldn't be adjudicated through the model.
+
+**For an atomic claim / conditional update, use `_Query` directly.** `_Query::getAffectedRows()`
+(`Query.php` line 106) is the only API that exposes the affected-rows count. The idiom is:
+
+```php
+// UPDATE ... SET claim='<sentinel>' WHERE <businessKey>=? AND claim IS NULL  (raw _Query)
+// then commit; affectedRows === 1 → this caller won the claim; === 0 → another already claimed it.
+```
+
+Back the guarded UPDATE with a UNIQUE index on the business key so it locks a single row, and commit
+before any external side effect so the row lock is released (and to dodge the `_Database` lazy-transaction
+write-drop). All **non-claim** writes stay on the ORM — `save()` is fine for plain
+load → set → save → `transactionCommit` by primary key (the idiom
+`_Worker_Netsuite_Opportunity::delete()` already uses).
+
+## Gotchas / known issues
+
+- Do **not** reach for `save()` to implement a row-claim / optimistic-concurrency guard — it silently
+  degrades to a non-atomic check-then-act because its `WHERE` is primary-key-only and it exposes no
+  affected-rows count. Use raw `_Query` + `getAffectedRows()`.
+- A no-diff `save()` emits **no** UPDATE, so "the write must have run because save() returned" is not a
+  safe assumption.
+
+## Change history
+
+- 2026-07-17 — Documented that `_Model::save()` cannot perform an atomic conditional update
+  (primary-key-only `WHERE`, skips no-diff writes, no affected-rows count) and that raw `_Query` +
+  `_Query::getAffectedRows()` is the required surface for any DB row-claim / optimistic-concurrency
+  pattern. Surfaced while designing the TRUE-80044 atomic ClickUp-task claim. (dfranks)
+</content>
+</invoke>

package/knowledge/2.0/apps/_underscore/features/surface-resolver.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-16
+updated: 2026-07-17
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Core/Surface.php
@@ -20,6 +20,13 @@ files:
   - dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql
   - dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql
   - dbchanges2/Client_Compass/2026-07-15f - SalesOrderRecordActionsRemoveDeadConfigRuleOverrides.sql
+  - dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql
+  - dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql
+  - dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql
+  - dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql
+  - dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql
+  - dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql
+  - dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql
   - _underscore/Model/Core/SurfaceElement.php
   - _underscore/Model/Core/Action.php
   - _underscore/Model/Core/Vocabulary.php
@@ -186,16 +193,35 @@ Compass's shape. Core was re-baselined as a true shared default so clients store
 4. Edit-in-Commerce only for Compass / CompassCanada.
 5. Columns button hidden by default.
 
-Per-client diffs layered on top:
-- **Quad** — Approve + Deny only; filter narrowed to `pendingApproval`; filter button visible.
-- **Compass USA / Compass Canada** — two-stage approvals: record-action `visibilityRule`/`enabledRule`
-  = `in [pendingApproval, pendingInitialApproval]`. **Compass Canada** additionally gets a `CONFIG`
-  override on the approvals filter button (surface `sales-order-listing-actions`) to add
-  `pendingInitialApproval`.
-
-> ⚠ **Regression left open:** the Compass / CompassCanada **non-rule** overrides (Edit-in-Commerce
-> flags, role-8 Manager hides) were **wiped during the rebuilds and not re-added**. The two-stage rule
-> overrides are also LOCAL only (see above).
+### Per-client sales-order button diffs — materialized 2026-07-17
+The Core neutral default now covers the **approvals filter button too**: `Core/2026-07-17h` cleared
+element 22's `config` to `{}`, so Core carries no `_status` default and **every** client (even Quad,
+whose value matches the old default) supplies the whole filter `CONFIG` via its own override (REPLACE
+semantics). Concrete per-client diffs, all via `SurfaceOverrides` (rule JSON is
+`{"all":[{"field":"order._status","op":"in","value":[…]}]}`; seed authoring/element-id map in the
+[surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md) doc):
+
+- **Compass USA / Compass Canada** (mirror each other) — two-stage approval:
+  - **ADMIN**: opts into all four gated record-action buttons (approve/deny/approvalWorkflow/editOrder)
+    `IS_VISIBLE=1`, and widens **both** `VISIBILITY_RULE` **and** `ENABLED_RULE` to
+    `_status in [pendingApproval, pendingInitialApproval]`. (For approve, the Tier-2 `stepTwoAssigned`
+    predicate still further gates *enabled* in PHP.) On the approvals filter button: `IS_VISIBLE=1` +
+    `CONFIG` `additionalData._status = [pendingApproval, pendingInitialApproval]`.
+  - **MANAGER**: opts into **approve + deny only** (`IS_VISIBLE=1`); rules left at the Core base
+    (`pendingApproval` only, single-stage). No approvals-filter override → inherits Core `isVisible=0`
+    (hidden).
+- **Quad** — Approve + Deny only, visible for **role ids 7/8/9** (`IS_VISIBLE=1`), with **no** rule
+  override (status stays at the Core base `pendingApproval`). This is deliberately **per-role**, unlike
+  Quad's usual client-wide (`roleId NULL`) pattern — per request. Approvals filter button is
+  client-wide with `CONFIG` `_status=[pendingApproval]`; the "Enter PO Details" button (element 32) is
+  made client-wide visible (⚠ dual-gate — see the schema doc; the FE may also read `config.isVisible`).
+
+> ✅ **Regression (mostly) closed:** the two-stage rule overrides and the record-action/filter opt-ins
+> for Compass / Compass Canada that were wiped in the earlier rebuild were **re-added 2026-07-17**
+> (`Client_Compass`/`Client_CompassCanada/2026-07-17a`+`b`). These surface DB changes remain **local/
+> beta only** pending promotion; the `_underscore` rule-override code + the ENUM widening still ship
+> together on promotion, and the php-reviewer pass + PHPUnit regression for the rule-override path are
+> still outstanding.
 
 ### Operational gotcha — raw SQL bypasses the cache-bust
 Raw SQL against the surface tables bypasses the model-layer cache-bust, so the on-disk bundle cache
@@ -312,6 +338,14 @@ Core record grants + their logic-group expressions all evaluate `all`/`"1"`. The
   match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-07-17 — Materialized the per-client sales-order button diffs (re-adding the overrides wiped in
+  the earlier rebuild): Compass/CompassCanada ADMIN = all four record-action buttons visible + both
+  `VISIBILITY_RULE`/`ENABLED_RULE` widened to `[pendingApproval, pendingInitialApproval]`, MANAGER =
+  approve+deny visible with Core-base rules; Quad = approve+deny visible per-role (ids 7/8/9), no rule
+  override. Extended the Core neutral default to the **approvals filter button** — `Core/2026-07-17h`
+  cleared element 22's config so every client (including Quad) now supplies the full filter `CONFIG`
+  (REPLACE semantics): Compass/CC admin = two statuses, Quad client-wide = `pendingApproval`. Overrides
+  remain local/beta only pending promotion. (apeterson)
 - 2026-07-16 — Recorded a resolver gotcha: a `SurfaceOverrides` row with `attribute='CONFIG'` carrying
   a rule value is silently dead — `_castOverride` routes CONFIG→`$config`, not
   `$visibilityRule`/`$enabledRule` (logs + returns null), and `overridesByElementAndAttr` keyed by

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

@@ -3,5 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
-| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql |
+| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | How to manually stand up a new 2.0 client (tenant). | Client/, Client_<Tenant>/, Core/, Logs_Client/ |

package/knowledge/2.0/apps/dbchanges2/features/surface-layer-schema.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-07-16
+updated: 2026-07-17
 owners: [jcardinal, apeterson]
 files:
   - dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql
@@ -31,6 +31,13 @@ files:
   - dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql
   - dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql
   - dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql
+  - dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql
+  - dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql
+  - dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql
+  - dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql
+  - dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql
+  - dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql
+  - dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql
 related:
   - ../../_underscore/features/surface-resolver.md
 ---
@@ -114,6 +121,52 @@ it `isVisible: true`. Both `Core/2026-06-29a` (Item) and `Core/2026-06-29d` (Ven
 off." A client opts a role in via a `SurfaceOverride` (`IS_VISIBLE=1`), scoped by role/persona. This is
 the seed-authoring corollary of the Core neutral-default re-baseline recorded in the resolver doc.
 
+## Sales-order button overrides — element identities & the id-agnostic authoring house style
+
+When a client opts its roles into the sales-order action/filter buttons (the resolved per-client
+*behavior* lives in the [surface-resolver](../../_underscore/features/surface-resolver.md)
+per-client-diffs section), the override seeds follow a strict **id-agnostic house style** so one file
+runs unchanged across local/beta/prod:
+
+- **Resolve `roleId` by `Roles.name`** (`'Admin'`/`'Manager'`) — client role ids are environment-specific.
+- **Resolve the Core element by surface slug + one discriminator**, never a hardcoded Core id:
+  `Core.Actions.slug` for action buttons; the **label `messageKey`** (`salesOrder.filter.approvals`)
+  for the approvals filter button — it has no `actionId` and, after the Core config wipe (below), no
+  `config` left to match on; or `config.valueKey` (`poNumber`) for the "Enter PO Details" button.
+- **`personaId`/`languageId` NULL** for role/client scope (language-agnostic).
+- **Every INSERT guarded by `NOT EXISTS`** on `(surfaceElementId, roleId, attribute, personaId NULL,
+  languageId NULL)` so the file is re-runnable. A per-role Quad seed does this with a
+  `CROSS JOIN (SELECT 7 UNION ALL SELECT 8 UNION ALL SELECT 9)` + a `Roles` existence join, so a
+  missing role id is skipped rather than erroring.
+- Cross-DB read of `Core.*` from the client seed mirrors the established Surface override pattern
+  (safe where Core+client are co-located; the prod cross-cluster caveat in the gotchas applies).
+
+**Which attribute for which change:** `IS_VISIBLE`/`CONFIG` are in the base attribute ENUM;
+`VISIBILITY_RULE`/`ENABLED_RULE` require the widened ENUM
+(`Client/2026-07-15 - SurfaceOverridesAttributeRuleValues.sql`) applied per-tenant first (see the
+resolver doc — an unknown ENUM value silently coerces to `''` in non-strict mode). A `CONFIG` override
+**replaces the whole object**, so a filter override must carry the full config
+(`role`+`filterKey`+`additionalData`), never just the changed key.
+
+**Sales-order surface element identities** (Core seed `2026-07-17c` assigns EXPLICIT, stable ids — but
+author overrides by slug/messageKey/valueKey, not by these numbers):
+
+| Surface (id) | Element | id | Discriminator |
+|---|---|---|---|
+| `sales-order-record-actions` (8) | approve | 17 | action `salesOrder.approve` |
+| | deny | 18 | action `salesOrder.deny` |
+| | approvalWorkflow | 19 | action `salesOrder.approvalWorkflow` |
+| | viewLog | 20 | always-visible / ungated (excluded from overrides) |
+| | editOrder | 21 | action `salesOrder.editOrder` |
+| | Enter PO Details | 32 | no `actionId`; `config.valueKey='poNumber'` |
+| `sales-order-listing-actions` (9) | approvals filter | 22 | label messageKey `salesOrder.filter.approvals` |
+| | columns | 23 | — |
+
+**Core approvals-filter default removed (`Core/2026-07-17h`).** Core element 22's `config` was cleared
+to `{}` so Core carries **no** `_status` default. Every client — even Quad, whose config matches the
+old default — now declares the full filter config via its own `CONFIG` override. This makes the Core
+seed a true neutral default for the filter button, matching the action-button rule above.
+
 ## ThemeTokens — per-tenant, physically isolated in each client DB
 
 `ThemeTokens` lives **inside each tenant's own database** (`Client_Compass.ThemeTokens`,
@@ -251,8 +304,32 @@ rule resumes.
   flip a section per role/persona. Also discovered: `elementType` in `orderViewFields.json` is **dead
   config** (no renderer reads it); and MANAGER/Quad summary tooltips can't be removed via the cascade
   because `TOOLTIP_MESSAGE` is numeric-only (cosmetic, deferred).
+- **`Client_CompassCanada` may be missing the `SurfaceOverrides` table entirely** (its beta reset
+  predates the surface rollout). Prereqs — in order — **before any CompassCanada surface override
+  runs:** `Client/2026-06-25a - SurfaceClientTables.sql` (creates `ThemeTokens`/`MessageTranslations`/
+  `SurfaceOverrides`), then `Client/2026-07-15 - SurfaceOverridesAttributeRuleValues.sql` (ENUM
+  widening for the rule attributes); and for the `/surfaces/meta` endpoint to resolve at all, the ACL
+  dispatch grants (`Client/2026-06-25c`, `2026-06-29c`, `2026-06-30a`). Skipping the table/ENUM
+  bring-up makes the `2026-07-17a/b` override inserts fail or silently coerce.
+- **"Enter PO Details" (element 32) has a DUAL visibility gate.** Its rendering is gated by BOTH the
+  element-level `isVisible` flag AND a `config`-embedded `"isVisible":false` (migrated from Quad's
+  legacy field JSON, alongside `isEnabled`/`isComplete`). Flipping the element-level `IS_VISIBLE=1`
+  (as `Client_Quad/2026-07-17b` block 3 does) may **not** render the button if the FE
+  (`SalesOrderTopBar`) reads `config.isVisible` — in which case a `CONFIG` override is also needed.
+  Element 32 is likewise `isEnabled=0` (appears but disabled until an `IS_ENABLED`/`ENABLED_RULE`
+  override is added). **Open follow-up.**
 
 ## Change history
+- 2026-07-17 — Applied the Core-neutral-default → client-opt-in pattern to the sales-order action &
+  filter buttons across Compass, CompassCanada, and Quad (`Client_*/2026-07-17a`+`b`). Cleared the
+  Core approvals-filter `_status` default (`Core/2026-07-17h`) so every client declares its own filter
+  `CONFIG`. Documented the sales-order surface **element-identity map** (surface 8 elements 17-21/32;
+  surface 9 elements 22-23) and the **id-agnostic override authoring house style** (resolve `roleId`
+  by name; resolve Core elements by surface slug + `Actions.slug`/label messageKey/`config.valueKey`;
+  `personaId`/`languageId` NULL; `NOT EXISTS`-guarded). Added gotchas: `Client_CompassCanada` may lack
+  the `SurfaceOverrides` table (beta reset predates rollout — table/ENUM/ACL prereqs must run first),
+  and "Enter PO Details" (element 32) has a dual visibility gate (element-level `isVisible` AND a
+  `config.isVisible` the FE may also read). (apeterson)
 - 2026-07-16 — Documented `SurfaceElements`' two orthogonal axes (`valueType` display vs `inputType`
   edit widget — neither derived from the other) and the edit-mode columns added in `Core/2026-06-25a`
   (`inputType`, `validationType` [renamed from `hasTypeCheck`], `showRequiredIndicator`, `isSearchable`,

package/knowledge/2.0/apps/worker2/features/netsuite-opportunity-sync.md

@@ -31,6 +31,7 @@ files:
 related:
   - ./netsuite-salesorder-open-orders-sync.md
   - ../architecture.md
+  - ../../_underscore/architecture/external-identifiers-map-table.md
 ---
 
 ## Summary
@@ -177,6 +178,9 @@ tasks. The fix is a **race-safe DB claim** on the **existing `Forecast.Opportuni
 `NetsuiteOpportunityClickupTask` table in `Client_True`; reviewer Rohan Girish rejected that and mandated
 reusing `Forecast.Opportunities`.)
 
+A counter-proposal (ExternalIdentifiers map table) has been raised — see
+`_underscore/architecture/external-identifiers-map-table.md`; unresolved.
+
 How the claim is race-safe:
 - **Conditional UPDATE = the atomic claim.** A raw `_Query`:
   `UPDATE Opportunities SET clickupTaskId='<uuid sentinel>' WHERE netsuiteOpportunityInternalId=X AND

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 33 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 35 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 30 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 12 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/package.json

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