toga-ai 1.0.717 → 1.0.719

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-29
+updated: 2026-09-01
 owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
@@ -118,6 +118,23 @@ belong to the NetSuite importer — documented in the per-client-sync doc, not h
 - `page`/`recordsPerPage`/`depth`/`calcDepth`/`key` pass through. Pagination is the universal
   `for ($page=1,$nextPage=0; !is_null($nextPage); ++$page)` loop reading `meta->nextPage`.
 
+> **⚠ `where` needs the `and` / `or` key even for a SINGLE condition.** A bare list of conditions
+> compiles to something api2 rejects with **HTTP 500, error code `EO-1`, and an empty
+> `transactionId`** — no usable message to work from.
+>
+> ```php
+> // WRONG — 500 / EO-1
+> 'where' => [ ['Items.partNumber' => ['in' => $partNumbers]] ]
+>
+> // CORRECT — the operator key is mandatory at every level
+> 'where' => [ 'and' => [ ['Items.partNumber' => ['in' => $partNumbers]] ] ]
+> ```
+>
+> The realistic way to hit this is **deleting a condition from an existing multi-condition
+> `where`** — the one surviving line looks like it can stand on its own. Cost a deploy cycle in
+> Compass cron 3a on 2026-08-31
+> ([ODP EDI 850 line-item resolution](../../../clients/compass-usa/features/odp-edi-850-item-resolution.md)).
+
 ### `syncWithToga()` — 2.0 → 1.0 (TOGa)
 
 Signature: `(int $togaClientId, string $clientUuid, string $apiKey, string $apiSecret,
@@ -396,6 +413,12 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-09-01 — Recorded an options-DSL gotcha: a `where` with a **single** condition still
+  needs the `'and' =>` (or `'or' =>`) wrapper — a bare list of conditions makes api2 return
+  **HTTP 500 `EO-1` with an empty `transactionId`**, no usable message. Most often hit by
+  **deleting a condition from an existing multi-condition `where`**, because the one surviving
+  line looks like it can stand alone. Cost a deploy cycle in Compass cron 3a on 2026-08-31.
+  (bala)
 - 2026-08-29 — The `*FromNetsuite()` importer methods in this class were **completed onto REST** — the
   item-receipt and inventory-adjustment paths dropped their last `App_NetSuite::` SOAP calls in favor of
   `App_Api_Netsuite_Rest::fetch*ById()`, so the togasupply importer now makes **zero SOAP network

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

@@ -27,7 +27,7 @@
 | [isFulfillable Propagation Up the SO↔PO Chain](features/fulfillable-item-propagation.md) | `Items.isFulfillable` is a boolean that gates whether a storefront line's **Qty Fulfilled** cell is actionable. | _underscore/Model/Client/Item.php, _underscore/Model/Compass/Item.php, toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx, dbchanges2/Core/2026-07-17 - Items isFulfillable RecordField.sql, dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql, dbchanges2/Client/2026-07-17 - ItemsisFulfillable.sql |
 | [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/Canada/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/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 |
 | [DB-free unit testing for _underscore model interceptors](features/model-interceptor-unit-testing.md) | `_underscore` shipped with **no** PHPUnit setup (no `composer.json`/`phpunit`; only vendored PhpOffice tests existed). | _underscore/Test/bootstrap.php, _underscore/Test/Prudential/ServiceRequestTest.php, test/@Bala/tests/netsuite_salesorder_payload_tests.php |
-| [_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, _underscore/Model.php, _underscore/Model/Rate/Subscription.php |
+| [_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, _underscore/Model.php, _underscore/Model/Rate/Subscription.php, _underscore/Model/Client/RecordFieldSetting.php, _underscore/Model/Client/ClientRecordFieldSetting.php |
 | [_Model::save() parent FK cascade — stored-SQL-field recompute deadlocks](features/model-save-parent-cascade-stored-field-deadlock.md) | `_Model::save()` runs a **generic parent foreign-key cascade**: inserting (or saving) a child row that carries an FK to a parent causes `_Model` to **re-load an | _underscore/Model.php, _underscore/Model/Client/PurchaseOrder.php, _underscore/Model/Client/AdvanceShippingNotice.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, _underscore/Model/Rate/Subscription.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, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, _underscore/Trait/Netsuite/SalesOrder.php, worker2/Worker/Netsuite/SalesOrder.php, worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Worker/Netsuite/Opportunity.php |
@@ -42,6 +42,7 @@
 | [SO↔PO bridge tables are TWO tables in OPPOSITE directions (upstream vs downstream)](features/sales-order-purchase-order-bridge-direction.md) | There are **two** bridge tables linking sales orders and purchase orders, and they mean **opposite things**. | _underscore/Model/Client/PurchaseOrders/SalesOrder.php, _underscore/Model/Client/SalesOrders/PurchaseOrder.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/SalesOrder.php, _underscore/Trait/Netsuite/SalesOrder.php, library/app/api/toga2.php |
 | [Per-client sales-order status filter (Surface FILTER_SET → table meta `filterOptions`)](features/sales-order-status-filter-surface.md) | The status-filter dropdown on the sales-orders table is **per client**, driven by a Surface `FILTER_SET` rather than by the raw contents of the client's `SalesO | _underscore/Model/Client/TableView.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Prudential/SalesOrder.php, toga-blox/src/components/Table/hooks/useFetchTablePageMeta.ts, toga-blox/src/api/types.ts, dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql |
 | [_String helpers — ASCII-safe HTML entity encoding (and the parseBetween trap)](features/string-html-entity-helpers.md) | `_String` is the 2.0 framework's static string utility class. | _underscore/String.php |
+| [Surface FIELD ↔ RecordField binding (maxLength / validationType / isWritable fold-in)](features/surface-field-recordfield-binding.md) | A resolver capability that makes a surface `FIELD` element carry its **input contract** — max length, validator name, and whether the caller may write it — inst | _underscore/Model/Core/Surface.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/AclFieldPermission.php, _underscore/Model/Client/RecordFieldSetting.php, _underscore/Model/Client/ClientRecordFieldSetting.php, dbchanges2/Core/2026-08-14c - RecordFieldsValidationMetadata.sql, dbchanges2/Client/2026-08-14a - RecordFieldSettingsClientTable.sql, api2/Component/Api/V2/V2.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/Client/Language.php, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, toga25-supply/src/App.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/contexts/AuthContext.tsx, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Core/2026-08-21a - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_Compass/2026-08-04a - ApprovalDetailsAssignedManagerPreferredStage.sql, _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, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-12a - NavigationSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-12a - NavigationRoleGrants.sql, toga25-supply/surface-layer-guide.md |
 | [Table-View Hyperlink Columns (meta → ACL → computed URL → render)](features/tableview-hyperlink-columns.md) | Any 2.0 table-view column can render its value as a clickable link instead of plain text. | _underscore/Model/Client/TableView.php, _underscore/Model/Client/TrackingNumber.php, api2/Component/Api/V2/V2.php, toga2-supply/src/api/toga.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/convertData.tsx, toga2-supply/src/components/ui/Tables/hooks/useDataTableState.tsx, dbchanges2/Client/2026-07-20 - TrackingNumberHyperlinkAndFieldPermission.sql |
 | [TableView joins (TableViewJoins → SQL) — aliasing, chained multi-hop joins, ACL](features/tableview-joins.md) | `Client_*.TableViewJoins` rows are what let a table view show a column from a table other than its base record. | _underscore/Model/Client/TableView.php, _underscore/Model.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql, dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_CompassCanada/2026-08-27a - ItemFulfillmentTableViewsRebuild.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql |
@@ -50,4 +51,5 @@
 | [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 | _underscore/Model/Client/ServiceRequest.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql |
 | [USPS DPV Deliverability Verdict (is this address actually insurable/shippable?)](features/usps-dpv-deliverability.md) | **USPS returning HTTP 200 with a populated address is NOT evidence that the address is deliverable.** The authoritative signal is USPS's **DPV (Delivery Point V | _underscore/Component/Library/Carriers/Usps/Usps.php, _underscore/Model/Client/Address.php, _underscore/Model/Rate/Entitlement.php |
 | [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 |
+| [Deleting a shared branch does not remove bad commits — a stale local clone merges them back](workflows/recreated-shared-branch-stale-local-remerge.md) | **Deleting and recreating a shared environment branch removes only the *ref*.** Every teammate who still has that branch checked out locally keeps the full pre- | _underscore/Model/Core/Surface.php, _underscore/Model/Client/RecordFieldSetting.php, api2/.platform/hooks/prebuild/git.sh, api2/.ebextensions/git.php |
 | [Running a 2.0 App Locally (browser, end-to-end via api2)](workflows/running-a-2.0-app-locally.md) | The full dependency chain required to run a 2.0 client app **through the browser**, end-to-end, against a **local `api2`** (e.g. | _underscore/Environment.php, _underscore/Config.php, _underscore/Database.php, _underscore/Route.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, api2/index.php, api2/.htaccess |

package/knowledge/2.0/apps/_underscore/features/model-magic-field-access.md

@@ -6,15 +6,19 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-06
-owners: ["jcardinal", "mhammontree"]
+updated: 2026-09-01
+owners: ["jcardinal", "mhammontree", "apeterson"]
 files:
   - _underscore/Model/Core/Model.php
   - _underscore/Model.php
   - _underscore/Model/Rate/Subscription.php
+  - _underscore/Model/Client/RecordFieldSetting.php
+  - _underscore/Model/Client/ClientRecordFieldSetting.php
 related:
   - ../../api2/features/language-translation-layer.md
   - ./model-save-vs-query-atomic-update.md
+  - ./surface-field-recordfield-binding.md
+  - ../../dbchanges2/workflows/framework-branch-ahead-of-schema.md
   - ../../../../clients/rate/features/subscription-cancellation.md
 ---
 
@@ -59,6 +63,38 @@ $isRequested = trim((string) $subscription->dtRequestToCancel) !== '';
 `_Model` declares `__get`/`__set` only (`_underscore/Model.php:464,481`) — there is no `__isset` on
 the base `_Model` either, so this applies to **every** 2.0 model, not just the Core one.
 
+## Triage rule — "There is no field called 'X' in the '_Model_…' model" is ALWAYS an undeclared non-`c_` column
+
+A **500 `EO-1`** whose `identifiers.message` reads:
+
+```
+There is no field called '<column>' in the '<_Model_...>' model.
+```
+
+is a `_Model::__get()` **throw**, not a database error. It means code read a property the model
+class does not declare. Two things follow immediately, and they cut the search space hard:
+
+1. **It is never a schema problem.** No SQL ran. Do not check `information_schema`, do not suspect a
+   missing migration on *that* column — check the model class.
+2. **The column is never `c_`-prefixed.** Custom `c_` columns are framework-dynamic and need no
+   declaration, so this error can only ever fire for a **standard** column. The fix is binary:
+   declare the property on the model, or stop reading it.
+
+**The trap that produces it: two similarly-named models, one of which lacks the column.** Swapping
+one for another at a call site **lints clean and only dies at runtime** — nothing in PHP or CI
+flags it. Concrete (2026-09-01): a surface call site was repointed from
+`_Model_Client_RecordFieldSetting` (table `RecordFieldSettings`, declares `maxLength`) to
+`_Model_Client_ClientRecordFieldSetting` (legacy EAV table `ClientRecordFieldSettings`, no
+`maxLength`), producing exactly this message and 500ing every RecordField-bound surface field. See
+[surface FIELD ↔ RecordField binding](surface-field-recordfield-binding.md).
+
+**Contrast with the other failure shape.** A column declared on the model but **absent from the
+database** fails as MySQL **1054 "Unknown column"** on the model's own `SELECT`, because
+`_Model::initialize()` selects every declared property. So the two messages tell you which side is
+wrong: **1054** = the database is behind the model (see
+[framework branch ahead of schema](../../dbchanges2/workflows/framework-branch-ahead-of-schema.md));
+**"no field called"** = the call site is reading something the model never declared.
+
 ## Gotchas / known issues
 
 - **Treat `empty()` / `isset()` / `??` on a magic field as simply UNRELIABLE — the exact behavior
@@ -91,6 +127,15 @@ the base `_Model` either, so this applies to **every** 2.0 model, not just the C
 
 ## Change history
 
+- 2026-09-01 — Added the **triage rule** for the other half of this gap (no code changed): a 500
+  `EO-1` reading *"There is no field called 'X' in the '_Model_…' model"* is a `__get` throw, so it
+  is **never** a schema problem and the column is **never** `c_`-prefixed (custom fields need no
+  declaration) — fix the model declaration or the read. Recorded the trap that produces it: swapping
+  two similarly-named models at one call site **lints clean and only fails at runtime** — verified on
+  `_Model_Client_RecordFieldSetting` (declares `maxLength`) vs the legacy EAV
+  `_Model_Client_ClientRecordFieldSetting` (does not), which 500'd every RecordField-bound surface
+  field. Also drew the contrast that identifies the opposite direction: MySQL **1054** means the
+  database is behind the model, because `initialize()` selects every declared property. (apeterson)
 - 2026-08-06 — TRUE-80282 testing: confirmed the gap exists on the **base `_Model`** too (it
   declares `__get`/`__set` only, `_underscore/Model.php:464,481`), so this applies to every 2.0
   model. Recorded the sharpest empirical case yet: `$s->dateCancelled` returns `'2026-08-26'` while

package/knowledge/2.0/apps/_underscore/features/surface-field-recordfield-binding.md

@@ -0,0 +1,233 @@
+---
+title: "Surface FIELD ↔ RecordField binding (maxLength / validationType / isWritable fold-in)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-09-01
+owners: [apeterson, jcardinal]
+files:
+  - _underscore/Model/Core/Surface.php
+  - _underscore/Model/Core/RecordField.php
+  - _underscore/Model/Core/AclFieldPermission.php
+  - _underscore/Model/Client/RecordFieldSetting.php
+  - _underscore/Model/Client/ClientRecordFieldSetting.php
+  - dbchanges2/Core/2026-08-14c - RecordFieldsValidationMetadata.sql
+  - dbchanges2/Client/2026-08-14a - RecordFieldSettingsClientTable.sql
+  - api2/Component/Api/V2/V2.php
+related:
+  - surface-resolver.md
+  - acl-permission-chain.md
+  - model-magic-field-access.md
+  - ../../dbchanges2/workflows/framework-branch-ahead-of-schema.md
+  - ../../dbchanges2/features/surface-layer-schema.md
+  - ../../api2/features/environment-variable-drives-underscore-branch.md
+  - ../workflows/recreated-shared-branch-stale-local-remerge.md
+---
+
+## What it is
+
+A resolver capability that makes a surface `FIELD` element carry its **input contract** — max
+length, validator name, and whether the caller may write it — instead of the front end guessing.
+When a resolved `SurfaceElement` has `renderType = FIELD` **and** a non-null `recordFieldId`, the
+resolver folds `Core.RecordFields` metadata plus the field-level ACL write gate onto the element
+before it goes in the bundle.
+
+It lives in `_Model_Core_Surface::_resolveRecordFieldBinding()` and its helper
+`_resolveFieldWritableMap()`. It is an addition to `resolve()`/`_buildBundle()` — see
+[surface-resolver](surface-resolver.md) for the rest of the pipeline.
+
+> ## ⚠ Read this before you grep — this doc describes code that ships on TWO feature branches only
+>
+> **`_resolveRecordFieldBinding` is NOT on `_production`, `_beta`, `_sandbox-client` or
+> `_sandbox-dev`.** Verified 2026-09-01 against live remote refs:
+>
+> | Branch | hits |
+> |---|---|
+> | `origin/toga25-desk` | **3** |
+> | `origin/_qa-alpha` | **3** |
+> | `origin/_sandbox-client` | 0 |
+> | `origin/_production` | 0 |
+> | `origin/_beta` | 0 |
+>
+> `origin/_sandbox-client` and `origin/_production` are both at `91ce7462` and byte-identical.
+> **Nothing in this doc is live in production.** It was briefly on `_sandbox-client` (as
+> `fefeebd7`) and was rolled back on 2026-09-01 — see the incident gotcha below.
+>
+> **So a grep of `_sandbox-client` or `_production` returns nothing, and that is expected — it is not
+> evidence this doc is fiction.** This is the same hazard as the surface-resolver gotcha *"'grep says
+> this function doesn't exist' is meaningless unless you state which `_underscore` branch is checked
+> out"* ([surface-resolver](surface-resolver.md) → Gotchas). Always name the branch. See also
+> [ENVIRONMENT decides the `_underscore`
+> branch](../../api2/features/environment-variable-drives-underscore-branch.md).
+
+## What gets folded onto the element
+
+| Emitted key | Source |
+|---|---|
+| `maxLength` | 3-level cascade: `element.characterLimit` ?? client override (`Client.RecordFieldSettings.maxLength`) ?? `Core.RecordFields.maxLength` |
+| `validationType` | `element.validationType` ?? `Core.RecordFields.validationType` |
+| `showRequiredIndicator`, `inputType`, `isSearchable` | straight off the `SurfaceElements` columns |
+| `isWritable` | the per-record field-permission map (see below) |
+
+Every other element (`TEXT`, `BUTTON`, …), and any `FIELD` element with a null `recordFieldId`, is
+untouched. The presence gate is the whole trigger — and also the whole blast radius (see gotchas).
+
+## Drop semantics — it never fabricates a permission and never silently hides an unjudged field
+
+This is the part worth knowing, because it is deliberately asymmetric:
+
+- A permission map **was** resolved and the field has **no entry** in it → the element is
+  **dropped**. Presence in the map means readable (`AclFieldPermissions` has no `isReadable`
+  column — row presence grants READ, `isWritable` additionally grants WRITE; see
+  [acl-permission-chain](acl-permission-chain.md)).
+- **No map could be resolved** (e.g. `$api` is not the V2 engine) → the element is **kept** and
+  `isWritable` is simply **omitted**. It does not invent `true`, and it does not hide a field whose
+  permissions were never adjudicated.
+- **Dangling `recordFieldId`** (the `RecordField` row is gone) → `error_log`'d and the element is
+  **kept unchanged**. Same soft-FK tolerance as the rest of the resolver.
+
+## Role-id space and caching
+
+`_resolveFieldWritableMap()` picks the role-id space **off the record**, exactly as
+`V2::processRoutePairs` does: `Core.Records.aclDatabase = CORE` → `id.core.roles`, otherwise
+`id.client.roles`. It then calls `$api->getAclFieldPermissions()`, which delegates to the one shared
+transformer `_Model_Core_AclFieldPermission::resolveFieldPermissions()` — there is no second copy of
+the ACL logic here.
+
+Two per-request caches keep it cheap:
+
+- `$recordFieldCache` — keyed by `recordFieldId`.
+- `$writableMapByRecordId` — the map is computed **once per record**, so N fields of one record cost
+  **one** ACL lookup, not N.
+
+## Schema it depends on (both migrations are STRANDED, not merged)
+
+| Object | Migration | State |
+|---|---|---|
+| `Core.RecordFields.maxLength` + `validationType` | `Core/2026-08-14c - RecordFieldsValidationMetadata.sql` | on `origin/toga25-desk`, **not merged to `_main`**; hand-applied to `sandbox-client` 2026-08-27 |
+| `Client.RecordFieldSettings` (new table, `recordFieldId` + `maxLength`) | `Client/2026-08-14a - RecordFieldSettingsClientTable.sql` | on `origin/toga25-desk`, **not merged to `_main`**, applied **nowhere** |
+
+`Client.RecordFieldSettings` is a purpose-built typed override table — a single `maxLength` column,
+`UNIQUE(recordFieldId)`, ships empty, and `recordFieldId` is a **soft** cross-cluster integer ref to
+`Core.RecordFields` (Core and client DBs are separate production clusters, so no FK is possible).
+That is correct by the isolation rule, not an oversight. Full drift procedure and inventory:
+[framework branch ahead of schema](../../dbchanges2/workflows/framework-branch-ahead-of-schema.md).
+
+**Consequence for the front end:** `toga25-supply` does **not** consume `maxLength`,
+`validationType` or `isWritable` yet. The backend emission is ahead of the FE.
+
+## Gotchas / known issues
+
+- **🚨 The client-override tier is easy to point at the WRONG model, and the wrong one 500s the
+  whole screen.** There are two similarly-named client models and only one has a `maxLength`:
+
+  | Model | `const TABLE` | Shape | Has `maxLength`? |
+  |---|---|---|---|
+  | `_Model_Client_RecordFieldSetting` | `RecordFieldSettings` | purpose-built typed override | **yes** |
+  | `_Model_Client_ClientRecordFieldSetting` | `ClientRecordFieldSettings` | legacy EAV (`settingId` + `value`) | **no** |
+
+  The legacy one declares only `id`/`uuid`/`recordFieldId`/`contextRecordFieldId`/`settingId`/
+  `isOverridable`/`value` — it is part of the old `*Settings` EAV cascade behind
+  [page-meta-context-field-settings](page-meta-context-field-settings.md). Reading `->maxLength` off
+  it **throws**, because `maxLength` is not `c_`-prefixed and so needs a declared property (see
+  [model-magic-field-access](model-magic-field-access.md)).
+
+  **Incident (`_sandbox-client`, 2026-08-31 → 2026-09-01 — RESOLVED by a branch rollback).**
+  `GET /v2/surfaces/meta-group` returned **500 `EO-1`** with
+  `identifiers.message` = *"There is no field called 'maxLength' in the
+  '_Model_Client_ClientRecordFieldSetting' model."* Trace: `_Model::__get` ←
+  `_resolveRecordFieldBinding` ← `_buildBundle` ← `resolve` ← `metaGroup` (`V2.php:4458`).
+  A commit pair had **deleted** `Model/Client/RecordFieldSetting.php` (`66022382`) and repointed the
+  call site at the legacy `ClientRecordFieldSetting` (`64466ca2`) — swapping a "table doesn't exist"
+  500 for a `__get` 500. It lints clean; it only dies at runtime.
+
+  Branch timeline: recreated clean at `2de6815b` (Aug 31 09:17) → **re-polluted** by merge
+  `a57f13fd` (Aug 31 18:20, parents `64466ca2` + `2de6815b` — a teammate's stale local clone) →
+  `fefeebd7`, which the deploy picked up → **rolled back to `_production` at `91ce7462`**
+  (2026-09-01). Full mechanism and triage:
+  [recreated shared branch / stale-local re-merge](../workflows/recreated-shared-branch-stale-local-remerge.md).
+
+  Two things follow. **(a)** The bad swap is on **no remote branch** today — it survives only in
+  local clones, so the re-merge vector is still live. **(b)** The rollback was indiscriminate: it
+  also removed the **good** half, which is why `_sandbox-client` has none of this feature now. The
+  canonical code on `origin/toga25-desk` / `origin/_qa-alpha` uses the **correct**
+  `_Model_Client_RecordFieldSetting`.
+
+  **Do not "fix" this by deleting the client-override tier.** The tier has a designed table and a
+  written migration (above) — it is **unapplied, not imaginary**. That was the session's initial
+  recommendation and it was **wrong**, because the branch search that produced it excluded
+  `origin/toga25-desk`. Fix the schema instead — see *Forward path* below.
+
+- **⚠ One bad FIELD element takes down a WHOLE SCREEN, not one control.** The binding is gated only
+  on `renderType = FIELD && recordFieldId`, so it runs for **every** RecordField-bound field element.
+  And because `metaGroup` resolves **N section surfaces in one call**, a single throwing element
+  fails the entire response — the front end reports it as a generic *"network error"*, which reads
+  like an outage rather than a data problem. When a whole 2.5 screen dies at once, suspect one shared
+  element, not the screen.
+
+- **A missing `Core.RecordFields` column fails EARLIER and differently.** In `sandbox-client` the
+  `new _Model_Core_RecordField($id)` load **succeeded**, which is what proved `maxLength` /
+  `validationType` were physically present there (they were hand-applied 2026-08-27) — a missing
+  column would have thrown MySQL **1054** on the model `SELECT` first, because
+  `_Model::initialize()` selects every declared property. So the two failure shapes tell you which
+  layer is broken: **1054 on the RecordField SELECT** = Core schema behind the model;
+  **`__get` throw** = call site reading an undeclared property. A freshly provisioned environment
+  gets the 1054 form, not the `__get` form.
+
+- Confirm the Core columns in any environment with:
+  ```sql
+  SELECT COLUMN_NAME FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = 'Core' AND TABLE_NAME = 'RecordFields'
+    AND COLUMN_NAME IN ('maxLength', 'validationType');
+  ```
+
+## Forward path for whoever lands this feature
+
+1. **Keep `_Model_Client_RecordFieldSetting`.** Do not repoint it at the legacy EAV model, and do not
+   delete the client-override tier.
+2. **Merge the two stranded `2026-08-14` migrations together with the code** —
+   `Core/2026-08-14c - RecordFieldsValidationMetadata.sql` and
+   `Client/2026-08-14a - RecordFieldSettingsClientTable.sql`, both on `origin/toga25-desk`. Code
+   without them reproduces the 500; the migrations without the code are inert and harmless, so they
+   are safe to land first.
+3. **Remember `Client/` is a fan-out** — `RecordFieldSettings` is one `CREATE TABLE` **per tenant
+   database** (~30), plus the blank client template so newly provisioned clients get it. `Core` is a
+   single `ALTER`.
+4. **⚠ `sandbox-client`'s Core schema is AHEAD of its own repo state.** `Core.RecordFields.maxLength`
+   and `validationType` were **hand-applied** there on 2026-08-27 (recorded verbatim in
+   [framework branch ahead of schema](../../dbchanges2/workflows/framework-branch-ahead-of-schema.md)),
+   so the real migration will run against at least one database that already has the columns —
+   **idempotent by requirement, not by preference.** `Client/2026-08-14a` already uses
+   `CREATE TABLE IF NOT EXISTS`.
+5. **Sweep before deploying.** Moving a tier onto a branch that carries this feature is a schema
+   event; run the `origin/_production..origin/<env-branch> -- Model/` sweep first.
+
+## Change history
+
+- 2026-09-01 — Documented the capability from a production-diagnosis session (no code changed).
+  Recorded the fold-in contract (`maxLength` 3-level cascade / `validationType` / `isWritable` /
+  `showRequiredIndicator` / `inputType` / `isSearchable`), the asymmetric drop semantics (drop only
+  when a map exists and the field is absent; keep-and-omit when no map resolves; keep + `error_log`
+  on a dangling `recordFieldId`), the record-driven role-id space, and the two per-request caches.
+  Diagnosed the **500 `EO-1` "no field called 'maxLength' in
+  `_Model_Client_ClientRecordFieldSetting`"** crash: the call site had been repointed from the
+  purpose-built `_Model_Client_RecordFieldSetting` (`RecordFieldSettings`, declares `maxLength`) to
+  the legacy EAV `ClientRecordFieldSettings` (no such column). **Corrected the session's own
+  premise:** the client-override tier is **not** table-less — `Client/2026-08-14a -
+  RecordFieldSettingsClientTable.sql` exists on `origin/toga25-desk` (unmerged, applied nowhere), so
+  deleting the tier is the wrong fix. Verified branch scope against live refs: the whole feature is
+  only on `origin/toga25-desk` and `origin/_qa-alpha`; `_sandbox-client` and `_production` are both
+  `91ce7462` with zero hits, so **production is unaffected**. Also recorded the blast-radius rule
+  (one throwing FIELD element fails an entire `metaGroup` response, surfacing as a "network error")
+  and the 1054-vs-`__get` distinction that identifies which layer is broken. Captured the branch
+  timeline — clean `2de6815b` → re-polluted by merge `a57f13fd` → `fefeebd7` (deployed, 500ing) →
+  **rolled back to `_production` at `91ce7462`** on 2026-09-01, which ended the incident and also
+  removed the good half, leaving this feature on `toga25-desk` / `_qa-alpha` only (mechanism:
+  [recreated shared branch / stale-local
+  re-merge](../workflows/recreated-shared-branch-stale-local-remerge.md)). Added the **Forward path**
+  — keep `_Model_Client_RecordFieldSetting`, land the two stranded migrations with the code, treat
+  `Client/` as a ~30-database fan-out, and write the Core migration **idempotently** because
+  sandbox-client's Core already has the hand-applied columns. (apeterson)

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
+updated: 2026-09-01
 owners: [jcardinal, apeterson, bala]
 files:
   - _underscore/Model/Client/Language.php
@@ -63,6 +63,7 @@ related:
   - ../../api2/features/surface-meta-option.md
   - acl-permission-chain.md
   - sales-order-status-filter-surface.md
+  - surface-field-recordfield-binding.md
   - ../../toga25-supply/features/side-navigation-and-default-route.md
 ---
 
@@ -154,6 +155,16 @@ boolean rows; the item-record modal (the first boolean consumer) exposed the gap
 `_underscore`, so it takes effect only once the framework branch is deployed (framework is pulled at
 deploy).
 
+## FIELD elements bound to a RecordField — see the dedicated doc
+
+A `renderType = FIELD` element with a non-null `recordFieldId` gets `Core.RecordFields` metadata and
+the field-level ACL write gate folded onto it (`maxLength`, `validationType`, `isWritable`,
+`showRequiredIndicator`, `inputType`, `isSearchable`) inside `_buildBundle`. That capability, its
+drop semantics, its stranded migrations, and the 500 it can cause are documented separately:
+[surface FIELD ↔ RecordField binding](surface-field-recordfield-binding.md). **It is not on
+`_production`, `_beta`, `_sandbox-client` or `_sandbox-dev`** — only `origin/toga25-desk` and
+`origin/_qa-alpha` (verified 2026-09-01).
+
 ## Vocabulary / label per-client relabeling (slugs are internal, labels are messages)
 
 Clients **never rename a Vocabulary**. `Vocabularies.slug` (`sales-order-status`) and
@@ -247,6 +258,25 @@ cluster-isolation rule.
   exact ids to a *different* element. See the NYCHH ship-together constraint in
   [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md).
 
+### ✅ A wrong `surfaceElementId` in an override is INERT — overrides cannot leak across surfaces
+
+`_loadOverrides()` (`Model/Core/Surface.php:748`) filters `WHERE SurfaceOverrides.surfaceId =
+$surfaceId`, so an override row is only ever read while rendering **its own** surface. That bounds the
+landmine above: a row whose `surfaceElementId` points at an element belonging to a **different**
+surface is never applied — dead weight, not damage.
+
+Proven 2026-08-31. After sandbox-client was reset from production, NYCHH's navigation override still
+carried `surfaceElementId` **170**, which by then belonged to another team's
+`sales-order-denial-details` surface (**47**). It could not affect that surface, because the override
+row's own `surfaceId` is **39** (`navigation`). Confirmed no damage: every denial-details row still
+had `dtCreated = dtUpdated = the reset timestamp`.
+
+**So the failure mode of a stale Core id is a MISSING UI element, not a corrupted one** — which is why
+a fairly serious id collision showed up as one absent menu item rather than a broken feature. Two ways
+it can still hurt: (1) the override silently does nothing, so the element you meant to show stays
+hidden; (2) if that id is later reused by an element **inside the same surface**, the override lands on
+the wrong element. Fix the literal — but do not go hunting for collateral damage in other surfaces.
+
 ### 🚨 …but the REPO still does not describe prod. Read production. (2026-08-28)
 
 The reserved-literal house style fixes **new** files. It did **not** retroactively fix the ~51
@@ -725,6 +755,21 @@ full stop. See
   match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-09-01 — Split the new **FIELD ↔ RecordField binding** capability out into its own doc
+  ([surface-field-recordfield-binding](surface-field-recordfield-binding.md)) rather than growing this
+  one: for a `renderType=FIELD` element with a `recordFieldId`, `_buildBundle` now folds on
+  `maxLength` / `validationType` / `isWritable` / `showRequiredIndicator` / `inputType` /
+  `isSearchable`. Flagged its branch scope here because it is the kind of thing people grep for and
+  wrongly declare missing: it exists **only** on `origin/toga25-desk` and `origin/_qa-alpha`, not on
+  `_production` / `_beta` / `_sandbox-client` / `_sandbox-dev`. No code changed this session.
+  (apeterson)
+- 2026-08-31 — Recorded a **safety property**: `SurfaceOverrides` cannot leak across surfaces.
+  `_loadOverrides()` (`Surface.php:748`) filters on `SurfaceOverrides.surfaceId`, so an override whose
+  `surfaceElementId` belongs to a **different** surface is inert. Proven after a Core id collision:
+  NYCHH's nav override still pointed at element 170 — by then owned by another team's surface 47 — and
+  could not touch it, because the row's own `surfaceId` is 39; every denial-details row still had
+  `dtCreated = dtUpdated = the reset timestamp`. The failure mode of a stale Core id is a **missing**
+  element, not a corrupted one. (apeterson)
 - 2026-08-28 — Recorded that the reserved-literal house style fixed **new** authoring only: the ~51
   existing `Client_Compass`/`Client_CompassCanada`/`Client_Quad` override files still carry
   cross-cluster `Core.*` joins and are **unrunnable in prod** (verified empirically — the Core and

package/knowledge/2.0/apps/_underscore/workflows/recreated-shared-branch-stale-local-remerge.md

@@ -0,0 +1,141 @@
+---
+title: "Deleting a shared branch does not remove bad commits — a stale local clone merges them back"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: workflow
+status: active
+updated: 2026-09-01
+owners: [apeterson]
+files:
+  - _underscore/Model/Core/Surface.php
+  - _underscore/Model/Client/RecordFieldSetting.php
+  - api2/.platform/hooks/prebuild/git.sh
+  - api2/.ebextensions/git.php
+related:
+  - ../features/surface-field-recordfield-binding.md
+  - ../features/surface-resolver.md
+  - ../../api2/features/environment-variable-drives-underscore-branch.md
+  - ../../dbchanges2/workflows/framework-branch-ahead-of-schema.md
+---
+
+## Summary
+
+**Deleting and recreating a shared environment branch removes only the *ref*.** Every teammate who
+still has that branch checked out locally keeps the full pre-deletion commit history, and the first
+one to push **re-merges it**. Branch surgery is not a durable remedy for a bad commit — **fix forward
+in code.**
+
+The recreated branch *looks* fixed, and it genuinely is fixed, for as long as it takes one teammate
+to run `git push`. That gap is usually hours, and the re-merge lands as an innocuous-looking
+"Merge branch 'X' of github.com/… into X" commit that nobody reads.
+
+Use this doc when the question is **"we already fixed this — why is it back?"**
+
+## Proven timeline (`_underscore` / `_sandbox-client`, 2026-08-31 → 2026-09-01)
+
+The subject was the surface FIELD-binding 500 (see
+[surface FIELD ↔ RecordField binding](../features/surface-field-recordfield-binding.md)); the
+mechanism below is what matters and is subject-independent.
+
+| When | Ref | What happened |
+|---|---|---|
+| 2026-08-31 09:17 | `2de6815b` | Branch **deleted + recreated clean**. Verified: `git merge-base --is-ancestor` said **none** of `a5e79448` / `66022382` / `64466ca2` were ancestors. The deploy off this ref was fine. |
+| 2026-08-31 10:14 | `6f63a62` | `api2/_sandbox-client` likewise recreated. |
+| 2026-08-31 18:20:35 | `a57f13fd` | A teammate pushed. The merge's **two parents** are `64466ca2` (his stale local tip — the pre-deletion history, containing the bug) and `2de6815b` (the clean ref). **This restored the deleted commits.** |
+| 2026-08-31 18:20:42 | `fefeebd7` | `_production` merged on top. Branch tip = `fefeebd7`. |
+| 2026-09-01 | — | The sandbox-client deploy pulled `fefeebd7` (the framework is cloned **at build time** from the moving `_<ENVIRONMENT>` branch) and the 500s returned. |
+| 2026-09-01 (observed mid-session) | `91ce7462` | Branch **rolled back again**, to be byte-identical with `origin/_production`. The live incident ended here. |
+
+`api2/_sandbox-client` was **never** re-polluted — it stayed at `6f63a62`. Only the repo whose
+branch a teammate held locally came back.
+
+## State as of 2026-09-01 — the vector is still live
+
+- **No remote branch carries the bad swap.** `66022382`, `64466ca2`, `a57f13fd` and `fefeebd7` are
+  reachable from **zero** remote branches (`git branch -r --contains` → empty).
+- **They survive in local clones.** Which is exactly the condition that produced `a57f13fd` in the
+  first place. **Rule 2 below still applies to anyone who has not re-cloned.**
+- **The rollback also reverted the *good* half.** `_sandbox-client` no longer has the FIELD-binding
+  feature at all — it now matches `_production`. A rollback is indiscriminate: it does not
+  distinguish the regression from the work it arrived with.
+
+## Why branch deletion could never have worked here
+
+`a5e79448` — the commit that introduces the whole affected code path — is **also** reachable from
+`origin/toga25-desk` and `origin/_qa-alpha`, and `toga25-desk` is merged into `_sandbox-client`
+routinely (e.g. `8bca0286`, 2026-08-27).
+
+So even with every stale local clone deleted, the code path returns on the next `toga25-desk` merge.
+**Deleting a ref cannot remove a commit that another branch also reaches.** That is the structural
+reason the decision was to fix forward in code, not to keep doing branch surgery.
+
+## Steps — triaging "we already fixed this, why is it back?"
+
+1. **Read the merge parents of the reconcile merge.** This names the vector precisely and takes one
+   command:
+   ```
+   git log -1 --format='%p' <merge-sha>
+   git merge-base --is-ancestor <bad-commit> <each-parent>
+   ```
+   A parent that answers YES is the stale local clone that re-introduced it.
+2. **Ask which branches still reach the bad commit** — not just the one you are looking at:
+   ```
+   git branch -r --contains <bad-commit>
+   ```
+   Empty output means "no remote branch", **not** "gone" — local clones are invisible here.
+3. **Check whether the code path has a second home.** If the introducing commit is reachable from a
+   long-lived feature branch that gets merged in routinely (`toga25-desk`, `_qa-alpha`), branch
+   surgery is a no-op by design. Fix forward.
+4. **Confirm what the environment actually deployed.** The framework is cloned at build time from a
+   moving branch, so the tip at deploy time — not the tip now — is what ran. See
+   [ENVIRONMENT decides the `_underscore` branch](../../api2/features/environment-variable-drives-underscore-branch.md),
+   including the stack-trace-line-number technique for pinning the running version.
+5. **Pair any branch move with a migration sweep.** Moving a branch in either direction is a schema
+   event. See
+   [framework branch ahead of schema](../../dbchanges2/workflows/framework-branch-ahead-of-schema.md).
+
+## Rules
+
+1. **A branch-delete "fix" only appears to work** because the recreated ref happens to predate the
+   bad commits. It removes no commit and changes no teammate's clone.
+2. **Before pushing to a re-created shared branch, delete your local copy and re-checkout from
+   origin.** Otherwise your first push re-merges everything the recreation was meant to remove.
+   Announce a recreation to the team for this reason — it is the only mitigation that works.
+3. **When triaging a returning bug, read the merge parents first.** Do not re-read the code; the
+   history says who brought it back.
+4. **Fix forward in code.** Prefer a corrective commit over ref surgery, always.
+5. **Never force-push to recover.** Force-pushing `_main` is forbidden in every repo, and
+   force-pushing a shared environment branch multiplies the stale-local problem instead of solving it.
+
+## Gotchas / known issues
+
+- **The re-merge is invisible in a normal log skim.** It arrives as
+  `Merge branch '_sandbox-client' of https://github.com/… into _sandbox-client` — a
+  self-referential merge title that reads like routine noise. `--format='%p'` is what exposes it.
+- **A rollback is not a fix either.** It reverts the regression *and* the legitimate work that
+  shipped alongside it, and it leaves the underlying commits alive in local clones and on sibling
+  branches. Both rollbacks in the timeline above bought hours, not a resolution.
+- **"Verified clean" has a shelf life.** `merge-base --is-ancestor` returning NO is a statement about
+  one ref at one moment, not a property of the branch. Re-verify immediately before a deploy.
+- **Two repos, two outcomes, one cause.** `api2` stayed clean and `_underscore` did not, purely
+  because of who had which branch checked out locally. Do not infer that one repo is "safer".
+
+## Change history
+
+- 2026-09-01 — Created from the `_underscore/_sandbox-client` surface FIELD-binding incident (no code
+  changed; diagnosis only). Recorded the mechanism — deleting a shared branch removes only the ref,
+  and a teammate's stale local clone re-merges the full pre-deletion history — with the exact proven
+  timeline: recreated clean at `2de6815b` (Aug 31 09:17), re-polluted by merge `a57f13fd` (Aug 31
+  18:20, parents `64466ca2` + `2de6815b`), then `fefeebd7`, then **rolled back to `_production` at
+  `91ce7462`** on 2026-09-01, which ended the live incident and simultaneously reverted the good half
+  of the work. Noted that `api2/_sandbox-client` was never re-polluted (`6f63a62`) because nobody
+  held it locally. Recorded the structural reason branch surgery can never work for this class of
+  problem: the introducing commit `a5e79448` is also reachable from `origin/toga25-desk` and
+  `origin/_qa-alpha`, which are merged in routinely — so **fix forward in code** was the decision.
+  Captured the triage procedure (merge parents via `git log -1 --format='%p'` +
+  `merge-base --is-ancestor` per parent; `git branch -r --contains`, whose empty output means "no
+  *remote* branch", not "gone") and the four standing rules, including "delete your local copy and
+  re-checkout from origin before pushing to a recreated branch" — still live, because the bad commits
+  remain in local clones. (apeterson)