toga-ai 1.0.668 → 1.0.669

package/knowledge/2.0/apps/api2/features/environment-variable-drives-underscore-branch.md

@@ -21,6 +21,7 @@ related:
   - ../workflows/environment-configuration-and-provisioning.md
   - ../workflows/codepipeline-codeconnections-deploy.md
   - ../../_underscore/features/togaiq-gateway-client.md
+  - ../../dbchanges2/workflows/framework-branch-ahead-of-schema.md
 ---
 
 ## Summary
@@ -154,6 +155,26 @@ Related detail: **the slug V2 uses to pick the override class is `Clients.client
 (`V2.php:1521`), taken from the JWT. `Core.Clients` has **no `slug` column** — do not go looking for
 one.
 
+## ⚠ Moving a tier onto its correct branch is a SCHEMA event, not just a code event
+
+The gotchas below are all about a tier running **stale** code. The inverse hurts too: when a deploy
+moves an environment **forward** onto a newer `_underscore` branch — including a deploy that *fixes*
+a wrong branch pin — it fast-forwards across every model change made since the pin, and
+`_Model::initialize()` SELECTs **every declared property**. Any of those columns without a merged
+`dbchanges2` migration becomes an **environment-wide MySQL 1054 → HTTP 500 / `EO-1`**, for every
+tenant, immediately.
+
+**Concrete (2026-08-26).** The 2026-08-26 deploy moved `sandbox-client` off the `_production`
+framework — which it had been running for weeks (see the 2026-08-25 entry below) — onto
+`_sandbox-client`, carrying ~2 weeks of model changes whose migrations were stranded on an unmerged
+`dbchanges2` branch. Table-meta requests 500'd on `RecordFields.maxLength`, then (once that was
+patched) on `TableViewFields.isGroupable`.
+
+**Rule: pair a branch-pin correction with a migration sweep** — enumerate what the new branch expects
+(`git log origin/_production..origin/<env-branch> --oneline -- Model/`) **before** redeploying, or
+the tier trades a stale-code bug for a total outage. Full procedure:
+[framework branch ahead of schema](../../dbchanges2/workflows/framework-branch-ahead-of-schema.md).
+
 ## Gotchas / known issues
 
 - **⚠ Merging to the branch named after the EB environment can be a no-op.** Merge to
@@ -220,6 +241,13 @@ one.
 
 ## Change history
 
+- 2026-08-27 — Recorded the **inverse hazard**: moving a tier **forward** onto its correct
+  `_underscore` branch is a **schema event**. The 2026-08-26 deploy moved `sandbox-client` off the
+  `_production` framework (which the 2026-08-25 entry below explains it had been running for weeks)
+  onto `_sandbox-client`, fast-forwarding it across ~2 weeks of model changes whose `dbchanges2`
+  migrations were stranded on an unmerged branch — producing environment-wide MySQL 1054 → 500/`EO-1`
+  on `RecordFields.maxLength` and then `TableViewFields.isGroupable`. A branch-pin correction must
+  ship with a migration sweep of `origin/_production..origin/<env-branch> -- Model/`. (apeterson)
 - 2026-08-25 — Recorded the **second delivery mechanism**: besides `.ebextensions/git.php`, the
   **CodePipeline `_underscore` source action has its own branch trigger configured in AWS**, and it
   can serve the wrong branch while `git.<env>.json` is perfectly correct. Live case: `ApiSandboxClient`

package/knowledge/2.0/apps/api2/features/tableview-field-metadata.md

@@ -43,9 +43,20 @@ it.
 - **`Client_*.TableViewFields`** — one row per **column** of a view. Key columns: `recordFieldId`
   (which field this column shows), `tableViewJoinId` (which join in the view the field is reached
   through), `slug` (the frontend/tanstack column id), `isVisible` (0 = projected-but-hidden),
-  and the per-view **presentation flags** `isCopyable` / `isSortable` / `isFilterable`. These
-  four flags **are** per-view — the same underlying field can be copyable in one view and not in
-  another.
+  and the per-view **presentation flags** `isCopyable` / `isSortable` / `isFilterable` /
+  `isGroupable`. These flags **are** per-view — the same underlying field can be copyable in one
+  view and not in another.
+
+> **⚠ `isGroupable` is declared in the framework but has NO migration (as of 2026-08-27).**
+> `_underscore` `9f296a71` (2026-08-26) added `public $isGroupable = self::FIELD_BOOLEAN;` to
+> `_Model_Client_TableViewField` **and** named the column in `_Model_Client_TableView::meta()`'s
+> hand-written `SELECT` — but no `dbchanges2` file adds it, in any branch or in the blank client
+> template. Any environment whose framework branch carries that commit **500s (`EO-1`, MySQL 1054)
+> on every table-meta request, for every tenant**, until the column is added to each `Client_*` DB.
+> It was hand-applied to `sandbox-client` as
+> `TINYINT UNSIGNED NULL … AFTER isFilterable` (matching its sibling flags); the real fan-out
+> migration is still outstanding. Background:
+> [framework branch ahead of schema](../../dbchanges2/workflows/framework-branch-ahead-of-schema.md).
 
 ### A column's `type` / `precision` are NOT per-view — they come from `Core.RecordFields`
 
@@ -207,9 +218,20 @@ SalesOrderListingSortByDateOrderDesc.sql`).
   is suppressed.
 - **`type`/`precision` are canonical (Core-wide), not per-view.** Editing `Core.RecordFields`
   changes every view/client that shows the field; there is no per-view type override. `isCopyable`,
-  `isSortable`, `isFilterable`, `isVisible` are the per-view knobs (on `TableViewFields`).
+  `isSortable`, `isFilterable`, `isGroupable`, `isVisible` are the per-view knobs (on
+  `TableViewFields`).
+- **`TableView::meta()` contains a hand-written `SELECT` that names `TableViewFields` columns
+  explicitly.** So a new column on that table is required by **two** mechanisms — the model property
+  *and* that query — and a grep for the property alone under-reports what a missing column breaks.
 
 ## Change history
+- 2026-08-27 - Added **`isGroupable`** as a fourth per-view presentation flag on `TableViewFields`,
+  with the warning that it is declared in `_underscore` (`9f296a71`, 2026-08-26 — model property
+  **and** `TableView::meta()`'s hand-written SELECT) while **no `dbchanges2` migration adds it on any
+  branch**, so any environment on that framework branch 500s (`EO-1`/1054) on every table-meta
+  request for every tenant. Hand-applied to `sandbox-client` as `TINYINT UNSIGNED NULL AFTER
+  isFilterable`; fan-out migration still outstanding. Also recorded that `meta()`'s explicit SELECT
+  makes a property grep an under-count of a missing column's blast radius. (apeterson)
 - 2026-08-26 - Added the **per-client type override**: a column can point at
   `TableViewFields.customRecordFieldId` instead of `recordFieldId`, so registering a
   `Client_<X>.CustomRecordFields` row with the **same field name** as the Core RecordField and the

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

@@ -7,6 +7,7 @@
 | [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/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, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Quad/2026-07-21b - ApproveDisabledTooltipPoNumber.sql, dbchanges2/Client_Quad/2026-08-21 - SalesOrderDecisionSummaryOverride.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, 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, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Core/2026-07-29a - SalesOrderApprovalDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-05b - ApprovalDetailsShippingMethodConcatCharge.sql, dbchanges2/Core/2026-08-14a - NoteBadgesVocabularySurface.sql, dbchanges2/Client/2026-08-14a - NoteBadgeThemeTokens.sql, dbchanges2/Client/2026-08-14b - NoteBadgeUserColorFix.sql, dbchanges2/Client_Compass/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Client_CompassCanada/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Core/2026-08-26a - ServiceRequestRecordHeaderSurfaceSeed.sql, dbchanges2/Core/2026-08-26b - ServiceRequestDetailsSurfaceSeed.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | > **A local browser wizard now automates this.** Steps 2–9 below (create DBs, generate Core/API > inserts, append to `Clients_Db.txt`) — plus the dbchanges2 bla | Client/, Client_<Tenant>/, Core/, Logs_Client/ |
 | [Auditing a client DB that drifted from its models (partially applied module migration)](workflows/client-schema-drift-audit.md) | A recurring 2.0 failure mode: **one client's database drifts from what the PHP models declare**, usually because a `_modules/<module>/` migration was applied to | dbchanges2/Client_Growrk/2026-05-28.sql, dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/_modules.txt |
+| [Framework branch running AHEAD of schema — environment-wide 1054/EO-1 after a deploy](workflows/framework-branch-ahead-of-schema.md) | A **third** kind of 2.0 schema drift, distinct from the two already documented: nobody's database went backwards — **the code went forwards**. | _underscore/Model/Core/RecordField.php, _underscore/Model/Client/TableViewField.php, _underscore/Model/Client/TableView.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/Urgency.php, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-14c - RecordFieldsValidationMetadata.sql, dbchanges2/Client/2026-08-14a - RecordFieldSettingsClientTable.sql, dbchanges2/Client/2026-08-13a - UserNavPreferencesClientTable.sql, dbchanges2/Client/2026-08-13c - PersonaNavVisibilityClientTable.sql |
 | [Local vs prod MySQL config parity — why “it passed locally” is not evidence](workflows/local-vs-prod-mysql-config-parity.md) | Several migration failures that look like "prod-only bugs" are actually **per-machine MySQL server-configuration differences**. |  |
 | [Repairing non-prod metadata drift (works in prod, broken in beta/dev-sandbox)](workflows/nonprod-metadata-drift-repair.md) | Almost all 2.0 platform behavior is **metadata** — `Core.Records`/`RecordFields`, `Core.RecordScripts`, `Core.ApiPayloadInterceptors`, and per-client `Acl*` row | dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql, dbchanges2/Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Aig/_modules.txt, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, api2/Config/beta.ini, api2/Config/sandbox-dev.ini, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql |
 | [Verifying whether a dbchanges2 migration actually ran in an environment](workflows/verifying-a-migration-ran.md) | dbchanges2 has no execution ledger you can query — "did this file run here?" has to be answered from the **rows the file would have produced**. | Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, Client/2026-08-13 - UnitsForItemsPO_SalesOrderItemsJoin.sql |

package/knowledge/2.0/apps/dbchanges2/workflows/client-schema-drift-audit.md

@@ -7,7 +7,7 @@ client: shared
 type: workflow
 status: active
 updated: 2026-08-11
-owners: ["bala", "mhammontree"]
+owners: ["bala", "mhammontree", "apeterson"]
 files:
   - dbchanges2/Client_Growrk/2026-05-28.sql
   - dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql
@@ -22,6 +22,7 @@ related:
   - ../../_underscore/features/acl-permission-chain.md
   - ../../api2/features/v2-api-error-codes.md
   - ../../../../clients/growrk/features/units-netsuite-custom-fields.md
+  - ./framework-branch-ahead-of-schema.md
 ---
 
 ## Summary
@@ -36,6 +37,12 @@ touches the record.
 > (works in prod, broken in beta). Here **production is the outlier** and beta/dev-sandbox is
 > correct — so "it works on beta" is not evidence the schema is fine. Check *which* side is behind
 > before assuming.
+>
+> **Third possibility — no database is behind, the CODE is ahead.** If the 1054 started right after
+> a **deploy**, is **not** client-specific, and the column exists in **no** environment, the
+> framework branch is running ahead of schema (its migration was never merged). Use
+> [framework branch ahead of schema](./framework-branch-ahead-of-schema.md) — the repair is a branch
+> merge, not a per-client catch-up file.
 
 Written from repairing `Client_Growrk.Units` (missing `c_lastModified`, 6 of 7 columns and 1 of 6
 metadata rows applied) — see
@@ -155,6 +162,11 @@ part, and it is what makes a missing column fatal. Standard, non-`c_` fields use
 
 ## Change history
 
+- 2026-08-27 — Added a pointer to the **third drift direction**: when the 1054 starts right after a
+  deploy, is not client-specific, and the column exists in no environment, the **framework branch is
+  ahead of schema** and the repair is a branch merge, not a catch-up file — see
+  [framework branch ahead of schema](./framework-branch-ahead-of-schema.md). No change to this
+  procedure. (apeterson)
 - 2026-08-11 — TRUE-80824: **corrected the premise.** The `Client_Growrk` drift was **not** a partially
   applied module migration — `Client_Growrk/2026-05-28.sql` is committed on `_main` (`af30e63`) and was
   **never executed** against production, which explains both the 2026-08-10 `Units` 500s and the

package/knowledge/2.0/apps/dbchanges2/workflows/framework-branch-ahead-of-schema.md

@@ -0,0 +1,256 @@
+---
+title: "Framework branch running AHEAD of schema — environment-wide 1054/EO-1 after a deploy"
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: shared
+type: workflow
+status: active
+updated: 2026-08-27
+owners: [apeterson]
+files:
+  - _underscore/Model/Core/RecordField.php
+  - _underscore/Model/Client/TableViewField.php
+  - _underscore/Model/Client/TableView.php
+  - _underscore/Model/Core/Surface.php
+  - _underscore/Model/Client/Urgency.php
+  - api2/Component/Api/V2/V2.php
+  - dbchanges2/Core/2026-08-14c - RecordFieldsValidationMetadata.sql
+  - dbchanges2/Client/2026-08-14a - RecordFieldSettingsClientTable.sql
+  - dbchanges2/Client/2026-08-13a - UserNavPreferencesClientTable.sql
+  - dbchanges2/Client/2026-08-13c - PersonaNavVisibilityClientTable.sql
+related:
+  - ./client-schema-drift-audit.md
+  - ./nonprod-metadata-drift-repair.md
+  - ./verifying-a-migration-ran.md
+  - ../architecture.md
+  - ../../api2/features/environment-variable-drives-underscore-branch.md
+  - ../../api2/features/tableview-field-metadata.md
+  - ../../_underscore/features/field-storage-row-hydration.md
+---
+
+## Summary
+
+A **third** kind of 2.0 schema drift, distinct from the two already documented: nobody's database
+went backwards — **the code went forwards**. A deploy moved an environment onto a newer
+`_underscore` branch that carries model changes whose `dbchanges2` migrations were **never merged**.
+Every request touching an affected model then dies with MySQL **1054 "Unknown column"** →
+**HTTP 500 / `EO-1`**, for **every tenant at once**, tenant-agnostic.
+
+> **Which of the three drift docs do you want?**
+>
+> | The outlier is… | Doc |
+> |---|---|
+> | one **client's** DB, behind its models (migration partially/never applied) | [client schema-drift audit](./client-schema-drift-audit.md) |
+> | a **non-prod environment's** metadata, behind production | [non-prod metadata drift repair](./nonprod-metadata-drift-repair.md) |
+> | **the code** — the framework branch is ahead of every schema, including production's | **this doc** |
+>
+> The tell for *this* doc: the failure started **immediately after a deploy**, it is **not**
+> client-specific, and the missing column exists in **no** environment because the migration
+> exists in **no merged branch**.
+
+Written from the 2026-08-26 `sandbox-client` outage: table-meta requests returned 500/EO-1 on two
+successive columns after a deploy moved that environment from the `_production` framework onto
+`_sandbox-client`, which carried ~2 weeks of model changes.
+
+## Why one model property takes down a whole environment
+
+`_Model::initialize()` builds its SELECT from **every property declared on the class**, ignoring the
+caller's `fields=` (see
+[client schema-drift audit](./client-schema-drift-audit.md) → *Why it 500s*).
+So this one line, shipped without a migration, breaks **every construction of that model,
+everywhere**:
+
+```php
+public $isGroupable = self::FIELD_BOOLEAN;   // _Model_Client_TableViewField
+```
+
+**Second variant, same failure, no model property involved:** hand-written SQL inside a model that
+names the new column explicitly. `_Model_Client_TableView::meta()` lists `isGroupable` in its own
+`SELECT`, so the column is required **twice** by two different mechanisms — a grep for the property
+alone under-reports the blast radius.
+
+**Contrast — `FIELD_STORAGE` is the exception**: those columns are excluded from the main SELECT and
+hydrated lazily per row, so they 500 only once a query **returns** rows. See
+[FIELD_STORAGE row hydration](../../_underscore/features/field-storage-row-hydration.md).
+
+**Why a deploy can cause this without anyone changing the framework:** api2 clones `_underscore` at
+**build time from a moving `_<ENVIRONMENT>` branch**, and the CodePipeline source action has its own
+branch setting. A redeploy — including one that *fixes* a stale box — can silently move the
+environment onto a newer framework branch. See
+[ENVIRONMENT decides the `_underscore` branch](../../api2/features/environment-variable-drives-underscore-branch.md).
+
+> **The corollary that surprises people: "unstaling" a box is a schema event.** Correcting a wrong
+> branch pin fast-forwards the environment across every model change since the pin was made. Before
+> re-pointing a tier at its correct branch, run the sweep below — the branch fix and the migrations
+> ship together, or the tier trades a stale-code bug for an environment-wide 500.
+
+## Steps
+
+1. **Get the real exception.** You need the **column name**, the **database** (Core vs Client), and
+   the **model file + line** from the stack. Both 2026-08-26 failures pointed at the same entry
+   point, `V2.php:4516` → `_Model_Client_TableView::meta()`, but at different columns in different
+   databases — so the entry point tells you nothing; the column does.
+
+2. **Prove the code is ahead, not the DB behind** — in `_underscore`:
+
+   ```
+   git log --all -S"<columnName>" -- Model/       # which commit introduced the property
+   git branch -a --contains <sha>                 # WHICH environment branches carry it
+   ```
+
+   If the commit is on `_sandbox-client` but not `_production`, the environments are running
+   **different schema expectations** from the same repo. That is the finding.
+
+3. **Find out whether a migration exists at all** — in `dbchanges2`:
+
+   ```
+   git log --all -S"<columnName>"                 # any branch, ever
+   git ls-tree --name-only origin/_main <folder>/ # is it merged?
+   git merge-base --is-ancestor <sha> origin/_main
+   ```
+
+   Three possible answers, and they need different fixes: **merged** (an executor problem — use the
+   other two drift docs), **written but stranded on an unmerged branch** (merge it), or **never
+   written** (author it).
+
+4. **⚠ Do the full sweep BEFORE fixing anything.** This is the step that turns the incident from
+   whack-a-mole into one piece of work:
+
+   ```
+   git log origin/_production..origin/<env-branch> --oneline -- Model/
+   git show <sha> -- Model/ | grep -E "^\+\s*public \$"
+   ```
+
+   Enumerate **every** new column the framework branch expects, then cross-check each token against
+   `dbchanges2`. Also grep the same commits for hand-written `SELECT`s (the `meta()` variant above),
+   which the `public $` grep misses.
+
+5. **Merge the stranded branch — do not hand-patch column by column.** *(Decision, 2026-08-27.)*
+   The failures arrive **one at a time**: each next column only surfaces once the previous is fixed,
+   so column-by-column patching guarantees a repeat incident per column. And a column applied by
+   hand exists in **no migration file**, so that environment drifts permanently from every other one.
+   Merge the branch, then verify with [verifying a migration ran](./verifying-a-migration-ran.md).
+
+6. **If you must unblock by hand, write down exactly what you ran** (see the section below) and
+   treat the eventual migration as **idempotent by requirement**, not by preference — it will run
+   against at least one database that already has the column.
+
+7. **Remember `Client/` is a fan-out.** A Core column is one `ALTER`; a Client column is one `ALTER`
+   **per tenant database**. Getting this wrong fixes the tenant you are testing and leaves the rest
+   500ing.
+
+## The 2026-08-26 `sandbox-client` incident (worked example)
+
+Two successive 500s, both `V2.php:4516` → `_Model_Client_TableView::meta()`:
+
+| # | Error | DB | Failing path | Mechanism |
+|---|---|---|---|---|
+| 1 | `Unknown column 'maxLength' in 'field list'` (`SELECT … FROM RecordFields WHERE id = 41`) | **Core** | `Model/Client/TableView.php:84` → `_Model::initialize()` → `Query.php:405` | model **property** (`_Model_Core_RecordField::$maxLength`) |
+| 2 | `Unknown column 'TableViewFields.isGroupable' in 'field list'` | **Client** | `Model/Client/TableView.php:188` → `_Query::fetchRow()` → `Query.php:186` | **hand-written SELECT** in `meta()` |
+
+The second only appeared **after** the first was fixed — the canonical reason step 4 exists.
+
+## Current drift inventory — `_underscore` `_sandbox-client` vs. schema (as of 2026-08-27)
+
+Framework commits ahead of `_production` on `_sandbox-client`: `af90e987` (08-13), `a5e79448`
+(08-14), `9f296a71` (08-26), `78ad65a5` (08-26), `64233162` (08-26 — logic only, no new columns).
+
+**Category A — migration WRITTEN but stranded on `dbchanges2` branch `origin/toga25-desk`**, never
+merged to `origin/_main`, so it has run in **no** environment fed by `_main`:
+
+| Object | File (on `origin/toga25-desk`) |
+|---|---|
+| `Core.RecordFields.maxLength` + `validationType` | `Core/2026-08-14c - RecordFieldsValidationMetadata.sql` (commit `84a022c`, jcardinal, 2026-08-17) |
+| `Client.RecordFieldSettings` (new table) | `Client/2026-08-14a - RecordFieldSettingsClientTable.sql` |
+| `Client.UserNavPreferences` (new table) | `Client/2026-08-13a`, `b`, `d`, `e`, `g`, `h` (commit `9523c04`) |
+| `Client.PersonaNavVisibility` (new table) | `Client/2026-08-13c`, `f` (same commit) |
+| Core surface/ACL seeds | `Core/2026-08-14a` SettingsNavSurfaceSeed, `2026-08-14b` SettingsProfileAndAppearance, `2026-08-14d` ProfileSensitiveFieldAclRevoke, `2026-08-14e` SettingsProfileFieldElements, `2026-08-14f` LogoutConfirmSurfaceSeed |
+
+`Core/2026-08-14c` adds `maxLength INT UNSIGNED NULL` + `validationType VARCHAR(32) NULL` and then
+seeds **13 platform defaults by literal `RecordFields` id** (113, 115–118, 1324–1327, 1329, 1863).
+`Client.RecordFieldSettings.recordFieldId` is a deliberate **soft (non-FK) cross-cluster reference**
+to `Core.RecordFields` — correct per the [database-isolation rule](../architecture.md), not an
+oversight.
+
+**Category B — framework shipped with NO migration written ANYWHERE** (no `dbchanges2` branch, not in
+`Client/2026-06-03- BLANK_CLIENT_DATABASE.sql`). Both landed **2026-08-26**, the day of the deploy:
+
+- **`Client.TableViewFields.isGroupable`** — `_underscore` `9f296a71` "Add groupable table view
+  fields". Adds the model property **and** the column to `meta()`'s hand-written SELECT. Verified
+  absent from every `dbchanges2` branch (`git log --all -S"isGroupable"` returns nothing).
+- **`Client.Urgencies.slug`** — `_underscore` `78ad65a5` "Add slug to urgency model". The blank
+  template's `Urgencies` has only `id`/`uuid`/`weight`/`name`. **Has not surfaced yet** because
+  Supply never constructs an Urgency — it is the Desk/Tickets path, so this one is a **pre-detonated
+  mine**, not a live outage.
+
+**Verified NOT a problem** (already on `_main`): the `SurfaceElements` columns
+`showRequiredIndicator`, `isSearchable`, `characterLimit`, `trueMessageId`, `falseMessageId`,
+`inputType`, `validationType` — `Core/2026-07-17a - Migrate - AlterSurfaceElements.sql`.
+
+> **Note on the stranded branch's file names:** `origin/toga25-desk` carries **three**
+> `Core/2026-08-14a` files and **three** `Client/2026-08-14a` files. That violates the
+> one-letter-per-day contract in [architecture.md](../architecture.md) and is the same shape as the
+> unproven duplicate-letter executor lead in
+> [non-prod metadata drift](./nonprod-metadata-drift-repair.md). Fix the letters as part of the merge.
+
+## Hand-applied to `sandbox-client` on 2026-08-27 (NOT in any migration file)
+
+Recorded so the real migrations are written **idempotently** and nobody is surprised by a column that
+exists here and in no `.sql` file.
+
+**Core (single DB)** — lifted verbatim from the stranded `Core/2026-08-14c`; the 13 seed `UPDATE`s
+were **not** run, because `NULL` correctly means "no platform default":
+
+```sql
+ALTER TABLE RecordFields
+  ADD COLUMN maxLength INT UNSIGNED NULL COMMENT 'Platform-default maximum character length for the field',
+  ADD COLUMN validationType VARCHAR(32) NULL COMMENT 'Named front-end validator, e.g. email/phone';
+```
+
+**Client_&lt;Tenant&gt; (FAN-OUT — every tenant DB)** — no migration file exists for this yet; the
+type/nullability/position were chosen to match its siblings `isSortable`/`isFilterable`/
+`isCopyable`/`isEditable` in the blank template:
+
+```sql
+ALTER TABLE TableViewFields
+  ADD COLUMN isGroupable TINYINT UNSIGNED NULL COMMENT 'Whether or not the field is groupable' AFTER isFilterable;
+```
+
+**Still outstanding in `sandbox-client` at session end:** the 13 Core seed `UPDATE`s,
+`Client.RecordFieldSettings`, `Client.Urgencies.slug`, `Client.PersonaNavVisibility`,
+`Client.UserNavPreferences`, and the five Core `2026-08-14` surface/ACL seeds.
+
+## Gotchas / known issues
+
+- **The failures are serialized — one fix reveals the next.** Never treat "the 500 is gone" as
+  "the environment is healthy" until the step-4 sweep comes back empty.
+- **`git grep` for the property under-counts.** A column can be required by a hand-written `SELECT`
+  inside a model with no property declared at all (`TableView::meta()`), and by both at once.
+- **A column that has not failed yet is not safe** — it is waiting for the first request that
+  constructs that model. `Urgencies.slug` is live in `sandbox-client` right now and simply
+  unreachable from Supply.
+- **Fixing a wrong branch pin is a schema change in disguise.** Pair the branch correction with the
+  migration sweep; do not ship it as a lone "deploy fix".
+- **A migration on an unmerged branch has run nowhere** — including production. "It's written" and
+  "it's applied" are different claims, and so are "it's on a branch" and "it's on `_main`".
+- **Core is one `ALTER`; `Client` is one per tenant.** Fixing only the tenant in front of you leaves
+  every other tenant 500ing on the same request.
+
+## Change history
+
+- 2026-08-27 — Created from the `sandbox-client` outage that followed the 2026-08-26 production
+  `_underscore`/`api2`/`_production`-DB deploy. Recorded the **third drift direction** (the code
+  moved forward, not the DB backward): a deploy moved the environment off the `_production`
+  framework onto `_sandbox-client`, which carried ~2 weeks of model changes whose migrations were
+  never merged, producing environment-wide MySQL 1054 → 500/`EO-1`. Documented the two mechanisms
+  (a `public $x = self::FIELD_*` property, which `_Model::initialize()` puts in every SELECT; and a
+  hand-written `SELECT` inside a model such as `TableView::meta()`), the reusable triage
+  (`git log --all -S"<column>"` + `git branch -a --contains` in `_underscore`, the same in
+  `dbchanges2`, then the `git log origin/_production..origin/<env-branch> -- Model/` sweep), and the
+  **decision to merge the stranded branch wholesale rather than hand-patch column by column** —
+  because failures serialize and hand-applied columns drift permanently. Captured the full
+  2026-08-27 inventory (Category A stranded on `origin/toga25-desk`: `RecordFields.maxLength`/
+  `validationType`, `RecordFieldSettings`, `UserNavPreferences`, `PersonaNavVisibility`, five Core
+  surface/ACL seeds; Category B never written anywhere: `TableViewFields.isGroupable`,
+  `Urgencies.slug`) and the two `ALTER`s hand-applied to `sandbox-client`. (apeterson)

package/knowledge/INDEX.md

@@ -21,7 +21,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **_underscore** (_Underscore) _(framework core)_ — 69 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 57 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
-- **dbchanges2** (Database Changes) _(framework core)_ — 12 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
+- **dbchanges2** (Database Changes) _(framework core)_ — 13 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 9 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 4 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 12 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)

package/package.json

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