toga-ai 1.0.1070 → 1.0.1071

package/knowledge/2.0/apps/_underscore/features/calculated-column-filter-options.md

@@ -6,11 +6,13 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-18
-owners: [apeterson]
+updated: 2026-10-17
+owners: [apeterson, jcardinal]
 files:
   - _underscore/Model/Client/TableView.php
   - _underscore/Model/Compass/SalesOrder.php
+  - _underscore/Model/Client/Certification.php
+  - _underscore/Model/Client/UserCertification.php
   - _underscore/Model.php
 related:
   - sales-order-status-filter-surface.md
@@ -34,7 +36,10 @@ Before this, `filterOptions` in table meta was filled in **only** for `TYPE__STA
 column whose options are **live data** (e.g. the list of active Admin users): seeding a surface
 element per user would go stale constantly.
 
-First and only consumer today: the Compass **Assigned Admin** column on the sales-orders table.
+Consumers: Compass **Assigned Admin** (live data, below); `_Model_Client_Certification::_complianceStateFilterOptions()`
+and `_Model_Client_UserCertification::_statusFilterOptions()` (fixed enum list: loop the model's
+state constant, `slug` = `name` = the value; the front end labels it from language data). Use the
+enum shape for any status-like calc column.
 
 ## How it works
 
@@ -56,7 +61,7 @@ an empty dropdown. Same contract as `getStatusFilterOptions()`.
 throws when a `FIELD_SQL` field has no static of the same name — that is why `_assignedAdmin()`
 exists. The seam just adds a `FilterOptions` suffix to the same name-derived rule.
 
-It is a **no-op for every existing column**: nothing else declares a `<field>FilterOptions` static.
+It is a **no-op** for any column whose model declares no `<field>FilterOptions` static.
 
 ### The Compass example
 
@@ -161,10 +166,11 @@ generic version at roughly **4–5** such columns, driven by real examples.
   the same pattern `_assignedManager()` already uses.
 - **Matching a role by its human-readable `name` is fragile** (flagged by `sql-reviewer`): a client
   renaming the `Admin` role silently empties the list. A stable role id would be sturdier.
-- **⚠ Filtering a calculated column lands in HAVING, not WHERE.**
-  `api2/Component/Api/V2/V2.php` `splitWhereExpressionsIntoWhereHaving` routes a where on a
-  calculated field into `HAVING`, so the `_assignedAdmin` correlated subquery is evaluated for every
-  row surviving the WHERE, **before LIMIT** — and again for the pagination count query. On a large
+- **⚠ Filter with the BARE calc name** (`_complianceState:eq:AT_RISK`) — it is inlined into
+  `WHERE`. The table-prefixed form (`Table._x`) goes to `HAVING` and returns 500 / `EO-1`. Mechanism:
+  [V2 REST query contract](../../api2/features/v2-rest-query-contract.md). Either way the expression
+  (here the `_assignedAdmin` correlated subquery) is evaluated **per row, before LIMIT** — and again
+  for the pagination count query. On a large
   Compass `SalesOrders` table this can be slow, and it will not fail loudly (api2's Apache gateway
   timeout is 1800s). This is pre-existing behaviour of filtering **any** calculated column, not new
   here, and it was **not** measured with `EXPLAIN` at production size. The cheaper target would be

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-10-15
+updated: 2026-10-17
 owners: [apeterson, bala, jcardinal]
 files:
   - _underscore/Model/Client/TableView.php
@@ -140,6 +140,7 @@ So the visible failure is a broken SQL query while the actual defect is one miss
 - **Flag columns are NULLable** — guard flag migrations with `COALESCE(col, 0) = 0`, never `col = 0`, or the UPDATE matches 0 rows and looks like caching.
 - **`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`, `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.
+- **⚠ Type `SELECT` only on a JOINED FK column.** `meta()`'s `TYPE__SELECT` branch reads `$tableViewJoins[$tableAlias]->record` (`TableView.php` ~L265-272); a main-table column has no join alias, so it breaks at runtime. For an enum column on the main table, expose a calc label field (e.g. `_status`) with a `<field>FilterOptions` static — see [calculated-column filter options](../../_underscore/features/calculated-column-filter-options.md).
 - **`isGroupable` has no migration** — omit it from new TableView migrations (fails on prod/beta) until the fan-out migration lands. Composite unique keys read as unconstrained in `information_schema.COLUMNS`; use `information_schema.STATISTICS` / `SHOW INDEX`.
 
 ## Related
@@ -151,4 +152,5 @@ So the visible failure is a broken SQL query while the actual defect is one miss
 - [TableView joins](../../_underscore/features/tableview-joins.md)
 
 ## Change history
+- 2026-10-17 — `SELECT` type is safe only on a joined FK column; main-table enum → calc label + FilterOptions. (jcardinal)
 - 2026-09-23 — Recorded that `Core.RecordFields.type` drives display/filter only and never sorting; that `NUMBER` on a text column blanks non-numeric rows (Compass `kit 205-207` bundles) while `BOOLEAN` fixes genuinely blank flag columns; and that the flag columns are NULLable so a `= 0` migration guard matches nothing. (apeterson)

package/knowledge/2.0/apps/api2/features/v2-rest-query-contract.md

@@ -56,6 +56,10 @@ controller.
   (`V2.php` ~L3673–3682). **Prefer bare for ascending:** the query string is parsed *without*
   urldecoding (see Encoding rules), so a client that percent-encodes the `+` as `%2B` sends a
   field literally named `%2Bfield` and the sort is silently dropped. Bare has no such failure mode.
+- **Multi-sort = comma list** (`sort=-dateIssued,uuid`; `parseOptionsSort` ~L10888 explodes on `,`;
+  a blox `sort: [...]` array is sent comma-joined). **Offset paging (`page`) is only stable with a
+  unique last key** — add `uuid` as the tie-breaker, or rows with equal sort values shuffle between
+  pages.
 - **A LIST select is `SELECT SQL_CALC_FOUND_ROWS DISTINCT <table>.<primaryKey>`** (`V2.php:3884`;
   the aggregate-fields path is the one exception). Two consequences: (a) join fan-out collapses to
   one row per record, so **duplicate child rows are invisible in the response** — a duplicate join
@@ -382,9 +386,10 @@ Mechanism, read from `api2/Component/Api/V2/V2.php`:
 1. `buildWhereExpressionsFromOptions` (~L6953) **deliberately does not prepend the default table**
    to a field starting with `_` — its own comment says *"add the default table if not specified and
    is not a calculated field."*
-2. `buildWhereClauseFromWhereExpressions` (~L7069) sees the leading `_` and **inlines the field's own
-   SQL expression** straight into the `WHERE` clause. That is the working path.
-3. `splitWhereExpressionsIntoWhereHaving` (~L8622) routes to `HAVING` **only when the field contains
+2. `validateWhereFieldReference` (~L8704-8741) accepts a bare calc name on the primary table.
+3. `buildWhereClauseFromWhereExpressions` (~L9225-9234) sees the leading `_` and **inlines the field's
+   own SQL expression** straight into the `WHERE` clause. That is the working path.
+4. `splitWhereExpressionsIntoWhereHaving` (~L11286) routes to `HAVING` **only when the field contains
    `._`** — i.e. only the table-**prefixed** form. That form targets a joined-table select alias
    (`PurchaseOrderItems__qtyAvailable`, built ~L3984) which **does not exist for the main table**,
    and ~L4116 also appends the `HAVING` to the `$sqlProhibited` COUNT query, which has no such alias
@@ -411,9 +416,11 @@ production — `toga2-supply/src/api/toga.ts` L906-919 (`_status` OR group) and
 **Zero** occurrences of the table-prefixed form exist in any repo — nobody has ever used it
 successfully.
 
-> ⚠ **Scope this to `where` only.** It says nothing about `group` or `sort` on a calculated field;
-> `group=_status` is separately known to fail. And `where` still never prunes a nested child array
-> (see below).
+> **`sort` on a calculated field also works** (bare name, calc branch of `ORDER BY` above).
+> **`group=_status` fails.** `where` still never prunes a nested child array (see below).
+> A TableView column over a calc field can be `isFilterable` — a code comment saying "calc fields
+> are not filterable" records a choice, not an engine limit. Dropdown options:
+> [calculated-column filter options](../../_underscore/features/calculated-column-filter-options.md).
 
 #### ⚠ `in` instead of an OR-chain of `contains` shortens the SQL - it does NOT make the filter fast
 
@@ -618,6 +625,7 @@ If you need the behaviour, loop uuids client-side. Point 3 is the durable, non-o
   [V2 request logging](request-logging.md).
 
 ## Change history
+- 2026-10-17 — Multi-sort comma list + `uuid` tie-breaker for stable paging; sort on calc works; refreshed where-path line refs. (jcardinal)
 - 2026-10-17 — POST create = 201, PUT/DELETE = 200 (TRUE-82889). (jcardinal)
 - 2026-10-15 — Security: `where` on an unreadable field still filters under default `identifier_acl_mode=log` (hash guessing); dotted FK path in `where` = `EV-8`, use a join alias (TRUE-82836). Folded older history. (jcardinal)
 - 2026-09-24 — `depth`/`calcDepth` ignored inside the base64 `_` blob; field three levels under an inherent child dropped (TRUE-82138). (apeterson)

package/package.json

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